Naturally Processed Meals

    birdwatch

    4.2.3 • Public • Published

    Birdwatch logo

    Build Status Coverage Status

    Birdwatch helps you fetch, filter, sort, cache and serve specific tweets from specific twitter accounts, thus avoiding any request limits set by the Twitter API, and giving you more control over the data that is served to your applications or websites. Use the built-in server to get you up and running quickly, or switch the server off and use the cache file anyway you like.

    If you find any bugs, or have suggestions please report them. If you want to help, pull requests are always appreciated!

    Installation

    Step 1: Install the package via npm

    $ npm install --save birdwatch
    

    Step 2: Add your Twitter App Credentials via environment variables

    There are a number of ways to set environment variables in your app, some depend on your operating system. I use dotenv, but you can use the command line, a makefile or npm. No matter what method you choose, your environment variables should have the following names:

    • CONSUMER_KEY : Your Twitter Consumer Key
    • CONSUMER_SECRET : Your Twitter Consumer Secret
    • ACCESS_TOKEN : Your Twitter Access Token
    • ACCESS_TOKEN_SECRET : Your Twitter Access Token Secret

    Now you're ready to birdwatch! :bowtie:

    Usage

    var Birdwatch = require('birdwatch');
     
    new Birdwatch()
        .feed('justinbieber')
        .feed('taylorswift13', {filterTags:['tagOne', 'tagTwo']})
        .start()
        .then(tweets => {
            console.log('birdwatch is ready to serve %s tweets', tweets.length);
        });

    By default, Birdwatch will launch a server on port 8417 for you, but you can change the port number using the port option. After running the code above, you can access your tweets at the default location:

    http://localhost:8417/birdwatch/tweets
    

    Cached HTML Tweet

    If birdwatch can't find an html string on the returned tweet data, (which is sometimes the default from the Twitter API), then one will be rebuilt and added for you via tweet-patch. This means that plaintext hashtags, user-mentions and hyperlinks are converted back into twitter-ready html for you (you're welcome). 😍

    const tweet = cached_tweets[0];
     
    tweet.text;
    //=> "This is the #plaintext tweet"
     
    tweet.html;
    //=> "This is the <a href="https://twitter.com/hashtag/plaintext">#plaintext</a> tweet"

    Built-in Server

    Birdwatch comes equipped with its own built-in server. You don't have to configure the server at all, it will launch just fine using the defaults, but in case you need more control, you can configure the server by the following:

    Tip: The cache file is created even if the server is turned off, this means you can use Birdwatch with your own caching server: just turn the Birdwatch server off, and use the cache file however you want.

    Note: As of v4.0.4, birdwatch sets defaults for CORS middleware, to see the default settings, see the source code. In the future, you will be able to customize these settings PR's welcome!.

    API

    Birdwatch([options])

    options

    Type: object

    Options set here will override the defaults in the constructor.

    logReports

    Type: boolean
    Default: true

    Pretty-print birdwatch activity to the console.

    birdwatch

    refreshTime

    Type: Number
    Default: 600

    The number of seconds to wait before the cache updates again. The default is 10 minutes (600 seconds)

    Tip: Update your cache frequently, but not frequently enough to hit any Twitter API Rate Limits.

    tweetPatchOptions

    Type: object
    Default: {stripTrailingUrl: true, hrefProps: 'target="_blank"'}

    The tweet-patch options you want to pass to Birdwatch. This will affect how the final html property on the returned/cached tweets will be processed. By default, Birdwatch removes the trailing url that Twitter adds to the end of the text property when media was attached to the tweet. Since the media url can't render in a text-based tweet, Birdwatch removes the unneeded trailing url.

    server

    Type: boolean
    Default: true

    Boolean to turn the server off or on. Turn the server off if you want to run your own server. Your own server can do whatever it wants with the cache file in birdwatch/dist/cache/

    port

    Type: number
    Default: 8417

    Assign a port to the Birdwatch server. If you set a port of 0 the server will assign an open port for you, and you can get the port number with the logReport: true setting or using birdwatch.options.port. Note that setting the port to 0 (zero) will assign any open port.

    url

    Type: string
    Default: /birdwatch/tweets

    The url you want to use to access the cached tweets. Requires the server to be running.

    cacheDir

    Type: string
    Default: ${__dirname}/cache/

    Override the location of the cache file. Make sure you have appropriate read/write permissions on this directory.

    testData

    Type: json

    Serve tweet data in JSON format to birdwatch. Useful for testing/debugging without making network requests.

    sortBy

    Type: function
    Default: tweet => { return new Date(tweet.created_at) * -1; }

    Override the custom sorting function. Birdwatch defaults sorting to chronological order.

    balancedScreennames

    Type: boolean
    Default: false

    If this is set to true then a special sorting of the tweets will occur, which will balance the tweets by the unique screen_name values. This will spread the usernames apart evenly so that the distribution of tweets seems balanced. For example, suppose you have tweets authored by three people, and they are returned from the Twitter API in this order:

    USER01
    USER01
    USER02
    USER02
    USER03
    USER03
    

    setting this option to true will shuffle the tweets in a balanced order:

    USER01
    USER02
    USER03
    USER01
    USER02
    USER03
    

    ⚠️ Important to note that this option can NOT be used in combination with the sortBy option.

    birdwatch.feed(screenname, [options])

    Add a twitter feed.

    screenname

    Required
    Type: string

    The screenname of the twitter account you want to watch.

    options

    Type: object

    Feed options.

    filterTags

    Type: Regex|Array

    The regular expression containing the tags you want to filter with, or an array of strings. For example, all of these examples will result in the same filter:

    .feed('user1', {filterTags: /#01|#02/gi })
    .feed('user2', {filterTags: ['01','02'] })
    .feed('user3', {filterTags: ['#01','#02'] })

    Tip: If you need help writing your regular expressions, try regexpal.com

    limit

    Type: number
    Default: 12

    Set a limit on how many tweets you want to cache from the feed. If you are watching three feeds with a limit of 10, you will have a cache of 30 tweets.

    removeRetweets

    Type: boolean
    Default: false

    Use this if you want to remove retweets from the feed you are watching.

    birdwatch.feedsFromList(listName, listOwner)

    Automatically process feeds from individual members from a Twitter list

    listName

    Required
    Type: string

    The name of the list you want to extract members from

    listOwner

    Required
    Type: string

    The owner's screenname of the Twitter list you want to extract members from

    Example

    new Birdwatch(settings)
        .feed('taylorswift13')
        .feedsFromList('birdwatch-allstars', 'birdwatchnpm')
        .feedsFromList('unhcr-twitter-stars', 'GisellaLomax')
        .start()
        .then(tweets => {
            console.log('\nbirdwatch is ready to serve %s tweets', tweets.length);
            tweets.forEach(tweet => {
                console.log('text', tweet.text);
                console.log('html', tweet.html);
                console.log('\n\n');
            });
        }).catch(err => {
            console.log(err);
        });

    birdwatch.start()

    Start the Birdwatch process.

    License

    MIT @ Michael Wuergler

    Install

    npm i birdwatch

    DownloadsWeekly Downloads

    3

    Version

    4.2.3

    License

    MIT

    Unpacked Size

    38.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • radiovisual