commerce-sdk
Advanced tools
The Salesforce Commerce SDK allows easy interaction with the Salesforce B2C Commerce platform APIs on the Node.js runtime.
Visit the Commerce Cloud Developer Center to learn more about Salesforce Commerce. The developer center has API documentation, getting started guides, community forums, and more.
Download and install Node.js and npm here.
Note: Only Node.js version 10 and 12 LTS are supported. Other versions can cause unexpected results. To use a different version of Node.js for other projects, you can manage multiple versions of Node.js with nvm.
Use npm to install the Commerce SDK.
npm install commerce-sdk
To use an SDK client, instantiate an object of that client and configure these parameters.
Note: These are optional parameters.
| Parameter | Description |
|---|---|
| baseUri | URL of the service with which the SDK interacts. If the baseUri isn't provided, the default baseUri for the relevant RAML file is used. |
| clientId | ID of the client account created with Salesforce Commerce. |
| organizationId | The unique identifier for your Salesforce identity. |
| shortCode | Region specific merchant ID. |
| siteId | A unique site ID (for example, RefArch or SiteGenesis). |
/**
* Sample TypeScript code that shows how Commerce SDK can access Salesforce Commerce
* APIs.
*/
// Import the SDK in TypeScript
// tsc requires the --esModuleInterop flag for this
import * as CommerceSdk from "commerce-sdk";
// For Javascript, use:
// import CommerceSdk from "commerce-sdk";
const { ClientConfig, helpers, Search } = CommerceSdk;
// Older Node.js versions can instead use:
// const { ClientConfig, helpers, Search } = require("commerce-sdk");
// Create a configuration to use when creating API clients
const config = {
headers: {},
parameters: {
clientId: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
organizationId: "f_ecom_bblx_stg",
shortCode: "0dnz6oep",
siteId: "RefArch"
}
}
// Get a JWT to use with Shopper API clients, a guest token in this case
helpers.getShopperToken(config, { type: "guest" }).then(async (token) => {
try {
// Add the token to the client configuration
config.headers["authorization"] = token.getBearerHeader();
// Create a new ShopperSearch API client
const searchClient = new Search.ShopperSearch(config);
// Search for dresses
const searchResults = await searchClient.productSearch({
parameters: {
q: "dress",
limit: 5
}
});
if (searchResults.total) {
const firstResult = searchResults.hits[0];
console.log(`${firstResult.productId} ${firstResult.productName}`);
} else {
console.log("No results for search");
}
return searchResults;
} catch (e) {
console.error(e);
console.error(await e.response.text());
}
}).catch(async (e) => {
console.error(e);
console.error(await e.response.text());
});
When using an IDE such as VSCode, the autocomplete feature lets you view the available method and class definitions, including parameters.
To view the details of a method or a variable, hover over methods and variables.
Autocomplete also shows the available properties of the data returned by SDK methods.
The SDK currently supports two types of caches - In-memory and Redis. Both the implementations respect standard cache headers. To use another type of cache, write your own implementation of the CacheManager. See the default cache manager to design your implementation.
The default cache storage is limited to 10,000 distinct entities before applying a simple least recently used policy for cache replacement. The limit can be changed by creating a quick-lru storage adapter.
import { CacheManagerKeyv } from '@commerce-apps/core';
import { QuickLRU } from 'quick-lru';
const cacheManagerKeyv = new CacheManagerKeyv({
keyvStore: new QuickLRU({ maxSize: 50000 }),
});
const config = {
cacheManager: cacheManagerKeyv,
parameters: {
clientId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
organizationId: 'f_ecom_bblx_stg',
shortCode: '0dnz6oep',
siteId: 'RefArch',
},
};
See these directions to create a cache storage adapter.
In-memory caching of responses is enabled by default. To disable caching for a client, set cacheManager to 'null'.
const config = {
cacheManager: null,
parameters: {
clientId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
organizationId: 'f_ecom_bblx_stg',
shortCode: '0dnz6oep',
siteId: 'RefArch',
},
};
To use a Redis cache, instantiate a CacheManagerRedis object with a Redis URL and add it to your client config object.
import { CacheManagerRedis } from '@commerce-apps/core';
const cacheManager = new CacheManagerRedis({
connection: 'redis://localhost:6379',
});
const config = {
cacheManager: cacheManager,
parameters: {
clientId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
organizationId: 'f_ecom_bblx_stg',
shortCode: '0dnz6oep',
siteId: 'RefArch',
},
};
Redis can be configured to apply an eviction policy when the specified memory limit is reached. See this article to set up Redis as an LRU cache and to learn more about supported eviction policies.
Use the node-retry package to facilitate request retries. The following retry type definition is taken from the node-retry package.
type RetrySettings = {
/**
* Whether to retry forever.
* @default false
*/
forever?: boolean;
/**
* Whether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's.
* @default false
*/
unref?: boolean;
/**
* The maximum time (in milliseconds) that the retried operation is allowed to run.
* @default Infinity
*/
maxRetryTime?: number;
/**
* The maximum amount of times to retry the operation.
* @default 10
*/
retries?: number;
/**
* The exponential factor to use.
* @default 2
*/
factor?: number;
/**
* The number of milliseconds before starting the first retry.
* @default 1000
*/
minTimeout?: number;
/**
* The maximum number of milliseconds between two retries.
* @default Infinity
*/
maxTimeout?: number;
/**
* Randomizes the timeouts by multiplying a factor between 1-2.
* @default false
*/
randomize?: boolean;
};
All options can be set per client or per request.
Example:
productClient = new Product({
retrySettings: {
// This means 3 total calls are made
retries: 2,
// Max wait between retries
maxTimeout: 200,
// Min wait between retries
minTimeout: 100
}
}
Default log level of the SDK is WARN (warning). SDK uses loglevel npm package. All the log levels supported by loglevel package are supported in SDK.
To change the loglevel, set the desired level on the SDK logger.
import { sdkLogger } from 'commerce-sdk';
sdkLogger.setLevel(sdkLogger.levels.INFO);
INFO level logging enables:
DEBUG level logging enables logging of:
Note: Debug level logging may expose sensitive data in the logs
The Commerce SDK is licensed under BSD-3-Clause license. See the license for details.
v1.5.0-beta.0
Shopper Stores API
Customer API
Type Name Removed
Display Name Changed
Endpoints Removed
Shopper Baskets API
Shopper Login SLAS
FAQs
Salesforce Commerce Cloud SDK
The npm package commerce-sdk receives a total of 6,418 weekly downloads. As such, commerce-sdk popularity was classified as popular.
We found that commerce-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.