@xenia-martech/sdk-js 1.1.0-rc.2 → 1.2.0-dev.1

package/README.md

@@ -1,5 +1,13 @@
 # @xenia-martech/sdk-js
 
+[![npm version](https://img.shields.io/npm/v/@xenia-martech/sdk-js.svg)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+[![npm downloads](https://img.shields.io/npm/dm/@xenia-martech/sdk-js.svg)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+[![coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2F%40xenia-martech%2Fsdk-js%40latest%2Fassets%2Fcoverage.json)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+[![types](https://img.shields.io/npm/types/@xenia-martech/sdk-js.svg)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+[![bundle size](https://img.shields.io/bundlejs/size/@xenia-martech/sdk-js)](https://bundlejs.com/?q=%40xenia-martech/sdk-js)
+[![node](https://img.shields.io/node/v/@xenia-martech/sdk-js.svg)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+[![license](https://img.shields.io/npm/l/@xenia-martech/sdk-js.svg)](https://www.npmjs.com/package/@xenia-martech/sdk-js)
+
 The official Xenia Marketer SDK for **web (pull) channels**. Drop in one wrapper, annotate a few elements, and Xenia handles identity, attribution, event delivery, in-page personalization, and analytics for you — from any framework, or none.
 
 **Jump to a quick start:** [React](#-react) · [Vue / Angular / plain JS](#-vue-angular-or-plain-js) · [No-build (`<script>` tag)](#-no-build-iife) · [Server / Next.js / RSC](#-server-ssr--rsc)
@@ -131,6 +139,7 @@ Building a plain HTML site (no npm, no bundler)? Skip the install and pull the p
 | `@xenia-martech/sdk-js/client/react` | browser + React | `<XeniaProvider>` + hooks (`useTrack`, `usePersonalization`, `useWebhook`, …), built on top of `/client`. |
 | `@xenia-martech/sdk-js/server` | Node / SSR / RSC | Server-side events, webhooks, personalization, and token minting. Stateless — identity passed explicitly. |
 | `@xenia-martech/sdk-js/next` | Next.js 15+ (App Router) | `xeniaProxy()` for `proxy.ts`/`middleware.ts` and `xeniaServerFromNext()` — the visitor cookie and URL context wired for you. Needs `next` (optional peer). |
+| `@xenia-martech/sdk-js/cms/contentful` | any | `contentfulAdapter()` for [CMS page personalization](#cms-page-personalization). |
 | `@xenia-martech/sdk-js/iife` | `<script>` tag | Prebuilt `window.Xenia` for sites without a bundler. |
 
 ---
@@ -694,6 +703,47 @@ function Hero({ base }: { base: HeroContent }) {
 
 The tracker reads `data-xenia-content-key` (required), `data-xenia-content-entry-id`, `data-xenia-base-entry-id`, and optional `data-xenia-personalized`. Server-side holdout *exposure* is recorded automatically by the `resolve()` call — the SDK does nothing for that.
 
+### CMS page personalization
+
+Tell the SDK which page to render; it fetches it from your CMS and swaps the entries a journey personalizes, at any depth:
+
+```ts
+import { contentfulAdapter } from "@xenia-martech/sdk-js/cms/contentful";
+
+const cms = contentfulAdapter({ space, accessToken, include: 6 });  // or { client: contentful }
+const { content } = await xenia.personalizePage({ contentType: "page", fields: { slug } }, { cms, timeoutMs: 250 });
+// or by entry id: xenia.personalizePage("1Tl24n6FueOegEOALask0F", { cms })
+// content is the page entry, or null when it doesn't exist / the CMS fetch failed (`error` says which)
+```
+
+Already fetching the page yourself (your own caching, a CMS client you keep)? Pass it in instead: `xenia.personalizeContent(page, { cms })`.
+
+How it works:
+
+- **Marking.** Xenia writes two fields onto personalized entries: `xenia` (the marker: `kind`, `op`, `field`) and `xeniaVariants` (static replacements).
+- **Static swaps cost nothing.** A static swap's replacement comes back in your own CMS fetch, so it is applied with no Xenia call.
+- **Runtime swaps cost one call per nesting level.** All runtime targets the walk finds go to Xenia in one `POST /api/personalization/resolve-entries` call. Their replacements are then loaded in one CMS call.
+- **Nested targets.** A runtime target's own subtree is not walked until it has been decided, because it may be replaced. So targets inside it, or inside its replacement, are decided in the next round.
+- **One-to-many.** `op: "expand"` splices N entries where one stood. `op: "items"` replaces an array field, e.g. a carousel's slides, with explicit entries or a content-type query (for example, "4 products in the visitor's category").
+- **Bounded and safe.** All rounds share the `timeoutMs` budget (default 300 ms), capped by `maxRounds` (default 3). It never throws: anything undecided keeps its base content.
+- **Skeletons, not flicker.** `pendingTargets(page, cms)` returns the entry ids Xenia still has to decide, read from the markers with no network call. Render those as skeletons and the visitor never sees base content that is about to change. The hooks' `status(id)` / `useXeniaEntry(id)` report `"pending"` from the first render, server render included.
+
+Where to run it:
+
+| Where | How | Trade-off |
+|---|---|---|
+| Server (SSR) | `await xeniaServer.personalizePage(ref, { cms })` | No flicker. Adds at most one Xenia round trip per nesting level to the response. |
+| Next.js RSC, streamed | `personalizePage(ref, { cms, maxRounds: 0 })` for the page with no Xenia call; render the `pendingTargets()` entries as skeletons in a `<Suspense>` fallback, and the full `personalizePage` inside it (share one run per request with `personalizeOnce(key, fn)` from `/next`) | Fast first byte. Skeletons fill in when ready; no content changes. |
+| Server + browser | Run on the server with `maxRounds: 1`, then pass the result to `usePersonalizedContent` | Above-the-fold content is personalized on the server. Deeper levels finish in the browser. Entries already decided are not asked about again. |
+| Browser | `usePersonalizedPage(ref, { cms, render })` (or `usePersonalizedContent(page, …)` for a page you fetched) | `"base-first"` shows the page at once; render `status(id) === "pending"` entries as skeletons and they fill in as they are decided. `"hide-until-resolved"` holds the content back (up to `hideTimeoutMs`) so you can show a skeleton. `status(id)` and `useXeniaEntry(id)` give a loading state per entry. |
+
+**Other CMSs.** Implement `CmsAdapter`:
+
+- `entryId`, `marker`, `staticVariants`, `getField` / `setField` and `fetchEntries` / `queryEntries` are what you write;
+- `fetchPage` (needed for `personalizePage`), `prepare`, `mergeItems` and `clearMarker` are optional.
+
+The walk, rounds, budget and splicing are shared.
+
 ### Webhook-backed personalization
 
 `usePersonalization(triggerId, data?)` is an explicit, standalone-looking call — but under the hood it's entirely webhook-based: it fires the given webhook trigger (same journey/webhook mechanism as `useWebhook()`) and hands you back the response body as `data`, re-firing whenever `triggerId` or `data` changes:

package/assets/coverage.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"coverage","message":"98%","color":"brightgreen"}

package/dist/{actions-CKeiofxJ.d.cts → actions-D9_aAvCv.d.cts}

@@ -351,6 +351,41 @@ interface ResolveOptions {
      */
     context?: EventContext;
 }
+/** How a personalized entry's replacement is spliced into the page. */
+type EntrySwapOp = "replace" | "expand" | "items";
+/** CMS-neutral filter of a content-type query; the adapter maps it to its CMS syntax. */
+interface EntryFilter {
+    field: string;
+    op: "eq" | "ne" | "in" | "nin" | "exists" | "lt" | "lte" | "gt" | "gte" | "match";
+    /** Already rendered from the visitor data by the backend; comma-separated for `in`/`nin`. */
+    value: string;
+}
+/** "Entries of this content type", run by the adapter against the tenant's own delivery API. */
+interface EntryQuery {
+    contentType: string;
+    filters?: EntryFilter[];
+    /** CMS order expression, e.g. `-sys.updatedAt`. */
+    order?: string;
+    limit: number;
+}
+/**
+ * Xenia's decision for one personalized entry: splice `ids` (explicit entries) or the result of
+ * `query` at `target`. A requested target with no decision keeps its base content.
+ */
+interface EntryDecision {
+    target: string;
+    op: EntrySwapOp;
+    /** Array field replaced by `op: "items"`; absent = merge the replacement's array fields. */
+    field?: string;
+    ids?: string[];
+    query?: EntryQuery;
+    contentKey: string;
+    bucket?: string;
+}
+/** Response of `POST /api/personalization/resolve-entries`. */
+interface ResolveEntriesResult {
+    decisions: EntryDecision[];
+}
 /** Body posted to `POST /api/events/v1/identify` — binds visitor to a known user. */
 interface IdentifyRequest {
     xeniaVisitorId: string;
@@ -699,8 +734,141 @@ declare class XeniaApi {
      * semantics as {@link resolve}.
      */
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    /**
+     * Resolve personalized CMS entries by id for one visitor (≤200) —
+     * `POST /api/personalization/resolve-entries`. The page resolver
+     * ({@link personalizeContent}) calls this once per round with the runtime
+     * targets it found; callers rarely need it directly.
+     */
+    resolveEntries(entryIds: string[], opts?: ResolveOptions): Promise<ResolveEntriesResult>;
 }
 
+/**
+ * CMS page personalization — walk a fetched CMS page breadth-first, swap the
+ * entries Xenia marked as personalized, and do it in as few round trips as
+ * the page's nesting allows.
+ *
+ * Rules (see the "Rounds" section of the feature plan):
+ * - **Static** targets carry their replacement in the payload (`xeniaVariants`)
+ *   and are swapped inline — no network at all.
+ * - **Runtime** targets are a barrier: their id is collected, their subtree is
+ *   NOT walked (it may be replaced). One `resolve-entries` call decides every
+ *   target found in a round, one parallel CMS fetch loads every replacement,
+ *   and the next round walks whatever now sits at each position.
+ * - Never throws: on error or when `timeoutMs` runs out, whatever is not yet
+ *   decided keeps its base content.
+ *
+ * CMS specifics live behind {@link CmsAdapter}; built-in adapters ship as
+ * `@xenia-martech/sdk-js/cms/contentful` (and later `/cms/contentstack`). Any
+ * other CMS works by implementing the interface.
+ */
+
+/** Any value inside a CMS payload — the walker is shape-agnostic; adapters give it meaning. */
+type Node = any;
+/** The parsed `xenia` marker field of a personalized entry. */
+interface XeniaMarker {
+    kind: "static" | "runtime";
+    op?: EntrySwapOp;
+    /** Array field replaced by `op: "items"`. */
+    field?: string;
+    limit?: number;
+}
+/** What the page resolver needs to know about a CMS's entries. `N` is the entry shape. */
+interface CmsAdapter<N extends object = Node> {
+    /** The entry id when `value` is a CMS entry (not a link stub, asset or plain object). */
+    entryId(value: unknown): string | undefined;
+    /** The entry's Xenia marker, or null when it is not personalized. */
+    marker(entry: N): XeniaMarker | null;
+    /** Static replacements pinned on the entry (its resolved `xeniaVariants`). */
+    staticVariants(entry: N): N[];
+    getField(entry: N, field: string): unknown;
+    setField(entry: N, field: string, value: unknown): void;
+    /** Legacy `items` without a field: copy the replacement's array fields onto the entry. */
+    mergeItems?(entry: N, replacement: N): void;
+    /**
+     * Remove the marker from an entry that has been dealt with (kept base, or had its items replaced),
+     * so personalizing the output again — e.g. the browser continuing a server render — never decides
+     * it twice. Optional; without it a re-run re-asks Xenia about those entries.
+     */
+    clearMarker?(entry: N): void;
+    /** Normalize a fetched payload before walking (e.g. resolve links). Defaults to identity. */
+    prepare?(payload: unknown): unknown;
+    /** Load entries by id in ONE call; order does not matter. */
+    fetchEntries(ids: string[], locale?: string): Promise<N[]>;
+    /** Run a content-type query in ONE call, in the query's order. */
+    queryEntries(query: EntryQuery, locale?: string): Promise<N[]>;
+    /**
+     * Load one page with its whole tree (links resolved), or null when there is none. Optional; it
+     * is what lets `personalizePage(ref)` do the fetch, so apps never fetch the page themselves.
+     */
+    fetchPage?(ref: PageRef, locale?: string): Promise<N | null>;
+}
+/** Identifies a page in the CMS: its entry id, or a content type plus exact field values (a slug). */
+type PageRef = string | {
+    contentType: string;
+    fields: Record<string, string | number | boolean>;
+};
+/** Resolves a round's runtime targets — `XeniaApi.resolveEntries` bound to the visitor. */
+type EntryResolver = (entryIds: string[]) => Promise<EntryDecision[]>;
+/** Reported for every swap actually applied (for impressions / analytics). */
+interface AppliedSwap {
+    target: string;
+    kind: "static" | "runtime";
+    op: EntrySwapOp;
+    /** Ids of the entries now at the target's position (or in its field). */
+    entryIds: string[];
+    contentKey?: string;
+    bucket?: string;
+    round: number;
+}
+interface PersonalizeContentOptions {
+    cms: CmsAdapter;
+    /** Decides runtime targets. Omit to apply static swaps only (zero network). */
+    resolve?: EntryResolver;
+    locale?: string;
+    /** Max network rounds (nesting depth of runtime targets). Default 3. */
+    maxRounds?: number;
+    /** Total budget for all rounds, in ms. Undecided targets keep their base. Default 300. */
+    timeoutMs?: number;
+    /** Mutate the payload in place instead of personalizing a copy. Default false. */
+    inPlace?: boolean;
+    onApplied?(swap: AppliedSwap): void;
+    /**
+     * Called when a round starts waiting on the network (`pending` = targets being decided) and when
+     * it has been applied (`pending` empty). `content` is the live, partially personalized tree —
+     * lets a UI render level by level instead of waiting for every round.
+     */
+    onProgress?(progress: {
+        content: unknown;
+        round: number;
+        pending: string[];
+    }): void;
+}
+/** `personalizeContent` options as taken by `XeniaClient` / `XeniaServer`, which supply `resolve`. */
+type PagePersonalizeOptions = Omit<PersonalizeContentOptions, "resolve"> & Pick<ResolveOptions, "data" | "identity" | "context">;
+interface PersonalizeContentResult<T> {
+    content: T;
+    applied: AppliedSwap[];
+    /** False when the budget ran out, a call failed, or `maxRounds` was hit with targets left. */
+    complete: boolean;
+    error?: unknown;
+}
+declare function personalizeContent<T>(payload: T, options: PersonalizeContentOptions): Promise<PersonalizeContentResult<T>>;
+/**
+ * The entries Xenia still has to decide on this page — runtime targets reachable without crossing
+ * another undecided one. Synchronous and network-free (it reads the `xenia` markers), so a page can
+ * render a skeleton in exactly those places from the first frame instead of flashing base content.
+ * Nested targets inside a pending one are found once it is decided.
+ */
+declare function pendingTargets(payload: unknown, cms: CmsAdapter): string[];
+/**
+ * Fetch a page through `options.cms` and personalize it — {@link personalizeContent} without the
+ * fetch in app code. Never throws: a failed fetch comes back as `content: null` with `error`; a page
+ * that does not exist as `content: null`, `complete: true`. The page fetch is not counted against
+ * `timeoutMs` — that budget is for personalization only.
+ */
+declare function personalizePage<T>(ref: PageRef, options: PersonalizeContentOptions): Promise<PersonalizeContentResult<T | null>>;
+
 /**
  * Persists webhook responses the SDK receives, keyed by an arbitrary string
  * (typically the eventId, triggerId, or journeyId). Lets the app read back the
@@ -831,12 +999,16 @@ declare class XeniaClient {
     private readonly renderer;
     private readonly analyticsQueue;
     private tracker;
-    private ready;
+    /** The in-flight (or finished) boot; shared so concurrent `init()` calls start one tracker. */
+    private booting;
+    /** Bumped by `destroy()`, so a boot still waiting on the device id knows to stop. */
+    private generation;
     private consentState;
     private readonly listeners;
     constructor(options: XeniaClientOptions);
     /** Boot the client: resolve device id and start auto-tracking. Idempotent. */
     init(): Promise<void>;
+    private boot;
     /** Tear down listeners, observers, and injected UI. */
     destroy(): void;
     /**
@@ -894,6 +1066,20 @@ declare class XeniaClient {
     resolve(contentKey: string, opts?: ResolveOptions): Promise<ResolveResult>;
     /** Resolve several content keys in one round-trip (`POST /api/personalization/resolve-batch`). */
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    /**
+     * Personalize a fetched CMS page: static swaps are applied from the payload, runtime targets are
+     * decided by Xenia in one `resolve-entries` call per nesting level, and replacements are loaded
+     * through `opts.cms` (e.g. `contentfulAdapter(...)`). Never throws — anything undecided within
+     * `opts.timeoutMs` keeps its base content.
+     */
+    personalizeContent<T>(page: T, opts: PagePersonalizeOptions): Promise<PersonalizeContentResult<T>>;
+    /**
+     * Fetch a page through `opts.cms` and personalize it — the app passes only the page's identity
+     * (entry id, or `{ contentType, fields: { slug } }`). Never throws: a failed fetch is `content:
+     * null` with `error`, a missing page `content: null`.
+     */
+    personalizePage<T = unknown>(ref: PageRef, opts: PagePersonalizeOptions): Promise<PersonalizeContentResult<T | null>>;
+    private entryResolver;
     /** The SDK-owned visitor anchor: the `identify()`/`config.visitorId` id, else the device id. */
     private resolveVisitorId;
     /**
@@ -1002,4 +1188,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, extractContentSwaps as B, type ConsentState as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ClientEvent as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };
+export { type AnalyticsContext as A, type WidgetType as B, type ConsentState as C, XeniaClient as D, type XeniaClientOptions as E, type XeniaMarker as F, createXeniaClient as G, extractContentSwaps as H, type InteractionType as I, type JsonValue as J, parseActions as K, pendingTargets as L, type MessageCta as M, personalizeContent as N, personalizePage as O, type PagePersonalizeOptions as P, spliceSlots as Q, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type AppliedSwap as j, type ClientEvent as k, type CmsAdapter as l, type ContentSwap as m, type IdentifyRequest as n, type IdentifyResponse as o, Identity as p, type MessageMountContext as q, type MessageRenderContext as r, type PageRef as s, type PersonalizationSwap as t, type ResolveBatchResult as u, type ResolveOptions as v, type ResolveResult as w, type WebhookResponse as x, type WidgetPrize as y, type WidgetSegment as z };

package/dist/{actions-CKeiofxJ.d.ts → actions-D9_aAvCv.d.ts}

@@ -351,6 +351,41 @@ interface ResolveOptions {
      */
     context?: EventContext;
 }
+/** How a personalized entry's replacement is spliced into the page. */
+type EntrySwapOp = "replace" | "expand" | "items";
+/** CMS-neutral filter of a content-type query; the adapter maps it to its CMS syntax. */
+interface EntryFilter {
+    field: string;
+    op: "eq" | "ne" | "in" | "nin" | "exists" | "lt" | "lte" | "gt" | "gte" | "match";
+    /** Already rendered from the visitor data by the backend; comma-separated for `in`/`nin`. */
+    value: string;
+}
+/** "Entries of this content type", run by the adapter against the tenant's own delivery API. */
+interface EntryQuery {
+    contentType: string;
+    filters?: EntryFilter[];
+    /** CMS order expression, e.g. `-sys.updatedAt`. */
+    order?: string;
+    limit: number;
+}
+/**
+ * Xenia's decision for one personalized entry: splice `ids` (explicit entries) or the result of
+ * `query` at `target`. A requested target with no decision keeps its base content.
+ */
+interface EntryDecision {
+    target: string;
+    op: EntrySwapOp;
+    /** Array field replaced by `op: "items"`; absent = merge the replacement's array fields. */
+    field?: string;
+    ids?: string[];
+    query?: EntryQuery;
+    contentKey: string;
+    bucket?: string;
+}
+/** Response of `POST /api/personalization/resolve-entries`. */
+interface ResolveEntriesResult {
+    decisions: EntryDecision[];
+}
 /** Body posted to `POST /api/events/v1/identify` — binds visitor to a known user. */
 interface IdentifyRequest {
     xeniaVisitorId: string;
@@ -699,8 +734,141 @@ declare class XeniaApi {
      * semantics as {@link resolve}.
      */
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    /**
+     * Resolve personalized CMS entries by id for one visitor (≤200) —
+     * `POST /api/personalization/resolve-entries`. The page resolver
+     * ({@link personalizeContent}) calls this once per round with the runtime
+     * targets it found; callers rarely need it directly.
+     */
+    resolveEntries(entryIds: string[], opts?: ResolveOptions): Promise<ResolveEntriesResult>;
 }
 
+/**
+ * CMS page personalization — walk a fetched CMS page breadth-first, swap the
+ * entries Xenia marked as personalized, and do it in as few round trips as
+ * the page's nesting allows.
+ *
+ * Rules (see the "Rounds" section of the feature plan):
+ * - **Static** targets carry their replacement in the payload (`xeniaVariants`)
+ *   and are swapped inline — no network at all.
+ * - **Runtime** targets are a barrier: their id is collected, their subtree is
+ *   NOT walked (it may be replaced). One `resolve-entries` call decides every
+ *   target found in a round, one parallel CMS fetch loads every replacement,
+ *   and the next round walks whatever now sits at each position.
+ * - Never throws: on error or when `timeoutMs` runs out, whatever is not yet
+ *   decided keeps its base content.
+ *
+ * CMS specifics live behind {@link CmsAdapter}; built-in adapters ship as
+ * `@xenia-martech/sdk-js/cms/contentful` (and later `/cms/contentstack`). Any
+ * other CMS works by implementing the interface.
+ */
+
+/** Any value inside a CMS payload — the walker is shape-agnostic; adapters give it meaning. */
+type Node = any;
+/** The parsed `xenia` marker field of a personalized entry. */
+interface XeniaMarker {
+    kind: "static" | "runtime";
+    op?: EntrySwapOp;
+    /** Array field replaced by `op: "items"`. */
+    field?: string;
+    limit?: number;
+}
+/** What the page resolver needs to know about a CMS's entries. `N` is the entry shape. */
+interface CmsAdapter<N extends object = Node> {
+    /** The entry id when `value` is a CMS entry (not a link stub, asset or plain object). */
+    entryId(value: unknown): string | undefined;
+    /** The entry's Xenia marker, or null when it is not personalized. */
+    marker(entry: N): XeniaMarker | null;
+    /** Static replacements pinned on the entry (its resolved `xeniaVariants`). */
+    staticVariants(entry: N): N[];
+    getField(entry: N, field: string): unknown;
+    setField(entry: N, field: string, value: unknown): void;
+    /** Legacy `items` without a field: copy the replacement's array fields onto the entry. */
+    mergeItems?(entry: N, replacement: N): void;
+    /**
+     * Remove the marker from an entry that has been dealt with (kept base, or had its items replaced),
+     * so personalizing the output again — e.g. the browser continuing a server render — never decides
+     * it twice. Optional; without it a re-run re-asks Xenia about those entries.
+     */
+    clearMarker?(entry: N): void;
+    /** Normalize a fetched payload before walking (e.g. resolve links). Defaults to identity. */
+    prepare?(payload: unknown): unknown;
+    /** Load entries by id in ONE call; order does not matter. */
+    fetchEntries(ids: string[], locale?: string): Promise<N[]>;
+    /** Run a content-type query in ONE call, in the query's order. */
+    queryEntries(query: EntryQuery, locale?: string): Promise<N[]>;
+    /**
+     * Load one page with its whole tree (links resolved), or null when there is none. Optional; it
+     * is what lets `personalizePage(ref)` do the fetch, so apps never fetch the page themselves.
+     */
+    fetchPage?(ref: PageRef, locale?: string): Promise<N | null>;
+}
+/** Identifies a page in the CMS: its entry id, or a content type plus exact field values (a slug). */
+type PageRef = string | {
+    contentType: string;
+    fields: Record<string, string | number | boolean>;
+};
+/** Resolves a round's runtime targets — `XeniaApi.resolveEntries` bound to the visitor. */
+type EntryResolver = (entryIds: string[]) => Promise<EntryDecision[]>;
+/** Reported for every swap actually applied (for impressions / analytics). */
+interface AppliedSwap {
+    target: string;
+    kind: "static" | "runtime";
+    op: EntrySwapOp;
+    /** Ids of the entries now at the target's position (or in its field). */
+    entryIds: string[];
+    contentKey?: string;
+    bucket?: string;
+    round: number;
+}
+interface PersonalizeContentOptions {
+    cms: CmsAdapter;
+    /** Decides runtime targets. Omit to apply static swaps only (zero network). */
+    resolve?: EntryResolver;
+    locale?: string;
+    /** Max network rounds (nesting depth of runtime targets). Default 3. */
+    maxRounds?: number;
+    /** Total budget for all rounds, in ms. Undecided targets keep their base. Default 300. */
+    timeoutMs?: number;
+    /** Mutate the payload in place instead of personalizing a copy. Default false. */
+    inPlace?: boolean;
+    onApplied?(swap: AppliedSwap): void;
+    /**
+     * Called when a round starts waiting on the network (`pending` = targets being decided) and when
+     * it has been applied (`pending` empty). `content` is the live, partially personalized tree —
+     * lets a UI render level by level instead of waiting for every round.
+     */
+    onProgress?(progress: {
+        content: unknown;
+        round: number;
+        pending: string[];
+    }): void;
+}
+/** `personalizeContent` options as taken by `XeniaClient` / `XeniaServer`, which supply `resolve`. */
+type PagePersonalizeOptions = Omit<PersonalizeContentOptions, "resolve"> & Pick<ResolveOptions, "data" | "identity" | "context">;
+interface PersonalizeContentResult<T> {
+    content: T;
+    applied: AppliedSwap[];
+    /** False when the budget ran out, a call failed, or `maxRounds` was hit with targets left. */
+    complete: boolean;
+    error?: unknown;
+}
+declare function personalizeContent<T>(payload: T, options: PersonalizeContentOptions): Promise<PersonalizeContentResult<T>>;
+/**
+ * The entries Xenia still has to decide on this page — runtime targets reachable without crossing
+ * another undecided one. Synchronous and network-free (it reads the `xenia` markers), so a page can
+ * render a skeleton in exactly those places from the first frame instead of flashing base content.
+ * Nested targets inside a pending one are found once it is decided.
+ */
+declare function pendingTargets(payload: unknown, cms: CmsAdapter): string[];
+/**
+ * Fetch a page through `options.cms` and personalize it — {@link personalizeContent} without the
+ * fetch in app code. Never throws: a failed fetch comes back as `content: null` with `error`; a page
+ * that does not exist as `content: null`, `complete: true`. The page fetch is not counted against
+ * `timeoutMs` — that budget is for personalization only.
+ */
+declare function personalizePage<T>(ref: PageRef, options: PersonalizeContentOptions): Promise<PersonalizeContentResult<T | null>>;
+
 /**
  * Persists webhook responses the SDK receives, keyed by an arbitrary string
  * (typically the eventId, triggerId, or journeyId). Lets the app read back the
@@ -831,12 +999,16 @@ declare class XeniaClient {
     private readonly renderer;
     private readonly analyticsQueue;
     private tracker;
-    private ready;
+    /** The in-flight (or finished) boot; shared so concurrent `init()` calls start one tracker. */
+    private booting;
+    /** Bumped by `destroy()`, so a boot still waiting on the device id knows to stop. */
+    private generation;
     private consentState;
     private readonly listeners;
     constructor(options: XeniaClientOptions);
     /** Boot the client: resolve device id and start auto-tracking. Idempotent. */
     init(): Promise<void>;
+    private boot;
     /** Tear down listeners, observers, and injected UI. */
     destroy(): void;
     /**
@@ -894,6 +1066,20 @@ declare class XeniaClient {
     resolve(contentKey: string, opts?: ResolveOptions): Promise<ResolveResult>;
     /** Resolve several content keys in one round-trip (`POST /api/personalization/resolve-batch`). */
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    /**
+     * Personalize a fetched CMS page: static swaps are applied from the payload, runtime targets are
+     * decided by Xenia in one `resolve-entries` call per nesting level, and replacements are loaded
+     * through `opts.cms` (e.g. `contentfulAdapter(...)`). Never throws — anything undecided within
+     * `opts.timeoutMs` keeps its base content.
+     */
+    personalizeContent<T>(page: T, opts: PagePersonalizeOptions): Promise<PersonalizeContentResult<T>>;
+    /**
+     * Fetch a page through `opts.cms` and personalize it — the app passes only the page's identity
+     * (entry id, or `{ contentType, fields: { slug } }`). Never throws: a failed fetch is `content:
+     * null` with `error`, a missing page `content: null`.
+     */
+    personalizePage<T = unknown>(ref: PageRef, opts: PagePersonalizeOptions): Promise<PersonalizeContentResult<T | null>>;
+    private entryResolver;
     /** The SDK-owned visitor anchor: the `identify()`/`config.visitorId` id, else the device id. */
     private resolveVisitorId;
     /**
@@ -1002,4 +1188,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, extractContentSwaps as B, type ConsentState as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ClientEvent as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };
+export { type AnalyticsContext as A, type WidgetType as B, type ConsentState as C, XeniaClient as D, type XeniaClientOptions as E, type XeniaMarker as F, createXeniaClient as G, extractContentSwaps as H, type InteractionType as I, type JsonValue as J, parseActions as K, pendingTargets as L, type MessageCta as M, personalizeContent as N, personalizePage as O, type PagePersonalizeOptions as P, spliceSlots as Q, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type AppliedSwap as j, type ClientEvent as k, type CmsAdapter as l, type ContentSwap as m, type IdentifyRequest as n, type IdentifyResponse as o, Identity as p, type MessageMountContext as q, type MessageRenderContext as r, type PageRef as s, type PersonalizationSwap as t, type ResolveBatchResult as u, type ResolveOptions as v, type ResolveResult as w, type WebhookResponse as x, type WidgetPrize as y, type WidgetSegment as z };

package/dist/api-BEPW0Uan.d.cts

@@ -0,0 +1,88 @@
+import { L as XeniaConfig, J as JsonValue, W as WebhookResponse, F as WidgetSubmitResponse, N as XeniaEvent, c as AnalyticsIngestResponse, I as IdentifyRequest, m as IdentifyResponse, f as ConsentState, w as ResolveOptions, x as ResolveResult, R as ResolveBatchItem, u as ResolveBatchResult, v as ResolveEntriesResult } from './personalize-content-Clc1oMYY.cjs';
+
+/**
+ * Low-level, isomorphic Xenia API client. Wraps the raw endpoints; identity,
+ * UTM capture, and action rendering are layered on top by the client runtime.
+ * All paths are relative to `baseUrl`, which defaults to the hosted engine
+ * (`https://engine.xeniamartech.com/xenia`) when omitted from config.
+ */
+declare class XeniaApi {
+    private readonly http;
+    private readonly tenantId;
+    private readonly environmentKey;
+    private readonly tokenProvider;
+    constructor(config: XeniaConfig);
+    /** Tenant-scope headers required by header-scoped endpoints. */
+    private tenantHeaders;
+    /**
+     * Tenant headers plus a resolved `Authorization: Bearer` header when
+     * `config.token`/`config.getToken` is set — e.g. required by a webhook
+     * trigger node configured with its own auth token. No-op (tenant headers
+     * only) when no token source is configured, so this is safe to call
+     * unconditionally on every request.
+     */
+    private authHeaders;
+    /**
+     * Webhook request/response — `GET|POST /flow?id={triggerId}`. Held open by the
+     * backend until a `webhook-response` node resolves. Returns the normalized
+     * response, including any `xeniaActions` parsed from the body.
+     *
+     * Not retried by default: the backend long-polls this call, so a retry would
+     * duplicate the journey run.
+     */
+    webhook(triggerId: string, data?: JsonValue, method?: "GET" | "POST"): Promise<WebhookResponse>;
+    /**
+     * Widget form submission — `POST /widget-submissions?ref={bindingRef}`. Used whenever the
+     * action's `formSubmit.requiresResolve` is true (spin-wheel, which must have a
+     * server-resolved outcome before anything renders) or `mode === "endpoint"` — the common
+     * plain-popup case (`mode === "journey" && !requiresResolve`) bypasses this entirely and calls
+     * {@link webhook} against `flowRef` instead (see `XeniaClient.submitWidgetForm`'s endpoint
+     * selection).
+     *
+     * Not retried (`noRetry: true`), styled like {@link webhook} — a retried POST must never
+     * double-fire a journey or double-resolve a prize server-side.
+     */
+    submitWidget(ref: string, body?: JsonValue): Promise<WidgetSubmitResponse>;
+    /**
+     * Unified event batch (max 100/request per the backend) — `POST /api/events/v1`.
+     * Records analytics for every event and matches/advances a journey for any
+     * event with `trigger: true`. Replaces the old `sendEvent()` (journey trigger)
+     * and `sendAnalytics()` (CDP) calls.
+     */
+    sendEvents(events: XeniaEvent[], opts?: {
+        keepalive?: boolean;
+    }): Promise<AnalyticsIngestResponse>;
+    /** Bind visitor→user — `POST /api/events/v1/identify`. */
+    identify(body: IdentifyRequest): Promise<IdentifyResponse>;
+    /**
+     * Update consent — `POST /api/events/v1/consent`.
+     *
+     * The three scope flags are required (non-null) by the backend, so an omitted
+     * one is sent as an explicit `false` rather than left out: a partial body like
+     * `consent({ analytics: true })` — the shape most callers actually write — is
+     * otherwise rejected with a 400 and the consent record is never stored.
+     */
+    consent(xeniaVisitorId: string, consent: ConsentState): Promise<JsonValue>;
+    /**
+     * Resolve in-entry content personalization for one content key —
+     * `POST /api/personalization/resolve?merge=<bool>`. Requires the SDK Bearer
+     * token (same credential as events; resolve is auth-required). `merge=true`
+     * returns server-spliced `content`; otherwise splice `swaps` client-side.
+     */
+    resolve(contentKey: string, opts?: ResolveOptions): Promise<ResolveResult>;
+    /**
+     * Resolve several content keys in one round-trip (≤50) —
+     * `POST /api/personalization/resolve-batch?merge=<bool>`. Same auth/merge
+     * semantics as {@link resolve}.
+     */
+    resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    /**
+     * Resolve personalized CMS entries by id for one visitor (≤200) —
+     * `POST /api/personalization/resolve-entries`. The page resolver
+     * ({@link personalizeContent}) calls this once per round with the runtime
+     * targets it found; callers rarely need it directly.
+     */
+    resolveEntries(entryIds: string[], opts?: ResolveOptions): Promise<ResolveEntriesResult>;
+}
+
+export { XeniaApi as X };