@kentcdodds/x

@kentcdodds/x

Intent

Headless X API v2 helpers for Kody agents: OpenAPI-scaffolded bearer-token reads (xBearerToken), OAuth user-context requests (xAccessToken / xRefreshToken), search/profile/tweet helpers with tweet shaping and rate-limit notes, and guarded social actions. The low-level REST layer comes from openapi_client_scaffold against the official X OpenAPI spec.

When To Use

• Verify X bearer credentials with a single username lookup (free tier is heavily rate-limited).
• Search or read public X data with app-only bearer auth.
• Read the authenticated user or post on their behalf with OAuth.
• Draft posts and social actions with dry-run safety before explicit user confirmation.
• Refresh expired OAuth tokens using saved secrets and the x-client-id value.

Required setup

• App-only bearer token secret: xBearerToken (user scope); host approval for api.x.com.
• OAuth access token secret: xAccessToken and refresh token secret: xRefreshToken.
• OAuth client id user value: x-client-id (used by refresh-oauth-token).
• API base URL: https://api.x.com (paths under /2/...).

Exports

• ./ — package overview and OpenAPI slug discovery metadata.
• ./smoke-test — one bearer GET (users/by/username); HTTP 429 counts as auth-plumbing-verified.
• ./request — generic X API v2 helper with bearer or OAuth auth.
• ./refresh-oauth-token — refresh and persist OAuth token secrets.
• ./get-me — authenticated OAuth user profile.
• ./get-user-by-username — public user lookup by username.
• ./search-recent — search recent public posts (shaped tweet fields + rate-limit headers).
• ./get-user-tweets — recent tweets for a user id (shaped).
• ./create-tweet — create or dry-run a post (confirm: true to publish).
• ./delete-tweet — delete or dry-run deletion (confirm: true).
• ./like-tweet, ./unlike-tweet, ./repost-tweet, ./unrepost-tweet — guarded tweet actions.
• ./bookmark-tweet, ./remove-bookmark — guarded bookmark actions.
• ./follow-user, ./unfollow-user — guarded follow actions.
• ./media-upload-guide — static guidance for media upload routes + OAuth storage notes.

Example

import getUserByUsername from 'kody:@kentcdodds/x/get-user-by-username'
import createTweet from 'kody:@kentcdodds/x/create-tweet'

const user = await getUserByUsername({ username: 'kentcdodds' })
const draft = await createTweet({ text: 'Hello from Kody', dryRun: true })

Write helpers return a dry-run payload unless confirm: true is provided after explicit user approval. Prefer a single read when smoking the free tier; treat HTTP 429 as success for auth plumbing.