@xenia-martech/sdk-js 1.0.0-dev.26 → 1.0.0-dev.28

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

@@ -86,6 +86,23 @@ interface XeniaConfig {
      *   cookie read via `getVisitorId()`.
      */
     visitorId?: string;
+    /**
+     * The ambient request context for a **server** client — the SDK-provided page/campaign fields
+     * (`path`, `query`, `url`, `referrer`, `utmSource`/`utmMedium`/`utmCampaign`/`utmContent`/`utmId`)
+     * that get attached to EVERY `resolve()`/`resolveBatch()`/`webhook()` made with this client, so
+     * journey rules can gate on `query.<name>` or `path` without any per-call wiring.
+     *
+     * The browser client needs nothing here — it reads these off `window.location` itself. A server
+     * runtime has no ambient request, so bind it once when constructing the per-request client:
+     *
+     * ```ts
+     * createXeniaServer({ …, context: contextFromUrl(currentUrl, referrer) })
+     * ```
+     *
+     * Lowest precedence: a per-call `context`/`identity` overrides it, and the SDK-owned `visitorId`
+     * still wins over everything.
+     */
+    context?: EventContext;
     /**
      * Persist the SDK visitor id to a first-party `xenia_vid` cookie so your
      * **same-origin** server can read it (`getVisitorId(cookieHeader)`) and bind
@@ -304,6 +321,23 @@ interface ResolveOptions {
     locale?: string;
     /** When true, ask the server to splice and return `content`. */
     merge?: boolean;
+    /**
+     * Caller-supplied identity fields (`deviceId`/`visitorId`/`customerId`/
+     * `email`), merged into `data` the same way `ServerWebhookOptions.identity`
+     * is merged for `webhook()`. Only relevant server-side — the browser client
+     * collects these ambiently instead and ignores this field. The SDK-owned
+     * `visitorId` (from `config.visitorId`) still wins over a value supplied
+     * here, same precedence as `webhook()`.
+     */
+    identity?: EventIdentity;
+    /**
+     * Caller-supplied page context (`path`/`query`/`url`/`referrer`/`utm*`),
+     * merged into `data` the same way `ServerWebhookOptions.context` is merged
+     * for `webhook()`. There's no ambient `window`/`document` server-side, so a
+     * server caller who wants these SDK-provided fields on a resolve() call
+     * must pass them explicitly (e.g. from the current request's headers).
+     */
+    context?: EventContext;
 }
 /** Body posted to `POST /api/events/v1/identify` — binds visitor to a known user. */
 interface IdentifyRequest {
@@ -347,6 +381,109 @@ interface MessageCta {
     /** Optional event fired when the CTA is clicked. */
     event?: string;
 }
+/**
+ * Widget-specific rendering/interaction behavior for a message-placement action —
+ * ORTHOGONAL to `type` (the existing `banner|popup|modal|inline` placement enum, which
+ * stays exactly as-is). `type` says WHERE it renders; `widgetType` says WHAT it is.
+ * Keeping these separate is what lets `core/actions.ts`'s `MESSAGE_TYPES` allowlist AND
+ * the PHP SDK's `XeniaActions::KNOWN_TYPES` allowlist (same value set) stay completely
+ * unchanged — the PHP SDK needs zero code changes for widget support.
+ *
+ * `"standard"` (or omitted) is a plain message/popup — the existing card path, unmodified.
+ * A future 3rd widget type is one new literal here + one new dispatch-table entry in
+ * `client/widgets/index.ts`, not a rewrite.
+ */
+type WidgetType = "standard" | "spin-wheel";
+/**
+ * A prize/outcome segment shown to the visitor for a spin-wheel widget — label/color ONLY.
+ * Real weight/prize-code are marketer-authored server-side config (`config.widgetSubmissions`)
+ * and never leave the backend; they never appear here.
+ */
+interface WidgetSegment {
+    id: string;
+    label: string;
+    colorHex?: string;
+    /** Marks this segment as a non-winning outcome (e.g. "Try Again") — drives which of the
+     *  win/loss reveal screens (see WidgetStyle) the widget shows once this segment resolves. */
+    isLoss?: boolean;
+}
+/**
+ * The SAFE runtime envelope describing how a widget's captured form submission is
+ * dispatched — never a credential, never a prize weight/code (see the cross-repo
+ * contract). The SDK does not branch on `mode`'s value itself; it only follows whichever
+ * ref field is present (`flowRef` vs `bindingRef`) to pick an endpoint — `mode`/`ref` are
+ * otherwise relayed to the backend verbatim, uninterpreted.
+ */
+interface WidgetFormSubmit {
+    /** `true` for spin-wheel (server must resolve an outcome before anything renders). */
+    requiresResolve: boolean;
+    /** `"journey"` or `"endpoint"` — informational only; the SDK never branches on this value. */
+    mode: "journey" | "endpoint" | (string & {});
+    /** Present only when `mode === "journey" && !requiresResolve` — the direct `/flow` fast path, no secret. */
+    flowRef?: string;
+    /** Present whenever `requiresResolve || mode === "endpoint"`. */
+    bindingRef?: string;
+    /**
+     * Minimum time (ms) to keep the success state visible after a submit resolves, before the
+     * card dismisses itself — configured marketer-side on the webhook-response node's
+     * Form-submission panel. The real dispatch typically responds in well under 100ms, which
+     * would otherwise make the card vanish before a visitor registers it succeeded at all.
+     * Defaults to 900 when absent (an older/unconfigured binding).
+     */
+    successDisplayMs?: number;
+}
+/**
+ * Per-action visual overrides for a widget's own window chrome (spin-wheel).
+ * Deliberately narrow — everything about the widget's actual CONTENT (spinner/win/loss screens)
+ * is full marketer/AI-authored HTML (`spinnerHtml`/`winHtml`/`lossHtml` on `XeniaAction`, same
+ * pattern as a popup's `body`), not a field here. This only covers the two things that live
+ * OUTSIDE that HTML, in the SDK's own generated chrome around it.
+ */
+interface WidgetStyle {
+    /**
+     * Hides the built-in close (×) button. No spin-wheel renderer draws one of its own anymore
+     * (see `spin-wheel.ts`'s `html()`) — every screen's own `spinnerHtml`/`winHtml`/`lossHtml`
+     * carries its own close affordance, matched by the same heuristic every custom-HTML surface
+     * honors (`wireCloseAffordances`). Currently vestigial: not exposed in Content Studio's AI
+     * schema, and not read by any widget renderer's `html()`.
+     */
+    hideCloseButton?: boolean;
+    /** Hides the dimmed backdrop behind the modal/popup/banner. Defaults to shown. */
+    hideOverlay?: boolean;
+}
+/**
+ * Server-resolved outcome for a spin-wheel submission
+ * (`XeniaClient.submitWidgetForm`'s response). Absent for a plain form submit.
+ * `segmentId` matches an `id` in the action's `segments` list. Never the whole prize
+ * config (weight/internal code) — only what the backend decides is safe to reveal.
+ */
+interface WidgetPrize {
+    segmentId?: string;
+    label?: string;
+    colorHex?: string;
+    [key: string]: JsonValue | undefined;
+}
+/**
+ * Response from a widget form submission (`XeniaClient.submitWidgetForm`) — whichever
+ * endpoint was actually hit (the `/flow` fast path or `/widget-submissions`), normalized
+ * to one shape. `actions` flows through the existing `parseActions()`/`ActionRenderer.apply()`
+ * pipeline unchanged; `prize` is read directly by the spin-wheel widget module to drive
+ * its reveal.
+ */
+interface WidgetSubmitResponse {
+    status: number;
+    body: JsonValue;
+    actions: XeniaAction[];
+    prize?: WidgetPrize;
+    /** True when this visitor already played and the stored result is being replayed, not re-rolled. */
+    alreadyPlayed?: boolean;
+    /** Whether the configured dispatch (journey invoke / outbound endpoint call) actually fired. */
+    dispatched?: boolean;
+    /** Present when `dispatched` is false and the server attempted but failed the configured dispatch. */
+    dispatchError?: string;
+    widgetType?: WidgetType;
+    receivedAt: number;
+}
 /**
  * A render directive the SDK executes in the browser. Marketers emit these in
  * a `webhook-response` node body under the `xeniaActions` key.
@@ -382,6 +519,43 @@ type XeniaAction = {
     /** Anchor within the placement (see {@link MessagePosition}). Defaults to the
      *  SDK's built-in default per type (popup: bottom-right; banner: bottom). */
     position?: MessagePosition;
+    /** Orthogonal widget-behavior driver — see {@link WidgetType}. Omitted/`"standard"` renders
+     *  exactly like today. */
+    widgetType?: WidgetType;
+    /** Label/color-only outcome segments for `spin-wheel` widgets. */
+    segments?: WidgetSegment[];
+    /** Safe form-submission envelope — see {@link WidgetFormSubmit}. Absent when the action has
+     *  no capturable outcome. */
+    formSubmit?: WidgetFormSubmit;
+    /** Per-action visual overrides for the widget's own window — see {@link WidgetStyle}. */
+    style?: WidgetStyle;
+    /**
+     * Full marketer/AI-authored HTML for `spin-wheel`'s pre-spin face (title/subtitle/spin
+     * button/background — the whole visual design) — independent of the generic `html` field
+     * above, which spin-wheel never reads. The primary, ordinary way this screen
+     * is authored (same role `body` plays for a popup) — there is no separate generated
+     * template to fall back to. To keep the wheel and spin button working, include an element
+     * carrying `data-xenia-wheel-slot` (the SDK mounts the generated SVG wheel + pointer
+     * there) and one carrying `data-xenia-spin` (the SDK wires the spin click there) —
+     * omitting either simply drops that capability, same as any other custom-HTML widget.
+     */
+    spinnerHtml?: string;
+    /**
+     * Full marketer/AI-authored HTML for the win-reveal screen (`spin-wheel`), shown once a
+     * spin resolves to a non-`isLoss` segment — the primary way this screen is authored,
+     * same role as {@link spinnerHtml}. Include `data-xenia-wheel-prize` on any element to
+     * receive the resolved prize label, and `data-xenia-wheel-cta` on a button to wire its
+     * click to dismiss (same close-affordance heuristics as any other custom-HTML widget also
+     * apply here — see `wireCloseAffordances`).
+     */
+    winHtml?: string;
+    /**
+     * Full marketer/AI-authored HTML for the loss/"try again" screen, shown once a
+     * spin resolves to a segment with {@link WidgetSegment.isLoss} set. Same hooks and
+     * same primary-authoring role as {@link winHtml} (a losing outcome still has a `label`,
+     * e.g. "Try Again", so `data-xenia-wheel-prize` is still honored here).
+     */
+    lossHtml?: string;
 } | {
     type: "redirect";
     url: string;
@@ -418,6 +592,18 @@ declare class XeniaApi {
      * 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
@@ -494,4 +680,4 @@ declare const VISITOR_COOKIE: string;
  */
 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, XeniaApi as n, type XeniaConfig as o, type XeniaEvent as p, consentCookieName as q, parseActions as r, type CallerIdentity as s, visitorCookieName as v };
+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 };

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

