Birdwatch v1

Birdwatch 🐤⌚

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

If you would like to contribute to Birdwatch and help speed up development, pull requests and issues are welcomed

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 [email protected]

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, both of these values will result in the same filter:

.feed('user1', {filterTags: /#01|#02/gi })
.feed('user2', {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

License

MIT @ Michael Wuergler