Collection of Sync components for SPHERE.IO entities.

npm install sphere-node-sync
33 downloads in the last day
166 downloads in the last week
569 downloads in the last month


Node.js Sync

Build Status NPM version Coverage Status Dependency Status devDependency Status

Collection of Sync components for SPHERE.IO entities

Table of Contents

Getting Started

Install the module with: npm install sphere-node-sync

sync = require 'sphere-node-sync'

# or require one of the Sync components
{ProductSync} = require 'sphere-node-sync'
{OrderSync} = require 'sphere-node-sync'
{InventorySync} = require 'sphere-node-sync'


The module exposes many collection Sync objects, resource-specific, and it's used to build update actions for that resource. Available resources are:

  • products - ProductSync
  • orders - OrderSync
  • inventory - InventorySync

All Sync objects share the same implementation, only the mapping of the actions update is resource-specific. I will assume from now on (for the sake of simplicity) that the Sync is either an instance of one of the resources listed above.


It's recommended to use the Sync together with the sphere-node-client module and work with promises.

A Sync instance has an internal instance _client of the SphereClient. You can use that instead of creating a new instance.

sync = new Sync({})
sync._client ...

The credentials are optional, if you don't pass them the SphereClient won't be instantiated.

Error handling

Please refer to the SphereClient documentation.


Following methods are accessible from the object.


Pass a list of actions groups in order to restrict the actions that will be built

options = [
  {type: 'base', group: 'black'}
  {type: 'prices', group: 'white'}
  {type: 'variants', group: 'black'}
# => this will exclude 'base' and 'variants' mapping of actions and include the rest (white group is actually implicit if not given)

sync.config(options).buildActions ...

An empty list means all actions are built


There is basically one main method buildActions which expects 2 valid JSON objects, here is the signature:

buildActions = (new_obj, old_obj) ->
  # ...

The method returns a reference to the current object Sync, so that you can chain it with optional methods get and update.

The important data (actions, etc) is stored in a variable of the Sync class and accessible with _data.


You can pass a custom function to filter built actions and internally update the actions payload.

This function should be called after the actions are built

sync = new ProductSync {...}
sync.buildActions(new_obj, old_obj).filterActions (a) -> a is 'changeName'
# => actions payload will now contain only 'changeName' action

The method returns a reference to the current object Sync, so that you can chain it with optional methods get and update.


It's a wrapper of the _data object and returns one of its values given a key. Available keys:

_data =
  update: {...} # the update actions object, undefined if there is no update
  updateId: '...' # the id of the product to be updated

# example
sync.get() # return _data.update
sync.get('updateId') # return _data.updateId

# or chain it
sync.buildActions(new_obj, old_obj).get()


You can chain this after you built your actions. This will return a Q Promise. It will use internally the id of the old_obj passed in the buildActions to update the related resource.

It will throw an Error if no credentials were given to the Sync object.

sync.buildActions(new_obj, old_obj).update()
.then (result) -> # {statusCode: 200, body: {}}

Update actions groups

Based on the instantiated resource sync (product, order, ...) there are groups of actions used for updates defined below.

Groups gives you the ability to configure the sync to include / exclude them when the actions are built. This concept can be expressed in terms of blacklisting and whitelisting


  • base (name, slug, description)
  • references (taxCategory, categories)
  • prices
  • attributes
  • images
  • variants
  • metaAttributes


  • status (orderState, paymentState, shipmentState)
  • returnInfo (returnInfo, shipmentState / paymentState of ReturnInfo)
  • deliveries (delivery, parcel)


  • quantity
  • expectedDelivery


In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.


Releasing a new version is completely automated using the Grunt task grunt release.

grunt release // patch release
grunt release:minor // minor release
grunt release:major // major release


We <3 CoffeeScript! So please have a look at this referenced coffeescript styleguide when doing changes to the code.


Copyright (c) 2013 Nicola Molinari Licensed under the MIT license.

npm loves you