twitter-api-v2: a strongly typed Twitter/X API v1.1 and v2 client for Node.js, published on npm as twitter-api-v2.
src/: library code.v1/,v2/,v2-labs/,ads/,ads-sandbox/hold the API clients,paginators/the paginators,stream/the streaming client,types/the API types.test/: mocha + chai tests, in TypeScript. The ones that call the real X API are intest/live/.doc/: user documentation. Update it when public behaviour changes.changelog.md: written byrelease.mjsduring a release, don't edit it in feature work.
npm run lint,npm run buildandnpm testmust pass. CI runs them on Node 22, 24 and 26, on pushes to master and on pull requests.npm testruns the tests oftest/, offline and without credentials. Run a single file withnpm run mocha test/<name>.test.ts.- Test new behaviour offline.
test/fake-x.tsis a fake X API: its clients keep callinghttps://api.x.com/..., but their requests go to a local server that records them, checks OAuth 1.0a signatures like X does, and answers with the replies set withon(). Narrower fakes are fine too, like a fakeinstance.getfor paginators or a fake response stream forTweetStream. - The tests of
test/live/call the real X API and some calls are billed: ask before running them. They needCONSUMER_TOKEN,CONSUMER_SECRET,OAUTH_TOKENandOAUTH_SECRET(in.env) and throw at import without them. Run them withnpm run test:live, or with the Live tests workflow on GitHub, which uses the repository secrets.
- Short commit subjects, conventional prefixes welcome:
fix(stream): …,feat: …,docs: …. - The changelog lists merged pull requests only. Commits pushed directly to master (CI, tooling, chores) are left out of it.
Creating a GitHub release makes .github/workflows/publish.yml publish the package to npm, with trusted publishing and provenance (no npm token involved). release.mjs does the rest and needs an authenticated gh CLI:
node release.mjs <patch|minor|major> --dry-runshows the next version and its changelog entries. There is one entry per commit since the latest tag that belongs to a merged pull request, formatted as- <subject> #<pr> (@<author>). Use patch for fixes, minor for new features or new API fields, and major for breaking changes.node release.mjs <patch|minor|major>first checks that master is clean and in sync with origin, then runs lint and build. It bumpspackage.jsonandpackage-lock.json, prepends the entries tochangelog.md, and commitsupgrade to <version>.node release.mjs --publishpushes master and creates the<version>release (tag, title and notes from the changelog), which starts the npm publish. It then commentsShipped in <version>on every released pull request and on the issues they close.node release.mjs patch --publishdoes steps 2 and 3 in one go.
Then follow the publish with gh run list --workflow publish.yml and check npm view twitter-api-v2 version. Also look for open issues that the release fixes without being linked to a pull request. Comment on those by hand, explaining the fix.
- X documents v2 pagination tokens as opaque, but they are base36-encoded text. For tweet timelines,
previous_tokendecodes toPREV_TOKEN<newest_id>andnext_tokentoNEXT_TOKEN<oldest_id>, so they act likesince_id/until_idand can be replayed. Searchnext_tokens decode to{"maxId":<oldest_id>}.