Deprecate default export (#371)

Author: malessani

CHANGELOG.md

@@ -1,3 +1,14 @@
+## [8.0.0-beta.8](https://github.com/commercelayer/commercelayer-sdk/compare/v8.0.0-beta.7...v8.0.0-beta.8) (2026-07-02)
+
+### Features
+
+* add `@since` JSDoc annotations — counterpart to `@deprecated`. ([c1ff52b](https://github.com/commercelayer/commercelayer-sdk/commit/c1ff52b1213df610fb4d3d45e15e5542594da6bc))
+* add SDK version to request headers ([0d66f57](https://github.com/commercelayer/commercelayer-sdk/commit/0d66f574fbc7b3770ddde86bfb8fd2fdab58f3cb))
+* add support for `versions` attribute in schema ([a54ba3d](https://github.com/commercelayer/commercelayer-sdk/commit/a54ba3d623a907c62ab5b237e20b8076ffc723fc))
+* isolate client config between multiple instances ([39ee08a](https://github.com/commercelayer/commercelayer-sdk/commit/39ee08a33d3251c3c4a37e49a0b95983378559e2))
+* use `bundle` mode as default. Default one will become the `single-client` version ([788655d](https://github.com/commercelayer/commercelayer-sdk/commit/788655d2faf8a0710e75bb36ab7b2c567be5bf2c))
+* use children type for payment settings, promotions, ([7dc99ed](https://github.com/commercelayer/commercelayer-sdk/commit/7dc99edd823924d967d63a556923e0c40d622a0f))
+
 ## [8.0.0-beta.7](https://github.com/commercelayer/commercelayer-sdk/compare/v8.0.0-beta.6...v8.0.0-beta.7) (2026-06-25)
 
 ### ⚠ BREAKING CHANGES

README.md

@@ -58,12 +58,12 @@ All requests to Commerce Layer API must be authenticated with an [OAuth2](https:
 
 ### Import
 
-The SDK supports two import approaches. **Use the bundled client by default**, the selective import pattern is available for specific use cases but comes with important caveats described below.
+The SDK offers two import styles. **The default entry is the bundled client** — use it unless you have a specific reason not to. The selective (tree-shakeable) style lives on a separate subpath and carries an important caveat described below.
 
-#### Bundled client import
+#### Bundled client (default)
 
 ```javascript
-import { CommerceLayer } from '@commercelayer/sdk/bundle'
+import { CommerceLayer } from '@commercelayer/sdk'
 
 const cl = CommerceLayer({
   accessToken: 'your-access-token'
@@ -73,12 +73,22 @@ const orderList = await cl.orders.list()
 const skuList = await cl.skus.list()
 ```
 
-All resource accessors are available directly on the client object. This increases your final bundle size but keeps all resource calls scoped to a specific client instance.
+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.):
 
-#### Selective resource imports
+```javascript
+const clUS = CommerceLayer({ accessToken: usToken })
+const clEU = CommerceLayer({ accessToken: euToken })
+
+const [usOrders, euOrders] = await Promise.all([
+  clUS.orders.list(),
+  clEU.orders.list()
+]) // each request uses its own token
+```
+
+#### Selective resource imports (`/single-client`)
 
 ```javascript
-import CommerceLayer, { orders, skus } from '@commercelayer/sdk'
+import { CommerceLayer, orders, skus } from '@commercelayer/sdk/single-client'
 
 const cl = CommerceLayer({
   accessToken: 'your-access-token'
@@ -88,9 +98,9 @@ const orderList = await orders.list()
 const skuList = await skus.list()
 ```
 
-Only the imported resources are included in your bundle. However, imported resources share a single global SDK configuration. If two requests are in-flight simultaneously with different access tokens (common in serverless environments with connection reuse, or in any multi-tenant context), they may silently use the wrong token.
+Only the imported resources are included in your bundle, so it produces the smallest output. The trade-off: imported resources share **a single global SDK configuration**. If two requests are in-flight simultaneously with different access tokens, they may silently use the wrong token — so this style supports only **one active token at a time**.
 
-It is a good fit for edge/serverless functions or webhook handlers that use only a few resources and a single token active at a time.
+It is a good fit for edge/serverless functions or webhook handlers that use only a few resources and a single token. When you need multiple concurrent tokens, use the bundled client above.
 
 ### Options
 
@@ -129,6 +139,8 @@ The JavaScript SDK is a wrapper around Commerce Layer API which means you would
 
 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(...)`.
+
 ### Create
 
 <details>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/sdk",
-  "version": "8.0.0-beta.7",
+  "version": "8.0.0-beta.8",
   "main": "lib/index.cjs",
   "types": "lib/index.d.ts",
   "module": "lib/index.js",

specs/bundle-smoke.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import CommerceLayer from '../src' // default entry === the bundle client
+import { CommerceLayer } from '../src' // default entry === the bundle client
 import { handleError, interceptRequest } from '../test/common'
 
 // Smoke coverage for the DEFAULT entry (the bundle). The exhaustive

src/index.ts

@@ -2,8 +2,19 @@
 // isolated per client). For the lightweight, tree-shakeable single-client
 // model (direct resource imports, one global token) use
 // `@commercelayer/sdk/single-client`.
-export { CommerceLayer, type CommerceLayerBundle, default } from './bundle'
+import { CommerceLayer, type CommerceLayerBundle } from './bundle'
+
 export { SDK_VERSION } from './commercelayer'
+// Preferred: the named export. Clean, and the form we're standardising on.
+export { CommerceLayer, type CommerceLayerBundle }
+
+/**
+ * @deprecated Use the named import instead:
+ * `import { CommerceLayer } from '@commercelayer/sdk'`. The default export is
+ * kept for backwards compatibility and will be removed in a future major.
+ */
+const CommerceLayerDefault = CommerceLayer
+export default CommerceLayerDefault
 
 // Commerce Layer static functions
 export { CommerceLayerStatic } from './static'

src/single-client.ts

@@ -1,7 +1,20 @@
 // Resource adapters
 export * from './api'
+
 // SDK
-export { CommerceLayer, default, SDK_VERSION } from './commercelayer'
+import { CommerceLayer } from './commercelayer'
+
+// Preferred: the named export. Clean, and the form we're standardising on.
+export { CommerceLayer, SDK_VERSION } from './commercelayer'
+
+/**
+ * @deprecated Use the named import instead:
+ * `import { CommerceLayer } from '@commercelayer/sdk/single-client'`. The
+ * default export is kept for backwards compatibility and will be removed in
+ * a future major.
+ */
+const CommerceLayerDefault = CommerceLayer
+export default CommerceLayerDefault
 
 // Commerce Layer static functions
 export { CommerceLayerStatic } from './static'

test/common.ts

@@ -1,7 +1,8 @@
 import { inspect, isDeepStrictEqual } from 'node:util'
 import dotenv from 'dotenv'
 import { API_SCHEMA_VERSION } from '../src/commercelayer'
-import CommerceLayer, {
+import {
+  CommerceLayer,
   type CommerceLayerClient,
   type CommerceLayerConfig,
   type QueryParamsList,

test/util.ts

@@ -1,5 +1,5 @@
 import { inspect } from 'node:util'
-import CommerceLayer, { type CommerceLayerClient, type CommerceLayerInitConfig, CommerceLayerStatic } from '../src'
+import { CommerceLayer, type CommerceLayerClient, type CommerceLayerInitConfig, CommerceLayerStatic } from '../src'
 import getToken, { type AccessToken } from './token'
 
 export const getAccessToken = async (env?: string): Promise<AccessToken> => {