{"id":22691110,"url":"https://github.com/radiovisual/birdwatch","last_synced_at":"2025-04-12T22:54:13.145Z","repository":{"id":35737092,"uuid":"40015832","full_name":"radiovisual/birdwatch","owner":"radiovisual","description":"Monitor, filter, cache and serve raw tweets from one or more specific twitter feeds.","archived":false,"fork":false,"pushed_at":"2018-07-29T23:02:01.000Z","size":746,"stargazers_count":11,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T22:54:06.925Z","etag":null,"topics":["cache","filter","server","tweets","twitter","twitter-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radiovisual.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-31T17:05:33.000Z","updated_at":"2025-01-25T23:07:35.000Z","dependencies_parsed_at":"2022-08-18T06:29:02.495Z","dependency_job_id":null,"html_url":"https://github.com/radiovisual/birdwatch","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiovisual%2Fbirdwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiovisual%2Fbirdwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiovisual%2Fbirdwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiovisual%2Fbirdwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radiovisual","download_url":"https://codeload.github.com/radiovisual/birdwatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643045,"owners_count":21138353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","filter","server","tweets","twitter","twitter-api"],"created_at":"2024-12-10T01:09:26.815Z","updated_at":"2025-04-12T22:54:13.112Z","avatar_url":"https://github.com/radiovisual.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Birdwatch logo](media/birdwatch-logo.png)\n\n[![Build Status](https://travis-ci.org/radiovisual/birdwatch.svg?branch=master)](https://travis-ci.org/radiovisual/birdwatch)\n[![Coverage Status](https://coveralls.io/repos/github/radiovisual/birdwatch/badge.svg?branch=master)](https://coveralls.io/github/radiovisual/birdwatch?branch=master)\n\nBirdwatch helps you fetch, filter, sort, cache and serve specific tweets from specific twitter accounts, thus avoiding any request\nlimits set by the Twitter API, and giving you more control over the data that is served to your applications or websites.\n 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.\n\nIf you find any bugs, or have suggestions [please report them](https://github.com/radiovisual/birdwatch/issues). If you want to help, pull requests are always appreciated! \n\n\n## Installation\n\n**Step 1:** Install the package via npm\n```\n$ npm install --save birdwatch\n```\n\n**Step 2:** Add your Twitter App Credentials via environment variables\n\nThere are a number of ways to set environment variables in your app, some depend on your operating system. I use [dotenv](https://github.com/motdotla/dotenv), but you can use\nthe command line, a makefile or npm. No matter what method you choose, your environment variables should have the following names:\n\n- `CONSUMER_KEY` : Your Twitter Consumer Key\n- `CONSUMER_SECRET` : Your Twitter Consumer Secret\n- `ACCESS_TOKEN` : Your Twitter Access Token\n- `ACCESS_TOKEN_SECRET` : Your Twitter Access Token Secret\n\n*Now you're ready to birdwatch!* :bowtie: \n\n\n## Usage\n\n```js\nvar Birdwatch = require('birdwatch');\n\nnew Birdwatch()\n    .feed('justinbieber')\n    .feed('taylorswift13', {filterTags:['tagOne', 'tagTwo']})\n    .start()\n    .then(tweets =\u003e {\n        console.log('birdwatch is ready to serve %s tweets', tweets.length);\n    });\n```\n\nBy 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:\n\n```\nhttp://localhost:8417/birdwatch/tweets\n```\n\n### Cached HTML Tweet\nIf 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](https://github.com/radiovisual/tweet-patch). This means that **_plaintext_** hashtags, user-mentions and hyperlinks are converted back into twitter-ready html for you (you're welcome). :heart_eyes:\n   \n```js\nconst tweet = cached_tweets[0];\n\ntweet.text;\n//=\u003e \"This is the #plaintext tweet\"\n\ntweet.html;\n//=\u003e \"This is the \u003ca href=\"https://twitter.com/hashtag/plaintext\"\u003e#plaintext\u003c/a\u003e tweet\"\n```\n\n### Built-in Server\n\nBirdwatch 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: \n\n- [Turning it on or off](https://github.com/radiovisual/birdwatch#server) using the `server: \u003ctrue|false\u003e` option \n- [Overriding the url to the Birdwatch cache](https://github.com/radiovisual/birdwatch#cacheDir) with the `cacheDir: \u003cpath\u003e` option\n- [Specifying the port](https://github.com/radiovisual/birdwatch#port) you want the server to run on with the `port: \u003cportnumber\u003e` option\n- [Optionally serving test data](https://github.com/radiovisual/birdwatch#testData) in a JSON format using the `testData: \u003cjson\u003e` option\n\n**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. \n\n**Note:** As of `v4.0.4`, birdwatch sets defaults for CORS middleware, to see the default settings, see [the source code](https://github.com/radiovisual/birdwatch/blob/master/lib/utils.js#L20-L30). In the future, you will be [able to customize these settings](https://github.com/radiovisual/birdwatch/issues/28) *PR's welcome!*.\n\n\n## API\n\n### Birdwatch([options])\n\n#### options\n\nType: `object`  \n\nOptions set here will override the defaults in the constructor.\n\n##### logReports\n\nType: `boolean`  \nDefault: `true`\n\nPretty-print birdwatch activity to the console.\n\n# ![birdwatch](media/screenshot-v.3.1.2.png)\n\n##### refreshTime\n\nType: `Number`  \nDefault: `600`  \n\nThe number of seconds to wait before the cache updates again. The default is 10 minutes (600 seconds)\n \n**Tip:** Update your cache frequently, but not frequently enough to hit any [Twitter API Rate Limits](https://dev.twitter.com/rest/public/rate-limits).\n\n##### tweetPatchOptions\n\nType: `object`\u003cbr\u003e\nDefault: `{stripTrailingUrl: true, hrefProps: 'target=\"_blank\"'}`\n\nThe [tweet-patch](https://github.com/radiovisual/tweet-patch) options you want to pass to Birdwatch. This will affect how \nthe final `html` property on the returned/cached tweets will be processed. By default, Birdwatch removes the trailing url that\nTwitter adds to the end of the `text` property when media was attached to the tweet. Since the media url can't render in a \ntext-based tweet, Birdwatch removes the unneeded trailing url.\n\n##### server\n\nType: `boolean`  \nDefault: `true`  \n\nBoolean 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/`\n\n##### port\n\nType: `number`  \nDefault: `8417`  \n\nAssign 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 \nget the port number with the `logReport: true` setting or using `birdwatch.options.port`. Note that setting the port to `0` (zero)\nwill assign any open port.\n\n##### url\n\nType: `string`  \nDefault: `/birdwatch/tweets`\n\nThe url you want to use to access the cached tweets. Requires the server to be running.\n\n##### cacheDir\n\nType: `string`  \nDefault: `${__dirname}/cache/`  \n\nOverride the location of the cache file. Make sure you have appropriate read/write permissions on this directory.\n\n##### testData\n\nType: `json`  \n\nServe tweet data in JSON format to birdwatch. Useful for testing/debugging without making network requests.\n\n##### sortBy\n\nType: `function`  \nDefault: `tweet =\u003e { return new Date(tweet.created_at) * -1; }`    \n\nOverride the custom sorting function. Birdwatch defaults sorting to chronological order.\n\n##### balancedScreennames\n\nType: `boolean`  \nDefault: `false`    \n\nIf this is set to `true` then a special sorting of the tweets will occur, which will balance the \ntweets by the unique `screen_name` values. This will spread the usernames apart evenly so that the \ndistribution of tweets seems balanced. For example, suppose you have tweets authored by three people, \nand they are returned from the Twitter API in this order:\n\n```\nUSER01\nUSER01\nUSER02\nUSER02\nUSER03\nUSER03\n```\n\nsetting this option to `true` will shuffle the tweets in a balanced order:\n\n```\nUSER01\nUSER02\nUSER03\nUSER01\nUSER02\nUSER03\n```\n\n:warning: **Important to note** that this option can NOT be used in combination with the `sortBy` option.\n\n### birdwatch.feed(screenname, [options])\n\nAdd a twitter feed.\n\n#### screenname\n\n*Required*  \nType: `string`  \n\nThe screenname of the twitter account you want to watch.\n\n#### options\n\nType: `object`  \n\nFeed options.\n\n##### filterTags\n  \nType: `Regex|Array`  \n  \nThe 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:\n\n```js\n.feed('user1', {filterTags: /#01|#02/gi })\n.feed('user2', {filterTags: ['01','02'] })\n.feed('user3', {filterTags: ['#01','#02'] })\n```\n**Tip:** If you need help writing your regular expressions, try [regexpal.com](http://regexpal.com/)\n\n##### limit\n  \nType: `number`  \nDefault: `12`  \n  \nSet 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.\n   \n##### removeRetweets\n  \nType: `boolean`  \nDefault: `false`  \n\nUse this if you want to remove retweets from the feed you are watching.\n\n### birdwatch.feedsFromList(listName, listOwner)\n\nAutomatically process feeds from individual members from a Twitter list\n\n#### listName\n\n*Required*  \nType: `string`  \n\nThe name of the list you want to extract members from\n\n#### listOwner\n\n*Required*  \nType: `string`  \n\nThe owner's screenname of the Twitter list you want to extract members from\n\n#### Example\n\n```js\nnew Birdwatch(settings)\n\t.feed('taylorswift13')\n\t.feedsFromList('birdwatch-allstars', 'birdwatchnpm')\n\t.feedsFromList('unhcr-twitter-stars', 'GisellaLomax')\n\t.start()\n\t.then(tweets =\u003e {\n\t\tconsole.log('\\nbirdwatch is ready to serve %s tweets', tweets.length);\n\t\ttweets.forEach(tweet =\u003e {\n\t\t\tconsole.log('text', tweet.text);\n\t\t\tconsole.log('html', tweet.html);\n\t\t\tconsole.log('\\n\\n');\n\t\t});\n\t}).catch(err =\u003e {\n\t\tconsole.log(err);\n\t});\n```\n### birdwatch.start()\n\nStart the Birdwatch process.\n\n### License\n\nMIT @ [Michael Wuergler](http://numetriclabs.com/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiovisual%2Fbirdwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradiovisual%2Fbirdwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiovisual%2Fbirdwatch/lists"}