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

package/dist/index.js

@@ -1,4 +1,4 @@
-export { LocalStorageResponseStore, MemoryResponseStore, extractContentSwaps, spliceSlots } from './chunk-TLTG3BTC.js';
-export { CONSENT_COOKIE, CircuitOpenError, DEFAULT_PREFIX, HttpClient, HttpError, MAX_EVENT_ID_LENGTH, VISITOR_COOKIE, XeniaApi, buildUrl, consentCookie, consentCookieName, contextFromUrl, generateUlid, isBrowser, parseActions, toEventId, visitorCookieName } from './chunk-FYSEKFIY.js';
+export { LocalStorageResponseStore, MemoryResponseStore, extractContentSwaps, spliceSlots } from './chunk-OUZU4Z5B.js';
+export { CONSENT_COOKIE, CircuitOpenError, DEFAULT_PREFIX, HttpClient, HttpError, MAX_EVENT_ID_LENGTH, VISITOR_COOKIE, XeniaApi, buildUrl, consentCookie, consentCookieName, contextFromUrl, generateUlid, isBrowser, parseActions, pendingTargets, personalizeContent, personalizePage, toEventId, visitorCookieName } from './chunk-7NGJC7CF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/next/index.cjs

@@ -1,10 +1,31 @@
 'use strict';
 
