# twitter

> Twitter API client library for node.js

Latest version **1.7.1** (published 2017-06-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install twitter
pnpm add twitter
yarn add twitter
bun add twitter
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.7.1 |
| Published | 2017-06-13 |
| First published | 2011-01-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/twitter) |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1258 |
| Author | Desmond Morris |
| Maintainers | reconbot, desmondmorris |
| Keywords | twitter, streaming, oauth |

## Links

- npm: https://www.npmjs.com/package/twitter
- Repository: https://github.com/desmondmorris/node-twitter
- Issues: https://github.com/desmondmorris/node-twitter/issues
- npm.io page: https://npm.io/package/twitter

## Dependencies (2)

- [request](https://npm.io/package/request.md) ^2.72.0
- [deep-extend](https://npm.io/package/deep-extend.md) ^0.5.0

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 1.7.1 (latest) — 2017-06-13
- 1.7.0 — 2016-12-11
- 1.6.0 — 2016-12-11
- 1.5.0 — 2016-12-02
- 1.4.0 — 2016-08-03
- 1.3.0 — 2016-05-14
- 1.2.5 — 2015-03-16
- 1.2.4 — 2015-03-12
- 1.2.3 — 2015-03-07
- 1.2.2 — 2015-03-07
- 1.2.1 — 2015-01-25
- 1.2.0 — 2015-01-25
- 1.1.0 — 2015-01-24
- 1.0.3 — 2015-01-16
- 1.0.2 — 2015-01-08
- … 25 more at https://npm.io/package/twitter/versions

## README

# Twitter for Node.js

An asynchronous client library for the Twitter [REST](https://dev.twitter.com/rest/public) and [Streaming](https://dev.twitter.com/streaming/overview) API's.

[![Build Status](https://travis-ci.org/desmondmorris/node-twitter.svg?branch=master)](https://travis-ci.org/desmondmorris/node-twitter)
 [![NPM](https://nodei.co/npm/twitter.png?mini=true)](https://nodei.co/npm/twitter/)

```javascript
var Twitter = require('twitter');

var client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: ''
});

var params = {screen_name: 'nodejs'};
client.get('statuses/user_timeline', params, function(error, tweets, response) {
  if (!error) {
    console.log(tweets);
  }
});
```

## Installation

`npm install twitter`

## Quick Start

You will need valid Twitter developer credentials in the form of a set of consumer and access tokens/keys.  You can get these [here](https://apps.twitter.com/).  Do not forgot to adjust your permissions - most POST request require write permissions.

```javascript
var Twitter = require('twitter');
```

## For User based authentication:

```javascript
var client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: ''
});
```

Add your credentials accordingly.  I would use environment variables to keep your private info safe.  So something like:

```javascript
var client = new Twitter({
  consumer_key: process.env.TWITTER_CONSUMER_KEY,
  consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
  access_token_key: process.env.TWITTER_ACCESS_TOKEN_KEY,
  access_token_secret: process.env.TWITTER_ACCESS_TOKEN_SECRET
});
```
## For Application Only based authentication:

You will need to fetch a bearer token from Twitter as documented [Here](https://dev.twitter.com/oauth/application-only), once you have it you can use it as follows.

```javascript
var client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  bearer_token: ''
});
```

Add your credentials accordingly.  I would use environment variables to keep your private info safe.  So something like:

```javascript
var client = new Twitter({
  consumer_key: process.env.TWITTER_CONSUMER_KEY,
  consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
  bearer_token: process.env.TWITTER_BEARER_TOKEN
});
```

NB - You will not have access to all endpoints whilst using Application Only authentication, but you will have access to higher API limits.

## Requests

You now have the ability to make GET and POST requests against the API via the convenience methods.

```javascript
client.get(path, params, callback);
client.post(path, params, callback);
client.stream(path, params, callback);
```

## REST API

You simply need to pass the endpoint and parameters to one of convenience methods.  Take a look at the [documentation site](https://dev.twitter.com/rest/public) to reference available endpoints.

Example, lets get a [list of favorites](https://dev.twitter.com/rest/reference/get/favorites/list):

```javascript
client.get('favorites/list', function(error, tweets, response) {
  if(error) throw error;
  console.log(tweets);  // The favorites.
  console.log(response);  // Raw response object.
});
```

How about an example that passes parameters?  Let's  [tweet something](https://dev.twitter.com/rest/reference/post/statuses/update):

```javascript
client.post('statuses/update', {status: 'I Love Twitter'},  function(error, tweet, response) {
  if(error) throw error;
  console.log(tweet);  // Tweet body.
  console.log(response);  // Raw response object.
});
```

### Promises

The REST API convenience methods will also return Promises if:

1.  A callback is omitted
2.  Promise's are available.

If those two conditions are met, the above example becomes:

```javascript
client.post('statuses/update', {status: 'I Love Twitter'})
  .then(function (tweet) {
    console.log(tweet);
  })
  .catch(function (error) {
    throw error;
  })
```

Note, the raw `response` object returned by the Request module is not passed through
the fulfilled promise.  If you require this, please use the callback pattern.

## Streaming API

Using the `stream` convenience method, you to open and manipulate data via a stream piped directly from one of the streaming API's. Let's see who is talking about javascript:

```javascript
var stream = client.stream('statuses/filter', {track: 'javascript'});
stream.on('data', function(event) {
  console.log(event && event.text);
});

stream.on('error', function(error) {
  throw error;
});

// You can also get the stream in a callback if you prefer.
client.stream('statuses/filter', {track: 'javascript'}, function(stream) {
  stream.on('data', function(event) {
    console.log(event && event.text);
  });

  stream.on('error', function(error) {
    throw error;
  });
});
```

**Note** twitter stream several types of events, see [the docs](https://dev.twitter.com/streaming/overview/messages-types) for more info. There is no canonical way of detecting tweets versus other messages, but some users have had success with the following strategy.

```javascript
_ = require('lodash')
const isTweet = _.conforms({
  contributors: _.isObject,
  id_str: _.isString,
  text: _.isString,
})
```

## Examples

* [Tweet](https://github.com/desmondmorris/node-twitter/tree/master/examples#tweet)
* [Search](https://github.com/desmondmorris/node-twitter/tree/master/examples#search)
* [Streams](https://github.com/desmondmorris/node-twitter/tree/master/examples#streams)
* [Proxy](https://github.com/desmondmorris/node-twitter/tree/master/examples#proxy)
* [Media](https://github.com/desmondmorris/node-twitter/tree/master/examples#media)
* [Chunked Media](https://github.com/desmondmorris/node-twitter/tree/master/examples#chunked-media)

## Contributors

Originally authored by  [@technoweenie](http://github.com/technoweenie)
 and maintained by [@jdub](http://github.com/jdub)

Currently maintained by [@desmondmorris](http://github.com/desmondmorris)

[And we cannot forget the community](https://github.com/desmondmorris/node-twitter/graphs/contributors)

---
_Source: https://npm.io/package/twitter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._