@kentcdodds/x

@kentcdodds/x

Intent

Generic X API v2 utilities. Kodykoala Activity Pam policy moved to @kentcdodds/kodykoala-activity.

Headless X API v2 helpers for Kody agents: OpenAPI-scaffolded bearer-token reads (xBearerToken), multi-account OAuth user-context requests via saved x / x-* integrations, search/profile/post helpers with post shaping and read/metrics helpers (get-post, get-post-thread, summarize-post-metrics), rate-limit notes, guarded social actions, legacy direct messages, on-demand encrypted X Chat (list threads, read a thread, send a message) via a Fly XDK sidecar that unlocks the existing Chat identity with xChatPin, and an

Keep @kentcdodds/x as the single X package — do not stand up a separate 24/7 poller. Activity logic lives here; register X against the minted activity-event webhook URL. Platform challenge: x-activity-crc answers CRC on that URL (no Cloudflare Worker shim). Do not register the session-gated package-app URL with X.

Surface naming uses post (exports like ./get-post, ./create-post); the underlying X API resources remain /tweets and tweet.fields.

What it does

• App-only bearer reads: username lookup, recent search, public user posts, single-post fetch with quote/referenced shaping, conversation thread helper
• Engagement tables from public_metrics (summarize-post-metrics) — follows per view are not available in public metrics
• Multi-account OAuth: authenticated profile, posts, likes, reposts, bookmarks, follows
• Media: chunked v2 upload on api.x.com via ./upload-media (dry-run by default; media.write), then attach media.media_ids on create-post
• Legacy DMs: list events, read a conversation, send (guarded)
• Encrypted X Chat via Fly XDK sidecar: list inbox metadata, decrypt a thread, send ciphertext (guarded)
• Token refresh for a selected x / x-* integration
• Generic X API helpers used by @kentcdodds/kodykoala-activity for Pam wake (this package no longer owns that policy)
• Fork adapt guide and sidecar source for deploying your own Fly app

Activity / Pam wake (moved)

@kodykoala Activity → jev → Pam auto-wake now lives in @kentcdodds/kodykoala-activity. This package keeps generic X API helpers (including request used by that package). Do not register Pam webhooks here.

Prerequisites / setup

1. Save user secret xBearerToken (app-only bearer). Approve host api.x.com if prompted.
2. Connect OAuth integration x (default). Optional accounts: x-<purpose> (for example x-kodykoala). Reconnect at https://kody.codes/connect/oauth?provider=x or ...?provider=x-<purpose>.
3. For encrypted X Chat (needs OAuth dm.read / dm.write plus sidecar):
   • User secrets xChatPin (existing x.com Chat PIN — never generate a new keypair) and xChatSidecarToken (shared bearer for your Fly sidecar)
   • Package storage xChatSidecarUrl — your Fly origin (forks must set this; the listing default is the author’s sidecar)
   • Host-approve only your sidecar host on those secrets — not Juicebox or api.x.com for the PIN
4. Agents: see AGENTS.md for import paths, smoke/dryRun snippets, and fork adapt steps.

Multi-account: omit account → integration x; account: 'kodykoala' → x-kodykoala; or pass integration: 'x-kodykoala' exactly.

Done when

• xBearerToken is saved; OAuth x (and any x-*) connected as needed
• Bearer smoke returns ok: true (HTTP 429 counts as auth-plumbing-verified)
• Write helpers return dry-run unless confirm: true after explicit approval
• Chat (if used): sidecar URL stored, PIN/token secrets approved for your sidecar host only; list/get chat work without generating a new identity