# @kody/x Official X logo (black rounded square, white glyph) from the [X brand toolkit](https://about.x.com/en/who-we-are/brand-toolkit). Paths are unmodified. X and the X logo are trademarks of X Corp. ## Intent Give any Kody account reusable, headless X API v2 helpers for user lookup, tweets, recent search, and guarded posting. Auth is the caller’s saved `x` / `x-*` OAuth integration (optional app-only bearer for public reads). Identity always comes from the connected account — never a hard-coded profile. This listing is meant to be forked. After you fork, connect **your** X app and run `./smoke-test` on **your** copy. Do not treat the live `@kody/x` integration as yours. Share [https://kody.codes/@kody/x](https://kody.codes/@kody/x). ## What it does - Verify a saved `x` OAuth integration and read the connected user - Look up a user by username, read a tweet, list a user’s recent tweets, or search recent posts - Call uncommon X API v2 routes with `./request` - Preview a post or social action with `dryRun: true`, then mutate only after `confirm: true` Do not use this package as a 24/7 bot, a scraping client, or a place to paste access tokens. It does not include encrypted X Chat, Fly sidecars, or any owner-specific infrastructure. ## Prerequisites / setup X is **bring-your-own OAuth**. There is no built-in Kody X app. Tokens come from the hosted connect page. Never paste a client secret or access token into chat. 1. Open [X Developer Portal](https://developer.x.com/en/portal/dashboard) → create a Project and App with **User authentication** (OAuth 2.0). 2. App type: **Native App** (public / PKCE) or a confidential client with PKCE enabled. 3. Callback / redirect URI — register exactly `https://kody.codes/connect/oauth`. 4. Website URL can be `https://kody.codes`. 5. Open this prefilled connect URL while signed in to Kody: ```text https://kody.codes/connect/oauth?provider=x ``` First-time setup also needs X’s authorize and token URLs. Use this complete prefilled URL when the connection does not exist yet: ```text https://kody.codes/connect/oauth?provider=x&authorizeUrl=https%3A%2F%2Fx.com%2Fi%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.x.com%2F2%2Foauth2%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.x.com%2F2&flow=pkce&allowedHosts=api.x.com%2Cupload.x.com&dashboardUrl=https%3A%2F%2Fdeveloper.x.com%2Fen%2Fportal%2Fdashboard&scopes=tweet.read%20tweet.write%20users.read%20offline.access%20like.read%20like.write%20follows.read%20follows.write%20bookmark.read%20bookmark.write ``` Decoded: authorize `https://x.com/i/oauth2/authorize`, token `https://api.x.com/2/oauth2/token`, API base `https://api.x.com/2`, flow `pkce` (use `flow=confidential&pkce=true` if the X app has a client secret), hosts `api.x.com` + `upload.x.com`, scopes `tweet.read` / `tweet.write` / `users.read` / `offline.access` / `like.*` / `follows.*` / `bookmark.*`. 6. Paste the Client ID (and Client Secret only for confidential apps) into the Kody form, continue to X, and approve. 7. Run the smoke test on the **forked** package (agents: [`AGENTS.md`](./AGENTS.md)). Reconnect with `https://kody.codes/connect/oauth?provider=x`. ### Optional app-only bearer Public reads can use an [app-only bearer token](https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only). Save it as `xBearerToken` (never paste the value into chat): ```text https://kody.codes/account/secrets/new?name=xBearerToken&description=X%20API%20v2%20app-only%20bearer%20token%20for%20optional%20public%20reads&allowedHosts=api.x.com&scope=user ``` OAuth remains the default. Writes always use OAuth. ### Multi-account | Call | Resolves to | | --- | --- | | omit both | integration `x` | | `account: 'work'` | integration `x-work` | | `integration: 'x-work'` | that exact integration | Connect more accounts at `https://kody.codes/connect/oauth?provider=x-work` (same first-time query params, different `provider`). ### Mutation safety Mutating helpers never write when `dryRun: true`, and refuse a live write unless `confirm: true`. Agents: import paths, smoke snippets, and confirm examples live in [`AGENTS.md`](./AGENTS.md). ## Done when - `x` (or `x-*`) OAuth is connected; hosts `api.x.com` / `upload.x.com` approved - Smoke test returns `{ ok: true, user: { id, username, name } }` without posting - Destructive / posting helpers refuse unless `confirm: true`; `dryRun: true` never writes ## Troubleshooting - Connect page asks for authorize/token URLs: use the complete first-time URL above. - HTTP 401 / expired token: reconnect or call `./refresh-oauth-token`. - HTTP 403 on writes: add matching write scopes, then reconnect. - HTTP 429: rate-limited; treat as plumbing-verified for smoke; wait before retrying. - `redirect_uri` mismatch: callback must be exactly `https://kody.codes/connect/oauth`. ## Docs - [X API v2](https://docs.x.com/x-api/introduction) - [OAuth 2.0 Authorization Code with PKCE](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code) - [App-only bearer](https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only)