<commit_before>![SPHERE.IO icon](https://admin.sphere.io/assets/images/sphere_logo_rgb_long.png)

# NODE.JS Client

[![Build Status](https://secure.travis-ci.org/sphereio/sphere-node-client.png?branch=master)](http://travis-ci.org/sphereio/sphere-node-client) [![NPM version](https://badge.fury.io/js/sphere-node-client.png)](http://badge.fury.io/js/sphere-node-client) [![Coverage Status](https://coveralls.io/repos/sphereio/sphere-node-client/badge.png?branch=master)](https://coveralls.io/r/sphereio/sphere-node-client?branch=master) [![Dependency Status](https://david-dm.org/sphereio/sphere-node-client.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-node-client) [![devDependency Status](https://david-dm.org/sphereio/sphere-node-client/dev-status.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-node-client#info=devDependencies)

[SPHERE.IO](http://sphere.io/) is the first **Platform-as-a-Service** solution for eCommerce.

This module is a standalone Node.js client for accessing the Sphere HTTP APIs.

## Table of Contents
* [Getting Started](#getting-started)
* [Documentation](#documentation)
  * [Services](#services)
  * [Types of requests](#types-of-requests)
    * [Query request](#query-request)
    * [Create resource](#create-resource)
    * [Update resource](#update-resource)
  * [Error handling](#error-handling)
* [Examples](#examples)
* [Releasing](#releasing)
* [License](#license)


## Getting Started
Install the module with `npm install sphere-node-client`

```javascript
var SphereClient = require('sphere-node-client');
```

## Documentation
To start using the Sphere client you need to create an instance of the `SphereClient` by passing the credentials (and other options) in order to connect with the HTTP APIs. Project credentials can be found in the SPHERE.IO [Merchant Center](https://admin.sphere.io/) under `Developers > API clients` section.

> For a list of options to pass to the client, see [`sphere-node-connect`](https://github.com/emmenko/sphere-node-connect#documentation).

```javascript
var sphere_client = new SphereClient({
  config: {
    client_id: "CLIENT_ID_HERE",
    client_secret: "CLIENT_SECRET_HERE",
    project_key: "PROJECT_KEY_HERE"
  }
})
```

### Services
The `SphereClient` provides a set of Services to connect with the related API endpoints. Currently following services are supported:

- `carts`
- `categories`
- `channels`
- `comments`
- `customObjects`
- `customers`
- `customerGroups`
- `inventories`
- `orders`
- `products`
- `productProjections`
- `productTypes`
- `reviews`
- `shippingMethods`
- `taxCategories`

### Types of requests
Requests to the HTTP API are obviously asynchronous and they all return a [`Q` promise](https://github.com/kriskowal/q).

```javascript
var sphere_client = new SphereClient({...})

sphere_client.products.fetch()
.then(function(result){
  // a JSON object containing either a result or a SPHERE.IO HTTP error
})
.fail(function(error){
  // either the request failed or was rejected (the response returned an error)
})
```

Current methods using promises are:

- `fetch` HTTP `GET` request
- `save` HTTP `POST` request
- `update` HTTP `POST` request (_alias for `save`_)


#### Query request
All resource endpoints support queries, returning a list of results of type [PagedQueryResponse](http://commercetools.de/dev/http-api.html#paged-query-response).

> Fetching and endpoint without specifying and `ID` returns a `PagedQueryResponse`

A query request can be configured with following query parameters:

- `where` ([Predicate](http://commercetools.de/dev/http-api.html#predicates))
- `sort` ([Sort](http://commercetools.de/dev/http-api.html#sorting))
- `limit` (Number)
- `offset` (Number)

The `SphereClient` helps you build those requests with following methods:

- `where(predicate)` defines a URI encoded predicate from the given string (can be set multiple times)
- `whereOperator(operator)` defines the logical operator to combine multiple where parameters
- `sort` _TBD_
- `page(n)` defines the page number to be requested from the complete query result (default is `1`)
- `perPage(n)` defines the number of results to return from a query (default is `100`). If set to `0` all results are returned

> All these methods are chainable

```javascript
// example

var sphere_client = new SphereClient({...})
sphere_client.products
.where('name(en="Foo")')
.where('id="1234567890"')
.whereOperator('or')
.page(3)
.perPage(25)
.fetch()

// HTTP request
// /{project_key}/products?where=name(en%3D%22Foo%22)%20or%20id%3D%221234567890%22&limit=25&offset=50
```

#### Create resource
All endpoints allow a resource to be created by posting a JSON `Representation` of the selected resource as a body payload.


```javascript
var product = {
  'name': {
    'en': 'Foo'
  },
  'slug': {
    'en': 'foo'
  },
  ...
}
sphere_client.products.save(product)
.then(function(result){
  // a JSON object containing either a result or a SPHERE.IO HTTP error
})
.fail(function(error){
  // either the request failed or was rejected (the response returned an error)
})
```

#### Update resource
Updates are just a POST request to the endpoint specified by an `ID`, provided with a body payload of [Update Actions](http://commercetools.de/dev/http-api.html#partial-updates).<commit_msg>Add some doc on sort and staged query params.<commit_after>![SPHERE.IO icon](https://admin.sphere.io/assets/images/sphere_logo_rgb_long.png)

# NODE.JS Client

[![Build Status](https://secure.travis-ci.org/sphereio/sphere-node-client.png?branch=master)](http://travis-ci.org/sphereio/sphere-node-client) [![NPM version](https://badge.fury.io/js/sphere-node-client.png)](http://badge.fury.io/js/sphere-node-client) [![Coverage Status](https://coveralls.io/repos/sphereio/sphere-node-client/badge.png?branch=master)](https://coveralls.io/r/sphereio/sphere-node-client?branch=master) [![Dependency Status](https://david-dm.org/sphereio/sphere-node-client.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-node-client) [![devDependency Status](https://david-dm.org/sphereio/sphere-node-client/dev-status.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-node-client#info=devDependencies)

[SPHERE.IO](http://sphere.io/) is the first **Platform-as-a-Service** solution for eCommerce.

This module is a standalone Node.js client for accessing the Sphere HTTP APIs.

## Table of Contents
* [Getting Started](#getting-started)
* [Documentation](#documentation)
  * [Services](#services)
  * [Types of requests](#types-of-requests)
    * [Query request](#query-request)
    * [Create resource](#create-resource)
    * [Update resource](#update-resource)
  * [Error handling](#error-handling)
* [Examples](#examples)
* [Releasing](#releasing)
* [License](#license)


## Getting Started
Install the module with `npm install sphere-node-client`

```javascript
var SphereClient = require('sphere-node-client');
```

## Documentation
To start using the Sphere client you need to create an instance of the `SphereClient` by passing the credentials (and other options) in order to connect with the HTTP APIs. Project credentials can be found in the SPHERE.IO [Merchant Center](https://admin.sphere.io/) under `Developers > API clients` section.

> For a list of options to pass to the client, see [`sphere-node-connect`](https://github.com/emmenko/sphere-node-connect#documentation).

```javascript
var sphere_client = new SphereClient({
  config: {
    client_id: "CLIENT_ID_HERE",
    client_secret: "CLIENT_SECRET_HERE",
    project_key: "PROJECT_KEY_HERE"
  }
})
```

### Services
The `SphereClient` provides a set of Services to connect with the related API endpoints. Currently following services are supported:

- `carts`
- `categories`
- `channels`
- `comments`
- `customObjects`
- `customers`
- `customerGroups`
- `inventories`
- `orders`
- `products`
- `productProjections`
- `productTypes`
- `reviews`
- `shippingMethods`
- `taxCategories`

### Types of requests
Requests to the HTTP API are obviously asynchronous and they all return a [`Q` promise](https://github.com/kriskowal/q).

```javascript
var sphere_client = new SphereClient({...})

sphere_client.products.fetch()
.then(function(result){
  // a JSON object containing either a result or a SPHERE.IO HTTP error
})
.fail(function(error){
  // either the request failed or was rejected (the response returned an error)
})
```

Current methods using promises are:

- `fetch` HTTP `GET` request
- `save` HTTP `POST` request
- `update` HTTP `POST` request (_alias for `save`_)


#### Query request
All resource endpoints support queries, returning a list of results of type [PagedQueryResponse](http://commercetools.de/dev/http-api.html#paged-query-response).

> Fetching and endpoint without specifying and `ID` returns a `PagedQueryResponse`

A query request can be configured with following query parameters:

- `where` ([Predicate](http://commercetools.de/dev/http-api.html#predicates))
- `sort` ([Sort](http://commercetools.de/dev/http-api.html#sorting))
- `limit` (Number)
- `offset` (Number)

The `SphereClient` helps you build those requests with following methods:

- `where(predicate)` defines a URI encoded predicate from the given string (can be set multiple times)
- `whereOperator(operator)` defines the logical operator to combine multiple where parameters
- `sort` _TBD_
- `page(n)` defines the page number to be requested from the complete query result (default is `1`)
- `perPage(n)` defines the number of results to return from a query (default is `100`). If set to `0` all results are returned

> All these methods are chainable

```javascript
// example

var sphere_client = new SphereClient({...})
sphere_client.products
.where('name(en="Foo")')
.where('id="1234567890"')
.whereOperator('or')
.page(3)
.perPage(25)
.sort('name', false)
.fetch()

// HTTP request
// /{project_key}/products?where=name(en%3D%22Foo%22)%20or%20id%3D%221234567890%22&limit=25&offset=50&sort=name%20desc
```

##### Staged products

The `ProductProjectionService` is by default querying for published products. To query for staged products do:

```javascript
sphere_client.productProjections
.staged()
.fetch()
```

#### Create resource
All endpoints allow a resource to be created by posting a JSON `Representation` of the selected resource as a body payload.


```javascript
var product = {
  'name': {
    'en': 'Foo'
  },
  'slug': {
    'en': 'foo'
  },
  ...
}
sphere_client.products.save(product)
.then(function(result){
  // a JSON object containing either a result or a SPHERE.IO HTTP error
})
.fail(function(error){
  // either the request failed or was rejected (the response returned an error)
})
```

#### Update resource
Updates are just a POST request to the endpoint specified by an `ID`, provided with a body payload of [Update Actions](http://commercetools.de/dev/http-api.html#partial-updates).
{'fraction_non_alphanumeric': 0.14275215873599117, 'fraction_numerical': 0.008634943964725335, 'mean_word_length': 4.965479452054795, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 11, 'https://': 24, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7159387', 'n_tokens_mistral': 3563, 'n_tokens_neox': 3339, 'n_words': 960}