pajaro

means 'bird' in spanish

JSTP bindings for the Twitter API, including OAuth flow. pajaro allows you to easily consume both the REST and Streaming APIs with a neat JSTP interface.

As a freebie, pajaro optimizes the amount of streams opened from Twitter. Twitter has a somewhat strict policy regarding opened streaming connections and the amount of API calls per minute; pajaro makes an intelligent configuration of the opened connections so that there are as little connections as possible. You're welcome.

Installation

npm install pajaro

Usage

This package contains several modules. The rationale behind pajaro is that many distributed applications should be able to make use of the same client to maximize efficiency. The Client module of pajaro interacts with the REST and Streaming APIs of Twitter, and is intended to "just run". The other module, Consumer, deals with the OAuth flow but in the application side and needs some configuration to run.

OAuth flow

Since pajaro is JSTP, the Client can be runned standalone or in the same application as the Consumer. I will demonstrate both setups.

In order to work, the application needs a client-side component: at least a button for the user to click and be redirected to Twitter, and some way to send to the Client the OAuth Token and OAuth Token Verifier returned by Twitter in the query string of the redirection to the callback URL. This is achieved with an HTTP Server and a JSTP client library: in the samples below I'm using express because it is quite popular and easy to setup for this examples, but any server that relies on node-http can be used. You can find the JSTP client library from the official repo. The usage is very much alike the usage of the Node.js library.

Separated pajaro Client

You can find this example in test/consumer/oauth-separated. Clone this repo to try it. Run npm install in the repo folder after cloning. You will have to setup the config.json with your application's data (the access tokens are optional for the OAuth flow examples, they are used in the test/client samples).

In the separated setup, a host should be configured like this:

// client.js
var pajaro = require('pajaro');
var jstp   = require('jstp');

pajaro.Client(jstp);

jstp.listen({
  tcp: 33333
});

The http server/consumer application. We'll be using express for the webserver (note: this is just pseudocode since the full setup requires static files and what not, please download the tests to try it):

// consumer.js
var express     = require('express');
var app         = express();
var jstp        = require('jstp');
var http        = require('http');
var mustache    = require('mustache');
var fs          = require('fs');

var config      = {
  "app": {
    "token": "YOUR_TWITTER_APPLICATION_CONSUMER_TOKEN",
    "secret": "YOUR_TWITTER_APPLICATION_CONSUMER_SECRET",
    "callback": "YOUR_TWITTER_APPLICATION_CALLBACK_URL"
  }
}

var pajaro      = require('pajaro');

// The pajaro Consumer setup
pajaro.Consumer.setup(
  jstp,                           // The JSTP Object
  config.app,                     // The Twitter App configuration
  [['localhost', 33333, 'tcp']]   // The Host header data of the `Client
);

app.configure(function () {
  app.use(express.bodyParser());
  app.use(express.cookieParser());
  app.use(express.logger('dev'));
  app.use(express.static(__dirname + "/public"));
});

app.get('/', function (req, res) {
  res.redirect('/index.html');
});

app.get('/index.html', function (req, res) {
  fs.readFile('index.html', function (err, content) {
    if (err) throw err;
    res.send(mustache.render(content.toString(), { token: config.app.token }));
  });
});

app.get('/twitter', function (req, res) {
  pajaro.Consumer.processCallback(
    req.query.oauth_token, 
    req.query.oauth_verifier, function (accessToken, accessSecret) {
    // HERE'S WHERE THE MAGIC HAPPENS
    console.log("token: "   + accessToken); 
    console.log("secret: "  + accessSecret); 
  });
  res.redirect('/index.html');
});

server = http.createServer(app);

jstp.listen({
  websocket: server
});

server.listen(8000, function () {
  console.log("Express server listening on port 8000");
});

Start the client.js first (node test/consumer/oauth-separated/client.js). You will see something like this:

BIND BIND Twitter/*/*/*/* {}
BIND RELEASE Twitter/*/*/*/* {}
BIND BIND Twitter/*/RequestToken/* {}
BIND BIND Twitter/*/AccessToken/* {}

This is the JSTP notifying the BIND dispatches that pajaro.Client issues. Now start the server.js (node test/consumer/oauth-separated/server.js). You will see something like this:

BIND BIND Twitter/YOUR_TWITTER_APP_CONSUMER_TOKEN/RequestToken {}
BIND RELEASE Twitter/YOUR_TWITTER_APP_CONSUMER_TOKEN/RequestToken {}
Express server listening on port 8000

This script binds itself specifically to the App's consumer token.

Finally, open a browser to http://localhost:8000/ and click the button. Accept the application in Twitter and afterwards you should be able to see:

token: ACCESS_TOKEN
secret: ACCESS_SECRET

in the server.js output.

Integrated

You can find this example in test/consumer/oauth-integrated. Clone this repo to try it. Run npm install in the repo folder after cloning. You will have to setup the config.json with your application's data (the access tokens are optional for the OAuth flow examples, they are used in the test/client samples).

The integrated form initializes both the pajaro.Client and the pajaro.Consumer in the same server. The setup is mostly alike that of the server.js in the separated form, except for the pajaro initialization:

pajaro.Client(jstp); // The client is initialized with the JSTP object

pajaro.Consumer.setup( // There is no host information, because the client resides
                       // in the same host as the Customer
  jstp, 
  config.app
);

Run it with node test/customer/oauth-integrated/server.js.

API

pajaro supports several endpoints for both the REST and Streaming APIs. In fact, pajaro makes consuming any of those APIs seamless. A complete usage guideline is pending, but you can learn a lot from the pajaro.Client tests.

Endpoints

This section should be clarified with code.

Streaming:

Twitter/:apptoken/:viewerid/:user/:track

Relationship graph (friends):

Twitter/:apptoken/:viewerid/following/*
Twitter/:apptoken/:viewerid/followers/*

Mentions:

BIND POST Twitter/:apptoken/:viewerid/mentions/*

RequestToken

Twitter/:apptoken/RequestToken

AccessToken

Twitter/:apptoken/AccessToken

License

Copyright © 2013 SouthLogics

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.