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

package/dist/client/index.d.cts

@@ -1,5 +1,5 @@
-import { I as InteractionType, X as XeniaConfig, a as XeniaEvent, M as MessageCta, b as MessageTemplateFn, c as MessageComponentRenderer, d as XeniaAction } from '../actions-CkiSdvSa.cjs';
-export { A as AnalyticsContext, e as AnalyticsEventName, f as AnalyticsIdentity, g as AnalyticsIngestResponse, C as ClientEvent, h as ConsentState, i as ContentSwap, j as IdentifyRequest, k as IdentifyResponse, l as Identity, J as JsonValue, m as MessageMountContext, n as MessagePlacement, o as MessageRenderContext, P as PersonalizationSwap, R as ResolveBatchItem, p as ResolveBatchResult, q as ResolveOptions, r as ResolveResult, T as TrackOptions, W as WebhookResponse, s as XeniaClient, t as XeniaClientOptions, u as createXeniaClient, v as extractContentSwaps, w as parseActions, x as spliceSlots } from '../actions-CkiSdvSa.cjs';
+import { I as InteractionType, X as XeniaConfig, a as XeniaEvent, M as MessageCta, b as MessageTemplateFn, c as MessageComponentRenderer, W as WidgetFormSubmit, d as WidgetSubmitResponse, e as XeniaAction, f as MessagePlacement } from '../actions-CcBYV--3.cjs';
+export { A as AnalyticsContext, g as AnalyticsEventName, h as AnalyticsIdentity, i as AnalyticsIngestResponse, C as ClientEvent, j as ConsentState, k as ContentSwap, l as IdentifyRequest, m as IdentifyResponse, n as Identity, J as JsonValue, o as MessageMountContext, p as MessageRenderContext, P as PersonalizationSwap, R as ResolveBatchItem, q as ResolveBatchResult, r as ResolveOptions, s as ResolveResult, T as TrackOptions, t as WebhookResponse, u as WidgetPrize, v as WidgetSegment, w as WidgetType, x as XeniaClient, y as XeniaClientOptions, z as createXeniaClient, B as extractContentSwaps, D as parseActions, E as spliceSlots } from '../actions-CcBYV--3.cjs';
 
 interface Parsed {
     eventId: string;
@@ -156,6 +156,10 @@ declare class AnalyticsQueue {
 
 /** Callback invoked when a rendered CTA fires an event. */
 type CtaHandler = (event: string, cta: MessageCta) => void;
+/** Submits a widget's captured form values — injected from `XeniaClient.submitWidgetForm`. */
+type SubmitWidgetFormHandler = (submit: WidgetFormSubmit, fields: Record<string, string>, opts?: {
+    idempotencyKey?: string;
+}) => Promise<WidgetSubmitResponse>;
 /**
  * Resolve a target string to an element. Supports plain CSS selectors and the
  * `data-xenia-slot="<id>"` convention (a bare id with no CSS metacharacters is
@@ -183,12 +187,15 @@ declare class ActionRenderer {
     private readonly messageTemplate?;
     private readonly messageStyles?;
     private readonly messageComponent?;
+    private readonly submitWidgetFormFn?;
     /** Unmount callbacks for currently-mounted framework components, keyed by their container. */
     private readonly mounted;
     constructor(onCta?: CtaHandler, opts?: {
         messageTemplate?: MessageTemplateFn;
         messageStyles?: string;
         messageComponent?: MessageComponentRenderer;
+        /** Wired from `XeniaClient.submitWidgetForm` — powers every widget's form submission. */
+        submitWidgetForm?: SubmitWidgetFormHandler;
     });
     /** Apply a list of actions. Returns the count successfully applied. */
     apply(actions: XeniaAction[]): number;
@@ -211,6 +218,108 @@ declare class ActionRenderer {
     private positionClass;
     private cardHtml;
     private wireCard;
+    /** Build the imperative hooks (`dismiss`/`fireCta`/`submitWidgetForm`) handed to a widget's `wire()`. */
+    private buildWidgetCtx;
 }
 
-export { ActionRenderer, AnalyticsQueue, type AnalyticsQueueOptions, type AutoTrackOptions, AutoTracker, type CtaHandler, InteractionType, MessageComponentRenderer, MessageCta, MessageTemplateFn, type SlotMeta, TokenProvider, XeniaAction, XeniaConfig, XeniaEvent, hideContent, parseDataAttribute, readSlotMeta, resolveTarget, showContent, swapContent };
+/** A message-placement action (banner/popup/modal/inline) — the shape every widget renders. */
+type MessageAction = Extract<XeniaAction, {
+    type: MessagePlacement;
+}>;
+/**
+ * Imperative hooks a widget's `wire()` can call back into, injected by `ActionRenderer` —
+ * the widget module itself never touches `XeniaClient`/`XeniaApi` directly.
+ */
+interface WidgetWireContext {
+    /**
+     * Dismiss this message — unmounts/removes it, same as the built-in card's close button.
+     * Absent for placements with no dismiss affordance in this render (e.g. an `inline` action
+     * rendered without a wrapping overlay). Widgets should guard with `ctx.dismiss?.()`.
+     */
+    dismiss?: () => void;
+    /** Fire the action's `cta` (event + url), then {@link dismiss}. A no-op beyond dismiss when the action has no `cta`. */
+    fireCta: () => void;
+    /**
+     * Submit captured field values for this widget's `formSubmit` config. Routes to the `/flow`
+     * fast path or `/widget-submissions`, per the cross-repo contract's endpoint-selection rule —
+     * the widget module never branches on `mode`/inspects the ref fields itself, it just calls this.
+     *
+     * Rejects if the action has no `formSubmit` config or no submission handler is wired (e.g. a
+     * bare `ActionRenderer` constructed without `XeniaClient`). A per-widget-instance
+     * `idempotencyKey` is applied automatically and reused across every call from the SAME
+     * `wire()` invocation (i.e. a retried submit of the same interaction never mints a new one).
+     */
+    submitWidgetForm: (fields: Record<string, string>) => Promise<WidgetSubmitResponse>;
+}
+/**
+ * Renders and wires a `widgetType`'s UI. One implementation per dispatchable widget type,
+ * collected into `WIDGET_RENDERERS` (`client/widgets/index.ts`). `standard`/`custom`/undefined
+ * are NOT dispatched through this interface — they use `ActionRenderer`'s existing built-in card
+ * path unmodified (plus the shared `wireFormSubmit()` addition), per the cross-repo contract.
+ */
+interface WidgetRenderer {
+    /** Build the card markup injected into the shadow overlay or host-page slot. */
+    html(action: MessageAction, variant: MessagePlacement): string;
+    /** Wire interactivity after `html()`'s markup is already in the DOM under `root`. */
+    wire(root: Element | ShadowRoot, action: MessageAction, ctx: WidgetWireContext): void;
+}
+
+/**
+ * Shared form-field / submit DOM convention, used by EVERY widget type (including standard
+ * popups and `custom`) — see the cross-repo contract. Capturable inputs are marked
+ * `data-xenia-field="<name>"`; the submit trigger is marked `data-xenia-submit`. Read directly
+ * by `wireFormSubmit()` below, and reused as-is by the spin-wheel widget module
+ * (which has its own trigger — a Spin button — but still collects
+ * `data-xenia-field` values the same way).
+ */
+declare function collectFields(root: Element | ShadowRoot | Document): Record<string, string>;
+/**
+ * Wire the shared field-collection/submit convention onto an already-injected card. Used for
+ * every `standard`/`custom` widget (i.e. the fallthrough path in `ActionRenderer.wireCard()`) —
+ * this is the fix for the original loophole: a marketer/AI-authored popup with a real `<input>` +
+ * submit button now actually does something on submit.
+ *
+ * - If a real `<form>` is present in the injected HTML, its native `submit` event is
+ *   auto-detected: `preventDefault()` is called and its `FormData` is merged into the collected
+ *   `data-xenia-field` values (a marketer/AI who bothers to wrap fields in a `<form>` gets native
+ *   Enter-to-submit/validation for free — nothing requires it).
+ * - Otherwise, the trigger is a click on `[data-xenia-submit]`.
+ * - The submit control is disabled synchronously on trigger (double-submit guard) and grows a
+ *   small spinner (`[data-xenia-submitting]`) for the duration of the request.
+ * - On success: the spinner clears, the design's own `[data-xenia-success]` block (if authored —
+ *   see {@link revealSuccess}) swaps in for the form, and after at least `successDisplayMs` has
+ *   elapsed since the submit started (real dispatch round-trips are typically well under 100ms,
+ *   too fast to register on its own), the whole card fades/scales out and dismisses itself
+ *   ({@link fadeOutAndDismiss}) — the widget never just sits there disabled forever, and never
+ *   vanishes before a visitor sees it worked.
+ * - On error: the spinner clears, the control re-enables, and an error message is shown.
+ *
+ * The `<form>`'s native `submit` is ALWAYS intercepted, even when `action.formSubmit` is missing
+ * (the marketer hasn't configured a submission target in the webhook-response node's
+ * Form-submission panel yet) — otherwise an unconfigured widget's real `<form>` falls through to
+ * the browser's default GET-to-current-URL submission, i.e. a full page reload. An unconfigured
+ * submit now surfaces a visible, inert error instead of silently doing nothing OR reloading.
+ */
+declare function wireFormSubmit(root: Element | ShadowRoot, action: MessageAction, ctx: WidgetWireContext): void;
+
+/**
+ * Deterministic resting rotation (degrees) that lands segment `segmentIndex` (out of
+ * `segmentCount`, equal slices starting at 12 o'clock going clockwise) under the wheel's fixed
+ * pointer, plus `extraSpins` full rotations for purely cosmetic flair — extra spins are
+ * client-random visual dressing ONLY; they never affect which segment the wheel lands on (the
+ * returned value mod 360 is fully determined by `segmentIndex`/`segmentCount`).
+ *
+ * Pure, exported, and unit-testable with no DOM — per the "wheel resolution sequencing"
+ * rule, this is called only AFTER the server-resolved `segmentIndex` is known, never before.
+ */
+declare function computeSpinRotation(segmentIndex: number, segmentCount: number, extraSpins?: number): number;
+
+/**
+ * Dispatch table keyed by `widgetType`, consulted by `ActionRenderer.cardHtml()`/`wireCard()`.
+ * `standard`/undefined is deliberately NOT here — it falls through to `ActionRenderer`'s
+ * existing built-in card path (plus the shared `wireFormSubmit()` addition), per the cross-repo
+ * contract. A 3rd future widget type is one new module + one new line here.
+ */
+declare const WIDGET_RENDERERS: Record<string, WidgetRenderer>;
+
+export { ActionRenderer, AnalyticsQueue, type AnalyticsQueueOptions, type AutoTrackOptions, AutoTracker, type CtaHandler, InteractionType, type MessageAction, MessageComponentRenderer, MessageCta, MessagePlacement, MessageTemplateFn, type SlotMeta, type SubmitWidgetFormHandler, TokenProvider, WIDGET_RENDERERS, WidgetFormSubmit, type WidgetRenderer, WidgetSubmitResponse, type WidgetWireContext, XeniaAction, XeniaConfig, XeniaEvent, collectFields, computeSpinRotation, hideContent, parseDataAttribute, readSlotMeta, resolveTarget, showContent, swapContent, wireFormSubmit };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InteractionType, X as XeniaConfig, a as XeniaEvent, M as MessageCta, b as MessageTemplateFn, c as MessageComponentRenderer, d as XeniaAction } from '../actions-CkiSdvSa.js';
-export { A as AnalyticsContext, e as AnalyticsEventName, f as AnalyticsIdentity, g as AnalyticsIngestResponse, C as ClientEvent, h as ConsentState, i as ContentSwap, j as IdentifyRequest, k as IdentifyResponse, l as Identity, J as JsonValue, m as MessageMountContext, n as MessagePlacement, o as MessageRenderContext, P as PersonalizationSwap, R as ResolveBatchItem, p as ResolveBatchResult, q as ResolveOptions, r as ResolveResult, T as TrackOptions, W as WebhookResponse, s as XeniaClient, t as XeniaClientOptions, u as createXeniaClient, v as extractContentSwaps, w as parseActions, x as spliceSlots } from '../actions-CkiSdvSa.js';
+import { I as InteractionType, X as XeniaConfig, a as XeniaEvent, M as MessageCta, b as MessageTemplateFn, c as MessageComponentRenderer, W as WidgetFormSubmit, d as WidgetSubmitResponse, e as XeniaAction, f as MessagePlacement } from '../actions-CcBYV--3.js';
+export { A as AnalyticsContext, g as AnalyticsEventName, h as AnalyticsIdentity, i as AnalyticsIngestResponse, C as ClientEvent, j as ConsentState, k as ContentSwap, l as IdentifyRequest, m as IdentifyResponse, n as Identity, J as JsonValue, o as MessageMountContext, p as MessageRenderContext, P as PersonalizationSwap, R as ResolveBatchItem, q as ResolveBatchResult, r as ResolveOptions, s as ResolveResult, T as TrackOptions, t as WebhookResponse, u as WidgetPrize, v as WidgetSegment, w as WidgetType, x as XeniaClient, y as XeniaClientOptions, z as createXeniaClient, B as extractContentSwaps, D as parseActions, E as spliceSlots } from '../actions-CcBYV--3.js';
 
 interface Parsed {
     eventId: string;
@@ -156,6 +156,10 @@ declare class AnalyticsQueue {
 
 /** Callback invoked when a rendered CTA fires an event. */
 type CtaHandler = (event: string, cta: MessageCta) => void;
+/** Submits a widget's captured form values — injected from `XeniaClient.submitWidgetForm`. */
+type SubmitWidgetFormHandler = (submit: WidgetFormSubmit, fields: Record<string, string>, opts?: {
+    idempotencyKey?: string;
+}) => Promise<WidgetSubmitResponse>;
 /**
  * Resolve a target string to an element. Supports plain CSS selectors and the
  * `data-xenia-slot="<id>"` convention (a bare id with no CSS metacharacters is
@@ -183,12 +187,15 @@ declare class ActionRenderer {
     private readonly messageTemplate?;
     private readonly messageStyles?;
     private readonly messageComponent?;
+    private readonly submitWidgetFormFn?;
     /** Unmount callbacks for currently-mounted framework components, keyed by their container. */
     private readonly mounted;
     constructor(onCta?: CtaHandler, opts?: {
         messageTemplate?: MessageTemplateFn;
         messageStyles?: string;
         messageComponent?: MessageComponentRenderer;
+        /** Wired from `XeniaClient.submitWidgetForm` — powers every widget's form submission. */
+        submitWidgetForm?: SubmitWidgetFormHandler;
     });
     /** Apply a list of actions. Returns the count successfully applied. */
     apply(actions: XeniaAction[]): number;
@@ -211,6 +218,108 @@ declare class ActionRenderer {
     private positionClass;
     private cardHtml;
     private wireCard;
+    /** Build the imperative hooks (`dismiss`/`fireCta`/`submitWidgetForm`) handed to a widget's `wire()`. */
+    private buildWidgetCtx;
 }
 
-export { ActionRenderer, AnalyticsQueue, type AnalyticsQueueOptions, type AutoTrackOptions, AutoTracker, type CtaHandler, InteractionType, MessageComponentRenderer, MessageCta, MessageTemplateFn, type SlotMeta, TokenProvider, XeniaAction, XeniaConfig, XeniaEvent, hideContent, parseDataAttribute, readSlotMeta, resolveTarget, showContent, swapContent };
+/** A message-placement action (banner/popup/modal/inline) — the shape every widget renders. */
+type MessageAction = Extract<XeniaAction, {
+    type: MessagePlacement;
+}>;
+/**
+ * Imperative hooks a widget's `wire()` can call back into, injected by `ActionRenderer` —
+ * the widget module itself never touches `XeniaClient`/`XeniaApi` directly.
+ */
+interface WidgetWireContext {
+    /**
+     * Dismiss this message — unmounts/removes it, same as the built-in card's close button.
+     * Absent for placements with no dismiss affordance in this render (e.g. an `inline` action
+     * rendered without a wrapping overlay). Widgets should guard with `ctx.dismiss?.()`.
+     */
+    dismiss?: () => void;
+    /** Fire the action's `cta` (event + url), then {@link dismiss}. A no-op beyond dismiss when the action has no `cta`. */
+    fireCta: () => void;
+    /**
+     * Submit captured field values for this widget's `formSubmit` config. Routes to the `/flow`
+     * fast path or `/widget-submissions`, per the cross-repo contract's endpoint-selection rule —
+     * the widget module never branches on `mode`/inspects the ref fields itself, it just calls this.
+     *
+     * Rejects if the action has no `formSubmit` config or no submission handler is wired (e.g. a
+     * bare `ActionRenderer` constructed without `XeniaClient`). A per-widget-instance
+     * `idempotencyKey` is applied automatically and reused across every call from the SAME
+     * `wire()` invocation (i.e. a retried submit of the same interaction never mints a new one).
+     */
+    submitWidgetForm: (fields: Record<string, string>) => Promise<WidgetSubmitResponse>;
+}
+/**
+ * Renders and wires a `widgetType`'s UI. One implementation per dispatchable widget type,
+ * collected into `WIDGET_RENDERERS` (`client/widgets/index.ts`). `standard`/`custom`/undefined
+ * are NOT dispatched through this interface — they use `ActionRenderer`'s existing built-in card
+ * path unmodified (plus the shared `wireFormSubmit()` addition), per the cross-repo contract.
+ */
+interface WidgetRenderer {
+    /** Build the card markup injected into the shadow overlay or host-page slot. */
+    html(action: MessageAction, variant: MessagePlacement): string;
+    /** Wire interactivity after `html()`'s markup is already in the DOM under `root`. */
+    wire(root: Element | ShadowRoot, action: MessageAction, ctx: WidgetWireContext): void;
+}
+
+/**
+ * Shared form-field / submit DOM convention, used by EVERY widget type (including standard
+ * popups and `custom`) — see the cross-repo contract. Capturable inputs are marked
+ * `data-xenia-field="<name>"`; the submit trigger is marked `data-xenia-submit`. Read directly
+ * by `wireFormSubmit()` below, and reused as-is by the spin-wheel widget module
+ * (which has its own trigger — a Spin button — but still collects
+ * `data-xenia-field` values the same way).
+ */
+declare function collectFields(root: Element | ShadowRoot | Document): Record<string, string>;
+/**
+ * Wire the shared field-collection/submit convention onto an already-injected card. Used for
+ * every `standard`/`custom` widget (i.e. the fallthrough path in `ActionRenderer.wireCard()`) —
+ * this is the fix for the original loophole: a marketer/AI-authored popup with a real `<input>` +
+ * submit button now actually does something on submit.
+ *
+ * - If a real `<form>` is present in the injected HTML, its native `submit` event is
+ *   auto-detected: `preventDefault()` is called and its `FormData` is merged into the collected
+ *   `data-xenia-field` values (a marketer/AI who bothers to wrap fields in a `<form>` gets native
+ *   Enter-to-submit/validation for free — nothing requires it).
+ * - Otherwise, the trigger is a click on `[data-xenia-submit]`.
+ * - The submit control is disabled synchronously on trigger (double-submit guard) and grows a
+ *   small spinner (`[data-xenia-submitting]`) for the duration of the request.
+ * - On success: the spinner clears, the design's own `[data-xenia-success]` block (if authored —
+ *   see {@link revealSuccess}) swaps in for the form, and after at least `successDisplayMs` has
+ *   elapsed since the submit started (real dispatch round-trips are typically well under 100ms,
+ *   too fast to register on its own), the whole card fades/scales out and dismisses itself
+ *   ({@link fadeOutAndDismiss}) — the widget never just sits there disabled forever, and never
+ *   vanishes before a visitor sees it worked.
+ * - On error: the spinner clears, the control re-enables, and an error message is shown.
+ *
+ * The `<form>`'s native `submit` is ALWAYS intercepted, even when `action.formSubmit` is missing
+ * (the marketer hasn't configured a submission target in the webhook-response node's
+ * Form-submission panel yet) — otherwise an unconfigured widget's real `<form>` falls through to
+ * the browser's default GET-to-current-URL submission, i.e. a full page reload. An unconfigured
+ * submit now surfaces a visible, inert error instead of silently doing nothing OR reloading.
+ */
+declare function wireFormSubmit(root: Element | ShadowRoot, action: MessageAction, ctx: WidgetWireContext): void;
+
+/**
+ * Deterministic resting rotation (degrees) that lands segment `segmentIndex` (out of
+ * `segmentCount`, equal slices starting at 12 o'clock going clockwise) under the wheel's fixed
+ * pointer, plus `extraSpins` full rotations for purely cosmetic flair — extra spins are
+ * client-random visual dressing ONLY; they never affect which segment the wheel lands on (the
+ * returned value mod 360 is fully determined by `segmentIndex`/`segmentCount`).
+ *
+ * Pure, exported, and unit-testable with no DOM — per the "wheel resolution sequencing"
+ * rule, this is called only AFTER the server-resolved `segmentIndex` is known, never before.
+ */
+declare function computeSpinRotation(segmentIndex: number, segmentCount: number, extraSpins?: number): number;
+
+/**
+ * Dispatch table keyed by `widgetType`, consulted by `ActionRenderer.cardHtml()`/`wireCard()`.
+ * `standard`/undefined is deliberately NOT here — it falls through to `ActionRenderer`'s
+ * existing built-in card path (plus the shared `wireFormSubmit()` addition), per the cross-repo
+ * contract. A 3rd future widget type is one new module + one new line here.
+ */
+declare const WIDGET_RENDERERS: Record<string, WidgetRenderer>;
+
+export { ActionRenderer, AnalyticsQueue, type AnalyticsQueueOptions, type AutoTrackOptions, AutoTracker, type CtaHandler, InteractionType, type MessageAction, MessageComponentRenderer, MessageCta, MessagePlacement, MessageTemplateFn, type SlotMeta, type SubmitWidgetFormHandler, TokenProvider, WIDGET_RENDERERS, WidgetFormSubmit, type WidgetRenderer, WidgetSubmitResponse, type WidgetWireContext, XeniaAction, XeniaConfig, XeniaEvent, collectFields, computeSpinRotation, hideContent, parseDataAttribute, readSlotMeta, resolveTarget, showContent, swapContent, wireFormSubmit };