# @kody/x — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by **name** only — never paste token values. Do not disable live webhooks or jobs. ## Auth / secrets / integrations | Kind | Name | Notes | | --- | --- | --- | | OAuth integration | `x` | Default user-context (BYO X app) | | OAuth integration | `x-` | Extra accounts (e.g. `x-work`) | | User secret | `xBearerToken` | Optional app-only bearer for public reads | Hosts: `api.x.com`, `upload.x.com`. There is no built-in Kody X app and no encrypted X Chat / Fly sidecar in this official listing. Multi-account: omit both → `x`; `account: 'work'` → `x-work`; `integration: 'x-work'` → exact name. ## Import paths | Export | Import | | --- | --- | | overview | `kody:@kody/x` | | accounts | `kody:@kody/x/accounts` | | smoke-test | `kody:@kody/x/smoke-test` | | request | `kody:@kody/x/request` | | refresh-oauth-token | `kody:@kody/x/refresh-oauth-token` | | get-me | `kody:@kody/x/get-me` | | get-user-by-username | `kody:@kody/x/get-user-by-username` | | get-tweet | `kody:@kody/x/get-tweet` | | get-user-tweets | `kody:@kody/x/get-user-tweets` | | search-recent | `kody:@kody/x/search-recent` | | create-tweet | `kody:@kody/x/create-tweet` | | delete-tweet | `kody:@kody/x/delete-tweet` | | like-tweet / unlike-tweet | `kody:@kody/x/like-tweet` / `.../unlike-tweet` | | repost-tweet / unrepost-tweet | `kody:@kody/x/repost-tweet` / `.../unrepost-tweet` | | bookmark-tweet / remove-bookmark | `kody:@kody/x/bookmark-tweet` / `.../remove-bookmark` | | follow-user / unfollow-user | `kody:@kody/x/follow-user` / `.../unfollow-user` | | media-upload-guide | `kody:@kody/x/media-upload-guide` | Prefer static `kody:@kody/x/...` imports from `execute`. Do not lead with `packages.invoke`. ## Smoke test (read-only) ```ts import smokeTest from 'kody:@kody/x/smoke-test' export default async function main() { return await smokeTest() // success => { ok: true, integration: 'x', user: { id, username, name } } // missing creds => { ok: false, setup } // HTTP 429 counts as auth plumbing verified } ``` ## dryRun / confirm Mutating helpers never write when `dryRun: true`, and refuse a live write unless `confirm: true` after the user approved the exact payload. Do not infer confirmation from a successful dry-run. ```ts import createTweet from 'kody:@kody/x/create-tweet' export default async function main() { return await createTweet({ text: 'Draft text', dryRun: true }) } ``` Named account: ```ts import getMe from 'kody:@kody/x/get-me' export default async function main() { return await getMe({ account: 'work' }) } ``` ## Edge cases / fork notes - Scopes: `tweet.read` / `tweet.write`, `users.read`, `offline.access`, `like.*`, `follows.*`, `bookmark.*`. `./request` uses whatever the saved token already has. - Optional public reads: save `xBearerToken` and pass `authMode: 'bearer'`. Writes always use OAuth. - HTTP 401: reconnect `https://kody.codes/connect/oauth?provider=x` or call `./refresh-oauth-token`. - HTTP 403 on writes: add matching write scopes and reconnect. - Callback must be exactly `https://kody.codes/connect/oauth`. - After fork, connect **your** X app — do not treat live `@kody/x` as yours. Keep `dryRun` / `confirm` guards. This package does not include Chat/sidecar.