Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    pajaropublic

    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/>.

    install

    npm i pajaro

    Downloadsweekly downloads

    4

    version

    1.0.0

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar