@contentful/experiences-client 0.10.0 → 0.10.2

package/dist/index.d.ts

@@ -1,15 +1,251 @@
-import { ContentfulViewDelivery } from '@contentful/experience-delivery';
+import { ContentfulViewDeliveryClient, ContentfulViewDelivery } from '@contentful/experience-delivery';
 export { ContentfulViewDelivery, ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
-export { DestinationPreviewNotSupportedError, ExperienceFetchError } from './errors.js';
-export { CreateClientOptions, createClient } from './create-delivery-client.js';
-export { ByDestinationNodeIdExperienceOptions, ByDestinationPathExperienceOptions, ByIdExperienceOptions, DestinationRedirectResult, ExperienceOptions, ExperienceRequestExtensions, PersonalizationOptions, ResolveOptions, fetchExperience } from './fetch-experience.js';
-export { DestinationSitemapResult, FetchDestinationSitemapOptions, FetchDestinationSitemapPaginationOptions, SitemapPathItem, fetchDestinationSitemap } from './fetch-destination-sitemap.js';
-export { ExperienceResponse, readSourceMap, toExperiencePayload, toExperiencePayloadFromDestination } from './to-experience-payload.js';
-export { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from './hosts.js';
-export { ClientOptions } from './client-resolution.js';
-import '@contentful/experiences-sdk-core';
+import { ResolverConfig, PortableRenderPlan, ExperienceSourceMap, ExperiencePayload } from '@contentful/experiences-sdk-core';
+
+/**
+ * Thrown by `fetchExperience` for a fetch failure that is not "experience not
+ * found" — network failure, an invalid/expired token, a 5xx from the
+ * delivery API, etc. This failure mode is "surface clearly to the host app,"
+ * unlike the diagnostics `resolveExperience` collects for resolve/render-time
+ * issues — there's no partial payload to render around a fetch that never
+ * returned one, so a real thrown class is the right shape.
+ *
+ * `NotFoundError` (the delivery client's class, re-exported from this
+ * package) is the one exception: it passes through undisturbed so callers
+ * can route it to their framework's 404 idiom, per the existing
+ * distinguishable-404 contract.
+ *
+ * `environmentId` is `undefined` for the destination-shaped `fetchExperience`
+ * branches — the destinations delivery endpoints are space-scoped only, with
+ * no environment segment, unlike the by-id path.
+ */
+declare class ExperienceFetchError extends Error {
+    readonly spaceId: string;
+    readonly environmentId: string | undefined;
+    readonly experienceId: string;
+    constructor(message: string, options: {
+        spaceId: string;
+        environmentId?: string;
+        experienceId: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by `fetchExperience` and `fetchDestinationSitemap` when
+ * `clientOptions.preview` is `true` for a destination-shaped call
+ * (`destinationId` + `nodeId`/`path`, or a sitemap fetch). The Destinations
+ * Delivery API has no preview host or preview-token support yet, so this
+ * guards against silently hitting the production host with a preview token
+ * it doesn't accept.
+ *
+ * This is a bridge, not a permanent design: revisit once the platform ships
+ * preview support for destinations.
+ *
+ * Only fires for the inline-credentials branch of `ClientOptions`. A
+ * caller-supplied `{ client }` already ignores `preview` entirely, per that
+ * branch's existing contract.
+ */
+declare class DestinationPreviewNotSupportedError extends Error {
+    readonly spaceId: string;
+    readonly destinationId: string;
+    readonly nodeId: string | undefined;
+    readonly path: string | undefined;
+    constructor(message: string, options: {
+        spaceId: string;
+        destinationId: string;
+        nodeId?: string;
+        path?: string;
+    });
+}
+
+/** Options for the legacy functional Delivery client constructor. */
+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;
+
+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`, uses `previewToken` and the preview host; when `false` or
+     * unset, 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;
+};
+
+/** One collection order path; `-` selects descending order. Delivery validates the path. */
+type ExperienceParameterOrder = `fields.${string}` | `sys.${string}` | `-fields.${string}` | `-sys.${string}`;
+/** Runtime values for one Record parameter. Nested records and arrays are not supported. */
+type ExperienceParameterRecord = Record<string, string | number>;
+type ExperienceParameterValue = string | number | ExperienceParameterRecord;
+/** Unprefixed IDs declared in Experience.parameters and referenced as `$parameters/<id>`. */
+type ExperienceParameters = Record<string, ExperienceParameterValue>;
+
+type DeliveryExperienceRequestExtensions = ContentfulViewDelivery.GetWithOverridesExperienceRequestExtensions;
+type PersonalizationOptions = NonNullable<DeliveryExperienceRequestExtensions['personalization']>;
+type ExperienceRequestExtensions = Omit<DeliveryExperienceRequestExtensions, 'personalization'>;
+type ByIdExperienceOptions = {
+    spaceId: string;
+    environmentId: string;
+    experienceId: string;
+    locale?: string;
+    /** Values for declared Experience parameters. Refetch with new values to swap content. */
+    parameters?: ExperienceParameters;
+    /**
+     * Profile and events used by XDA to personalize the resolved Experience.
+     */
+    personalization?: PersonalizationOptions;
+    /**
+     * Additional XDA request extensions such as source maps. Supplying a defined
+     * extension switches the request to POST.
+     */
+    extensions?: ExperienceRequestExtensions;
+};
+/**
+ * Resolve an Experience by the Destination Node instead of `experienceId`
+ * The destinations delivery endpoints are space-scoped only and have no locale
+ * param, unlike the by-id path.
+ */
+type ByDestinationNodeIdExperienceOptions = {
+    spaceId: string;
+    destinationId: string;
+    nodeId: string;
+};
+/**
+ * Resolve an Experience by the absolute path wired up to a
+ * Destination Node, instead of a node id directly. Same scoping as
+ * `ByDestinationNodeIdExperienceOptions` — no `environmentId` or `locale`.
+ */
+type ByDestinationPathExperienceOptions = {
+    spaceId: string;
+    destinationId: string;
+    /** Absolute path to resolve. Must start with `/`. */
+    path: string;
+};
+type ExperienceOptions = ByIdExperienceOptions | ByDestinationNodeIdExperienceOptions | ByDestinationPathExperienceOptions;
+/**
+ * A Destination resolution that the app must act on as control flow — honor
+ * it by navigating or re-resolving at the new path — rather than a hydrated
+ * Experience to render. Modeled as a normal return value, not a thrown error,
+ * per the Destinations delivery API's own framing of a redirect response.
+ */
+interface DestinationRedirectResult {
+    redirect: {
+        path: string;
+    };
+}
+type ResolveOptions = {
+    config: ResolverConfig;
+    /**
+     * Arbitrary per-render metadata exposed to every resolver as
+     * `ctx.experience.metadata` and readable at render time via the framework
+     * adapter's `useExperience()` / `getExperience()`.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Observability switch. When on: logs the fetch (host, ids) and the raw
+     * payload here, and threads through to `resolveExperience` (resolution steps
+     * + `resolveData` timings) and the renderer (visible missing-component box,
+     * debug fallback). A single boolean across fetch + resolve + render.
+     */
+    debug?: boolean;
+};
+declare function fetchExperience(experienceOptions: ByIdExperienceOptions, clientOptions: ClientOptions, resolveOptions: ResolveOptions): Promise<PortableRenderPlan>;
+declare function fetchExperience(experienceOptions: ByDestinationNodeIdExperienceOptions, clientOptions: ClientOptions, resolveOptions: ResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+declare function fetchExperience(experienceOptions: ByDestinationPathExperienceOptions, clientOptions: ClientOptions, resolveOptions: ResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+
+type FetchDestinationSitemapOptions = {
+    spaceId: string;
+    destinationId: string;
+};
+type FetchDestinationSitemapPaginationOptions = {
+    /** Maximum number of paths to return. Defaults to `100`, maximum `1000`. */
+    limit?: number;
+    /** Cursor from a previous call's `pages.next`. Treat as opaque; don't combine with `pagePrev`. */
+    pageNext?: string;
+    /** Cursor from a previous call's `pages.prev`. Treat as opaque; don't combine with `pageNext`. */
+    pagePrev?: string;
+};
+type SitemapPathItem = {
+    /** Path this entry routes. */
+    path: string;
+    /** Flat id extracted from the entry's `experienceUrn`. */
+    experienceId: string;
+    /** Type of the Destination Node that claims this path, e.g. `"DestinationExperienceNode"`. */
+    type: string;
+};
+type DestinationSitemapResult = {
+    items: SitemapPathItem[];
+    limit: number;
+    pages: {
+        next?: string;
+        prev?: string;
+    };
+};
+/**
+ * List every routable path in a published Destination. Bulk enumeration —
+ * pairs with `fetchExperience`'s `destinationId` + `nodeId`/`path` branches,
+ * which resolve one path at a time. Does not hydrate any Experience itself
+ * and does not call `fetchExperience` internally.
+ */
+declare function fetchDestinationSitemap(destinationOptions: FetchDestinationSitemapOptions, clientOptions: ClientOptions, paginationOptions?: FetchDestinationSitemapPaginationOptions): Promise<DestinationSitemapResult>;
+
+/** Either shape the experience endpoint can return — `get()` and `getWithOverrides()` share it. */
+type ExperienceResponse = ContentfulViewDelivery.GetExperienceResponse | ContentfulViewDelivery.GetWithOverridesExperienceResponse;
+/**
+ * Narrow a delivery response to `ExperiencePayload`.
+ *
+ * The endpoint types its response as `HydratedView | HydratedExperienceView`.
+ * The alpha-feature header the delivery client always sends guarantees the
+ * latter, but TypeScript cannot know that, so callers were left casting by hand.
+ *
+ * `fetchExperience` uses this internally; it is exported for anyone driving the
+ * delivery client directly. Type-level only — no validation, no copying.
+ *
+ * A legacy-shaped response carries `componentType` / `template` links instead;
+ * `resolveExperience` reports those through `warnUnrenderableNode`.
+ */
+declare function toExperiencePayload(response: ExperienceResponse): ExperiencePayload;
+/** Read `extensions.sourceMap` off a response. `undefined` when the request did not opt in. */
+declare function readSourceMap(response: ExperienceResponse): ExperienceSourceMap | undefined;
+/**
+ * Narrow a `ResolvedDestinationExperience.experience` to `ExperiencePayload`.
+ *
+ * Same cast rationale as `toExperiencePayload` above, for the destination
+ * resolution endpoints' `HydratedExperience` shape instead of the by-id
+ * endpoints' `HydratedExperienceView`.
+ */
+declare function toExperiencePayloadFromDestination(experience: ContentfulViewDelivery.HydratedExperience): ExperiencePayload;
+
+declare const DELIVERY_HOST = "https://xdn.contentful.com";
+declare const PREVIEW_HOST = "https://preview.xdn.contentful.com";
+declare const PREVIEW_WEBSOCKET_HOST = "wss://preview.xdn.contentful.com";
+
+/** Validate and serialize events to the generated XDA request contract. */
+declare function serializePersonalization(personalization: unknown): PersonalizationOptions;
 
 declare const NotFoundError: typeof ContentfulViewDelivery.NotFoundError;
 type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;
 
-export { NotFoundError };
+export { type ByDestinationNodeIdExperienceOptions, type ByDestinationPathExperienceOptions, type ByIdExperienceOptions, type ClientOptions, type CreateClientOptions, DELIVERY_HOST, DestinationPreviewNotSupportedError, type DestinationRedirectResult, type DestinationSitemapResult, ExperienceFetchError, type ExperienceOptions, type ExperienceParameterOrder, type ExperienceParameterRecord, type ExperienceParameterValue, type ExperienceParameters, type ExperienceRequestExtensions, type ExperienceResponse, type FetchDestinationSitemapOptions, type FetchDestinationSitemapPaginationOptions, NotFoundError, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST, type PersonalizationOptions, type ResolveOptions, type SitemapPathItem, createClient, fetchDestinationSitemap, fetchExperience, readSourceMap, serializePersonalization, toExperiencePayload, toExperiencePayloadFromDestination };

package/dist/index.js

@@ -1,22 +1,315 @@
-import { ContentfulViewDelivery } from "@contentful/experience-delivery";
+// src/index.ts
+import { ContentfulViewDelivery as ContentfulViewDelivery3 } from "@contentful/experience-delivery";
 import {
-  ContentfulViewDelivery as ContentfulViewDelivery2,
-  ContentfulViewDeliveryClient
+  ContentfulViewDelivery as ContentfulViewDelivery4,
+  ContentfulViewDeliveryClient as ContentfulViewDeliveryClient2
 } from "@contentful/experience-delivery";
-const NotFoundError = ContentfulViewDelivery.NotFoundError;
-import { ExperienceFetchError, DestinationPreviewNotSupportedError } from "./errors.js";
-import { createClient } from "./create-delivery-client.js";
-import { fetchExperience } from "./fetch-experience.js";
-import { fetchDestinationSitemap } from "./fetch-destination-sitemap.js";
-import {
-  readSourceMap,
-  toExperiencePayload,
-  toExperiencePayloadFromDestination
-} from "./to-experience-payload.js";
-import { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from "./hosts.js";
+
+// src/errors.ts
+var ExperienceFetchError = class extends Error {
+  spaceId;
+  environmentId;
+  experienceId;
+  constructor(message, options) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "ExperienceFetchError";
+    this.spaceId = options.spaceId;
+    this.environmentId = options.environmentId;
+    this.experienceId = options.experienceId;
+  }
+};
+var DestinationPreviewNotSupportedError = class extends Error {
+  spaceId;
+  destinationId;
+  nodeId;
+  path;
+  constructor(message, options) {
+    super(message);
+    this.name = "DestinationPreviewNotSupportedError";
+    this.spaceId = options.spaceId;
+    this.destinationId = options.destinationId;
+    this.nodeId = options.nodeId;
+    this.path = options.path;
+  }
+};
+
+// src/create-delivery-client.ts
+import { ContentfulViewDeliveryClient } from "@contentful/experience-delivery";
+function createClient(options) {
+  const { accessToken, host, ...rest } = options;
+  return new ContentfulViewDeliveryClient({
+    ...rest,
+    token: accessToken,
+    baseUrl: host
+  });
+}
+
+// src/fetch-experience.ts
+import { ContentfulViewDelivery } from "@contentful/experience-delivery";
+
+// src/personalization.ts
+import { GetWithOverridesExperienceRequestExtensionsPersonalization as personalizationSchema } from "@contentful/experience-delivery/serialization";
+function serializePersonalization(personalization) {
+  try {
+    return personalizationSchema.parseOrThrow(personalization, {
+      unrecognizedObjectKeys: "strip"
+    });
+  } catch (cause) {
+    throw new TypeError("Invalid Experience personalization options", { cause });
+  }
+}
+
+// src/fetch-experience.ts
+import { createDebugLogger, resolveExperience } from "@contentful/experiences-sdk-core";
+
+// src/destination-guards.ts
+function assertDestinationPreviewSupported(isPreview, destination) {
+  if (!isPreview) return;
+  const { spaceId, destinationId, nodeId, path } = destination;
+  const locator = nodeId !== void 0 ? `nodeId "${nodeId}"` : `path "${path}"`;
+  throw new DestinationPreviewNotSupportedError(
+    `preview: true was combined with a destination-shaped call (destinationId "${destinationId}", ${locator}). The Destinations Delivery API does not support preview mode yet \u2014 pass preview: false (or omit it) for destination-based fetches.`,
+    { spaceId, destinationId, nodeId, path }
+  );
+}
+
+// src/hosts.ts
+var DELIVERY_HOST = "https://xdn.contentful.com";
+var PREVIEW_HOST = "https://preview.xdn.contentful.com";
+var PREVIEW_WEBSOCKET_HOST = "wss://preview.xdn.contentful.com";
+
+// src/client-resolution.ts
+function resolveDeliveryClient(clientOptions, log, callerName) {
+  if ("client" in clientOptions) {
+    log.log("using caller-supplied delivery client");
+    return clientOptions.client;
+  }
+  const { accessToken, previewToken, preview, host } = clientOptions;
+  if (preview && !previewToken) {
+    throw new Error(`${callerName}() called with preview: true but no previewToken was provided`);
+  }
+  const resolvedHost = host ?? (preview ? PREVIEW_HOST : void 0);
+  const client = createClient({
+    accessToken: preview ? previewToken : accessToken,
+    host: resolvedHost
+  });
+  log.log("created delivery client", { preview: Boolean(preview), host: resolvedHost });
+  return client;
+}
+
+// src/experience-parameters.ts
+function parameterQuery(parameters) {
+  const entries = [];
+  for (const [id, value] of Object.entries(parameters ?? {})) {
+    if (id.includes(".")) return void 0;
+    if (typeof value === "string" || typeof value === "number") {
+      entries.push([`parameter.${id}`, value]);
+    } else {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+      const leaves = Object.entries(value);
+      if (leaves.length === 0) return void 0;
+      for (const [field, leaf] of leaves) {
+        if (field.includes(".")) return void 0;
+        if (typeof leaf !== "string" && typeof leaf !== "number") return void 0;
+        entries.push([`parameter.${id}.${field}`, leaf]);
+      }
+    }
+  }
+  return Object.fromEntries(entries);
+}
+
+// src/to-experience-payload.ts
+function toExperiencePayload(response) {
+  return response;
+}
+function readSourceMap(response) {
+  const extensions = response.extensions;
+  return extensions?.sourceMap;
+}
+function toExperiencePayloadFromDestination(experience) {
+  return experience;
+}
+
+// src/fetch-experience.ts
+async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
+  const { config, metadata, debug } = resolveOptions;
+  const log = createDebugLogger(debug, "client");
+  if (!("client" in clientOptions) && "destinationId" in experienceOptions) {
+    const { spaceId: spaceId2, destinationId } = experienceOptions;
+    const locator = "nodeId" in experienceOptions ? { nodeId: experienceOptions.nodeId } : { path: experienceOptions.path };
+    assertDestinationPreviewSupported(clientOptions.preview, {
+      spaceId: spaceId2,
+      destinationId,
+      ...locator
+    });
+  }
+  const client = resolveDeliveryClient(clientOptions, log, "fetchExperience");
+  if ("nodeId" in experienceOptions) {
+    const { spaceId: spaceId2, destinationId, nodeId } = experienceOptions;
+    return fetchByDestination(
+      { spaceId: spaceId2, destinationId, locator: nodeId },
+      () => client.destination.resolveByNodeId(spaceId2, destinationId, nodeId),
+      log,
+      { config, metadata, debug }
+    );
+  }
+  if ("path" in experienceOptions) {
+    const { spaceId: spaceId2, destinationId, path } = experienceOptions;
+    return fetchByDestination(
+      { spaceId: spaceId2, destinationId, locator: path },
+      () => client.destination.resolveByPath(spaceId2, destinationId, { path }),
+      log,
+      { config, metadata, debug }
+    );
+  }
+  const { spaceId, environmentId, experienceId, locale, personalization, extensions } = experienceOptions;
+  log.log("fetching experience", {
+    spaceId,
+    environmentId,
+    experienceId,
+    locale,
+    // avoiding log any personalization sensitive data
+    personalization: personalization !== void 0,
+    extensions
+  });
+  const response = await fetchByExperienceId(client, experienceOptions);
+  const payload = toExperiencePayload(response);
+  log.lazy("received raw payload", () => payload);
+  return resolveExperience(payload, config, { metadata, debug });
+}
+async function fetchByExperienceId(client, options) {
+  const { spaceId, environmentId, experienceId, locale, parameters, personalization, extensions } = options;
+  const requestExtensions = { ...extensions };
+  if (personalization !== void 0) {
+    requestExtensions.personalization = serializePersonalization(personalization);
+  }
+  try {
+    const queryParams = parameterQuery(parameters);
+    if (hasRequestExtensions(requestExtensions) || queryParams === void 0) {
+      const request = {
+        locale,
+        extensions: requestExtensions,
+        ...parameters === void 0 ? {} : { parameters }
+      };
+      return await client.experience.getWithOverrides(
+        spaceId,
+        environmentId,
+        experienceId,
+        request
+      );
+    }
+    if (Object.keys(queryParams).length > 0) {
+      return await client.experience.get(
+        spaceId,
+        environmentId,
+        experienceId,
+        { locale },
+        {
+          queryParams
+        }
+      );
+    }
+    return await client.experience.get(spaceId, environmentId, experienceId, { locale });
+  } catch (err) {
+    if (err instanceof ContentfulViewDelivery.NotFoundError) {
+      throw err;
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ExperienceFetchError(
+      `Failed to fetch Experience "${experienceId}" (space "${spaceId}", environment "${environmentId}"): ${reason}. Check network connectivity, the access token, and that the space/environment/experience ids are correct.`,
+      { spaceId, environmentId, experienceId, cause: err }
+    );
+  }
+}
+async function fetchByDestination(identity, resolve, log, resolveOptions) {
+  const { spaceId, destinationId, locator } = identity;
+  const { config, metadata, debug } = resolveOptions;
+  log.log("resolving destination experience", { spaceId, destinationId, locator });
+  let response;
+  try {
+    response = await resolve();
+  } catch (err) {
+    if (err instanceof ContentfulViewDelivery.NotFoundError) {
+      throw err;
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ExperienceFetchError(
+      `Failed to resolve Destination "${destinationId}" at "${locator}" (space "${spaceId}"): ${reason}. Check network connectivity, the access token, and that the space/destination/node-or-path values are correct.`,
+      { spaceId, experienceId: locator, cause: err }
+    );
+  }
+  if ("redirect" in response) {
+    log.log("destination resolved to a redirect", response.redirect);
+    return { redirect: response.redirect };
+  }
+  const [firstExperience] = response.experiences;
+  if (!firstExperience) {
+    throw new ExperienceFetchError(
+      `Destination "${destinationId}" resolved "${locator}" to zero Experiences (space "${spaceId}"). Expected exactly one hydrated Experience or a redirect.`,
+      { spaceId, experienceId: locator }
+    );
+  }
+  const payload = toExperiencePayloadFromDestination(firstExperience.experience);
+  log.lazy("received raw payload", () => payload);
+  return resolveExperience(payload, config, {
+    metadata,
+    debug
+  });
+}
+function hasRequestExtensions(extensions) {
+  return extensions !== void 0 && Object.values(extensions).some((extension) => extension !== void 0);
+}
+
+// src/fetch-destination-sitemap.ts
+import { ContentfulViewDelivery as ContentfulViewDelivery2 } from "@contentful/experience-delivery";
+import { createDebugLogger as createDebugLogger2 } from "@contentful/experiences-sdk-core";
+async function fetchDestinationSitemap(destinationOptions, clientOptions, paginationOptions = {}) {
+  const { spaceId, destinationId } = destinationOptions;
+  const log = createDebugLogger2(false, "client");
+  if (!("client" in clientOptions)) {
+    assertDestinationPreviewSupported(clientOptions.preview, { spaceId, destinationId });
+  }
+  const client = resolveDeliveryClient(clientOptions, log, "fetchDestinationSitemap");
+  const { limit, pageNext, pagePrev } = paginationOptions;
+  let response;
+  try {
+    response = await client.destination.sitemap(spaceId, destinationId, {
+      limit,
+      pageNext,
+      pagePrev
+    });
+  } catch (err) {
+    if (err instanceof ContentfulViewDelivery2.NotFoundError) {
+      throw err;
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ExperienceFetchError(
+      `Failed to fetch sitemap for Destination "${destinationId}" (space "${spaceId}"): ${reason}. Check network connectivity, the access token, and that the space/destination ids are correct.`,
+      { spaceId, experienceId: destinationId, cause: err }
+    );
+  }
+  const result = {
+    items: response.paths.items.map((item) => ({
+      path: item.path,
+      experienceId: extractIdFromUrn(item.experienceUrn),
+      type: item.sys.type
+    })),
+    limit: response.paths.limit,
+    pages: response.paths.pages
+  };
+  log.lazy("received sitemap page", () => result);
+  return result;
+}
+function extractIdFromUrn(urn) {
+  const segments = urn.split("/").filter((s) => s.length > 0);
+  return segments[segments.length - 1] ?? urn;
+}
+
+// src/index.ts
+var NotFoundError = ContentfulViewDelivery3.NotFoundError;
 export {
-  ContentfulViewDelivery2 as ContentfulViewDelivery,
-  ContentfulViewDeliveryClient,
+  ContentfulViewDelivery4 as ContentfulViewDelivery,
+  ContentfulViewDeliveryClient2 as ContentfulViewDeliveryClient,
   DELIVERY_HOST,
   DestinationPreviewNotSupportedError,
   ExperienceFetchError,
@@ -27,6 +320,7 @@ export {
   fetchDestinationSitemap,
   fetchExperience,
   readSourceMap,
+  serializePersonalization,
   toExperiencePayload,
   toExperiencePayloadFromDestination
 };