facebook-complete

This is a complete port of the facebook sdk from authentication to multi part form posting. Based on the work of criso found here: https://raw.github.com/criso/fbgraph/master/lib/graph.js

Stay Classy, Facebook

Facebook Complete is a nodejs module that provides easy access to the facebook graph api

I created this because I wanted to access FB's graph from node. The libraries I found, felt clunky to me, and I needed an excuse to create a node module.

All calls will return json. Facebook sometimes (on friend requests, deleting test users, access token request) decides to just return a string or true or redirects directly to the image. I say nay-nay! Let's make it Disney, and keep things consistent!

$ npm install facebook-complete

var graph = require('facebook-complete');

If you get an accesstoken via some other Oauth module like everyauth , connect-auth or node-oauth you can just set the access token directly. Most get calls, and pretty much all post calls will require an access_token

    graph.setAccessToken(access_token);
    // pass it in as part of the url  
    graph.post(userId + "/feed?access_token=007", wallPost, function(errres) {
        // returns the post id 
        console.log(res); // { id: xxxxx} 
    });
 

This is how you would get authenticated using only the facebook-complete module. More details below on the express app section

    // get authorization url 
    var authUrl = graph.getOauthUrl({
        "client_id":     conf.client_id
      , "redirect_uri":  conf.redirect_uri
    });
 
    // shows dialog 
    res.redirect(authUrl);
 
    // after user click, auth `code` will be set 
    // we'll send that and get the access token 
    graph.authorize({
        "client_id":      conf.client_id
      , "redirect_uri":   conf.redirect_uri
      , "client_secret":  conf.client_secret
      , "code":           req.query.code
    }, function (errfacebookRes) {
      res.redirect('/loggedIn');
    });

Facebook recommends adding the appsecret_proof parameter to all API calls to verify that the access tokens are coming from a valid app. You can make this happen automatically by calling graph.setAppSecret(app_secret), which will be used on all calls to generate the appsecret_proof hash that is sent to Facebook. Make sure you also set the access token for the user via graph.setAccessToken.

If you want to extend the expiration time of your short-living access token, you may use extendAccessToken method as it is shown below:

    // extending static access token 
    graph.extendAccessToken({
        "client_id":      conf.client_id
      , "client_secret":  conf.client_secret
    }, function (errfacebookRes) {
       console.log(facebookRes);
    });
 
    // extending specific access token 
    graph.extendAccessToken({
        "access_token":    client_access_token
      , "client_id":      conf.client_id
      , "client_secret":  conf.client_secret
    }, function (errfacebookRes) {
       console.log(facebookRes);
    });
 
 

All calls are made using the request nodejs module Why? something to do with wheels and re-invention.

Request options are directly mapped and can be set like so:

var options = {
    timeout:  3000
  , pool:     { maxSockets:  Infinity }
  , headers:  { connection:  "keep-alive" }
};
 
graph
  .setOptions(options)
  .get("zuck", function(errres) {
    console.log(res); // { id: '4', name: 'Mark Zuckerberg'... } 
  });

Possible options can be found on the request github page

followRedirect cannot be overriden and has a default value of false encoding will have utf-8 as default if nothing is set

Pagination in Facebook is done either with a cursor or a next url to call. To simplify the facebook-complete API, it's possible to use a fully constructed URL in order to get the next page. See the following example:

// note: you might want to prevent the callback hell :) 
graph.get('likes', {limit: 2, access_token: "foobar"}, function(errres) {
  if(res.paging && res.paging.next) {
    graph.get(res.paging.next, function(errres) {
      // page 2 
    });
  }
});
graph.get("zuck", function(errres) {
  console.log(res); // { id: '4', name: 'Mark Zuckerberg'... } 
});

params in the url

graph.get("zuck?fields=picture", function(errres) {
  console.log(res); // { picture: 'http://profile.ak.fbcdn.net/'... } 
});

params as an object

var params = { fields: "picture" };
 
graph.get("zuck", params,  function(errres) {
  console.log(res); // { picture: "http://profile.ak.fbcdn.net/..." } 
});

GraphApi calls that redirect directly to an image will return a json response with relevant fields

graph.get("/zuck/picture", function(errres) {
  console.log(res); // { image: true, location: "http://profile.ak.fb..." } 
});

Search for public posts that contain brogramming

var searchOptions = {
    q:     "brogramming"
  , type:  "post"
};
 
graph.search(searchOptions, function(errres) {
  console.log(res); // {data: [{id: xxx, from: ...}, {id: xxx, from: ...}]} 
});

All publish requests will require an access token

only needs to be set once

graph.setAccessToken(accessToken);

Post a message on a friend's wall

var wallPost = {
  message: "I'm gonna come at you like a spider monkey, chip!"
};
 
