BlueBirdie 🐦

A lightweight wrapper for the Twitter API

---

BlueBirdie is very new and still in it's experimental phase. Especially with the streaming. Until the 1.0 release, this library is highly likely to change. All parts of BlueBirdie are under construction.

BlueBirdie is yet another NodeJS interface for the Twitter API. Why did I make it? Because the other 3 libraries I found were not being maintained and I felt I could actually keep up with this one. With the upcoming Version 2 of the Twitter API, I wanted to be sure that a library can support that, as well as the painful way developers have to interact with Twitters Version 1 API. Why should you use this?

• A clear abstraction between the Application and User Authentication Types
• Support for Version 1 endpoints.
• Support for Version 2 endpoints.
• Nice abstraction of the OAuth authentication requirements.
• Easy to use Streaming API.

Download & Installation

$ yarn add bluebirdie

Application Example

const twitter = new BlueBirdie({
  apiKey: 'api_key',
  apiSecretKey: 'api_secret_key',
  bearerToken: 'bearer_token',
});

twitter.app
  .get('/1.1/statuses/lookup.json', {
    params: {
      id: ['1278747501642657792', '1255542774432063488'],
    },
  })
  .then(data => console.log({ resultOne: data }));

twitter.app
  .get('/2/tweets', {
    params: {
      ids: ['1278747501642657792', '1255542774432063488'], // Edit Tweet IDs to look up
      'tweet.fields': ['lang', 'author_id'], // Edit optional query parameters here
      'user.fields': 'created_at', // Edit optional query parameters here
    },
  })
  .then(data => console.log({ resultTwo: data }));

User Example

const twitter = new BlueBirdie({
  apiKey: 'api_key',
  apiSecretKey: 'api_secret_key',,
  accessToken: 'access_token',
  accessTokenSecret: 'access_token_secret'
})

twitter.user.postForm("/1.1/statuses/update.json", { status: 'testing 12345' })
  .then(results => {
    console.log("results", results);
  })
  .catch(err => console.log({ err }))

twitter.user.post('/1.1/direct_messages/events/new.json',
  {
    event: {
      type: 'message_create',
      message_create: {
        target: { recipient_id: '123456' },
        message_data: { text: 'Hello World!' }
      }
    }
  })
  .then(results => {
    console.log('results', results);
  })
  .catch(err => console.log({ err }))

twitter.user.get('/1.1/statuses/lookup.json', {
  params: {
    id: ["1278747501642657792", "1255542774432063488"],
  }
}).then(data => console.log({ resultOne: data }));

twitter.user.get('/2/tweets', {
  params: {
    "ids": ["1278747501642657792", "1255542774432063488"], // Edit Tweet IDs to look up
    "tweet.fields": ["lang", "author_id"], // Edit optional query parameters here
    "user.fields": "created_at" // Edit optional query parameters here
  }
}).then(data => console.log({ resultTwo: data }));

Streaming Examples

Twitters API v2 supports streaming for Applications and User Contexts. The version 1 API only allows streaming from the User Context.

Version 2

const rules = [
  {
    value: 'dog has:images -is:retweet',
    tag: 'dog pictures',
  },
  {
    value: 'cat has:images -grumpy',
    tag: 'cat pictures',
  },
];

await twitter.app.post('/2/tweets/search/stream/rules', { add: rules });

// This can be twitter.user or twitter.app
const stream = await twitter.app.getStream('/2/tweets/search/stream');
stream
  .on('data', data => {
    console.log({ yay: data });
  })
  .on('error', err => {
    console.log(err);
  });

Version 1

// Currently, there is a manual baseURL override, since version 1 api is on a different domain. If the bluebird client instance is only going to be used for version 1 stream, the domain can be set in the config.
await stream = twitter.user.postStream(
  '/1.1/statuses/filter.json',
  { track: 'jojo' },
  { baseURL: 'https://stream.twitter.com' }
);

stream
  .on('data', data => {
    console.log({ yay: data });
  })
  .on('error', err => {
    console.log(err);
  });

Upcoming Examples

• Requesting Bearer Tokens and Access Tokens
• Full User OAuth Flow Example
• More Streaming Examples (streaming API is under heavy construction)

Upcoming for BlueBirdie

• Lots of test writing
• Better Exmaples
• I am also brainstorming some ideas for easy abstractions on common use cases that would other be reimplemented in each project

Contributing

Contributors are always welcome! I would love new ideas and thoughts. I have a specific direction I am wanting this project to go in.

License

This project is licensed under the MIT License