@contentful/experiences-client 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.4.9 (2026-09-28)
+
+### 🚀 Features
+
+- add shared Experiences client runtime ([#206](https://github.com/contentful/experiences/pull/206))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.8.7
+
+## 0.4.8 (2026-09-22)
+
+### 🚀 Features
+
+- guard against preview mode with destination fetches [AIS-568] ([#201](https://github.com/contentful/experiences/pull/201))
+
 ## 0.4.7 (2026-09-22)
 
 ### 🚀 Features

package/README.md

@@ -2,12 +2,36 @@
 
 > **Internal package.** Published to npm so framework adapters can resolve it at install time, but you're not meant to import it directly. It comes in transitively via the framework adapter (`@contentful/experiences-react`, `@contentful/experiences-svelte`, etc.).
 
-Isolates `@contentful/experience-delivery` — the generated experience delivery client — so that `@contentful/experiences-sdk-core` stays zero-dep and framework adapters that don't need network access don't pull it in transitively.
+Isolates `@contentful/experience-delivery` — the generated experience delivery client — so that `@contentful/experiences-sdk-core` stays dependency-free and framework adapters that don't need network access don't pull it in transitively. It also owns the lower-layer shared `ContentfulExperiences` runtime for future Node/Web SDKs and event construction.
+
+`ContentfulExperiences` is intentionally not re-exported by framework adapters
+and is not a new application-facing adapter API. The existing free functions
+remain supported for adapter and application integration.
 
 ---
 
 ## What's in here
 
+### Shared lower-layer runtime
+
+`ContentfulExperiences` is an internal shared runtime contract for future
+Node/Web SDKs. Construct it with a space, environment, resolver configuration,
+and a delivery client source; optionally provide a preview client source. It
+retains those clients, merges configured resolve defaults with per-call options,
+and exposes `resolveExperience` and by-id/destination `fetchExperience` methods.
+Calling `fetchExperience` with `preview: true` requires the optional preview
+client.
+
+The runtime constructs and owns one `EventBuilder`. Its defaults are server
+channel, this SDK's library identity, and the runtime locale; callers may
+override the supported event-builder configuration. This is the owner of event
+construction for the lower layer, rather than Core.
+
+This package's direct dependencies are the generated delivery client,
+`@contentful/optimization-api-client` (event schemas and logger), `es-toolkit`
+(event-property merging), and `zod` (event argument schemas), in addition to
+Core. None of those dependencies are introduced into Core.
+
 ### `fetchExperience(experienceOptions, clientOptions, resolveOptions)`
 
 The primary fetch + resolve entry point. Fetches an Experience payload from the Experience Delivery API and resolves it into a `PortableRenderPlan` in one call.

package/dist/contentful-experiences.d.ts

@@ -0,0 +1,69 @@
+import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
+import { ExperiencePayload, PortableRenderPlan, ResolverConfig } from '@contentful/experiences-sdk-core';
+import EventBuilder, { EventBuilderConfig } from './event-builder.js';
+import { DestinationRedirectResult } from './fetch-experience.js';
+import { CreateClientOptions } from './create-client.js';
+import '@contentful/optimization-api-client/api-schemas';
+import 'zod/mini';
+
+type RuntimeClientSource = CreateClientOptions | {
+    client: ContentfulViewDeliveryClient;
+};
+type RuntimeResolveOptions = {
+    metadata?: Record<string, unknown>;
+    debug?: boolean;
+    initialViewportId?: string;
+};
+type RuntimeEventBuilderConfig = Omit<EventBuilderConfig, 'channel' | 'library'> & {
+    channel?: EventBuilderConfig['channel'];
+    library?: Partial<EventBuilderConfig['library']>;
+};
+type RuntimeFetchExperienceOptions = {
+    experienceId: string;
+    locale?: string;
+    preview?: boolean;
+    withSourceMap?: boolean;
+};
+type RuntimeFetchByDestinationNodeOptions = {
+    destinationId: string;
+    nodeId: string;
+};
+type RuntimeFetchByDestinationPathOptions = {
+    destinationId: string;
+    path: string;
+};
+/** Structural contract implemented by the Client runtime. */
+interface ExperienceRuntime {
+    readonly spaceId: string;
+    readonly environmentId: string;
+    readonly locale: string | undefined;
+    readonly eventBuilder: EventBuilder;
+    resolveExperience(payload: ExperiencePayload, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan>;
+    fetchExperience(options: RuntimeFetchExperienceOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan>;
+    fetchByDestinationNode(options: RuntimeFetchByDestinationNodeOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+    fetchByDestinationPath(options: RuntimeFetchByDestinationPathOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+}
+type ContentfulExperiencesConfig = {
+    spaceId: string;
+    environmentId: string;
+    locale?: string;
+    resolverConfig: ResolverConfig;
+    delivery: RuntimeClientSource;
+    preview?: RuntimeClientSource;
+    resolveDefaults?: Pick<RuntimeResolveOptions, 'metadata' | 'debug'>;
+    eventBuilder?: RuntimeEventBuilderConfig;
+};
+declare class ContentfulExperiences implements ExperienceRuntime {
+    #private;
+    readonly spaceId: string;
+    readonly environmentId: string;
+    readonly locale: string | undefined;
+    readonly eventBuilder: EventBuilder;
+    constructor(config: ContentfulExperiencesConfig);
+    resolveExperience(payload: ExperiencePayload, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan>;
+    fetchExperience(options: RuntimeFetchExperienceOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan>;
+    fetchByDestinationNode(options: RuntimeFetchByDestinationNodeOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+    fetchByDestinationPath(options: RuntimeFetchByDestinationPathOptions, resolveOptions?: RuntimeResolveOptions): Promise<PortableRenderPlan | DestinationRedirectResult>;
+}
+
+export { ContentfulExperiences, type ContentfulExperiencesConfig, type ExperienceRuntime, type RuntimeClientSource, type RuntimeEventBuilderConfig, type RuntimeFetchByDestinationNodeOptions, type RuntimeFetchByDestinationPathOptions, type RuntimeFetchExperienceOptions, type RuntimeResolveOptions };

package/dist/contentful-experiences.js

@@ -0,0 +1,87 @@
+import { resolveExperience as resolveCoreExperience } from "@contentful/experiences-sdk-core";
+import EventBuilder from "./event-builder.js";
+import { createClient } from "./create-client.js";
+import { fetchExperience } from "./fetch-experience.js";
+import { PREVIEW_HOST } from "./hosts.js";
+import { DEFAULT_EVENT_CONTEXT_LIBRARY } from "./sdk-info.js";
+class ContentfulExperiences {
+  spaceId;
+  environmentId;
+  locale;
+  eventBuilder;
+  #resolverConfig;
+  #deliveryClient;
+  #previewClient;
+  #resolveDefaults;
+  constructor(config) {
+    this.spaceId = config.spaceId;
+    this.environmentId = config.environmentId;
+    this.locale = config.locale;
+    this.#resolverConfig = config.resolverConfig;
+    this.#deliveryClient = resolveClient(config.delivery);
+    this.#previewClient = config.preview === void 0 ? void 0 : resolveClient(config.preview, PREVIEW_HOST);
+    this.#resolveDefaults = config.resolveDefaults ?? {};
+    const eventBuilder = config.eventBuilder ?? {};
+    this.eventBuilder = new EventBuilder({
+      ...eventBuilder,
+      channel: eventBuilder.channel ?? "server",
+      library: { ...DEFAULT_EVENT_CONTEXT_LIBRARY, ...eventBuilder.library },
+      getLocale: eventBuilder.getLocale ?? (() => this.locale)
+    });
+  }
+  resolveExperience(payload, resolveOptions) {
+    return resolveCoreExperience(
+      payload,
+      this.#resolverConfig,
+      this.#mergeResolveOptions(resolveOptions)
+    );
+  }
+  fetchExperience(options, resolveOptions) {
+    if (options.preview === true && this.#previewClient === void 0) {
+      throw new Error(
+        "fetchExperience() called with preview: true but this runtime has no preview client"
+      );
+    }
+    return fetchExperience(
+      {
+        spaceId: this.spaceId,
+        environmentId: this.environmentId,
+        experienceId: options.experienceId,
+        locale: options.locale ?? this.locale,
+        withSourceMap: options.withSourceMap
+      },
+      {
+        client: options.preview ? this.#previewClient : this.#deliveryClient
+      },
+      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }
+    );
+  }
+  fetchByDestinationNode(options, resolveOptions) {
+    return fetchExperience(
+      { spaceId: this.spaceId, destinationId: options.destinationId, nodeId: options.nodeId },
+      { client: this.#deliveryClient },
+      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }
+    );
+  }
+  fetchByDestinationPath(options, resolveOptions) {
+    return fetchExperience(
+      { spaceId: this.spaceId, destinationId: options.destinationId, path: options.path },
+      { client: this.#deliveryClient },
+      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }
+    );
+  }
+  #mergeResolveOptions(options) {
+    return {
+      metadata: { ...this.#resolveDefaults.metadata, ...options?.metadata },
+      debug: options?.debug ?? this.#resolveDefaults.debug,
+      initialViewportId: options?.initialViewportId
+    };
+  }
+}
+function resolveClient(source, defaultHost) {
+  return "client" in source ? source.client : createClient({ ...source, host: source.host ?? defaultHost });
+}
+export {
+  ContentfulExperiences
+};
+//# sourceMappingURL=contentful-experiences.js.map

package/dist/contentful-experiences.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contentful-experiences.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience as resolveCoreExperience } from '@contentful/experiences-sdk-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport EventBuilder from './event-builder.js';\nimport type { EventBuilderConfig } from './event-builder.js';\nimport { createClient } from './create-client.js';\nimport { fetchExperience, type DestinationRedirectResult } from './fetch-experience.js';\nimport type { CreateClientOptions } from './create-client.js';\nimport { PREVIEW_HOST } from './hosts.js';\nimport { DEFAULT_EVENT_CONTEXT_LIBRARY } from './sdk-info.js';\n\nexport type RuntimeClientSource = CreateClientOptions | { client: ContentfulViewDeliveryClient };\n\nexport type RuntimeResolveOptions = {\n  metadata?: Record<string, unknown>;\n  debug?: boolean;\n  initialViewportId?: string;\n};\n\nexport type RuntimeEventBuilderConfig = Omit<EventBuilderConfig, 'channel' | 'library'> & {\n  channel?: EventBuilderConfig['channel'];\n  library?: Partial<EventBuilderConfig['library']>;\n};\n\nexport type RuntimeFetchExperienceOptions = {\n  experienceId: string;\n  locale?: string;\n  preview?: boolean;\n  withSourceMap?: boolean;\n};\n\nexport type RuntimeFetchByDestinationNodeOptions = {\n  destinationId: string;\n  nodeId: string;\n};\n\nexport type RuntimeFetchByDestinationPathOptions = {\n  destinationId: string;\n  path: string;\n};\n\n/** Structural contract implemented by the Client runtime. */\nexport interface ExperienceRuntime {\n  readonly spaceId: string;\n  readonly environmentId: string;\n  readonly locale: string | undefined;\n  readonly eventBuilder: EventBuilder;\n  resolveExperience(\n    payload: ExperiencePayload,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan>;\n  fetchExperience(\n    options: RuntimeFetchExperienceOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan>;\n  fetchByDestinationNode(\n    options: RuntimeFetchByDestinationNodeOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan | DestinationRedirectResult>;\n  fetchByDestinationPath(\n    options: RuntimeFetchByDestinationPathOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan | DestinationRedirectResult>;\n}\n\nexport type ContentfulExperiencesConfig = {\n  spaceId: string;\n  environmentId: string;\n  locale?: string;\n  resolverConfig: ResolverConfig;\n  delivery: RuntimeClientSource;\n  preview?: RuntimeClientSource;\n  resolveDefaults?: Pick<RuntimeResolveOptions, 'metadata' | 'debug'>;\n  eventBuilder?: RuntimeEventBuilderConfig;\n};\n\nexport class ContentfulExperiences implements ExperienceRuntime {\n  readonly spaceId: string;\n  readonly environmentId: string;\n  readonly locale: string | undefined;\n  readonly eventBuilder: EventBuilder;\n\n  readonly #resolverConfig: ResolverConfig;\n  readonly #deliveryClient: ContentfulViewDeliveryClient;\n  readonly #previewClient: ContentfulViewDeliveryClient | undefined;\n  readonly #resolveDefaults: Pick<RuntimeResolveOptions, 'metadata' | 'debug'>;\n\n  constructor(config: ContentfulExperiencesConfig) {\n    this.spaceId = config.spaceId;\n    this.environmentId = config.environmentId;\n    this.locale = config.locale;\n    this.#resolverConfig = config.resolverConfig;\n    this.#deliveryClient = resolveClient(config.delivery);\n    this.#previewClient =\n      config.preview === undefined ? undefined : resolveClient(config.preview, PREVIEW_HOST);\n    this.#resolveDefaults = config.resolveDefaults ?? {};\n\n    const eventBuilder = config.eventBuilder ?? {};\n    this.eventBuilder = new EventBuilder({\n      ...eventBuilder,\n      channel: eventBuilder.channel ?? 'server',\n      library: { ...DEFAULT_EVENT_CONTEXT_LIBRARY, ...eventBuilder.library },\n      getLocale: eventBuilder.getLocale ?? (() => this.locale),\n    });\n  }\n\n  resolveExperience(\n    payload: ExperiencePayload,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan> {\n    return resolveCoreExperience(\n      payload,\n      this.#resolverConfig,\n      this.#mergeResolveOptions(resolveOptions)\n    );\n  }\n\n  fetchExperience(\n    options: RuntimeFetchExperienceOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan> {\n    if (options.preview === true && this.#previewClient === undefined) {\n      throw new Error(\n        'fetchExperience() called with preview: true but this runtime has no preview client'\n      );\n    }\n    return fetchExperience(\n      {\n        spaceId: this.spaceId,\n        environmentId: this.environmentId,\n        experienceId: options.experienceId,\n        locale: options.locale ?? this.locale,\n        withSourceMap: options.withSourceMap,\n      },\n      {\n        client: options.preview\n          ? (this.#previewClient as ContentfulViewDeliveryClient)\n          : this.#deliveryClient,\n      },\n      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }\n    );\n  }\n\n  fetchByDestinationNode(\n    options: RuntimeFetchByDestinationNodeOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan | DestinationRedirectResult> {\n    return fetchExperience(\n      { spaceId: this.spaceId, destinationId: options.destinationId, nodeId: options.nodeId },\n      { client: this.#deliveryClient },\n      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }\n    );\n  }\n\n  fetchByDestinationPath(\n    options: RuntimeFetchByDestinationPathOptions,\n    resolveOptions?: RuntimeResolveOptions\n  ): Promise<PortableRenderPlan | DestinationRedirectResult> {\n    return fetchExperience(\n      { spaceId: this.spaceId, destinationId: options.destinationId, path: options.path },\n      { client: this.#deliveryClient },\n      { config: this.#resolverConfig, ...this.#mergeResolveOptions(resolveOptions) }\n    );\n  }\n\n  #mergeResolveOptions(options: RuntimeResolveOptions | undefined): RuntimeResolveOptions {\n    return {\n      metadata: { ...this.#resolveDefaults.metadata, ...options?.metadata },\n      debug: options?.debug ?? this.#resolveDefaults.debug,\n      initialViewportId: options?.initialViewportId,\n    };\n  }\n}\n\nfunction resolveClient(\n  source: RuntimeClientSource,\n  defaultHost?: string\n): ContentfulViewDeliveryClient {\n  return 'client' in source\n    ? source.client\n    : createClient({ ...source, host: source.host ?? defaultHost });\n}\n"],"mappings":"AACA,SAAS,qBAAqB,6BAA6B;AAM3D,OAAO,kBAAkB;AAEzB,SAAS,oBAAoB;AAC7B,SAAS,uBAAuD;AAEhE,SAAS,oBAAoB;AAC7B,SAAS,qCAAqC;AAmEvC,MAAM,sBAAmD;AAAA,EACrD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,QAAqC;AAC/C,SAAK,UAAU,OAAO;AACtB,SAAK,gBAAgB,OAAO;AAC5B,SAAK,SAAS,OAAO;AACrB,SAAK,kBAAkB,OAAO;AAC9B,SAAK,kBAAkB,cAAc,OAAO,QAAQ;AACpD,SAAK,iBACH,OAAO,YAAY,SAAY,SAAY,cAAc,OAAO,SAAS,YAAY;AACvF,SAAK,mBAAmB,OAAO,mBAAmB,CAAC;AAEnD,UAAM,eAAe,OAAO,gBAAgB,CAAC;AAC7C,SAAK,eAAe,IAAI,aAAa;AAAA,MACnC,GAAG;AAAA,MACH,SAAS,aAAa,WAAW;AAAA,MACjC,SAAS,EAAE,GAAG,+BAA+B,GAAG,aAAa,QAAQ;AAAA,MACrE,WAAW,aAAa,cAAc,MAAM,KAAK;AAAA,IACnD,CAAC;AAAA,EACH;AAAA,EAEA,kBACE,SACA,gBAC6B;AAC7B,WAAO;AAAA,MACL;AAAA,MACA,KAAK;AAAA,MACL,KAAK,qBAAqB,cAAc;AAAA,IAC1C;AAAA,EACF;AAAA,EAEA,gBACE,SACA,gBAC6B;AAC7B,QAAI,QAAQ,YAAY,QAAQ,KAAK,mBAAmB,QAAW;AACjE,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,MACL;AAAA,QACE,SAAS,KAAK;AAAA,QACd,eAAe,KAAK;AAAA,QACpB,cAAc,QAAQ;AAAA,QACtB,QAAQ,QAAQ,UAAU,KAAK;AAAA,QAC/B,eAAe,QAAQ;AAAA,MACzB;AAAA,MACA;AAAA,QACE,QAAQ,QAAQ,UACX,KAAK,iBACN,KAAK;AAAA,MACX;AAAA,MACA,EAAE,QAAQ,KAAK,iBAAiB,GAAG,KAAK,qBAAqB,cAAc,EAAE;AAAA,IAC/E;AAAA,EACF;AAAA,EAEA,uBACE,SACA,gBACyD;AACzD,WAAO;AAAA,MACL,EAAE,SAAS,KAAK,SAAS,eAAe,QAAQ,eAAe,QAAQ,QAAQ,OAAO;AAAA,MACtF,EAAE,QAAQ,KAAK,gBAAgB;AAAA,MAC/B,EAAE,QAAQ,KAAK,iBAAiB,GAAG,KAAK,qBAAqB,cAAc,EAAE;AAAA,IAC/E;AAAA,EACF;AAAA,EAEA,uBACE,SACA,gBACyD;AACzD,WAAO;AAAA,MACL,EAAE,SAAS,KAAK,SAAS,eAAe,QAAQ,eAAe,MAAM,QAAQ,KAAK;AAAA,MAClF,EAAE,QAAQ,KAAK,gBAAgB;AAAA,MAC/B,EAAE,QAAQ,KAAK,iBAAiB,GAAG,KAAK,qBAAqB,cAAc,EAAE;AAAA,IAC/E;AAAA,EACF;AAAA,EAEA,qBAAqB,SAAmE;AACtF,WAAO;AAAA,MACL,UAAU,EAAE,GAAG,KAAK,iBAAiB,UAAU,GAAG,SAAS,SAAS;AAAA,MACpE,OAAO,SAAS,SAAS,KAAK,iBAAiB;AAAA,MAC/C,mBAAmB,SAAS;AAAA,IAC9B;AAAA,EACF;AACF;AAEA,SAAS,cACP,QACA,aAC8B;AAC9B,SAAO,YAAY,SACf,OAAO,SACP,aAAa,EAAE,GAAG,QAAQ,MAAM,OAAO,QAAQ,YAAY,CAAC;AAClE;","names":[]}

package/dist/errors.d.ts

@@ -26,5 +26,31 @@ declare class ExperienceFetchError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Thrown by `fetchExperience` when `clientOptions.preview` is `true` and
+ * `experienceOptions` is destination-shaped (`destinationId` + `nodeId` or
+ * `destinationId` + `path`). 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;
+    });
+}
 
-export { ExperienceFetchError };
+export { DestinationPreviewNotSupportedError, ExperienceFetchError };

package/dist/errors.js

@@ -10,7 +10,22 @@ class ExperienceFetchError extends Error {
     this.experienceId = options.experienceId;
   }
 }
+class DestinationPreviewNotSupportedError 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;
+  }
+}
 export {
+  DestinationPreviewNotSupportedError,
   ExperienceFetchError
 };
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Thrown by `fetchExperience` for a fetch failure that is not \"experience not\n * found\" — network failure, an invalid/expired token, a 5xx from the\n * delivery API, etc. This failure mode is \"surface clearly to the host app,\"\n * unlike the diagnostics `resolveExperience` collects for resolve/render-time\n * issues — there's no partial payload to render around a fetch that never\n * returned one, so a real thrown class is the right shape.\n *\n * `NotFoundError` (the delivery client's class, re-exported from this\n * package) is the one exception: it passes through undisturbed so callers\n * can route it to their framework's 404 idiom, per the existing\n * distinguishable-404 contract.\n *\n * `environmentId` is `undefined` for the destination-shaped `fetchExperience`\n * branches — the destinations delivery endpoints are space-scoped only, with\n * no environment segment, unlike the by-id path.\n */\nexport class ExperienceFetchError extends Error {\n  readonly spaceId: string;\n  readonly environmentId: string | undefined;\n  readonly experienceId: string;\n\n  constructor(\n    message: string,\n    options: {\n      spaceId: string;\n      environmentId?: string;\n      experienceId: string;\n      cause?: unknown;\n    }\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.name = 'ExperienceFetchError';\n    this.spaceId = options.spaceId;\n    this.environmentId = options.environmentId;\n    this.experienceId = options.experienceId;\n  }\n}\n"],"mappings":"AAiBO,MAAM,6BAA6B,MAAM;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAMA;AACA,UAAM,SAAS,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,MAAS;AACjF,SAAK,OAAO;AACZ,SAAK,UAAU,QAAQ;AACvB,SAAK,gBAAgB,QAAQ;AAC7B,SAAK,eAAe,QAAQ;AAAA,EAC9B;AACF;","names":[]}
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Thrown by `fetchExperience` for a fetch failure that is not \"experience not\n * found\" — network failure, an invalid/expired token, a 5xx from the\n * delivery API, etc. This failure mode is \"surface clearly to the host app,\"\n * unlike the diagnostics `resolveExperience` collects for resolve/render-time\n * issues — there's no partial payload to render around a fetch that never\n * returned one, so a real thrown class is the right shape.\n *\n * `NotFoundError` (the delivery client's class, re-exported from this\n * package) is the one exception: it passes through undisturbed so callers\n * can route it to their framework's 404 idiom, per the existing\n * distinguishable-404 contract.\n *\n * `environmentId` is `undefined` for the destination-shaped `fetchExperience`\n * branches — the destinations delivery endpoints are space-scoped only, with\n * no environment segment, unlike the by-id path.\n */\nexport class ExperienceFetchError extends Error {\n  readonly spaceId: string;\n  readonly environmentId: string | undefined;\n  readonly experienceId: string;\n\n  constructor(\n    message: string,\n    options: {\n      spaceId: string;\n      environmentId?: string;\n      experienceId: string;\n      cause?: unknown;\n    }\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.name = 'ExperienceFetchError';\n    this.spaceId = options.spaceId;\n    this.environmentId = options.environmentId;\n    this.experienceId = options.experienceId;\n  }\n}\n\n/**\n * Thrown by `fetchExperience` when `clientOptions.preview` is `true` and\n * `experienceOptions` is destination-shaped (`destinationId` + `nodeId` or\n * `destinationId` + `path`). The Destinations Delivery API has no preview\n * host or preview-token support yet, so this guards against silently hitting the\n * production host with a preview token it doesn't accept.\n *\n * This is a bridge, not a permanent design: revisit once the platform ships\n * preview support for destinations.\n *\n * Only fires for the inline-credentials branch of `ClientOptions`. A\n * caller-supplied `{ client }` already ignores `preview` entirely, per that\n * branch's existing contract.\n */\nexport class DestinationPreviewNotSupportedError extends Error {\n  readonly spaceId: string;\n  readonly destinationId: string;\n  readonly nodeId: string | undefined;\n  readonly path: string | undefined;\n\n  constructor(\n    message: string,\n    options: { spaceId: string; destinationId: string; nodeId?: string; path?: string }\n  ) {\n    super(message);\n    this.name = 'DestinationPreviewNotSupportedError';\n    this.spaceId = options.spaceId;\n    this.destinationId = options.destinationId;\n    this.nodeId = options.nodeId;\n    this.path = options.path;\n  }\n}\n"],"mappings":"AAiBO,MAAM,6BAA6B,MAAM;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SAMA;AACA,UAAM,SAAS,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,MAAS;AACjF,SAAK,OAAO;AACZ,SAAK,UAAU,QAAQ;AACvB,SAAK,gBAAgB,QAAQ;AAC7B,SAAK,eAAe,QAAQ;AAAA,EAC9B;AACF;AAgBO,MAAM,4CAA4C,MAAM;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACE,SACA,SACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,UAAU,QAAQ;AACvB,SAAK,gBAAgB,QAAQ;AAC7B,SAAK,SAAS,QAAQ;AACtB,SAAK,OAAO,QAAQ;AAAA,EACtB;AACF;","names":[]}

