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

package/dist/client/react/index.cjs

@@ -549,6 +549,25 @@ var XeniaApi = class {
     });
     return data;
   }
+  /**
+   * 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.
+   */
+  async resolveEntries(entryIds, opts = {}) {
+    const { data } = await this.http.request({
+      method: "POST",
+      path: "/api/personalization/resolve-entries",
+      headers: await this.authHeaders(),
+      body: compact({
+        entryIds,
+        data: opts.data,
+        locale: opts.locale
+      })
+    });
+    return data;
+  }
 };
 
 // src/core/cookie-names.ts
@@ -663,6 +682,233 @@ function toEventId(raw) {
   return digest;
 }
 
+// src/core/personalize-content.ts
+var DEFAULT_TIMEOUT_MS = 300;
+var DEFAULT_MAX_ROUNDS = 3;
+var copyOf = (v) => v && typeof v === "object" && typeof structuredClone === "function" ? structuredClone(v) : v;
+async function personalizeContent(payload, options) {
+  const { cms } = options;
+  const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const applied = [];
+  const report = (swap) => {
+    applied.push(swap);
+    try {
+      options.onApplied?.(swap);
+    } catch {
+    }
+  };
+  let content = payload;
+  try {
+    if (!options.inPlace && typeof structuredClone === "function") content = structuredClone(content);
+    content = cms.prepare ? cms.prepare(content) : content;
+  } catch (error) {
+    return { content: payload, applied, complete: false, error };
+  }
+  const box = { root: content };
+  const settled = /* @__PURE__ */ new WeakSet();
+  const decided = /* @__PURE__ */ new Map();
+  let frontier = [{ parent: box, key: "root", value: box.root }];
+  const settle = (target, d, round) => {
+    settled.add(target.entry);
+    cms.clearMarker?.(target.entry);
+    const items = d.items.map(copyOf);
+    if (!d.decision || items.length === 0) {
+      return deferredSlots(target, cms);
+    }
+    for (const item of items) if (item && typeof item === "object") settled.add(item);
+    const op = d.decision.op ?? target.marker.op ?? "replace";
+    const next = apply(target, op, d.decision.field ?? target.marker.field, items, cms);
+    report({
+      target: target.id,
+      kind: "runtime",
+      op,
+      entryIds: items.map((e) => cms.entryId(e)).filter((id) => !!id),
+      contentKey: d.decision.contentKey,
+      bucket: d.decision.bucket,
+      round
+    });
+    return next;
+  };
+  for (let round = 0; ; round++) {
+    const pending = walk(frontier, cms, settled, round, report, (t) => {
+      const d = decided.get(t.id);
+      return d ? settle(t, d, round) : void 0;
+    });
+    if (pending.size === 0) return { content: box.root, applied, complete: true };
+    if (!options.resolve || round >= maxRounds) {
+      return { content: box.root, applied, complete: !options.resolve };
+    }
+    progress(options, { content: box.root, round, pending: [...pending.keys()] });
+    let decisions;
+    let entriesById;
+    let queried;
+    try {
+      decisions = await withDeadline(options.resolve([...pending.keys()]), deadline);
+      ({ entriesById, queried } = await withDeadline(loadReplacements(decisions, cms, options.locale), deadline));
+    } catch (error) {
+      return { content: box.root, applied, complete: false, error: error === TIMEOUT ? void 0 : error };
+    }
+    const byTarget = new Map(decisions.map((d) => [d.target, d]));
+    frontier = [];
+    for (const target of pending.values()) {
+      const decision = byTarget.get(target.id);
+      const items = decision ? decision.ids ? decision.ids.map((id) => entriesById.get(id)).filter((e) => e !== void 0) : queried.get(decision) ?? [] : [];
+      const d = { decision, items };
+      decided.set(target.id, d);
+      frontier.push(...settle(target, d, round));
+    }
+    progress(options, { content: box.root, round, pending: [] });
+  }
+}
+function progress(options, p) {
+  try {
+    options.onProgress?.(p);
+  } catch {
+  }
+}
+function walk(frontier, cms, settled, round, report, reuse) {
+  const pending = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new WeakSet();
+  const deferred = /* @__PURE__ */ new WeakSet();
+  const queue = [...frontier];
+  while (queue.length > 0) {
+    const slot = queue.shift();
+    const value = slot.value;
+    if (!value || typeof value !== "object" || deferred.has(value)) continue;
+    const id = settled.has(value) ? void 0 : cms.entryId(value);
+    const marker = id ? cms.marker(value) : null;
+    if (id && marker?.kind === "runtime") {
+      const again = reuse({ id, marker, entry: value, slots: [slot] });
+      if (again) {
+        queue.push(...again);
+        continue;
+      }
+      const existing = pending.get(id);
+      if (existing) {
+        existing.slots.push(slot);
+      } else {
+        pending.set(id, { id, marker, entry: value, slots: [slot] });
+        if (marker.op === "items" && marker.field) {
+          const held = cms.getField(value, marker.field);
+          if (held && typeof held === "object") deferred.add(held);
+          queue.push(...children(value));
+        }
+      }
+      continue;
+    }
+    if (id && marker?.kind === "static") {
+      const variants = cms.staticVariants(value).filter((v) => v && typeof v === "object");
+      settled.add(value);
+      cms.clearMarker?.(value);
+      if (variants.length > 0) {
+        for (const v of variants) settled.add(v);
+        const op = marker.op ?? "replace";
+        const target = { entry: value, slots: [slot] };
+        queue.push(...apply(target, op, marker.field, variants, cms));
+        report({
+          target: id,
+          kind: "static",
+          op,
+          entryIds: variants.map((v) => cms.entryId(v)).filter((x) => !!x),
+          round
+        });
+        continue;
+      }
+    }
+    if (seen.has(value)) continue;
+    seen.add(value);
+    queue.push(...children(value));
+  }
+  return pending;
+}
+function apply(target, op, field, items, cms) {
+  if (op === "items") {
+    if (field) {
+      cms.setField(target.entry, field, items);
+      return [{ parent: target.entry, key: field, value: cms.getField(target.entry, field) }];
+    }
+    if (cms.mergeItems) {
+      cms.mergeItems(target.entry, items[0]);
+      return target.slots.map((s) => ({ ...s, value: target.entry }));
+    }
+    op = "replace";
+  }
+  const next = [];
+  for (const slot of target.slots) {
+    const placed = op === "expand" && Array.isArray(slot.parent) ? items : [items[0]];
+    if (Array.isArray(slot.parent)) {
+      const index = slot.parent.indexOf(target.entry);
+      if (index < 0) continue;
+      slot.parent.splice(index, 1, ...placed);
+    } else {
+      slot.parent[slot.key] = placed[0];
+    }
+    for (const value of placed) next.push({ parent: slot.parent, key: slot.key, value });
+  }
+  return next;
+}
+function deferredSlots(target, cms) {
+  if (target.marker.op === "items" && target.marker.field) {
+    return [{ parent: target.entry, key: target.marker.field, value: cms.getField(target.entry, target.marker.field) }];
+  }
+  return target.slots.map((s) => ({ ...s, value: target.entry }));
+}
+function children(value) {
+  if (Array.isArray(value)) return value.map((v, i) => ({ parent: value, key: i, value: v }));
+  return Object.keys(value).map((k) => ({ parent: value, key: k, value: value[k] }));
+}
+async function loadReplacements(decisions, cms, locale) {
+  const ids = [...new Set(decisions.flatMap((d) => d.ids ?? []))];
+  const queries = decisions.filter((d) => !d.ids && d.query);
+  const [fetched, ...results] = await Promise.all([
+    ids.length > 0 ? cms.fetchEntries(ids, locale) : Promise.resolve([]),
+    ...queries.map((d) => cms.queryEntries(d.query, locale).catch(() => []))
+  ]);
+  const entriesById = /* @__PURE__ */ new Map();
+  for (const entry of fetched) {
+    const id = cms.entryId(entry);
+    if (id) entriesById.set(id, entry);
+  }
+  const queried = /* @__PURE__ */ new Map();
+  queries.forEach((d, i) => queried.set(d, results[i]));
+  return { entriesById, queried };
+}
+var TIMEOUT = /* @__PURE__ */ Symbol("timeout");
+function withDeadline(promise, deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) return Promise.reject(TIMEOUT);
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(TIMEOUT), remaining);
+    })
+  ]).finally(() => clearTimeout(timer));
+}
+function pendingTargets(payload, cms) {
+  try {
+    let content = typeof structuredClone === "function" ? structuredClone(payload) : payload;
+    content = cms.prepare ? cms.prepare(content) : content;
+    const root = { parent: { root: content }, key: "root", value: content };
+    return [...walk([root], cms, /* @__PURE__ */ new WeakSet(), 0, () => {
+    }, () => void 0).keys()];
+  } catch {
+    return [];
+  }
+}
+async function personalizePage(ref, options) {
+  let page;
+  try {
+    if (!options.cms.fetchPage) throw new Error("This CMS adapter cannot fetch pages; use personalizeContent(page)");
+    page = await options.cms.fetchPage(ref, options.locale);
+  } catch (error) {
+    return { content: null, applied: [], complete: false, error };
+  }
+  if (page == null) return { content: null, applied: [], complete: true };
+  return personalizeContent(page, options);
+}
+
 // src/core/response-store.ts
 var MemoryResponseStore = class {
   map = /* @__PURE__ */ new Map();
@@ -1914,7 +2160,10 @@ var XeniaClient = class {
   renderer;
   analyticsQueue;
   tracker = null;
-  ready = false;
+  /** The in-flight (or finished) boot; shared so concurrent `init()` calls start one tracker. */
+  booting = null;
+  /** Bumped by `destroy()`, so a boot still waiting on the device id knows to stop. */
+  generation = 0;
   consentState;
   listeners = /* @__PURE__ */ new Map();
   constructor(options) {
@@ -1944,10 +2193,14 @@ var XeniaClient = class {
     });
   }
   /** Boot the client: resolve device id and start auto-tracking. Idempotent. */
-  async init() {
-    if (this.ready || !isBrowser()) return;
+  init() {
+    if (!isBrowser()) return Promise.resolve();
+    return this.booting ??= this.boot();
+  }
+  async boot() {
+    const generation = this.generation;
     await this.identity.resolveDeviceId();
-    this.ready = true;
+    if (generation !== this.generation) return;
     if (this.analyticsAllowed()) this.analyticsQueue.start();
     if (this.options.autoTrack !== false) {
       this.tracker = new AutoTracker({
@@ -1983,7 +2236,8 @@ var XeniaClient = class {
     this.tracker = null;
     this.renderer.destroy();
     this.analyticsQueue.stop();
-    this.ready = false;
+    this.booting = null;
+    this.generation++;
   }
   // ── Identity ───────────────────────────────────────────────────────────────
   /**
@@ -2112,6 +2366,27 @@ var XeniaClient = class {
   async resolveBatch(items, opts) {
     return this.api.resolveBatch(items, this.withVisitor(opts));
   }
+  /**
+   * 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.
+   */
+  async personalizeContent(page, opts) {
+    return personalizeContent(page, { ...opts, resolve: this.entryResolver(opts) });
+  }
+  /**
+   * 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`.
+   */
+  async personalizePage(ref, opts) {
+    return personalizePage(ref, { ...opts, resolve: this.entryResolver(opts) });
+  }
+  entryResolver(opts) {
+    const resolveOpts = this.withVisitor({ data: opts.data, locale: opts.locale });
+    return async (ids) => (await this.api.resolveEntries(ids, resolveOpts)).decisions ?? [];
+  }
   /** The SDK-owned visitor anchor: the `identify()`/`config.visitorId` id, else the device id. */
   resolveVisitorId() {
     return this.identity.getVisitorId() ?? this.identity.getDeviceId() ?? void 0;
@@ -2190,8 +2465,8 @@ var XeniaClient = class {
     const response = await this.api.webhook(triggerId, body, opts?.method ?? "POST");
     this.responses.set(triggerId, response);
     this.emit("response", { triggerId, response });
-    const apply = opts?.apply ?? this.options.autoApplyActions !== false;
-    if (apply && response.actions.length) {
+    const apply2 = opts?.apply ?? this.options.autoApplyActions !== false;
+    if (apply2 && response.actions.length) {
       this.applyActions(response.actions);
     }
     return response;
@@ -2245,8 +2520,8 @@ var XeniaClient = class {
       compact({ ...ambient, fields })
     );
     this.emit("response", { triggerId: ref, response });
-    const apply = opts?.apply ?? this.options.autoApplyActions !== false;
-    if (apply && response.actions.length) this.applyActions(response.actions);
+    const apply2 = opts?.apply ?? this.options.autoApplyActions !== false;
+    if (apply2 && response.actions.length) this.applyActions(response.actions);
     return response;
   }
   // ── Imperative render helpers ─────────────────────────────────────────────────
@@ -2324,7 +2599,7 @@ function useXenia() {
   }
   return client;
 }
-function XeniaProvider({ children, client, ...options }) {
+function XeniaProvider({ children: children2, client, ...options }) {
   const ref = react.useRef(null);
   const instance = react.useMemo(() => {
     if (client) return client;
@@ -2335,7 +2610,7 @@ function XeniaProvider({ children, client, ...options }) {
     void instance.init();
     return () => instance.destroy();
   }, [instance]);
-  return /* @__PURE__ */ jsxRuntime.jsx(XeniaContext.Provider, { value: instance, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(XeniaContext.Provider, { value: instance, children: children2 });
 }
 
 // src/core/content-splice.ts
@@ -2522,12 +2797,92 @@ function useXeniaResponse(key) {
   const xenia = useXenia();
   return xenia.getResponse(key);
 }
+function usePersonalizedContent(page, opts) {
+  const xenia = useXenia();
+  const hide = opts.render === "hide-until-resolved";
+  const initialPending = react.useMemo(
+    () => new Set(page == null ? [] : pendingTargets(page, opts.cms)),
+    [page]
+    // markers live in `page`; a new adapter object for the same page changes nothing
+  );
+  const [state, setState] = react.useState(
+    () => ({ page, content: hide ? null : page ?? null, done: false, complete: false, applied: [], pending: initialPending })
+  );
+  const optsRef = react.useRef(opts);
+  optsRef.current = opts;
+  const optsKey = JSON.stringify({ data: opts.data ?? {}, locale: opts.locale });
+  react.useEffect(() => {
+    if (page == null) return;
+    let active = true;
+    const o = optsRef.current;
+    setState({ page, content: hide ? null : page, done: false, complete: false, applied: [], pending: initialPending });
+    const reveal = hide ? setTimeout(() => active && setState((s) => s.content ? s : { ...s, content: page }), o.hideTimeoutMs ?? o.timeoutMs ?? 300) : void 0;
+    const applied = [];
+    void xenia.personalizeContent(page, {
+      ...o,
+      onApplied(swap) {
+        applied.push(swap);
+        o.onApplied?.(swap);
+      },
+      onProgress(p) {
+        o.onProgress?.(p);
+        if (!active || hide) return;
+        setState({ page, content: p.content, done: false, complete: false, applied: [...applied], pending: new Set(p.pending) });
+      }
+    }).then((r) => {
+      if (active) setState({ page, content: r.content, done: true, complete: r.complete, applied: r.applied, pending: /* @__PURE__ */ new Set() });
+    }).finally(() => clearTimeout(reveal));
+    return () => {
+      active = false;
+      clearTimeout(reveal);
+    };
+  }, [xenia, page, optsKey, hide, initialPending]);
+  const personalized = new Set(state.applied.map((a) => a.target));
+  const pending = state.page === page ? state.pending : initialPending;
+  return {
+    content: state.content,
+    isLoading: page != null && !state.done,
+    complete: state.complete,
+    applied: state.applied,
+    status: (id) => pending.has(id) ? "pending" : personalized.has(id) ? "personalized" : "base"
+  };
+}
+function usePersonalizedPage(ref, opts) {
+  const [page, setPage] = react.useState({ value: null, loaded: false });
+  const cmsRef = react.useRef(opts.cms);
+  cmsRef.current = opts.cms;
+  const refKey = JSON.stringify([ref, opts.locale]);
+  react.useEffect(() => {
+    let active = true;
+    setPage({ value: null, loaded: false });
+    const fetchPage = cmsRef.current.fetchPage;
+    Promise.resolve(fetchPage ? fetchPage.call(cmsRef.current, ref, opts.locale) : null).then(
+      (value) => active && setPage({ value: value ?? null, loaded: true }),
+      () => active && setPage({ value: null, loaded: true, failed: true })
+    );
+    return () => {
+      active = false;
+    };
+  }, [refKey]);
+  const result = usePersonalizedContent(page.value, opts);
+  const complete = page.value == null ? page.loaded && !page.failed : result.complete;
+  return { ...result, isLoading: !page.loaded || result.isLoading, complete };
+}
+var PersonalizedContentContext = react.createContext(null);
+function XeniaContentProvider(props) {
+  return react.createElement(PersonalizedContentContext.Provider, { value: props.value }, props.children);
+}
+function useXeniaEntry(entryId) {
+  const ctx = react.useContext(PersonalizedContentContext);
+  const status = ctx ? ctx.status(entryId) : "base";
+  return { status, isLoading: status === "pending" };
+}
 function XeniaTrack({
   event,
   on = "click",
   props,
   as = "span",
-  children,
+  children: children2,
   className
 }) {
   const xenia = useXenia();
@@ -2559,7 +2914,7 @@ function XeniaTrack({
   const handlers = on === "click" ? {
     onClick: () => xenia.track(event, { ...props, interactionType: "click" }, { trigger: true })
   } : {};
-  return react.createElement(as, { ref, className, ...handlers }, children);
+  return react.createElement(as, { ref, className, ...handlers }, children2);
 }
 function XeniaMessage({ actions }) {
   const xenia = useXenia();
@@ -2577,6 +2932,7 @@ function reactMessageComponent(Component) {
 }
 
 exports.XeniaClient = XeniaClient;
+exports.XeniaContentProvider = XeniaContentProvider;
 exports.XeniaContext = XeniaContext;
 exports.XeniaMessage = XeniaMessage;
 exports.XeniaProvider = XeniaProvider;
@@ -2584,15 +2940,21 @@ exports.XeniaTrack = XeniaTrack;
 exports.createXeniaClient = createXeniaClient;
 exports.extractContentSwaps = extractContentSwaps;
 exports.parseActions = parseActions;
+exports.pendingTargets = pendingTargets;
+exports.personalizeContent = personalizeContent;
+exports.personalizePage = personalizePage;
 exports.reactMessageComponent = reactMessageComponent;
 exports.spliceSlots = spliceSlots;
 exports.usePersonalization = usePersonalization;
 exports.usePersonalizationResolve = usePersonalizationResolve;
 exports.usePersonalizationResolveSlots = usePersonalizationResolveSlots;
 exports.usePersonalizationSlots = usePersonalizationSlots;
+exports.usePersonalizedContent = usePersonalizedContent;
+exports.usePersonalizedPage = usePersonalizedPage;
 exports.useTrack = useTrack;
 exports.useWebhook = useWebhook;
 exports.useXenia = useXenia;
+exports.useXeniaEntry = useXeniaEntry;
 exports.useXeniaResponse = useXeniaResponse;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map