@contentful/experiences-client 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.3.1 (2026-08-07)
+
+### 🚀 Features
+
+- server-side design pre-resolution against a fallback viewport [AIS-386] ([#119](https://github.com/contentful/experiences/pull/119))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.7.1
+
 ## 0.3.0 (2026-08-07)
 
 ### 🩹 Fixes

package/dist/fetch-experience.d.ts

@@ -45,6 +45,12 @@ type ResolveOptions = {
      * debug fallback). A single boolean across fetch + resolve + render.
      */
     debug?: boolean;
+    /**
+     * Per-request fallback viewport for server-side design pre-resolution. Pass
+     * the same id you seed the renderer's `initialViewportId` with (e.g. a
+     * User-Agent-derived viewport) so SSR paints correct design on first render.
+     */
+    initialViewportId?: string;
 };
 declare function fetchExperience(experienceOptions: ExperienceOptions, clientOptions: ClientOptions, resolveOptions: ResolveOptions): Promise<PortableRenderPlan>;
 

package/dist/fetch-experience.js

@@ -4,7 +4,7 @@ import { createClient } from "./create-client.js";
 import { PREVIEW_HOST } from "./hosts.js";
 async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
   const { spaceId, environmentId, experienceId, locale } = experienceOptions;
-  const { config, metadata, debug } = resolveOptions;
+  const { config, metadata, debug, initialViewportId } = resolveOptions;
   const log = createDebugLogger(debug, "client");
   let client;
   if ("client" in clientOptions) {
@@ -34,7 +34,11 @@ async function fetchExperience(experienceOptions, clientOptions, resolveOptions)
   );
   const payload = response;
   log.lazy("received raw payload", () => payload);
-  return resolveExperience(payload, config, { metadata, debug });
+  return resolveExperience(payload, config, {
+    metadata,
+    debug,
+    initialViewportId
+  });
 }
 export {
   fetchExperience

package/dist/fetch-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n} from '@contentful/experience-delivery';\nimport { createDebugLogger, resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { NEW_EXO_ENTITY_TYPES_HEADERS } from './alpha-feature.js';\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  /**\n   * Arbitrary per-render metadata exposed to every resolver as\n   * `ctx.experience.metadata` and readable at render time via the framework\n   * adapter's `useExperience()` / `getExperience()`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: logs the fetch (host, ids) and the raw\n   * payload here, and threads through to `resolveExperience` (resolution steps\n   * + `resolveData` timings) and the renderer (visible missing-component box,\n   * debug fallback). A single boolean across fetch + resolve + render.\n   */\n  debug?: boolean;\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, metadata, debug } = resolveOptions;\n  const log = createDebugLogger(debug, 'client');\n\n  let client: ContentfulViewDeliveryClient;\n  if ('client' in clientOptions) {\n    client = clientOptions.client;\n    log.log('using caller-supplied delivery 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    const resolvedHost = host ?? (preview ? PREVIEW_HOST : undefined);\n    client = createClient({\n      accessToken: preview ? (previewToken as string) : accessToken,\n      host: resolvedHost,\n    });\n    log.log('created delivery client', { preview: Boolean(preview), host: resolvedHost });\n  }\n\n  log.log('fetching experience', { spaceId, environmentId, experienceId, locale });\n\n  // The alpha-feature header goes on the request as well as on clients built by\n  // `createClient`, so a caller-supplied `{ client }` also gets the ExO entity\n  // shapes this SDK reads.\n  const response = await client.experience.get(\n    spaceId,\n    environmentId,\n    experienceId,\n    { locale },\n    { headers: NEW_EXO_ENTITY_TYPES_HEADERS }\n  );\n\n  // `GetExperienceResponse` is a union of the shapes the endpoint can return;\n  // the header above pins it to `HydratedExperienceView`, which is a structural\n  // superset of `ExperiencePayload`.\n  const payload = response as ContentfulViewDelivery.HydratedExperienceView as ExperiencePayload;\n\n  log.lazy('received raw payload', () => payload);\n\n  return resolveExperience(payload, config, { metadata, debug });\n}\n"],"mappings":"AAIA,SAAS,mBAAmB,yBAAyB;AAMrD,SAAS,oCAAoC;AAC7C,SAAS,oBAAoB;AAC7B,SAAS,oBAAoB;AAkD7B,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,UAAU,MAAM,IAAI;AACpC,QAAM,MAAM,kBAAkB,OAAO,QAAQ;AAE7C,MAAI;AACJ,MAAI,YAAY,eAAe;AAC7B,aAAS,cAAc;AACvB,QAAI,IAAI,uCAAuC;AAAA,EACjD,OAAO;AACL,UAAM,EAAE,aAAa,cAAc,SAAS,KAAK,IAAI;AACrD,QAAI,WAAW,CAAC,cAAc;AAC5B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,eAAe,SAAS,UAAU,eAAe;AACvD,aAAS,aAAa;AAAA,MACpB,aAAa,UAAW,eAA0B;AAAA,MAClD,MAAM;AAAA,IACR,CAAC;AACD,QAAI,IAAI,2BAA2B,EAAE,SAAS,QAAQ,OAAO,GAAG,MAAM,aAAa,CAAC;AAAA,EACtF;AAEA,MAAI,IAAI,uBAAuB,EAAE,SAAS,eAAe,cAAc,OAAO,CAAC;AAK/E,QAAM,WAAW,MAAM,OAAO,WAAW;AAAA,IACvC;AAAA,IACA;AAAA,IACA;AAAA,IACA,EAAE,OAAO;AAAA,IACT,EAAE,SAAS,6BAA6B;AAAA,EAC1C;AAKA,QAAM,UAAU;AAEhB,MAAI,KAAK,wBAAwB,MAAM,OAAO;AAE9C,SAAO,kBAAkB,SAAS,QAAQ,EAAE,UAAU,MAAM,CAAC;AAC/D;","names":[]}
+{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n} from '@contentful/experience-delivery';\nimport { createDebugLogger, resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { NEW_EXO_ENTITY_TYPES_HEADERS } from './alpha-feature.js';\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  /**\n   * Arbitrary per-render metadata exposed to every resolver as\n   * `ctx.experience.metadata` and readable at render time via the framework\n   * adapter's `useExperience()` / `getExperience()`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: logs the fetch (host, ids) and the raw\n   * payload here, and threads through to `resolveExperience` (resolution steps\n   * + `resolveData` timings) and the renderer (visible missing-component box,\n   * debug fallback). A single boolean across fetch + resolve + render.\n   */\n  debug?: boolean;\n  /**\n   * Per-request fallback viewport for server-side design pre-resolution. Pass\n   * the same id you seed the renderer's `initialViewportId` with (e.g. a\n   * User-Agent-derived viewport) so SSR paints correct design on first render.\n   */\n  initialViewportId?: string;\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, metadata, debug, initialViewportId } = resolveOptions;\n  const log = createDebugLogger(debug, 'client');\n\n  let client: ContentfulViewDeliveryClient;\n  if ('client' in clientOptions) {\n    client = clientOptions.client;\n    log.log('using caller-supplied delivery 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    const resolvedHost = host ?? (preview ? PREVIEW_HOST : undefined);\n    client = createClient({\n      accessToken: preview ? (previewToken as string) : accessToken,\n      host: resolvedHost,\n    });\n    log.log('created delivery client', { preview: Boolean(preview), host: resolvedHost });\n  }\n\n  log.log('fetching experience', { spaceId, environmentId, experienceId, locale });\n\n  // The alpha-feature header goes on the request as well as on clients built by\n  // `createClient`, so a caller-supplied `{ client }` also gets the ExO entity\n  // shapes this SDK reads.\n  const response = await client.experience.get(\n    spaceId,\n    environmentId,\n    experienceId,\n    { locale },\n    { headers: NEW_EXO_ENTITY_TYPES_HEADERS }\n  );\n\n  // `GetExperienceResponse` is a union of the shapes the endpoint can return;\n  // the header above pins it to `HydratedExperienceView`, which is a structural\n  // superset of `ExperiencePayload`.\n  const payload = response as ContentfulViewDelivery.HydratedExperienceView as ExperiencePayload;\n\n  log.lazy('received raw payload', () => payload);\n\n  return resolveExperience(payload, config, {\n    metadata,\n    debug,\n    initialViewportId,\n  });\n}\n"],"mappings":"AAIA,SAAS,mBAAmB,yBAAyB;AAMrD,SAAS,oCAAoC;AAC7C,SAAS,oBAAoB;AAC7B,SAAS,oBAAoB;AAwD7B,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,UAAU,OAAO,kBAAkB,IAAI;AACvD,QAAM,MAAM,kBAAkB,OAAO,QAAQ;AAE7C,MAAI;AACJ,MAAI,YAAY,eAAe;AAC7B,aAAS,cAAc;AACvB,QAAI,IAAI,uCAAuC;AAAA,EACjD,OAAO;AACL,UAAM,EAAE,aAAa,cAAc,SAAS,KAAK,IAAI;AACrD,QAAI,WAAW,CAAC,cAAc;AAC5B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,eAAe,SAAS,UAAU,eAAe;AACvD,aAAS,aAAa;AAAA,MACpB,aAAa,UAAW,eAA0B;AAAA,MAClD,MAAM;AAAA,IACR,CAAC;AACD,QAAI,IAAI,2BAA2B,EAAE,SAAS,QAAQ,OAAO,GAAG,MAAM,aAAa,CAAC;AAAA,EACtF;AAEA,MAAI,IAAI,uBAAuB,EAAE,SAAS,eAAe,cAAc,OAAO,CAAC;AAK/E,QAAM,WAAW,MAAM,OAAO,WAAW;AAAA,IACvC;AAAA,IACA;AAAA,IACA;AAAA,IACA,EAAE,OAAO;AAAA,IACT,EAAE,SAAS,6BAA6B;AAAA,EAC1C;AAKA,QAAM,UAAU;AAEhB,MAAI,KAAK,wBAAwB,MAAM,OAAO;AAE9C,SAAO,kBAAkB,SAAS,QAAQ;AAAA,IACxC;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACH;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-client",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Delivery client + fetchExperience for Contentful Experiences",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
   },
   "dependencies": {
     "@contentful/experience-delivery": "1.0.0-dev.6",
-    "@contentful/experiences-sdk-core": "0.7.0"
+    "@contentful/experiences-sdk-core": "0.7.1"
   }
 }