package/dist/event-builder.d.ts

@@ -0,0 +1,444 @@
+import { App, Channel, Library, Page, UniversalEventProperties, ExoViewEvent, ExoClickEvent, ExoHoverEvent, ViewEvent, IdentifyEvent, PageViewEvent, TrackEvent } from '@contentful/optimization-api-client/api-schemas';
+import * as z from 'zod/mini';
+
+interface EventBuilderConfig {
+    app?: App;
+    channel: Channel;
+    library: Library;
+    getLocale?: () => string | undefined;
+    getPageProperties?: () => Page;
+    getUserAgent?: () => string | undefined;
+    getConsent?: () => boolean | undefined;
+}
+declare const UniversalEventBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs>;
+declare const InteractionBuilderArgsBase: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entityId: z.ZodMiniString<string>;
+    entityKind: z.ZodMiniEnum<{
+        Experience: "Experience";
+        Fragment: "Fragment";
+        InlineFragment: "InlineFragment";
+        InlineComponent: "InlineComponent";
+    }>;
+    entityKindId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entryIds: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+    optimizationId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    parameters: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    parentExperienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+type InteractionBuilderArgsBase = z.infer<typeof InteractionBuilderArgsBase>;
+declare const ViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entityId: z.ZodMiniString<string>;
+    entityKind: z.ZodMiniEnum<{
+        Experience: "Experience";
+        Fragment: "Fragment";
+        InlineFragment: "InlineFragment";
+        InlineComponent: "InlineComponent";
+    }>;
+    entityKindId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entryIds: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+    optimizationId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    parameters: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    parentExperienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    viewId: z.ZodMiniString<string>;
+    viewDurationMs: z.ZodMiniInt;
+}, z.core.$strip>;
+type ViewBuilderArgs = z.infer<typeof ViewBuilderArgs>;
+declare const ClickBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entityId: z.ZodMiniString<string>;
+    entityKind: z.ZodMiniEnum<{
+        Experience: "Experience";
+        Fragment: "Fragment";
+        InlineFragment: "InlineFragment";
+        InlineComponent: "InlineComponent";
+    }>;
+    entityKindId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entryIds: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+    optimizationId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    parameters: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    parentExperienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+type ClickBuilderArgs = z.infer<typeof ClickBuilderArgs>;
+declare const HoverBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entityId: z.ZodMiniString<string>;
+    entityKind: z.ZodMiniEnum<{
+        Experience: "Experience";
+        Fragment: "Fragment";
+        InlineFragment: "InlineFragment";
+        InlineComponent: "InlineComponent";
+    }>;
+    entityKindId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    entryIds: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+    optimizationId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    parameters: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    parentExperienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    hoverId: z.ZodMiniString<string>;
+    hoverDurationMs: z.ZodMiniInt;
+}, z.core.$strip>;
+type HoverBuilderArgs = z.infer<typeof HoverBuilderArgs>;
+declare const FlagViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    componentId: z.ZodMiniString<string>;
+    experienceId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    variantIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    viewId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    viewDurationMs: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+type FlagViewBuilderArgs = z.infer<typeof FlagViewBuilderArgs>;
+declare const IdentifyBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    traits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>;
+    userId: z.ZodMiniString<string>;
+}, z.core.$strip>;
+type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs>;
+declare const PageViewBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    properties: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        query: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
+        referrer: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        search: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        title: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniString<string>>>;
+        url: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+}, z.core.$strip>;
+type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs>;
+declare const TrackBuilderArgs: z.ZodMiniObject<{
+    campaign: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        source: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        medium: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        term: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        content: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    locale: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    location: z.ZodMiniOptional<z.ZodMiniObject<{
+        coordinates: z.ZodMiniOptional<z.ZodMiniObject<{
+            latitude: z.ZodMiniNumber<number>;
+            longitude: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        city: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        region: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        regionCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        countryCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        continent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        timezone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+    page: z.ZodMiniOptional<z.ZodMiniObject<{
+        path: z.ZodMiniString<string>;
+        query: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        referrer: z.ZodMiniString<string>;
+        search: z.ZodMiniString<string>;
+        title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        url: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    screen: z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+    }, z.core.$catchall<z.ZodMiniJSONSchema>>>;
+    userAgent: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    event: z.ZodMiniString<string>;
+    properties: z.ZodMiniOptional<z.ZodMiniPrefault<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniJSONSchema>>>;
+}, z.core.$strip>;
+type TrackBuilderArgs = z.infer<typeof TrackBuilderArgs>;
+declare const DEFAULT_PAGE_PROPERTIES: Page;
+declare class EventBuilder {
+    app?: App;
+    channel: Channel;
+    library: Library;
+    getLocale: () => string | undefined;
+    getPageProperties: () => Page;
+    getUserAgent: () => string | undefined;
+    getConsent: () => boolean | undefined;
+    constructor(config: EventBuilderConfig);
+    protected buildUniversalEventProperties({ campaign, locale, location, page, screen, userAgent, }: UniversalEventBuilderArgs): UniversalEventProperties;
+    private buildInteractionBase;
+    buildView(args: ViewBuilderArgs): ExoViewEvent;
+    buildClick(args: ClickBuilderArgs): ExoClickEvent;
+    buildHover(args: HoverBuilderArgs): ExoHoverEvent;
+    buildFlagView(args: FlagViewBuilderArgs): ViewEvent;
+    buildIdentify(args: IdentifyBuilderArgs): IdentifyEvent;
+    buildPageView(args?: PageViewBuilderArgs): PageViewEvent;
+    buildTrack(args: TrackBuilderArgs): TrackEvent;
+}
+
+export { ClickBuilderArgs, DEFAULT_PAGE_PROPERTIES, type EventBuilderConfig, FlagViewBuilderArgs, HoverBuilderArgs, IdentifyBuilderArgs, InteractionBuilderArgsBase, PageViewBuilderArgs, TrackBuilderArgs, UniversalEventBuilderArgs, ViewBuilderArgs, EventBuilder as default };

package/dist/event-builder.js

@@ -0,0 +1,274 @@
+import {
+  Campaign,
+  ExoEntityKind,
+  GeoLocation,
+  Page,
+  PageEventContext,
+  parseWithFriendlyError,
+  Properties,
+  Screen,
+  Traits
+} from "@contentful/optimization-api-client/api-schemas";
+import { createScopedLogger } from "@contentful/optimization-api-client/logger";
+import { merge } from "es-toolkit/object";
+import * as z from "zod/mini";
+const eventBuilderLogger = createScopedLogger("Experiences:EventBuilder");
+const UTM_CAMPAIGN_PARAMETERS = [
+  ["utm_campaign", "name"],
+  ["utm_source", "source"],
+  ["utm_medium", "medium"],
+  ["utm_term", "term"],
+  ["utm_content", "content"]
+];
+function extractCampaignFromUrl(url) {
+  if (url === void 0) return void 0;
+  try {
+    const { searchParams } = new URL(url);
+    const campaign = {};
+    let hasCampaignParameter = false;
+    for (const [parameter, property] of UTM_CAMPAIGN_PARAMETERS) {
+      if (!searchParams.has(parameter)) continue;
+      campaign[property] = searchParams.get(parameter) ?? "";
+      hasCampaignParameter = true;
+    }
+    return hasCampaignParameter ? campaign : void 0;
+  } catch {
+    return void 0;
+  }
+}
+const UniversalEventBuilderArgs = z.object({
+  campaign: z.optional(Campaign),
+  locale: z.optional(z.string()),
+  location: z.optional(GeoLocation),
+  page: z.optional(Page),
+  screen: z.optional(Screen),
+  userAgent: z.optional(z.string())
+});
+const InteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {
+  entityId: z.string(),
+  entityKind: ExoEntityKind,
+  entityKindId: z.optional(z.string()),
+  entryIds: z.optional(z.array(z.string())),
+  optimizationId: z.optional(z.string()),
+  parameters: z.optional(z.record(z.string(), z.json())),
+  parentExperienceId: z.optional(z.string()),
+  variantId: z.optional(z.string()),
+  variantIndex: z.optional(z.number())
+});
+const ViewBuilderArgs = z.extend(InteractionBuilderArgsBase, {
+  viewId: z.string(),
+  viewDurationMs: z.int().check(z.minimum(0))
+});
+const ClickBuilderArgs = InteractionBuilderArgsBase;
+const HoverBuilderArgs = z.extend(InteractionBuilderArgsBase, {
+  hoverId: z.string(),
+  hoverDurationMs: z.int().check(z.minimum(0))
+});
+const FlagInteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {
+  componentId: z.string(),
+  experienceId: z.optional(z.string()),
+  variantIndex: z.optional(z.number())
+});
+const FlagViewBuilderArgs = z.extend(FlagInteractionBuilderArgsBase, {
+  viewId: z.optional(z.string()),
+  viewDurationMs: z.optional(z.number())
+});
+const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+  traits: z.optional(Traits),
+  userId: z.string()
+});
+const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+  properties: z.optional(z.partial(Page))
+});
+const TrackBuilderArgs = z.extend(UniversalEventBuilderArgs, {
+  event: z.string(),
+  properties: z.optional(z.prefault(Properties, {}))
+});
+const PAGE_CONTEXT_CONFLICT_KEYS = ["path", "query", "search", "url"];
+function warnIfPageContextConflicts(explicitPage, properties) {
+  if (!explicitPage) return;
+  const conflictingKeys = PAGE_CONTEXT_CONFLICT_KEYS.filter((key) => {
+    const { [key]: explicitValue } = explicitPage;
+    const { [key]: propertyValue } = properties;
+    return JSON.stringify(explicitValue) !== JSON.stringify(propertyValue);
+  });
+  if (conflictingKeys.length === 0) return;
+  eventBuilderLogger.warn(
+    `Explicit page context differs from page event properties for: ${conflictingKeys.join(", ")}`
+  );
+}
+const DEFAULT_PAGE_PROPERTIES = {
+  path: "",
+  query: {},
+  referrer: "",
+  search: "",
+  title: "",
+  url: ""
+};
+class EventBuilder {
+  app;
+  channel;
+  library;
+  getLocale;
+  getPageProperties;
+  getUserAgent;
+  getConsent;
+  constructor(config) {
+    const { app, channel, library, getLocale, getPageProperties, getUserAgent, getConsent } = config;
+    this.app = app;
+    this.channel = channel;
+    this.library = library;
+    this.getLocale = getLocale ?? (() => "en-US");
+    this.getPageProperties = getPageProperties ?? (() => DEFAULT_PAGE_PROPERTIES);
+    this.getUserAgent = getUserAgent ?? (() => void 0);
+    this.getConsent = getConsent ?? (() => void 0);
+  }
+  buildUniversalEventProperties({
+    campaign,
+    locale,
+    location,
+    page,
+    screen,
+    userAgent
+  }) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const resolvedPage = page ?? this.getPageProperties();
+    return {
+      channel: this.channel,
+      context: {
+        app: this.app,
+        campaign: campaign ?? extractCampaignFromUrl(resolvedPage.url) ?? {},
+        gdpr: { isConsentGiven: this.getConsent() === true },
+        library: this.library,
+        locale: locale ?? this.getLocale() ?? "en-US",
+        location,
+        page: resolvedPage,
+        screen,
+        userAgent: userAgent ?? this.getUserAgent()
+      },
+      messageId: crypto.randomUUID(),
+      originalTimestamp: timestamp,
+      sentAt: timestamp,
+      timestamp
+    };
+  }
+  buildInteractionBase(args) {
+    const { campaign, locale, location, page, screen, userAgent, ...interactionProperties } = args;
+    return {
+      ...this.buildUniversalEventProperties({
+        campaign,
+        locale,
+        location,
+        page,
+        screen,
+        userAgent
+      }),
+      ...interactionProperties
+    };
+  }
+  buildView(args) {
+    const { viewId, viewDurationMs, ...interaction } = parseWithFriendlyError(
+      ViewBuilderArgs,
+      args
+    );
+    return {
+      ...this.buildInteractionBase(interaction),
+      type: "exo_node_view",
+      viewId,
+      viewDurationMs
+    };
+  }
+  buildClick(args) {
+    const interaction = parseWithFriendlyError(ClickBuilderArgs, args);
+    return {
+      ...this.buildInteractionBase(interaction),
+      type: "exo_node_click"
+    };
+  }
+  buildHover(args) {
+    const { hoverId, hoverDurationMs, ...interaction } = parseWithFriendlyError(
+      HoverBuilderArgs,
+      args
+    );
+    return {
+      ...this.buildInteractionBase(interaction),
+      type: "exo_node_hover",
+      hoverId,
+      hoverDurationMs
+    };
+  }
+  buildFlagView(args) {
+    const { componentId, experienceId, variantIndex, viewId, viewDurationMs, ...universal } = parseWithFriendlyError(FlagViewBuilderArgs, args);
+    return {
+      ...this.buildUniversalEventProperties(universal),
+      ...viewDurationMs === void 0 ? {} : { viewDurationMs },
+      ...viewId === void 0 ? {} : { viewId },
+      type: "component",
+      componentType: "Variable",
+      componentId,
+      experienceId,
+      variantIndex: variantIndex ?? 0
+    };
+  }
+  buildIdentify(args) {
+    const { traits = {}, userId, ...universal } = parseWithFriendlyError(IdentifyBuilderArgs, args);
+    return {
+      ...this.buildUniversalEventProperties(universal),
+      type: "identify",
+      traits,
+      userId
+    };
+  }
+  buildPageView(args = {}) {
+    const { properties = {}, ...universal } = parseWithFriendlyError(PageViewBuilderArgs, args);
+    const propertiesCampaign = extractCampaignFromUrl(properties.url);
+    const pageProperties = this.getPageProperties();
+    const merged = merge(
+      {
+        ...pageProperties,
+        title: pageProperties.title ?? DEFAULT_PAGE_PROPERTIES.title
+      },
+      properties
+    );
+    warnIfPageContextConflicts(universal.page, merged);
+    const {
+      context: { screen: _, ...universalContext },
+      ...universalProperties
+    } = this.buildUniversalEventProperties({
+      ...universal,
+      campaign: universal.campaign ?? propertiesCampaign,
+      page: universal.page ?? merged
+    });
+    const context = parseWithFriendlyError(PageEventContext, universalContext);
+    return {
+      ...universalProperties,
+      context,
+      type: "page",
+      properties: merged
+    };
+  }
+  buildTrack(args) {
+    const { event, properties = {}, ...universal } = parseWithFriendlyError(TrackBuilderArgs, args);
+    return {
+      ...this.buildUniversalEventProperties(universal),
+      type: "track",
+      event,
+      properties
+    };
+  }
+}
+var event_builder_default = EventBuilder;
+export {
+  ClickBuilderArgs,
+  DEFAULT_PAGE_PROPERTIES,
+  FlagViewBuilderArgs,
+  HoverBuilderArgs,
+  IdentifyBuilderArgs,
+  InteractionBuilderArgsBase,
+  PageViewBuilderArgs,
+  TrackBuilderArgs,
+  UniversalEventBuilderArgs,
+  ViewBuilderArgs,
+  event_builder_default as default
+};
+//# sourceMappingURL=event-builder.js.map

