Twitter V2 API for Node.js

An asynchronous client library for the Twitter REST and Streaming, with support for making non-streaming requests via a proxy V2 API's.

Try it now

const Twitter = require('twitter-v2-withproxy');

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: '',
  proxy_url: '',
});

const { data } = await client.get('tweets', { ids: '1228393702244134912' });
console.log(data);

Installation

npm install twitter-v2-withproxy

Quick Start

You will need valid Twitter developer credentials in the form of a set of consumer keys. You can get early access V2 keys here.

For user based authentication:

User authentication requires your app's consumer keys and access tokens obtained from oauth 1.0a.

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: '',
});

For app based authentication:

Alternatively, app authentication (which can only access public data but is often suitable for server applications) only needs your app's consumer keys and/or bearer token.

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
});

or

const client = new Twitter({
  bearer_token: '',
});

REST API

You can make GET, POST, and DELETE requests against the REST API via the convenience methods.

client.get(path, urlParams);
client.post(path, body, urlParams);
client.delete(path, urlParams);

The REST API convenience methods return Promises.

Streaming API

Use the streaming convenience methods for any stream APIs. Note that the proxy is not supported here as most proxies will not detect the disconnection and would leave the connection to Twitter open

client.stream(path, urlParams);

The Streaming API will return an async iterator with the convenience method close(). Ensure that you call close() when done with a stream, otherwise it will continue to download content from Twitter in the background.

const stream = client.stream(path, urlParams);

// Close the stream after 30s.
setTimeout(() => {
  stream.close();
}, 30000);

for await (const { data } of stream) {
  console.log(data);
}

Note that reconnect logic is not handled by this package, you're responsible for implementing it based on the needs of your application. The stream will close itself in two cases:

1. If the stream becomes disconnected for an unknown reason, a TwitterError will be thrown.
2. If Twitter's backend disconnects the stream healthily, the stream will be closed with no error.

If you wish to continuously listen to a stream, you'll need to handle both of these cases. For example:

async function listenForever(streamFactory, dataConsumer) {
  try {
    for await (const { data } of streamFactory()) {
      dataConsumer(data);
    }
    // The stream has been closed by Twitter. It is usually safe to reconnect.
    console.log('Stream disconnected healthily. Reconnecting.');
    listenForever(streamFactory, dataConsumer);
  } catch (error) {
    // An error occurred so we reconnect to the stream. Note that we should
    // probably have retry logic here to prevent reconnection after a number of
    // closely timed failures (may indicate a problem that is not downstream).
    console.warn('Stream disconnected with error. Retrying.', error);
    listenForever(streamFactory, dataConsumer);
  }
}

listenForever(
  () => client.stream('tweets/search/stream'),
  (data) => console.log(data)
);

V1.1 API Support

This module does not support previous versions of the Twitter API, however it works well with the following V1.1 modules