@xenia-martech/sdk-js 1.2.0-dev.7 → 1.2.0-dev.9

package/dist/personalize-content-Cwc2AomC.d.ts

@@ -1,141 +0,0 @@
-import { h as EntrySwapOp, g as EntryQuery, e as EntryDecision, p as ResolveOptions } from './types-DgVHS4Qw.js';
-
-/**
- * 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;
-    /**
-     * The content keys (Personalization Resolve identifiers) that personalize this entry. A page only
-     * acts on markers that list its `contentKey`; a marker without keys is ignored.
-     */
-    keys?: string[];
-}
-/** 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;
-    /**
-     * The page's Personalization Resolve identifier (required). Only that journey personalizes the
-     * page: a marker that doesn't list this key is plain content, and the backend decides for this key
-     * alone — another journey targeting the same section is neither consulted nor run.
-     */
-    contentKey: 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, adapter: CmsAdapter, contentKey: string): 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>>;
-
-export { personalizeContent as d, personalizePage as e, pendingTargets as p };
-export type { AppliedSwap as A, CmsAdapter as C, EntryResolver as E, PagePersonalizeOptions as P, XeniaMarker as X, PageRef as a, PersonalizeContentOptions as b, PersonalizeContentResult as c };

package/dist/personalize-content-CxSdplMV.d.cts

@@ -1,141 +0,0 @@
-import { h as EntrySwapOp, g as EntryQuery, e as EntryDecision, p as ResolveOptions } from './types-DgVHS4Qw.cjs';
-
-/**
- * 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;
-    /**
-     * The content keys (Personalization Resolve identifiers) that personalize this entry. A page only
-     * acts on markers that list its `contentKey`; a marker without keys is ignored.
-     */
-    keys?: string[];
-}
-/** 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;
-    /**
-     * The page's Personalization Resolve identifier (required). Only that journey personalizes the
-     * page: a marker that doesn't list this key is plain content, and the backend decides for this key
-     * alone — another journey targeting the same section is neither consulted nor run.
-     */
-    contentKey: 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, adapter: CmsAdapter, contentKey: string): 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>>;
-
-export { personalizeContent as d, personalizePage as e, pendingTargets as p };
-export type { AppliedSwap as A, CmsAdapter as C, EntryResolver as E, PagePersonalizeOptions as P, XeniaMarker as X, PageRef as a, PersonalizeContentOptions as b, PersonalizeContentResult as c };