@elasticpath/js-sdk
v17.0.0
Published
SDK for the Elastic Path eCommerce API
Downloads
834
Keywords
Readme
Elastic Path Commerce Cloud JavaScript SDK
[!IMPORTANT]
This repository has been migrated from @moltin/sdk. If you are a previous user of the Moltin SDK, read our guide to learn more about migrating your implementation to this codebase
A simple to use API interface to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud JavaScript apps.
📚 API reference — 📚 Elastic Path Commerce Cloud
🛠 Installation
Install the package from npm and import in your project.
npm install --save @elasticpath/js-sdk
⛽️ Usage
To get started, instantiate a new Elastic Path client with your store credentials.
[!NOTE]
This requires an Elastic Path Commerce Cloud account. You can sign up for a free trial here
// JavaScript
import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'
const ElasticPath = ElasticPathGateway({
client_id: 'XXX'
})
// Node.js
const ElasticPathGateway = require('@elasticpath/js-sdk').gateway
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
client_secret: 'XXX'
})
Alternatively you can include the UMD
bundle via UNPKG like so:
<script src="https://unpkg.com/@elasticpath/js-sdk"></script>
<script>
const ElasticPath = elasticpath.gateway({
client_id: 'XXX'
});
</script>
Note: If you're using webpack, you'll need to add the following to your projects configuration file.
node: {
fs: 'empty'
}
You can now authenticate with the ElasticPath service 🎉
ElasticPath.Authenticate().then(response => {
console.log('authenticated', response)
})
Check out the API reference to learn more about authenticating and the available endpoints.
Custom Host
If you're an enterprise customer with your own infrastructure, you'll need to specify your API URL when instantiating:
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
host: 'api.yourdomain.com'
})
Custom Storage
By default the Elastic Path Commerce Cloud SDK persists data to window.localStorage
in the browser and node-localstorage
in Node. If this doesn't suit your needs you can override the default storage with a MemoryStorageFactory
which will persist data for the life cycle of the JavaScript VM:
import { gateway as ElasticPathGateway, MemoryStorageFactory } from '@elasticpath/js-sdk'
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
storage: new MemoryStorageFactory()
})
Or alternatively, create your own storage factory by passing in an object which implements the following interface:
interface StorageFactory {
set(key: string, value: string): void;
get(key: string): string | null;
delete(key: string): void;
}
Multiple Gateways
You can support multiple gateways with a name
property when initializing the gateway.
name
should be unique to avoid sharing storage keys with the other gateways of the same name.
import { gateway as EPCCGateway } from "@elasticpath/js-sdk"
const gatewayOne = EPCCGateway({
name: "my-first-gateway",
client_id: 'XXX'
})
const gatewayTwo = EPCCGateway({
name: "my-second-gateway",
client_id: 'XXX'
})
Storage keys used for storage solutions are prefixed with the name provided and end with the relevant feature e.g.
my-first-gateway_ep_cart
, my-first-gateway_ep_credentials
and my-first-gateway_ep_currency
.
If no name property is provided to the EPCCGateway function, the legacy naming is maintained:
mcart
, epCredentials
and mcurrency
Included Headers
There are currently several optional headers you can pass into the configuration, which include application
, language
and currency
.
You can pass them into the config used by the gateway like this:
// JavaScript
import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'
// const ElasticPathGateway = require('@elasticpath/js-sdk').gateway -> for Node
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
client_secret: 'XXX'
currency: 'YEN',
language: 'en',
application: 'my-app'
})
Retries
In case the server responds with status 429 - "Too Many Requests" SDK will wait for some time and retry the same API request up to a given number of times. You can fine tune this logic through following config parameters:
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
client_secret: 'XXX',
retryDelay: 1000,
retryJitter: 500,
fetchMaxAttempts: 4
})
In case of a 429 response SDK will wait for retryDelay
milliseconds (default 1000) before attempting to make the same call.
If the server responds with 429 again it will wait for 2 * retryDelay
ms, then 3 * retryDelay
ms and so on.
On top of that the random value between 0 and retryJitter
(default 500) will be added to each wait.
This would repeat up to fetchMaxAttempts
(default 4) times.
Throttling (Rate Limiting)
SDK supports throttling through use of throttled-queue
library.
Unlike the throttle functions of popular libraries, throttled-queue
will not prevent any executions.
Instead, every execution is placed into a queue, which will be drained at the desired rate limit.
You can control throttling through following parameters:
const ElasticPath = ElasticPathGateway({
client_id: 'XXX',
client_secret: 'XXX',
throttleEnabled: true,
throttleLimit: 3,
throttleInterval: 125
})
This feature is disabled by default and to enable it you need to set throttleEnabled
to true.
Once enabled you can use throttleLimit
(default 3) and throttleInterval
(default 125) to define what is the maximum number of calls per interval.
For example setting throttleLimit = 5, throttleInterval = 1000
means maximum of 5 calls per second.
Handling File Upload
Files can be uploaded to the EPCC file service with the ElasticPath.Files.Create
method. You should pass a FormData
object as described in the documentation.
In a Node.js environment, where you may be using an alternative FormData
implementation, you can include a second parameter to represent the Content-Type
header for the request. This must be multipart/form-data
and must include a boundary
. For example, using the form-data
package:
const FormData = require('form-data')
const formData = new FormData()
formData.append('file', buffer)
const contentType = formData.getHeaders()['content-type']
ElasticPath.Files.Create(formData, contentType)
Referencing a file stored elsewhere
If you want to create a file by simply referencing a file stored elsewhere, you can use this helper method:
ElasticPath.Files.Link('https://cdn.external-host.com/files/filename.png')
Just pass the URL to the Link
method and creation will be handled for you.
TypeScript Support
The Elastic Path Commerce Cloud JavaScript SDK is fully supported in Typescript.
Imported module will contain all interfaces needed to consume backend services. i.e:
import * as elasticpath from '@elasticpath/js-sdk';
const product: elasticpath.ProductBase = {...}
If you do not want to use the namespace, you can extend the interfaces and define them yourself, like so:
// You can name the interface anything you like
interface Product extends product.ProductBase {
}
const product: Product = {...}
Here is an example of a simple product creation:
import { ElasticPath, gateway, ProductBase, Resource } from '@elasticpath/js-sdk';
async function main() {
const g: ElasticPath = gateway({client_id, client_secret});
const auth = await g.Authenticate();
const newProduct: ProductBase = {
type: "product",
name: "My Product",
slug: "my-prod",
sku: "my-prod",
manage_stock: false,
description: "Some description",
status: "draft",
commodity_type: "physical",
price: [
{
amount: 5499,
currency: "USD",
includes_tax: true
}
]
};
const nP: Resource<Product> = await g.Products.Create(newProduct);
}
You can also extend any base interface compatible with flows to create any custom interfaces that you might be using by re-declaring @elasticpath/js-sdk
module. Following example adds several properties to ProductsBase
interface that correspond to flows added to the backend.
In your project add a definition file (with a .d.ts
extension) with a following code:
import * as elasticpath from '@elasticpath/js-sdk';
declare module '@elasticpath/js-sdk' {
interface Weight {
g: number;
kg: number;
lb: number;
oz: number;
}
interface ProductBase {
background_color: string;
background_colour: string | null;
bulb: string;
bulb_qty: string;
finish: string;
material: string;
max_watt: string;
new: string | null;
on_sale: string | null;
weight: Weight;
}
}
This will affect base interface and all other Product interfaces that inherit from base interface so added properties will be present when creating, updating, fetching products.
❤️ Contributing
We love community contributions. Here's a quick guide if you want to submit a pull request:
- Fork the repository
- Add a test for your change (it should fail)
- Make the tests pass
- Commit your changes (see note below)
- Submit your PR with a brief description explaining your changes
Note: Commits should adhere to the Angular commit conventions.
Make sure you have Prettier installed for your editor with ESLint integration enabled.
⚡️ Development
The SDK is built with ES6 modules that are bundled using Rollup.
If you want to roll your own bundle, or make changes to any of the modules in src
, then you'll need to install the package dependencies and run rollup while watching for changes.
npm install
npm start
To run test
npm test
You can learn more about the Rollup API and configuration here.
Terms And Conditions
- Any changes to this project must be reviewed and approved by the repository owner.
- For more information about the license, see MIT License.