birdwatch

Birdwatch :baby_chick::watch:

Get and cache raw tweets from one or more specific twitter feeds. Optionally filter the tweets by hashtag!

Birdwatch will help you grab tweets from specific twitter accounts, and cache the tweets on your server, thus avoiding any request limits set by the Twitter API, and giving you more control over the data that is saved. You can filter tweets by hashtags, or ignore retweets!

Note: This is a work in progress. Pull requests welcome!

Installation

Step 1: Install the package via npm

$ npm install --save birdwatch

Step 2: Add your twitter app credentials to the configuration file

1. Open the file node_modules/birdwatch/birdwatch-config.js
2. Update the file with your Twitter App credentials.
3. Rename the file to local-config.js
4. Now you're ready to birdwatch!

Usage

var Birdwatch = require('birdwatch');

var birdwatch = new Birdwatch()
    .feed('gulpjs')
    .feed('reactjs', {filterTags: ['tag1', 'tag2']})
    .feed('nodejs',  {filterTags: /#tag1|#tag2/i, removeRetweets:true})
    .start();

// Now get your tweets in JSON format to serve or print
birdwatch.getCachedTweets();

Extra Features

Cached HTML Tweet

• If birdwatch can't find an html string on the returned tweet data, then it adds one for you using tweet-patch. This means the plain-text hashtags, user-mentions and hyperlinks are converted to twitter-ready HTML. Example below.

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

API

Birdwatch([options])

options

Type: object

Options set here will override the defaults in the constructor.

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.

logReports

Type: Boolean
Default: false

Shows a pretty-printed update to the console. Useful for debugging and logging.

useTestData

Type: boolean
Default: false

Use the test tweet data instead of making a network requests. Useful for testing/debugging.

sortBy

Type: function

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

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

removeRetweets

Type: boolean
Default: false

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

birdwatch.start()

Start the Birdwatch process.

birdwatch.getCachedTweets()

Use this to access the birdwatch cache of tweets in the JSON format

Returns: Array

Notes on Release 1.0

• Birdwatch is now in its 1.0 release, which means some subtle API changes have occurred:
  • .start() and .getCachedTweets() no longer return a Promise.
  • Custom sorting functions can now be passed to the Birdwatch instance.
• Birdwatch saves the filtered and sorted tweets to the hard disk, so you can use the cache file anyway you want, but Birdwatch only uses in-memory cache to serve data. Discussion here.
• Internally, the entire codebase has adopted the ES6 syntax (transpiles with Babel).
• The unit testing framework has migrated from Mocha to AVA.
• Simplified install process.

License

MIT @ Michael Wuergler