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

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
@@ -535,7 +583,27 @@ Each entry in `swaps` is `{ identifier, replacementEntryId, mode }` — `identif
 
 **Auth:** resolve **requires** the SDK Bearer token — the *same* `token` / `getToken` config as events (there is no separate personalization token). Events *optionally* send it (public otherwise); resolve *requires* it (401 without). Set it server-side; a browser without a token can still `track()` publicly but cannot `resolve()`.
 
-**Visitor id is attached automatically.** The SDK-owned visitor id (see [Analytics](#analytics--conversions)) is injected into the resolve `data` as `_xenia_vid`, so the backend can bucket holdout experiments and record per-visitor exposure — you don't add it yourself, and it can't be overridden per call. The webhook path (`request()` / `usePersonalization()`) carries the same id on the `/flow` body. Browser: resolved from `identify()`/device id; server: from `config.visitorId` (bind the `xenia_vid` cookie per request).
+**SDK-provided fields are attached automatically.** Every `resolve()`/`resolveBatch()` call carries a fixed set of fields into `data` — `path`, `query`, `deviceId`, `visitorId`, `customerId`, `email`, `url`, `referrer`, `utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmId` — plus the reserved `_xenia_vid` key the backend reads for holdout/exposure bucketing. These are the same "SDK-provided fields" a Personalization Resolve journey trigger exposes natively to downstream nodes. None of them can be overridden per call — the SDK's own values always win, even if your `data` happens to use one of these names.
+
+- **Browser:** collected ambiently — page URL/path/query/referrer/UTMs come from `window`/`document`; `visitorId`/`deviceId` from `identify()`/the auto-resolved device id; `customerId`/`email` from `identify(visitorId, { customerId, email })`. Nothing to configure.
+- **Server:** there's no ambient `window`/`document`, so bind the request **once** when you construct the per-request client and every call carries the fields automatically — no per-call wiring:
+
+  ```ts
+  import { createXeniaServer } from "@xenia-martech/sdk-js/server";
+  import { contextFromUrl } from "@xenia-martech/sdk-js";
+
+  const xenia = createXeniaServer({
+    tenantId, environmentKey, token,
+    visitorId: getVisitorId(cookieHeader),          // the browser's xenia_vid cookie
+    context: contextFromUrl(currentUrl, referrer),  // path / query / url / referrer / utm*
+  });
+
+  await xenia.resolve("hero");                      // ← fields already attached
+  ```
+
+  `contextFromUrl(url, referrer?)` derives the same fields the browser reads off `window.location`, so a rule can gate on `query.<name>` or `path` on a server-rendered page. In a framework where the render context can't see its own URL (e.g. a Next.js RSC), stamp the URL onto the request in middleware and read it back from `headers()` — see the `nextjs` example.
+
+  `opts.context`/`opts.identity` remain available per call, as an override on top of the ambient context or for values known only at that call site (e.g. `identity: { customerId: "c1", email: "a@b.com" }`). `visitorId`/`_xenia_vid` still come from `config.visitorId` and win over a per-call `identity.visitorId`. A client with neither bound behaves exactly as before.
 
 ```tsx
 import { usePersonalizationResolve } from "@xenia-martech/sdk-js/client/react";
@@ -821,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"`
@@ -879,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-DFLoSXO_.d.cts → actions-CcBYV--3.d.cts}

@@ -80,6 +80,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
@@ -115,6 +132,13 @@ interface VisitorCookieOptions {
     /** Cookie lifetime in days. Default 365. */
     maxAgeDays?: number;
 }
+/** Well-known event fields understood by the backend event-trigger node. */
+interface EventIdentity {
+    deviceId?: string;
+    visitorId?: string;
+    customerId?: string;
+    email?: string;
+}
 /** UTM + page context captured automatically by the client. */
 interface EventContext {
     utmSource?: string;
@@ -291,6 +315,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 {
@@ -334,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.
@@ -369,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;
@@ -455,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
@@ -543,6 +736,10 @@ declare class Identity {
     /** Persist a visitor id so it rides on every future event. */
     identify(visitorId: string): void;
     getVisitorId(): string | null;
+    setCustomerId(customerId: string | null): void;
+    getCustomerId(): string | null;
+    setEmail(email: string | null): void;
+    getEmail(): string | null;
     /**
      * Resolve the current session id: reused while activity continues within
      * {@link SESSION_TIMEOUT_MS}, otherwise a new one is minted. Persisted in
@@ -628,8 +825,15 @@ declare class XeniaClient {
      * Persist a visitor id, attached to every subsequent event, and bind it to
      * a known user server-side (`POST /api/events/v1/identify`, fire-and-
      * forget — resolves to an `"identify"` client event carrying `personId`).
+     *
+     * `extra.customerId`/`extra.email`, when supplied, are also persisted
+     * ambiently (like the visitor id) so they ride on every later `resolve()`
+     * call automatically — part of the SDK-provided-fields parity list.
      */
-    identify(visitorId: string): void;
+    identify(visitorId: string, extra?: {
+        customerId?: string;
+        email?: string;
+    }): void;
     /** Override the customer-journey UUID (else derived from utm_id). */
     setJourneyId(id: string | null): void;
     /**
@@ -675,10 +879,18 @@ declare class XeniaClient {
     /** The SDK-owned visitor anchor: the `identify()`/`config.visitorId` id, else the device id. */
     private resolveVisitorId;
     /**
-     * Stamp the SDK-owned visitor id into the resolve `data` under the reserved
-     * `_xenia_vid` key so the backend can bucket holdout experiments and record
-     * exposure per visitor (it reads visitor identity from `data`). Set last so a
-     * caller can't override it; a no-op when no visitor id is resolvable yet.
+     * Stamp the full set of SDK-provided fields into the resolve `data` —
+     * `path`, `query`, `deviceId`, `visitorId`, `customerId`, `email`, `url`,
+     * `referrer`, and the five `utm*` fields — the same field-name/type parity
+     * the webhook trigger's "SDK-provided fields" already promises, now native
+     * (always attached, no marketer toggle) for the Personalization Resolve
+     * trigger too. Plus the reserved `_xenia_vid` key the backend reads for
+     * holdout/exposure bucketing. All of these are spread LAST (after the
+     * caller's own `data`) so none can be overridden per call — the same
+     * override-protection guarantee `_xenia_vid` alone used to have, now
+     * widened to the full set. A no-op (returns `opts` unchanged) when nothing
+     * is resolvable yet (e.g. called before `init()` on a fresh visit with no
+     * page context available).
      */
     private withVisitor;
     private dntBlocked;
@@ -694,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;
@@ -748,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 };