⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
agentx
Drive X/Twitter from the CLI (read, post, DM, lists, communities, Grok, scheduling, analytics). Use when an agent needs to read or act on X/Twitter. Every command prints one JSON envelope.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
agentx is a from-scratch Go library + CLI built for autonomous agents. Every command prints a single predictable JSON object, supports multiple accounts, and keeps auth_token cookies alive by making traffic look like a real browser.
✨ Why cookies last longer here
X flags/expires auth_token cookies aggressively when traffic doesn't look human. agentx signs every authenticated request with:
- a freshly generated
x-client-transaction-id— the exact algorithm x.com's web app runs (golden-tested), - the full browser header set (bearer,
x-csrf-token,x-twitter-*,sec-fetch-*, stable User-Agent), - the complete cookie string,
- optional uTLS Chrome JA3 fingerprint over HTTP/2 (
AGENTX_UTLS=1).
🚀 Quick start
go build -o agentx ./cmd/agentx
# Register an account (cookies from a logged-in browser)
./agentx account add --name main --auth-token <auth_token> --ct0 <ct0>
# Read
./agentx feed -n 20
./agentx user jack
./agentx search --type Latest "golang" -n 20
./agentx analytics <tweet_id>
# Write
./agentx post "hello from agentx 👋"
./agentx reply <id> "nice!" --media pic.jpg
./agentx poll "Tabs or spaces?" --option Tabs --option Spaces
# Grok (AI)
./agentx grok "USD to IDR today?"
./agentx grok image "a majestic dragon" --out dragon.png
Every command prints one JSON envelope:
{ "ok": true, "schema_version": "1", "data": …, "pagination": {"nextCursor": "…"}, "rateLimit": {…} }
{ "ok": false, "schema_version": "1", "error": {"code": "…", "message": "…"} }
Check .ok, read .data, page with .pagination.nextCursor. Exit code is 0 on success, 1 on a handled error. Output is compact single-line JSON by default (token-efficient for agents) — add --pretty for human-readable output.
🧩 Features
| Area | What you get |
|---|---|
| Read | feed (for-you / following), search, user / posts / tweet / thread / article, media tab, bookmarks (+ folders), likes, followers / following, lists + members, communities, mentions, notifications + unread, trends (+ locations), analytics (engagement rate), retweeters / likers |
| Write | post, reply, quote, polls (+ vote), like / retweet / bookmark, follow / mute / block, pin, media upload (+ alt text), auto-threads, scheduled tweets, drafts, profile / avatar / banner / settings, topics, list & community management |
| Grok | text answers with live web search, and image generation (download to file) |
| DM | classic DM send / list / media / download |
| Infra | multi-account, zero-auth FxTwitter fallback, uTLS + HTTP/2, rate-limit surfacing, query-id override for X rotations, watch streaming, media download |
See SKILL.md for the compact, token-efficient command reference and AGENTS.md for the full agent integration guide.
🏛️ Architecture
cmd/agentx CLI — one JSON envelope per command
pkg/agent High-level facade (account selection, client cache, fallbacks)
pkg/xclient Authenticated x.com GraphQL/REST client (+ transaction signing)
pkg/transaction x-client-transaction-id generator [golden-tested]
pkg/account Multi-account credential store (~/.agentx, 0600) [tested]
pkg/backends/fxtwitter Zero-auth single-tweet fallback
pkg/models Backend-agnostic Tweet / UserProfile / Page
pkg/xerrors Stable machine-readable error codes
🔌 Use as a Go library
import "github.com/dezxbt/agentx/pkg/agent"
ag := agent.New(store)
page, err := ag.Feed(ctx, "main", false, 20, "")
⚠️ Notes
- Premium-gated (work on X Premium accounts; the client routes correctly and surfaces a clear error otherwise): long-form
post(>280),edit, bookmark-folder writes. - likers are returned by X only to the tweet's author (retweeters is public).
- grok image needs available image-generation quota.
- X's new XChat is end-to-end encrypted and out of scope — keys are device-only and non-extractable by design. Classic DMs work.
- Writes are real and public — confirm intent before acting.
📄 License
MIT — see LICENSE.
// HOW IT'S BUILT
// FILES
59 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md9.7 KB73260f6970d6upstream ↗
--- name: agentx description: Drive X/Twitter from the CLI (read, post, DM, lists, communities, Grok, scheduling, analytics). Use when an agent needs to read or act on X/Twitter. Every command prints one JSON envelope. --- # agentx — X/Twitter agent control surface `agentx` is a single Go binary. Every command prints **one JSON envelope** to stdout, so parse stdout as JSON and check `.ok`. Build: `go build -o agentx ./cmd/agentx`. ## Envelope (always this shape) ```json {"ok":true,"schema_version":"1","data":<any>,"pagination":{"nextCursor":"…"},"rateLimit":{…}} {"ok":false,"schema_version":"1","error":{"code":"…","message":"…"}} ``` Rules: check `.ok` first. List data → `.data` is an array + `.pagination.nextCursor`. Single object → `.data` is an object. On error read `.error.code` (machine) + `.error.message` (human). Exit code ≠0 on error. Output is **compact single-line JSON by default** (token-efficient); add `--pretty` only when a human reads it. ## Setup (once) ``` agentx account add --name NAME --auth-token <auth_token> --ct0 <ct0> ``` Cookies come from a logged-in browser (`auth_token` + `ct0`). Env fallback: `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`. Store: `$AGENTX_HOME/accounts.json` (default `~/.agentx`, mode 0600). Multi-account: add several, pick with `-a NAME`. `account login --name N --username U` (pass via `$TWITTER_PASSWORD`) does user/pass→cookies but X blocks login from datacenter IPs — prefer cookies. ## Global flags (may precede or follow the subcommand) `-a NAME` account · `-n N` max items · `--cursor C` page cursor · `--pretty` human-readable JSON · `--account`/`--count` long forms. IDs: any `<id>` also accepts a full tweet/list/community URL. Handles: with or without `@`. ## Commands (one line each) READ ``` feed [--latest] [-n N] [--cursor C] home timeline search [--type Top|Latest] <query> search user <handle> | user --id <id> profile me own profile posts <handle> [-n N] a user's tweets media <handle|id> [-n N] user's photos/videos tweet <id> single tweet (zero-auth FxTwitter fallback) thread <id> tweet + replies article <id> [--markdown] long-form X Article analytics <id> metrics + engagement rate likes <handle> | bookmarks | mentions tweet lists followers <handle> | following <handle> user lists retweeters <id> | likers <id> who RT'd/liked (likers: author-only by X) list <id> | list members <id> List tweets / members community posts <id> [--latest] | community info <id> notifications [all|mentions|verified] | unread (alias: notif) trends [woeid] | trends locations trending (Indonesia woeid=23424846) scheduled | drafts your queued/draft tweets settings your privacy settings ``` WRITE (state-changing; reversible ones noted) ``` post <text> [--media f [--alt txt]] [--thread] tweet (>280 → long-form, Premium) reply <id> <text> [--media f] | quote <id> <text> [--media f] poll <text> --option A --option B [--option C|D] [--duration MIN] vote <id> <choice 1-4> like/unlike retweet/unretweet bookmark/unbookmark delete <id> pin/unpin <id> pin tweet to profile bookmark <id> --folder <id> bookmark into folder follow/unfollow mute/unmute block/unblock <handle> edit <id> <text> Premium draft <text> | draft delete <id> schedule <unix|+30m|+2h|+1d> <text> | unschedule <id> profile [--name N] [--bio B] [--location L] [--url U] avatar <img> | banner <img> settings [--protected b] [--dms-from all|following] [--discoverable-email b] [--geo b] topic follow|unfollow <topic_id> list create <name> [--desc T] [--private] | list delete <id> list add|remove <listid> <handle|id> | list subscribe|unsubscribe <id> community join|leave <id> | community create <name> (create is permanent) bookmarks folder create <name> | delete <id> (Premium) dm send <handle> <text> [--media f] ``` GROK (AI) ``` grok <prompt> text answer (live web search built in) grok image <prompt> [--out file] generate image(s), download to file(s) ``` UTILITIES ``` download <id|url> [--out f] [--all] save tweet media / a direct URL watch <mentions|search <q>> [--interval 60s] [--once] NDJSON stream of new tweets account list|remove <n>|default [n]|check [n] oauth inspect <authorize_url> Sign-in-with-X: app name + scope audit (no approval) oauth approve <authorize_url> auto-approve consent → callback URL (see PERMISSION RULE) oauth callback <callback_url> GET the app callback to finish sign-in ``` ## Pagination List commands return `.pagination.nextCursor`. Pass it back via `--cursor` for the next page. `-n N` caps items in the response (note: the cursor still points past the full fetched page, so for exact paging use the cursor, not a tiny `-n`). ## Error codes (`.error.code`) `not_authenticated` bad/expired cookies · `not_found` · `invalid_input` · `rate_limited` (see `.rateLimit`) · `query_id_error` X rotated a GraphQL id → set `AGENTX_QID_<Operation>=<id>` env or update constants · `network_error` · `api_error` x.com rejected (message has detail) · `account_error`. ## Gotchas - **`oauth` PERMISSION RULE (Sign-in-with-X, agents MUST follow)** — `oauth approve` hands the account's permissions to a third-party app. Always run `oauth inspect` first and read `writeScopes` in the envelope: if it is NOT empty (`tweet.write`, `users.write`, `follows.write`, `dm.read/write`, `like.write`, `bookmark.write`) → **stop and get explicit confirmation from the human operator before approving.** Never approve account-control scopes on your own initiative — malicious developers deliberately bundle those permissions so the agent posts/follows/reads DMs on the user's behalf without the user realizing it (acting on the account unprompted = a violation). Scope `*.read` is safe; `offline.access` is reported in `persistentScopes` (refresh tokens, not a write) — OK to proceed. The inspect/approve envelope always carries a `permissionWarning` that flags this automatically. - **TWO KINDS OF Sign-in-with-X SITES — diagnose first, don't retry blindly:** - **TYPE A — callback sets the session directly** (verified: fanszn/IPXExchange, Sovren): `GET redirect_uri` → the site sets its session cookie immediately → sign-in done. `agentx oauth callback` captures those cookies in `data.sessionCookies`; pass the site's state cookies via `--cookie name=value` (repeatable) if needed. Verify via the site's `me`/profile endpoint. **Working example: `examples/fanszn_connect_x.py`** — complete verified chain (start redirect -> approve -> callback with state cookie -> /me). - **TYPE B — session-bound callback** (verified: quest.dogeos.com): the site requires its own primary login first (DogeOS = SIWE wallet → jwt), then `POST .../social-connections/{provider}/initiate` (Bearer) → `sessionId` + `launchUrl` paired server-side. `agentx oauth approve <launchUrl>` still gets the code, but the callback must be executed WITH the site's session/state — otherwise: "Authentication failed" / `invalid_state` / still logged out despite a successful approve. **Fix: a thin site-specific tool** (~100 lines: site login → initiate → `agentx oauth approve` → GET the backend callback → poll async status `pending → connected`). Do not re-initiate while pending — it jams. - **Quick diagnosis:** approve succeeds and X issues a code, but the site stays logged out / errors → it is Type B; find the `initiate`/`confirm` endpoints in the site's JS bundle and stop retrying the callback. - **Working example: `examples/dogeos_connect_x.py`** — a complete, verified Type B connector (SIWE login → initiate → `agentx oauth approve` → GET backend callback → async poll). Copy it and swap the endpoints for your target site; the Gotchas in its docstring (field names, pending semantics, stuck-session cleanup) are the mistakes agents actually make. - **Premium-gated** (work only on X Premium accounts; routing is correct, x.com returns a clear error otherwise): `edit`, note/long-form `post` (>280), `bookmarks folder` writes. - **Account-eligibility**: `community create` needs an eligible account. - **likers**: X returns the liker list only to the tweet's author; empty for others (retweeters is public). - **grok image**: needs image-gen quota (free tier is limited/daily); errors clearly when the quota is spent. - **DM**: only classic (unencrypted) DMs via `dm send/list/download`. X's new **XChat is end-to-end encrypted and out of scope** (keys are device-only, non-extractable). - **Rate limit**: `.rateLimit` carries `x-rate-limit-*`; back off when `remaining` is low. - `AGENTX_UTLS=1` sends a Chrome JA3 TLS fingerprint (HTTP/2) for stealth. - Writes are real and public — confirm intent before posting/following/etc. ## Typical flows - Read a user's latest: `agentx posts elonmusk -n 20` - Reply: `agentx reply <id> "nice"` · Quote with image: `agentx quote <id> "look" --media pic.jpg` - Thread: `agentx post --thread "long text…"` · Poll: `agentx poll "Q?" --option A --option B` - Schedule: `agentx schedule +2h "later"` then `agentx scheduled` - Ask Grok: `agentx grok "USD to IDR today?"` · Image: `agentx grok image "a dragon" --out d.png` - Paginate: `agentx feed -n 40` → take `nextCursor` → `agentx feed --cursor <c>` - Sign-in-with-X: `agentx oauth inspect <url>` (check permissionWarning) → `agentx oauth approve <url>` → GET/`oauth callback` on `data.redirect_uri` → verify the session via the target site's "me" endpointREADME.md4.8 KBa975cb196450upstream ↗
<div align="center"> <img src="assets/logo.png" alt="AgentX" width="420"> <h1>agentx</h1> <p><b>An agent-first X / Twitter client in Go.</b><br> One binary, one JSON envelope per command — so any agent runtime can drive X.</p> <p> <img alt="Go" src="https://img.shields.io/badge/Go-1.22%2B-00ADD8?logo=go&logoColor=white"> <img alt="status" src="https://img.shields.io/badge/status-production-brightgreen"> <img alt="interface" src="https://img.shields.io/badge/interface-JSON%20envelope-blue"> <img alt="accounts" src="https://img.shields.io/badge/multi--account-yes-success"> </p> </div> --- `agentx` is a from-scratch Go library **+** CLI built for **autonomous agents**. Every command prints a single predictable JSON object, supports **multiple accounts**, and keeps **`auth_token` cookies alive** by making traffic look like a real browser. ## ✨ Why cookies last longer here X flags/expires `auth_token` cookies aggressively when traffic doesn't look human. agentx signs **every** authenticated request with: - a freshly generated **`x-client-transaction-id`** — the exact algorithm x.com's web app runs (golden-tested), - the **full browser header set** (bearer, `x-csrf-token`, `x-twitter-*`, `sec-fetch-*`, stable User-Agent), - the complete cookie string, - optional **uTLS** Chrome JA3 fingerprint over **HTTP/2** (`AGENTX_UTLS=1`). ## 🚀 Quick start ```bash go build -o agentx ./cmd/agentx # Register an account (cookies from a logged-in browser) ./agentx account add --name main --auth-token <auth_token> --ct0 <ct0> # Read ./agentx feed -n 20 ./agentx user jack ./agentx search --type Latest "golang" -n 20 ./agentx analytics <tweet_id> # Write ./agentx post "hello from agentx 👋" ./agentx reply <id> "nice!" --media pic.jpg ./agentx poll "Tabs or spaces?" --option Tabs --option Spaces # Grok (AI) ./agentx grok "USD to IDR today?" ./agentx grok image "a majestic dragon" --out dragon.png ``` Every command prints **one JSON envelope**: ```json { "ok": true, "schema_version": "1", "data": …, "pagination": {"nextCursor": "…"}, "rateLimit": {…} } { "ok": false, "schema_version": "1", "error": {"code": "…", "message": "…"} } ``` Check `.ok`, read `.data`, page with `.pagination.nextCursor`. Exit code is `0` on success, `1` on a handled error. Output is **compact single-line JSON by default** (token-efficient for agents) — add `--pretty` for human-readable output. ## 🧩 Features | Area | What you get | | --- | --- | | **Read** | feed (for-you / following), search, user / posts / tweet / thread / **article**, media tab, bookmarks (+ folders), likes, followers / following, **lists** + members, **communities**, mentions, **notifications** + unread, **trends** (+ locations), **analytics** (engagement rate), retweeters / likers | | **Write** | post, reply, quote, **polls** (+ vote), like / retweet / bookmark, follow / mute / block, **pin**, media upload (+ alt text), auto-**threads**, **scheduled** tweets, **drafts**, profile / avatar / banner / **settings**, **topics**, list & community management | | **Grok** | text answers with **live web search**, and **image generation** (download to file) | | **DM** | classic DM send / list / media / download | | **Infra** | multi-account, zero-auth **FxTwitter** fallback, uTLS + HTTP/2, rate-limit surfacing, query-id override for X rotations, `watch` streaming, media `download` | See **[SKILL.md](SKILL.md)** for the compact, token-efficient command reference and **[AGENTS.md](AGENTS.md)** for the full agent integration guide. ## 🏛️ Architecture ``` cmd/agentx CLI — one JSON envelope per command pkg/agent High-level facade (account selection, client cache, fallbacks) pkg/xclient Authenticated x.com GraphQL/REST client (+ transaction signing) pkg/transaction x-client-transaction-id generator [golden-tested] pkg/account Multi-account credential store (~/.agentx, 0600) [tested] pkg/backends/fxtwitter Zero-auth single-tweet fallback pkg/models Backend-agnostic Tweet / UserProfile / Page pkg/xerrors Stable machine-readable error codes ``` ## 🔌 Use as a Go library ```go import "github.com/dezxbt/agentx/pkg/agent" ag := agent.New(store) page, err := ag.Feed(ctx, "main", false, 20, "") ``` ## ⚠️ Notes - **Premium-gated** (work on X Premium accounts; the client routes correctly and surfaces a clear error otherwise): long-form `post` (>280), `edit`, bookmark-folder writes. - **likers** are returned by X only to the tweet's author (retweeters is public). - **grok image** needs available image-generation quota. - X's new **XChat is end-to-end encrypted and out of scope** — keys are device-only and non-extractable by design. Classic DMs work. - Writes are **real and public** — confirm intent before acting. ## 📄 License MIT — see [LICENSE](LICENSE).assets/logo.png846 KB18373324cdb0upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
.gitignore179 B24e319c4c94fupstream ↗
# Binaries /agentx *.exe *.out # Local agentx state (contains session secrets) .agentx/ accounts.json # Go /vendor/ *.test coverage.out # Editor / OS .DS_Store .idea/ .vscode/AGENTS.md2.8 KBd21e5bcd1e95upstream ↗
# agentx — agent integration guide This file tells an autonomous agent how to drive X/Twitter through agentx. ## Contract - Drive everything through the `agentx` binary (or import `pkg/agent` in Go). - Every command prints **one JSON object** to stdout and nothing else: - success: `{"ok":true,"schema_version":"1","data":...,"pagination":{"nextCursor":"..."}}` - failure: `{"ok":false,"schema_version":"1","error":{"code":"...","message":"..."}}` - process exit code is `0` on success, `1` on a handled error. - Parse the envelope; never scrape human text. `data` shape depends on the command (a tweet array for timelines, a user object for `user`, etc.). ## Decision guide | Goal | Command | | --- | --- | | Read my home feed | `agentx feed -n N` (add `--latest` for chronological) | | Search | `agentx search --type Top\|Latest "<query>" -n N` | | Look up a profile | `agentx user <handle>` | | Read someone's tweets | `agentx posts <handle> -n N` | | Read one tweet (no login needed) | `agentx tweet <id\|url>` | | Read a tweet + replies | `agentx thread <id\|url>` | | Publish | `agentx post "<text>"` | | Reply / quote | `agentx reply <id> "<text>"` / `agentx quote <id> "<text>"` | | Engage | `agentx like\|unlike\|retweet\|unretweet\|bookmark\|delete <id>` | `<id|url>` accepts a numeric id or any `https://x.com/<user>/status/<id>` URL. ## Multi-account - Register once: `agentx account add --name <n> --auth-token <t> --ct0 <c> [--cookie "<full cookie>"]`. - Choose per call with `-a <name>` or set `AGENTX_ACCOUNT`. - The first account becomes the default; change it with `agentx account default <name>`. - Inspect with `agentx account list` (returns names + which is default). Prefer supplying the **full browser cookie string** via `--cookie`: it keeps the session looking like a real browser, which makes the cookies last much longer. ## Pagination Timeline-style results include `pagination.nextCursor`. To page, re-issue the same command with `--cursor <nextCursor>`. Stop when `nextCursor` is empty or stops changing. ## Handling errors Switch on `error.code`: - `not_authenticated` → cookies missing/expired; ask the user to re-add the account, then retry. - `rate_limited` → back off (seconds→minutes) and retry; the client already retries transient 429s a few times. - `query_id_error` / repeated `not_found` on a known-good id → x.com rotated a GraphQL query id; report it so the operator can refresh ids. - `invalid_input` → fix arguments; do not retry blindly. - `network_error` → transient; retry with backoff. ## Notes for safe automation - Writes (`post`, `like`, ...) change real account state. Confirm intent before bulk actions. - Keep one stable User-Agent per account (set `--user-agent` at add time) — do not rotate it between requests.cmd/agentx/main.go56 KB5c135918cc21upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
cmd/agentx/oauth.go6.8 KB87c21d4f0942upstream ↗
package main import ( "context" "os" "strings" "github.com/dezxbt/agentx/pkg/xclient" "github.com/dezxbt/agentx/pkg/xerrors" ) // writeScopes are OAuth scopes that let an app ACT as the account (post, // follow, DM, read DMs). Approving them hands over account control. var writeScopes = map[string]string{ "tweet.write": "post/retweet/reply as the account", "users.write": "follow/unfollow/mute/block as the account", "follows.write": "follow/unfollow as the account", "dm.read": "read the account's direct messages", "dm.write": "send DMs as the account", "bookmark.write": "modify bookmarks", "like.write": "like/unlike as the account", } // persistentScopes keep access alive but cannot act — flagged separately // from write scopes so read-only apps don't get a false account-control warn. var persistentScopes = map[string]string{ "offline.access": "stay connected until revoked (refresh tokens)", } // auditScopes splits the requested scopes into safe (read-only), // account-control (write/DM), and persistent buckets. func auditScopes(scopes []xclient.OAuthScopeInfo) (safe []string, dangerous map[string]string, persistent []string) { dangerous = map[string]string{} for _, s := range scopes { if reason, ok := writeScopes[s.Name]; ok { dangerous[s.Name] = reason continue } if _, ok := persistentScopes[s.Name]; ok { persistent = append(persistent, s.Name) continue } safe = append(safe, s.Name) } return safe, dangerous, persistent } // cmdOAuth handles `agentx oauth` — Sign-in-with-X via the account's session // cookies, no browser needed: // // agentx oauth inspect <authorize_url> show app name + scopes (no approval) // agentx oauth approve <authorize_url> auto-approve, print the callback URL // agentx oauth callback <callback_url> GET the app callback (finishes sign-in) // // PERMISSION RULE: approve is a delegated account action. Before approving an // app that requests ANY write scope, the operator (human) must explicitly // confirm it — never approve account-control permissions on your own // initiative. Read-only apps (users.read/tweet.read/follows.read) are safe to // approve autonomously. func cmdOAuth(ctx context.Context, args []string) { if len(args) == 0 { fail(xerrors.New(xerrors.InvalidInput, "usage: agentx oauth inspect|approve|callback <url>")) } sub, rest := args[0], args[1:] if len(rest) == 0 { fail(xerrors.New(xerrors.InvalidInput, "usage: agentx oauth %s <authorize_url>", sub)) } targetURL := rest[0] var ( rest3 []string authToken string ct0 string ) switch sub { case "callback": // GET the app callback WITH a cookie jar: any Set-Cookie the app // issues on login (its own session) is captured and returned, so the // agent finishes sign-in without a browser. The jar only ever holds // the third-party app's cookies — it never sees X credentials. siteCookies, _ := flagValues(rest, "--cookie") res2, cbErr := runCallback(ctx, targetURL, siteCookies) if cbErr != nil { fail(cbErr) } emit(res2, nil) return case "inspect", "approve": // fall through to the shared path below default: fail(xerrors.New(xerrors.InvalidInput, "unknown oauth subcommand %q (inspect|approve|callback)", sub)) } // approve/inspect need the cookies of an account. --auth-token/--ct0 // overrides are supported for one-shot use without a stored account. var rest2 []string authToken, rest2 = flagValue(rest, "--auth-token") ct0, rest3 = flagValue(rest2, "--ct0") if authToken == "" { authToken = os.Getenv("TWITTER_AUTH_TOKEN") } if ct0 == "" { ct0 = os.Getenv("TWITTER_CT0") } var ( res any err error ) if authToken != "" && ct0 != "" { cl, cErr := oneShotClient(authToken, ct0) if cErr != nil { fail(cErr) } if sub == "inspect" { res, err = cl.OAuthAuthorize(ctx, targetURL) } else { res, err = cl.OAuthApprove(ctx, targetURL, false) } } else { if sub == "inspect" { res, err = newAgent().OAuthAuthorize(ctx, mustAccount(rest3), targetURL) } else { res, err = newAgent().OAuthApprove(ctx, mustAccount(rest3), targetURL, false) } } if err != nil { fail(err) } if consent, ok := res.(*xclient.OAuthConsent); ok { // inspect: report the app + scope audit, explicitly not approved safe, dangerous, persistent := auditScopes(consent.Scopes) emit(map[string]any{ "app": consent.AppName, "description": consent.AppDesc, "safeScopes": safe, "writeScopes": dangerous, "persistentScopes": persistent, "permissionWarning": permissionWarning(dangerous), "approved": false, }, nil) return } // approve: attach the same audit to the result so the caller sees what it // just consented to (and agents can log it). if appr, ok := res.(*xclient.OAuthApproval); ok { if appr.Consent != nil { safe, dangerous, persistent := auditScopes(appr.Consent.Scopes) emit(map[string]any{ "redirect_uri": appr.RedirectURI, "app": appr.AppName, "safeScopes": safe, "writeScopes": dangerous, "persistentScopes": persistent, "permissionWarning": permissionWarning(dangerous), "scopes": appr.Scopes, }, nil) return } } emit(res, nil) } // permissionWarning renders the account-control warning shown on every // inspect/approve that includes write scopes. func permissionWarning(dangerous map[string]string) string { if len(dangerous) == 0 { return "read-only scopes — safe to approve" } names := make([]string, 0, len(dangerous)) for k := range dangerous { names = append(names, k) } return "ACCOUNT-CONTROL SCOPES REQUESTED (" + strings.Join(names, ", ") + "): this app can act as the account. " + "Never approve without the human operator's explicit confirmation — malicious apps bundle these to post, follow, or read DMs on the user's behalf." } // truncateStr caps a string for envelope output. func truncateStr(s string, n int) string { if len(s) <= n { return s } return s[:n] } // fetchCallback performs a plain GET against the app's callback URL. The // response body is surfaced for debugging; the app sets its own session // cookies in the browser normally, so this only proves the code was accepted. func fetchCallback(ctx context.Context, rawURL string) (string, string, error) { if !strings.HasPrefix(rawURL, "http") { return "", "", xerrors.New(xerrors.InvalidInput, "callback url must be absolute") } req, err := newPlainGet(ctx, rawURL) if err != nil { return "", "", err } resp, err := plainHTTP.Do(req) if err != nil { return "", "", xerrors.New(xerrors.NetworkError, "callback fetch failed: %v", err) } defer resp.Body.Close() buf := make([]byte, 0, 4096) tmp := make([]byte, 2048) for { n, rerr := resp.Body.Read(tmp) buf = append(buf, tmp[:n]...) if rerr != nil || len(buf) > 64*1024 { break } } return rawURL, string(buf), nil }cmd/agentx/oauth_callback.go2.6 KB226f3bae7e7bupstream ↗
package main import ( "context" "net/http" "net/http/cookiejar" "net/url" "strings" "time" "github.com/dezxbt/agentx/pkg/xerrors" ) // callbackJarHTTP performs the app-callback GET with a cookie jar so any // Set-Cookie the app issues on login (its session) is captured and reported // back to the caller. This is how sign-in-with-X finishes: the callback // response carries the site's own session cookies. type callbackResult struct { FinalURL string `json:"finalUrl"` Status int `json:"status"` SetCookie map[string]string `json:"sessionCookies"` Body string `json:"response"` } func runCallback(ctx context.Context, rawURL string, cookies []string) (*callbackResult, error) { if !strings.HasPrefix(rawURL, "http") { return nil, xerrors.New(xerrors.InvalidInput, "callback url must be absolute") } jar, jErr := cookiejar.New(nil) if jErr != nil { return nil, xerrors.Wrap(xerrors.NetworkError, jErr, "cookie jar") } // site-state cookies (e.g. fanszn_oauth={state,verifier}) must ride along // or the app rejects the callback with state_mismatch. baseURL, _ := url.Parse(rawURL) for _, kv := range cookies { k, v, ok := strings.Cut(kv, "=") if !ok || k == "" { return nil, xerrors.New(xerrors.InvalidInput, "bad --cookie %q (want name=value)", kv) } jar.SetCookies(baseURL, []*http.Cookie{{Name: k, Value: v}}) } base, _ := url.Parse(rawURL) client := &http.Client{Timeout: 45 * time.Second, Jar: jar} req, rErr := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil) if rErr != nil { return nil, xerrors.Wrap(xerrors.InvalidInput, rErr, "bad callback url") } req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36") req.Header.Set("Accept", "*/*") resp, dErr := client.Do(req) if dErr != nil { return nil, xerrors.Wrap(xerrors.NetworkError, dErr, "callback fetch failed") } defer resp.Body.Close() buf := make([]byte, 0, 4096) tmp := make([]byte, 2048) for { n, rErr := resp.Body.Read(tmp) buf = append(buf, tmp[:n]...) if rErr != nil || len(buf) > 256*1024 { break } } out := &callbackResult{FinalURL: resp.Request.URL.String(), Status: resp.StatusCode, SetCookie: map[string]string{}, Body: string(buf)} // report cookies that now live in the jar for the app domain(s) for _, cURL := range []*url.URL{resp.Request.URL, base} { if cURL == nil { continue } for _, ck := range jar.Cookies(cURL) { if _, seen := out.SetCookie[ck.Name]; !seen { out.SetCookie[ck.Name] = ck.Value } } } return out, nil }cmd/agentx/oauth_helper.go1.1 KB7110c97a5662upstream ↗
package main import ( "context" "net/http" "time" "github.com/dezxbt/agentx/pkg/account" "github.com/dezxbt/agentx/pkg/xclient" "github.com/dezxbt/agentx/pkg/xerrors" ) // oneShotClient builds a throwaway xclient from inline cookies (for // `oauth approve --auth-token T --ct0 C` without a stored account). func oneShotClient(authToken, ct0 string) (*xclient.Client, error) { acc := &account.Account{Name: "__oneshot__", AuthToken: authToken, CT0: ct0} return xclient.New(acc) } // plainHTTP is used only for `oauth callback` — a GET to the *third-party* // app's callback URL. It never carries X credentials. var plainHTTP = &http.Client{Timeout: 45 * time.Second} func newPlainGet(ctx context.Context, rawURL string) (*http.Request, error) { req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil) if err != nil { return nil, xerrors.Wrap(xerrors.InvalidInput, err, "bad callback url") } req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36") req.Header.Set("Accept", "*/*") return req, nil }examples/dogeos_connect_x.py7.0 KB539cd06965b8upstream ↗
#!/usr/bin/env python3 """Reference implementation of a "Type B" Sign-in-with-X site connector. Type B = the target site has its own primary login (here: SIWE wallet), and the X OAuth callback is bound to a server-side session created by an `initiate` endpoint. `agentx oauth approve` alone gets the X code but cannot finish the login — you need this thin glue tool. Generic flow (works for any Type B site, endpoints differ per site): 1. PRIMARY LOGIN get a bearer token from the site's own auth flow 2. INITIATE POST <site>/.../initiate -> {sessionId, launchUrl} 3. CONSENT `agentx oauth approve <launchUrl>` -> callback URL w/ code 4. CALLBACK GET the callback (the site's backend validates it) 5. POLL GET the site's connection status until connected The concrete endpoints below are from quest.dogeos.com (verified live) — swap them for your target site's equivalents (find them in its JS bundle). Requires: `agentx` >= v0.2.1 on PATH with an X account stored (`agentx account add`), plus `requests` and `eth_account`. Usage: export PRIVKEY=0x... # wallet private key python3 dogeos_connect_x.py status --wallet 0x... python3 dogeos_connect_x.py connect --wallet 0x... python3 dogeos_connect_x.py connect --token <bearer jwt> # skip step 1 """ import argparse import json import os import subprocess import sys import time import requests API = "https://quest-api.dogeos.com" # DogeOS backend; replace per site UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " "Chrome/126.0 Safari/537.36") PROVIDER = "twitter" # site enum: twitter (NOT "x"), discord, telegram, ... S = requests.Session() S.headers.update({"User-Agent": UA, "Origin": "https://quest.dogeos.com", "Referer": "https://quest.dogeos.com/", "Content-Type": "application/json"}) def api(method, path, token=None, **kw): """Authenticated JSON request against the site backend.""" headers = {"Authorization": f"Bearer {token}"} if token else {} r = S.request(method, API + path, headers=headers, timeout=45, **kw) try: return r.status_code, r.json() except Exception: return r.status_code, {"raw": r.text[:400]} def site_login(address, private_key): """PRIMARY LOGIN (step 1) — SIWE wallet challenge/sign/session. Gotchas found by reversing the site's JS bundle: - the signed field is `signedMessage`, NOT `signature` (422 otherwise) - the token is `data.jwt` """ from eth_account import Account from eth_account.messages import encode_defunct st, body = api("POST", "/v2/auth/wallet/challenges", json={"wallet": address}) if st != 200: raise SystemExit(f"challenge failed: {st} {body}") d = body["data"] sig = Account.sign_message(encode_defunct(text=d["message"]), private_key).signature.hex() if not sig.startswith("0x"): sig = "0x" + sig st, body = api("POST", "/v2/auth/wallet/sessions", json={"wallet": address, "nonce": d["nonce"], "signedMessage": sig}) if st != 200: raise SystemExit(f"session failed: {st} {body}") tok = body["data"].get("jwt") if not tok: raise SystemExit(f"no jwt in response: {json.dumps(body)[:300]}") return tok def connection_status(token): """Current state of the X connection on the site.""" st, body = api("GET", "/v2/me/social-connections", token=token) conns = body.get("data", {}).get("connections", []) for c in conns: if c.get("provider") == PROVIDER: return c return {} def connect(token, wait_secs=90): """Full Type B chain (steps 2-5).""" # A stuck `pending` session blocks a new initiate (launchUrl comes back # null until it expires) — clear it first if present. if connection_status(token).get("status") == "pending": api("DELETE", f"/v2/me/social-connections/{PROVIDER}", token=token) # 2) INITIATE — the server pairs sessionId with the X authorize state st, body = api("POST", f"/v2/me/social-connections/{PROVIDER}/initiate", token=token, json={"returnUrl": "https://quest.dogeos.com/oauth-callback"}) if st != 200: raise SystemExit(f"initiate failed: {st} {json.dumps(body)[:300]}") launch = body.get("data", {}).get("launchUrl") if not launch: raise SystemExit(f"launchUrl null (stuck pending session?): {json.dumps(body)[:400]}") # 3) CONSENT — agentx approves X's consent screen, no browser needed r = subprocess.run(["agentx", "oauth", "approve", launch], capture_output=True, text=True, timeout=120) env = json.loads(r.stdout) if not env.get("ok"): raise SystemExit(f"agentx approve failed: {env.get('error')}") callback = env["data"]["redirect_uri"].replace("&", "&") print(f"[approve] scopes={env['data'].get('scopes')}") # 4) CALLBACK — the SITE'S BACKEND validates the state/code pair. Plain # GET is enough; do NOT call the site's /confirm endpoint (DogeOS # returns 400 confirm_not_supported — the backend does it itself). out = subprocess.run(["curl", "-s", "-L", "-A", UA, "-o", "/dev/null", "-w", "%{http_code} %{url_effective}", callback], capture_output=True, text=True, timeout=60) print(f"[callback] {out.stdout}") # 5) POLL — the backend resolves asynchronously (30-60s is normal). # "pending" here is SUCCESS-IN-PROGRESS, not a failure: just keep # polling, do not re-initiate. deadline = time.time() + wait_secs while time.time() < deadline: time.sleep(5) cur = connection_status(token) s = cur.get("status") if s == "connected": acct = (cur.get("account") or {}).get("username") print(f"[verify] {PROVIDER}: connected -> @{acct}") return cur if s != "pending": print(f"[verify] status={s} lastError={cur.get('lastError')}") return cur print("[verify] timeout — still pending") return connection_status(token) def main(): p = argparse.ArgumentParser(description=__doc__.splitlines()[0]) p.add_argument("cmd", choices=["status", "connect"]) p.add_argument("--wallet", help="wallet address (0x..)") p.add_argument("--key", help="wallet private key hex, or env PRIVKEY") p.add_argument("--token", help="existing bearer token (skip primary login)") p.add_argument("--wait", type=int, default=90) a = p.parse_args() tok = a.token if not tok: key = a.key or os.environ.get("PRIVKEY") if not (a.wallet and key): raise SystemExit("need --wallet + --key (or env PRIVKEY), or --token") tok = site_login(a.wallet, key) print("[auth] site session OK") if a.cmd == "status": print(json.dumps(connection_status(tok), indent=2)[:1200]) return if connect(tok, a.wait).get("status") != "connected": sys.exit(1) if __name__ == "__main__": main()examples/fanszn_connect_x.py5.1 KBd15a704e4beaupstream ↗
#!/usr/bin/env python3 """Reference implementation of a "Type A" Sign-in-with-X site connector. Type A = the site's OAuth callback sets its own session cookies directly on GET. `agentx oauth approve` + `agentx oauth callback` finish the whole login — no site login, no glue tool, just cookies from X. Generic flow (endpoints differ per site; find them via the site's JS bundle): 1. START GET <site>/api/.../auth/x/start -> 302 Location: x.com/i/oauth2/authorize?... (the authorize_url) AND a state cookie the callback must echo back (e.g. fanszn_oauth={state,verifier}) 2. CONSENT `agentx oauth approve <authorize_url>` -> data.redirect_uri = the site's callback with the code 3. CALLBACK `agentx oauth callback <redirect_uri> --cookie <state jar>` -> data.sessionCookies = the site's session 4. VERIFY GET the site's /me endpoint with the session cookie Requires: `agentx` >= v0.2.1 on PATH with an X account stored (`agentx account add`), plus `requests`. Usage: python3 fanszn_connect_x.py # full chain, verify /me python3 fanszn_connect_x.py --account NAME # pick a stored X account """ import argparse import json import subprocess import sys from http.cookiejar import CookieJar import requests SITE = "https://fanszn.ipx.exchange" # verified Type A site START = "/api/fanszn/auth/x/start?returnTo=/fanszn/connect&ref=FAN-KQ4Z" STATE_COOKIE = "fanszn_oauth" # site's state/verifier jar ME_PATH = "/api/fanszn/me" # session verification endpoint UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " "Chrome/126.0 Safari/537.36") def start(authorize_out): """START (step 1) — capture the authorize_url AND the state cookie. Gotcha: the state cookie returned by the start endpoint MUST ride along on the callback, or the site rejects it with `state_mismatch`. The jar value is already URL-encoded by the server — pass it through verbatim. """ s = requests.Session() s.headers.update({"User-Agent": UA, "Cookie": "fanszn_ref=FAN-KQ4Z"}) r = s.get(SITE + START, allow_redirects=False, timeout=45) if r.status_code not in (301, 302, 303, 307): raise SystemExit(f"start did not redirect: {r.status_code} {r.text[:200]}") authorize_out["authorize_url"] = r.headers["Location"] return s.cookies def state_cookie_value(jar): for c in jar: if c.name == STATE_COOKIE: return c.value raise SystemExit(f"no {STATE_COOKIE} cookie from start endpoint") def agentx_approve(authorize_url, account=None): """CONSENT (step 2) — approve X's consent screen via agentx.""" cmd = ["agentx", "oauth", "approve", authorize_url] if account: cmd += ["-a", account] r = subprocess.run(cmd, capture_output=True, text=True, timeout=120) env = json.loads(r.stdout) if not env.get("ok"): raise SystemExit(f"agentx approve failed: {env.get('error')}") return env["data"]["redirect_uri"].replace("&", "&") def agentx_callback(callback_url, state_cookie, account=None): """CALLBACK (step 3) — GET the site callback WITH the state cookie. agentx runs the GET in a cookie jar and returns every Set-Cookie the site issues on login in `data.sessionCookies`. `--cookie` is repeatable. """ cmd = ["agentx", "oauth", "callback", callback_url, "--cookie", f"{STATE_COOKIE}={state_cookie}"] if account: cmd += ["-a", account] r = subprocess.run(cmd, capture_output=True, text=True, timeout=120) env = json.loads(r.stdout) if not env.get("ok"): raise SystemExit(f"agentx callback failed: {env.get('error')}") return env["data"] def main(): p = argparse.ArgumentParser(description=__doc__.splitlines()[0]) p.add_argument("--account", help="stored agentx account (-a NAME)") authorize_out = {} p.set_defaults(func=lambda a: None) a = p.parse_args() # 1) START — authorize_url + state cookie in one redirect jar = start(authorize_out) state = state_cookie_value(jar) print(f"[start] authorize_url={authorize_out['authorize_url'][:80]}...") # 2) CONSENT callback = agentx_approve(authorize_out["authorize_url"], a.account) print("[approve] got redirect_uri") # 3) CALLBACK — capture the site session data = agentx_callback(callback, state, a.account) cookies = data["sessionCookies"] print(f"[callback] status={data['status']} final={data['finalUrl']}") print(f"[callback] sessionCookies: {sorted(cookies.keys())}") session = next((v for k, v in cookies.items() if "session" in k.lower()), None) if not session: raise SystemExit(f"no session cookie captured: {list(cookies.keys())}") # 4) VERIFY — prove the login actually landed me = requests.get(SITE + ME_PATH, headers={"User-Agent": UA, "Cookie": f"{next(k for k in cookies if 'session' in k.lower())}={session}"}, timeout=45).json() print(f"[verify] me: {json.dumps(me)[:300]}") if __name__ == "__main__": main()go.mod452 Be84beb3f9a4dupstream ↗
module github.com/dezxbt/agentx go 1.25.0 require ( github.com/PuerkitoBio/goquery v1.12.0 github.com/refraction-networking/utls v1.8.2 golang.org/x/net v0.52.0 ) require ( github.com/andybalholm/brotli v1.0.6 // indirect github.com/andybalholm/cascadia v1.3.3 // indirect github.com/klauspost/compress v1.17.4 // indirect golang.org/x/crypto v0.49.0 // indirect golang.org/x/sys v0.42.0 // indirect golang.org/x/text v0.35.0 // indirect )go.sum7.2 KB649182d014f7upstream ↗
github.com/PuerkitoBio/goquery v1.12.0 h1:pAcL4g3WRXekcB9AU/y1mbKez2dbY2AajVhtkO8RIBo= github.com/PuerkitoBio/goquery v1.12.0/go.mod h1:802ej+gV2y7bbIhOIoPY5sT183ZW0YFofScC4q/hIpQ= github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sxfOI= github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= github.com/andybalholm/cascadia v1.3.3 h1:AG2YHrzJIm4BZ19iwJ/DAua6Btl3IwJX+VI4kktS1LM= github.com/andybalholm/cascadia v1.3.3/go.mod h1:xNd9bqTn98Ln4DwST8/nG+H0yuB8Hmgu1YHNnWw0GeA= github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4= github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM= github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo= github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM= github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc= golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU= golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8= golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk= golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4= golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA= golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c= golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c= golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg= golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk= golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44= golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM= golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4= golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0= golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo= golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo= golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU= golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk= golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY= golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ= golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8= golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58= golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=LICENSE1.0 KBd53d60568e73upstream ↗
MIT License Copyright (c) 2026 DezXBT Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.pkg/account/account.go2.0 KB2b8dd9aff183upstream ↗
// Package account manages multiple X/Twitter credential sets so a single agentx // install can drive many accounts. Credentials are cookie-based (auth_token + // ct0, plus an optional full cookie string for a richer browser fingerprint). package account import ( "fmt" "strings" "time" ) // Account holds one X session's credentials and metadata. type Account struct { Name string `json:"name"` // AuthToken is the x.com `auth_token` cookie (the actual session secret). AuthToken string `json:"authToken"` // CT0 is the `ct0` cookie, also sent as the x-csrf-token header. CT0 string `json:"ct0"` // CookieString is the optional full Cookie header. When present it is sent // verbatim, preserving every cookie the browser had (best for longevity). CookieString string `json:"cookieString,omitempty"` // UserAgent pins the browser UA for this account. Keeping it stable across // requests is important for not tripping anti-automation heuristics. UserAgent string `json:"userAgent,omitempty"` // Proxy is an optional per-account proxy URL (http/https/socks5). Proxy string `json:"proxy,omitempty"` ScreenName string `json:"screenName,omitempty"` AddedAt time.Time `json:"addedAt"` LastUsed time.Time `json:"lastUsed,omitempty"` } // Validate checks that the minimum required credentials are present. func (a *Account) Validate() error { if strings.TrimSpace(a.Name) == "" { return fmt.Errorf("account name is required") } if strings.TrimSpace(a.AuthToken) == "" { return fmt.Errorf("account %q: auth_token is required", a.Name) } if strings.TrimSpace(a.CT0) == "" { return fmt.Errorf("account %q: ct0 is required", a.Name) } return nil } // Cookie returns the Cookie header value to send for this account. It uses the // full cookie string when available, otherwise synthesises a minimal one. func (a *Account) Cookie() string { if s := strings.TrimSpace(a.CookieString); s != "" { return s } return fmt.Sprintf("auth_token=%s; ct0=%s", a.AuthToken, a.CT0) }pkg/account/store.go4.4 KB53d0579223e6upstream ↗
package account import ( "encoding/json" "fmt" "os" "path/filepath" "sort" "sync" "time" "github.com/dezxbt/agentx/pkg/xerrors" ) // Store is a thread-safe, file-backed collection of accounts. type Store struct { path string mu sync.RWMutex accounts map[string]*Account def string // default account name } type persisted struct { Default string `json:"default"` Accounts []*Account `json:"accounts"` } // DefaultPath returns the standard store location (~/.agentx/accounts.json), // overridable via the AGENTX_HOME environment variable. func DefaultPath() string { if h := os.Getenv("AGENTX_HOME"); h != "" { return filepath.Join(h, "accounts.json") } home, err := os.UserHomeDir() if err != nil { return "accounts.json" } return filepath.Join(home, ".agentx", "accounts.json") } // Open loads the store at path, creating an empty one if it does not exist. func Open(path string) (*Store, error) { if path == "" { path = DefaultPath() } s := &Store{path: path, accounts: map[string]*Account{}} data, err := os.ReadFile(path) if os.IsNotExist(err) { return s, nil } if err != nil { return nil, fmt.Errorf("account: read store: %w", err) } var p persisted if err := json.Unmarshal(data, &p); err != nil { return nil, fmt.Errorf("account: parse store: %w", err) } for _, a := range p.Accounts { s.accounts[a.Name] = a } s.def = p.Default return s, nil } func (s *Store) saveLocked() error { if err := os.MkdirAll(filepath.Dir(s.path), 0o700); err != nil { return fmt.Errorf("account: create store dir: %w", err) } p := persisted{Default: s.def} for _, a := range s.accounts { p.Accounts = append(p.Accounts, a) } sort.Slice(p.Accounts, func(i, j int) bool { return p.Accounts[i].Name < p.Accounts[j].Name }) data, err := json.MarshalIndent(p, "", " ") if err != nil { return err } // 0600: the file contains session secrets. if err := os.WriteFile(s.path, data, 0o600); err != nil { return fmt.Errorf("account: write store: %w", err) } return nil } // Add inserts or replaces an account and persists the store. The first account // added becomes the default. func (s *Store) Add(a *Account) error { if err := a.Validate(); err != nil { return err } s.mu.Lock() defer s.mu.Unlock() if a.AddedAt.IsZero() { a.AddedAt = time.Now() } s.accounts[a.Name] = a if s.def == "" { s.def = a.Name } return s.saveLocked() } // Remove deletes an account by name. func (s *Store) Remove(name string) error { s.mu.Lock() defer s.mu.Unlock() if _, ok := s.accounts[name]; !ok { return fmt.Errorf("account %q not found", name) } delete(s.accounts, name) if s.def == name { s.def = "" for n := range s.accounts { s.def = n break } } return s.saveLocked() } // Get returns a copy of the named account. func (s *Store) Get(name string) (*Account, error) { s.mu.RLock() defer s.mu.RUnlock() a, ok := s.accounts[name] if !ok { // account_error, not the api_error default: the documented code list maps // "the named account is not usable" to account_error, and agents switch on it. return nil, xerrors.New(xerrors.AccountError, "account %q not found", name) } cp := *a return &cp, nil } // Resolve returns the named account, or the default when name is empty. func (s *Store) Resolve(name string) (*Account, error) { if name != "" { return s.Get(name) } s.mu.RLock() def := s.def s.mu.RUnlock() if def == "" { return nil, fmt.Errorf("no accounts configured; add one first") } return s.Get(def) } // List returns all accounts sorted by name. func (s *Store) List() []*Account { s.mu.RLock() defer s.mu.RUnlock() out := make([]*Account, 0, len(s.accounts)) for _, a := range s.accounts { cp := *a out = append(out, &cp) } sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) return out } // Default returns the default account name (may be empty). func (s *Store) Default() string { s.mu.RLock() defer s.mu.RUnlock() return s.def } // SetDefault changes the default account. func (s *Store) SetDefault(name string) error { s.mu.Lock() defer s.mu.Unlock() if _, ok := s.accounts[name]; !ok { return fmt.Errorf("account %q not found", name) } s.def = name return s.saveLocked() } // Touch records that an account was just used. func (s *Store) Touch(name, screenName string) { s.mu.Lock() defer s.mu.Unlock() if a, ok := s.accounts[name]; ok { a.LastUsed = time.Now() if screenName != "" { a.ScreenName = screenName } _ = s.saveLocked() } }pkg/account/store_test.go1.8 KB715cb87dcfabupstream ↗
package account import ( "path/filepath" "testing" ) func TestStoreAddListResolvePersist(t *testing.T) { path := filepath.Join(t.TempDir(), "accounts.json") s, err := Open(path) if err != nil { t.Fatalf("open: %v", err) } if err := s.Add(&Account{Name: "a", AuthToken: "tok-a", CT0: "ct-a"}); err != nil { t.Fatalf("add a: %v", err) } if err := s.Add(&Account{Name: "b", AuthToken: "tok-b", CT0: "ct-b"}); err != nil { t.Fatalf("add b: %v", err) } if s.Default() != "a" { t.Errorf("default = %q, want a (first added)", s.Default()) } if got := len(s.List()); got != 2 { t.Errorf("list len = %d, want 2", got) } // default resolution def, err := s.Resolve("") if err != nil || def.Name != "a" { t.Errorf("resolve default = %v, %v", def, err) } // reload from disk preserves state s2, err := Open(path) if err != nil { t.Fatalf("reopen: %v", err) } if s2.Default() != "a" || len(s2.List()) != 2 { t.Errorf("reload mismatch: default=%q len=%d", s2.Default(), len(s2.List())) } b, err := s2.Get("b") if err != nil || b.AuthToken != "tok-b" { t.Errorf("get b = %v, %v", b, err) } // remove default reassigns if err := s2.Remove("a"); err != nil { t.Fatalf("remove: %v", err) } if s2.Default() != "b" { t.Errorf("after remove default = %q, want b", s2.Default()) } } func TestAccountValidateAndCookie(t *testing.T) { a := &Account{Name: "x", AuthToken: "tok", CT0: "csrf"} if err := a.Validate(); err != nil { t.Fatalf("validate: %v", err) } if got := a.Cookie(); got != "auth_token=tok; ct0=csrf" { t.Errorf("cookie = %q", got) } a.CookieString = "auth_token=tok; ct0=csrf; guest_id=v1" if a.Cookie() != a.CookieString { t.Error("expected full cookie string to be used verbatim") } bad := &Account{Name: "x"} if err := bad.Validate(); err == nil { t.Error("expected validation error for missing tokens") } }pkg/agent/agent.go30 KBf5203ac5a21fupstream ↗
// Package agent is the high-level, agent-friendly facade over agentx. It hides // account resolution, per-account client caching, the shared transaction // provider, and zero-auth fallbacks behind a small, stable method set. This is // the layer most agents should use. package agent import ( "context" "net/http" "os" "strings" "sync" "time" "github.com/dezxbt/agentx/pkg/account" "github.com/dezxbt/agentx/pkg/backends/fxtwitter" "github.com/dezxbt/agentx/pkg/models" "github.com/dezxbt/agentx/pkg/transaction" "github.com/dezxbt/agentx/pkg/xclient" ) // Agent coordinates accounts, clients and fallbacks. It is safe for concurrent // use. type Agent struct { store *account.Store tx *transaction.Provider fx *fxtwitter.Client mu sync.Mutex clients map[string]*xclient.Client } // New builds an Agent over an account store. The transaction provider (which // derives the x-client-transaction-id keys from x.com) is shared across all // accounts because those keys are account-independent. func New(store *account.Store) *Agent { hc := &http.Client{Timeout: 30 * time.Second} return &Agent{ store: store, tx: transaction.NewProvider(transaction.WithHTTPClient(hc)), fx: fxtwitter.New(hc), clients: map[string]*xclient.Client{}, } } // Store exposes the underlying account store for management commands. func (a *Agent) Store() *account.Store { return a.store } // client resolves an account (empty => default) and returns a cached client. func (a *Agent) client(name string) (*xclient.Client, error) { acc, err := a.store.Resolve(name) if err != nil { return nil, err } a.mu.Lock() defer a.mu.Unlock() if cl, ok := a.clients[acc.Name]; ok { return cl, nil } opts := []xclient.Option{xclient.WithTransactionProvider(a.tx)} if os.Getenv("AGENTX_UTLS") != "" { // opt-in Chrome-like TLS fingerprint for authenticated traffic opts = append(opts, xclient.WithUTLS()) } cl, err := xclient.New(acc, opts...) if err != nil { return nil, err } a.clients[acc.Name] = cl return cl, nil } // hasAccounts reports whether any account is configured. func (a *Agent) hasAccounts() bool { return a.store.Default() != "" } // limitPage trims a page to at most count tweets when a positive count is // requested. x.com ignores small count hints on timelines and returns a full // page, so this enforces the caller's requested size. Note: the page cursor // still points past the full fetched page, so paginating with a small count // skips the untrimmed remainder. func limitPage(p *models.Page, count int) *models.Page { if p != nil && count > 0 && len(p.Tweets) > count { p.Tweets = p.Tweets[:count] } return p } // Feed returns the home timeline for an account. func (a *Agent) Feed(ctx context.Context, accountName string, latest bool, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.HomeTimeline(ctx, latest, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // Search runs an advanced search for an account. func (a *Agent) Search(ctx context.Context, accountName, query, product string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.Search(ctx, query, product, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // User resolves a profile. Requires an account. func (a *Agent) User(ctx context.Context, accountName, screenName string) (*models.UserProfile, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.UserByScreenName(ctx, screenName) } // UserPosts fetches a user's tweets. Requires an account. func (a *Agent) UserPosts(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.UserPosts(ctx, screenName, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // Thread fetches a tweet plus its conversation. Requires an account. func (a *Agent) Thread(ctx context.Context, accountName, tweetID string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.TweetDetail(ctx, tweetID) } // Bookmarks returns the authenticated user's bookmarks. func (a *Agent) Bookmarks(ctx context.Context, accountName string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.Bookmarks(ctx, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // Likes returns the tweets a user has liked. func (a *Agent) Likes(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.LikesByScreenName(ctx, screenName, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // ListTweets returns the latest tweets of a List. func (a *Agent) ListTweets(ctx context.Context, accountName, listID string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.ListTweets(ctx, listID, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // CommunityTweets returns the timeline of posts in a Community. func (a *Agent) CommunityTweets(ctx context.Context, accountName, communityID string, count int, cursor string, latest bool) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.CommunityTweets(ctx, communityID, count, cursor, latest) if err != nil { return nil, err } return limitPage(p, count), nil } // CommunityInfo returns metadata about a Community. func (a *Agent) CommunityInfo(ctx context.Context, accountName, communityID string) (map[string]any, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.CommunityInfo(ctx, communityID) } // JoinCommunity / LeaveCommunity move the authenticated account in/out of a Community. func (a *Agent) JoinCommunity(ctx context.Context, accountName, communityID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.JoinCommunity(ctx, communityID) }) } func (a *Agent) LeaveCommunity(ctx context.Context, accountName, communityID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.LeaveCommunity(ctx, communityID) }) } // CreateCommunity creates a new Community (permanent, not undoable here). func (a *Agent) CreateCommunity(ctx context.Context, accountName, name string) (map[string]any, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.CreateCommunity(ctx, name) } // ListMembers returns the members of a List. func (a *Agent) ListMembers(ctx context.Context, accountName, listID string, count int, cursor string) (*models.UserPage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.ListMembers(ctx, listID, count, cursor) if err != nil { return nil, err } return limitUserPage(p, count), nil } // CreateList creates a List owned by the authenticated account. func (a *Agent) CreateList(ctx context.Context, accountName, name, description string, private bool) (map[string]any, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.CreateList(ctx, name, description, private) } // DeleteList deletes a List owned by the authenticated account. func (a *Agent) DeleteList(ctx context.Context, accountName, listID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteList(ctx, listID) }) } // SubscribeList / UnsubscribeList follow or unfollow a List owned by anyone. func (a *Agent) SubscribeList(ctx context.Context, accountName, listID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.SubscribeList(ctx, listID) }) } func (a *Agent) UnsubscribeList(ctx context.Context, accountName, listID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnsubscribeList(ctx, listID) }) } // UserByID resolves a profile by numeric user id. func (a *Agent) UserByID(ctx context.Context, accountName, userID string) (*models.UserProfile, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.UserByRestId(ctx, userID) } // UserMedia returns a user's media tab. The target may be a @handle or numeric id. func (a *Agent) UserMedia(ctx context.Context, accountName, target string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } userID, err := a.resolveUserID(ctx, cl, target) if err != nil { return nil, err } p, err := cl.UserMedia(ctx, userID, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // Trends returns trending topics for a WOEID location (empty = worldwide). func (a *Agent) Trends(ctx context.Context, accountName, woeid string) ([]xclient.Trend, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Trends(ctx, woeid) } // PinTweet / UnpinTweet manage the account's pinned profile tweet. func (a *Agent) PinTweet(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.PinTweet(ctx, tweetID) }) } func (a *Agent) UnpinTweet(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnpinTweet(ctx, tweetID) }) } // AddListMember / RemoveListMember edit a List's membership. The member may be a // @handle or numeric id. func (a *Agent) AddListMember(ctx context.Context, accountName, listID, member string) error { return a.listMember(ctx, accountName, listID, member, true) } func (a *Agent) RemoveListMember(ctx context.Context, accountName, listID, member string) error { return a.listMember(ctx, accountName, listID, member, false) } func (a *Agent) listMember(ctx context.Context, accountName, listID, member string, add bool) error { cl, err := a.client(accountName) if err != nil { return err } userID, err := a.resolveUserID(ctx, cl, member) if err != nil { return err } if add { return cl.AddListMember(ctx, listID, userID) } return cl.RemoveListMember(ctx, listID, userID) } // isNumericID reports whether s is a non-empty all-digit string (a user id). func isNumericID(s string) bool { if s == "" { return false } for _, r := range s { if r < '0' || r > '9' { return false } } return true } // resolveUserID returns target unchanged if it is already a numeric id, // otherwise resolves the @handle via UserByScreenName. func (a *Agent) resolveUserID(ctx context.Context, cl *xclient.Client, target string) (string, error) { target = strings.TrimPrefix(target, "@") if isNumericID(target) { return target, nil } u, err := cl.UserByScreenName(ctx, target) if err != nil { return "", err } return u.ID, nil } // BookmarkFolders lists the account's bookmark folders. func (a *Agent) BookmarkFolders(ctx context.Context, accountName string) ([]xclient.BookmarkFolder, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.BookmarkFolders(ctx) } // BookmarkFolderTweets returns the tweets in a bookmark folder. func (a *Agent) BookmarkFolderTweets(ctx context.Context, accountName, folderID string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.BookmarkFolderTweets(ctx, folderID, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // CreateBookmarkFolder creates a bookmark folder. func (a *Agent) CreateBookmarkFolder(ctx context.Context, accountName, name string) (*xclient.BookmarkFolder, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.CreateBookmarkFolder(ctx, name) } // DeleteBookmarkFolder deletes a bookmark folder. func (a *Agent) DeleteBookmarkFolder(ctx context.Context, accountName, folderID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteBookmarkFolder(ctx, folderID) }) } // BookmarkToFolder bookmarks a tweet into a specific folder. func (a *Agent) BookmarkToFolder(ctx context.Context, accountName, tweetID, folderID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.BookmarkToFolder(ctx, tweetID, folderID) }) } // Retweeters / Favoriters return the accounts that retweeted or liked a tweet. func (a *Agent) Retweeters(ctx context.Context, accountName, tweetID string, count int, cursor string) (*models.UserPage, error) { return a.engagers(ctx, accountName, tweetID, count, cursor, true) } func (a *Agent) Favoriters(ctx context.Context, accountName, tweetID string, count int, cursor string) (*models.UserPage, error) { return a.engagers(ctx, accountName, tweetID, count, cursor, false) } func (a *Agent) engagers(ctx context.Context, accountName, tweetID string, count int, cursor string, rt bool) (*models.UserPage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } var p *models.UserPage if rt { p, err = cl.Retweeters(ctx, tweetID, count, cursor) } else { p, err = cl.Favoriters(ctx, tweetID, count, cursor) } if err != nil { return nil, err } return limitUserPage(p, count), nil } // ScheduleTweet queues a tweet for executeAt (unix seconds). func (a *Agent) ScheduleTweet(ctx context.Context, accountName, text string, executeAt int64) (string, error) { cl, err := a.client(accountName) if err != nil { return "", err } return cl.ScheduleTweet(ctx, text, executeAt, nil) } // ScheduledTweets lists pending scheduled tweets. func (a *Agent) ScheduledTweets(ctx context.Context, accountName string) ([]xclient.ScheduledTweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.ScheduledTweets(ctx) } // DeleteScheduledTweet removes a pending scheduled tweet. func (a *Agent) DeleteScheduledTweet(ctx context.Context, accountName, id string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteScheduledTweet(ctx, id) }) } // Badges returns the account's unread counts. func (a *Agent) Badges(ctx context.Context, accountName string) (*xclient.BadgeCount, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Badges(ctx) } // Notifications returns the authenticated account's notifications timeline. func (a *Agent) Notifications(ctx context.Context, accountName, tab string, count int, cursor string) (*xclient.NotificationPage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.Notifications(ctx, tab, count, cursor) if err != nil { return nil, err } if count > 0 && len(p.Items) > count { p.Items = p.Items[:count] } return p, nil } // Followers / Following return a user's social graph. func (a *Agent) Followers(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.UserPage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.FollowersByScreenName(ctx, screenName, count, cursor) if err != nil { return nil, err } return limitUserPage(p, count), nil } func (a *Agent) Following(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.UserPage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.FollowingByScreenName(ctx, screenName, count, cursor) if err != nil { return nil, err } return limitUserPage(p, count), nil } func limitUserPage(p *models.UserPage, count int) *models.UserPage { if p != nil && count > 0 && len(p.Users) > count { p.Users = p.Users[:count] } return p } // Tweet fetches a single tweet. With an account it uses the authenticated API; // without one it transparently falls back to the zero-auth FxTwitter backend. func (a *Agent) Tweet(ctx context.Context, accountName, tweetID string) (*models.Tweet, error) { // An explicitly requested account that cannot be resolved must fail loudly: // falling through to the unauthenticated FxTwitter path would otherwise look // like success for an account name that does not exist. var accountErr error if a.hasAccounts() || accountName != "" { cl, err := a.client(accountName) if err != nil { accountErr = err } else if page, derr := cl.TweetDetail(ctx, tweetID); derr == nil { for i := range page.Tweets { if page.Tweets[i].ID == tweetID { return &page.Tweets[i], nil } } if len(page.Tweets) > 0 { return &page.Tweets[0], nil } } } if accountName != "" && accountErr != nil { return nil, accountErr } return a.fx.GetTweet(ctx, tweetID) } // TweetAnalytics is a tweet's engagement metrics plus a derived engagement rate. type TweetAnalytics struct { ID string `json:"id"` Text string `json:"text,omitempty"` Author string `json:"author,omitempty"` Metrics models.Metrics `json:"metrics"` Engagements int `json:"engagements"` // likes+RTs+replies+quotes+bookmarks EngagementRate float64 `json:"engagementRatePct"` // engagements / views, percent } // Analytics fetches a tweet and reports its metrics with a computed engagement // rate. X does not expose its private analytics (link clicks, profile visits) // through a public API op, so this surfaces the full set of available counts // (views/impressions, likes, retweets, replies, quotes, bookmarks). func (a *Agent) Analytics(ctx context.Context, accountName, tweetID string) (*TweetAnalytics, error) { t, err := a.Tweet(ctx, accountName, tweetID) if err != nil { return nil, err } m := t.Metrics eng := m.Likes + m.Retweets + m.Replies + m.Quotes + m.Bookmarks rate := 0.0 if m.Views > 0 { rate = float64(eng) / float64(m.Views) * 100 } return &TweetAnalytics{ ID: t.ID, Text: t.Text, Author: t.Author.ScreenName, Metrics: m, Engagements: eng, EngagementRate: rate, }, nil } // Article fetches a single tweet by id and populates the X Article fields when // the tweet is a long-form article. The article endpoint is authenticated, so // an account is required (no zero-auth fallback). markdown renders the article // body as markdown instead of plain text. func (a *Agent) Article(ctx context.Context, accountName, tweetID string, markdown bool) (*models.Tweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Article(ctx, tweetID, markdown) } // Mentions returns tweets mentioning the authenticated user. cursor is the v1.1 // max_id for older pages. func (a *Agent) Mentions(ctx context.Context, accountName string, count int, cursor string) (*models.Page, error) { cl, err := a.client(accountName) if err != nil { return nil, err } p, err := cl.Mentions(ctx, count, cursor) if err != nil { return nil, err } return limitPage(p, count), nil } // SendDM sends a direct message to a @handle (resolved to a user id first). func (a *Agent) SendDM(ctx context.Context, accountName, screenName, text string) error { cl, err := a.client(accountName) if err != nil { return err } u, err := cl.UserByScreenName(ctx, screenName) if err != nil { return err } return cl.SendDM(ctx, u.ID, text) } // SendDMMedia sends a media DM to a @handle. func (a *Agent) SendDMMedia(ctx context.Context, accountName, screenName, text string, data []byte, mimeType string) error { cl, err := a.client(accountName) if err != nil { return err } u, err := cl.UserByScreenName(ctx, screenName) if err != nil { return err } return cl.SendDMMedia(ctx, u.ID, text, data, mimeType) } // SetAltText sets accessibility alt text on an uploaded media id. func (a *Agent) SetAltText(ctx context.Context, accountName, mediaID, text string) error { cl, err := a.client(accountName) if err != nil { return err } return cl.SetAltText(ctx, mediaID, text) } // DirectMessages lists recent DMs for an account. func (a *Agent) DirectMessages(ctx context.Context, accountName string, count int) ([]xclient.DirectMessage, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.DirectMessages(ctx, count) } // DownloadMedia fetches the bytes of an auth-gated media URL for an account. func (a *Agent) DownloadMedia(ctx context.Context, accountName, url string) ([]byte, string, error) { cl, err := a.client(accountName) if err != nil { return nil, "", err } return cl.DownloadMedia(ctx, url) } // PostThread posts a sequence of tweets as a self-reply chain (the first is a // root tweet, each subsequent one replies to the previous) and returns them. func (a *Agent) PostThread(ctx context.Context, accountName string, chunks []string, firstMedia []string) ([]models.Tweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } var out []models.Tweet replyTo := "" for i, c := range chunks { opts := xclient.PostOptions{ReplyToID: replyTo} if i == 0 { opts.MediaIDs = firstMedia } t, err := cl.Post(ctx, c, opts) if err != nil { return out, err } out = append(out, *t) replyTo = t.ID } if len(out) > 0 { a.store.Touch(cl.Account().Name, out[0].Author.ScreenName) } return out, nil } // Check verifies an account's cookies are still valid by resolving its own // profile, returning that profile on success. func (a *Agent) Check(ctx context.Context, accountName string) (*models.UserProfile, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Me(ctx) } // Me returns the authenticated user's own profile for an account. func (a *Agent) Me(ctx context.Context, accountName string) (*models.UserProfile, error) { cl, err := a.client(accountName) if err != nil { return nil, err } u, err := cl.Me(ctx) if err == nil && u != nil { a.store.Touch(cl.Account().Name, u.ScreenName) } return u, err } // Follow / Unfollow / Mute / Unmute / Block / Unblock act on a @handle. func (a *Agent) Follow(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Follow(ctx, screenName) }) } func (a *Agent) Unfollow(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unfollow(ctx, screenName) }) } func (a *Agent) Mute(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Mute(ctx, screenName) }) } func (a *Agent) Unmute(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unmute(ctx, screenName) }) } func (a *Agent) Block(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Block(ctx, screenName) }) } func (a *Agent) Unblock(ctx context.Context, accountName, screenName string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unblock(ctx, screenName) }) } // Post creates a tweet/reply/quote for an account. func (a *Agent) Post(ctx context.Context, accountName, text string, opts xclient.PostOptions) (*models.Tweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } t, err := cl.Post(ctx, text, opts) if err == nil { a.store.Touch(cl.Account().Name, t.Author.ScreenName) } return t, err } // EditTweet replaces the text of an existing tweet (Premium-gated). func (a *Agent) EditTweet(ctx context.Context, accountName, tweetID, text string) (*models.Tweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Post(ctx, text, xclient.PostOptions{EditTweetID: tweetID}) } // CreateDraft saves a draft tweet and returns its id. func (a *Agent) CreateDraft(ctx context.Context, accountName, text string) (string, error) { cl, err := a.client(accountName) if err != nil { return "", err } return cl.CreateDraft(ctx, text, nil) } // Drafts lists the account's saved drafts. func (a *Agent) Drafts(ctx context.Context, accountName string) ([]xclient.Draft, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Drafts(ctx) } // DeleteDraft removes a draft tweet. func (a *Agent) DeleteDraft(ctx context.Context, accountName, draftID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteDraft(ctx, draftID) }) } // GrokAsk sends a prompt to Grok and returns the reply. func (a *Agent) GrokAsk(ctx context.Context, accountName, prompt string) (string, error) { cl, err := a.client(accountName) if err != nil { return "", err } return cl.GrokAsk(ctx, prompt) } // GrokImage asks Grok to generate an image and returns the attachment URLs. func (a *Agent) GrokImage(ctx context.Context, accountName, prompt string) ([]string, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.GrokImage(ctx, prompt) } // VotePoll votes choice (1..N) on the poll attached to a tweet. func (a *Agent) VotePoll(ctx context.Context, accountName, tweetID string, choice int) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.VotePoll(ctx, tweetID, choice) }) } // UpdateProfile edits the account's profile (name, bio, location, url). func (a *Agent) UpdateProfile(ctx context.Context, accountName string, f xclient.ProfileFields) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateProfile(ctx, f) }) } // Settings returns the account's privacy/DM/discovery settings. func (a *Agent) Settings(ctx context.Context, accountName string) (map[string]any, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.Settings(ctx) } // UpdateSettings changes account settings (only the provided keys). func (a *Agent) UpdateSettings(ctx context.Context, accountName string, fields map[string]string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateSettings(ctx, fields) }) } // UpdateAvatar / UpdateBanner set the profile picture / banner from image bytes. func (a *Agent) UpdateAvatar(ctx context.Context, accountName string, image []byte) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateAvatar(ctx, image) }) } func (a *Agent) UpdateBanner(ctx context.Context, accountName string, image []byte) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateBanner(ctx, image) }) } // FollowTopic / UnfollowTopic manage followed Topics. func (a *Agent) FollowTopic(ctx context.Context, accountName, topicID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.FollowTopic(ctx, topicID) }) } func (a *Agent) UnfollowTopic(ctx context.Context, accountName, topicID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnfollowTopic(ctx, topicID) }) } // TrendLocations lists places (WOEIDs) with trending data. func (a *Agent) TrendLocations(ctx context.Context, accountName string) ([]xclient.TrendLocation, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.TrendLocations(ctx) } // PostPoll posts a tweet with an attached poll (2–4 choices, duration minutes). func (a *Agent) PostPoll(ctx context.Context, accountName, text string, choices []string, durationMinutes int) (*models.Tweet, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.PostPoll(ctx, text, choices, durationMinutes) } // UploadMedia uploads media bytes for an account and returns the media id to // attach to a subsequent Post. func (a *Agent) UploadMedia(ctx context.Context, accountName string, data []byte, mediaType string) (string, error) { cl, err := a.client(accountName) if err != nil { return "", err } return cl.UploadMedia(ctx, data, mediaType, "") } // Like favourites a tweet for an account. func (a *Agent) Like(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Like(ctx, tweetID) }) } // Unlike removes a favourite for an account. func (a *Agent) Unlike(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unlike(ctx, tweetID) }) } // Retweet reposts for an account. func (a *Agent) Retweet(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Retweet(ctx, tweetID) }) } // Unretweet undoes a repost for an account. func (a *Agent) Unretweet(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unretweet(ctx, tweetID) }) } // Delete removes a tweet for an account. func (a *Agent) Delete(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Delete(ctx, tweetID) }) } // Bookmark saves a tweet for an account. func (a *Agent) Bookmark(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Bookmark(ctx, tweetID) }) } // Unbookmark removes a saved tweet for an account. func (a *Agent) Unbookmark(ctx context.Context, accountName, tweetID string) error { return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unbookmark(ctx, tweetID) }) } func (a *Agent) act(ctx context.Context, accountName string, fn func(*xclient.Client) error) error { cl, err := a.client(accountName) if err != nil { return err } return fn(cl) }pkg/agent/oauth.go1018 B965ab1f2f975upstream ↗
package agent import ( "context" "github.com/dezxbt/agentx/pkg/xclient" ) // OAuthAuthorize inspects an OAuth2 authorization request on behalf of an // account: returns the app metadata and requested scopes without approving. func (a *Agent) OAuthAuthorize(ctx context.Context, accountName, authorizeURL string) (*xclient.OAuthConsent, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.OAuthAuthorize(ctx, authorizeURL) } // OAuthApprove auto-approves an OAuth2 consent request (Sign-in-with-X) using // the account's session cookies — the programmatic equivalent of clicking // "Authorize app" on the consent screen. With inspect=true nothing is // approved; the caller only gets the app name and scope list. func (a *Agent) OAuthApprove(ctx context.Context, accountName, authorizeURL string, inspect bool) (*xclient.OAuthApproval, error) { cl, err := a.client(accountName) if err != nil { return nil, err } return cl.OAuthApprove(ctx, authorizeURL, inspect) }pkg/backends/fxtwitter/fxtwitter.go4.0 KBc57d35725756upstream ↗
// Package fxtwitter is a zero-auth fallback backend for fetching single tweets // via the public FxTwitter API (https://github.com/FxEmbed/FxEmbed). It needs // no cookies, so agents can read a tweet even with no account configured. package fxtwitter import ( "context" "encoding/json" "fmt" "io" "net/http" "time" "github.com/dezxbt/agentx/pkg/models" "github.com/dezxbt/agentx/pkg/xerrors" ) const apiBase = "https://api.fxtwitter.com" // Client fetches tweets from FxTwitter. type Client struct { httpClient *http.Client userAgent string } // New builds a Client. A nil http client uses a sane default. func New(hc *http.Client) *Client { if hc == nil { hc = &http.Client{Timeout: 30 * time.Second} } return &Client{httpClient: hc, userAgent: "Mozilla/5.0 (compatible; agentx/1.0)"} } type apiResponse struct { Code int `json:"code"` Message string `json:"message"` Tweet *apiTweet `json:"tweet"` } type apiTweet struct { URL string `json:"url"` ID string `json:"id"` Text string `json:"text"` Lang string `json:"lang"` CreatedAt string `json:"created_at"` Likes int `json:"likes"` Retweets int `json:"retweets"` Replies int `json:"replies"` Views int `json:"views"` Bookmarks int `json:"bookmarks"` Author apiAuthor `json:"author"` Media *apiMedia `json:"media"` Quote *apiTweet `json:"quote"` // FxTwitter exposes reply linkage as a screen name plus the parent id. ReplyingTo string `json:"replying_to"` ReplyingToStatus string `json:"replying_to_status"` } type apiAuthor struct { ID string `json:"id"` Name string `json:"name"` ScreenName string `json:"screen_name"` AvatarURL string `json:"avatar_url"` } type apiMedia struct { All []apiMediaItem `json:"all"` } type apiMediaItem struct { Type string `json:"type"` URL string `json:"url"` Width int `json:"width"` Height int `json:"height"` } // GetTweet fetches a single tweet by id. func (c *Client) GetTweet(ctx context.Context, id string) (*models.Tweet, error) { url := fmt.Sprintf("%s/i/status/%s", apiBase, id) req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { return nil, xerrors.Wrap(xerrors.InvalidInput, err, "build request") } req.Header.Set("User-Agent", c.userAgent) resp, err := c.httpClient.Do(req) if err != nil { return nil, xerrors.Wrap(xerrors.NetworkError, err, "fxtwitter request failed") } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) if resp.StatusCode == http.StatusNotFound { return nil, xerrors.New(xerrors.NotFound, "tweet %s not found", id) } if resp.StatusCode != http.StatusOK { return nil, xerrors.New(xerrors.APIError, "fxtwitter returned %d", resp.StatusCode) } var out apiResponse if err := json.Unmarshal(body, &out); err != nil { return nil, xerrors.Wrap(xerrors.APIError, err, "decode fxtwitter response") } if out.Tweet == nil { return nil, xerrors.New(xerrors.NotFound, "tweet %s not available", id) } return convert(out.Tweet), nil } func convert(t *apiTweet) *models.Tweet { if t == nil { return nil } out := &models.Tweet{ ID: t.ID, Text: t.Text, CreatedAt: t.CreatedAt, Lang: t.Lang, Author: models.Author{ ID: t.Author.ID, Name: t.Author.Name, ScreenName: t.Author.ScreenName, ProfileImageURL: t.Author.AvatarURL, }, Metrics: models.Metrics{ Likes: t.Likes, Retweets: t.Retweets, Replies: t.Replies, Views: t.Views, Bookmarks: t.Bookmarks, }, Source: "fxtwitter", } out.InReplyToID = t.ReplyingToStatus out.InReplyToUser = t.ReplyingTo out.ConversationID = t.ReplyingToStatus out.IsReply = t.ReplyingToStatus != "" || t.ReplyingTo != "" if t.Media != nil { for _, m := range t.Media.All { out.Media = append(out.Media, models.Media{ Type: m.Type, URL: m.URL, Width: m.Width, Height: m.Height, }) } } out.QuotedTweet = convert(t.Quote) return out }pkg/models/models.go3.9 KB7579b660d672upstream ↗
// Package models holds the shared, backend-agnostic data types returned by the // agentx client. Every fetch backend (authenticated GraphQL, FxTwitter, ...) // normalises its raw payload into these types so agents see one stable schema. package models // Author is the user that produced a tweet. type Author struct { ID string `json:"id"` Name string `json:"name"` ScreenName string `json:"screenName"` ProfileImageURL string `json:"profileImageUrl,omitempty"` Verified bool `json:"verified,omitempty"` } // Metrics holds public engagement counters. type Metrics struct { Likes int `json:"likes"` Retweets int `json:"retweets"` Replies int `json:"replies"` Quotes int `json:"quotes"` Views int `json:"views"` Bookmarks int `json:"bookmarks"` } // Media is an attached photo, video or animated gif. type Media struct { Type string `json:"type"` URL string `json:"url"` Width int `json:"width,omitempty"` Height int `json:"height,omitempty"` } // PollChoice is one option of a poll plus the vote count x.com reports for it. type PollChoice struct { Label string `json:"label"` Count int `json:"count"` } // Poll is the poll attached to a tweet. x.com delivers a poll as a card, not as // a typed object, so these fields are decoded from the card's binding_values. type Poll struct { Choices []PollChoice `json:"choices"` EndsAt string `json:"endsAt,omitempty"` DurationMinutes int `json:"durationMinutes,omitempty"` Final bool `json:"final,omitempty"` // counts_are_final Selected int `json:"selected,omitempty"` } // Tweet is the normalised representation of a single tweet. type Tweet struct { ID string `json:"id"` Text string `json:"text"` Author Author `json:"author"` Metrics Metrics `json:"metrics"` CreatedAt string `json:"createdAt,omitempty"` Media []Media `json:"media,omitempty"` URLs []string `json:"urls,omitempty"` IsRetweet bool `json:"isRetweet,omitempty"` RetweetedBy string `json:"retweetedBy,omitempty"` IsReply bool `json:"isReply,omitempty"` InReplyToID string `json:"inReplyToId,omitempty"` InReplyToUser string `json:"inReplyToUser,omitempty"` // ConversationID is the root tweet of the thread. Equal to ID for a tweet // that starts a thread, so it is what tells a client which thread a reply // landed in without fetching the parent. ConversationID string `json:"conversationId,omitempty"` Lang string `json:"lang,omitempty"` QuotedTweet *Tweet `json:"quotedTweet,omitempty"` Poll *Poll `json:"poll,omitempty"` ArticleTitle string `json:"articleTitle,omitempty"` ArticleText string `json:"articleText,omitempty"` Source string `json:"source,omitempty"` // which backend produced this tweet } // UserProfile is the normalised representation of a user. type UserProfile struct { ID string `json:"id"` Name string `json:"name"` ScreenName string `json:"screenName"` Bio string `json:"bio,omitempty"` Location string `json:"location,omitempty"` URL string `json:"url,omitempty"` FollowersCount int `json:"followersCount"` FollowingCount int `json:"followingCount"` TweetsCount int `json:"tweetsCount"` Verified bool `json:"verified,omitempty"` ProfileImageURL string `json:"profileImageUrl,omitempty"` CreatedAt string `json:"createdAt,omitempty"` } // Page is a paginated slice of tweets with an optional continuation cursor. type Page struct { Tweets []Tweet `json:"tweets"` NextCursor string `json:"nextCursor,omitempty"` } // UserPage is a paginated slice of users (followers/following) with an optional // continuation cursor. type UserPage struct { Users []UserProfile `json:"users"` NextCursor string `json:"nextCursor,omitempty"` }pkg/transaction/animate.go605 B17ba7874e1bbupstream ↗
package transaction import "math" // interpolate ports interpolate.interpolate (numeric branch only; the boolean // branch in the Python source is never reached for this library's inputs). func interpolate(from, to []float64, f float64) []float64 { out := make([]float64, len(from)) for i := range from { out[i] = from[i]*(1-f) + to[i]*f } return out } // convertRotationToMatrix ports rotation.convert_rotation_to_matrix. func convertRotationToMatrix(rotation float64) []float64 { rad := rotation * math.Pi / 180 return []float64{math.Cos(rad), -math.Sin(rad), math.Sin(rad), math.Cos(rad)} }pkg/transaction/constants.go1.9 KB72e5bc2facc7upstream ↗
// Package transaction is a faithful Go port of iSarabjitDhiman/XClientTransaction. // // It generates the `x-client-transaction-id` header that x.com expects on its // internal GraphQL / REST endpoints. Sending a correct transaction id on every // authenticated request makes traffic look like a real browser session, which // is the single biggest factor in keeping `auth_token` cookies alive instead of // getting them flagged and expired early. package transaction import "regexp" const ( // additionalRandomNumber is the static byte appended to the payload before // the XOR masking step. Ported from constants.ADDITIONAL_RANDOM_NUMBER. additionalRandomNumber = 3 // defaultKeyword is the obfuscation keyword folded into the SHA-256 input. // Ported from constants.DEFAULT_KEYWORD. defaultKeyword = "obfiowerehiring" // onDemandFileURLTemplate builds the ondemand.s JS file URL from its hash. onDemandFileURLTemplate = "https://abs.twimg.com/responsive-web/client-web/ondemand.s.%sa.js" // epochOffsetMillis is subtracted from the current unix-millis timestamp. // 1682924400 seconds ~= 2023-04-23T00:00:00Z. Ported from the literal // 1682924400 * 1000 in generate_transaction_id. epochOffsetMillis = 1682924400 * 1000 // totalTime is the animation frame-time normaliser. totalTime = 4096 ) var ( // onDemandFileRegex finds the ondemand.s file index in the home page HTML. // Python: r""",(\d+):["']ondemand\.s["']""" onDemandFileRegex = regexp.MustCompile(`,(\d+):["']ondemand\.s["']`) // indicesRegex extracts the key-byte indices from the ondemand.s JS file. // Python: r"""(\(\w{1}\[(\d{1,2})\],\s*16\))+""" indicesRegex = regexp.MustCompile(`\(\w\[(\d{1,2})\],\s*16\)`) ) // onDemandHashPattern builds the per-index hash extraction regex. Python: // r',{}:\"([0-9a-f]+)\"'. func onDemandHashPattern(index string) *regexp.Regexp { return regexp.MustCompile(`,` + regexp.QuoteMeta(index) + `:"([0-9a-f]+)"`) }pkg/transaction/cubic.go1.3 KB5c4c03b0835dupstream ↗
package transaction // cubic ports cubic_curve.Cubic: a cubic Bézier solver over four control // values [x1, y1, x2, y2]. type cubic struct { curves []float64 } func newCubic(curves []float64) *cubic { return &cubic{curves: curves} } func (c *cubic) getValue(t float64) float64 { var startGradient, endGradient float64 start, mid, end := 0.0, 0.0, 1.0 if t <= 0.0 { if c.curves[0] > 0.0 { startGradient = c.curves[1] / c.curves[0] } else if c.curves[1] == 0.0 && c.curves[2] > 0.0 { startGradient = c.curves[3] / c.curves[2] } return startGradient * t } if t >= 1.0 { if c.curves[2] < 1.0 { endGradient = (c.curves[3] - 1.0) / (c.curves[2] - 1.0) } else if c.curves[2] == 1.0 && c.curves[0] < 1.0 { endGradient = (c.curves[1] - 1.0) / (c.curves[0] - 1.0) } return 1.0 + endGradient*(t-1.0) } for start < end { mid = (start + end) / 2 xEst := cubicCalculate(c.curves[0], c.curves[2], mid) if abs(t-xEst) < 0.00001 { return cubicCalculate(c.curves[1], c.curves[3], mid) } if xEst < t { start = mid } else { end = mid } } return cubicCalculate(c.curves[1], c.curves[3], mid) } func cubicCalculate(a, b, m float64) float64 { return 3.0*a*(1-m)*(1-m)*m + 3.0*b*(1-m)*m*m + m*m*m } func abs(x float64) float64 { if x < 0 { return -x } return x }pkg/transaction/mathutil.go2.0 KB126eb7ff0106upstream ↗
package transaction import ( "math" "strconv" ) // roundTo replicates Python's round(x, n). CPython rounds half-to-even on the // true decimal value; Go's strconv.FormatFloat uses the same round-half-to-even // rule on the exact binary value, so formatting and re-parsing reproduces // Python's result bit-for-bit for the inputs this library deals with. func roundTo(x float64, n int) float64 { v, _ := strconv.ParseFloat(strconv.FormatFloat(x, 'f', n, 64), 64) return v } // roundHalfEven replicates Python's round(x) -> int (banker's rounding). func roundHalfEven(x float64) int { v, _ := strconv.ParseInt(strconv.FormatFloat(x, 'f', 0, 64), 10, 64) return int(v) } // mathRound ports utils.Math.round: floor, bump to ceil on >= .5, keep sign. func mathRound(num float64) float64 { x := math.Floor(num) if num-x >= 0.5 { x = math.Ceil(num) } return math.Copysign(x, num) } // solve ports ClientTransaction.solve. func solve(value, minVal, maxVal float64, rounding bool) float64 { result := value*(maxVal-minVal)/255 + minVal if rounding { return math.Floor(result) } return roundTo(result, 2) } // isOdd ports utils.is_odd: -1.0 for odd, 0.0 for even. func isOdd(n int) float64 { if n%2 != 0 { return -1.0 } return 0.0 } // floatToHex ports utils.float_to_hex, including its uppercase A-F digits and // the leading-dot behaviour for pure fractions. func floatToHex(x float64) string { var result []byte quotient := int(x) fraction := x - float64(quotient) for quotient > 0 { quotient = int(x / 16) remainder := int(x - float64(quotient)*16) if remainder > 9 { result = append([]byte{byte(remainder + 55)}, result...) } else { result = append([]byte{byte(remainder + '0')}, result...) } x = float64(quotient) } if fraction == 0 { return string(result) } result = append(result, '.') for fraction > 0 { fraction *= 16 integer := int(fraction) fraction -= float64(integer) if integer > 9 { result = append(result, byte(integer+55)) } else { result = append(result, byte(integer+'0')) } } return string(result) }pkg/transaction/parse.go2.7 KB4989ec740b59upstream ↗
package transaction import ( "fmt" "regexp" "strconv" "strings" "github.com/PuerkitoBio/goquery" ) var digitsRegex = regexp.MustCompile(`\d+`) // getKey extracts the twitter-site-verification key from the home page. func getKey(doc *goquery.Document) (string, error) { v, ok := doc.Find("meta[name='twitter-site-verification']").First().Attr("content") if !ok || v == "" { return "", fmt.Errorf("transaction: couldn't get [twitter-site-verification] key from page source") } return v, nil } // getFrames returns the loading-x-anim animation frame elements. func getFrames(doc *goquery.Document) *goquery.Selection { return doc.Find("[id^='loading-x-anim']") } // get2DArray ports ClientTransaction.get_2d_array. It selects the frame at // keyBytes[5]%4, reads the second path's "d" attribute, drops the first 9 // characters, splits on "C", and parses each segment's digit runs. func get2DArray(doc *goquery.Document, keyBytes []int) ([][]int, error) { frames := getFrames(doc) if frames.Length() == 0 { return nil, fmt.Errorf("transaction: no loading-x-anim frames found") } frame := frames.Eq(keyBytes[5] % 4) d, ok := frame.Children().Eq(0).Children().Eq(1).Attr("d") if !ok || len(d) < 9 { return nil, fmt.Errorf("transaction: animation frame path data missing or too short") } segments := strings.Split(d[9:], "C") out := make([][]int, 0, len(segments)) for _, seg := range segments { nums := digitsRegex.FindAllString(seg, -1) row := make([]int, 0, len(nums)) for _, n := range nums { i, _ := strconv.Atoi(n) row = append(row, i) } out = append(out, row) } return out, nil } // getIndices ports ClientTransaction.get_indices over the ondemand.s text. func getIndices(ondemandText string) (rowIndex int, keyBytesIndices []int, err error) { matches := indicesRegex.FindAllStringSubmatch(ondemandText, -1) if len(matches) == 0 { return 0, nil, fmt.Errorf("transaction: couldn't get KEY_BYTE indices") } all := make([]int, 0, len(matches)) for _, m := range matches { i, convErr := strconv.Atoi(m[1]) if convErr != nil { return 0, nil, fmt.Errorf("transaction: bad index %q: %w", m[1], convErr) } all = append(all, i) } return all[0], all[1:], nil } // getOndemandFileURL ports utils.get_ondemand_file_url over the raw home HTML. func getOndemandFileURL(homeHTML string) (string, error) { idxMatch := onDemandFileRegex.FindStringSubmatch(homeHTML) if idxMatch == nil { return "", fmt.Errorf("transaction: couldn't locate ondemand.s file index") } hashMatch := onDemandHashPattern(idxMatch[1]).FindStringSubmatch(homeHTML) if hashMatch == nil { return "", fmt.Errorf("transaction: couldn't locate ondemand.s file hash") } return fmt.Sprintf(onDemandFileURLTemplate, hashMatch[1]), nil }pkg/transaction/provider.go5.0 KBdb3c5d82a3daupstream ↗
package transaction import ( "fmt" "io" "net/http" "net/url" "sync" "time" ) // DefaultUserAgent matches a recent desktop Chrome, consistent with the headers // xclient sends on API calls. const DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36" // Provider fetches and caches the data needed to build a Generator (the x.com // home page and its ondemand.s file), refreshing it after TTL. The verification // and animation keys rotate infrequently, so a long TTL keeps requests cheap // while still looking like a live browser session. type Provider struct { httpClient *http.Client userAgent string ttl time.Duration // cookie is the account cookie string sent when fetching x.com. x.com only // serves the responsive-web chunk map (the `,<idx>:"ondemand.s"` entry the // generator needs) to an authenticated session; the logged-out shell this // provider used to request does not contain it, which made every // transaction-id generation fail. Writes are fatal on that failure, so // posts/likes/DMs/Grok all errored with "generate x-client-transaction-id". cookie string mu sync.Mutex gen *Generator fetchedAt time.Time } // ProviderOption customises a Provider. type ProviderOption func(*Provider) // WithHTTPClient sets the HTTP client used to fetch x.com (share this with the // API client so both present the same TLS fingerprint). func WithHTTPClient(c *http.Client) ProviderOption { return func(p *Provider) { p.httpClient = c } } // WithUserAgent sets the User-Agent used when fetching x.com. func WithUserAgent(ua string) ProviderOption { return func(p *Provider) { p.userAgent = ua } } // WithTTL sets how long fetched home/ondemand data is reused (default 3h). func WithTTL(d time.Duration) ProviderOption { return func(p *Provider) { p.ttl = d } } // WithCookie sets the account cookie string used when fetching x.com. Required: // x.com only serves the chunk map the generator parses to authenticated // sessions (see Provider.cookie). func WithCookie(cookie string) ProviderOption { return func(p *Provider) { p.cookie = cookie } } // SetCookie updates the cookie used for x.com fetches. Safe to call per client // even when the provider is shared: the cached Generator is account-independent, // so an update only affects the next refresh. func (p *Provider) SetCookie(cookie string) { p.mu.Lock() p.cookie = cookie p.mu.Unlock() } // NewProvider creates a Provider with sensible defaults. func NewProvider(opts ...ProviderOption) *Provider { p := &Provider{ httpClient: &http.Client{Timeout: 30 * time.Second}, userAgent: DefaultUserAgent, ttl: 3 * time.Hour, } for _, o := range opts { o(p) } return p } // TransactionID returns a fresh x-client-transaction-id for the method/path, // refreshing the underlying keys if the cache has expired. func (p *Provider) TransactionID(method, path string) (string, error) { g, err := p.generator() if err != nil { return "", err } return g.GenerateTransactionID(method, path), nil } func (p *Provider) generator() (*Generator, error) { p.mu.Lock() defer p.mu.Unlock() if p.gen != nil && time.Since(p.fetchedAt) < p.ttl { return p.gen, nil } if err := p.refreshLocked(); err != nil { if p.gen != nil { return p.gen, nil // fall back to stale keys rather than failing the request } return nil, err } return p.gen, nil } func (p *Provider) refreshLocked() error { homeHTML, err := p.fetch("https://x.com", p.cookie) if err != nil { return fmt.Errorf("transaction: fetch home page: %w", err) } ondemandURL, err := getOndemandFileURL(homeHTML) if err != nil { return err } // The ondemand.s file is a static asset on abs.twimg.com: send no cookies. ondemandText, err := p.fetch(ondemandURL, "") if err != nil { return fmt.Errorf("transaction: fetch ondemand file: %w", err) } gen, err := New(homeHTML, ondemandText) if err != nil { return err } p.gen = gen p.fetchedAt = time.Now() return nil } func (p *Provider) fetch(rawURL, cookie string) (string, error) { req, err := http.NewRequest(http.MethodGet, rawURL, nil) if err != nil { return "", err } req.Header.Set("User-Agent", p.userAgent) req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8") req.Header.Set("Accept-Language", "en-US,en;q=0.9") req.Header.Set("Referer", "https://x.com") req.Header.Set("Cache-Control", "no-cache") // Only x.com serves the chunk map, and only to an authenticated session. // Never send the account cookies to the static asset host. if u, perr := url.Parse(rawURL); perr == nil && u.Host == "x.com" && cookie != "" { req.Header.Set("Cookie", cookie) } resp, err := p.httpClient.Do(req) if err != nil { return "", err } defer resp.Body.Close() if resp.StatusCode != http.StatusOK { return "", fmt.Errorf("transaction: %s returned status %d", rawURL, resp.StatusCode) } body, err := io.ReadAll(resp.Body) if err != nil { return "", err } return string(body), nil }pkg/transaction/provider_test.go2.3 KB253ac939de55upstream ↗
package transaction import ( "io" "net/http" "strings" "testing" ) // captureRT records the last request it saw so tests can assert on headers. type captureRT struct{ req *http.Request } func (c *captureRT) RoundTrip(r *http.Request) (*http.Response, error) { c.req = r return &http.Response{ StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader("<html></html>")), Header: make(http.Header), }, nil } func newTestProvider(rt *captureRT, cookie string) *Provider { return NewProvider( WithHTTPClient(&http.Client{Transport: rt}), WithCookie(cookie), ) } func TestProviderCookieOptions(t *testing.T) { p := NewProvider(WithCookie("auth_token=a; ct0=b")) if p.cookie != "auth_token=a; ct0=b" { t.Fatalf("WithCookie not applied: %q", p.cookie) } p.SetCookie("auth_token=c") if p.cookie != "auth_token=c" { t.Fatalf("SetCookie not applied: %q", p.cookie) } } // x.com only serves the responsive-web chunk map (the `,<idx>:"ondemand.s"` // entry getOndemandFileURL parses) to an authenticated session, so the home // page fetch must carry the account cookie — and only that host may see it. func TestProviderFetchCookieScope(t *testing.T) { rt := &captureRT{} p := newTestProvider(rt, "auth_token=a; ct0=b") if _, err := p.fetch("https://x.com/", p.cookie); err != nil { t.Fatalf("fetch x.com: %v", err) } if got := rt.req.Header.Get("Cookie"); got != "auth_token=a; ct0=b" { t.Fatalf("x.com home fetch must send the account cookie, got %q", got) } if got := rt.req.Header.Get("User-Agent"); got == "" { t.Fatal("home fetch lost its User-Agent") } // The ondemand.s file is a static asset on abs.twimg.com: no cookies. if _, err := p.fetch("https://abs.twimg.com/responsive-web/client-web/ondemand.s.deadbeef1a.js", ""); err != nil { t.Fatalf("fetch asset: %v", err) } if got := rt.req.Header.Get("Cookie"); got != "" { t.Fatalf("static asset host must not receive the account cookie, got %q", got) } // Belt and braces: even if a cookie is passed in, a non-x.com host is refused. if _, err := p.fetch("https://example.com/", "auth_token=a"); err != nil { t.Fatalf("fetch other host: %v", err) } if got := rt.req.Header.Get("Cookie"); got != "" { t.Fatalf("non-x.com host must not receive the account cookie, got %q", got) } }pkg/transaction/transaction.go5.9 KB3bd0e883c240upstream ↗
package transaction import ( "crypto/sha256" "encoding/base64" "fmt" "math" "math/rand" "net/url" "regexp" "strconv" "strings" "time" "github.com/PuerkitoBio/goquery" ) // Generator is a faithful port of XClientTransaction.ClientTransaction. It is // safe for concurrent use: GenerateTransactionID only reads immutable state and // uses package-level randomness. type Generator struct { doc *goquery.Document key string keyBytes []int animationKey string rowIndex int keyBytesIndices []int randomKeyword string additionalNumber int } // Option customises a Generator. type Option func(*Generator) // WithKeyword overrides the obfuscation keyword (defaults to "obfiowerehiring"). func WithKeyword(k string) Option { return func(g *Generator) { g.randomKeyword = k } } // WithNumber overrides the static appended byte (defaults to 3). func WithNumber(n int) Option { return func(g *Generator) { g.additionalNumber = n } } var dotDashRegex = regexp.MustCompile(`[.-]`) // New builds a Generator from the x.com home page HTML and the ondemand.s file // text. Both are fetched without authentication (see Provider for a helper that // retrieves and caches them). func New(homeHTML, ondemandText string, opts ...Option) (*Generator, error) { doc, err := goquery.NewDocumentFromReader(strings.NewReader(homeHTML)) if err != nil { return nil, fmt.Errorf("transaction: parse home page: %w", err) } g := &Generator{ doc: doc, randomKeyword: defaultKeyword, additionalNumber: additionalRandomNumber, } for _, o := range opts { o(g) } if g.rowIndex, g.keyBytesIndices, err = getIndices(ondemandText); err != nil { return nil, err } if g.key, err = getKey(doc); err != nil { return nil, err } keyBytes, err := decodeKeyBytes(g.key) if err != nil { return nil, err } g.keyBytes = keyBytes if g.animationKey, err = g.getAnimationKey(); err != nil { return nil, err } return g, nil } func decodeKeyBytes(key string) ([]int, error) { raw, err := base64.StdEncoding.DecodeString(key) if err != nil { return nil, fmt.Errorf("transaction: decode verification key: %w", err) } out := make([]int, len(raw)) for i, b := range raw { out[i] = int(b) } return out, nil } func (g *Generator) getAnimationKey() (string, error) { rowIndex := g.keyBytes[g.rowIndex] % 16 frameTime := 1 for _, idx := range g.keyBytesIndices { frameTime *= g.keyBytes[idx] % 16 } frameTimeF := mathRound(float64(frameTime)/10) * 10 arr, err := get2DArray(g.doc, g.keyBytes) if err != nil { return "", err } if rowIndex >= len(arr) { return "", fmt.Errorf("transaction: frame row index %d out of range (%d rows)", rowIndex, len(arr)) } frameRow := arr[rowIndex] if len(frameRow) < 11 { return "", fmt.Errorf("transaction: frame row too short (%d values)", len(frameRow)) } targetTime := frameTimeF / totalTime return animate(frameRow, targetTime), nil } // animate ports ClientTransaction.animate. func animate(frames []int, targetTime float64) string { fromColor := []float64{float64(frames[0]), float64(frames[1]), float64(frames[2]), 1} toColor := []float64{float64(frames[3]), float64(frames[4]), float64(frames[5]), 1} fromRotation := []float64{0.0} toRotation := []float64{solve(float64(frames[6]), 60.0, 360.0, true)} rest := frames[7:] curves := make([]float64, len(rest)) for i, item := range rest { curves[i] = solve(float64(item), isOdd(i), 1.0, false) } val := newCubic(curves).getValue(targetTime) color := interpolate(fromColor, toColor, val) for i := range color { color[i] = math.Max(0, math.Min(255, color[i])) } rotation := interpolate(fromRotation, toRotation, val) matrix := convertRotationToMatrix(rotation[0]) var sb strings.Builder for _, value := range color[:len(color)-1] { sb.WriteString(strconv.FormatInt(int64(roundHalfEven(value)), 16)) } for _, value := range matrix { rounded := roundTo(value, 2) if rounded < 0 { rounded = -rounded } hexValue := floatToHex(rounded) switch { case strings.HasPrefix(hexValue, "."): sb.WriteString(strings.ToLower("0" + hexValue)) case hexValue != "": sb.WriteString(hexValue) default: sb.WriteString("0") } } sb.WriteString("00") return dotDashRegex.ReplaceAllString(sb.String(), "") } // GenerateTransactionID produces the x-client-transaction-id value for an HTTP // method and request path (e.g. "/i/api/graphql/<qid>/UserByScreenName"). func (g *Generator) GenerateTransactionID(method, path string) string { timeNow := int64(math.Floor(float64(time.Now().UnixMilli()-epochOffsetMillis) / 1000)) timeNowBytes := []int{ int(timeNow & 0xFF), int((timeNow >> 8) & 0xFF), int((timeNow >> 16) & 0xFF), int((timeNow >> 24) & 0xFF), } input := fmt.Sprintf("%s!%s!%d%s%s", method, path, timeNow, g.randomKeyword, g.animationKey) sum := sha256.Sum256([]byte(input)) bytesArr := make([]int, 0, len(g.keyBytes)+4+16+1) bytesArr = append(bytesArr, g.keyBytes...) bytesArr = append(bytesArr, timeNowBytes...) for _, b := range sum[:16] { bytesArr = append(bytesArr, int(b)) } bytesArr = append(bytesArr, g.additionalNumber) randomNum := rand.Intn(256) out := make([]byte, 0, len(bytesArr)+1) out = append(out, byte(randomNum)) for _, item := range bytesArr { out = append(out, byte(item^randomNum)) } return strings.TrimRight(base64.StdEncoding.EncodeToString(out), "=") } // GenerateForURL is a convenience wrapper that extracts the path from a full URL. func (g *Generator) GenerateForURL(method, rawURL string) (string, error) { u, err := url.Parse(rawURL) if err != nil { return "", fmt.Errorf("transaction: parse url: %w", err) } return g.GenerateTransactionID(method, u.Path), nil } // Key returns the verification key extracted from the home page. func (g *Generator) Key() string { return g.key } // AnimationKey returns the computed animation key (useful for debugging/tests). func (g *Generator) AnimationKey() string { return g.animationKey }pkg/transaction/transaction_test.go2.2 KBab75c8b5e3aaupstream ↗
package transaction import ( "encoding/base64" "os" "strings" "testing" ) // golden values produced by the reference Python XClientTransaction library // (iSarabjitDhiman/XClientTransaction) on the same fixtures. const ( goldenAnimationKey = "7ad100ccccccccccccd00ccccccccccccd100" goldenRowIndex = 2 ) func loadFixtures(t *testing.T) (home, ondemand string) { t.Helper() h, err := os.ReadFile("testdata/home.html") if err != nil { t.Fatalf("read home fixture: %v", err) } o, err := os.ReadFile("testdata/ondemand.js") if err != nil { t.Fatalf("read ondemand fixture: %v", err) } return string(h), string(o) } func TestParityWithPython(t *testing.T) { home, ondemand := loadFixtures(t) g, err := New(home, ondemand) if err != nil { t.Fatalf("New: %v", err) } if g.rowIndex != goldenRowIndex { t.Errorf("rowIndex = %d, want %d", g.rowIndex, goldenRowIndex) } if g.AnimationKey() != goldenAnimationKey { t.Errorf("animationKey = %q, want %q", g.AnimationKey(), goldenAnimationKey) } } func TestGenerateTransactionIDShape(t *testing.T) { home, ondemand := loadFixtures(t) g, err := New(home, ondemand) if err != nil { t.Fatalf("New: %v", err) } id := g.GenerateTransactionID("GET", "/i/api/graphql/abc/UserByScreenName") if id == "" { t.Fatal("empty transaction id") } if strings.HasSuffix(id, "=") { t.Errorf("transaction id should be unpadded: %q", id) } // must decode as standard base64 once padding is restored padded := id if m := len(padded) % 4; m != 0 { padded += strings.Repeat("=", 4-m) } if _, err := base64.StdEncoding.DecodeString(padded); err != nil { t.Errorf("transaction id is not valid base64: %v", err) } // two successive ids should differ (random byte + timestamp) if id2 := g.GenerateTransactionID("GET", "/i/api/graphql/abc/UserByScreenName"); id2 == id { t.Error("expected successive transaction ids to differ") } } func TestFloatToHex(t *testing.T) { // spot-checks mirroring the Python implementation's behaviour. cases := map[float64]string{ 0: "", 1: "1", 255: "FF", 16: "10", } for in, want := range cases { if got := floatToHex(in); got != want { t.Errorf("floatToHex(%v) = %q, want %q", in, got, want) } } }pkg/xclient/article_test.go5.2 KB9062679ed896upstream ↗
package xclient import ( "testing" "github.com/dezxbt/agentx/pkg/models" ) // richArticleResult mirrors the real article schema: an inline Bold range, plus // atomic blocks whose entityRanges reference an entityMap (list of // {key,value}) carrying DIVIDER, MARKDOWN and MEDIA entities, with media URLs // resolved through media_entities. const richArticleResult = `{ "article": { "article_results": { "result": { "title": "Rich", "media_entities": [ { "media_id": "m1", "media_info": { "__typename": "ApiImage", "original_img_url": "https://img/x.jpg" } } ], "content_state": { "blocks": [ { "type": "unstyled", "text": "Hello bold world", "inlineStyleRanges": [ { "offset": 6, "length": 4, "style": "Bold" } ], "entityRanges": [] }, { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 0, "length": 1, "offset": 0 } ] }, { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 1, "length": 1, "offset": 0 } ] }, { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 2, "length": 1, "offset": 0 } ] } ], "entityMap": [ { "key": "0", "value": { "type": "DIVIDER", "data": {} } }, { "key": "1", "value": { "type": "MARKDOWN", "data": { "markdown": "| a | b |\n|---|---|" } } }, { "key": "2", "value": { "type": "MEDIA", "data": { "caption": "fig", "mediaItems": [ { "mediaId": "m1" } ] } } } ] } } } } }` func TestArticleEntitiesAndInlineMarkdown(t *testing.T) { tw := &models.Tweet{} fillArticle(tw, asMap(decode([]byte(richArticleResult))), true) want := "Hello **bold** world\n\n---\n\n| a | b |\n|---|---|\n\n" if tw.ArticleText != want { t.Errorf("markdown =\n%q\nwant\n%q", tw.ArticleText, want) } } func TestArticleEntitiesPlain(t *testing.T) { tw := &models.Tweet{} fillArticle(tw, asMap(decode([]byte(richArticleResult))), false) // plain: no inline marks, divider skipped, markdown + media captions kept want := "Hello bold world\n| a | b |\n|---|---|\nfig: https://img/x.jpg" if tw.ArticleText != want { t.Errorf("plain =\n%q\nwant\n%q", tw.ArticleText, want) } } func TestApplyInlineStylesNestedAndUnicode(t *testing.T) { // "a—b" has an en-dash (multi-byte in UTF-8, 1 UTF-16 unit); bold over "b". got := applyInlineStyles("a—b", []any{ map[string]any{"offset": float64(2), "length": float64(1), "style": "Bold"}, }) if got != "a—**b**" { t.Errorf("got %q, want %q", got, "a—**b**") } } // sampleArticleTweet mirrors a TweetResultByRestId result for a long-form X // Article: a normal tweet object plus an article.article_results.result holding // a DraftJS content_state with assorted block types. const sampleArticleTweet = `{ "__typename": "Tweet", "rest_id": "456", "core": { "user_results": { "result": { "rest_id": "9", "core": { "name": "Jack", "screen_name": "jack" } } } }, "legacy": { "full_text": "Read my article", "lang": "en" }, "article": { "article_results": { "result": { "title": "My Great Article", "preview_text": "A short preview", "content_state": { "blocks": [ { "type": "header-one", "text": "Intro" }, { "type": "unstyled", "text": "First paragraph." }, { "type": "ordered-list-item", "text": "step one" }, { "type": "ordered-list-item", "text": "step two" }, { "type": "unordered-list-item", "text": "a bullet" }, { "type": "blockquote", "text": "a quote" } ] } } } } }` func TestParseArticlePlainText(t *testing.T) { tw := parseTweetResult(decode([]byte(sampleArticleTweet))) if tw == nil { t.Fatal("parseTweetResult returned nil") } if tw.ID != "456" { t.Errorf("id = %q, want 456", tw.ID) } if tw.ArticleTitle != "My Great Article" { t.Errorf("articleTitle = %q", tw.ArticleTitle) } want := "Intro\nFirst paragraph.\nstep one\nstep two\na bullet\na quote" if tw.ArticleText != want { t.Errorf("articleText (plain) =\n%q\nwant\n%q", tw.ArticleText, want) } } func TestRenderArticleMarkdown(t *testing.T) { res := asMap(deepGet(decode([]byte(sampleArticleTweet)), "article", "article_results", "result")) cs := articleContentState(res) got := renderArticle(asSlice(cs["blocks"]), nil, nil, true) want := "# Intro\n\nFirst paragraph.\n\n1. step one\n\n2. step two\n\n- a bullet\n\n> a quote" if got != want { t.Errorf("markdown =\n%q\nwant\n%q", got, want) } } // content_state is sometimes delivered as a JSON-encoded string; ensure we // decode that form too. func TestArticleContentStateAsString(t *testing.T) { res := map[string]any{ "content_state": `{"blocks":[{"type":"unstyled","text":"hi"}]}`, } cs := articleContentState(res) if cs == nil { t.Fatal("expected decoded content_state, got nil") } if got := renderArticle(asSlice(cs["blocks"]), nil, nil, false); got != "hi" { t.Errorf("text = %q, want hi", got) } } // A tweet with no article block must leave the article fields empty. func TestNonArticleTweetHasNoArticleFields(t *testing.T) { tw := parseTweetResult(decode([]byte(`{ "rest_id": "1", "legacy": { "full_text": "plain tweet" } }`))) if tw == nil { t.Fatal("nil tweet") } if tw.ArticleTitle != "" || tw.ArticleText != "" { t.Errorf("expected empty article fields, got title=%q text=%q", tw.ArticleTitle, tw.ArticleText) } }pkg/xclient/bookmarkfolders.go2.5 KBa961d22fe7d3upstream ↗
package xclient import ( "context" "github.com/dezxbt/agentx/pkg/models" "github.com/dezxbt/agentx/pkg/xerrors" ) // BookmarkFolder is a named bookmark collection. type BookmarkFolder struct { ID string `json:"id"` Name string `json:"name"` } // BookmarkFolders lists the account's bookmark folders. func (c *Client) BookmarkFolders(ctx context.Context) ([]BookmarkFolder, error) { data, err := c.graphqlGET(ctx, "BookmarkFoldersSlice", map[string]any{}, nil, nil) if err != nil { return nil, err } var out []BookmarkFolder for _, raw := range asSlice(deepGet(decode(data), "viewer", "bookmark_collections_slice", "items")) { m := asMap(raw) if id := asString(m["id"]); id != "" { out = append(out, BookmarkFolder{ID: id, Name: asString(m["name"])}) } } return out, nil } // CreateBookmarkFolder creates a new bookmark folder and returns it. func (c *Client) CreateBookmarkFolder(ctx context.Context, name string) (*BookmarkFolder, error) { data, err := c.graphqlPOST(ctx, "createBookmarkFolder", map[string]any{"name": name}, nil, true) if err != nil { return nil, err } m := asMap(deepGet(decode(data), "bookmark_collection_create")) id := asString(m["id"]) if id == "" { id = asString(findKey(decode(data), "id")) } if id == "" { return nil, xerrors.New(xerrors.APIError, "bookmark folder not created: unexpected response") } n := asString(m["name"]) if n == "" { n = name } return &BookmarkFolder{ID: id, Name: n}, nil } // DeleteBookmarkFolder deletes a bookmark folder by id. func (c *Client) DeleteBookmarkFolder(ctx context.Context, folderID string) error { return c.simpleWrite(ctx, "DeleteBookmarkFolder", map[string]any{"bookmark_collection_id": folderID}) } // BookmarkToFolder bookmarks a tweet into a specific folder. func (c *Client) BookmarkToFolder(ctx context.Context, tweetID, folderID string) error { return c.simpleWrite(ctx, "bookmarkTweetToFolder", map[string]any{ "tweet_id": tweetID, "bookmark_collection_id": folderID, }) } // BookmarkFolderTweets returns the tweets saved in a bookmark folder. func (c *Client) BookmarkFolderTweets(ctx context.Context, folderID string, count int, cursor string) (*models.Page, error) { vars := map[string]any{ "bookmark_collection_id": folderID, "count": clampCount(count), } if cursor != "" { vars["cursor"] = cursor } data, err := c.graphqlGET(ctx, "BookmarkFolderTimeline", vars, nil, nil) if err != nil { return nil, err } return pageFrom(data), nil }pkg/xclient/client.go16 KB604319e9276dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/community.go5.1 KBe2814a4e02f2upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/constants.go6.9 KB75622d20148cupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/dm.go5.3 KBb5ce6d3f869dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/dm_test.go1.1 KB4f7277d0bfeaupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/drafts.go1.8 KB3c671a90c26cupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/grok.go5.0 KB0eabeb6ccd79upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/jsonutil.go1.5 KBb83af3cd921fupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/lists.go2.5 KBa969fce8a038upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/login.go8.9 KB4ca58c093238upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/notifications.go4.5 KBc36203414e47upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/oauth.go6.4 KBa4b2a73f9bc8upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/parser.go18 KB20bc6fd7f9eaupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/parser_test.go4.1 KB1a532ce0b084upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/poll_reply_test.go4.8 KB01395c458b3aupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/polls.go3.4 KB1866714da0d3upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/profile.go901 Bb9e221c1f0b4upstream ↗
package xclient import ( "context" "net/url" ) // ProfileFields are the editable profile attributes. Empty fields are omitted, // so callers can update just the ones they pass. type ProfileFields struct { Name string // display name Description string // bio Location string URL string } // UpdateProfile edits the authenticated account's profile (name, bio, location, // url) via the v1.1 account/update_profile endpoint. Only the non-empty fields // are sent. func (c *Client) UpdateProfile(ctx context.Context, f ProfileFields) error { form := url.Values{} if f.Name != "" { form.Set("name", f.Name) } if f.Description != "" { form.Set("description", f.Description) } if f.Location != "" { form.Set("location", f.Location) } if f.URL != "" { form.Set("url", f.URL) } _, err := c.restPostForm(ctx, "/1.1/account/update_profile.json", form) return err }pkg/xclient/reads.go14 KB7744dcec93a0upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/restparse.go2.4 KB2c3fb8b231f9upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/restparse_test.go1.1 KB582b6c84f1a7upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/scheduled.go2.5 KBa3a937a10a1dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/settings.go4.1 KB0c3824697ce7upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/upload.go5.6 KB281ba693b9c7upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/upload_test.go409 B289290657032upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/utls.go3.8 KBb0b9e4c0f150upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xclient/writes.go7.6 KBbfa86415874dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
pkg/xerrors/xerrors.go1.4 KB7e455c41707dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/dezxbt-agentx.md