ecomplus-sdk

1.16.0 • Public • Published

ecomplus-sdk-js

npm version license mit

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.

Include minified script via CDN:

<script src="https://cdn.jsdelivr.net/npm/ecomplus-sdk@1/dist/sdk.min.js"></script>

Or install npm package:

npm install --save ecomplus-sdk

Summary

  1. Getting Started
  2. Methods

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:

Arguments Type Required
err Error object or null ✔️
body Object or null ✔️

If the method runs correctly, err will be null, otherwise, it will be an Error object.

The response object from the APIs is parsed and returned in body, it's null if no JSON response can be captured.

Initialize

init(callback, StoreId, StoreObjectId, Logger)

Before you call the other methods you need to initialize the library.

In client JS (browser) StoreId is not required, if undefined, it will be set in function of site domain name.

You have to define StoreId, and should also define StoreObjectId, if using SDK on backend with Node.js, or if you are embedding the store in another external site, such as a blog, not in the storefront.

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 Type Required
callback Function ✔️
StoreId Number
StoreObjectId String
Logger Console object
// storefront on browser
EcomIo.init(callback)
// Node.js or not storefront site
EcomIo.init(callback, 100, '5a674f224e0dcec2c3353d9d')

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.

Get Store

getStore(callback, id)

API reference

Method to read a store object by the ID.

Arguments Type Required
callback Function ✔️
id String

The id is not required only if StoreObjectId is set, then this method will get the object of current store.

StoreObjectId will be set automaticly if SDK is running on storefront with browser.

// get current store object
// uses saved StoreObjectId
EcomIo.getStore(callback)
// specific store by object id
EcomIo.getStore(callback, '5a674f224e0dcec2c3353d9d')

Get Product

getProduct(callback, id)

API reference

Method to read a product object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getProduct(callback, '123a5432109876543210cdef')

Example of returned body:

{
  '_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,
  // ...
}

Get Product By Sku

getProductBySku(callback, sku)

Similar to getProduct, with the same return, but here you pass the product SKU instead of ID.

Arguments Type Required
callback Function ✔️
sku String ✔️
EcomIo.getProductBySku(callback, 'COD1')

Get Order

getOrder(callback, id)

API reference

Method to read an order object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getOrder(callback, 'fe1000000000000000000005')

Get Cart

getCart(callback, id)

API reference

Method to read a cart object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getCart(callback, '2ca000000000000000000003')

Get Customer

getCustomer(callback, id)

API reference

Method to read a customer object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getCustomer(callback, '3c1000000000000000000003')

Get Application

getApplication(callback, id)

API reference

Method to read an application object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getApplication(callback, '42aa00000000000000000111')

Get Brand

getBrand(callback, id)

API reference

Method to read a brand object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getBrand(callback, 'a10000000000000000000001')

Find Brand By Slug

findBrandBySlug(callback, slug)

API reference

Method to find and read a brand by the slug.

Arguments Type Required
callback Function ✔️
slug String ✔️
EcomIo.findBrandBySlug(callback, 'brand-four')

List Brands

listBrands(callback, offset, limit, sort, fields, customQuery)

API reference

Method to list the store brands.

Arguments Type Required
callback Function ✔️
offset Number
limit Number
sort Number
fields Array
customQuery String

Offset, limit, sort and fields are URL parameters (metadata) for pagination and ordering, you can use customQuery to query by particular object properties. Default enumered sort options:

Number Usage
1 Sort by name ascending
2 Sort by name descending
3 Sort by creation date ascending
4 Sort by creation date descending
5 Sort by popularity descending
EcomIo.listBrands(callback)
EcomIo.listBrands(callback, 0, 1000, 1, ['name'])
EcomIo.listBrands(callback, null, null, null, null, 'limit=2&offset=4')

Get Category

getCategory(callback, id)

API reference

Method to read a category object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getCategory(callback, 'f10000000000000000000001')

Find Category By Slug

findCategoryBySlug(callback, slug)

API reference

Method to find and read a category by the slug.

Arguments Type Required
callback Function ✔️
slug String ✔️
EcomIo.findCategoryBySlug(callback, 'category-four')

List Categories

listCategories(callback, offset, limit, sort, fields, customQuery)

API reference

Similar to listBrands, but listing store categories.

Arguments Type Required
callback Function ✔️
offset Number
limit Number
sort Number
fields Array
customQuery String
EcomIo.listCategories(callback)
EcomIo.listCategories(callback, 0, 1000, 1, ['name'])
EcomIo.listCategories(callback, null, null, null, null, 'limit=2&offset=4')

Get Collections

getCollection(callback, id)

API reference

Method to read a collection object by the ID.

Arguments Type Required
callback Function ✔️
id String ✔️
EcomIo.getCollection(callback, 'f10000000000000000000001')

Find Collection By Slug

findCollectionBySlug(callback, slug)

API reference

Method to find and read a collection by the slug.

Arguments Type Required
callback Function ✔️
slug String ✔️
EcomIo.findCollectionBySlug(callback, 'special-collection')

List Collections

listCollections(callback, offset, limit, sort, fields, customQuery)

