README

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.

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);
});

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

Usage no npm install needed!