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

package/dist/client/index.cjs

@@ -542,6 +542,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
@@ -656,6 +675,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();
@@ -985,6 +1231,20 @@ var AutoTracker = class {
   }
 };
 
+// src/server/cookies.ts
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const idx = part.indexOf("=");
+    if (idx === -1) continue;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (key) out[key] = decodeURIComponent(value);
+  }
+  return out;
+}
+
 // src/client/identity.ts
 var SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
 var Identity = class {
@@ -1032,10 +1292,19 @@ var Identity = class {
     } catch {
     }
   }
+  /** The visitor id already in the cookie — e.g. minted by `xeniaProxy()` on the first request. */
+  readVisitorCookie() {
+    if (!this.cookie || typeof document === "undefined") return null;
+    try {
+      return parseCookies(document.cookie)[this.cookieName()] || null;
+    } catch {
+      return null;
+    }
+  }
   // ── Device id ────────────────────────────────────────────────────────────
   /**
-   * Resolve a stable device id: localStorage cache → MediaDevices → SHA-256
-   * browser fingerprint. Cached for the session and across reloads.
+   * Resolve a stable device id: localStorage cache → the visitor cookie a server already set →
+   * MediaDevices → SHA-256 browser fingerprint. Cached for the session and across reloads.
    */
   async resolveDeviceId() {
     if (this.deviceId) {
@@ -1052,7 +1321,8 @@ var Identity = class {
       }
     } catch {
     }
-    let id = await this.mediaDeviceId();
+    let id = this.readVisitorCookie();
+    if (!id) id = await this.mediaDeviceId();
     if (!id) id = await this.fingerprint();
     this.deviceId = id;
     try {
@@ -1907,7 +2177,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) {
@@ -1937,10 +2210,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({
@@ -1976,7 +2253,8 @@ var XeniaClient = class {
     this.tracker = null;
     this.renderer.destroy();
     this.analyticsQueue.stop();
-    this.ready = false;
+    this.booting = null;
+    this.generation++;
   }
   // ── Identity ───────────────────────────────────────────────────────────────
   /**
@@ -2105,6 +2383,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;
@@ -2183,8 +2482,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;
@@ -2238,8 +2537,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 ─────────────────────────────────────────────────
@@ -2373,6 +2672,9 @@ exports.extractContentSwaps = extractContentSwaps;
 exports.hideContent = hideContent;
 exports.parseActions = parseActions;
 exports.parseDataAttribute = parseDataAttribute;
+exports.pendingTargets = pendingTargets;
+exports.personalizeContent = personalizeContent;
+exports.personalizePage = personalizePage;
 exports.readSlotMeta = readSlotMeta;
 exports.resolveTarget = resolveTarget;
 exports.showContent = showContent;