opencommercesearch-sdk-js

OpenCommerceSearch Javascript SDK

Description

JS version of the ProductApi SDK to be used on the server and (eventually) client.

---

Common Tasks

Install

npm install opencommercesearch-ocs-sdk

Test

Run style and unit tests once.

npm test

or

grunt test

Develop

Continuosly run style and unit tests while watching for changes.

grunt develop

---

Basic Usage

All API methods make async requests and return promises which support .then() .done() and .fail() methods. Read more about promises here.

var productApiService = require('opencommercesearch-sdk-js');

productApiService.config({
  host: 'api.domain.com'
});

productApiService
  .searchProducts({
    q: 'a search term',
    site: 'your_site'
  })
  .then(function(data) {
    // do something
  });

---

Utility Methods

.config(options)

Configures the service, best used at application startup.

Property	Type	Description
host	String	the host to use for all requests, should only be set once during server start
preview	boolean	whether or not to set the
debug	boolean	exposes additional helper methods and logging for debug purposes

.getConfig()

Returns the current configuration settings.

---

API Methods

Available methods are grouped below by the type of item returned (product, category, etc). All methods accept a single options object requiring at least a site, and usually one or more additional properties. Additionally, there are several optional properties that can be passed to most endpoints:

• fields --- all endpoints have default fields that can be overridden with a comma separated list of field names
  • dot notation is supported for nested fields brand.name
  • during development fields: '*' can be used to return all fields but is not recommended for production
  • always request the least amount of data required
• metadata --- (string) used to specify what metadata is returned and is useful for reducing the size of the request
  • for a product search request where facets are not required, using metadata: found can significantly reduce the size of the response
• limit --- (int) number of items to return, search/browse endpoints have a max limit of 40
• offset --- (int) number of items to offset, used for pagination on search/browse endpoints
• preview --- (boolean) whether or not to return results from the preview environment
• outlet --- (boolean) whether or not to return products/categories in outlet
• filterQueries --- (string) filters (facets) to apply to search/browse endpoints, values can be found in metadata.facets.filters.filterQueries

Products

.findProducts(options)

Returns the specified product(s). Multiple products can be requested at once by passing a comma-separated string or array of productIds.

Property	Type	Description
productId	String|Array	one or more productIds
site	String	site code

---

.searchProducts(options)

Returns all products that match the search query.

Property	Type	Description
q	String	a search query
site	String	site code

---

.browseCategory(options)

Returns all products belonging to a particular category.

Property	Type	Description
categoryId	String	a single categoryId
site	String	site code

---

.browseBrand(options)

Returns all products belonging to a particular brand.

Property	Type	Description
brandId	String	a single brandId
site	String	site code

---

.browseBrandCategory(options)

Returns all products belonging to a particular brand and category.

Property	Type	Description
brandId	String	a single brandId
categoryId	String	a single categoryId
site	String	site code

---

.findSimilarProducts(options)

Returns products similar to the product specified.

Property	Type	Description
productId	String	a single productId
site	String	site code

---

.findProductGenerations(options)

Returns all generations of the product.

Property	Type	Description
productId	String	a single productId
site	String	site code

---

.suggestProducts(options)

Returns products with brand and titles matching the query.

Property	Type	Description
q	String	a search query
site	String	site code

---

Categories

.findCategory(options)

Returns the specified category.

Property	Type	Description
categoryId	String	a single categoryId
site	String	site code
maxLevels	Int	(optional) the number of taxonomy levels, defaults to 1
maxChildren	Int	(optional) the number childCategories to return per taxonomy level, defaults to all

---

.categoryTaxonomy(options)

Returns the top level category taxonomy for the specified site. Use maxLevels: -1 to return the entire taxonomy (only as needed).

Property	Type	Description
site	String	site code
maxLevels	Int	(optional) the number of taxonomy levels, defaults to 1
maxChildren	Int	(optional) the number childCategories to return per taxonomy level, defaults to all

---

.findBrandCategories(options)

Returns all categories for the specified brand.

Property	Type	Description
brandId	String	a single brandId
site	String	site code

---

.suggestCategories(options)

Returns categories with titles that substring match the query.

Property	Type	Description
q	String	a search query
site	String	site code

---

Brands

.findBrands(options)

Returns the brand specified.

Property	Type	Description
brandId	String	a single brandId
site	String	site code

---

.allBrands(options)

Returns all brands for the specified site.

Property	Type	Description
site	String	site code

---

.suggestBrands(options)

Returns all brands with names that substring match the query.

Property	Type	Description
q	String	a search query
site	String	site code

.findCategoryBrands(options)

Returns all brands with at least one product in the specified category.

Property	Type	Description
categoryId	String	a single categoryId
site	String	site code

---

Suggestions

.suggestAll(options)

Returns suggestions for queries, products, brands, and categories that substring match the query.

Property	Type	Description
q	String	a search query
site	String	site code

---

Queries

.suggestQueries(options)

Returns suggestions for user search term queries that substring match query.

Property	Type	Description
q	String	a search query
site	String	site code