API reference

Similar to listBrands, but listing store collections.

Arguments Type Required
callback Function ✔️
offset Number
limit Number
sort Number
fields Array
customQuery String
EcomIo.listCollections(callback)
EcomIo.listCollections(callback, 0, 1000, 1, ['name'])
EcomIo.listCollections(callback, null, null, null, null, 'limit=2&offset=4')

Search Products

searchProducts(callback, term, from, size, sort, specs, ids, brands, categories, prices, customDsl)

API reference

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

You must follow Request Body Search specifications and this type mapping reference.

Arguments Type Required Default Description
callback Function ✔️ Callback function
term String Term that you are searching for
from number 0 Results offset number
size number 24 Maximum number of results
sort number 0 Results ordering, default is by views
specs Object Filter results by item specifications
ids Array Filter results by product IDs
brands Array Filter results by brands
categories Array Filter results by categories
prices Object Filter results by prices min and max
customDsl Object Custom search request body
// list trending items
EcomIo.searchProducts(callback)

Term

We use a multi match query to search specified term in two fields, the name and keywords of each product.

// search product by term
EcomIo.searchProducts(callback, 'tshirt')

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 option.

Default enumered sort options:

Number Field Usage
0 views Sort by popularity, products with more page 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.

Specs

The specs argument should be an object with specifications properties that we use to filter the search. The key is the specifications name and the value is an array with the specifications values.

// sample specs object
let specs = {
  'color': [ 'blue', 'red' ],
  'size': [ 'G' ]
}

IDs

The ids argument should be an array of products IDs to filter the search. If used, only the products of specified object ID(s) will be returned.

// sample ids array
let ids = [
  '1234567890abcdef01291510',
  '1234567890abcdef01291511',
  '1234567890abcdef01291512'
]

Brands

The brands argument should be an array of brands IDs or names to filter the search. If used, only products of specified brand(s) will be returned.

// sample brands array
let brands = [
  'a10000000000000000001110'
]
// sample brands array with names
let brands = [
  'Lenovo',
  'HP'
]

Categories

The categories argument should be an array of categories IDs or names to filter the search. If used, only products of specified categorie(s) will be returned.

// sample categories array
let categories = [
  'b10000000000000000001110'
]
// sample categories array with names
let brands = [
  'Laptops',
  'All-in-One Computers'
]

Prices

The prices argument should be an object to filter search by price range. You can pass the minimum and the maximum prices.

It's based on Range query from Elasticsearch documentation.

// sample prices object
let prices = {
  'min': 10,
  'max': 100
}

Custom DSL

The customDsl is an object that you can pass to run your own Elasticsearch Query DSL.

It must be a valid Request Body Search.

List Recommended Products

listRecommendedProducts(callback, id)

API reference

Method to get a list of products to recommend together with one reference product.

Arguments Type Required
callback Function ✔️
id String ✔️

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".

EcomIo.listRecommendedProducts(callback, 'a00000000000000000000000')

List Related Products

listRelatedProducts(callback, id)

API reference

Method to get a list of products similar to one reference product.

Arguments Type Required
callback Function ✔️
id String ✔️

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".

EcomIo.listRelatedProducts(callback, 'a00000000000000000000000')

Map By Slug

mapBySlug(callback, slug)

Method to discouver the respective resource and ID by the page slug.

Arguments Type Required
callback Function ✔️
slug String ✔️
EcomIo.mapBySlug(callback, 'product-sample-slug')

Example of returned body:

{
  'resource': 'products',
  '_id': '123a5432109876543210cdef'
}

Map By Window URI

mapByWindowUri(callback)

Does the same as mapBySlug, but sets slug automaticlly from window.location.

Arguments Type Required
callback Function ✔️

This method is available client side only (JS on browser)

EcomIo.mapByWindowUri(callback)

Get Any By ID

getById(callback, resource, id)

Generic method to read any public resource object from Store API by the ID.

Arguments Type Required
callback Function ✔️
resource String ✔️
id String ✔️
EcomIo.getById(callback, 'products', '123a5432109876543210cdef')

Get Any List

getList(callback, resource, offset, limit, sort, fields, customQuery)

Generic method to read any public resource list from Store API.

Arguments Type Required
callback Function ✔️
resource String ✔️
offset Number
limit Number
sort Number
fields Array
customQuery String
EcomIo.getList(callback, 'grids')
EcomIo.getList(callback, 'grids', 0, 1000, 1, ['title'])
EcomIo.getList(callback, 'grids', null, null, null, null, 'limit=2&offset=4')

Modules

Working with Modules API

TODO documentation

Calculate Shipping

calculateShipping(callback, body)

TODO documentation

List Payments

listPayments(callback, body)

TODO documentation

Create Transaction

createTransaction(callback, body)

TODO documentation

Checkout

checkout(callback, body)

TODO documentation

Package Sidebar

Install

npm i ecomplus-sdk

Weekly Downloads

3

Version

1.16.0

License

MIT

Unpacked Size

70.8 kB

Total Files

6

Last publish

Collaborators

  • leomp12