@contentful/experiences-client 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.1.5 (2026-07-24)
+
+### 🚀 Features
+
+- add preview toggle to fetchExperience with dual-token client options [AIS-233] ([#93](https://github.com/contentful/experiences/pull/93))
+
+## 0.1.4 (2026-07-24)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.4
+
 ## 0.1.3 (2026-07-21)
 
 ### 🩹 Fixes

package/README.md

@@ -14,11 +14,11 @@ The primary fetch + resolve entry point. Fetches an Experience payload from the
 
 Three positional args group by concern:
 
-| Arg                 | Type                                                | Purpose                                           |
-| ------------------- | --------------------------------------------------- | ------------------------------------------------- |
-| `experienceOptions` | `{ spaceId, environmentId, experienceId, locale? }` | Which Experience to fetch.                        |
-| `clientOptions`     | `{ accessToken, host? }` **or** `{ client }`        | How to fetch — inline creds or a pre-made client. |
-| `resolveOptions`    | `{ config, context? }`                              | How to resolve — component registry + context.    |
+| Arg                 | Type                                                                  | Purpose                                                                                |
+| ------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `experienceOptions` | `{ spaceId, environmentId, experienceId, locale? }`                   | Which Experience to fetch.                                                             |
+| `clientOptions`     | `{ accessToken, previewToken?, preview?, host? }` **or** `{ client }` | How to fetch — inline credentials (with optional preview toggle) or a pre-made client. |
+| `resolveOptions`    | `{ config, context? }`                                                | How to resolve — component registry + context.                                         |
 
 ```ts
 import { fetchExperience } from '@contentful/experiences-react'; // or experiences-svelte
@@ -28,7 +28,8 @@ const plan = await fetchExperience(
   { spaceId: '...', environmentId: 'master', experienceId: slug, locale: 'en-US' },
   {
     accessToken: process.env.CDA_TOKEN!,
-    host: 'https://preview.xdn.contentful.com', // optional — omit for default endpoint
+    previewToken: process.env.PREVIEW_TOKEN!, // optional — only required when preview: true
+    preview: false, // flip to true for preview mode; picks previewToken + preview host
   },
   {
     config: experienceConfig,
@@ -48,16 +49,39 @@ const plan = await fetchExperience(
 
 Returns `PortableRenderPlan`. An empty-nodes payload (draft / unpublished / empty locale) resolves to a valid plan with `nodes: []` — it is not a 404. For the missing-experience case, catch `NotFoundError` (re-exported below).
 
+#### Preview mode
+
+Configure both tokens up front and flip `preview: true` per call to hit the preview API.
+
+```ts
+const experience = await fetchExperience(
+  { spaceId, environmentId, experienceId },
+  {
+    accessToken: process.env.CDA_TOKEN!,
+    previewToken: process.env.PREVIEW_TOKEN!,
+    preview: previewMode, // boolean — flip per request
+  },
+  { config: experienceConfig }
+);
+```
+
+- `preview: false` (or unset) → uses `accessToken` against the delivery host.
+- `preview: true` → uses `previewToken` against the preview host. Throws `fetchExperience() called with preview: true but no previewToken was provided` if `previewToken` is missing.
+- `host` is only for custom base URLs (staging, proxy, per-region). When set, it wins over the `preview`-derived host — so `{ previewToken, preview: true, host: 'https://preview-staging…' }` uses the preview token against your custom URL.
+- With the `{ client }` option, `preview` is ignored (bring your own client, bring your own token/host choice).
+
 ### `createClient(options)`
 
-Functional constructor over `ContentfulViewDeliveryClient` matching the SDK's option shape. Maps `accessToken → token` and `host → baseUrl`; passes everything else through unchanged. Prefer over `new ContentfulViewDeliveryClient({...})` so field names stay consistent with `fetchExperience`'s inline-creds path.
+Functional constructor over `ContentfulViewDeliveryClient` matching the SDK's option shape. Maps `accessToken → token` and `host → baseUrl`; passes everything else through unchanged. Prefer over `new ContentfulViewDeliveryClient({...})` so field names stay consistent with `fetchExperience`'s inline-credentials path.
+
+`createClient` is a one-time setup primitive — it builds a single client bound to a single token and does not participate in the per-request `preview` toggle. If you need runtime-dynamic swaps between delivery and preview, use `fetchExperience`'s inline-credentials path (`{ accessToken, previewToken, preview }`) instead of pre-building a client via `createClient` and passing `{ client }`.
 
 ```ts
 import { createClient } from '@contentful/experiences-react';
 
 const client = createClient({
   accessToken: process.env.CDA_TOKEN!,
-  host: 'https://preview.xdn.contentful.com', // optional
+  host: 'https://preview-staging.example.com', // optional custom base URL
   // headers, timeoutInSeconds, maxRetries, fetch, logging pass through
 });
 ```

package/dist/fetch-experience.d.ts

@@ -9,6 +9,23 @@ type ExperienceOptions = {
 };
 type ClientOptions = {
     accessToken: string;
+    /**
+     * Preview access token. Required when calling with `preview: true`.
+     */
+    previewToken?: string;
+    /**
+     * Flip between delivery (default) and preview at request time. When
+     * `true`, `fetchExperience` uses `previewToken` and the preview host;
+     * when `false` or unset, it uses `accessToken` and the delivery host.
+     * Ignored when a pre-made `client` is passed instead of inline creds.
+     */
+    preview?: boolean;
+    /**
+     * Custom base URL for the delivery client (staging, proxy, per-region).
+     * Wins over the `preview`-derived default host — combine `host` with
+     * `preview: true` to point preview mode at a non-prod endpoint.
+     * Omit for the standard delivery / preview hosts.
+     */
     host?: string;
 } | {
     client: ContentfulViewDeliveryClient;

package/dist/fetch-experience.js

@@ -1,9 +1,24 @@
 import { resolveExperience } from "@contentful/experiences-sdk-core";
 import { createClient } from "./create-client.js";
+const PREVIEW_HOST = "https://preview.xdn.contentful.com";
 async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
   const { spaceId, environmentId, experienceId, locale } = experienceOptions;
   const { config, context } = resolveOptions;
-  const client = "client" in clientOptions ? clientOptions.client : createClient({ accessToken: clientOptions.accessToken, host: clientOptions.host });
+  let client;
+  if ("client" in clientOptions) {
+    client = clientOptions.client;
+  } else {
+    const { accessToken, previewToken, preview, host } = clientOptions;
+    if (preview && !previewToken) {
+      throw new Error(
+        "fetchExperience() called with preview: true but no previewToken was provided"
+      );
+    }
+    client = createClient({
+      accessToken: preview ? previewToken : accessToken,
+      host: host ?? (preview ? PREVIEW_HOST : void 0)
+    });
+  }
   const payload = await client.view.getExperience(spaceId, environmentId, experienceId, {
     locale
   });

package/dist/fetch-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolveExperienceOptions,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\n\nexport type ExperienceOptions = {\n  spaceId: string;\n  environmentId: string;\n  experienceId: string;\n  locale?: string;\n};\n\nexport type ClientOptions =\n  | { accessToken: string; host?: string }\n  | { client: ContentfulViewDeliveryClient };\n\nexport type ResolveOptions = {\n  config: ResolverConfig;\n  context?: ResolveExperienceOptions['experience'];\n};\n\nexport async function fetchExperience(\n  experienceOptions: ExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan> {\n  const { spaceId, environmentId, experienceId, locale } = experienceOptions;\n  const { config, context } = resolveOptions;\n\n  const client =\n    'client' in clientOptions\n      ? clientOptions.client\n      : createClient({ accessToken: clientOptions.accessToken, host: clientOptions.host });\n\n  // Response from the experience delivery client is structurally compatible with ExperiencePayload (superset)\n  const payload = (await client.view.getExperience(spaceId, environmentId, experienceId, {\n    locale,\n  })) as unknown as ExperiencePayload;\n\n  return resolveExperience(payload, config, { experience: context });\n}\n"],"mappings":"AACA,SAAS,yBAAyB;AAOlC,SAAS,oBAAoB;AAkB7B,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,QAAQ,IAAI;AAE5B,QAAM,SACJ,YAAY,gBACR,cAAc,SACd,aAAa,EAAE,aAAa,cAAc,aAAa,MAAM,cAAc,KAAK,CAAC;AAGvF,QAAM,UAAW,MAAM,OAAO,KAAK,cAAc,SAAS,eAAe,cAAc;AAAA,IACrF;AAAA,EACF,CAAC;AAED,SAAO,kBAAkB,SAAS,QAAQ,EAAE,YAAY,QAAQ,CAAC;AACnE;","names":[]}
+{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolveExperienceOptions,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\n\nconst PREVIEW_HOST = 'https://preview.xdn.contentful.com';\n\nexport type ExperienceOptions = {\n  spaceId: string;\n  environmentId: string;\n  experienceId: string;\n  locale?: string;\n};\n\nexport type ClientOptions =\n  | {\n      accessToken: string;\n      /**\n       * Preview access token. Required when calling with `preview: true`.\n       */\n      previewToken?: string;\n      /**\n       * Flip between delivery (default) and preview at request time. When\n       * `true`, `fetchExperience` uses `previewToken` and the preview host;\n       * when `false` or unset, it uses `accessToken` and the delivery host.\n       * Ignored when a pre-made `client` is passed instead of inline creds.\n       */\n      preview?: boolean;\n      /**\n       * Custom base URL for the delivery client (staging, proxy, per-region).\n       * Wins over the `preview`-derived default host — combine `host` with\n       * `preview: true` to point preview mode at a non-prod endpoint.\n       * Omit for the standard delivery / preview hosts.\n       */\n      host?: string;\n    }\n  | { client: ContentfulViewDeliveryClient };\n\nexport type ResolveOptions = {\n  config: ResolverConfig;\n  context?: ResolveExperienceOptions['experience'];\n};\n\nexport async function fetchExperience(\n  experienceOptions: ExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan> {\n  const { spaceId, environmentId, experienceId, locale } = experienceOptions;\n  const { config, context } = resolveOptions;\n\n  let client: ContentfulViewDeliveryClient;\n  if ('client' in clientOptions) {\n    client = clientOptions.client;\n  } else {\n    const { accessToken, previewToken, preview, host } = clientOptions;\n    if (preview && !previewToken) {\n      throw new Error(\n        'fetchExperience() called with preview: true but no previewToken was provided'\n      );\n    }\n    client = createClient({\n      accessToken: preview ? (previewToken as string) : accessToken,\n      host: host ?? (preview ? PREVIEW_HOST : undefined),\n    });\n  }\n\n  // Response from the experience delivery client is structurally compatible with ExperiencePayload (superset)\n  const payload = (await client.view.getExperience(spaceId, environmentId, experienceId, {\n    locale,\n  })) as unknown as ExperiencePayload;\n\n  return resolveExperience(payload, config, { experience: context });\n}\n"],"mappings":"AACA,SAAS,yBAAyB;AAOlC,SAAS,oBAAoB;AAE7B,MAAM,eAAe;AAsCrB,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,QAAQ,IAAI;AAE5B,MAAI;AACJ,MAAI,YAAY,eAAe;AAC7B,aAAS,cAAc;AAAA,EACzB,OAAO;AACL,UAAM,EAAE,aAAa,cAAc,SAAS,KAAK,IAAI;AACrD,QAAI,WAAW,CAAC,cAAc;AAC5B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,aAAS,aAAa;AAAA,MACpB,aAAa,UAAW,eAA0B;AAAA,MAClD,MAAM,SAAS,UAAU,eAAe;AAAA,IAC1C,CAAC;AAAA,EACH;AAGA,QAAM,UAAW,MAAM,OAAO,KAAK,cAAc,SAAS,eAAe,cAAc;AAAA,IACrF;AAAA,EACF,CAAC;AAED,SAAO,kBAAkB,SAAS,QAAQ,EAAE,YAAY,QAAQ,CAAC;AACnE;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Delivery client + fetchExperience for Contentful Experiences",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
   },
   "dependencies": {
     "@contentful/experience-delivery": "1.0.0-dev.3",
-    "@contentful/experiences-sdk-core": "0.5.3"
+    "@contentful/experiences-sdk-core": "0.5.4"
   }
 }