@@ -86,6 +86,23 @@ interface XeniaConfig {
      *   cookie read via `getVisitorId()`.
      */
     visitorId?: string;
+    /**
+     * The ambient request context for a **server** client — the SDK-provided page/campaign fields
+     * (`path`, `query`, `url`, `referrer`, `utmSource`/`utmMedium`/`utmCampaign`/`utmContent`/`utmId`)
+     * that get attached to EVERY `resolve()`/`resolveBatch()`/`webhook()` made with this client, so
+     * journey rules can gate on `query.<name>` or `path` without any per-call wiring.
+     *
+     * The browser client needs nothing here — it reads these off `window.location` itself. A server
+     * runtime has no ambient request, so bind it once when constructing the per-request client:
+     *
+     * ```ts
+     * createXeniaServer({ …, context: contextFromUrl(currentUrl, referrer) })
+     * ```
+     *
+     * Lowest precedence: a per-call `context`/`identity` overrides it, and the SDK-owned `visitorId`
+     * still wins over everything.
+     */
+    context?: EventContext;
     /**
      * Persist the SDK visitor id to a first-party `xenia_vid` cookie so your
      * **same-origin** server can read it (`getVisitorId(cookieHeader)`) and bind
@@ -304,6 +321,23 @@ interface ResolveOptions {
     locale?: string;
     /** When true, ask the server to splice and return `content`. */
     merge?: boolean;
+    /**
+     * Caller-supplied identity fields (`deviceId`/`visitorId`/`customerId`/
+     * `email`), merged into `data` the same way `ServerWebhookOptions.identity`
+     * is merged for `webhook()`. Only relevant server-side — the browser client
+     * collects these ambiently instead and ignores this field. The SDK-owned
+     * `visitorId` (from `config.visitorId`) still wins over a value supplied
+     * here, same precedence as `webhook()`.
+     */
+    identity?: EventIdentity;
+    /**
+     * Caller-supplied page context (`path`/`query`/`url`/`referrer`/`utm*`),
+     * merged into `data` the same way `ServerWebhookOptions.context` is merged
+     * for `webhook()`. There's no ambient `window`/`document` server-side, so a
+     * server caller who wants these SDK-provided fields on a resolve() call
+     * must pass them explicitly (e.g. from the current request's headers).
+     */
+    context?: EventContext;
 }
 /** Body posted to `POST /api/events/v1/identify` — binds visitor to a known user. */
 interface IdentifyRequest {
@@ -347,6 +381,109 @@ interface MessageCta {
     /** Optional event fired when the CTA is clicked. */
     event?: string;
 }
+/**
+ * Widget-specific rendering/interaction behavior for a message-placement action —
+ * ORTHOGONAL to `type` (the existing `banner|popup|modal|inline` placement enum, which
+ * stays exactly as-is). `type` says WHERE it renders; `widgetType` says WHAT it is.
+ * Keeping these separate is what lets `core/actions.ts`'s `MESSAGE_TYPES` allowlist AND
+ * the PHP SDK's `XeniaActions::KNOWN_TYPES` allowlist (same value set) stay completely
+ * unchanged — the PHP SDK needs zero code changes for widget support.
+ *
+ * `"standard"` (or omitted) is a plain message/popup — the existing card path, unmodified.
+ * A future 3rd widget type is one new literal here + one new dispatch-table entry in
+ * `client/widgets/index.ts`, not a rewrite.
+ */
+type WidgetType = "standard" | "spin-wheel";
+/**
+ * A prize/outcome segment shown to the visitor for a spin-wheel widget — label/color ONLY.
+ * Real weight/prize-code are marketer-authored server-side config (`config.widgetSubmissions`)
+ * and never leave the backend; they never appear here.
+ */
+interface WidgetSegment {
+    id: string;
+    label: string;
+    colorHex?: string;
+    /** Marks this segment as a non-winning outcome (e.g. "Try Again") — drives which of the
+     *  win/loss reveal screens (see WidgetStyle) the widget shows once this segment resolves. */
+    isLoss?: boolean;
+}
+/**
+ * The SAFE runtime envelope describing how a widget's captured form submission is
+ * dispatched — never a credential, never a prize weight/code (see the cross-repo
+ * contract). The SDK does not branch on `mode`'s value itself; it only follows whichever
+ * ref field is present (`flowRef` vs `bindingRef`) to pick an endpoint — `mode`/`ref` are
+ * otherwise relayed to the backend verbatim, uninterpreted.
+ */
+interface WidgetFormSubmit {
+    /** `true` for spin-wheel (server must resolve an outcome before anything renders). */
+    requiresResolve: boolean;
+    /** `"journey"` or `"endpoint"` — informational only; the SDK never branches on this value. */
+    mode: "journey" | "endpoint" | (string & {});
+    /** Present only when `mode === "journey" && !requiresResolve` — the direct `/flow` fast path, no secret. */
+    flowRef?: string;
+    /** Present whenever `requiresResolve || mode === "endpoint"`. */
+    bindingRef?: string;
+    /**
+     * Minimum time (ms) to keep the success state visible after a submit resolves, before the
+     * card dismisses itself — configured marketer-side on the webhook-response node's
+     * Form-submission panel. The real dispatch typically responds in well under 100ms, which
+     * would otherwise make the card vanish before a visitor registers it succeeded at all.
+     * Defaults to 900 when absent (an older/unconfigured binding).
+     */
+    successDisplayMs?: number;
+}
+/**
+ * Per-action visual overrides for a widget's own window chrome (spin-wheel).
+ * Deliberately narrow — everything about the widget's actual CONTENT (spinner/win/loss screens)
+ * is full marketer/AI-authored HTML (`spinnerHtml`/`winHtml`/`lossHtml` on `XeniaAction`, same
+ * pattern as a popup's `body`), not a field here. This only covers the two things that live
+ * OUTSIDE that HTML, in the SDK's own generated chrome around it.
+ */
+interface WidgetStyle {
+    /**
+     * Hides the built-in close (×) button. No spin-wheel renderer draws one of its own anymore
+     * (see `spin-wheel.ts`'s `html()`) — every screen's own `spinnerHtml`/`winHtml`/`lossHtml`
+     * carries its own close affordance, matched by the same heuristic every custom-HTML surface
+     * honors (`wireCloseAffordances`). Currently vestigial: not exposed in Content Studio's AI
+     * schema, and not read by any widget renderer's `html()`.
+     */
+    hideCloseButton?: boolean;
+    /** Hides the dimmed backdrop behind the modal/popup/banner. Defaults to shown. */
+    hideOverlay?: boolean;
+}
+/**
+ * Server-resolved outcome for a spin-wheel submission
+ * (`XeniaClient.submitWidgetForm`'s response). Absent for a plain form submit.
+ * `segmentId` matches an `id` in the action's `segments` list. Never the whole prize
+ * config (weight/internal code) — only what the backend decides is safe to reveal.
+ */
+interface WidgetPrize {
+    segmentId?: string;
+    label?: string;
+    colorHex?: string;
+    [key: string]: JsonValue | undefined;
+}
+/**
+ * Response from a widget form submission (`XeniaClient.submitWidgetForm`) — whichever
+ * endpoint was actually hit (the `/flow` fast path or `/widget-submissions`), normalized
+ * to one shape. `actions` flows through the existing `parseActions()`/`ActionRenderer.apply()`
+ * pipeline unchanged; `prize` is read directly by the spin-wheel widget module to drive
+ * its reveal.
+ */
+interface WidgetSubmitResponse {
+    status: number;
+    body: JsonValue;
+    actions: XeniaAction[];
+    prize?: WidgetPrize;
+    /** True when this visitor already played and the stored result is being replayed, not re-rolled. */
+    alreadyPlayed?: boolean;
+    /** Whether the configured dispatch (journey invoke / outbound endpoint call) actually fired. */
+    dispatched?: boolean;
+    /** Present when `dispatched` is false and the server attempted but failed the configured dispatch. */
+    dispatchError?: string;
+    widgetType?: WidgetType;
+    receivedAt: number;
+}
 /**
  * A render directive the SDK executes in the browser. Marketers emit these in
  * a `webhook-response` node body under the `xeniaActions` key.
@@ -382,6 +519,43 @@ type XeniaAction = {
     /** Anchor within the placement (see {@link MessagePosition}). Defaults to the
      *  SDK's built-in default per type (popup: bottom-right; banner: bottom). */
     position?: MessagePosition;
+    /** Orthogonal widget-behavior driver — see {@link WidgetType}. Omitted/`"standard"` renders
+     *  exactly like today. */
+    widgetType?: WidgetType;
+    /** Label/color-only outcome segments for `spin-wheel` widgets. */
+    segments?: WidgetSegment[];
+    /** Safe form-submission envelope — see {@link WidgetFormSubmit}. Absent when the action has
+     *  no capturable outcome. */
+    formSubmit?: WidgetFormSubmit;
+    /** Per-action visual overrides for the widget's own window — see {@link WidgetStyle}. */
+    style?: WidgetStyle;
+    /**
+     * Full marketer/AI-authored HTML for `spin-wheel`'s pre-spin face (title/subtitle/spin
+     * button/background — the whole visual design) — independent of the generic `html` field
+     * above, which spin-wheel never reads. The primary, ordinary way this screen
+     * is authored (same role `body` plays for a popup) — there is no separate generated
+     * template to fall back to. To keep the wheel and spin button working, include an element
+     * carrying `data-xenia-wheel-slot` (the SDK mounts the generated SVG wheel + pointer
+     * there) and one carrying `data-xenia-spin` (the SDK wires the spin click there) —
+     * omitting either simply drops that capability, same as any other custom-HTML widget.
+     */
+    spinnerHtml?: string;
+    /**
+     * Full marketer/AI-authored HTML for the win-reveal screen (`spin-wheel`), shown once a
+     * spin resolves to a non-`isLoss` segment — the primary way this screen is authored,
+     * same role as {@link spinnerHtml}. Include `data-xenia-wheel-prize` on any element to
+     * receive the resolved prize label, and `data-xenia-wheel-cta` on a button to wire its
+     * click to dismiss (same close-affordance heuristics as any other custom-HTML widget also
+     * apply here — see `wireCloseAffordances`).
+     */
+    winHtml?: string;
+    /**
+     * Full marketer/AI-authored HTML for the loss/"try again" screen, shown once a
+     * spin resolves to a segment with {@link WidgetSegment.isLoss} set. Same hooks and
+     * same primary-authoring role as {@link winHtml} (a losing outcome still has a `label`,
+     * e.g. "Try Again", so `data-xenia-wheel-prize` is still honored here).
+     */
+    lossHtml?: string;
 } | {
     type: "redirect";
     url: string;
@@ -418,6 +592,18 @@ declare class XeniaApi {
      * 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
@@ -494,4 +680,4 @@ declare const VISITOR_COOKIE: string;
  */
 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, XeniaApi as n, type XeniaConfig as o, type XeniaEvent as p, consentCookieName as q, parseActions as r, type CallerIdentity as s, visitorCookieName as v };
+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 };

