node-twitter-api-v2

twitter-api-v2 is a TypeScript client that wraps the Twitter/X v1.1, v2, v2-labs, and Ads REST APIs behind one strongly typed interface. It handles OAuth 1.0a three-legged auth and OAuth2 (Bearer and PKCE user-context) flows internally, so consumers don’t need a separate auth library, and it ships with zero runtime dependencies, keeping the installed footprint small.

Beyond raw request/response wrapping, the library adds real-time streaming via a TweetStream class with reconnection handling, cursor-based paginator classes for tweets/users/DMs/lists/followers, and chunked media-upload helpers. Read and write access are separated at the type level through TwitterApiReadOnly and TwitterApiReadWrite subclasses, so misusing a read-only token to attempt a write fails a type check before it ever reaches the network.

What You Get

• Typed request/response wrappers for essentially every documented v1.1 and v2 REST endpoint, plus the Ads and v2-labs APIs
• TwitterApi, TwitterApiReadOnly, and TwitterApiReadWrite classes that encode read/write scope at the type level
• Built-in OAuth1 (three-legged) and OAuth2 (Bearer + PKCE user-context) authentication helpers
• TweetStream-based real-time consumption of the filtered/sampled stream endpoints, including reconnection handling
• Cursor/paginator classes that walk paginated tweet, user, DM, list, and follower responses
• Media upload helpers (v1.uploadMedia) supporting chunked upload for images, video, and GIFs
• Rate-limit tracking utilities and a plugin system (ITwitterApiClientPlugin) for cross-cutting concerns

Common Use Cases

• Server-side Twitter/X bots that post, reply, and DM using OAuth1 app-only or three-legged tokens
• Real-time monitoring tools that consume the filtered/sampled stream and react to matching tweets
• “Sign in with X” OAuth2 user-authorization flows in web apps
• Analytics/backfill scripts that page through a user’s or search query’s full tweet history
• Media-heavy publishing tools that upload images/video/GIFs before attaching them to tweets

Under The Hood

Architecture The client is built from a base TwitterApiBase class (src/client.base.ts) that owns a single ClientRequestMaker and exposes get/post/put/patch/delete/getStream/postStream primitives; version-specific surfaces (TwitterApiv1, TwitterApiv2, TwitterAds, v2-labs) are thin subclients layered on top via client.subclient.ts, each exposed lazily as a getter on the top-level TwitterApi class (src/client/index.ts) so .v1/.v2/.ads instances are created on first access and reused after. Read/write access is separated by class inheritance (TwitterApiReadOnly -> TwitterApiReadWrite -> TwitterApi) rather than runtime checks, so the type system - not a guard clause - prevents write calls through a read-only-typed client. Request construction, retries, rate-limit bookkeeping, and streaming are isolated in client-mixins/ (request-maker.mixin.ts, request-handler.helper.ts, oauth1/oauth2 helpers), keeping the version-specific client files focused purely on endpoint mapping.

Tech Stack Written entirely in TypeScript with zero runtime dependencies - HTTP requests are made directly against Node’s built-in https module (client-mixins/request-handler.helper.ts) rather than through axios or node-fetch, and OAuth1 request signing is implemented by hand using Node’s crypto module rather than an external OAuth library. The package builds twice via tsc -b against separate tsconfig.cjs.json/tsconfig.esm.json project files to ship both CommonJS and ESM output, and API reference docs are generated from source via typedoc. Tests run on mocha/chai through ts-node, and dotenv loads live Twitter credentials for integration-style tests.

Code Quality The codebase is fully typed with a dedicated types/ directory covering v1, v2, auth, and error shapes, and ESLint (@typescript-eslint/recommended plus custom rules) plus a GitHub Actions CI workflow enforce style and catch regressions on push. Most of the test suite under test/ calls the real Twitter API and requires live credentials, and a number of tests are marked .skip by default (they need an active developer account and app-level tokens to run), so coverage in CI is narrower than the file count suggests, but the tests that do run exercise auth, streaming, pagination, and media upload against real responses rather than mocks.

API Design The public surface favors ergonomics: overloaded get/post signatures return either bare data or a full response object depending on a fullResponse flag, semantic accessors (.readOnly, .readWrite, .v1, .v2) make the available scope obvious at a call site, and twelve dedicated markdown guides under doc/ (auth, streaming, pagination, rate-limiting, plugins, examples) supplement generated API docs. The zero-dependency, ~23kb-gzipped install size is called out explicitly as a design goal relative to comparable clients.