ts-twitter-provider

A typed wrapper around the Twitter V2 API

Package is in development and API is subject to change.

---

Getting started

This package is installed via npm or yarn

# npm
npm install --save ts-twitter-provider

# yarn
yarn add ts-twitter-provider

From there you can import the main class, TwitterProvider, and related types.

import { TwitterProvider, Tweet } from "ts-twtter-provider";

// Instantiate a TwitterProvider using API key values from the environment or other configuration location
const provider = new TwitterProvider({
    consumer_key: process.env.CONSUMER_KEY!,
    consumer_secret: process.env.CONSUMER_SECRET!,
});

// Somewhere in an async function...
const response = await provider.listTweetsByUser({
    id: "953649053631434752",
});

const tweets: Tweet[] = response.data;

Full documentation can be found on the GitHub Pages site for this repo.

Features

Automatic expansions when required

This package adds an additional 'safe-guard' for interacting with the Twitter V2 endpoints and their parameters. For example, when requesting MediaFields values such as height, preview_image_url, etc., you would normally need to pass TweetExpansions.AttachmentsMediaKeys to expand the media object. By preprocessing the params that you request, each request that requires a specific expansions value to be passed along will be automatically added if not provided.

const response = await provider.getTweet({
    id,
    expansions: undefined, // <-- Despite not specifying TweetExpansions.AttachmentMediaKeys, it will be added to the request
    mediaFields: [MediaFields.Height, MediaFields.Type, MediaFields.Width],
});

Additional utility functions

There are certain endpoints that consumers might benefit from that do not exist in the Twitter V2 API. For example, there is no single endpoint to retrieve tweets from a specific user by their username. By wrapping up API calls to users/by/username/:username and users/:id/tweets, we can easily expose a function that does this work for you - supply a username, get that user's tweets!

// Somewhere in an async function...
const { data: tweets } = await provider.listTweetsByUsername({
    username: "TwitterDev",
});

Supported API

Below is a table of the currently supported API endpoints and methods available from the TwitterProvider. If you don't see a method/endpoint implemented yet, please check the open issues or open a new one.

Click to expand table

Endpoint	Method	Params
/2/tweets	listTweets	✅ expansions ✅ ids ✅ media.fields ✅ place.fields ✅ poll.fields ✅ tweet.fields ✅ user.fields
/2/tweets/:id	getTweet	✅ expansions ✅ media.fields ✅ place.fields ✅ poll.fields ✅ tweet.fields ✅ user.fields
/2/users/:id/tweets	listTweetsByUser	✅ end_time ✅ exclude ✅ expansions ✅ max_results ✅ media.fields ✅ pagination_token ✅ place.fields ✅ poll.fields ✅ since_id ✅ start_time ✅ tweet.fields ✅ until_id ✅ user.fields
/2/users/:id/mentions	listMentionsByUser	✅ end_time ✅ exclude ✅ expansions ✅ max_results ✅ media.fields ✅ pagination_token ✅ place.fields ✅ poll.fields ✅ since_id ✅ start_time ✅ tweet.fields ✅ until_id ✅ user.fields
/2/users	listUsers	✅ expansions ✅ ids ✅ tweet.fields ✅ user.fields
/2/users/:id	getUser	✅ expansions ✅ tweet.fields ✅ user.fields
/2/users/by	listUsersByUsername	✅ expansions ✅ tweet.fields ✅ user.fields ✅ usernames
/2/users/by/username/:username	getUserByUsername	✅ expansions ✅ tweet.fields ✅ user.fields