livefyre-easyxdm

Tools for using easyXDM with Livefyre Hosts (currently only api.livefyre.com). This module is meant to be used in a browser, and built with browserify.

Why?

Because IE9 doesn't support all of CORS, and so sometimes the only way to make the request is via an easyXDM-powered iframe proxy that can make a same-origin request on your behalf and postMessage the results back to you.

Usage

var lfxdm = require('livefyre-easyxdm');
var urlToRequest = 'https://cross-origin.com/api';
// Create an easyXDM RPC object for a url you'd like to request.
var rpc;
try {
  // Reuse same underlying iframe across requests
  rpc = lfxdm.rpc.getOrCreate(urlToRequest);
  // Or, to always make a new iframe on each request
  rpc = lfxdm.rpc.create(urlToRequest);
} catch (e) {
  if (e.name === 'UnknownOriginError') {
    // lfxdm does not know of any iframe proxies for that origin.
    // Try another method?
  }
}

Learn more about easyXDM.Rpc objects in easyXDM's README.

The currently exposed methods on Livefyre iframe proxies:

• The standard 'request' method that ships with easyXDM for CORS. Use this to make AJAX requests.

  var urlToRequest = 'https://api.livefyre.com/app-service/v4/apps/';
  var rpc = require('livefyre-easyxdm').rpc.getOrCreate(urlToRequest);
  rpc.request({
    url: urlToRequest,
    method: 'POST',
    headers: {
      'Authorization': 'lftoken {yourToken}',
      'Content-Type': 'application/json'
    }
  }, function onSuccess(res) {
    // res.headers, res.status, res.data    
  }, function onError(err) { /* ... */ });

Usage with other AJAX Libraries

• superagent-easyxdm can construct a superagent plugin to use rpc.request instead of XMLHttpRequest.

  require('superagent').patch(url)
    .send({ data: 1 })
    .use(require('superagent-easyxdm').rpcRequest(rpc.request))
    .end(function (err, res) {});

Server integration

If you are making a new Livefyre service and want to support this lib.

1. Add a route to your server which responds with require('livefyre-easyxdm/lib/html).cors, which is an HTML String.

   // If you're using express
   express().get('/cors.html', function (req, res, next) {
     res.send(require('livefyre-easyxdm/lib/html').cors);
   });

2. Add your service and route url to the map ./lib/proxy-urls.js module. Consider also writing a test in test.js.

Develop

make

Test

make test - Runs tests in node + jsdom