@commercelayer/sdk 8.0.0-beta.9 → 8.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [2026] [Commerce Layer]
+Copyright (c) 2019 Commerce Layer Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,14 +2,15 @@
 
 [![Version](https://img.shields.io/npm/v/@commercelayer/sdk.svg)](https://npmjs.org/package/@commercelayer/sdk)
 [![Downloads/week](https://img.shields.io/npm/dw/@commercelayer/sdk.svg)](https://npmjs.org/package/@commercelayer/sdk)
-[![License](https://img.shields.io/npm/l/@commercelayer/sdk.svg)](https://github.com/commercelayer/commercelayer-sdk/blob/master/package.json)
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
-[![Release](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/semantic-release.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/semantic-release.yml)
-[![CodeQL](https://github.com/commercelayer/commercelayer-cli/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/commercelayer/commercelayer-cli/actions/workflows/codeql-analysis.yml)
+[![License](https://img.shields.io/npm/l/@commercelayer/sdk.svg)](https://github.com/commercelayer/commercelayer-sdk/blob/main/packages/core-sdk/LICENSE)
+[![Verify](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/verify.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/verify.yml)
+[![CodeQL](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk/actions/workflows/codeql-analysis.yml)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript%205-%230074c1.svg)](https://www.typescriptlang.org/)
 
 A JavaScript Library wrapper that makes it quick and easy to interact with the [Commerce Layer API](https://docs.commercelayer.io/developers).
 
+> This package is generated and released from the [`commercelayer-sdk`](https://github.com/commercelayer/commercelayer-sdk) monorepo, alongside [`@commercelayer/provisioning-sdk`](https://www.npmjs.com/package/@commercelayer/provisioning-sdk). Both are produced by the same generator from the API’s own published schema.
+
 ## What is Commerce Layer?
 
 [Commerce Layer](https://commercelayer.io) is a multi-market commerce API and order management system that lets you add global shopping capabilities to any website, mobile app, chatbot, wearable, voice, or IoT device, with ease. Compose your stack with the best-of-breed tools you already mastered and love. Make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.
@@ -21,6 +22,7 @@ A JavaScript Library wrapper that makes it quick and easy to interact with the [
 - [Authentication](#authentication)
 - [Import](#import)
 - [Options](#options)
+- [API version](#api-version)
 - [SDK usage](#sdk-usage)
 - [Overriding credentials](#overriding-credentials)
 - [Handling validation errors](#handling-validation-errors)
@@ -66,7 +68,8 @@ The SDK offers two import styles. **The default entry is the bundled client**
 import { CommerceLayer } from '@commercelayer/sdk'
 
 const cl = CommerceLayer({
-  accessToken: 'your-access-token'
+  accessToken: 'your-access-token',
+  apiVersion: '2026-05'
 })
 
 const orderList = await cl.orders.list()
@@ -76,8 +79,8 @@ const skuList = await cl.skus.list()
 All resource accessors are available directly on the client object. This increases your final bundle size, but every call is scoped to that specific client instance — so you can safely create and use **multiple clients with different access tokens at the same time** (multi-tenant apps, serverless with connection reuse, etc.):
 
 ```javascript
-const clUS = CommerceLayer({ accessToken: usToken })
-const clEU = CommerceLayer({ accessToken: euToken })
+const clUS = CommerceLayer({ accessToken: usToken, apiVersion: '2026-05' })
+const clEU = CommerceLayer({ accessToken: euToken, apiVersion: '2026-05' })
 
 const [usOrders, euOrders] = await Promise.all([
   clUS.orders.list(),
@@ -91,7 +94,8 @@ const [usOrders, euOrders] = await Promise.all([
 import { CommerceLayer, orders, skus } from '@commercelayer/sdk/single-client'
 
 const cl = CommerceLayer({
-  accessToken: 'your-access-token'
+  accessToken: 'your-access-token',
+  apiVersion: '2026-05'
 })
 
 const orderList = await orders.list()
@@ -110,6 +114,7 @@ When instantiating a new SDK client you can pass some options to initialize it:
 {
   organization?: string       // The organization slug
   accessToken: string         // A valid API access token
+  apiVersion: ApiVersion      // The API version to target, e.g. '2026-05' — required, see API version below
   timeout?: number            // A custom request timout (<= 15 secs [default])
   headers?: RequestHeaders    // Custom request headers
   userAgent?: string          // Custom user-agent useful in certaing contexts but often not allowed by browsers
@@ -130,16 +135,42 @@ Same options can be changed after SDK initialization or passed at runtime while
   cl.config(options)
 
   // Use runtime configuration without persisting settings
-  customers.list({}, options)
+  cl.customers.list({}, options)
+```
+
+### API version
+
+The Core API is versioned, and every request targets a single version. `apiVersion` is therefore **required** when creating a client, and becomes part of each request URL — `/api/2026-05/orders`.
+
+Only the versions this release of the SDK was generated for are accepted; any other value is a type error. Both are exported:
+
+```javascript
+import { API_SCHEMA_VERSION, API_SUPPORTED_VERSIONS } from '@commercelayer/sdk'
+
+API_SUPPORTED_VERSIONS // ['2017-08', '2026-05'] — the versions you can target
+API_SCHEMA_VERSION     // '2026-05' — the version the types describe
+```
+
+The types are generated for `API_SCHEMA_VERSION`. Resources and fields that exist only in an older version are still included, marked `@deprecated` with the last version that has them, and newer additions carry `@since` — so you can keep targeting `'2017-08'` while migrating, and your editor shows what changes.
+
+The version can be changed on an existing client, or overridden for a single request:
+
+```javascript
+cl.config({ apiVersion: '2017-08' })
+
+const orderList = await cl.orders.list({}, { apiVersion: '2017-08' })
 ```
 
+> [!IMPORTANT]
+> Upgrading from 7.x: `apiVersion` is new and required, so every `CommerceLayer(...)` call needs it.
+
 ## SDK usage
 
 The JavaScript SDK is a wrapper around Commerce Layer API which means you would still be making API requests but with a different syntax. For now, we don't have comprehensive SDK documentation for every single resource our API supports (about 400+ endpoints), hence you will need to rely on our comprehensive [API Reference](https://docs.commercelayer.io/core/v/api-reference) as you go about using this SDK. So for example, if you want to create an order, take a look at the [Order object](https://docs.commercelayer.io/core/v/api-reference/orders/object) or the [Create an order](https://docs.commercelayer.io/core/v/api-reference/orders/create) documentation to see the required attributes and/or relationships. The same goes for every other supported resource.
 
 To show you how things work, we will use the [SKUs](https://docs.commercelayer.io/core/v/api-reference/skus) and [Shipping Categories](https://docs.commercelayer.io/core/v/api-reference/shipping_categories) resource in the following examples. The code snippets below show how to use the SDK when performing the standard CRUD operations provided by our REST API. Kindly check our [API reference](https://docs.commercelayer.io/core/v/api-reference) for the complete list of available **resources** and their **attributes**.
 
-> The examples below use the selective style (`skus.create(...)`, imported from `@commercelayer/sdk/single-client`) for brevity. With the default **bundled client**, call the same methods through the client instance instead — e.g. `cl.skus.create(...)`, `cl.shipping_categories.list(...)`.
+> The examples below assume a client `cl`, created as shown in [Import](#import).
 
 ### Create
 
@@ -149,18 +180,17 @@ To show you how things work, we will use the [SKUs](https://docs.commercelayer.i
 
 ```javascript
   // Select the shipping category (it's a required relationship for the SKU resource)
-  const shippingCategories = await shipping_categories.list({ filters: { name_eq: 'Merchandising' } })
+  const shippingCategories = await cl.shipping_categories.list({ filters: { name_eq: 'Merchandising' } })
 
-  const attributes = {
+  // Attributes passed inline, so each value is checked against the field it sets
+  const newSku = await cl.skus.create({
     code: 'TSHIRTMM000000FFFFFFXL',
     name: 'Black Men T-shirt with White Logo (XL)',
-    description: "A very beautiful and cozy mens t-shirt",
-    weight: "500",
-    unit_of_weight: "gr"
-    shipping_category: shipping_categories.relationship(shippingCategories[0].id), // assigns the relationship
-  }
-
-  const newSku = await skus.create(attributes)
+    description: 'A very beautiful and cozy mens t-shirt',
+    weight: 500,
+    unit_of_weight: 'gr',
+    shipping_category: cl.shipping_categories.relationship(shippingCategories[0].id), // assigns the relationship
+  })
 ```
 
 ℹ️ Check our API reference for more information on how to [create an SKU](https://docs.commercelayer.io/developers/v/api-reference/skus/create).
@@ -174,16 +204,16 @@ To show you how things work, we will use the [SKUs](https://docs.commercelayer.i
 
 ```javascript
   // Fetch the SKU by ID
-  const sku = await skus.retrieve('BxAkSVqKEn')
+  const sku = await cl.skus.retrieve('BxAkSVqKEn')
 
   // Fetch all SKUs and filter by code
-  const skuList = await skus.list({ filters: { code_eq: 'TSHIRTMM000000FFFFFFXLXX' } })
+  const skuList = await cl.skus.list({ filters: { code_eq: 'TSHIRTMM000000FFFFFFXLXX' } })
 
   // Fetch the first SKU of the list
-  const skuList = (await skus.list()).first()
+  const skuList = (await cl.skus.list()).first()
 
   // Fetch the last SKU of the list
-  const skuList = (await skus.list()).last()
+  const skuList = (await cl.skus.list()).last()
 ```
 
 ℹ️ Check our API reference for more information on how to [retrieve an SKU](https://docs.commercelayer.io/developers/v/api-reference/skus/retrieve).
@@ -195,14 +225,14 @@ To show you how things work, we will use the [SKUs](https://docs.commercelayer.i
 
 ```javascript
   // Fetch all the SKUs
-  const skuList = await skus.list()
+  const skuList = await cl.skus.list()
 ```
 
 When fetching a collection of resources you can leverage the `meta` attribute to get its `meta` information like so:
 
 ```javascript
-  const skuList = await skus.list()
-  const meta = skus.meta
+  const skuList = await cl.skus.list()
+  const meta = skuList.meta
 ```
 
 ℹ️ Check our API reference for more information on how to [list all SKUs](https://docs.commercelayer.io/developers/v/api-reference/skus/list).
@@ -214,10 +244,10 @@ When fetching a collection of resources you can leverage the `meta` attribute to
 
 ```javascript
   // Sort the results by creation date in ascending order (default)
-  const skuList = await skus.list({ sort: { created_at: 'asc' } })
+  const skuList = await cl.skus.list({ sort: { created_at: 'asc' } })
 
   // Sort the results by creation date in descending order
-  const skuList = await skus.list({ sort: { created_at: 'desc' } })
+  const skuList = await cl.skus.list({ sort: { created_at: 'desc' } })
   ```
 
 ℹ️ Check our API reference for more information on how to [sort results](https://docs.commercelayer.io/developers/sorting-results).
@@ -229,10 +259,10 @@ When fetching a collection of resources you can leverage the `meta` attribute to
 
 ```javascript
   // Include an association (prices)
-  const skuList = await skus.list({ include: [ 'prices' ] })
+  const skuList = await cl.skus.list({ include: [ 'prices' ] })
 
   // Include an association (stock items)
-  const skuList = await skus.list({ include: [ 'stock_items' ] })
+  const skuList = await cl.skus.list({ include: [ 'stock_items' ] })
   ```
 
 ℹ️ Check our API reference for more information on how to [include associations](https://docs.commercelayer.io/developers/including-associations).
@@ -244,10 +274,10 @@ When fetching a collection of resources you can leverage the `meta` attribute to
 
 ```javascript
   // Request the API to return only specific fields
-  const skuList = await skus.list({ fields: { skus: [ 'name', 'metadata' ] } })
+  const skuList = await cl.skus.list({ fields: { skus: [ 'name', 'metadata' ] } })
 
   // Request the API to return only specific fields of the included resource
-  const skuList = await skus.list({ include: [ 'prices' ], fields: { prices: [ 'currency_code', 'formatted_amount' ] } })
+  const skuList = await cl.skus.list({ include: [ 'prices' ], fields: { prices: [ 'currency_code', 'formatted_amount' ] } })
   ```
 
 ℹ️ Check our API reference for more information on how to [use sparse fieldsets](https://docs.commercelayer.io/developers/sparse-fieldsets).
@@ -259,25 +289,25 @@ When fetching a collection of resources you can leverage the `meta` attribute to
 
 ```javascript
   // Filter all the SKUs fetching only the ones whose code starts with the string "TSHIRT"
-  const skuList = await skus.list({ filters: { code_start: 'TSHIRT' } })
+  const skuList = await cl.skus.list({ filters: { code_start: 'TSHIRT' } })
 
   // Filter all the SKUs fetching only the ones whose code ends with the string "XLXX"
-  const skuList = await skus.list({ filters: { code_end: 'XLXX' } })
+  const skuList = await cl.skus.list({ filters: { code_end: 'XLXX' } })
 
   // Filter all the SKUs fetching only the ones whose name contains the string "White Logo"
-  const skuList = await skus.list({ filters: { name_cont: 'White Logo' } })
+  const skuList = await cl.skus.list({ filters: { name_cont: 'White Logo' } })
 
   // Filter all the SKUs fetching only the ones created between two specific dates
   // (filters combined according to the AND logic)
-  const skuList = await skus.list({ filters: { created_at_gt: '2018-01-01', created_at_lt: '2018-01-31'} })
+  const skuList = await cl.skus.list({ filters: { created_at_gt: '2018-01-01', created_at_lt: '2018-01-31'} })
 
   // Filters all the SKUs fetching only the ones created or updated after a specific date
   // (attributes combined according to the OR logic)
-  const skuList = await skus.list({ filters: { updated_at_or_created_at_gt: '2019-10-10' } })
+  const skuList = await cl.skus.list({ filters: { updated_at_or_created_at_gt: '2019-10-10' } })
 
   // Filters all the SKUs fetching only the ones whose name contains the string "Black"
   // and whose shipping category name starts with the string "MERCH"
-  const skuList = await skus.list({ filters: { name_cont: 'Black', shipping_category_name_start: 'MERCH'} })
+  const skuList = await cl.skus.list({ filters: { name_cont: 'Black', shipping_category_name_start: 'MERCH'} })
   ```
 
 ℹ️ Check our API reference for more information on how to [filter data](https://docs.commercelayer.io/developers/filtering-data).
@@ -291,13 +321,13 @@ When you fetch a collection of resources, you get paginated results. You can req
 
 ```javascript
   // Fetch the SKUs, setting the page number to 3 and the page size to 5
-  const skuList = await skus.list({ pageNumber: 3, pageSize: 5 })
+  const skuList = await cl.skus.list({ pageNumber: 3, pageSize: 5 })
 
   // Get the total number of SKUs in the collection
-  const skuCount = skus.meta.recordCount
+  const skuCount = skuList.meta.recordCount
 
   // Get the total number of pages
-  const pageCount = skus.meta.pageCount
+  const pageCount = skuList.meta.pageCount
 ```
 
 > PS: the default page number is **1**, the default page size is **10**, and the maximum page size allowed is **25**.
@@ -305,6 +335,31 @@ When you fetch a collection of resources, you get paginated results. You can req
 ℹ️ Check our API reference for more information on how [pagination](https://docs.commercelayer.io/developers/pagination) works.
 </details>
 
+<details>
+<summary>How to fetch a cursor-paginated collection (e.g. event stores)</summary>
+<br />
+
+A few resources — such as [event stores](https://docs.commercelayer.io/core-api-reference/event_stores) — use **cursor-based** pagination instead of page numbers. Navigate with `pageAfter` (and `pageBefore`), and read the cursor for the next page from `meta.cursor`, which is present only on cursor-paginated responses:
+
+```javascript
+  const skuId = 'xYZkjABcde'
+
+  // Event stores are fetched as a relationship of a resource
+  let page = await cl.skus.event_stores(skuId, { pageSize: 10 })
+  const events = [...page]
+
+  // Follow the cursor until there are no more pages
+  while (page.meta.cursor?.next) {
+    page = await cl.skus.event_stores(skuId, { pageAfter: page.meta.cursor.next.after })
+    events.push(...page)
+  }
+```
+
+> PS: the default page size is **10** and the maximum is **25**. On cursor-paginated responses the offset fields (`meta.pageCount`/`meta.recordCount`) are `NaN` and `hasNextPage()` returns `false`, so check `meta.cursor.next` instead. The `pageAfter`/`pageBefore` params are always accepted at the type level; offset-paginated resources simply ignore them.
+
+ℹ️ See the [event stores pagination](https://docs.commercelayer.io/core-api-reference/event_stores#pagination) reference for details.
+</details>
+
 <details>
 <summary>How to iterate through a collection of SKUs</summary>
 <br />
@@ -313,8 +368,8 @@ To execute a function for every item of a collection, use the `map()` method lik
 
 ```javascript
   // Fetch the whole list of SKUs (1st page) and print their names and codes to console
-  const skuList = await skus.list()
-  skus.map(p => console.log('Product: ' + p.name + ' - Code: ' + p.code))
+  const skuList = await cl.skus.list()
+  skuList.map(p => console.log('Product: ' + p.name + ' - Code: ' + p.code))
 ```
 
 </details>
@@ -334,16 +389,16 @@ Many resources have relationships with other resources and instead of including
 
 ```javascript
 // Fetch 1-to-1 related resource: billing address of an order
-const billingAddress = await orders.billing_address('xYZkjABcde')
+const billingAddress = await cl.orders.billing_address('xYZkjABcde')
 
 // Fetch 1-to-N related resources: orders associated to a customer
-const orders = await customers.orders('XyzKjAbCDe', { fields: ['status', 'number'] })
+const customerOrders = await cl.customers.orders('XyzKjAbCDe', { fields: ['status', 'number'] })
 ```
 
 In general:
 
-- An API endpoint like `/api/customers` or `/api/customers/<customerId>` translates to `cl.customers` or `cl.customers('<customerId>')` with the SDK.
-- 1-to-1 relationship API endpoints like `/api/orders/<orderId>/shipping_address` translates to `cl.orders('<orderId>', { include: ['shipping_address'] }}` with the SDK.
+- An API endpoint like `/api/customers` or `/api/customers/<customerId>` translates to `cl.customers.list()` or `cl.customers.retrieve('<customerId>')` with the SDK.
+- 1-to-1 relationship API endpoints like `/api/orders/<orderId>/shipping_address` translates to `cl.orders.shipping_address('<orderId>')` with the SDK, or to `cl.orders.retrieve('<orderId>', { include: ['shipping_address'] })` to get it along with the order.
 - 1-to-N relationship API endpoints like  `/api/customers/<customerId>?include=orders` or `/api/customers/<customerId>/orders` translates to `cl.customers.retrieve('<customerId>', { include: ['orders'] })` or `cl.customers.orders('<customerId>')` with the SDK.
 
 ℹ️ Check our API reference for more information on how to [fetch relationships](https://docs.commercelayer.io/core/fetching-relationships).
@@ -376,10 +431,10 @@ const placedOrders = await cl.orders.count({ filters: { status_eq: 'placed' } })
   const sku = {
     id: 'xYZkjABcde',
     description: 'Updated description...',
-    imageUrl: 'https://img.yourdomain.com/skus/new-image.png'
+    image_url: 'https://img.yourdomain.com/skus/new-image.png'
   }
 
-  skus.update(sku) // updates the SKU on the server
+  cl.skus.update(sku) // updates the SKU on the server
 ```
 
 ℹ️ Check our API reference for more information on how to [update an SKU](https://docs.commercelayer.io/developers/v/api-reference/skus/update).
@@ -392,7 +447,7 @@ const placedOrders = await cl.orders.count({ filters: { status_eq: 'placed' } })
 <br />
 
 ```javascript
-  skus.delete('xYZkjABcde') // persisted deletion
+  cl.skus.delete('xYZkjABcde') // persisted deletion
 ```
 
 ℹ️ Check our API reference for more information on how to [delete an SKU](https://docs.commercelayer.io/developers/v/api-reference/skus/delete).
@@ -405,12 +460,12 @@ If needed, Commerce Layer JS SDK lets you change the client configuration and se
 ```javascript
   // Permanently change configuration at client level
   cl.config({ organization: 'you-organization-slug', accessToken: 'your-access-token' })
-  const skuList = await skus.list()
+  const skuList = await cl.skus.list()
 
-  or
+  // or
 
   // Use configuration at request level
-  skus.list({}, { organization: 'you-organization-slug', accessToken: 'your-access-token' })
+  cl.skus.list({}, { organization: 'you-organization-slug', accessToken: 'your-access-token' })
 ```
 
 ## Handling validation errors
@@ -421,7 +476,7 @@ Commerce Layer API returns specific errors (with extra information) on each attr
   // Log error messages to console:
   const attributes = { code: 'TSHIRTMM000000FFFFFFXL', name: '' }
 
-  const newSku = await skus.create(attributes).catch(error => console.log(error.errors))
+  const newSku = await cl.skus.create(attributes).catch(error => console.log(error.errors))
 
   // Logged errors
   /*
@@ -487,7 +542,7 @@ Here an example of how to use them:
   cl.addRequestInterceptor(requestInterceptor)
   cl.addResponseInterceptor(responseInterceptor, errorInterceptor)
 
-  const customerList = await customers.list()
+  const customerList = await cl.customers.list()
 
   // Remove interceptors
   // Tt is possible to remove only a specific interceptor: cl.removeInterceptor('request')
@@ -502,7 +557,7 @@ The *RawResponseReader* is a special interceptor that allows to catch the origin
   // Add a RawResponseReader capable of capturing also response headers
   const rrr = cl.addRawResponseReader({ headers: true })
   
-  const customerList = await customers.list()
+  const customerList = await cl.customers.list()
 
   cl.removeRawResponseReader()
 
@@ -537,9 +592,17 @@ In this case you can define a special function that takes care of refreshing the
     git clone https://github.com/<your username>/commercelayer-sdk.git && cd commercelayer-sdk
     ```
 
-3. Make your changes and create a pull request ([learn how to do this](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)).
+3. Install the workspace from the repository root:
+
+    ```shell
+    pnpm install
+    ```
+
+4. Make your changes. Most of this package is generated from the API schema — anything you edit under `gen/` will be overwritten. Change the generator or `sdk.config.ts` instead, then run `pnpm generate` and commit the result.
+
+5. Create a pull request ([learn how to do this](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)). Lint, types, both test suites and a check that generated output is reproducible run automatically.
 
-4. Someone will attend to your pull request and provide some feedback.
+6. Someone will attend to your pull request and provide some feedback.
 
 ## Need help?