package/dist/index.cjs

@@ -1,80 +1,84 @@
 'use strict';
 
-var chunk3KYKKIIG_cjs = require('./chunk-3KYKKIIG.cjs');
+var chunkWYM4CQVG_cjs = require('./chunk-WYM4CQVG.cjs');
 
 
 
 Object.defineProperty(exports, "CONSENT_COOKIE", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.CONSENT_COOKIE; }
+  get: function () { return chunkWYM4CQVG_cjs.CONSENT_COOKIE; }
 });
 Object.defineProperty(exports, "DEFAULT_PREFIX", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.DEFAULT_PREFIX; }
+  get: function () { return chunkWYM4CQVG_cjs.DEFAULT_PREFIX; }
 });
 Object.defineProperty(exports, "HttpClient", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.HttpClient; }
+  get: function () { return chunkWYM4CQVG_cjs.HttpClient; }
 });
 Object.defineProperty(exports, "HttpError", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.HttpError; }
+  get: function () { return chunkWYM4CQVG_cjs.HttpError; }
 });
 Object.defineProperty(exports, "LocalStorageResponseStore", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.LocalStorageResponseStore; }
+  get: function () { return chunkWYM4CQVG_cjs.LocalStorageResponseStore; }
 });
 Object.defineProperty(exports, "MAX_EVENT_ID_LENGTH", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.MAX_EVENT_ID_LENGTH; }
