Naturally Pacifist Marsupials

    ts-twitter-provider
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.0 • Public • Published

    ts-twitter-provider

    v2 build status codecov code style: prettier TypeScript

    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

    Install

    npm i ts-twitter-provider

    DownloadsWeekly Downloads

    13

    Version

    0.8.0

    License

    Apache-2.0

    Unpacked Size

    221 kB

    Total Files

    119

    Last publish

    Collaborators

    • brandongregoryscott