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

package/README.md

@@ -101,6 +101,7 @@ Building a plain HTML site (no npm, no bundler)? Skip the install and pull the p
 | `@xenia-martech/sdk-js/client` | browser, **framework-agnostic** | `createXeniaClient()` — identity, auto-tracking, action rendering. No React. Works from Vue, Angular, Svelte, or plain JS. |
 | `@xenia-martech/sdk-js/client/react` | browser + React | `<XeniaProvider>` + hooks (`useTrack`, `usePersonalization`, `useWebhook`, …), built on top of `/client`. |
 | `@xenia-martech/sdk-js/server` | Node / SSR / RSC | Server-side events, webhooks, personalization, and token minting. Stateless — identity passed explicitly. |
+| `@xenia-martech/sdk-js/next` | Next.js 15+ (App Router) | `xeniaProxy()` for `proxy.ts`/`middleware.ts` and `xeniaServerFromNext()` — the visitor cookie and URL context wired for you. Needs `next` (optional peer). |
 | `@xenia-martech/sdk-js/iife` | `<script>` tag | Prebuilt `window.Xenia` for sites without a bundler. |
 
 ---
@@ -343,6 +344,44 @@ await xenia.track("purchase", { identity: { email }, properties: { /* … */ } }
 
 See [Recipes](#recipes--end-to-end-patterns) below for the full pattern in an RSC app that has no browser SDK writing that cookie for you.
 
+### Next.js: two calls instead of the wiring
+
+`@xenia-martech/sdk-js/next` does the cookie and URL plumbing above for the App Router:
+
+```ts
+// proxy.ts (middleware.ts before Next 16)
+import type { NextRequest } from "next/server";
+import { xeniaProxy } from "@xenia-martech/sdk-js/next";
+
+// Mints the xenia_vid cookie for new visitors and stamps the URL onto the request.
+// Pass { headers } to forward headers of your own as well.
+export const proxy = (request: NextRequest) => xeniaProxy(request);
+```
+
+```ts
+// Any Server Component, Server Action or Route Handler
+import { consentFromNext, xeniaServerFromNext } from "@xenia-martech/sdk-js/next";
+
+const xenia = await xeniaServerFromNext(cfg); // bound to this visitor + path/query/UTMs/referrer
+const res = await xenia.webhook("cog_prod_…");
+
+// In a Server Action, after a form submit:
+const consent = await consentFromNext();
+if (consent.analytics) {
+  await xenia.identify({ email });                       // visitor id defaults to the bound one
+  await xenia.track("formSubmitted", { eventId: `contact-${ref}`, consent });
+}
+```
+
+Your own consent banner (no browser SDK)? Write the cookie the server reads with `consentCookie()`:
+
+```ts
+import { consentCookie } from "@xenia-martech/sdk-js";
+document.cookie = consentCookie({ analytics: true, consentSource: "banner" });
+```
+
+The browser client's `consent()` writes the same cookie for you.
+
 ---
 
 ## Configuration
@@ -361,6 +400,7 @@ Passed to `XeniaProvider`, `createXeniaClient`, `createXeniaServer`, or `Xenia.i
 | `prefix` | `string` | `"xenia"` | Storage keys, the `data-<prefix>` attribute name, **and the visitor/consent cookie names** (`<prefix>_vid`, `<prefix>_consent`). If you change it, pass the same prefix to the server helpers — `getVisitorId(header, prefix)` — or the server looks for a cookie the browser never wrote. |
 | `timeout` | `number` | `8000` | Per-request timeout (ms). |
 | `retry` | `{ attempts?, baseDelayMs? }` | `{2, 300}` | Retry policy; honors `Retry-After`. |
+| `circuitBreaker` | `boolean \| { failureThreshold?, cooldownMs? }` | off | After `failureThreshold` (3) consecutive failures on one URL, calls to it throw `CircuitOpenError` instantly for `cooldownMs` (30s), then one call probes. State is shared across clients, so it works with one server client per request. Each webhook trigger has its own circuit. |
 | `headers` | `Record<string,string>` | — | Extra headers on every request. |
 | `debug` | `boolean` | `false` | Verbose console diagnostics. |
 | `consent` | `ConsentState` | — | Initial consent flags. **Browser only** — the server client ignores this; pass `consent` per `track()` call instead. |
@@ -931,10 +971,19 @@ Never block the page on this — render `baseHero` immediately and swap in the p
 - `track()` → `AnalyticsIngestResponse` — single-call unified event (no batching queue); `opts.trigger`, `opts.eventId`, `opts.source` (origin tag, default `"xenia-server-sdk"`), `identity`/`context`/`properties`/**`consent`** (see [Analytics](#analytics--conversions) — **consent is per-call here**, `createXeniaServer({ consent })` is ignored).
 - `webhook()` — `opts.identity`/`opts.context` merge in the same reserved fields (`path`, `query`, `url`, `referrer`, UTM, `deviceId`, `visitorId`, etc.) the browser client auto-attaches; there's no ambient `window` on the server, so pass them explicitly.
 - `resolve(contentKey, opts?)` → `ResolveResult` · `resolveBatch(items, opts?)` → `ResolveBatchResult[]` — REST personalization (requires the SDK token).
-- `identify(body: IdentifyRequest)` → `IdentifyResponse` — bind a visitor to a known user.
+- `identify(body)` → `IdentifyResponse` — bind a visitor to a known user. `xeniaVisitorId` defaults to the bound `config.visitorId`.
 - `refreshSdkToken(opts)` → `{ token, expiresAt? }` — exchanges your long-lived SDK token for a short-lived one; call this directly if you're not on a framework with route handlers.
 - `createTokenRoute(config)` → `(request) => Promise<Response>` — a ready-made handler wrapping `refreshSdkToken`; mount at your token endpoint.
-- `parseCookies(header)`, `getVisitorId(header, prefix?)`, `getConsent(header, prefix?)`, `visitorCookieName(prefix?)`, `consentCookieName(prefix?)`. `VISITOR_COOKIE` (`"xenia_vid"`) / `CONSENT_COOKIE` (`"xenia_consent"`) are the DEFAULT-prefix names — with a custom `prefix`, use the functions and pass the same prefix the browser client uses.
+- `parseCookies(header)`, `getVisitorId(header, prefix?)`, `getConsent(header, prefix?)`, `consentCookie(state, prefix?)`, `visitorCookieName(prefix?)`, `consentCookieName(prefix?)`. `VISITOR_COOKIE` (`"xenia_vid"`) / `CONSENT_COOKIE` (`"xenia_consent"`) are the DEFAULT-prefix names — with a custom `prefix`, use the functions and pass the same prefix the browser client uses.
+
+</details>
+
+<details>
+<summary><strong>Next.js (<code>/next</code>)</strong> — App Router 15+</summary>
+
+- `xeniaProxy(request, { headers?, prefix?, cookie? })` → `NextResponse` — ensures the visitor cookie and sets the `x-xenia-url` request header (`URL_HEADER`).
+- `xeniaServerFromNext(config)` → `Promise<XeniaServer>` — reads the visitor cookie and URL header back; `config.visitorId`/`config.context` still win.
+- `consentFromNext(prefix?)` → `Promise<ConsentState>` — `getConsent()` on this request's cookies.
 
 </details>
 
@@ -944,7 +993,7 @@ Never block the page on this — render `baseHero` immediately and swap in the p
 
 - `XeniaApi` — low-level endpoint client (`sendEvents`, `webhook`, `resolve`, `resolveBatch`, `identify`, `consent`). App code normally goes through `/client` or `/server` instead.
 - `parseActions(body)`, `generateUlid()`, `toEventId(raw)`, `MAX_EVENT_ID_LENGTH`, `spliceSlots(slots, swaps)`, `extractContentSwaps(body)`, `VISITOR_COOKIE`, `CONSENT_COOKIE`.
-- `HttpClient`, `HttpError`, `buildUrl(base, path)`, `isBrowser()` — the underlying HTTP layer; `isBrowser()` is handy for guarding SSR-unsafe code in your own app.
+- `HttpClient`, `HttpError`, `CircuitOpenError`, `buildUrl(base, path)`, `isBrowser()` — the underlying HTTP layer; `isBrowser()` is handy for guarding SSR-unsafe code in your own app.
 - `MemoryResponseStore`, `LocalStorageResponseStore` (implementations of the `ResponseStore` interface).
 - All types (`XeniaConfig`, `VisitorCookieOptions`, `XeniaEvent`, `TrackOptions`, `WebhookResponse`, `XeniaAction`, `MessagePosition`, `AnalyticsEventName`, `AnalyticsIngestResponse`, `AnalyticsContext`, `ResolveResult`, `ResolveBatchResult`, `PersonalizationSwap`, `ContentSwap`, `WidgetType`, `WidgetSegment`, `WidgetFormSubmit`, `WidgetStyle`, `WidgetPrize`, `WidgetSubmitResponse`, …).
 
@@ -954,7 +1003,7 @@ Never block the page on this — render `baseHero` immediately and swap in the p
 
 ## Resilience
 
-Events, webhooks, and personalization **never block your render**. A `usePersonalization()` call that fails just surfaces via `error` and leaves `data` as `null`, same as a no-match — your own base/fallback content keeps rendering. Requests time out (default 8s) and retry transient failures with backoff, honoring `Retry-After`. Treat a slow or unreachable Xenia as "render the base and move on."
+Events, webhooks, and personalization **never block your render**. A `usePersonalization()` call that fails just surfaces via `error` and leaves `data` as `null`, same as a no-match — your own base/fallback content keeps rendering. Requests time out (default 8s) and retry transient failures with backoff, honoring `Retry-After`. Treat a slow or unreachable Xenia as "render the base and move on." During an outage, set `circuitBreaker` so calls fail instantly instead of each visitor waiting out the timeout.
 
 ---
 

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

@@ -37,6 +37,19 @@ interface RetryConfig {
     /** Base backoff in ms (exponential). Default 300. */
     baseDelayMs?: number;
 }
+/**
+ * Opt-in memory of "the backend is down" across requests (and across clients, so a server that
+ * builds one client per request still benefits). After `failureThreshold` consecutive failures on
+ * one URL (query included, so each webhook trigger has its own circuit), calls to it fail instantly
+ * with `CircuitOpenError` for `cooldownMs`; then one call probes recovery. Failures are network
+ * errors, timeouts, `429` and `5xx`, after retries; any other response means the backend is up.
+ */
+interface CircuitBreakerConfig {
+    /** Consecutive failures that open the circuit. Default 3. */
+    failureThreshold?: number;
+    /** How long an open circuit fails fast before the next probe, in ms. Default 30000. */
+    cooldownMs?: number;
+}
 /**
  * Root configuration shared by client and server runtimes.
  *
@@ -114,6 +127,11 @@ interface XeniaConfig {
     timeout?: number;
     /** Retry policy for transient failures. */
     retry?: RetryConfig;
+    /**
+     * Fail fast while an endpoint is down instead of waiting out the timeout on every call. `true` for
+     * the defaults, or tune it. Off by default. See {@link CircuitBreakerConfig}.
+     */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
     /** Emit verbose diagnostics to the console. Default false. */
     debug?: boolean;
     /** Extra headers merged onto every request. */
@@ -984,4 +1002,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, extractContentSwaps as B, type ClientEvent as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ConsentState as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };
+export { type AnalyticsContext as A, extractContentSwaps as B, type ConsentState as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ClientEvent as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };

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

@@ -37,6 +37,19 @@ interface RetryConfig {
     /** Base backoff in ms (exponential). Default 300. */
     baseDelayMs?: number;
 }
+/**
+ * Opt-in memory of "the backend is down" across requests (and across clients, so a server that
+ * builds one client per request still benefits). After `failureThreshold` consecutive failures on
+ * one URL (query included, so each webhook trigger has its own circuit), calls to it fail instantly
+ * with `CircuitOpenError` for `cooldownMs`; then one call probes recovery. Failures are network
+ * errors, timeouts, `429` and `5xx`, after retries; any other response means the backend is up.
+ */
+interface CircuitBreakerConfig {
+    /** Consecutive failures that open the circuit. Default 3. */
+    failureThreshold?: number;
+    /** How long an open circuit fails fast before the next probe, in ms. Default 30000. */
+    cooldownMs?: number;
+}
 /**
  * Root configuration shared by client and server runtimes.
  *
@@ -114,6 +127,11 @@ interface XeniaConfig {
     timeout?: number;
     /** Retry policy for transient failures. */
     retry?: RetryConfig;
+    /**
+     * Fail fast while an endpoint is down instead of waiting out the timeout on every call. `true` for
+     * the defaults, or tune it. Off by default. See {@link CircuitBreakerConfig}.
+     */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
     /** Emit verbose diagnostics to the console. Default false. */
     debug?: boolean;
     /** Extra headers merged onto every request. */
@@ -984,4 +1002,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, extractContentSwaps as B, type ClientEvent as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ConsentState as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };
+export { type AnalyticsContext as A, extractContentSwaps as B, type ConsentState as C, parseActions as D, spliceSlots as E, type InteractionType as I, type JsonValue as J, type MessageCta as M, type PersonalizationSwap as P, type ResolveBatchItem as R, type TrackOptions as T, type WidgetFormSubmit as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type WidgetSubmitResponse as d, type XeniaAction as e, type MessagePlacement as f, type AnalyticsEventName as g, type AnalyticsIdentity as h, type AnalyticsIngestResponse as i, type ClientEvent as j, type ContentSwap as k, type IdentifyRequest as l, type IdentifyResponse as m, Identity as n, type MessageMountContext as o, type MessageRenderContext as p, type ResolveBatchResult as q, type ResolveOptions as r, type ResolveResult as s, type WebhookResponse as t, type WidgetPrize as u, type WidgetSegment as v, type WidgetType as w, XeniaClient as x, type XeniaClientOptions as y, createXeniaClient as z };

package/dist/{cookie-names-B3b0XNc2.d.cts → api-URhxxi4x.d.cts}

@@ -43,6 +43,19 @@ interface RetryConfig {
     /** Base backoff in ms (exponential). Default 300. */
     baseDelayMs?: number;
 }
+/**
+ * Opt-in memory of "the backend is down" across requests (and across clients, so a server that
+ * builds one client per request still benefits). After `failureThreshold` consecutive failures on
+ * one URL (query included, so each webhook trigger has its own circuit), calls to it fail instantly
+ * with `CircuitOpenError` for `cooldownMs`; then one call probes recovery. Failures are network
+ * errors, timeouts, `429` and `5xx`, after retries; any other response means the backend is up.
+ */
+interface CircuitBreakerConfig {
+    /** Consecutive failures that open the circuit. Default 3. */
+    failureThreshold?: number;
+    /** How long an open circuit fails fast before the next probe, in ms. Default 30000. */
+    cooldownMs?: number;
+}
 /**
  * Root configuration shared by client and server runtimes.
  *
@@ -120,6 +133,11 @@ interface XeniaConfig {
     timeout?: number;
     /** Retry policy for transient failures. */
     retry?: RetryConfig;
+    /**
+     * Fail fast while an endpoint is down instead of waiting out the timeout on every call. `true` for
+     * the defaults, or tune it. Off by default. See {@link CircuitBreakerConfig}.
+     */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
     /** Emit verbose diagnostics to the console. Default false. */
     debug?: boolean;
     /** Extra headers merged onto every request. */
@@ -639,45 +657,4 @@ declare class XeniaApi {
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
 }
 
-/**
- * Parse render actions out of a webhook-response body.
- *
- * The convention: marketers return `{ "xeniaActions": [ ... ] }` (or a bare
- * array) from the `webhook-response` node. Any body without a recognizable
- * `xeniaActions` array yields an empty list — a safe no-op.
- */
-declare function parseActions(body: JsonValue): XeniaAction[];
-
-/**
- * Cookie names shared by the browser and server halves of the SDK.
- *
- * The visitor cookie is the one channel where two runtimes must agree on a literal string: the
- * browser writes it, a same-origin server reads it back, and that match is what lets a server-side
- * conversion attribute to a browser-entered journey. `config.prefix` namespaces it — so two Xenia
- * apps on one domain keep separate visitors — which means **both halves must derive the name the
- * same way**. Deriving it on one side and hardcoding it on the other silently breaks the link for
- * anyone using a custom prefix: the server just finds no cookie and falls back to no visitor.
- *
- * Always build the name with these helpers rather than interpolating it by hand.
- */
-/** Default storage/cookie prefix, matching `XeniaConfig.prefix`. */
-declare const DEFAULT_PREFIX = "xenia";
-/** Name of the first-party cookie carrying the SDK-owned visitor id, for a given prefix. */
-declare function visitorCookieName(prefix?: string): string;
-/** Name of the first-party cookie carrying consent scopes, for a given prefix. */
-declare function consentCookieName(prefix?: string): string;
-/**
- * The visitor cookie name for the DEFAULT prefix (`"xenia_vid"`).
- *
- * Correct for the common case, and kept so existing code (e.g. reading the cookie straight out of a
- * framework's cookie jar) keeps working. If you set `config.prefix`, use {@link visitorCookieName}
- * instead — this constant will not match what the browser wrote.
- */
-declare const VISITOR_COOKIE: string;
-/**
- * The consent cookie name for the DEFAULT prefix (`"xenia_consent"`). Same custom-prefix caveat as
- * {@link VISITOR_COOKIE}.
- */
-declare const CONSENT_COOKIE: string;
-
-export { type AnalyticsContext as A, CONSENT_COOKIE as C, DEFAULT_PREFIX as D, 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 RetryConfig as R, type TrackOptions as T, VISITOR_COOKIE 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 ResolveBatchItem as j, type ResolveBatchResult as k, type ResolveOptions as l, type ResolveResult 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, consentCookieName as v, parseActions as w, visitorCookieName as x, type CallerIdentity as y };
+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 };

package/dist/{cookie-names-B3b0XNc2.d.ts → api-URhxxi4x.d.ts}

@@ -43,6 +43,19 @@ interface RetryConfig {
     /** Base backoff in ms (exponential). Default 300. */
     baseDelayMs?: number;
 }
+/**
+ * Opt-in memory of "the backend is down" across requests (and across clients, so a server that
+ * builds one client per request still benefits). After `failureThreshold` consecutive failures on
+ * one URL (query included, so each webhook trigger has its own circuit), calls to it fail instantly
+ * with `CircuitOpenError` for `cooldownMs`; then one call probes recovery. Failures are network
+ * errors, timeouts, `429` and `5xx`, after retries; any other response means the backend is up.
+ */
+interface CircuitBreakerConfig {
+    /** Consecutive failures that open the circuit. Default 3. */
+    failureThreshold?: number;
+    /** How long an open circuit fails fast before the next probe, in ms. Default 30000. */
+    cooldownMs?: number;
+}
 /**
  * Root configuration shared by client and server runtimes.
  *
@@ -120,6 +133,11 @@ interface XeniaConfig {
     timeout?: number;
     /** Retry policy for transient failures. */
     retry?: RetryConfig;
+    /**
+     * Fail fast while an endpoint is down instead of waiting out the timeout on every call. `true` for
+     * the defaults, or tune it. Off by default. See {@link CircuitBreakerConfig}.
+     */
+    circuitBreaker?: boolean | CircuitBreakerConfig;
     /** Emit verbose diagnostics to the console. Default false. */
     debug?: boolean;
     /** Extra headers merged onto every request. */
@@ -639,45 +657,4 @@ declare class XeniaApi {
     resolveBatch(items: ResolveBatchItem[], opts?: ResolveOptions): Promise<ResolveBatchResult[]>;
 }
 
-/**
- * Parse render actions out of a webhook-response body.
- *
- * The convention: marketers return `{ "xeniaActions": [ ... ] }` (or a bare
- * array) from the `webhook-response` node. Any body without a recognizable
- * `xeniaActions` array yields an empty list — a safe no-op.
- */
-declare function parseActions(body: JsonValue): XeniaAction[];
-
-/**
- * Cookie names shared by the browser and server halves of the SDK.
- *
- * The visitor cookie is the one channel where two runtimes must agree on a literal string: the
- * browser writes it, a same-origin server reads it back, and that match is what lets a server-side
- * conversion attribute to a browser-entered journey. `config.prefix` namespaces it — so two Xenia
- * apps on one domain keep separate visitors — which means **both halves must derive the name the
- * same way**. Deriving it on one side and hardcoding it on the other silently breaks the link for
- * anyone using a custom prefix: the server just finds no cookie and falls back to no visitor.
- *
- * Always build the name with these helpers rather than interpolating it by hand.
- */
-/** Default storage/cookie prefix, matching `XeniaConfig.prefix`. */
-declare const DEFAULT_PREFIX = "xenia";
-/** Name of the first-party cookie carrying the SDK-owned visitor id, for a given prefix. */
-declare function visitorCookieName(prefix?: string): string;
-/** Name of the first-party cookie carrying consent scopes, for a given prefix. */
-declare function consentCookieName(prefix?: string): string;
-/**
- * The visitor cookie name for the DEFAULT prefix (`"xenia_vid"`).
- *
- * Correct for the common case, and kept so existing code (e.g. reading the cookie straight out of a
- * framework's cookie jar) keeps working. If you set `config.prefix`, use {@link visitorCookieName}
- * instead — this constant will not match what the browser wrote.
- */
-declare const VISITOR_COOKIE: string;
-/**
- * The consent cookie name for the DEFAULT prefix (`"xenia_consent"`). Same custom-prefix caveat as
- * {@link VISITOR_COOKIE}.
- */
-declare const CONSENT_COOKIE: string;
-
-export { type AnalyticsContext as A, CONSENT_COOKIE as C, DEFAULT_PREFIX as D, 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 RetryConfig as R, type TrackOptions as T, VISITOR_COOKIE 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 ResolveBatchItem as j, type ResolveBatchResult as k, type ResolveOptions as l, type ResolveResult 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, consentCookieName as v, parseActions as w, visitorCookieName as x, type CallerIdentity as y };
+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 };

package/dist/chunk-5D7SJIO4.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+// src/core/content-splice.ts
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function cloneJson(value) {
+  return value === null || typeof value !== "object" ? value : JSON.parse(JSON.stringify(value));
+}
+function setAtPath(node, path, value, mode) {
+  if (path.length === 0) {
+    if (mode === "merge" && isPlainObject(node) && isPlainObject(value)) {
+      return { ...node, ...value };
+    }
+    return value;
+  }
+  const [key, ...rest] = path;
+  if (Array.isArray(node)) {
+    const index = Number(key);
+    if (!Number.isInteger(index) || index < 0 || index >= node.length) return node;
+    const next = node.slice();
+    next[index] = setAtPath(next[index], rest, value, mode);
+    return next;
+  }
+  if (isPlainObject(node)) {
+    if (!(key in node)) return node;
+    return { ...node, [key]: setAtPath(node[key], rest, value, mode) };
+  }
+  return node;
+}
+function spliceSlots(slots, swaps) {
+  const result = {};
+  for (const [key, value] of Object.entries(slots)) {
+    result[key] = cloneJson(value);
+  }
+  if (!swaps) return result;
+  for (const swap of swaps) {
+    const [slotKey, ...pathParts] = swap.identifier.split(".");
+    if (!(slotKey in result)) continue;
+    result[slotKey] = setAtPath(result[slotKey], pathParts, swap.replacement, swap.mode ?? "replace");
+  }
+  return result;
+}
+function extractContentSwaps(body) {
+  if (!isPlainObject(body)) return void 0;
+  const swaps = body.xeniaContentSwaps;
+  return Array.isArray(swaps) ? swaps : void 0;
+}
+
+// src/core/response-store.ts
+var MemoryResponseStore = class {
+  map = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.map.set(key, value);
+  }
+  get(key) {
+    return this.map.get(key);
+  }
+  keys() {
+    return [...this.map.keys()];
+  }
+  clear() {
+    this.map.clear();
+  }
+};
+var LocalStorageResponseStore = class {
+  nsKey;
+  constructor(prefix = "xenia") {
+    this.nsKey = `${prefix}_responses`;
+  }
+  read() {
+    try {
+      const raw = localStorage.getItem(this.nsKey);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  }
+  write(data) {
+    try {
+      localStorage.setItem(this.nsKey, JSON.stringify(data));
+    } catch {
+    }
+  }
+  set(key, value) {
+    const data = this.read();
+    data[key] = value;
+    this.write(data);
+  }
+  get(key) {
+    return this.read()[key];
+  }
+  keys() {
+    return Object.keys(this.read());
+  }
+  clear() {
+    try {
+      localStorage.removeItem(this.nsKey);
+    } catch {
+    }
+  }
+};
+
+exports.LocalStorageResponseStore = LocalStorageResponseStore;
+exports.MemoryResponseStore = MemoryResponseStore;
+exports.extractContentSwaps = extractContentSwaps;
+exports.spliceSlots = spliceSlots;
+//# sourceMappingURL=chunk-5D7SJIO4.cjs.map
+//# sourceMappingURL=chunk-5D7SJIO4.cjs.map

package/dist/chunk-5D7SJIO4.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/content-splice.ts","../src/core/response-store.ts"],"names":[],"mappings":"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","file":"chunk-5D7SJIO4.cjs","sourcesContent":["import type { JsonValue } from \"./types\";\n\n/**\n * A single content swap, as emitted in a webhook-response body's\n * `xeniaContentSwaps` array (the multi-slot personalization analogue of\n * `xeniaActions`). `identifier` is `\"<slotKey>\"` (whole-slot replace) or\n * `\"<slotKey>.<dotted.path>\"` addressing a node inside that slot's JSON\n * (object keys or array indices).\n *\n * NOTE: this field name/shape is a proposed contract, not yet emitted by any\n * journey node — confirm with the Journey Orchestrator (FE/BE) team before\n * relying on it in production.\n */\nexport interface ContentSwap {\n  identifier: string;\n  replacement: JsonValue;\n  /** `\"replace\"` (default) swaps the whole matched node; `\"merge\"` shallow-merges when both sides are objects. */\n  mode?: \"replace\" | \"merge\";\n}\n\nfunction isPlainObject(v: JsonValue): v is { [key: string]: JsonValue } {\n  return v !== null && typeof v === \"object\" && !Array.isArray(v);\n}\n\nfunction cloneJson<T extends JsonValue>(value: T): T {\n  return value === null || typeof value !== \"object\" ? value : (JSON.parse(JSON.stringify(value)) as T);\n}\n\nfunction setAtPath(node: JsonValue, path: string[], value: JsonValue, mode: \"replace\" | \"merge\"): JsonValue {\n  if (path.length === 0) {\n    if (mode === \"merge\" && isPlainObject(node) && isPlainObject(value)) {\n      return { ...node, ...value };\n    }\n    return value;\n  }\n\n  const [key, ...rest] = path;\n  if (Array.isArray(node)) {\n    const index = Number(key);\n    if (!Number.isInteger(index) || index < 0 || index >= node.length) return node;\n    const next = node.slice();\n    next[index] = setAtPath(next[index], rest, value, mode);\n    return next;\n  }\n  if (isPlainObject(node)) {\n    if (!(key in node)) return node;\n    return { ...node, [key]: setAtPath(node[key], rest, value, mode) };\n  }\n  return node;\n}\n\n/**\n * Splice `swaps` into a base map of named content slots, recursively at any\n * nesting depth. Defensive by design (mirrors the PHP SDK's personalization\n * client): a swap whose `identifier` doesn't resolve to an existing slot/path\n * is silently ignored rather than thrown — this never fails, it degrades to\n * the base slot value. Slots are deep-cloned; inputs are never mutated.\n */\nexport function spliceSlots(\n  slots: Record<string, JsonValue>,\n  swaps: ContentSwap[] | undefined,\n): Record<string, JsonValue> {\n  const result: Record<string, JsonValue> = {};\n  for (const [key, value] of Object.entries(slots)) {\n    result[key] = cloneJson(value);\n  }\n  if (!swaps) return result;\n\n  for (const swap of swaps) {\n    const [slotKey, ...pathParts] = swap.identifier.split(\".\");\n    if (!(slotKey in result)) continue;\n    result[slotKey] = setAtPath(result[slotKey], pathParts, swap.replacement, swap.mode ?? \"replace\");\n  }\n  return result;\n}\n\n/** Extract `xeniaContentSwaps` from a webhook-response body, if present and well-formed. */\nexport function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined {\n  if (!isPlainObject(body)) return undefined;\n  const swaps = body.xeniaContentSwaps;\n  return Array.isArray(swaps) ? (swaps as unknown as ContentSwap[]) : undefined;\n}\n","import type { WebhookResponse } from \"./types\";\n\n/**\n * Persists webhook responses the SDK receives, keyed by an arbitrary string\n * (typically the eventId, triggerId, or journeyId). Lets the app read back the\n * last server response for a given interaction without re-firing it.\n */\nexport interface ResponseStore {\n  set(key: string, value: WebhookResponse): void;\n  get(key: string): WebhookResponse | undefined;\n  keys(): string[];\n  clear(): void;\n}\n\n/** In-memory store. Default; lost on reload. */\nexport class MemoryResponseStore implements ResponseStore {\n  private readonly map = new Map<string, WebhookResponse>();\n\n  set(key: string, value: WebhookResponse): void {\n    this.map.set(key, value);\n  }\n  get(key: string): WebhookResponse | undefined {\n    return this.map.get(key);\n  }\n  keys(): string[] {\n    return [...this.map.keys()];\n  }\n  clear(): void {\n    this.map.clear();\n  }\n}\n\n/**\n * localStorage-backed store — survives reloads. Falls back to memory semantics\n * (silent no-op reads/writes) when localStorage is unavailable or throws.\n */\nexport class LocalStorageResponseStore implements ResponseStore {\n  private readonly nsKey: string;\n\n  constructor(prefix = \"xenia\") {\n    this.nsKey = `${prefix}_responses`;\n  }\n\n  private read(): Record<string, WebhookResponse> {\n    try {\n      const raw = localStorage.getItem(this.nsKey);\n      return raw ? (JSON.parse(raw) as Record<string, WebhookResponse>) : {};\n    } catch {\n      return {};\n    }\n  }\n\n  private write(data: Record<string, WebhookResponse>): void {\n    try {\n      localStorage.setItem(this.nsKey, JSON.stringify(data));\n    } catch {\n      /* storage full / unavailable — ignore */\n    }\n  }\n\n  set(key: string, value: WebhookResponse): void {\n    const data = this.read();\n    data[key] = value;\n    this.write(data);\n  }\n  get(key: string): WebhookResponse | undefined {\n    return this.read()[key];\n  }\n  keys(): string[] {\n    return Object.keys(this.read());\n  }\n  clear(): void {\n    try {\n      localStorage.removeItem(this.nsKey);\n    } catch {\n      /* ignore */\n    }\n  }\n}\n"]}