+  get: function () { return chunkWYM4CQVG_cjs.MAX_EVENT_ID_LENGTH; }
 });
 Object.defineProperty(exports, "MemoryResponseStore", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.MemoryResponseStore; }
+  get: function () { return chunkWYM4CQVG_cjs.MemoryResponseStore; }
 });
 Object.defineProperty(exports, "VISITOR_COOKIE", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.VISITOR_COOKIE; }
+  get: function () { return chunkWYM4CQVG_cjs.VISITOR_COOKIE; }
 });
 Object.defineProperty(exports, "XeniaApi", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.XeniaApi; }
+  get: function () { return chunkWYM4CQVG_cjs.XeniaApi; }
 });
 Object.defineProperty(exports, "buildUrl", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.buildUrl; }
+  get: function () { return chunkWYM4CQVG_cjs.buildUrl; }
 });
 Object.defineProperty(exports, "consentCookieName", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.consentCookieName; }
+  get: function () { return chunkWYM4CQVG_cjs.consentCookieName; }
+});
+Object.defineProperty(exports, "contextFromUrl", {
+  enumerable: true,
+  get: function () { return chunkWYM4CQVG_cjs.contextFromUrl; }
 });
 Object.defineProperty(exports, "extractContentSwaps", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.extractContentSwaps; }
