Have ideas to improve npm?Join in the discussion! »

    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

    Install

    npm i ecomplus-sdk

    DownloadsWeekly Downloads

    12

    Version

    1.16.0

    License

    MIT

    Unpacked Size

    70.8 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar