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

AGENTS.md

95 lines · 3.3 KB · Markdown

@kody/x — agent notes

Human setup and intent live in 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

KindNameNotes
OAuth integrationxDefault user-context (BYO X app)
OAuth integrationx-<purpose>Extra accounts (e.g. x-work)
User secretxBearerTokenOptional 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

ExportImport
overviewkody:@kody/x
accountskody:@kody/x/accounts
smoke-testkody:@kody/x/smoke-test
requestkody:@kody/x/request
refresh-oauth-tokenkody:@kody/x/refresh-oauth-token
get-mekody:@kody/x/get-me
get-user-by-usernamekody:@kody/x/get-user-by-username
get-tweetkody:@kody/x/get-tweet
get-user-tweetskody:@kody/x/get-user-tweets
search-recentkody:@kody/x/search-recent
create-tweetkody:@kody/x/create-tweet
delete-tweetkody:@kody/x/delete-tweet
like-tweet / unlike-tweetkody:@kody/x/like-tweet / .../unlike-tweet
repost-tweet / unrepost-tweetkody:@kody/x/repost-tweet / .../unrepost-tweet
bookmark-tweet / remove-bookmarkkody:@kody/x/bookmark-tweet / .../remove-bookmark
follow-user / unfollow-userkody:@kody/x/follow-user / .../unfollow-user
media-upload-guidekody:@kody/x/media-upload-guide

Prefer static kody:@kody/x/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

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.

import createTweet from 'kody:@kody/x/create-tweet'

export default async function main() {
	return await createTweet({ text: 'Draft text', dryRun: true })
}

Named account:

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.