-var chunkU2WBBOYT_cjs = require('../chunk-U2WBBOYT.cjs');
-var chunkJEKVN7HK_cjs = require('../chunk-JEKVN7HK.cjs');
+var chunk3PYPPIUM_cjs = require('../chunk-3PYPPIUM.cjs');
+var chunkIBNIRT7J_cjs = require('../chunk-IBNIRT7J.cjs');
+var React = require('react');
 var headers = require('next/headers');
 var server = require('next/server');
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
 var URL_HEADER = "x-xenia-url";
 function cookieAttributes(c = {}) {
   const sameSite = c.sameSite ?? "Lax";
@@ -17,9 +38,9 @@ function cookieAttributes(c = {}) {
   };
 }
 function xeniaProxy(request, opts = {}) {
-  const name = chunkJEKVN7HK_cjs.visitorCookieName(opts.prefix);
+  const name = chunkIBNIRT7J_cjs.visitorCookieName(opts.prefix);
   const existing = request.cookies.get(name)?.value;
-  const visitorId = existing ?? chunkJEKVN7HK_cjs.generateUlid();
+  const visitorId = existing ?? chunkIBNIRT7J_cjs.generateUlid();
   const forwarded = new Headers(opts.headers ?? request.headers);
   forwarded.set(URL_HEADER, request.url);
   if (!existing) {
@@ -32,27 +53,38 @@ function xeniaProxy(request, opts = {}) {
 }
 async function xeniaServerFromNext(config) {
   const [jar, h] = await Promise.all([headers.cookies(), headers.headers()]);
-  const name = chunkJEKVN7HK_cjs.visitorCookieName(config.prefix);
+  const name = chunkIBNIRT7J_cjs.visitorCookieName(config.prefix);
   let visitorId = config.visitorId ?? jar.get(name)?.value;
   if (!visitorId) {
-    visitorId = chunkJEKVN7HK_cjs.generateUlid();
+    visitorId = chunkIBNIRT7J_cjs.generateUlid();
     try {
       jar.set(name, visitorId, cookieAttributes());
     } catch {
     }
   }
-  return chunkU2WBBOYT_cjs.createXeniaServer({
+  return chunk3PYPPIUM_cjs.createXeniaServer({
     ...config,
     visitorId,
-    context: { ...chunkJEKVN7HK_cjs.contextFromUrl(h.get(URL_HEADER), h.get("referer")), ...config.context }
+    context: { ...chunkIBNIRT7J_cjs.contextFromUrl(h.get(URL_HEADER), h.get("referer")), ...config.context }
   });
 }
 async function consentFromNext(prefix) {
-  return chunkU2WBBOYT_cjs.getConsent((await headers.headers()).get("cookie"), prefix);
+  return chunk3PYPPIUM_cjs.getConsent((await headers.headers()).get("cookie"), prefix);
+}
+var requestStore = typeof React__namespace.cache === "function" ? React__namespace.cache(() => /* @__PURE__ */ new Map()) : () => /* @__PURE__ */ new Map();
+function personalizeOnce(key, personalize) {
+  const store = requestStore();
+  let run = store.get(key);
+  if (!run) {
+    run = personalize();
+    store.set(key, run);
+  }
+  return run;
 }
 
 exports.URL_HEADER = URL_HEADER;
 exports.consentFromNext = consentFromNext;
+exports.personalizeOnce = personalizeOnce;
 exports.xeniaProxy = xeniaProxy;
 exports.xeniaServerFromNext = xeniaServerFromNext;
 //# sourceMappingURL=index.cjs.map

package/dist/next/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/next/index.ts"],"names":["visitorCookieName","generateUlid","NextResponse","cookies","headers","createXeniaServer","contextFromUrl","getConsent"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.\n *\n * A Server Component can't see its own URL or set cookies during render, so the two halves split\n * the work: `xeniaProxy()` runs in `proxy.ts`/`middleware.ts` (mints the visitor cookie, stamps the\n * URL onto a request header), and `xeniaServerFromNext()` reads both back to bind a per-request\n * `XeniaServer`. Use them together; each alone degrades gracefully (no URL context / a throwaway\n * visitor id).\n */\n\nimport { cookies, headers } from \"next/headers\";\nimport { NextResponse, type NextRequest } from \"next/server\";\nimport { visitorCookieName } from \"../core/cookie-names\";\nimport { generateUlid } from \"../core/id\";\nimport { contextFromUrl } from \"../core/request-context\";\nimport type { ConsentState, VisitorCookieOptions, XeniaConfig } from \"../core/types\";\nimport { getConsent } from \"../server/cookies\";\nimport { createXeniaServer, type XeniaServer } from \"../server/xenia-server\";\n\n/** Request header `xeniaProxy()` stamps with the URL being served. */\nexport const URL_HEADER = \"x-xenia-url\";\n\nexport interface XeniaProxyOptions {\n  /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */\n  headers?: Headers;\n  /** Must match the browser client's `config.prefix`, if you set one. */\n  prefix?: string;\n  /** Visitor cookie attributes. Default: `path=/`, `SameSite=Lax`, one year. */\n  cookie?: VisitorCookieOptions;\n}\n\nfunction cookieAttributes(c: VisitorCookieOptions = {}) {\n  const sameSite = c.sameSite ?? \"Lax\";\n  return {\n    path: \"/\",\n    maxAge: Math.floor((c.maxAgeDays ?? 365) * 86400),\n    sameSite: sameSite.toLowerCase() as \"lax\" | \"strict\" | \"none\",\n    secure: c.secure || sameSite === \"None\",\n    ...(c.domain && { domain: c.domain }),\n  };\n}\n\n/**\n * Next.js proxy/middleware step: ensure the visitor cookie exists and stamp the URL onto\n * {@link URL_HEADER}, then continue. A new visitor id is also put on the forwarded `Cookie` header,\n * so this very request's render already sees it.\n *\n * ```ts\n * // proxy.ts\n * export const proxy = (request: NextRequest) => xeniaProxy(request);\n * ```\n */\nexport function xeniaProxy(request: NextRequest, opts: XeniaProxyOptions = {}): NextResponse {\n  const name = visitorCookieName(opts.prefix);\n  const existing = request.cookies.get(name)?.value;\n  const visitorId = existing ?? generateUlid();\n\n  const forwarded = new Headers(opts.headers ?? request.headers);\n  forwarded.set(URL_HEADER, request.url);\n  if (!existing) {\n    // NextRequest.cookies.set doesn't rewrite the forwarded Cookie header, and cookies() reads that.\n    const header = forwarded.get(\"cookie\");\n    forwarded.set(\"cookie\", header ? `${header}; ${name}=${visitorId}` : `${name}=${visitorId}`);\n  }\n\n  const response = NextResponse.next({ request: { headers: forwarded } });\n  if (!existing) response.cookies.set(name, visitorId, cookieAttributes(opts.cookie));\n  return response;\n}\n\n/**\n * A `XeniaServer` bound to this request's visitor (the cookie `xeniaProxy()` set) and URL context\n * (path, query, UTMs, referrer). For Server Components, Server Actions and Route Handlers.\n * `config.visitorId`/`config.context` still win when passed.\n */\nexport async function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer> {\n  const [jar, h] = await Promise.all([cookies(), headers()]);\n  const name = visitorCookieName(config.prefix);\n  let visitorId = config.visitorId ?? jar.get(name)?.value;\n  if (!visitorId) {\n    visitorId = generateUlid();\n    try {\n      jar.set(name, visitorId, cookieAttributes());\n    } catch {\n      // Expected during a Server Component render; xeniaProxy() is the place that persists it.\n    }\n  }\n  return createXeniaServer({\n    ...config,\n    visitorId,\n    context: { ...contextFromUrl(h.get(URL_HEADER), h.get(\"referer\")), ...config.context },\n  });\n}\n\n/** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */\nexport async function consentFromNext(prefix?: string): Promise<ConsentState> {\n  return getConsent((await headers()).get(\"cookie\"), prefix);\n}\n"]}
+{"version":3,"sources":["../../src/next/index.ts"],"names":["visitorCookieName","generateUlid","NextResponse","cookies","headers","createXeniaServer","contextFromUrl","getConsent","React"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.\n *\n * A Server Component can't see its own URL or set cookies during render, so the two halves split\n * the work: `xeniaProxy()` runs in `proxy.ts`/`middleware.ts` (mints the visitor cookie, stamps the\n * URL onto a request header), and `xeniaServerFromNext()` reads both back to bind a per-request\n * `XeniaServer`. Use them together; each alone degrades gracefully (no URL context / a throwaway\n * visitor id).\n */\n\nimport * as React from \"react\";\nimport { cookies, headers } from \"next/headers\";\nimport { NextResponse, type NextRequest } from \"next/server\";\nimport { visitorCookieName } from \"../core/cookie-names\";\nimport { generateUlid } from \"../core/id\";\nimport { contextFromUrl } from \"../core/request-context\";\nimport type { ConsentState, VisitorCookieOptions, XeniaConfig } from \"../core/types\";\nimport { getConsent } from \"../server/cookies\";\nimport { createXeniaServer, type XeniaServer } from \"../server/xenia-server\";\n\n/** Request header `xeniaProxy()` stamps with the URL being served. */\nexport const URL_HEADER = \"x-xenia-url\";\n\nexport interface XeniaProxyOptions {\n  /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */\n  headers?: Headers;\n  /** Must match the browser client's `config.prefix`, if you set one. */\n  prefix?: string;\n  /** Visitor cookie attributes. Default: `path=/`, `SameSite=Lax`, one year. */\n  cookie?: VisitorCookieOptions;\n}\n\nfunction cookieAttributes(c: VisitorCookieOptions = {}) {\n  const sameSite = c.sameSite ?? \"Lax\";\n  return {\n    path: \"/\",\n    maxAge: Math.floor((c.maxAgeDays ?? 365) * 86400),\n    sameSite: sameSite.toLowerCase() as \"lax\" | \"strict\" | \"none\",\n    secure: c.secure || sameSite === \"None\",\n    ...(c.domain && { domain: c.domain }),\n  };\n}\n\n/**\n * Next.js proxy/middleware step: ensure the visitor cookie exists and stamp the URL onto\n * {@link URL_HEADER}, then continue. A new visitor id is also put on the forwarded `Cookie` header,\n * so this very request's render already sees it.\n *\n * ```ts\n * // proxy.ts\n * export const proxy = (request: NextRequest) => xeniaProxy(request);\n * ```\n */\nexport function xeniaProxy(request: NextRequest, opts: XeniaProxyOptions = {}): NextResponse {\n  const name = visitorCookieName(opts.prefix);\n  const existing = request.cookies.get(name)?.value;\n  const visitorId = existing ?? generateUlid();\n\n  const forwarded = new Headers(opts.headers ?? request.headers);\n  forwarded.set(URL_HEADER, request.url);\n  if (!existing) {\n    // NextRequest.cookies.set doesn't rewrite the forwarded Cookie header, and cookies() reads that.\n    const header = forwarded.get(\"cookie\");\n    forwarded.set(\"cookie\", header ? `${header}; ${name}=${visitorId}` : `${name}=${visitorId}`);\n  }\n\n  const response = NextResponse.next({ request: { headers: forwarded } });\n  if (!existing) response.cookies.set(name, visitorId, cookieAttributes(opts.cookie));\n  return response;\n}\n\n/**\n * A `XeniaServer` bound to this request's visitor (the cookie `xeniaProxy()` set) and URL context\n * (path, query, UTMs, referrer). For Server Components, Server Actions and Route Handlers.\n * `config.visitorId`/`config.context` still win when passed.\n */\nexport async function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer> {\n  const [jar, h] = await Promise.all([cookies(), headers()]);\n  const name = visitorCookieName(config.prefix);\n  let visitorId = config.visitorId ?? jar.get(name)?.value;\n  if (!visitorId) {\n    visitorId = generateUlid();\n    try {\n      jar.set(name, visitorId, cookieAttributes());\n    } catch {\n      // Expected during a Server Component render; xeniaProxy() is the place that persists it.\n    }\n  }\n  return createXeniaServer({\n    ...config,\n    visitorId,\n    context: { ...contextFromUrl(h.get(URL_HEADER), h.get(\"referer\")), ...config.context },\n  });\n}\n\n/** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */\nexport async function consentFromNext(prefix?: string): Promise<ConsentState> {\n  return getConsent((await headers()).get(\"cookie\"), prefix);\n}\n\n// ── CMS page personalization ──────────────────────────────────────────────────\n\n// One store per server request (React.cache scopes it to the render), so every section that asks\n// for the same page shares ONE personalization run. Falls back to \"no sharing\" outside React\n// Server Components, where `cache` is unavailable.\nconst requestStore: () => Map<string, Promise<unknown>> =\n  typeof (React as { cache?: unknown }).cache === \"function\"\n    ? (React as unknown as { cache: <F extends () => unknown>(fn: F) => F }).cache(() => new Map())\n    : () => new Map();\n\n/**\n * Run `personalize` at most once per request for `key`, and share the promise. Lets a page shell\n * render immediately while each personalized section awaits the same run inside its own\n * `<Suspense>`, streaming in as soon as it's ready:\n *\n * ```tsx\n * const run = (ref) => personalizeOnce(`page:${ref}`, async () =>\n *   (await xeniaServerFromNext(config)).personalizePage(ref, { cms, timeoutMs: 800 }));\n *\n * export default async function Page({ params }) {\n *   const xenia = await xeniaServerFromNext(config);\n *   const base = await xenia.personalizePage(ref, { cms, maxRounds: 0 }); // CMS only, no Xenia call\n *   const pending = new Set(pendingTargets(base.content, cms));          // from the markers\n *   return base.content.fields.sections.map((s) =>\n *     pending.has(s.sys.id) ? (\n *       <Suspense key={s.sys.id} fallback={<SectionSkeleton />}>   // never base content that will change\n *         <PersonalizedSection id={s.sys.id} run={() => run(ref)} />\n *       </Suspense>\n *     ) : (\n *       <Section key={s.sys.id} entry={s} />\n *     ));\n * }\n * ```\n *\n * To finish deeper levels in the browser instead, pass `maxRounds: 1` here and hand the result's\n * `content` to `usePersonalizedContent` — already-decided entries are not asked about again.\n */\nexport function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T> {\n  const store = requestStore();\n  let run = store.get(key) as Promise<T> | undefined;\n  if (!run) {\n    run = personalize();\n    store.set(key, run);\n  }\n  return run;\n}\n"]}

package/dist/next/index.d.cts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { V as VisitorCookieOptions, d as ConsentState, t as XeniaConfig } from '../api-URhxxi4x.cjs';
-import { X as XeniaServer } from '../xenia-server-Cti94W49.cjs';
+import { V as VisitorCookieOptions, f as ConsentState, L as XeniaConfig } from '../personalize-content-Clc1oMYY.cjs';
+import { X as XeniaServer } from '../xenia-server-o_wDOcei.cjs';
+import '../api-BEPW0Uan.cjs';
 
 /**
  * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.
@@ -41,5 +42,33 @@ declare function xeniaProxy(request: NextRequest, opts?: XeniaProxyOptions): Nex
 declare function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer>;
 /** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */
 declare function consentFromNext(prefix?: string): Promise<ConsentState>;
+/**
+ * Run `personalize` at most once per request for `key`, and share the promise. Lets a page shell
+ * render immediately while each personalized section awaits the same run inside its own
+ * `<Suspense>`, streaming in as soon as it's ready:
+ *
+ * ```tsx
+ * const run = (ref) => personalizeOnce(`page:${ref}`, async () =>
+ *   (await xeniaServerFromNext(config)).personalizePage(ref, { cms, timeoutMs: 800 }));
+ *
+ * export default async function Page({ params }) {
+ *   const xenia = await xeniaServerFromNext(config);
+ *   const base = await xenia.personalizePage(ref, { cms, maxRounds: 0 }); // CMS only, no Xenia call
+ *   const pending = new Set(pendingTargets(base.content, cms));          // from the markers
+ *   return base.content.fields.sections.map((s) =>
+ *     pending.has(s.sys.id) ? (
+ *       <Suspense key={s.sys.id} fallback={<SectionSkeleton />}>   // never base content that will change
+ *         <PersonalizedSection id={s.sys.id} run={() => run(ref)} />
+ *       </Suspense>
+ *     ) : (
+ *       <Section key={s.sys.id} entry={s} />
+ *     ));
+ * }
+ * ```
+ *
+ * To finish deeper levels in the browser instead, pass `maxRounds: 1` here and hand the result's
+ * `content` to `usePersonalizedContent` — already-decided entries are not asked about again.
+ */
+declare function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T>;
 
-export { URL_HEADER, type XeniaProxyOptions, consentFromNext, xeniaProxy, xeniaServerFromNext };
+export { URL_HEADER, type XeniaProxyOptions, consentFromNext, personalizeOnce, xeniaProxy, xeniaServerFromNext };

package/dist/next/index.d.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { V as VisitorCookieOptions, d as ConsentState, t as XeniaConfig } from '../api-URhxxi4x.js';
-import { X as XeniaServer } from '../xenia-server-DDtQp6Wi.js';
+import { V as VisitorCookieOptions, f as ConsentState, L as XeniaConfig } from '../personalize-content-Clc1oMYY.js';
+import { X as XeniaServer } from '../xenia-server-BWhWD0La.js';
+import '../api-CktVQ6Gl.js';
 
 /**
  * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.
@@ -41,5 +42,33 @@ declare function xeniaProxy(request: NextRequest, opts?: XeniaProxyOptions): Nex
 declare function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer>;
 /** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */
 declare function consentFromNext(prefix?: string): Promise<ConsentState>;
+/**
+ * Run `personalize` at most once per request for `key`, and share the promise. Lets a page shell
+ * render immediately while each personalized section awaits the same run inside its own
+ * `<Suspense>`, streaming in as soon as it's ready:
+ *
+ * ```tsx
+ * const run = (ref) => personalizeOnce(`page:${ref}`, async () =>
+ *   (await xeniaServerFromNext(config)).personalizePage(ref, { cms, timeoutMs: 800 }));
+ *
+ * export default async function Page({ params }) {
+ *   const xenia = await xeniaServerFromNext(config);
+ *   const base = await xenia.personalizePage(ref, { cms, maxRounds: 0 }); // CMS only, no Xenia call
+ *   const pending = new Set(pendingTargets(base.content, cms));          // from the markers
+ *   return base.content.fields.sections.map((s) =>
+ *     pending.has(s.sys.id) ? (
+ *       <Suspense key={s.sys.id} fallback={<SectionSkeleton />}>   // never base content that will change
+ *         <PersonalizedSection id={s.sys.id} run={() => run(ref)} />
+ *       </Suspense>
+ *     ) : (
+ *       <Section key={s.sys.id} entry={s} />
+ *     ));
+ * }
+ * ```
+ *
+ * To finish deeper levels in the browser instead, pass `maxRounds: 1` here and hand the result's
+ * `content` to `usePersonalizedContent` — already-decided entries are not asked about again.
+ */
+declare function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T>;
 
-export { URL_HEADER, type XeniaProxyOptions, consentFromNext, xeniaProxy, xeniaServerFromNext };
+export { URL_HEADER, type XeniaProxyOptions, consentFromNext, personalizeOnce, xeniaProxy, xeniaServerFromNext };

package/dist/next/index.js

@@ -1,5 +1,6 @@
-import { createXeniaServer, getConsent } from '../chunk-WYAMPEVV.js';
-import { visitorCookieName, generateUlid, contextFromUrl } from '../chunk-FYSEKFIY.js';
+import { createXeniaServer, getConsent } from '../chunk-DWFVDNU5.js';
+import { visitorCookieName, generateUlid, contextFromUrl } from '../chunk-7NGJC7CF.js';
+import * as React from 'react';
 import { cookies, headers } from 'next/headers';
 import { NextResponse } from 'next/server';
 
@@ -48,7 +49,17 @@ async function xeniaServerFromNext(config) {
 async function consentFromNext(prefix) {
   return getConsent((await headers()).get("cookie"), prefix);
 }
+var requestStore = typeof React.cache === "function" ? React.cache(() => /* @__PURE__ */ new Map()) : () => /* @__PURE__ */ new Map();
+function personalizeOnce(key, personalize) {
+  const store = requestStore();
+  let run = store.get(key);
+  if (!run) {
+    run = personalize();
+    store.set(key, run);
+  }
+  return run;
+}
 
-export { URL_HEADER, consentFromNext, xeniaProxy, xeniaServerFromNext };
+export { URL_HEADER, consentFromNext, personalizeOnce, xeniaProxy, xeniaServerFromNext };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/next/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/next/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.\n *\n * A Server Component can't see its own URL or set cookies during render, so the two halves split\n * the work: `xeniaProxy()` runs in `proxy.ts`/`middleware.ts` (mints the visitor cookie, stamps the\n * URL onto a request header), and `xeniaServerFromNext()` reads both back to bind a per-request\n * `XeniaServer`. Use them together; each alone degrades gracefully (no URL context / a throwaway\n * visitor id).\n */\n\nimport { cookies, headers } from \"next/headers\";\nimport { NextResponse, type NextRequest } from \"next/server\";\nimport { visitorCookieName } from \"../core/cookie-names\";\nimport { generateUlid } from \"../core/id\";\nimport { contextFromUrl } from \"../core/request-context\";\nimport type { ConsentState, VisitorCookieOptions, XeniaConfig } from \"../core/types\";\nimport { getConsent } from \"../server/cookies\";\nimport { createXeniaServer, type XeniaServer } from \"../server/xenia-server\";\n\n/** Request header `xeniaProxy()` stamps with the URL being served. */\nexport const URL_HEADER = \"x-xenia-url\";\n\nexport interface XeniaProxyOptions {\n  /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */\n  headers?: Headers;\n  /** Must match the browser client's `config.prefix`, if you set one. */\n  prefix?: string;\n  /** Visitor cookie attributes. Default: `path=/`, `SameSite=Lax`, one year. */\n  cookie?: VisitorCookieOptions;\n}\n\nfunction cookieAttributes(c: VisitorCookieOptions = {}) {\n  const sameSite = c.sameSite ?? \"Lax\";\n  return {\n    path: \"/\",\n    maxAge: Math.floor((c.maxAgeDays ?? 365) * 86400),\n    sameSite: sameSite.toLowerCase() as \"lax\" | \"strict\" | \"none\",\n    secure: c.secure || sameSite === \"None\",\n    ...(c.domain && { domain: c.domain }),\n  };\n}\n\n/**\n * Next.js proxy/middleware step: ensure the visitor cookie exists and stamp the URL onto\n * {@link URL_HEADER}, then continue. A new visitor id is also put on the forwarded `Cookie` header,\n * so this very request's render already sees it.\n *\n * ```ts\n * // proxy.ts\n * export const proxy = (request: NextRequest) => xeniaProxy(request);\n * ```\n */\nexport function xeniaProxy(request: NextRequest, opts: XeniaProxyOptions = {}): NextResponse {\n  const name = visitorCookieName(opts.prefix);\n  const existing = request.cookies.get(name)?.value;\n  const visitorId = existing ?? generateUlid();\n\n  const forwarded = new Headers(opts.headers ?? request.headers);\n  forwarded.set(URL_HEADER, request.url);\n  if (!existing) {\n    // NextRequest.cookies.set doesn't rewrite the forwarded Cookie header, and cookies() reads that.\n    const header = forwarded.get(\"cookie\");\n    forwarded.set(\"cookie\", header ? `${header}; ${name}=${visitorId}` : `${name}=${visitorId}`);\n  }\n\n  const response = NextResponse.next({ request: { headers: forwarded } });\n  if (!existing) response.cookies.set(name, visitorId, cookieAttributes(opts.cookie));\n  return response;\n}\n\n/**\n * A `XeniaServer` bound to this request's visitor (the cookie `xeniaProxy()` set) and URL context\n * (path, query, UTMs, referrer). For Server Components, Server Actions and Route Handlers.\n * `config.visitorId`/`config.context` still win when passed.\n */\nexport async function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer> {\n  const [jar, h] = await Promise.all([cookies(), headers()]);\n  const name = visitorCookieName(config.prefix);\n  let visitorId = config.visitorId ?? jar.get(name)?.value;\n  if (!visitorId) {\n    visitorId = generateUlid();\n    try {\n      jar.set(name, visitorId, cookieAttributes());\n    } catch {\n      // Expected during a Server Component render; xeniaProxy() is the place that persists it.\n    }\n  }\n  return createXeniaServer({\n    ...config,\n    visitorId,\n    context: { ...contextFromUrl(h.get(URL_HEADER), h.get(\"referer\")), ...config.context },\n  });\n}\n\n/** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */\nexport async function consentFromNext(prefix?: string): Promise<ConsentState> {\n  return getConsent((await headers()).get(\"cookie\"), prefix);\n}\n"]}
+{"version":3,"sources":["../../src/next/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `@xenia-martech/sdk-js/next` — Next.js (App Router, 15+) glue for the server SDK.\n *\n * A Server Component can't see its own URL or set cookies during render, so the two halves split\n * the work: `xeniaProxy()` runs in `proxy.ts`/`middleware.ts` (mints the visitor cookie, stamps the\n * URL onto a request header), and `xeniaServerFromNext()` reads both back to bind a per-request\n * `XeniaServer`. Use them together; each alone degrades gracefully (no URL context / a throwaway\n * visitor id).\n */\n\nimport * as React from \"react\";\nimport { cookies, headers } from \"next/headers\";\nimport { NextResponse, type NextRequest } from \"next/server\";\nimport { visitorCookieName } from \"../core/cookie-names\";\nimport { generateUlid } from \"../core/id\";\nimport { contextFromUrl } from \"../core/request-context\";\nimport type { ConsentState, VisitorCookieOptions, XeniaConfig } from \"../core/types\";\nimport { getConsent } from \"../server/cookies\";\nimport { createXeniaServer, type XeniaServer } from \"../server/xenia-server\";\n\n/** Request header `xeniaProxy()` stamps with the URL being served. */\nexport const URL_HEADER = \"x-xenia-url\";\n\nexport interface XeniaProxyOptions {\n  /** Request headers to forward (e.g. your own additions); defaults to the incoming ones. */\n  headers?: Headers;\n  /** Must match the browser client's `config.prefix`, if you set one. */\n  prefix?: string;\n  /** Visitor cookie attributes. Default: `path=/`, `SameSite=Lax`, one year. */\n  cookie?: VisitorCookieOptions;\n}\n\nfunction cookieAttributes(c: VisitorCookieOptions = {}) {\n  const sameSite = c.sameSite ?? \"Lax\";\n  return {\n    path: \"/\",\n    maxAge: Math.floor((c.maxAgeDays ?? 365) * 86400),\n    sameSite: sameSite.toLowerCase() as \"lax\" | \"strict\" | \"none\",\n    secure: c.secure || sameSite === \"None\",\n    ...(c.domain && { domain: c.domain }),\n  };\n}\n\n/**\n * Next.js proxy/middleware step: ensure the visitor cookie exists and stamp the URL onto\n * {@link URL_HEADER}, then continue. A new visitor id is also put on the forwarded `Cookie` header,\n * so this very request's render already sees it.\n *\n * ```ts\n * // proxy.ts\n * export const proxy = (request: NextRequest) => xeniaProxy(request);\n * ```\n */\nexport function xeniaProxy(request: NextRequest, opts: XeniaProxyOptions = {}): NextResponse {\n  const name = visitorCookieName(opts.prefix);\n  const existing = request.cookies.get(name)?.value;\n  const visitorId = existing ?? generateUlid();\n\n  const forwarded = new Headers(opts.headers ?? request.headers);\n  forwarded.set(URL_HEADER, request.url);\n  if (!existing) {\n    // NextRequest.cookies.set doesn't rewrite the forwarded Cookie header, and cookies() reads that.\n    const header = forwarded.get(\"cookie\");\n    forwarded.set(\"cookie\", header ? `${header}; ${name}=${visitorId}` : `${name}=${visitorId}`);\n  }\n\n  const response = NextResponse.next({ request: { headers: forwarded } });\n  if (!existing) response.cookies.set(name, visitorId, cookieAttributes(opts.cookie));\n  return response;\n}\n\n/**\n * A `XeniaServer` bound to this request's visitor (the cookie `xeniaProxy()` set) and URL context\n * (path, query, UTMs, referrer). For Server Components, Server Actions and Route Handlers.\n * `config.visitorId`/`config.context` still win when passed.\n */\nexport async function xeniaServerFromNext(config: XeniaConfig): Promise<XeniaServer> {\n  const [jar, h] = await Promise.all([cookies(), headers()]);\n  const name = visitorCookieName(config.prefix);\n  let visitorId = config.visitorId ?? jar.get(name)?.value;\n  if (!visitorId) {\n    visitorId = generateUlid();\n    try {\n      jar.set(name, visitorId, cookieAttributes());\n    } catch {\n      // Expected during a Server Component render; xeniaProxy() is the place that persists it.\n    }\n  }\n  return createXeniaServer({\n    ...config,\n    visitorId,\n    context: { ...contextFromUrl(h.get(URL_HEADER), h.get(\"referer\")), ...config.context },\n  });\n}\n\n/** This request's consent, from the cookie the browser client's `consent()` (or `consentCookie()`) wrote. */\nexport async function consentFromNext(prefix?: string): Promise<ConsentState> {\n  return getConsent((await headers()).get(\"cookie\"), prefix);\n}\n\n// ── CMS page personalization ──────────────────────────────────────────────────\n\n// One store per server request (React.cache scopes it to the render), so every section that asks\n// for the same page shares ONE personalization run. Falls back to \"no sharing\" outside React\n// Server Components, where `cache` is unavailable.\nconst requestStore: () => Map<string, Promise<unknown>> =\n  typeof (React as { cache?: unknown }).cache === \"function\"\n    ? (React as unknown as { cache: <F extends () => unknown>(fn: F) => F }).cache(() => new Map())\n    : () => new Map();\n\n/**\n * Run `personalize` at most once per request for `key`, and share the promise. Lets a page shell\n * render immediately while each personalized section awaits the same run inside its own\n * `<Suspense>`, streaming in as soon as it's ready:\n *\n * ```tsx\n * const run = (ref) => personalizeOnce(`page:${ref}`, async () =>\n *   (await xeniaServerFromNext(config)).personalizePage(ref, { cms, timeoutMs: 800 }));\n *\n * export default async function Page({ params }) {\n *   const xenia = await xeniaServerFromNext(config);\n *   const base = await xenia.personalizePage(ref, { cms, maxRounds: 0 }); // CMS only, no Xenia call\n *   const pending = new Set(pendingTargets(base.content, cms));          // from the markers\n *   return base.content.fields.sections.map((s) =>\n *     pending.has(s.sys.id) ? (\n *       <Suspense key={s.sys.id} fallback={<SectionSkeleton />}>   // never base content that will change\n *         <PersonalizedSection id={s.sys.id} run={() => run(ref)} />\n *       </Suspense>\n *     ) : (\n *       <Section key={s.sys.id} entry={s} />\n *     ));\n * }\n * ```\n *\n * To finish deeper levels in the browser instead, pass `maxRounds: 1` here and hand the result's\n * `content` to `usePersonalizedContent` — already-decided entries are not asked about again.\n */\nexport function personalizeOnce<T>(key: string, personalize: () => Promise<T>): Promise<T> {\n  const store = requestStore();\n  let run = store.get(key) as Promise<T> | undefined;\n  if (!run) {\n    run = personalize();\n    store.set(key, run);\n  }\n  return run;\n}\n"]}

package/dist/{api-URhxxi4x.d.cts → personalize-content-Clc1oMYY.d.cts}

@@ -357,6 +357,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;
@@ -580,81 +615,129 @@ type XeniaAction = {
 };
 
 /**
- * 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.
+ * 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.
  */
-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>;
+
+/** 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;
     /**
-     * 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.
+     * 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.
      */
-    consent(xeniaVisitorId: string, consent: ConsentState): Promise<JsonValue>;
+    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[]>;
     /**
-     * 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.
+     * 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.
      */
-    resolve(contentKey: string, opts?: ResolveOptions): Promise<ResolveResult>;
+    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;
     /**
-     * Resolve several content keys in one round-trip (≤50) —
-     * `POST /api/personalization/resolve-batch?merge=<bool>`. Same auth/merge
-     * semantics as {@link resolve}.
+     * 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.
      */
-    resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
+    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>>;
 
-export { type AnalyticsContext as A, type CircuitBreakerConfig as C, type EventContext as E, type HttpMethod as H, type IdentifyRequest as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type VisitorCookieOptions as V, type WebhookResponse as W, type XeniaAction as X, type AnalyticsEventName as a, type AnalyticsIdentity as b, type AnalyticsIngestResponse as c, type ConsentState as d, type EventIdentity as e, type IdentifyResponse as f, type InteractionType as g, type JsonObject as h, type MessagePlacement as i, type ResolveBatchResult as j, type ResolveOptions as k, type ResolveResult as l, type RetryConfig as m, type WidgetFormSubmit as n, type WidgetPrize as o, type WidgetSegment as p, type WidgetSubmitResponse as q, type WidgetType as r, XeniaApi as s, type XeniaConfig as t, type XeniaEvent as u, type CallerIdentity as v };
+export { type AnalyticsContext as A, type WidgetPrize as B, type CmsAdapter as C, type WidgetSegment as D, type EventContext as E, type WidgetSubmitResponse as F, type WidgetType as G, type HttpMethod as H, type IdentifyRequest as I, type JsonValue as J, type XeniaAction as K, type XeniaConfig as L, type MessageCta as M, type XeniaEvent as N, pendingTargets as O, type PagePersonalizeOptions as P, personalizeContent as Q, type ResolveBatchItem as R, personalizePage as S, type TrackOptions as T, type CallerIdentity as U, type VisitorCookieOptions as V, type WebhookResponse as W, type XeniaMarker as X, type AnalyticsEventName as a, type AnalyticsIdentity as b, type AnalyticsIngestResponse as c, type AppliedSwap as d, type CircuitBreakerConfig as e, type ConsentState as f, type EntryDecision as g, type EntryFilter as h, type EntryQuery as i, type EntryResolver as j, type EntrySwapOp as k, type EventIdentity as l, type IdentifyResponse as m, type InteractionType as n, type JsonObject as o, type MessagePlacement as p, type PageRef as q, type PersonalizationSwap as r, type PersonalizeContentOptions as s, type PersonalizeContentResult as t, type ResolveBatchResult as u, type ResolveEntriesResult as v, type ResolveOptions as w, type ResolveResult as x, type RetryConfig as y, type WidgetFormSubmit as z };