@contentful/experiences-client 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.1.7 (2026-08-03)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.5
+
+## 0.1.6 (2026-07-30)
+
+### 🚀 Features
+
+- export host constants [AIS-232] ([#97](https://github.com/contentful/experiences/pull/97), [#93](https://github.com/contentful/experiences/issues/93))
+
 ## 0.1.5 (2026-07-24)
 
 ### 🚀 Features

package/README.md

@@ -77,15 +77,38 @@ Functional constructor over `ContentfulViewDeliveryClient` matching the SDK's op
 `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';
+import { createClient, PREVIEW_HOST } from '@contentful/experiences-react';
+
+// Delivery (default)
+const client = createClient({ accessToken: process.env.CDA_TOKEN! });
 
-const client = createClient({
+// Preview — use PREVIEW_HOST + a CPA token
+const previewClient = createClient({
+  accessToken: process.env.PREVIEW_TOKEN!,
+  host: PREVIEW_HOST,
+});
+
+// Custom base URL (staging, proxy, per-region)
+const customClient = createClient({
   accessToken: process.env.CDA_TOKEN!,
-  host: 'https://preview-staging.example.com', // optional custom base URL
+  host: 'https://preview-staging.example.com',
   // headers, timeoutInSeconds, maxRetries, fetch, logging pass through
 });
 ```
 
+#### `DELIVERY_HOST` / `PREVIEW_HOST`
+
+Named constants for the canonical XDA delivery and preview URLs. Use them so you don't have to hardcode the URL strings in your app.
+
+```ts
+import { DELIVERY_HOST, PREVIEW_HOST } from '@contentful/experiences-react';
+
+DELIVERY_HOST; // 'https://xdn.contentful.com'
+PREVIEW_HOST; // 'https://preview.xdn.contentful.com'
+```
+
+`createClient` is the fixed-mode path — one client, one token, one host. If you need to flip between delivery and preview per request (e.g. an `isPreview` URL param), use `fetchExperience`'s inline-credentials form with `preview: boolean` instead of pre-building a client here. See ["Preview mode"](#preview-mode) above.
+
 ### `NotFoundError`
 
 Re-exported from `@contentful/experience-delivery` as a value + type. Thrown by the underlying delivery client on 404 responses. Route it to your framework's 404 idiom:

package/dist/create-client.d.ts

@@ -2,6 +2,11 @@ import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
 
 type CreateClientOptions = {
     accessToken: string;
+    /**
+     * Base URL for the delivery client. Defaults to `DELIVERY_HOST` when omitted.
+     * Pass `PREVIEW_HOST` for preview mode, or any custom URL (staging, proxy,
+     * per-region). Both constants are exported from this package.
+     */
     host?: string;
 } & Omit<ContentfulViewDeliveryClient.Options, 'token' | 'baseUrl'>;
 declare function createClient(options: CreateClientOptions): ContentfulViewDeliveryClient;

package/dist/create-client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/create-client.ts"],"sourcesContent":["import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\n\nexport type CreateClientOptions = {\n  accessToken: string;\n  host?: string;\n} & Omit<ContentfulViewDeliveryClient.Options, 'token' | 'baseUrl'>;\n\nexport function createClient(options: CreateClientOptions): ContentfulViewDeliveryClient {\n  const { accessToken, host, ...rest } = options;\n  return new ContentfulViewDeliveryClient({\n    ...rest,\n    token: accessToken,\n    baseUrl: host,\n  });\n}\n"],"mappings":"AAAA,SAAS,oCAAoC;AAOtC,SAAS,aAAa,SAA4D;AACvF,QAAM,EAAE,aAAa,MAAM,GAAG,KAAK,IAAI;AACvC,SAAO,IAAI,6BAA6B;AAAA,IACtC,GAAG;AAAA,IACH,OAAO;AAAA,IACP,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/create-client.ts"],"sourcesContent":["import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\n\nexport type CreateClientOptions = {\n  accessToken: string;\n  /**\n   * Base URL for the delivery client. Defaults to `DELIVERY_HOST` when omitted.\n   * Pass `PREVIEW_HOST` for preview mode, or any custom URL (staging, proxy,\n   * per-region). Both constants are exported from this package.\n   */\n  host?: string;\n} & Omit<ContentfulViewDeliveryClient.Options, 'token' | 'baseUrl'>;\n\nexport function createClient(options: CreateClientOptions): ContentfulViewDeliveryClient {\n  const { accessToken, host, ...rest } = options;\n  return new ContentfulViewDeliveryClient({\n    ...rest,\n    token: accessToken,\n    baseUrl: host,\n  });\n}\n"],"mappings":"AAAA,SAAS,oCAAoC;AAYtC,SAAS,aAAa,SAA4D;AACvF,QAAM,EAAE,aAAa,MAAM,GAAG,KAAK,IAAI;AACvC,SAAO,IAAI,6BAA6B;AAAA,IACtC,GAAG;AAAA,IACH,OAAO;AAAA,IACP,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

package/dist/fetch-experience.js

@@ -1,6 +1,6 @@
 import { resolveExperience } from "@contentful/experiences-sdk-core";
 import { createClient } from "./create-client.js";
-const PREVIEW_HOST = "https://preview.xdn.contentful.com";
+import { PREVIEW_HOST } from "./hosts.js";
 async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
   const { spaceId, environmentId, experienceId, locale } = experienceOptions;
   const { config, context } = resolveOptions;

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\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":[]}
+{"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';\nimport { PREVIEW_HOST } from './hosts.js';\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;AAC7B,SAAS,oBAAoB;AAsC7B,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/dist/hosts.d.ts

@@ -0,0 +1,4 @@
+declare const DELIVERY_HOST = "https://xdn.contentful.com";
+declare const PREVIEW_HOST = "https://preview.xdn.contentful.com";
+
+export { DELIVERY_HOST, PREVIEW_HOST };

package/dist/hosts.js

@@ -0,0 +1,7 @@
+const DELIVERY_HOST = "https://xdn.contentful.com";
+const PREVIEW_HOST = "https://preview.xdn.contentful.com";
+export {
+  DELIVERY_HOST,
+  PREVIEW_HOST
+};
+//# sourceMappingURL=hosts.js.map

package/dist/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hosts.ts"],"sourcesContent":["export const DELIVERY_HOST = 'https://xdn.contentful.com';\nexport const PREVIEW_HOST = 'https://preview.xdn.contentful.com';\n"],"mappings":"AAAO,MAAM,gBAAgB;AACtB,MAAM,eAAe;","names":[]}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { ContentfulViewDelivery } from '@contentful/experience-delivery';
 export { ContentfulViewDelivery, ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
 export { CreateClientOptions, createClient } from './create-client.js';
 export { ClientOptions, ExperienceOptions, ResolveOptions, fetchExperience } from './fetch-experience.js';
+export { DELIVERY_HOST, PREVIEW_HOST } from './hosts.js';
 import '@contentful/experiences-sdk-core';
 
 declare const NotFoundError: typeof ContentfulViewDelivery.NotFoundError;

package/dist/index.js

@@ -6,10 +6,13 @@ import {
 const NotFoundError = ContentfulViewDelivery.NotFoundError;
 import { createClient } from "./create-client.js";
 import { fetchExperience } from "./fetch-experience.js";
+import { DELIVERY_HOST, PREVIEW_HOST } from "./hosts.js";
 export {
   ContentfulViewDelivery2 as ContentfulViewDelivery,
   ContentfulViewDeliveryClient,
+  DELIVERY_HOST,
   NotFoundError,
+  PREVIEW_HOST,
   createClient,
   fetchExperience
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { ContentfulViewDelivery } from '@contentful/experience-delivery';\n\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n} from '@contentful/experience-delivery';\nexport const NotFoundError = ContentfulViewDelivery.NotFoundError;\nexport type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;\nexport { createClient } from './create-client.js';\nexport type { CreateClientOptions } from './create-client.js';\nexport { fetchExperience } from './fetch-experience.js';\nexport type { ExperienceOptions, ClientOptions, ResolveOptions } from './fetch-experience.js';\n"],"mappings":"AAAA,SAAS,8BAA8B;AAEvC;AAAA,EACE,0BAAAA;AAAA,EACA;AAAA,OACK;AACA,MAAM,gBAAgB,uBAAuB;AAEpD,SAAS,oBAAoB;AAE7B,SAAS,uBAAuB;","names":["ContentfulViewDelivery"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { ContentfulViewDelivery } from '@contentful/experience-delivery';\n\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n} from '@contentful/experience-delivery';\nexport const NotFoundError = ContentfulViewDelivery.NotFoundError;\nexport type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;\nexport { createClient } from './create-client.js';\nexport type { CreateClientOptions } from './create-client.js';\nexport { fetchExperience } from './fetch-experience.js';\nexport type { ExperienceOptions, ClientOptions, ResolveOptions } from './fetch-experience.js';\nexport { DELIVERY_HOST, PREVIEW_HOST } from './hosts.js';\n"],"mappings":"AAAA,SAAS,8BAA8B;AAEvC;AAAA,EACE,0BAAAA;AAAA,EACA;AAAA,OACK;AACA,MAAM,gBAAgB,uBAAuB;AAEpD,SAAS,oBAAoB;AAE7B,SAAS,uBAAuB;AAEhC,SAAS,eAAe,oBAAoB;","names":["ContentfulViewDelivery"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-client",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.4"
+    "@contentful/experiences-sdk-core": "0.5.5"
   }
 }