ecomplus-sdk-js

JS library for E-Com Plus storefront with methods to access public resources from Store API, Graphs API and Search API.

This library implements only GET requests to public resources, so there aren't authentication.

You can include minified script from URL:

https://ecom.nyc3.digitaloceanspaces.com/plus/js/sdk.min.js

<script src="https://ecom.nyc3.digitaloceanspaces.com/plus/js/sdk.min.js"></script>

Or install npm package:

npm install --save ecomplus-sdk-js

Getting Started

The library declares an object called EcomIo, with methods (object properties) to read public resources from the APIs.

Callback

All the methods are functions with callback as his first argument, it's the function that you should pass to treat the request response. callback function must have two arguments:

| Name | Type | Description | | :---: | :---: | :---: | | err | Null or Object | Error Object | | body | Object | Response body object (JSON parsed) |

Initialize

init(StoreId, Logger)

Before you call the other methods you need to initialize the library with the store ID.

The Logger argument is not required, but you can pass a Console object, with properties log and error, if you want to save output on file.

Arguments

| Name | Type | | :---: | :---: | | StoreId | Number | | Logger | Console object |

Example

EcomIo.init(100)

Methods

The object returned from almost all methods is the response body of Store API endpoints, so if you want to see more examples, you should access the API documentation.

getProduct(callback, id)

It is a method to get a product by the ID.

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | id | String |

Example

EcomIo.getProduct(callback, '123a5432109876543210cdef')

Return

Example of returned body object:

{
  "_id": "123a5432109876543210cdef",
  "store_id": 100,
  "sku": "s-MP_2B4",
  "name": "Mens Pique Polo Shirt",
  "keywords": [
    "tshirt",
    "t-shirt",
    "man"
  ],
  "price": 42.9,
  "base_price": 60,
  "quantity": 100,
  "dimensions": {
    "width": {
      "value": 10,
      "unit": "cm"
    },
    "height": {
      "value": 8,
      "unit": "cm"
    },
    "length": {
      "value": 8,
      "unit": "cm"
    }
  },
  "weight": {
    "value": 400,
    "unit": "g"
  },
  "brands": [
    {
      "_id": "a10000000000000000000001",
      "name": "Shirts Example",
      "slug": "shirts-example",
      "logo": {
        "url": "https://mycdn.com/shirts-example.jpg",
        "size": "100x50"
      }
    }
  ],
  "categories": [
    {
      "_id": "f10000000000000000000001",
      "name": "Polo Shirts",
      "slug": "polo"
    }
  ]
}

getProductBySku(callback, sku)

Similar to getProduct but here you pass the product SKU instead of ID.

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | sku | String |

Example

EcomIo.getProductBySku(callback, 'COD1')

Return

Different from the store API, in that case the return is the same of getProduct.

getOrder(callback, id)

It is a method to get order by the ID.

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | id | String |

Example

EcomIo.getOrder(callback, 'fe1000000000000000000005')

getBrands(callback, filter)

It is a method to list store brands. The filter argument is a URL query string, it is not required but you can use for filtering and pagination purposes.

| Filter | Type | Usage | | :---: | :---: | :---: | | offset | number | Max number of objects to return | | limit | number | First entry to return | | sort | string | Rules to order resultant objects | | fields | string | Object properties to return |

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | filter | String |

Example

With no filter:

EcomIo.getBrands(callback)

With limit filter:

EcomIo.getBrands(callback, 'limit=40')

getCategories(callback, filter)

Similar to getBrands but here the returned body is the list of store categories.

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | filter | String |

Example

With no filter:

EcomIo.getCategories(callback)

With limit and offset:

EcomIo.getCategories(callback, 'limit=20&offset=10')

searchProduts(callback, term, sort, filter)

This method calls E-Com Plus Search API, that proxy pass all requests to Elasticsearch Search APIs with XGET method (read only). Responses are the same as returned from Eslasticsearch REST API, so you can read their documentation to get more info and examples.

You must follow Request Body Search specifications.

Type mapping reference.

Arguments

| Name | Type | Description | | :---: | :---: | :---: | | callback | Function | Callback function | | term | String | It is the term that you are searching for | | sort | Number or Object | Sort products, default for views | | filter | Object | It is a object to filter results |

Example

Search by term only:

EcomIo.searchProduts(callback, 'tshirt')

Order by sales:

EcomIo.searchProduts(callback, 'tshirt', 1)

Custom order:

EcomIo.searchProduts(callback, 'tshirt', {
  'base_price': 'desc'
})

Custom order and filter:

EcomIo.searchProduts(callback, 'tshirt', {
  'base_price': 'desc'
}, 'specifications' : {
  'color': {
    'rgb': [ '#fff', '#fefefe' ]
  }
})

Term

We use a multi match query because we will query in two fields, the name and the keywords of each product.

Sort

The sort argument is based on sort from Elasticsearch documentation.

The order that the resultant products will be sort is:

1. The available products;
2. Search score;
3. The products with more ad relevance;
4. Sort object.

Sort Object

To make your work easier, we have created three default sort options, by views, price and sales:

| Number | Name | Usage | | :---: | :---: | :---: | | 0 | views | Sort by views, products with more views will appear first | | 1 | sales | Sort by sales, products that sells more will appear first | | 2 | price | Sort by price ascending, products with lowest price will appear first | | 3 | price | Sort by price descending, products with highest price will appear first |

If sort argument is undefined or null, default is to sort by views.

If you don't want to sort by views, sales or prices, you can pass a sort object but you have to follow the Elasticsearch documentation.

Example of sort object

sort = {
  'sales' : 'desc'
}

Filter

The filter argument is based on post filter from Elasticsearch documentation.

First we use a filter that shows only visible products. Second, we use the filter argument that you pass, if defined. So if you want to filter by brands, categories or any other property, you have to pass a filter object.

Example of filter object

filter = {
  'specifications': {
    'color': {
      'rgb': ['#fff', '#fefefe']
    },
    'size': {
      'value': ['G']
    }
  },
  'brands': {
    'name': ['brandName']
  },
  'categories': {
    'name': ['categoryName']
  }
}

getRecommendedProducts(callback, id)

Returns up to 12 recommended products, selecting the products that was more times bought together with the reference product. You should use it to do something like "who bought it, bought too".

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | id | String |

Example

EcomIo.getRecommendedProducts(callback, 'a00000000000000000000000')

getRelatedProducts(callback, id)

Returns up to 12 related products, selecting the products that have more categories in common with the reference product. You should use it to do something like "you can also be interested by".

Arguments

| Name | Type | | :---: | :---: | | callback | Function | | id | String |

Example

EcomIo.getRelatedProducts(callback, 'a00000000000000000000000')