lds-platform

Client to consume the LDS.org platform service version 2.0. See Mulesoft docs for more information about the LDS platform service.

Initialization

var platform = require('lds-platform').init(config);

Where config looks like:

{

	"client": "Your-Super-Secret-Client-Id",

	"secret": "Your-Super-Secret-Client-Password",

	"env": "production",

	"cache": 600000,

	"timeout": 5000,

	"lang": "eng"

}

Initialization Configuration

client (required)

Your app's assigned Client Id.

secret (required)

Your app's assigned Client Secret

env (optional)

Which platform endpoint to use. Should be one of: 'production', 'stage', 'test', 'development', or 'local' (wamulated).

default: 'production'

timeout (optional)

The time in seconds (milliseconds) before request is deemed a failure.

default: 5000 (5 seconds)

lang (optional)

The default language when it's not specified on .get().

default: eng

Retrieval

.get(lang)

The parameter lang should a string of the appropriate 3 digit ISO language code.

It returns a Bluebird promise with its contents containing the head, header, footer

platform.get("eng")
	.then(function( data ){
		// do something with `data`
	});

data is an object that looks like:

{
	head: '<link ...>',
	header: '<header class="pf-header" role="banner">...</header>',
	footer: '<footer class="pf-footer">...</footer>'
}

.get(options)

Same results as above, but the options parameter should be of type object that looks something like:

var options = {
	lang:'eng',
	clang:'ase',
	domain:'lds.org',
	'no-scripts': true,
	mode:'published'
};

platform.get(options)
	.then(function( data ){
		// do something with `data`
	});

See the service's documentation on mulesoft for a full list of options.

Event Emitting

.emitter.on('fetch.{lang}', callback)

Emits an event when the platform for lang is grabbed from the endpoint. Does not fire if contents received from cache. Useful if you need to react endpoint calls...

platform.emitter.on('fetch.eng', function(data){
	// data is the platform object for `lang`: 'eng'
});

.emitter.on('fetch', callback)

Emits an event when the platform for any language is grabbed off from the endpoint. Does not fire if contents received from cache. Useful if you only want to react

platform.emitter.on('fetch', function(response){
	console.log(response.lang); // 'eng'
	console.log(response.data); // {} <- platform data for `eng`
});

Node.js / Express Example

// initialize
var platform = require('lds-platform').init( { client:'1337', secret:'633K'} );

// later: assuming `app` is an express app
app.use('/', function(req, res, next) {
	platform.get( req.query.lang )
		.then(function(data){
			res.locals.platform = data;
		})
		.nodeify(next);
});

Contributing

• Clone the repo

• branch off the master branch

• run npm install

• configure the unit tests by adding a credentials file to /test/credentials.json with valid API credentials for stage. The credentials.json file should look like:

  {
  	client: 'supersecretuser',
  	secret: 'supersecretpassword'
  }

• make changes

• add unit tests for your changes

• make sure linting and all unit tests pass by running npm test

• version bump in package.json

• submit pull request back into master

Questions

On the NPM module: Jared Anderson on slack (@j), the twitters (@tuxsudo) or by email too I guess.

On the Platform Service: the LDS.org team in CSP (Steve Hales or Aaron Barker)

Change Log

2.0.0

No longer clear the memcache automatically in preparation for EMX integration. Provide manual cache clearing method. Update production URL for apigateway from www.lds.org. Removed cache time expiration parameter

1.3.1

Hotfix to use www.lds.org vs apigateway...

1.3.0

Added support for timeout parameter

1.2.0

Added support for object parameters on .get for more specific usage. Added linting More better docs More better tests

1.1.0

Added .emitter Object

EMX Integration (coming soon as we figure out how it should work)

EMX currently is notified when the platform changes. LDS.org and Scriptures automatically clear their platform cache when EMX notifies them of the update. We want the same behavior built into all node apps.

Here is an idea of how this will work:

1. EMX will send a notification packet to an endpoint on your app - this work is done manually by notifying the EMX team that you would like to receive notifications for platform updates - Currently Cory Petersen.
2. Your app will send the body of the notification to this module. The module will store this notification for later use.
3. The module will continue to work as expected, clearing the cache for the expired platform caches.