Twitter API TypeScript SDK

For endpoints that support pagination (e.g., usersIdFollowers), you can either iterate over the pages using a for await...of loop to get all results, or await the call directly to get a single page of results.

// Iterate through all pages
const followers = client.users.usersIdFollowers("20");
for await (const page of followers) {
  console.log(page.data);
}

// Or get just the first page
const followersPage = await client.users.usersIdFollowers("20");
console.log(followersPage.data);

Install the SDK using npm to begin using the Twitter API V2 in your TypeScript or JavaScript projects. Note that this SDK requires Node.js 14+ and does not work in browser environments because the Twitter API does not support CORS.

npm install twitter-api-sdk

For App-only authentication, initialize the Client by passing your Bearer Token directly to the constructor.

import { Client } from "twitter-api-sdk";

const client = new Client("MY-BEARER-TOKEN");

To run the provided examples, navigate to the examples directory and follow these steps:

1. Install dependencies: Run npm install to install the required packages.
2. Configure environment variables: Create a .env file in the examples directory. Populate it with the necessary credentials. Note that different examples require different variables (e.g., oauth2-bearer.ts only requires BEARER_TOKEN).
3. Execute examples: Use ts-node to run specific TypeScript files.

Required environment variables for the .env file:

• BEARER_TOKEN
• CLIENT_ID
• CLIENT_SECRET

# 1. Install dependencies
npm install

# 2. Create .env file with required variables
echo "BEARER_TOKEN=my-bearer-token" > .env
echo "CLIENT_ID=my-client-id" >> .env
echo "CLIENT_SECRET=my-client-secret" >> .env

# 3. Run a specific example
npx ts-node oauth2-bearer.ts

The SDK uses TwitterPaginatedResponse<T> to handle endpoints that return paginated data. This type extends AsyncIterable<T>, allowing you to iterate over pages of results using for await...of loops. The generic type T must extend TwitterNextToken, which contains the meta.next_token required for subsequent requests.

// Example of how a paginated response is consumed
for await (const page of paginatedResponse) {
  console.log(page.data);
  console.log(page.meta?.next_token);
}

Use the client.tweets.findTweetById method to retrieve a specific tweet's data.

import { Client } from "twitter-api-sdk";

const client = new Client(process.env.BEARER_TOKEN);

async function main() {
  const tweet = await client.tweets.findTweetById("20");
  console.log(tweet.data.text);
}

main();

Endpoints that return a stream (like sampleStream) return an AsyncGenerator. You can iterate over the stream using a for await...of loop to process incoming data in real-time.

import { Client } from "twitter-api-sdk";

const client = new Client(process.env.BEARER_TOKEN);

async function main() {
  const stream = client.tweets.sampleStream({
    "tweet.fields": ["author_id"],
  });
  for await (const tweet of stream) {
    console.log(tweet.data?.author_id);
  }
}

main();

To make authenticated requests using the SDK's rest utility, call getAuthHeader(). This method is intelligent: it checks if the current access token is expired and automatically calls refreshAccessToken() if necessary before returning the Authorization: Bearer <token> header.

const headers = await oauth2.getAuthHeader();
// headers = { Authorization: 'Bearer ...' }

Use generateAuthURL to create the URL you redirect users to for granting permissions. You must provide a state string to prevent CSRF attacks.

Supported methods:

1. s256: Uses PKCE with SHA-256. The client automatically generates a code_verifier and code_challenge internally.
2. plain: Uses PKCE with a plain code_challenge provided by you.

// Using S256 (Recommended)
const url = oauth2.generateAuthURL({
  state: 'random_state_string',
  code_challenge_method: 's256'
});

// Using plain
const url = oauth2.generateAuthURL({
  state: 'random_state_string',
  code_challenge: 'my_secret_challenge',
  code_challenge_method: 'plain'
});

If you have a refresh_token, you can call refreshAccessToken() to obtain a new access_token without user intervention. The client will automatically update its internal token state.

if (oauth2.isAccessTokenExpired()) {
  await oauth2.refreshAccessToken();
}