package/dist/event-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/event-builder.ts"],"sourcesContent":["/* eslint-disable no-redeclare */\n\nimport {\n  type App,\n  Campaign,\n  type Channel,\n  type ExoClickEvent,\n  ExoEntityKind,\n  type ExoHoverEvent,\n  type ExoViewEvent,\n  GeoLocation,\n  type IdentifyEvent,\n  type Library,\n  Page,\n  PageEventContext,\n  type PageViewEvent,\n  parseWithFriendlyError,\n  Properties,\n  Screen,\n  type TrackEvent,\n  Traits,\n  UniversalEventProperties,\n  type ViewEvent,\n} from '@contentful/optimization-api-client/api-schemas';\nimport { createScopedLogger } from '@contentful/optimization-api-client/logger';\nimport { merge } from 'es-toolkit/object';\nimport * as z from 'zod/mini';\n\nconst eventBuilderLogger = createScopedLogger('Experiences:EventBuilder');\n\nconst UTM_CAMPAIGN_PARAMETERS = [\n  ['utm_campaign', 'name'],\n  ['utm_source', 'source'],\n  ['utm_medium', 'medium'],\n  ['utm_term', 'term'],\n  ['utm_content', 'content'],\n] as const;\n\nfunction extractCampaignFromUrl(url: string | undefined): Campaign | undefined {\n  if (url === undefined) return undefined;\n\n  try {\n    const { searchParams } = new URL(url);\n    const campaign: Campaign = {};\n    let hasCampaignParameter = false;\n\n    for (const [parameter, property] of UTM_CAMPAIGN_PARAMETERS) {\n      if (!searchParams.has(parameter)) continue;\n\n      campaign[property] = searchParams.get(parameter) ?? '';\n      hasCampaignParameter = true;\n    }\n\n    return hasCampaignParameter ? campaign : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nexport interface EventBuilderConfig {\n  app?: App;\n  channel: Channel;\n  library: Library;\n  getLocale?: () => string | undefined;\n  getPageProperties?: () => Page;\n  getUserAgent?: () => string | undefined;\n  getConsent?: () => boolean | undefined;\n}\n\nexport const UniversalEventBuilderArgs = z.object({\n  campaign: z.optional(Campaign),\n  locale: z.optional(z.string()),\n  location: z.optional(GeoLocation),\n  page: z.optional(Page),\n  screen: z.optional(Screen),\n  userAgent: z.optional(z.string()),\n});\n\nexport type UniversalEventBuilderArgs = z.infer<typeof UniversalEventBuilderArgs>;\n\nexport const InteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {\n  entityId: z.string(),\n  entityKind: ExoEntityKind,\n  entityKindId: z.optional(z.string()),\n  entryIds: z.optional(z.array(z.string())),\n  optimizationId: z.optional(z.string()),\n  parameters: z.optional(z.record(z.string(), z.json())),\n  parentExperienceId: z.optional(z.string()),\n  variantId: z.optional(z.string()),\n  variantIndex: z.optional(z.number()),\n});\n\nexport type InteractionBuilderArgsBase = z.infer<typeof InteractionBuilderArgsBase>;\n\nexport const ViewBuilderArgs = z.extend(InteractionBuilderArgsBase, {\n  viewId: z.string(),\n  viewDurationMs: z.int().check(z.minimum(0)),\n});\n\nexport type ViewBuilderArgs = z.infer<typeof ViewBuilderArgs>;\n\nexport const ClickBuilderArgs = InteractionBuilderArgsBase;\n\nexport type ClickBuilderArgs = z.infer<typeof ClickBuilderArgs>;\n\nexport const HoverBuilderArgs = z.extend(InteractionBuilderArgsBase, {\n  hoverId: z.string(),\n  hoverDurationMs: z.int().check(z.minimum(0)),\n});\n\nexport type HoverBuilderArgs = z.infer<typeof HoverBuilderArgs>;\n\nconst FlagInteractionBuilderArgsBase = z.extend(UniversalEventBuilderArgs, {\n  componentId: z.string(),\n  experienceId: z.optional(z.string()),\n  variantIndex: z.optional(z.number()),\n});\n\nexport const FlagViewBuilderArgs = z.extend(FlagInteractionBuilderArgsBase, {\n  viewId: z.optional(z.string()),\n  viewDurationMs: z.optional(z.number()),\n});\n\nexport type FlagViewBuilderArgs = z.infer<typeof FlagViewBuilderArgs>;\n\nexport const IdentifyBuilderArgs = z.extend(UniversalEventBuilderArgs, {\n  traits: z.optional(Traits),\n  userId: z.string(),\n});\n\nexport type IdentifyBuilderArgs = z.infer<typeof IdentifyBuilderArgs>;\n\nexport const PageViewBuilderArgs = z.extend(UniversalEventBuilderArgs, {\n  properties: z.optional(z.partial(Page)),\n});\n\nexport type PageViewBuilderArgs = z.infer<typeof PageViewBuilderArgs>;\n\nexport const TrackBuilderArgs = z.extend(UniversalEventBuilderArgs, {\n  event: z.string(),\n  properties: z.optional(z.prefault(Properties, {})),\n});\n\nexport type TrackBuilderArgs = z.infer<typeof TrackBuilderArgs>;\n\nconst PAGE_CONTEXT_CONFLICT_KEYS = ['path', 'query', 'search', 'url'] as const;\n\nfunction warnIfPageContextConflicts(explicitPage: Page | undefined, properties: Page): void {\n  if (!explicitPage) return;\n\n  const conflictingKeys = PAGE_CONTEXT_CONFLICT_KEYS.filter((key) => {\n    const { [key]: explicitValue } = explicitPage;\n    const { [key]: propertyValue } = properties;\n    return JSON.stringify(explicitValue) !== JSON.stringify(propertyValue);\n  });\n\n  if (conflictingKeys.length === 0) return;\n\n  eventBuilderLogger.warn(\n    `Explicit page context differs from page event properties for: ${conflictingKeys.join(', ')}`\n  );\n}\n\nexport const DEFAULT_PAGE_PROPERTIES: Page = {\n  path: '',\n  query: {},\n  referrer: '',\n  search: '',\n  title: '',\n  url: '',\n};\n\nclass EventBuilder {\n  app?: App;\n  channel: Channel;\n  library: Library;\n  getLocale: () => string | undefined;\n  getPageProperties: () => Page;\n  getUserAgent: () => string | undefined;\n  getConsent: () => boolean | undefined;\n\n  constructor(config: EventBuilderConfig) {\n    const { app, channel, library, getLocale, getPageProperties, getUserAgent, getConsent } =\n      config;\n    this.app = app;\n    this.channel = channel;\n    this.library = library;\n    this.getLocale = getLocale ?? (() => 'en-US');\n    this.getPageProperties = getPageProperties ?? (() => DEFAULT_PAGE_PROPERTIES);\n    this.getUserAgent = getUserAgent ?? (() => undefined);\n    this.getConsent = getConsent ?? (() => undefined);\n  }\n\n  protected buildUniversalEventProperties({\n    campaign,\n    locale,\n    location,\n    page,\n    screen,\n    userAgent,\n  }: UniversalEventBuilderArgs): UniversalEventProperties {\n    const timestamp = new Date().toISOString();\n    const resolvedPage = page ?? this.getPageProperties();\n\n    return {\n      channel: this.channel,\n      context: {\n        app: this.app,\n        campaign: campaign ?? extractCampaignFromUrl(resolvedPage.url) ?? {},\n        gdpr: { isConsentGiven: this.getConsent() === true },\n        library: this.library,\n        locale: locale ?? this.getLocale() ?? 'en-US',\n        location,\n        page: resolvedPage,\n        screen,\n        userAgent: userAgent ?? this.getUserAgent(),\n      },\n      messageId: crypto.randomUUID(),\n      originalTimestamp: timestamp,\n      sentAt: timestamp,\n      timestamp,\n    };\n  }\n\n  private buildInteractionBase(\n    args: InteractionBuilderArgsBase\n  ): UniversalEventProperties & InteractionBuilderArgsBase {\n    const { campaign, locale, location, page, screen, userAgent, ...interactionProperties } = args;\n\n    return {\n      ...this.buildUniversalEventProperties({\n        campaign,\n        locale,\n        location,\n        page,\n        screen,\n        userAgent,\n      }),\n      ...interactionProperties,\n    };\n  }\n\n  buildView(args: ViewBuilderArgs): ExoViewEvent {\n    const { viewId, viewDurationMs, ...interaction } = parseWithFriendlyError(\n      ViewBuilderArgs,\n      args\n    );\n\n    return {\n      ...this.buildInteractionBase(interaction),\n      type: 'exo_node_view',\n      viewId,\n      viewDurationMs,\n    };\n  }\n\n  buildClick(args: ClickBuilderArgs): ExoClickEvent {\n    const interaction = parseWithFriendlyError(ClickBuilderArgs, args);\n\n    return {\n      ...this.buildInteractionBase(interaction),\n      type: 'exo_node_click',\n    };\n  }\n\n  buildHover(args: HoverBuilderArgs): ExoHoverEvent {\n    const { hoverId, hoverDurationMs, ...interaction } = parseWithFriendlyError(\n      HoverBuilderArgs,\n      args\n    );\n\n    return {\n      ...this.buildInteractionBase(interaction),\n      type: 'exo_node_hover',\n      hoverId,\n      hoverDurationMs,\n    };\n  }\n\n  buildFlagView(args: FlagViewBuilderArgs): ViewEvent {\n    const { componentId, experienceId, variantIndex, viewId, viewDurationMs, ...universal } =\n      parseWithFriendlyError(FlagViewBuilderArgs, args);\n\n    return {\n      ...this.buildUniversalEventProperties(universal),\n      ...(viewDurationMs === undefined ? {} : { viewDurationMs }),\n      ...(viewId === undefined ? {} : { viewId }),\n      type: 'component',\n      componentType: 'Variable',\n      componentId,\n      experienceId,\n      variantIndex: variantIndex ?? 0,\n    };\n  }\n\n  buildIdentify(args: IdentifyBuilderArgs): IdentifyEvent {\n    const { traits = {}, userId, ...universal } = parseWithFriendlyError(IdentifyBuilderArgs, args);\n\n    return {\n      ...this.buildUniversalEventProperties(universal),\n      type: 'identify',\n      traits,\n      userId,\n    };\n  }\n\n  buildPageView(args: PageViewBuilderArgs = {}): PageViewEvent {\n    const { properties = {}, ...universal } = parseWithFriendlyError(PageViewBuilderArgs, args);\n    const propertiesCampaign = extractCampaignFromUrl(properties.url);\n    const pageProperties = this.getPageProperties();\n    const merged = merge(\n      {\n        ...pageProperties,\n        title: pageProperties.title ?? DEFAULT_PAGE_PROPERTIES.title,\n      },\n      properties\n    );\n\n    warnIfPageContextConflicts(universal.page, merged);\n\n    const {\n      context: { screen: _, ...universalContext },\n      ...universalProperties\n    } = this.buildUniversalEventProperties({\n      ...universal,\n      campaign: universal.campaign ?? propertiesCampaign,\n      page: universal.page ?? merged,\n    });\n\n    const context = parseWithFriendlyError(PageEventContext, universalContext);\n\n    return {\n      ...universalProperties,\n      context,\n      type: 'page',\n      properties: merged,\n    };\n  }\n\n  buildTrack(args: TrackBuilderArgs): TrackEvent {\n    const { event, properties = {}, ...universal } = parseWithFriendlyError(TrackBuilderArgs, args);\n\n    return {\n      ...this.buildUniversalEventProperties(universal),\n      type: 'track',\n      event,\n      properties,\n    };\n  }\n}\n\nexport default EventBuilder;\n"],"mappings":"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","names":[]}

package/dist/fetch-experience.js

@@ -1,7 +1,7 @@
 import { ContentfulViewDelivery } from "@contentful/experience-delivery";
 import { createDebugLogger, resolveExperience } from "@contentful/experiences-sdk-core";
 import { createClient } from "./create-client.js";
-import { ExperienceFetchError } from "./errors.js";
+import { DestinationPreviewNotSupportedError, ExperienceFetchError } from "./errors.js";
 import { PREVIEW_HOST } from "./hosts.js";
 import {
   readSourceMap,
@@ -11,6 +11,14 @@ import {
 async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
   const { config, metadata, debug, initialViewportId } = resolveOptions;
   const log = createDebugLogger(debug, "client");
+  if (!("client" in clientOptions) && clientOptions.preview && "destinationId" in experienceOptions) {
+    const { spaceId: spaceId2, destinationId } = experienceOptions;
+    const locator = "nodeId" in experienceOptions ? { nodeId: experienceOptions.nodeId } : { path: experienceOptions.path };
+    throw new DestinationPreviewNotSupportedError(
+      `fetchExperience() called with preview: true and a destination-shaped experienceOptions (destinationId "${destinationId}"). The Destinations Delivery API does not support preview mode yet \u2014 pass preview: false (or omit it) for destination-based fetches.`,
+      { spaceId: spaceId2, destinationId, ...locator }
+    );
+  }
   let client;
   if ("client" in clientOptions) {
     client = clientOptions.client;

package/dist/fetch-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { ContentfulViewDelivery } from '@contentful/experience-delivery';\nimport { createDebugLogger, resolveExperience } from '@contentful/experiences-sdk-core';\nimport type { PortableRenderPlan, ResolverConfig } from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\nimport { ExperienceFetchError } from './errors.js';\nimport { PREVIEW_HOST } from './hosts.js';\nimport {\n  readSourceMap,\n  toExperiencePayload,\n  toExperiencePayloadFromDestination,\n  type ExperienceResponse,\n} from './to-experience-payload.js';\n\nexport type ByIdExperienceOptions = {\n  spaceId: string;\n  environmentId: string;\n  experienceId: string;\n  locale?: string;\n  /**\n   * Fetch the content source map alongside the experience, onto\n   * `PortableRenderPlan.sourceMap`. Defaults to `false` because the map is large.\n   *\n   * Switches the request from `GET` to `POST` (the opt-in is a request-body\n   * field, only accepted by `getWithOverrides`), so it is not CDN-cacheable.\n   * Query params, auth, and the response shape are unchanged.\n   */\n  withSourceMap?: boolean;\n};\n\n/**\n * Resolve an Experience by the Destination Node instead of `experienceId`\n * The destinations delivery endpoints are space-scoped only and have no locale\n * param, unlike the by-id path.\n */\nexport type ByDestinationNodeIdExperienceOptions = {\n  spaceId: string;\n  destinationId: string;\n  nodeId: string;\n};\n\n/**\n * Resolve an Experience by the absolute path wired up to a\n * Destination Node, instead of a node id directly. Same scoping as\n * `ByDestinationNodeIdExperienceOptions` — no `environmentId` or `locale`.\n */\nexport type ByDestinationPathExperienceOptions = {\n  spaceId: string;\n  destinationId: string;\n  /** Absolute path to resolve. Must start with `/`. */\n  path: string;\n};\n\nexport type ExperienceOptions =\n  ByIdExperienceOptions | ByDestinationNodeIdExperienceOptions | ByDestinationPathExperienceOptions;\n\n/**\n * A Destination resolution that the app must act on as control flow — honor\n * it by navigating or re-resolving at the new path — rather than a hydrated\n * Experience to render. Modeled as a normal return value, not a thrown error,\n * per the Destinations delivery API's own framing of a redirect response.\n */\nexport interface DestinationRedirectResult {\n  redirect: { path: 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\n// TS overload signatures, not real redeclarations — base ESLint's no-redeclare doesn't know the\n// overload form (@typescript-eslint's own version does), so each repeated signature needs a\n// disable comment.\nexport async function fetchExperience(\n  experienceOptions: ByIdExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ByDestinationNodeIdExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ByDestinationPathExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult> {\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  if ('nodeId' in experienceOptions) {\n    const { spaceId, destinationId, nodeId } = experienceOptions;\n    return fetchByDestination(\n      { spaceId, destinationId, locator: nodeId },\n      () => client.destination.resolveByNodeId(spaceId, destinationId, nodeId),\n      log,\n      { config, metadata, debug, initialViewportId }\n    );\n  }\n\n  if ('path' in experienceOptions) {\n    const { spaceId, destinationId, path } = experienceOptions;\n    return fetchByDestination(\n      { spaceId, destinationId, locator: path },\n      () => client.destination.resolveByPath(spaceId, destinationId, { path }),\n      log,\n      { config, metadata, debug, initialViewportId }\n    );\n  }\n\n  const { spaceId, environmentId, experienceId, locale, withSourceMap } = experienceOptions;\n\n  log.log('fetching experience', {\n    spaceId,\n    environmentId,\n    experienceId,\n    locale,\n    withSourceMap: Boolean(withSourceMap),\n  });\n\n  // Typed as the union of both operations' responses — they declare the same\n  // union, but which one runs depends on `withSourceMap` below.\n  let response: ExperienceResponse;\n  try {\n    // Both methods hit the same endpoint; only the POST accepts a body, and\n    // `extensions` (the source-map opt-in) lives there. Otherwise identical.\n    // The alpha-feature header is sent by the delivery client itself since\n    // 1.0.0-dev.7, so a caller-supplied `{ client }` is covered too.\n    response = withSourceMap\n      ? await client.experience.getWithOverrides(spaceId, environmentId, experienceId, {\n          locale,\n          extensions: { sourceMap: {} },\n        })\n      : await client.experience.get(spaceId, environmentId, experienceId, { locale });\n  } catch (err) {\n    // `NotFoundError` is a distinguishable, expected outcome (draft/unpublished/\n    // wrong id) — callers already route it to their framework's 404 idiom, so\n    // it passes through as-is. Everything else (network failure, bad/expired\n    // token, a 5xx) is unexpected and gets wrapped in an actionable error\n    // instead of leaking whatever shape the delivery client happened to throw.\n    if (err instanceof ContentfulViewDelivery.NotFoundError) {\n      throw err;\n    }\n    const reason = err instanceof Error ? err.message : String(err);\n    throw new ExperienceFetchError(\n      `Failed to fetch Experience \"${experienceId}\" (space \"${spaceId}\", environment ` +\n        `\"${environmentId}\"): ${reason}. Check network connectivity, the access token, and ` +\n        `that the space/environment/experience ids are correct.`,\n      { spaceId, environmentId, experienceId, cause: err }\n    );\n  }\n\n  const payload = toExperiencePayload(response);\n  const sourceMap = withSourceMap ? readSourceMap(response) : undefined;\n\n  log.lazy('received raw payload', () => payload);\n  if (withSourceMap && !sourceMap) log.log('source map requested but not returned');\n\n  return resolveExperience(payload, config, {\n    metadata,\n    debug,\n    initialViewportId,\n    sourceMap,\n  });\n}\n\n/**\n * Shared response-handling for both destination-shaped `fetchExperience`\n * branches (by node id, by path).\n */\nasync function fetchByDestination(\n  identity: { spaceId: string; destinationId: string; locator: string },\n  resolve: () => Promise<ContentfulViewDelivery.DestinationExperienceResolutionResponse>,\n  log: ReturnType<typeof createDebugLogger>,\n  resolveOptions: {\n    config: ResolverConfig;\n    metadata: Record<string, unknown> | undefined;\n    debug: boolean | undefined;\n    initialViewportId: string | undefined;\n  }\n): Promise<PortableRenderPlan | DestinationRedirectResult> {\n  const { spaceId, destinationId, locator } = identity;\n  const { config, metadata, debug, initialViewportId } = resolveOptions;\n\n  log.log('resolving destination experience', { spaceId, destinationId, locator });\n\n  let response: ContentfulViewDelivery.DestinationExperienceResolutionResponse;\n  try {\n    response = await resolve();\n  } catch (err) {\n    if (err instanceof ContentfulViewDelivery.NotFoundError) {\n      throw err;\n    }\n    const reason = err instanceof Error ? err.message : String(err);\n    throw new ExperienceFetchError(\n      `Failed to resolve Destination \"${destinationId}\" at \"${locator}\" (space \"${spaceId}\"): ` +\n        `${reason}. Check network connectivity, the access token, and that the space/` +\n        `destination/node-or-path values are correct.`,\n      { spaceId, experienceId: locator, cause: err }\n    );\n  }\n\n  if ('redirect' in response) {\n    log.log('destination resolved to a redirect', response.redirect);\n    return { redirect: response.redirect };\n  }\n\n  const [firstExperience] = response.experiences;\n  if (!firstExperience) {\n    throw new ExperienceFetchError(\n      `Destination \"${destinationId}\" resolved \"${locator}\" to zero Experiences ` +\n        `(space \"${spaceId}\"). Expected exactly one hydrated Experience or a redirect.`,\n      { spaceId, experienceId: locator }\n    );\n  }\n\n  const payload = toExperiencePayloadFromDestination(firstExperience.experience);\n  log.lazy('received raw payload', () => payload);\n\n  return resolveExperience(payload, config, {\n    metadata,\n    debug,\n    initialViewportId,\n  });\n}\n"],"mappings":"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","names":["spaceId"]}
+{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { ContentfulViewDelivery } from '@contentful/experience-delivery';\nimport { createDebugLogger, resolveExperience } from '@contentful/experiences-sdk-core';\nimport type { PortableRenderPlan, ResolverConfig } from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\nimport { DestinationPreviewNotSupportedError, ExperienceFetchError } from './errors.js';\nimport { PREVIEW_HOST } from './hosts.js';\nimport {\n  readSourceMap,\n  toExperiencePayload,\n  toExperiencePayloadFromDestination,\n  type ExperienceResponse,\n} from './to-experience-payload.js';\n\nexport type ByIdExperienceOptions = {\n  spaceId: string;\n  environmentId: string;\n  experienceId: string;\n  locale?: string;\n  /**\n   * Fetch the content source map alongside the experience, onto\n   * `PortableRenderPlan.sourceMap`. Defaults to `false` because the map is large.\n   *\n   * Switches the request from `GET` to `POST` (the opt-in is a request-body\n   * field, only accepted by `getWithOverrides`), so it is not CDN-cacheable.\n   * Query params, auth, and the response shape are unchanged.\n   */\n  withSourceMap?: boolean;\n};\n\n/**\n * Resolve an Experience by the Destination Node instead of `experienceId`\n * The destinations delivery endpoints are space-scoped only and have no locale\n * param, unlike the by-id path.\n */\nexport type ByDestinationNodeIdExperienceOptions = {\n  spaceId: string;\n  destinationId: string;\n  nodeId: string;\n};\n\n/**\n * Resolve an Experience by the absolute path wired up to a\n * Destination Node, instead of a node id directly. Same scoping as\n * `ByDestinationNodeIdExperienceOptions` — no `environmentId` or `locale`.\n */\nexport type ByDestinationPathExperienceOptions = {\n  spaceId: string;\n  destinationId: string;\n  /** Absolute path to resolve. Must start with `/`. */\n  path: string;\n};\n\nexport type ExperienceOptions =\n  ByIdExperienceOptions | ByDestinationNodeIdExperienceOptions | ByDestinationPathExperienceOptions;\n\n/**\n * A Destination resolution that the app must act on as control flow — honor\n * it by navigating or re-resolving at the new path — rather than a hydrated\n * Experience to render. Modeled as a normal return value, not a thrown error,\n * per the Destinations delivery API's own framing of a redirect response.\n */\nexport interface DestinationRedirectResult {\n  redirect: { path: 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\n// TS overload signatures, not real redeclarations — base ESLint's no-redeclare doesn't know the\n// overload form (@typescript-eslint's own version does), so each repeated signature needs a\n// disable comment.\nexport async function fetchExperience(\n  experienceOptions: ByIdExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ByDestinationNodeIdExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ByDestinationPathExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult>;\n// eslint-disable-next-line no-redeclare -- see above\nexport async function fetchExperience(\n  experienceOptions: ExperienceOptions,\n  clientOptions: ClientOptions,\n  resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan | DestinationRedirectResult> {\n  const { config, metadata, debug, initialViewportId } = resolveOptions;\n  const log = createDebugLogger(debug, 'client');\n\n  if (\n    !('client' in clientOptions) &&\n    clientOptions.preview &&\n    'destinationId' in experienceOptions\n  ) {\n    const { spaceId, destinationId } = experienceOptions;\n    const locator =\n      'nodeId' in experienceOptions\n        ? { nodeId: experienceOptions.nodeId }\n        : { path: experienceOptions.path };\n    throw new DestinationPreviewNotSupportedError(\n      `fetchExperience() called with preview: true and a destination-shaped experienceOptions ` +\n        `(destinationId \"${destinationId}\"). The Destinations Delivery API does not support ` +\n        `preview mode yet — pass preview: false (or omit it) for destination-based fetches.`,\n      { spaceId, destinationId, ...locator }\n    );\n  }\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  if ('nodeId' in experienceOptions) {\n    const { spaceId, destinationId, nodeId } = experienceOptions;\n    return fetchByDestination(\n      { spaceId, destinationId, locator: nodeId },\n      () => client.destination.resolveByNodeId(spaceId, destinationId, nodeId),\n      log,\n      { config, metadata, debug, initialViewportId }\n    );\n  }\n\n  if ('path' in experienceOptions) {\n    const { spaceId, destinationId, path } = experienceOptions;\n    return fetchByDestination(\n      { spaceId, destinationId, locator: path },\n      () => client.destination.resolveByPath(spaceId, destinationId, { path }),\n      log,\n      { config, metadata, debug, initialViewportId }\n    );\n  }\n\n  const { spaceId, environmentId, experienceId, locale, withSourceMap } = experienceOptions;\n\n  log.log('fetching experience', {\n    spaceId,\n    environmentId,\n    experienceId,\n    locale,\n    withSourceMap: Boolean(withSourceMap),\n  });\n\n  // Typed as the union of both operations' responses — they declare the same\n  // union, but which one runs depends on `withSourceMap` below.\n  let response: ExperienceResponse;\n  try {\n    // Both methods hit the same endpoint; only the POST accepts a body, and\n    // `extensions` (the source-map opt-in) lives there. Otherwise identical.\n    // The alpha-feature header is sent by the delivery client itself since\n    // 1.0.0-dev.7, so a caller-supplied `{ client }` is covered too.\n    response = withSourceMap\n      ? await client.experience.getWithOverrides(spaceId, environmentId, experienceId, {\n          locale,\n          extensions: { sourceMap: {} },\n        })\n      : await client.experience.get(spaceId, environmentId, experienceId, { locale });\n  } catch (err) {\n    // `NotFoundError` is a distinguishable, expected outcome (draft/unpublished/\n    // wrong id) — callers already route it to their framework's 404 idiom, so\n    // it passes through as-is. Everything else (network failure, bad/expired\n    // token, a 5xx) is unexpected and gets wrapped in an actionable error\n    // instead of leaking whatever shape the delivery client happened to throw.\n    if (err instanceof ContentfulViewDelivery.NotFoundError) {\n      throw err;\n    }\n    const reason = err instanceof Error ? err.message : String(err);\n    throw new ExperienceFetchError(\n      `Failed to fetch Experience \"${experienceId}\" (space \"${spaceId}\", environment ` +\n        `\"${environmentId}\"): ${reason}. Check network connectivity, the access token, and ` +\n        `that the space/environment/experience ids are correct.`,\n      { spaceId, environmentId, experienceId, cause: err }\n    );\n  }\n\n  const payload = toExperiencePayload(response);\n  const sourceMap = withSourceMap ? readSourceMap(response) : undefined;\n\n  log.lazy('received raw payload', () => payload);\n  if (withSourceMap && !sourceMap) log.log('source map requested but not returned');\n\n  return resolveExperience(payload, config, {\n    metadata,\n    debug,\n    initialViewportId,\n    sourceMap,\n  });\n}\n\n/**\n * Shared response-handling for both destination-shaped `fetchExperience`\n * branches (by node id, by path).\n */\nasync function fetchByDestination(\n  identity: { spaceId: string; destinationId: string; locator: string },\n  resolve: () => Promise<ContentfulViewDelivery.DestinationExperienceResolutionResponse>,\n  log: ReturnType<typeof createDebugLogger>,\n  resolveOptions: {\n    config: ResolverConfig;\n    metadata: Record<string, unknown> | undefined;\n    debug: boolean | undefined;\n    initialViewportId: string | undefined;\n  }\n): Promise<PortableRenderPlan | DestinationRedirectResult> {\n  const { spaceId, destinationId, locator } = identity;\n  const { config, metadata, debug, initialViewportId } = resolveOptions;\n\n  log.log('resolving destination experience', { spaceId, destinationId, locator });\n\n  let response: ContentfulViewDelivery.DestinationExperienceResolutionResponse;\n  try {\n    response = await resolve();\n  } catch (err) {\n    if (err instanceof ContentfulViewDelivery.NotFoundError) {\n      throw err;\n    }\n    const reason = err instanceof Error ? err.message : String(err);\n    throw new ExperienceFetchError(\n      `Failed to resolve Destination \"${destinationId}\" at \"${locator}\" (space \"${spaceId}\"): ` +\n        `${reason}. Check network connectivity, the access token, and that the space/` +\n        `destination/node-or-path values are correct.`,\n      { spaceId, experienceId: locator, cause: err }\n    );\n  }\n\n  if ('redirect' in response) {\n    log.log('destination resolved to a redirect', response.redirect);\n    return { redirect: response.redirect };\n  }\n\n  const [firstExperience] = response.experiences;\n  if (!firstExperience) {\n    throw new ExperienceFetchError(\n      `Destination \"${destinationId}\" resolved \"${locator}\" to zero Experiences ` +\n        `(space \"${spaceId}\"). Expected exactly one hydrated Experience or a redirect.`,\n      { spaceId, experienceId: locator }\n    );\n  }\n\n  const payload = toExperiencePayloadFromDestination(firstExperience.experience);\n  log.lazy('received raw payload', () => payload);\n\n  return resolveExperience(payload, config, {\n    metadata,\n    debug,\n    initialViewportId,\n  });\n}\n"],"mappings":"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","names":["spaceId"]}

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 import { ContentfulViewDelivery } from '@contentful/experience-delivery';
 export { ContentfulViewDelivery, ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
-export { ExperienceFetchError } from './errors.js';
+export { DestinationPreviewNotSupportedError, ExperienceFetchError } from './errors.js';
 export { CreateClientOptions, createClient } from './create-client.js';
+export { ClickBuilderArgs, DEFAULT_PAGE_PROPERTIES, default as EventBuilder, EventBuilderConfig, FlagViewBuilderArgs, HoverBuilderArgs, IdentifyBuilderArgs, InteractionBuilderArgsBase, PageViewBuilderArgs, TrackBuilderArgs, UniversalEventBuilderArgs, ViewBuilderArgs } from './event-builder.js';
 export { ByDestinationNodeIdExperienceOptions, ByDestinationPathExperienceOptions, ByIdExperienceOptions, ClientOptions, DestinationRedirectResult, ExperienceOptions, ResolveOptions, fetchExperience } from './fetch-experience.js';
+export { ContentfulExperiences, ContentfulExperiencesConfig, ExperienceRuntime, RuntimeClientSource, RuntimeEventBuilderConfig, RuntimeFetchByDestinationNodeOptions, RuntimeFetchByDestinationPathOptions, RuntimeFetchExperienceOptions, RuntimeResolveOptions } from './contentful-experiences.js';
 export { ExperienceResponse, readSourceMap, toExperiencePayload, toExperiencePayloadFromDestination } from './to-experience-payload.js';
 export { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from './hosts.js';
+import '@contentful/optimization-api-client/api-schemas';
+import 'zod/mini';
 import '@contentful/experiences-sdk-core';
 
 declare const NotFoundError: typeof ContentfulViewDelivery.NotFoundError;

package/dist/index.js

@@ -4,9 +4,12 @@ import {
   ContentfulViewDeliveryClient
 } from "@contentful/experience-delivery";
 const NotFoundError = ContentfulViewDelivery.NotFoundError;
-import { ExperienceFetchError } from "./errors.js";
+import { ExperienceFetchError, DestinationPreviewNotSupportedError } from "./errors.js";
 import { createClient } from "./create-client.js";
+import { default as default2 } from "./event-builder.js";
+export * from "./event-builder.js";
 import { fetchExperience } from "./fetch-experience.js";
+import { ContentfulExperiences } from "./contentful-experiences.js";
 import {
   readSourceMap,
   toExperiencePayload,
@@ -14,9 +17,12 @@ import {
 } from "./to-experience-payload.js";
 import { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from "./hosts.js";
 export {
+  ContentfulExperiences,
   ContentfulViewDelivery2 as ContentfulViewDelivery,
   ContentfulViewDeliveryClient,
   DELIVERY_HOST,
+  DestinationPreviewNotSupportedError,
+  default2 as EventBuilder,
   ExperienceFetchError,
   NotFoundError,
   PREVIEW_HOST,

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;\n// eslint-disable-next-line no-redeclare -- value + type share a name across separate TS namespaces, not a real redeclaration\nexport type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;\nexport { ExperienceFetchError } from './errors.js';\nexport { createClient } from './create-client.js';\nexport type { CreateClientOptions } from './create-client.js';\nexport { fetchExperience } from './fetch-experience.js';\nexport {\n  readSourceMap,\n  toExperiencePayload,\n  toExperiencePayloadFromDestination,\n} from './to-experience-payload.js';\nexport type { ExperienceResponse } from './to-experience-payload.js';\nexport type {\n  ExperienceOptions,\n  ByIdExperienceOptions,\n  ByDestinationNodeIdExperienceOptions,\n  ByDestinationPathExperienceOptions,\n  ClientOptions,\n  ResolveOptions,\n  DestinationRedirectResult,\n} from './fetch-experience.js';\nexport { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from './hosts.js';\n"],"mappings":"AAAA,SAAS,8BAA8B;AAEvC;AAAA,EACE,0BAAAA;AAAA,EACA;AAAA,OACK;AACA,MAAM,gBAAgB,uBAAuB;AAGpD,SAAS,4BAA4B;AACrC,SAAS,oBAAoB;AAE7B,SAAS,uBAAuB;AAChC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAWP,SAAS,eAAe,cAAc,8BAA8B;","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;\n// eslint-disable-next-line no-redeclare -- value + type share a name across separate TS namespaces, not a real redeclaration\nexport type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;\nexport { ExperienceFetchError, DestinationPreviewNotSupportedError } from './errors.js';\nexport { createClient } from './create-client.js';\nexport type { CreateClientOptions } from './create-client.js';\nexport { default as EventBuilder } from './event-builder.js';\nexport * from './event-builder.js';\nexport { fetchExperience } from './fetch-experience.js';\nexport { ContentfulExperiences } from './contentful-experiences.js';\nexport type {\n  ContentfulExperiencesConfig,\n  ExperienceRuntime,\n  RuntimeFetchExperienceOptions,\n  RuntimeFetchByDestinationNodeOptions,\n  RuntimeFetchByDestinationPathOptions,\n  RuntimeClientSource,\n  RuntimeEventBuilderConfig,\n  RuntimeResolveOptions,\n} from './contentful-experiences.js';\nexport {\n  readSourceMap,\n  toExperiencePayload,\n  toExperiencePayloadFromDestination,\n} from './to-experience-payload.js';\nexport type { ExperienceResponse } from './to-experience-payload.js';\nexport type {\n  ExperienceOptions,\n  ByIdExperienceOptions,\n  ByDestinationNodeIdExperienceOptions,\n  ByDestinationPathExperienceOptions,\n  ClientOptions,\n  ResolveOptions,\n  DestinationRedirectResult,\n} from './fetch-experience.js';\nexport { DELIVERY_HOST, PREVIEW_HOST, PREVIEW_WEBSOCKET_HOST } from './hosts.js';\n"],"mappings":"AAAA,SAAS,8BAA8B;AAEvC;AAAA,EACE,0BAAAA;AAAA,EACA;AAAA,OACK;AACA,MAAM,gBAAgB,uBAAuB;AAGpD,SAAS,sBAAsB,2CAA2C;AAC1E,SAAS,oBAAoB;AAE7B,SAAoB,WAAXC,gBAA+B;AACxC,cAAc;AACd,SAAS,uBAAuB;AAChC,SAAS,6BAA6B;AAWtC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAWP,SAAS,eAAe,cAAc,8BAA8B;","names":["ContentfulViewDelivery","default"]}

package/dist/sdk-info.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default library metadata attached to the context of built Events.
+ *
+ * Build artifacts receive their package metadata through tsup defines. Source
+ * execution (including tests) uses stable fallback values instead.
+ */
+declare const DEFAULT_EVENT_CONTEXT_LIBRARY: {
+    name: string;
+    version: string;
+};
+
+export { DEFAULT_EVENT_CONTEXT_LIBRARY };

package/dist/sdk-info.js

@@ -0,0 +1,8 @@
+const DEFAULT_EVENT_CONTEXT_LIBRARY = {
+  name: true ? "@contentful/experiences-client" : "@contentful/experiences-client",
+  version: true ? "0.4.8" : "0.0.0"
+};
+export {
+  DEFAULT_EVENT_CONTEXT_LIBRARY
+};
+//# sourceMappingURL=sdk-info.js.map

package/dist/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk-info.ts"],"sourcesContent":["declare const __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__: string | undefined;\ndeclare const __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__: string | undefined;\n\n/**\n * Default library metadata attached to the context of built Events.\n *\n * Build artifacts receive their package metadata through tsup defines. Source\n * execution (including tests) uses stable fallback values instead.\n */\nexport const DEFAULT_EVENT_CONTEXT_LIBRARY = {\n  name:\n    typeof __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__ === 'string'\n      ? __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__\n      : '@contentful/experiences-client',\n  version:\n    typeof __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__ === 'string'\n      ? __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__\n      : '0.0.0',\n};\n"],"mappings":"AASO,MAAM,gCAAgC;AAAA,EAC3C,MACE,OACI,mCACA;AAAA,EACN,SACE,OACI,UACA;AACR;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-client",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Delivery client + fetchExperience for Contentful Experiences",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,9 @@
   },
   "dependencies": {
     "@contentful/experience-delivery": "1.0.0-dev.8",
-    "@contentful/experiences-sdk-core": "0.8.6"
+    "@contentful/experiences-sdk-core": "0.8.7",
+    "@contentful/optimization-api-client": "^2.0.1",
+    "es-toolkit": "^1.46.0",
+    "zod": "^4.3.6"
   }
 }