@xenia-martech/sdk-js 1.0.0-dev.27 → 1.0.0-dev.29

package/CSS_VARIABLES.md

@@ -105,6 +105,13 @@ declaring the variables on a narrower ancestor element instead of `:root`.
 | `--xenia-close-size` | `20px` | Close (`×`) glyph font size. |
 | `--xenia-close-color` | `#999` | Close (`×`) glyph color. |
 
+### Spin-wheel widget
+
+| Variable | Default | Affects |
+|---|---|---|
+| `--xenia-cta-bg` / `--xenia-cta-color` / `--xenia-cta-radius` / `--xenia-cta-padding` / `--xenia-cta-size` | see [Call-to-action button](#call-to-action-button) | The wheel's "Spin" button — shares the same variables as the generic CTA button, so both stay visually consistent by default. |
+| `--xenia-wheel-pointer-color` | `#111` | Color of the pointer triangle above the wheel and the center hub cap. |
+
 ## Notes
 
 - Variables only affect the SDK's **built-in** card markup. If you set `html` on an action, or

package/README.md

@@ -502,6 +502,54 @@ function OfferCard({ action, close, fireCta }: XeniaMessageComponentProps) {
 
 Your component owns 100% of the card's markup and styling (same as a per-action `html` override) — the SDK still owns placement, z-index, and (for `modal`) the backdrop, so `--xenia-z-index`/`--xenia-popup-offset`/`--xenia-modal-backdrop`/etc. from [Theming with CSS variables](#theming-with-css-variables) still apply; the card-specific variables (`--xenia-card-*`, `--xenia-title-*`, `--xenia-cta-*`, …) don't, since there's no built-in card element to style.
 
+### Interactive widgets (spin-wheel)
+
+An action can also carry `widgetType: "spin-wheel"` — a gamified outcome the server resolves (a discount code, a "try again"), rendered and submitted differently from a plain message action:
+
+```jsonc
+{
+  "type": "popup",
+  "widgetType": "spin-wheel",
+  "segments": [
+    { "id": "s1", "label": "10% off", "colorHex": "#7c3aed" },
+    { "id": "s2", "label": "Try again", "colorHex": "#2563eb", "isLoss": true }
+  ],
+  "formSubmit": { "requiresResolve": true, "mode": "journey", "bindingRef": "wsb_abc123" },
+  "spinnerHtml": "<div class=\"wheel-screen\">…</div>",
+  "winHtml": "<div class=\"win-screen\">…</div>",
+  "lossHtml": "<div class=\"loss-screen\">…</div>"
+}
+```
+
+`segments` is label/color/`isLoss` **only** — the real prize weighting and any prize code are marketer-configured server-side on the webhook-response node and never reach the browser. `formSubmit` is likewise entirely server-driven: `requiresResolve: true` means the widget must call the server and get back a resolved segment before showing any outcome — there is never a client-guessed or optimistic result.
+
+**Authoring the three screens.** `spinnerHtml`/`winHtml`/`lossHtml` are full marketer/AI-authored HTML, exactly like a popup's `html` override — there's no generated fallback design, so your markup **is** the widget. The SDK only needs a few `data-xenia-*` hooks inside it to wire behavior:
+
+| Attribute | Goes in | Effect |
+|---|---|---|
+| `data-xenia-wheel-slot` | `spinnerHtml` | Where the SDK mounts its generated SVG wheel + pointer. |
+| `data-xenia-spin` | `spinnerHtml` | Click starts the spin — calls `submitWidgetForm()`, waits for the server-resolved segment, then animates the wheel to land on it. |
+| `data-xenia-wheel-prize` | `winHtml` / `lossHtml` (either or both) | Filled with the resolved segment's `label` once known. A losing segment still has a label (e.g. "Try again"), so this works on the loss screen too. |
+| `data-xenia-wheel-cta` | `winHtml` / `lossHtml` | Click fires the action's `cta.event`/`cta.url` (same as a message action's CTA) before dismissing. |
+| `data-xenia-spin-again` | `winHtml` / `lossHtml` | Optional "try again" button — swaps back to `spinnerHtml` and re-arms the spin button. Hidden automatically once the server reports no plays remain (`alreadyPlayed`). This never grants another spin by itself — the server's own play-limit/win-lock decides what the next `data-xenia-spin` click actually resolves to. |
+| `data-xenia-close`, or any element whose class/id contains "close"/"backdrop" | any of the three | Dismisses the widget — the same close-affordance convention every custom-HTML surface in the SDK honors, so a design pasted from elsewhere (e.g. an inline `onclick`) still closes correctly. |
+| `data-xenia-field="<name>"` / `data-xenia-submit` | `spinnerHtml`, or any widget's markup | The shared field-capture convention (see below) — wrap real inputs in a `<form>` for free Enter-to-submit, or mark a plain click trigger with `data-xenia-submit`. |
+
+If a click on `data-xenia-spin`/`data-xenia-submit` fires before the widget has a configured `formSubmit` (the marketer hasn't wired the webhook-response node's Form-submission panel yet), the SDK shows an inert `data-xenia-error` message instead of silently doing nothing or reloading the page.
+
+**Replays.** A visitor who already played sees the same resolved outcome again rather than a fresh roll — `WidgetSubmitResponse.alreadyPlayed` is `true` in that case, and the wheel skips its spin animation and jumps straight to the reveal (there's nothing new to animate toward).
+
+**The shared field/submit/success convention** (`collectFields`/`wireFormSubmit`, also used by plain `standard` popups with a capturable form) applies inside widget HTML too:
+
+- Mark real inputs `data-xenia-field="<name>"`; the submit trigger is `data-xenia-submit` (a `<form>` wrapper is optional — the SDK intercepts its native `submit` either way).
+- The submit control grows a small built-in spinner while the request is in flight (no markup needed for this).
+- On success, if you authored a `<div data-xenia-success hidden>…</div>` block anywhere in the HTML, it's revealed in place of the form for at least `formSubmit.successDisplayMs` (default 900ms — long enough for a visitor to register it worked, since the real round-trip is often under 100ms) before the widget dismisses itself. No success block just means a plain wait-then-dismiss.
+- On error, the spinner clears, the control re-enables, and `data-xenia-error` shows a retry message.
+
+**Per-widget style overrides** — `style: { hideCloseButton?, hideOverlay? }` — control the SDK's own chrome around the widget (not authored content). `hideCloseButton` isn't currently exposed in Content Studio's AI schema or read by any renderer yet; `hideOverlay` suppresses the dimmed backdrop, default shown.
+
+See [Theming with CSS variables](#theming-with-css-variables) for the wheel's own variables (`--xenia-wheel-pointer-color`, plus the shared `--xenia-cta-*` set for the Spin button).
+
 ---
 
 ## Theming with CSS variables
@@ -841,6 +889,7 @@ Never block the page on this — render `baseHero` immediately and swap in the p
 - `resolve(contentKey, opts?: ResolveOptions)` → `ResolveResult` · `resolveBatch(items, opts?)` → `ResolveBatchResult[]` — REST personalization (requires the SDK token)
 - `identify(visitorId)` · `setJourneyId(id)` · `consent(state)`
 - `request(triggerId, data?, { apply?, method? })` → `WebhookResponse`
+- `submitWidgetForm(formSubmit, fields, opts?: { idempotencyKey?, apply? })` → `WidgetSubmitResponse` — submits a widget's captured fields (spin-wheel resolve, or a plain custom-widget form submit); see [Interactive widgets](#interactive-widgets-spin-wheel)
 - `getResponse(key)` → `WebhookResponse | undefined`
 - `swapContent(target, {html?|text?})` · `hideContent(target)` · `showContent(target)` · `applyActions(actions)`
 - `on(event, cb)` — `"event" | "response" | "actions" | "error" | "identify"`
@@ -899,7 +948,7 @@ Never block the page on this — render `baseHero` immediately and swap in the p
 - `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.
 - `MemoryResponseStore`, `LocalStorageResponseStore` (implementations of the `ResponseStore` interface).
-- All types (`XeniaConfig`, `VisitorCookieOptions`, `XeniaEvent`, `TrackOptions`, `WebhookResponse`, `XeniaAction`, `MessagePosition`, `AnalyticsEventName`, `AnalyticsIngestResponse`, `AnalyticsContext`, `ResolveResult`, `ResolveBatchResult`, `PersonalizationSwap`, `ContentSwap`, …).
+- All types (`XeniaConfig`, `VisitorCookieOptions`, `XeniaEvent`, `TrackOptions`, `WebhookResponse`, `XeniaAction`, `MessagePosition`, `AnalyticsEventName`, `AnalyticsIngestResponse`, `AnalyticsContext`, `ResolveResult`, `ResolveBatchResult`, `PersonalizationSwap`, `ContentSwap`, `WidgetType`, `WidgetSegment`, `WidgetFormSubmit`, `WidgetStyle`, `WidgetPrize`, `WidgetSubmitResponse`, …).
 
 </details>
 

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

@@ -375,6 +375,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.
@@ -410,6 +513,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;
@@ -496,6 +636,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
@@ -754,6 +906,30 @@ declare class XeniaClient {
     }): Promise<WebhookResponse>;
     /** Read the last saved webhook response for a key (triggerId/eventId). */
     getResponse(key: string): WebhookResponse | undefined;
+    /**
+     * Submit a widget's captured form values (standard/custom popup submit, or a spin-wheel/
+     * spin-wheel's resolve request) and apply any returned `xeniaActions`, exactly like
+     * {@link request}.
+     *
+     * **Endpoint selection is config-driven, not SDK-decided** (per the cross-repo contract): a
+     * `flowRef` (present only when `mode === "journey" && !requiresResolve` — the common
+     * plain-popup case) bypasses the resolve endpoint entirely and POSTs straight to the existing
+     * public `/flow` fast path; otherwise this POSTs to `/widget-submissions` via `bindingRef`. The
+     * SDK is agnostic to *why* — it just follows whichever ref field the backend populated.
+     *
+     * The full ambient-context parity list {@link request}/`withVisitor()` already build
+     * (visitorId, deviceId, url, referrer, path, query, `utm*`) rides on every call, plus `fields`
+     * and `submit.mode`/the resolved ref, relayed verbatim/uninterpreted — the SDK never branches
+     * on `mode`'s value itself, that's server-side.
+     *
+     * `opts.idempotencyKey` defaults to a freshly generated ULID; pass the SAME key back in on a
+     * retried submit of the same interaction so a network retry can't double-fire a journey or
+     * double-resolve a prize server-side.
+     */
+    submitWidgetForm(submit: WidgetFormSubmit, fields: Record<string, string>, opts?: {
+        idempotencyKey?: string;
+        apply?: boolean;
+    }): Promise<WidgetSubmitResponse>;
     swapContent(target: string, content: {
         html?: string;
         text?: string;
@@ -808,4 +984,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, type ClientEvent as C, 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 WebhookResponse as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type XeniaAction as d, type AnalyticsEventName as e, type AnalyticsIdentity as f, type AnalyticsIngestResponse as g, type ConsentState as h, type ContentSwap as i, type IdentifyRequest as j, type IdentifyResponse as k, Identity as l, type MessageMountContext as m, type MessagePlacement as n, type MessageRenderContext as o, type ResolveBatchResult as p, type ResolveOptions as q, type ResolveResult as r, XeniaClient as s, type XeniaClientOptions as t, createXeniaClient as u, extractContentSwaps as v, parseActions as w, spliceSlots as x };
+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 };

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

@@ -375,6 +375,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.
@@ -410,6 +513,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;
@@ -496,6 +636,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
@@ -754,6 +906,30 @@ declare class XeniaClient {
     }): Promise<WebhookResponse>;
     /** Read the last saved webhook response for a key (triggerId/eventId). */
     getResponse(key: string): WebhookResponse | undefined;
+    /**
+     * Submit a widget's captured form values (standard/custom popup submit, or a spin-wheel/
+     * spin-wheel's resolve request) and apply any returned `xeniaActions`, exactly like
+     * {@link request}.
+     *
+     * **Endpoint selection is config-driven, not SDK-decided** (per the cross-repo contract): a
+     * `flowRef` (present only when `mode === "journey" && !requiresResolve` — the common
+     * plain-popup case) bypasses the resolve endpoint entirely and POSTs straight to the existing
+     * public `/flow` fast path; otherwise this POSTs to `/widget-submissions` via `bindingRef`. The
+     * SDK is agnostic to *why* — it just follows whichever ref field the backend populated.
+     *
+     * The full ambient-context parity list {@link request}/`withVisitor()` already build
+     * (visitorId, deviceId, url, referrer, path, query, `utm*`) rides on every call, plus `fields`
+     * and `submit.mode`/the resolved ref, relayed verbatim/uninterpreted — the SDK never branches
+     * on `mode`'s value itself, that's server-side.
+     *
+     * `opts.idempotencyKey` defaults to a freshly generated ULID; pass the SAME key back in on a
+     * retried submit of the same interaction so a network retry can't double-fire a journey or
+     * double-resolve a prize server-side.
+     */
+    submitWidgetForm(submit: WidgetFormSubmit, fields: Record<string, string>, opts?: {
+        idempotencyKey?: string;
+        apply?: boolean;
+    }): Promise<WidgetSubmitResponse>;
     swapContent(target: string, content: {
         html?: string;
         text?: string;
@@ -808,4 +984,4 @@ declare function extractContentSwaps(body: JsonValue): ContentSwap[] | undefined
  */
 declare function parseActions(body: JsonValue): XeniaAction[];
 
-export { type AnalyticsContext as A, type ClientEvent as C, 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 WebhookResponse as W, type XeniaConfig as X, type XeniaEvent as a, type MessageTemplateFn as b, type MessageComponentRenderer as c, type XeniaAction as d, type AnalyticsEventName as e, type AnalyticsIdentity as f, type AnalyticsIngestResponse as g, type ConsentState as h, type ContentSwap as i, type IdentifyRequest as j, type IdentifyResponse as k, Identity as l, type MessageMountContext as m, type MessagePlacement as n, type MessageRenderContext as o, type ResolveBatchResult as p, type ResolveOptions as q, type ResolveResult as r, XeniaClient as s, type XeniaClientOptions as t, createXeniaClient as u, extractContentSwaps as v, parseActions as w, spliceSlots as x };
+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 };

package/dist/{chunk-UOW3GK4I.cjs → chunk-WYM4CQVG.cjs}

@@ -15,6 +15,7 @@ var MESSAGE_POSITIONS = /* @__PURE__ */ new Set([
   "top",
   "bottom"
 ]);
+var WIDGET_TYPES = /* @__PURE__ */ new Set(["standard", "spin-wheel"]);
 var ALL_TYPES = /* @__PURE__ */ new Set([
   "swap",
   "hide",
@@ -61,15 +62,67 @@ function toAction(raw) {
     message: asString(raw.message),
     imageUrl: asString(raw.imageUrl),
     html: asString(raw.html),
-    cta: cta && cta.label ? cta : void 0,
+    // A link-only CTA (empty label, e.g. a spin-wheel's data-xenia-wheel-cta —
+    // label is meaningless there, the winHtml/lossHtml design supplies its own button text)
+    // must still parse through — gating on `cta.label` alone silently dropped it.
+    cta: cta && (cta.label || cta.url) ? cta : void 0,
     dismissAfterMs: asNumber(raw.dismissAfterMs),
-    position: asMessagePosition(raw.position)
+    position: asMessagePosition(raw.position),
+    widgetType: asWidgetType(raw.widgetType),
+    segments: asSegments(raw.segments),
+    formSubmit: asFormSubmit(raw.formSubmit),
+    style: asWidgetStyle(raw.style),
+    spinnerHtml: asString(raw.spinnerHtml),
+    winHtml: asString(raw.winHtml),
+    lossHtml: asString(raw.lossHtml)
   };
 }
 function asMessagePosition(v) {
   const s = asString(v);
   return s && MESSAGE_POSITIONS.has(s) ? s : void 0;
 }
+function asWidgetType(v) {
+  const s = asString(v);
+  return s && WIDGET_TYPES.has(s) ? s : void 0;
+}
+function asSegments(v) {
+  if (!Array.isArray(v)) return void 0;
+  const segments = [];
+  for (const entry of v) {
+    if (!isObject(entry)) continue;
+    const id = asString(entry.id);
+    const label = asString(entry.label);
+    if (!id || !label) continue;
+    segments.push({
+      id,
+      label,
+      colorHex: asString(entry.colorHex),
+      isLoss: entry.isLoss === true
+    });
+  }
+  return segments.length ? segments : void 0;
+}
+function asFormSubmit(v) {
+  if (!isObject(v)) return void 0;
+  const mode = asString(v.mode);
+  if (!mode) return void 0;
+  return {
+    requiresResolve: v.requiresResolve === true,
+    mode,
+    flowRef: asString(v.flowRef),
+    bindingRef: asString(v.bindingRef),
+    successDisplayMs: asNumber(v.successDisplayMs)
+  };
+}
+function asWidgetStyle(v) {
+  if (!isObject(v)) return void 0;
+  const style = {
+    hideCloseButton: v.hideCloseButton === true,
+    hideOverlay: v.hideOverlay === true
+  };
+  const hasAny = style.hideCloseButton || style.hideOverlay;
+  return hasAny ? style : void 0;
+}
 function parseActions(body) {
   let list;
   if (Array.isArray(body)) {
@@ -252,6 +305,12 @@ var TokenProvider = class {
 };
 
 // src/core/api.ts
+function isJsonObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function asWidgetPrize(v) {
+  return v !== void 0 && isJsonObject(v) ? v : void 0;
+}
 function compact(obj) {
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
@@ -321,6 +380,39 @@ var XeniaApi = class {
       receivedAt: Date.now()
     };
   }
+  /**
+   * 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.
+   */
+  async submitWidget(ref, body) {
+    const { response, data: rawBody } = await this.http.request({
+      method: "POST",
+      path: "/widget-submissions",
+      query: { ref },
+      headers: await this.authHeaders(),
+      body: body ?? {},
+      noRetry: true
+    });
+    const obj = isJsonObject(rawBody) ? rawBody : {};
+    return {
+      status: response.status,
+      body: rawBody,
+      actions: parseActions(rawBody),
+      prize: asWidgetPrize(obj.prize),
+      alreadyPlayed: obj.alreadyPlayed === true,
+      dispatched: obj.dispatched === true,
+      dispatchError: typeof obj.dispatchError === "string" ? obj.dispatchError : void 0,
+      widgetType: typeof obj.widgetType === "string" ? obj.widgetType : void 0,
+      receivedAt: Date.now()
+    };
+  }
   /**
    * 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
@@ -620,5 +712,5 @@ exports.parseActions = parseActions;
 exports.spliceSlots = spliceSlots;
 exports.toEventId = toEventId;
 exports.visitorCookieName = visitorCookieName;
-//# sourceMappingURL=chunk-UOW3GK4I.cjs.map
-//# sourceMappingURL=chunk-UOW3GK4I.cjs.map
+//# sourceMappingURL=chunk-WYM4CQVG.cjs.map
+//# sourceMappingURL=chunk-WYM4CQVG.cjs.map