graph.post(userId + "/feed", wallPost, function(errres) {
  // returns the post id 
  console.log(res); // { id: xxxxx} 
});

Post/edit an event to a managed page, or a person's wall

  var event = {
    name : event title/name (required)
    start_time: ISO-8601 formatted date NOTE:Past events cannot be edited. (required)
    description : "An awesome event description" (required and html will be stripped automatically)
    ticket_uri: http://www.someticketurl.com (optional) 
    picture: http://someimageurl (optional, if not supplied we pass this off to the graph.post method ) 
    location: 1234 Main St. Kansas City, MO. 64105 (optional if location_id is provided)
    end_time:(optional) event end time ISO-8601 formatted date and time. 
    edit: true (optional) if you are updating an event instead of creating a new one set this to true otherwise leave it out of the postData
    postId: string containing the facebook id of the event to edit. (required if edit is true otherwise leave out of postData)
}
var url="/me/events"; //alternatively this could be something like /{page_id}/events 
graph.postEvent(url,event,function(err,response){
  //returns event id if succesfull 
  console.log(reponse.id);
});
 
 

To delete a graph object, provide an object id and the response will return {data: true} or {data:false}

graph.del(postID, function(errres) {
  console.log(res); // {data:true}/{data:false} 
});

A single FQL query is done by sending a query as a string

var query = "SELECT name FROM user WHERE uid = me()";
 
graph.fql(query, function(errres) {
  console.log(res); // { data: [ { name: 'Ricky Bobby' } ] } 
});

FQL Multi-Queries are done by sending in an object containing the separate queries

var query = {
    name:         "SELECT name FROM user WHERE uid = me()"
  , permissions:  "SELECT email, user_about_me, user_birthday FROM permissions WHERE uid = me()"
};
 
graph.fql(query, function(errres) {
  console.log(res);
  // { data: [ 
  //   { name: 'name', fql_result_set: [{name: 'Ricky Bobby'}] }, 
  //   { name: 'permissions', fql_result_set: [{email: 1, user_about_me: 1...}] } 
  // ]} 
});

This example assumes that you have a link on the main page / that points to /auth/facebook. The user will click this link and get into the facebook authorization flow ( if the user hasn't already connected) After authorizing the app the user will be redirected to /UserHasLoggedIn

/**
 * Module dependencies.
 */
 
var express   = require('express')
  , graph     = require('facebook-complete')
  , app       = module.exports = express.createServer();
 
// this should really be in a config file! 
var conf = {
    client_id:      'YOUR FACEBOOK APP ID'
  , client_secret:  'YOU FACEBOOK APP SECRET'
  , scope:          'email, user_about_me, user_birthday, user_location, publish_stream'
  , redirect_uri:   'http://localhost:3000/auth/facebook'
};
 
// Configuration 
 
app.configure(function(){
  app.set('views', __dirname + '/views');
  app.set('view engine', 'jade');
  app.use(express.bodyParser());
  app.use(express.methodOverride());
  app.use(app.router);
  app.use(express.static(__dirname + '/public'));
});
 
app.configure('development', function(){
  app.use(express.errorHandler({ dumpExceptions: true, showStack: true }));
});
 
app.configure('production', function(){
  app.use(express.errorHandler());
});
 
// Routes 
 
app.get('/', function(reqres){
  res.render("index", { title: "click link to connect" });
});
 
app.get('/auth/facebook', function(reqres) {
 
  // we don't have a code yet 
  // so we'll redirect to the oauth dialog 
  if (!req.query.code) {
    var authUrl = graph.getOauthUrl({
        "client_id":     conf.client_id
      , "redirect_uri":  conf.redirect_uri
      , "scope":         conf.scope
    });
 
    if (!req.query.error) { //checks whether a user denied the app facebook login/permissions 
      res.redirect(authUrl);
    } else {  //req.query.error == 'access_denied' 
      res.send('access denied');
    }
    return;
  }
 
  // code is set 
  // we'll send that and get the access token 
  graph.authorize({
      "client_id":      conf.client_id
    , "redirect_uri":   conf.redirect_uri
    , "client_secret":  conf.client_secret
    , "code":           req.query.code
  }, function (errfacebookRes) {
    res.redirect('/UserHasLoggedIn');
  });
 
 
});
 
 
// user gets sent here after being authorized 
app.get('/UserHasLoggedIn', function(reqres) {
  res.render("index", { title: "Logged In" });
});
 
 
var port = process.env.PORT || 3000;
app.listen(port, function() {
  console.log("Express server listening on port %d", port);
});
 

Before running the test suite, add your Facebook appId and appSecret to tests/config.js This is needed to create test users and to get a test access_token

$ npm install
$ make test

Tests might fail if the Facebook api has an issue.

(The MIT License)

Copyright (c) 2013 Robert Fines <fines.robert@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.