{"id":20397077,"url":"https://github.com/elasticpath/js-sdk","last_synced_at":"2025-04-07T07:05:45.433Z","repository":{"id":249853027,"uuid":"824581699","full_name":"elasticpath/js-sdk","owner":"elasticpath","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-18T10:23:23.000Z","size":3326,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-20T03:58:51.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elasticpath.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-05T12:45:42.000Z","updated_at":"2024-10-18T10:19:44.000Z","dependencies_parsed_at":"2024-07-23T19:52:31.235Z","dependency_job_id":"03405e9d-8bfe-4bd3-9996-276de906f258","html_url":"https://github.com/elasticpath/js-sdk","commit_stats":null,"previous_names":["elasticpath/js-sdk"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fjs-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fjs-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fjs-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fjs-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elasticpath","download_url":"https://codeload.github.com/elasticpath/js-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608150,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T04:11:41.663Z","updated_at":"2025-04-07T07:05:45.396Z","avatar_url":"https://github.com/elasticpath.png","language":"TypeScript","readme":"\u003cimg src=\"https://www.elasticpath.com/themes/custom/bootstrap_sass/logo.svg\" alt=\"\" width=\"400\" /\u003e\n\n# Elastic Path Commerce Cloud JavaScript SDK \n\n[![npm version](https://img.shields.io/npm/v/@elasticpath/js-sdk.svg)](https://www.npmjs.com/package/@elasticpath/js-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/elasticpath/js-sdk/issues)\n[![follow on Twitter](https://img.shields.io/twitter/follow/elasticpath?style=social\u0026logo=twitter)](https://twitter.com/intent/follow?screen_name=elasticpath)\n\n\u003e [!IMPORTANT]  \n\u003e This repository has been migrated from [@moltin/sdk](https://www.npmjs.com/package/@moltin/sdk). If you are a previous user of the Moltin SDK, read our [guide](MIGRATION_GUIDE.md) to learn more about migrating your implementation to this codebase  \n\nA simple to use API interface to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud JavaScript apps.\n\n📚 [API reference](https://documentation.elasticpath.com/commerce-cloud/docs/developer/get-started/sdk.html#officially-supported-sdk) \u0026mdash; 📚 [Elastic Path Commerce Cloud](https://www.elasticpath.com)\n\n## 🛠 Installation\n\nInstall the package from [npm](https://www.npmjs.com/package/@elasticpath/js-sdk) and import in your project.\n\n```bash\nnpm install --save @elasticpath/js-sdk\n```\n\n## ⛽️ Usage\n\nTo get started, instantiate a new Elastic Path client with your store credentials.\n\n\n\u003e [!NOTE]  \n\u003e This requires an [Elastic Path Commerce Cloud](https://www.elasticpath.com) account. You can sign up for a free trial [here](https://cm.elasticpath.com/free-trial)\n\n\n```js\n// JavaScript\nimport { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'\n\nconst ElasticPath = ElasticPathGateway({\n  client_id: 'XXX'\n})\n\n// Node.js\nconst ElasticPathGateway = require('@elasticpath/js-sdk').gateway\n\nconst ElasticPath = ElasticPathGateway({\n  client_id: 'XXX',\n  client_secret: 'XXX'\n})\n```\n\nAlternatively you can include the `UMD` bundle via [UNPKG](https://unpkg.com) like so:\n\n``` html\n\u003cscript src=\"https://unpkg.com/@elasticpath/js-sdk\"\u003e\u003c/script\u003e\n\n\u003cscript\u003e\n  const ElasticPath = elasticpath.gateway({\n    client_id: 'XXX'\n  });\n\u003c/script\u003e\n```\n\n\u003e **Note:** If you're using [webpack](https://webpack.github.io), you'll need to add the following to your projects configuration file.\n\n```js\nnode: {\n  fs: 'empty'\n}\n```\n\nYou can now authenticate with the ElasticPath service 🎉\n\n```js\nElasticPath.Authenticate().then(response =\u003e {\n  console.log('authenticated', response)\n})\n```\n\nCheck out the [API reference](https://elasticpath.dev/docs/commerce-cloud) to learn more about authenticating and the available endpoints.\n\n### Custom Host\n\nIf you're an enterprise customer with your own infrastructure, you'll need to specify your API URL when instantiating:\n\n```js\nconst ElasticPath = ElasticPathGateway({\n  client_id: 'XXX',\n  host: 'api.yourdomain.com'\n})\n```\n\n### Custom Storage\n\nBy 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:\n\n```js\nimport { gateway as ElasticPathGateway, MemoryStorageFactory } from '@elasticpath/js-sdk'\n\nconst ElasticPath = ElasticPathGateway({\n  client_id: 'XXX',\n  storage: new MemoryStorageFactory()\n})\n```\n\nOr alternatively, create your own storage factory by passing in an object which implements the following interface:\n\n```js\ninterface StorageFactory {\n  set(key: string, value: string): void;\n  get(key: string): string | null;\n  delete(key: string): void;\n}\n```\n\n### Multiple Gateways\n\nYou can support multiple gateways with a `name` property when initializing the gateway.\n\n`name` should be unique to avoid sharing storage keys with the other gateways of the same name.\n\n```js\nimport { gateway as EPCCGateway } from \"@elasticpath/js-sdk\"\n\nconst gatewayOne = EPCCGateway({\n    name: \"my-first-gateway\",\n    client_id: 'XXX'\n})\n\nconst gatewayTwo = EPCCGateway({\n    name: \"my-second-gateway\",\n    client_id: 'XXX'\n})\n```\n\nStorage keys used for storage solutions are prefixed with the name provided and end with the relevant feature e.g.\n`my-first-gateway_ep_cart`, `my-first-gateway_ep_credentials` and `my-first-gateway_ep_currency`.\n\nIf no name property is provided to the EPCCGateway function, the legacy naming is maintained:\n`mcart`, `epCredentials` and `mcurrency`\n\n### Included Headers\n\nThere are currently several optional headers you can pass into the configuration, which include `application`, `language` and `currency`.\n\nYou can pass them into the config used by the gateway like this:\n\n``` TypeScript\n// JavaScript\nimport { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'\n// const ElasticPathGateway = require('@elasticpath/js-sdk').gateway -\u003e for Node\n\nconst ElasticPath = ElasticPathGateway({\n    client_id: 'XXX',\n    client_secret: 'XXX'\n    currency: 'YEN',\n    language: 'en',\n    application: 'my-app'\n})\n```\n\n### Retries\n\nIn 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.\nYou can fine tune this logic through following config parameters:\n\n``` TypeScript\nconst ElasticPath = ElasticPathGateway({\n    client_id: 'XXX',\n    client_secret: 'XXX',\n    retryDelay: 1000,\n    retryJitter: 500,\n    fetchMaxAttempts: 4\n})\n\n```\n\nIn case of a 429 response SDK will wait for `retryDelay` milliseconds (default 1000) before attempting to make the same call.\nIf the server responds with 429 again it will wait for 2 * `retryDelay` ms, then 3 * `retryDelay` ms and so on.\nOn top of that the random value between 0 and `retryJitter` (default 500) will be added to each wait.\nThis would repeat up to `fetchMaxAttempts` (default 4) times.\n\n### Throttling (Rate Limiting)\n\nSDK supports throttling through use of `throttled-queue` library.\nUnlike the throttle functions of popular libraries, `throttled-queue` will not prevent any executions.\nInstead, every execution is placed into a queue, which will be drained at the desired rate limit.\nYou can control throttling through following parameters:\n\n``` TypeScript\nconst ElasticPath = ElasticPathGateway({\n    client_id: 'XXX',\n    client_secret: 'XXX',\n    throttleEnabled: true,\n    throttleLimit: 3,\n    throttleInterval: 125\n})\n\n```\n\nThis feature is disabled by default and to enable it you need to set `throttleEnabled` to true.\nOnce enabled you can use `throttleLimit` (default 3) and `throttleInterval` (default 125) to define what is the maximum number of calls per interval.\nFor example setting `throttleLimit = 5, throttleInterval = 1000` means maximum of 5 calls per second.\n\n### Handling File Upload\n\nFiles 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](https://documentation.elasticpath.com/commerce-cloud/docs/api/advanced/files/create-a-file.html#post-create-a-file 'documentation').\n\nIn 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](https://www.npmjs.com/package/form-data 'package'):\n\n``` TypeScript\nconst FormData = require('form-data')\nconst formData = new FormData()\nformData.append('file', buffer)\n\nconst contentType = formData.getHeaders()['content-type']\n\nElasticPath.Files.Create(formData, contentType)\n```\n\n#### Referencing a file stored elsewhere\n\nIf you want to create a file by simply [referencing](https://documentation.elasticpath.com/commerce-cloud/docs/api/advanced/files/create-a-file.html#post-create-a-file 'referencing') a file stored elsewhere, you can use this helper method:\n\n``` TypeScript\nElasticPath.Files.Link('https://cdn.external-host.com/files/filename.png')\n```\n\nJust pass the URL to the `Link` method and creation will be handled for you.\n\n### TypeScript Support\n\nThe Elastic Path Commerce Cloud JavaScript SDK is fully supported in Typescript.\n\nImported module will contain all interfaces needed to consume backend services. i.e:\n\n```TypeScript\nimport * as elasticpath from '@elasticpath/js-sdk';\n\nconst product: elasticpath.ProductBase = {...}\n```\n\nIf you do not want to use the namespace, you can extend the interfaces and define them yourself, like so:\n\n```TypeScript\n// You can name the interface anything you like\ninterface Product extends product.ProductBase {\n}\n\nconst product: Product = {...}\n```\n\nHere is an example of a simple product creation:\n\n```TypeScript\nimport { ElasticPath, gateway, ProductBase, Resource } from '@elasticpath/js-sdk';\n\nasync function main() {\n  const g: ElasticPath = gateway({client_id, client_secret});\n  const auth = await g.Authenticate();\n\n  const newProduct: ProductBase = {\n    type: \"product\",\n    name: \"My Product\",\n    slug: \"my-prod\",\n    sku: \"my-prod\",\n    manage_stock: false,\n    description: \"Some description\",\n    status: \"draft\",\n    commodity_type: \"physical\",\n    price: [\n      {\n        amount: 5499,\n        currency: \"USD\",\n        includes_tax: true\n      }\n    ]\n  };\n\n  const nP: Resource\u003cProduct\u003e = await g.Products.Create(newProduct);\n}\n```\n\nYou 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.\n\nIn your project add a definition file (with a `.d.ts` extension) with a following code:\n\n```TypeScript\nimport * as elasticpath from '@elasticpath/js-sdk';\n\ndeclare module '@elasticpath/js-sdk' {\n\n  interface Weight {\n    g: number;\n    kg: number;\n    lb: number;\n    oz: number;\n  }\n\n  interface ProductBase {\n    background_color: string;\n    background_colour: string | null;\n    bulb: string;\n    bulb_qty: string;\n    finish: string;\n    material: string;\n    max_watt: string;\n    new: string | null;\n    on_sale: string | null;\n    weight: Weight;\n  }\n\n}\n```\n\nThis 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.\n\n## ❤️ Contributing\n\nWe love community contributions. Here's a quick guide if you want to submit a pull request:\n\n1.  Fork the repository\n2.  Add a test for your change (it should fail)\n3.  Make the tests pass\n4.  Commit your changes (see note below)\n5.  Submit your PR with a brief description explaining your changes \n\n\u003e **Note:** Commits should adhere to the [Angular commit conventions](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines).\n\nMake sure you have [Prettier](https://prettier.io) installed for your editor with ESLint integration enabled.\n\n## ⚡️ Development\n\nThe SDK is built with [ES6 modules](https://strongloop.com/strongblog/an-introduction-to-javascript-es6-modules/) that are bundled using [Rollup](http://rollupjs.org).\n\nIf 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.\n\n```\nnpm install\nnpm start\n```\n\nTo run test\n\n```\nnpm test\n```\n\nYou can learn more about the Rollup API and configuration [here](https://github.com/rollup/rollup/wiki).\n\n## Terms And Conditions\n\n- Any changes to this project must be reviewed and approved by the repository owner.\n- For more information about the license, see [MIT License](https://github.com/elasticpath/js-sdk/blob/main/LICENSE).  ","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felasticpath%2Fjs-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felasticpath%2Fjs-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felasticpath%2Fjs-sdk/lists"}