@contentful/experiences-client 0.10.0 → 0.10.1

package/dist/index.d.mts

@@ -0,0 +1,241 @@
+import { ContentfulViewDeliveryClient, ContentfulViewDelivery } from '@contentful/experience-delivery';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
+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;
+};
+
+type DeliveryExperienceRequestExtensions = ContentfulViewDelivery.GetWithOverridesExperienceRequestExtensions;
+type PersonalizationOptions = NonNullable<DeliveryExperienceRequestExtensions['personalization']>;
+type ExperienceRequestExtensions = Omit<DeliveryExperienceRequestExtensions, 'personalization'>;
+type ByIdExperienceOptions = {
+    spaceId: string;
+    environmentId: string;
+    experienceId: string;
+    locale?: string;
+    /**
+     * 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 { type ByDestinationNodeIdExperienceOptions, type ByDestinationPathExperienceOptions, type ByIdExperienceOptions, type ClientOptions, type CreateClientOptions, DELIVERY_HOST, DestinationPreviewNotSupportedError, type DestinationRedirectResult, type DestinationSitemapResult, ExperienceFetchError, type ExperienceOptions, 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.d.ts

@@ -1,15 +1,241 @@
-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;
+};
+
+type DeliveryExperienceRequestExtensions = ContentfulViewDelivery.GetWithOverridesExperienceRequestExtensions;
+type PersonalizationOptions = NonNullable<DeliveryExperienceRequestExtensions['personalization']>;
+type ExperienceRequestExtensions = Omit<DeliveryExperienceRequestExtensions, 'personalization'>;
+type ByIdExperienceOptions = {
+    spaceId: string;
+    environmentId: string;
+    experienceId: string;
+    locale?: string;
+    /**
+     * 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 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 };