Skip to content
← Public packages

@kody/x

Look up X users and tweets, search recent posts, and preview guarded posts through saved OAuth.

FollowFork

Files

README.md

89 lines · 5.0 KB · Markdown

@kody/x

Official X logo (black rounded square, white glyph) from the X 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.

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 → 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:
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:

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.*.

  1. Paste the Client ID (and Client Secret only for confidential apps) into the Kody form, continue to X, and approve.
  2. Run the smoke test on the forked package (agents: AGENTS.md).

Reconnect with https://kody.codes/connect/oauth?provider=x.

Optional app-only bearer

Public reads can use an app-only bearer token. Save it as xBearerToken (never paste the value into chat):

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
CallResolves to
omit bothintegration 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.

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