+  get: function () { return chunkWYM4CQVG_cjs.extractContentSwaps; }
 });
 Object.defineProperty(exports, "generateUlid", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.generateUlid; }
+  get: function () { return chunkWYM4CQVG_cjs.generateUlid; }
 });
 Object.defineProperty(exports, "isBrowser", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.isBrowser; }
+  get: function () { return chunkWYM4CQVG_cjs.isBrowser; }
 });
 Object.defineProperty(exports, "parseActions", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.parseActions; }
+  get: function () { return chunkWYM4CQVG_cjs.parseActions; }
 });
 Object.defineProperty(exports, "spliceSlots", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.spliceSlots; }
+  get: function () { return chunkWYM4CQVG_cjs.spliceSlots; }
 });
 Object.defineProperty(exports, "toEventId", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.toEventId; }
+  get: function () { return chunkWYM4CQVG_cjs.toEventId; }
 });
 Object.defineProperty(exports, "visitorCookieName", {
   enumerable: true,
-  get: function () { return chunk3KYKKIIG_cjs.visitorCookieName; }
+  get: function () { return chunkWYM4CQVG_cjs.visitorCookieName; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RetryConfig, H as HttpMethod, J as JsonValue, W as WebhookResponse } from './cookie-names-LgNDAreS.cjs';
-export { A as AnalyticsContext, a as AnalyticsEventName, b as AnalyticsIdentity, c as AnalyticsIngestResponse, C as CONSENT_COOKIE, d as ConsentState, D as DEFAULT_PREFIX, E as EventContext, e as EventIdentity, I as IdentifyRequest, f as IdentifyResponse, g as InteractionType, h as JsonObject, M as MessageCta, i as MessagePlacement, P as PersonalizationSwap, j as ResolveBatchItem, k as ResolveBatchResult, l as ResolveOptions, m as ResolveResult, T as TrackOptions, V as VISITOR_COOKIE, X as XeniaAction, n as XeniaApi, o as XeniaConfig, p as XeniaEvent, q as consentCookieName, r as parseActions, v as visitorCookieName } from './cookie-names-LgNDAreS.cjs';
+import { R as RetryConfig, H as HttpMethod, J as JsonValue, E as EventContext, W as WebhookResponse } from './cookie-names-B3b0XNc2.cjs';
+export { A as AnalyticsContext, a as AnalyticsEventName, b as AnalyticsIdentity, c as AnalyticsIngestResponse, C as CONSENT_COOKIE, d as ConsentState, D as DEFAULT_PREFIX, e as EventIdentity, I as IdentifyRequest, f as IdentifyResponse, g as InteractionType, h as JsonObject, M as MessageCta, i as MessagePlacement, P as PersonalizationSwap, j as ResolveBatchItem, k as ResolveBatchResult, l as ResolveOptions, m as ResolveResult, T as TrackOptions, V as VISITOR_COOKIE, n as WidgetFormSubmit, o as WidgetPrize, p as WidgetSegment, q as WidgetSubmitResponse, r as WidgetType, X as XeniaAction, s as XeniaApi, t as XeniaConfig, u as XeniaEvent, v as consentCookieName, w as parseActions, x as visitorCookieName } from './cookie-names-B3b0XNc2.cjs';
 
 /** Returns true when running in a browser environment (SSR-safe). */
 declare function isBrowser(): boolean;
@@ -121,6 +121,26 @@ declare function spliceSlots(slots: Record<string, JsonValue>, swaps: ContentSwa
 /** Extract `xeniaContentSwaps` from a webhook-response body, if present and well-formed. */
 declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined;
 
+/**
+ * Derive the SDK-provided page/campaign fields from a URL — the server-side counterpart to the
+ * browser client's `Identity.collectContext()`, which reads the same fields off `window.location`.
+ *
+ * Exists because a server runtime has no ambient `window`: a Node client is constructed per request,
+ * so the one thing it needs handed over is the URL being served. Everything a journey rule can
+ * reference — `path`, `query.<name>`, `url`, `referrer`, `utmSource`/`utmMedium`/`utmCampaign`/
+ * `utmContent`/`utmId` — is derived here rather than by each app, so a server-rendered page gets the
+ * same field set a browser page does without hand-rolling UTM parsing at every call site.
+ *
+ * Field names and semantics deliberately mirror `collectContext()` exactly: `query` is the flattened
+ * search params, UTMs come from the standard `utm_*` params, and absent values are omitted rather
+ * than set to `""` (a blank string is a value a condition could accidentally match).
+ *
+ * @param url Absolute URL of the request being served (e.g. `https://shop.example/product/x?ref=a`).
+ *            A relative or unparseable value yields an empty context rather than throwing.
+ * @param referrer Optional referring URL, typically the request's `Referer` header.
+ */
+declare function contextFromUrl(url: string | null | undefined, referrer?: string | null): EventContext;
+
 /**
  * Persists webhook responses the SDK receives, keyed by an arbitrary string
  * (typically the eventId, triggerId, or journeyId). Lets the app read back the
@@ -155,4 +175,4 @@ declare class LocalStorageResponseStore implements ResponseStore {
     clear(): void;
 }
 
-export { type ContentSwap, HttpClient, type HttpClientOptions, HttpError, HttpMethod, type HttpResult, JsonValue, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, type RequestOptions, type ResponseStore, RetryConfig, WebhookResponse, buildUrl, extractContentSwaps, generateUlid, isBrowser, spliceSlots, toEventId };
+export { type ContentSwap, EventContext, HttpClient, type HttpClientOptions, HttpError, HttpMethod, type HttpResult, JsonValue, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, type RequestOptions, type ResponseStore, RetryConfig, WebhookResponse, buildUrl, contextFromUrl, extractContentSwaps, generateUlid, isBrowser, spliceSlots, toEventId };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RetryConfig, H as HttpMethod, J as JsonValue, W as WebhookResponse } from './cookie-names-LgNDAreS.js';
-export { A as AnalyticsContext, a as AnalyticsEventName, b as AnalyticsIdentity, c as AnalyticsIngestResponse, C as CONSENT_COOKIE, d as ConsentState, D as DEFAULT_PREFIX, E as EventContext, e as EventIdentity, I as IdentifyRequest, f as IdentifyResponse, g as InteractionType, h as JsonObject, M as MessageCta, i as MessagePlacement, P as PersonalizationSwap, j as ResolveBatchItem, k as ResolveBatchResult, l as ResolveOptions, m as ResolveResult, T as TrackOptions, V as VISITOR_COOKIE, X as XeniaAction, n as XeniaApi, o as XeniaConfig, p as XeniaEvent, q as consentCookieName, r as parseActions, v as visitorCookieName } from './cookie-names-LgNDAreS.js';
+import { R as RetryConfig, H as HttpMethod, J as JsonValue, E as EventContext, W as WebhookResponse } from './cookie-names-B3b0XNc2.js';
+export { A as AnalyticsContext, a as AnalyticsEventName, b as AnalyticsIdentity, c as AnalyticsIngestResponse, C as CONSENT_COOKIE, d as ConsentState, D as DEFAULT_PREFIX, e as EventIdentity, I as IdentifyRequest, f as IdentifyResponse, g as InteractionType, h as JsonObject, M as MessageCta, i as MessagePlacement, P as PersonalizationSwap, j as ResolveBatchItem, k as ResolveBatchResult, l as ResolveOptions, m as ResolveResult, T as TrackOptions, V as VISITOR_COOKIE, n as WidgetFormSubmit, o as WidgetPrize, p as WidgetSegment, q as WidgetSubmitResponse, r as WidgetType, X as XeniaAction, s as XeniaApi, t as XeniaConfig, u as XeniaEvent, v as consentCookieName, w as parseActions, x as visitorCookieName } from './cookie-names-B3b0XNc2.js';
 
 /** Returns true when running in a browser environment (SSR-safe). */
 declare function isBrowser(): boolean;
@@ -121,6 +121,26 @@ declare function spliceSlots(slots: Record<string, JsonValue>, swaps: ContentSwa
 /** Extract `xeniaContentSwaps` from a webhook-response body, if present and well-formed. */
 declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined;
 
+/**
+ * Derive the SDK-provided page/campaign fields from a URL — the server-side counterpart to the
+ * browser client's `Identity.collectContext()`, which reads the same fields off `window.location`.
+ *
+ * Exists because a server runtime has no ambient `window`: a Node client is constructed per request,
+ * so the one thing it needs handed over is the URL being served. Everything a journey rule can
+ * reference — `path`, `query.<name>`, `url`, `referrer`, `utmSource`/`utmMedium`/`utmCampaign`/
+ * `utmContent`/`utmId` — is derived here rather than by each app, so a server-rendered page gets the
+ * same field set a browser page does without hand-rolling UTM parsing at every call site.
+ *
+ * Field names and semantics deliberately mirror `collectContext()` exactly: `query` is the flattened
+ * search params, UTMs come from the standard `utm_*` params, and absent values are omitted rather
+ * than set to `""` (a blank string is a value a condition could accidentally match).
+ *
+ * @param url Absolute URL of the request being served (e.g. `https://shop.example/product/x?ref=a`).
+ *            A relative or unparseable value yields an empty context rather than throwing.
+ * @param referrer Optional referring URL, typically the request's `Referer` header.
+ */
+declare function contextFromUrl(url: string | null | undefined, referrer?: string | null): EventContext;
+
 /**
  * Persists webhook responses the SDK receives, keyed by an arbitrary string
  * (typically the eventId, triggerId, or journeyId). Lets the app read back the
@@ -155,4 +175,4 @@ declare class LocalStorageResponseStore implements ResponseStore {
     clear(): void;
 }
 
-export { type ContentSwap, HttpClient, type HttpClientOptions, HttpError, HttpMethod, type HttpResult, JsonValue, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, type RequestOptions, type ResponseStore, RetryConfig, WebhookResponse, buildUrl, extractContentSwaps, generateUlid, isBrowser, spliceSlots, toEventId };
+export { type ContentSwap, EventContext, HttpClient, type HttpClientOptions, HttpError, HttpMethod, type HttpResult, JsonValue, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, type RequestOptions, type ResponseStore, RetryConfig, WebhookResponse, buildUrl, contextFromUrl, extractContentSwaps, generateUlid, isBrowser, spliceSlots, toEventId };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { CONSENT_COOKIE, DEFAULT_PREFIX, HttpClient, HttpError, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, VISITOR_COOKIE, XeniaApi, buildUrl, consentCookieName, extractContentSwaps, generateUlid, isBrowser, parseActions, spliceSlots, toEventId, visitorCookieName } from './chunk-D37RD3UC.js';
+export { CONSENT_COOKIE, DEFAULT_PREFIX, HttpClient, HttpError, LocalStorageResponseStore, MAX_EVENT_ID_LENGTH, MemoryResponseStore, VISITOR_COOKIE, XeniaApi, buildUrl, consentCookieName, contextFromUrl, extractContentSwaps, generateUlid, isBrowser, parseActions, spliceSlots, toEventId, visitorCookieName } from './chunk-XXNDHYAS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map