/node-twitter-api-v2

Strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js.

Primary LanguageTypeScriptApache License 2.0Apache-2.0

Twitter API v2

Twitter API v2 badge Twitter API v1.1 badge Version badge Checks badge Package size badge

Strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js.

Main maintainer: @alkihis - Buy Me A Coffee

Highlights

Ready for v2 and good ol' v1.1 Twitter API

Light: No dependencies, 23kb minified+gzipped

Bundled types for request parameters and responses

Streaming support

Pagination utils

User-context authentication with OAuth2

Media upload helpers

How to use

Install it through your favorite package manager:

yarn add twitter-api-v2
# or
npm i twitter-api-v2

Here's a quick example of usage:

import { TwitterApi } from 'twitter-api-v2';

// Instantiate with desired auth type (here's Bearer v2 auth)
const twitterClient = new TwitterApi('<YOUR_APP_USER_TOKEN>');

// Tell typescript it's a readonly app
const readOnlyClient = twitterClient.readOnly;

// Play with the built in methods
const user = await readOnlyClient.v2.userByUsername('plhery');
await twitterClient.v1.tweet('Hello, this is a test.');
// You can upload media easily!
await twitterClient.v1.uploadMedia('./big-buck-bunny.mp4');

Why?

Sometimes, you just want to quickly bootstrap an application using the Twitter API. Even though there are a lot of libraries available on the JavaScript ecosystem, they usually just provide wrappers around HTTP methods, and some of them are bloated with many dependencies.

twitter-api-v2 is meant to provide full endpoint wrapping, from method name to response data, using descriptive typings for read/write/DMs rights, request parameters and response payload.

A small feature comparison with other libs:

Package API version(s) Response typings Media helpers Pagination Subdeps Size (gzip) Install size
twitter-api-v2 v1.1, v2, labs 0 ~23 kB twitter-api-v2 install size badge
twit v1.1 51 ~214.5 kB twit install size badge
twitter v1.1 50 ~182.1 kB twitter install size badge
twitter-lite v1.1, v2 4 ~5.3 kB twitter-lite install size badge
twitter-v2 v2 7 ~4.5 kB twitter-v2 install size badge

Features

Here's everything twitter-api-v2 can do:

Basics:

  • Support for v1.1 and v2 of Twitter API
  • Make signed HTTP requests to Twitter with every auth type: OAuth 1.0a, OAuth2 (even brand new user context OAuth2!) and Basic HTTP Authorization
  • Helpers for numerous HTTP request methods (GET, POST, PUT, DELETE and PATCH), that handle query string parse & format, automatic body formatting and more
  • High-class support for stream endpoints, with easy data consumption and auto-reconnect on stream errors

Request helpers:

  • Automatic paginator for endpoints like user and tweet timelines, allowing payload consumption with modern asynchronous iterators until your rate-limit is hit
  • Convenient methods for authentication - generate auth links and ask for tokens to your users
  • Media upload with API v1.1, including long video & subtitles support, automatic media type detection, chunked upload and support for concurrent uploads
  • Dedicated methods that wraps API v1.1 & v2 endpoints, with typed arguments and fully typed responses
  • Typed errors, meaningful error messages, error enumerations for both v1.1 and v2

Type-safe first:

  • Typings for tweet, user, media entities (and more) are bundled!
  • Type-safe wrapping of dedicated methods in 3 right level: DM/Read-write/Read-only (just like Twitter API do!) - you can declare a read-only client - you will only see the methods associated with read-only endpoints

And last but not least, fully powered by native Promises.

Documentation

Learn how to use the full potential of twitter-api-v2.

Plugins

Official plugins for twitter-api-v2:

See how to use plugins here.