@captello/ulc-webview-sdk 0.1.0

package/dist/client-3IBxKbIE.d.cts

@@ -0,0 +1,561 @@
+/**
+ * Typed access to a submission's **visible** data — the list a host renders as
+ * key/value pairs (one row per filled, visible form element).
+ *
+ * The webview emits this as `visible_submissions_data` inside the `submission_body`
+ * payload: an array of items discriminated by `element_type`, where `element_value`'s
+ * shape depends on the type. This module mirrors that contract and provides:
+ *
+ * - {@link parseVisibleSubmissionsData} — narrow `unknown` to typed items, dropping
+ *   anything that doesn't match the contract.
+ * - {@link toDisplayValue} / {@link toDisplayPairs} — flatten each item to a string
+ *   (and `{ id, label, value }` rows) for direct rendering.
+ *
+ * For custom rendering, narrow on `element_type` and read the precisely-typed
+ * `element_value` yourself.
+ */
+/**
+ * Every form element type, mirroring the webview's `FormElementType`. The string
+ * values are the wire values. Structural types (sections, separators, …) never carry
+ * a value and never appear in visible submission data.
+ */
+declare enum FormElementType {
+    email = "email",
+    section = "section_block",
+    html_block = "section",
+    url = "url",
+    text = "text",
+    select = "select",
+    radio = "radio",
+    simple_name = "simple_name",
+    textarea = "textarea",
+    time = "time",
+    address = "address",
+    money = "money",
+    number = "number",
+    date = "date",
+    phone = "phone",
+    simple_phone = "simple_phone",
+    checkbox = "checkbox",
+    image = "image",
+    business_card = "business_card",
+    signature = "signature",
+    barcode = "barcode",
+    separator = "column_separator",
+    activation = "activation",
+    document = "documents",
+    datetime = "datetime",
+    meeting = "meeting",
+    audio = "audio",
+    rating = "rating",
+    assign_owner = "assign_owner",
+    boolean = "boolean",
+    engagem_feeder = "engagem_feeder",
+    speaker_section = "speaker_section_block",
+    session_section = "session_section_block",
+    image_placeholder = "image_placeholder",
+    star_rating = "star_survey",
+    attachments = "attachments"
+}
+/** Composite element value (simple_name / address): sub-field values keyed by sub-element id. */
+type CompositeSubmissionValue = {
+    [subElementId: string]: string;
+};
+/** Checkbox value when the element is an "order" checkbox (quantities + note). */
+type OrderCheckboxSubmissionData = {
+    values: {
+        value: string;
+        quantity: number;
+    }[];
+    note: string;
+};
+/** Radio/select value when the element is an "order" radio/select (quantity + note). */
+type OrderRadioSubmissionData = {
+    value: string;
+    quantity: number;
+    note: string;
+};
+/** An uploaded attachment. `blob` is not present on the wire (postMessage JSON drops it). */
+type AttachmentValue = {
+    token: string;
+    url: string;
+    name: string;
+    size: number;
+};
+/** A business-card capture: front/back image references (either may be absent). */
+type BusinessCardValue = {
+    front: string;
+    back: string;
+};
+/** One engagement-feeder question/answer entry. */
+type SubmissionQuestionData = {
+    question: string;
+    answers: string[];
+    /** `""` when the element is hidden. */
+    correct_answer: number | "";
+};
+/**
+ * Maps each value-carrying element type to its `element_value` shape. Structural
+ * types are intentionally absent, so they can never appear in a visible item.
+ */
+type VisibleSubmissionElementValueMap = {
+    [FormElementType.email]: string;
+    [FormElementType.url]: string;
+    [FormElementType.text]: string;
+    [FormElementType.textarea]: string;
+    [FormElementType.money]: string;
+    [FormElementType.number]: string;
+    [FormElementType.phone]: string;
+    [FormElementType.simple_phone]: string;
+    [FormElementType.date]: string;
+    [FormElementType.time]: string;
+    [FormElementType.datetime]: string;
+    [FormElementType.audio]: string;
+    [FormElementType.rating]: string;
+    [FormElementType.star_rating]: string;
+    [FormElementType.assign_owner]: string;
+    [FormElementType.signature]: string;
+    [FormElementType.barcode]: string;
+    [FormElementType.meeting]: string;
+    [FormElementType.activation]: string;
+    [FormElementType.checkbox]: string[] | OrderCheckboxSubmissionData;
+    [FormElementType.radio]: string | OrderRadioSubmissionData;
+    [FormElementType.select]: string | OrderRadioSubmissionData;
+    [FormElementType.image]: string[];
+    [FormElementType.document]: number[];
+    [FormElementType.engagem_feeder]: SubmissionQuestionData[];
+    [FormElementType.business_card]: Partial<BusinessCardValue>;
+    [FormElementType.boolean]: boolean;
+    [FormElementType.attachments]: AttachmentValue[];
+    [FormElementType.simple_name]: CompositeSubmissionValue;
+    [FormElementType.address]: CompositeSubmissionValue;
+};
+/** Element types that carry a user-facing value (i.e. can appear in visible data). */
+type VisibleSubmissionElementType = keyof VisibleSubmissionElementValueMap;
+/**
+ * One entry in `visible_submissions_data`, discriminated by `element_type`. Narrowing
+ * on `element_type` gives a precisely-typed `element_value`.
+ */
+type VisibleSubmissionDataItem = {
+    [T in VisibleSubmissionElementType]: {
+        element_id: string;
+        element_title: string;
+        element_type: T;
+        element_value: VisibleSubmissionElementValueMap[T];
+    };
+}[VisibleSubmissionElementType];
+/**
+ * Narrows `unknown` to a typed `VisibleSubmissionDataItem[]`, ready for rendering.
+ *
+ * Accepts, in order of convenience:
+ * - the `visible_submissions_data` array itself,
+ * - a `submission_body` payload object (the `data` of a `SubmissionBody` message) —
+ *   its `visible_submissions_data` is extracted,
+ * - anything else → `[]`.
+ *
+ * Items that don't match the contract (missing fields, structural/unknown
+ * `element_type`) are dropped, so the result is always safe to map over.
+ *
+ * @example
+ * webview.on(OutboundMessageType.SubmissionBody, (msg) => {
+ *   const rows = toDisplayPairs(msg.data); // [{ elementId, label, value }, ...]
+ *   render(rows);
+ * });
+ */
+declare function parseVisibleSubmissionsData(data: unknown): VisibleSubmissionDataItem[];
+/** Options for {@link toDisplayValue} / {@link toDisplayPairs}. */
+interface DisplayValueOptions {
+    /** Separator for list-like values (checkbox, image, …). Default `", "`. */
+    listSeparator?: string;
+    /** Labels for boolean values. Default `{ true: "Yes", false: "No" }`. */
+    booleanLabels?: {
+        true: string;
+        false: string;
+    };
+    /** Text used when a value is empty/blank. Default `""`. */
+    emptyText?: string;
+}
+/**
+ * Flattens a single visible item's `element_value` to a human-readable string for
+ * rendering — composites are joined, list/order values are summarized, booleans use
+ * the configured labels. For full control, read `element_value` directly instead.
+ */
+declare function toDisplayValue(item: VisibleSubmissionDataItem, options?: DisplayValueOptions): string;
+/** A render-ready key/value row. */
+interface SubmissionDisplayPair {
+    elementId: string;
+    label: string;
+    value: string;
+}
+/**
+ * One-shot helper: parse `unknown` and map each visible item to a
+ * `{ elementId, label, value }` row, where `value` is {@link toDisplayValue}'s output.
+ * Ideal for rendering a submission as a key/value list.
+ */
+declare function toDisplayPairs(data: unknown, options?: DisplayValueOptions): SubmissionDisplayPair[];
+
+/**
+ * The message protocol exchanged between the Captello capture webview (the iframe)
+ * and its host page.
+ *
+ * Wire format (this is the contract — match it exactly):
+ * - Every message is a JSON **string**. The webview sends outbound messages with
+ *   `JSON.stringify(message)` and reads inbound messages with `JSON.parse(event.data)`.
+ *   A host that posts a raw object instead of a string will be ignored, because the
+ *   webview's parser produces a non-object and bails.
+ * - Every message is an object with a `type` discriminator. Inbound and outbound
+ *   types are disjoint string enums.
+ *
+ * Direction is named from the **webview's** point of view:
+ * - {@link OutboundMessageType}: webview → host (the host listens for these).
+ * - {@link InboundMessageType}: host → webview (the host sends these).
+ */
+
+/** Message `type` values the webview emits to its host. */
+declare enum OutboundMessageType {
+    /** The form finished loading and rendering. Safe to interact with it after this. */
+    FormLoadComplete = "form_load_complete",
+    /** A user-facing error occurred; `data` is the translated, display-ready message. */
+    FormErrorMessage = "form_error_message",
+    /**
+     * Emitted for embedded forms instead of submitting directly: `data` is the full
+     * submission body for the host to persist/forward.
+     */
+    SubmissionBody = "submission_body",
+    /** The form was submitted successfully (used in kiosk / quick-capture flows). */
+    FormSubmitSuccess = "form_submit_success",
+    /** Connexions: the host should perform the profile redirect (embed mode). */
+    ConnexionsProfileRedirect = "connexions_profile_redirect",
+    /** Connexions: the host should trigger the vCard download (embed mode). */
+    ConnexionsDownloadVcard = "connexions_download_vcard"
+}
+/**
+ * Opaque submission payload carried by {@link OutboundMessageType.SubmissionBody}.
+ *
+ * This mirrors the webview's internal `FormSubmission` model. It is intentionally
+ * typed as an open record here so the SDK stays decoupled from the app's full model
+ * graph; the documented fields below are stable, the rest are passed through as-is.
+ * Host code that needs the deep element-value types should treat `data` as untyped
+ * and key it by element id (e.g. `"element_12"`, `"element_12_3"`).
+ */
+interface SubmissionBody {
+    id: number;
+    form_id: number;
+    prospect_id: number;
+    email: string;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    company: string;
+    phone: string;
+    /** Submitted values keyed by element id / sub-element id. */
+    data: Record<string, unknown>;
+    /**
+     * Visible, filled elements ready to render as key/value rows — one item per
+     * element, discriminated by `element_type`. Use {@link parseVisibleSubmissionsData}
+     * or {@link toDisplayPairs} to consume it. May be absent on older webview builds.
+     */
+    visible_submissions_data?: VisibleSubmissionDataItem[];
+    submission_date: string;
+    /** Query-string params the webview was loaded with, echoed back on submit. */
+    query_parameters?: Record<string, string>;
+    /** Additional fields from the webview's submission model are passed through verbatim. */
+    [key: string]: unknown;
+}
+/**
+ * Loose submission shape accepted when **pre-filling** the form (host → webview).
+ *
+ * Distinct from {@link SubmissionBody}: a received `submission_body` is always fully
+ * populated, but when pre-filling you typically either round-trip a previously-received
+ * body or pass a partial object assembled from your own data. A {@link SubmissionBody}
+ * is assignable to this, so round-tripping just works.
+ */
+interface SubmissionPrefill {
+    /** Submitted values keyed by element id / sub-element id. */
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface FormLoadCompleteMessage {
+    type: OutboundMessageType.FormLoadComplete;
+}
+interface FormSubmitSuccessMessage {
+    type: OutboundMessageType.FormSubmitSuccess;
+}
+interface FormErrorMessageMessage {
+    type: OutboundMessageType.FormErrorMessage;
+    /** Translated, display-ready error text. */
+    data: string;
+}
+interface SubmissionBodyMessage {
+    type: OutboundMessageType.SubmissionBody;
+    data: SubmissionBody;
+}
+interface ConnexionsProfileRedirectMessage {
+    type: OutboundMessageType.ConnexionsProfileRedirect;
+}
+interface ConnexionsDownloadVcardMessage {
+    type: OutboundMessageType.ConnexionsDownloadVcard;
+}
+/** Discriminated union of every message the webview can emit to its host. */
+type OutboundMessage = FormLoadCompleteMessage | FormSubmitSuccessMessage | FormErrorMessageMessage | SubmissionBodyMessage | ConnexionsProfileRedirectMessage | ConnexionsDownloadVcardMessage;
+/** Maps each outbound `type` to its full message shape (used by the client's `.on`). */
+type OutboundMessageMap = {
+    [M in OutboundMessage as M["type"]]: M;
+};
+/** Message `type` values the host sends into the webview. */
+declare enum InboundMessageType {
+    /** Programmatically trigger form submission (as if the user pressed submit). */
+    Submit = "submit_form",
+    /** Reset the form, clearing all entered values. */
+    Reset = "reset_form",
+    /** Pre-fill the form with existing data. See {@link PrefillDataType}. */
+    FormPrefill = "form_prefill",
+    /** Switch the current submission into draft-update mode. */
+    UpdateDraft = "update_draft",
+    /** Run validation against a target field (or the whole form). */
+    TriggerValidation = "trigger_validation"
+}
+/** Shape selector for {@link InboundMessageType.FormPrefill} payloads. */
+declare enum PrefillDataType {
+    /** `data` is a full ULC submission (the webview's submission model). */
+    UlcSubmission = "ulc_submission",
+    /** `data` is a list of transcription field/value items. */
+    Info = "info",
+    /** `data` is `{ submission, info }` — a submission plus transcription items. */
+    UlcSubmissionAndInfo = "ulc_submission_and_info"
+}
+/** Targets for {@link InboundMessageType.TriggerValidation}. */
+type ValidationTarget = "invitation_code" | "email" | "all";
+/**
+ * A single transcription field/value item used by {@link PrefillDataType.Info}.
+ *
+ * The webview matches each item to a form element by `ll_field_unique_identifier`
+ * alone (e.g. `"FirstName"`, `"Email"`); `ll_field_id` is catalog metadata and is not
+ * used for matching, so it is accepted as either a number or a string. `value` is
+ * typically a string but may be a boolean (e.g. the PII opt-out field).
+ */
+interface PrefillInfoItem {
+    ll_field_unique_identifier: string;
+    ll_field_id?: string | number;
+    value: string | boolean;
+}
+interface SubmitMessage {
+    type: InboundMessageType.Submit;
+}
+interface ResetMessage {
+    type: InboundMessageType.Reset;
+}
+interface UpdateDraftMessage {
+    type: InboundMessageType.UpdateDraft;
+}
+interface TriggerValidationMessage {
+    type: InboundMessageType.TriggerValidation;
+    target: ValidationTarget;
+}
+interface PrefillSubmissionMessage {
+    type: InboundMessageType.FormPrefill;
+    data_type: PrefillDataType.UlcSubmission;
+    /** A submission body to pre-fill from (a received {@link SubmissionBody} or a partial). */
+    data: SubmissionPrefill;
+}
+interface PrefillInfoMessage {
+    type: InboundMessageType.FormPrefill;
+    data_type: PrefillDataType.Info;
+    data: PrefillInfoItem[];
+}
+interface PrefillSubmissionAndInfoMessage {
+    type: InboundMessageType.FormPrefill;
+    data_type: PrefillDataType.UlcSubmissionAndInfo;
+    data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    };
+}
+/** Discriminated union of every message the host can send into the webview. */
+type InboundMessage = SubmitMessage | ResetMessage | UpdateDraftMessage | TriggerValidationMessage | PrefillSubmissionMessage | PrefillInfoMessage | PrefillSubmissionAndInfoMessage;
+/**
+ * Parses a raw `MessageEvent.data` value into a typed {@link OutboundMessage}, or
+ * returns `null` if it is not a recognized Captello webview message.
+ *
+ * Accepts either a JSON string (the webview always sends strings) or an
+ * already-parsed object, so it is robust to hosts/proxies that pre-parse.
+ */
+declare function parseOutboundMessage(data: unknown): OutboundMessage | null;
+
+/** Listener for a specific outbound message type. */
+type OutboundListener<T extends OutboundMessageType> = (message: OutboundMessageMap[T]) => void;
+/** Listener for every outbound message (used by {@link CaptelloWebview.onAny}). */
+type AnyOutboundListener = (message: OutboundMessage) => void;
+/** Unsubscribe handle returned by every `on*` method. Calling it removes the listener. */
+type Unsubscribe = () => void;
+/**
+ * Rejection reason from {@link CaptelloWebview.submitAndWait} when the webview reports
+ * a `form_error_message`. `message` is the translated, display-ready text.
+ */
+declare class SubmissionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Rejection reason from {@link CaptelloWebview.submitAndWait} when no `submission_body`
+ * or `form_error_message` arrives within the timeout.
+ */
+declare class SubmissionTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+interface CaptelloWebviewOptions {
+    /**
+     * Origin to validate incoming messages against and to target outgoing messages.
+     * Strongly recommended — set it to the webview's origin (e.g.
+     * `"https://capture.captello.com"`). Use {@link targetOriginFromUrl} to derive it
+     * from the embed URL.
+     *
+     * Defaults to `"*"`, which accepts messages from any origin and posts without an
+     * origin check. Only acceptable for trusted/local development.
+     */
+    targetOrigin?: string;
+    /**
+     * The window to attach the `message` listener to. Defaults to the global `window`.
+     * Override for testing or non-standard host environments.
+     */
+    hostWindow?: Window;
+    /**
+     * If `true` (default), incoming messages are accepted only when they originate
+     * from the bound iframe's `contentWindow`. Set `false` only if the webview relays
+     * messages through an intermediate window and source matching is impossible.
+     */
+    matchSource?: boolean;
+    /**
+     * If `true` (default), messages sent before the webview reports
+     * `form_load_complete` are buffered and flushed, in order, once it's ready. This
+     * removes a common footgun: calling `prefillInfo(...)` right after mount would
+     * otherwise post to a form that isn't listening yet and be silently dropped.
+     *
+     * Set `false` to send immediately (the legacy behavior). Note: a client that
+     * attaches *after* the form already loaded will not have seen `form_load_complete`,
+     * so its queued messages won't flush — create the client with the iframe.
+     */
+    queueUntilReady?: boolean;
+}
+type ElementOrFrame = HTMLIFrameElement | {
+    contentWindow: Window | null;
+};
+/**
+ * Host-side controller for an embedded Captello capture webview.
+ *
+ * Wraps a single `<iframe>` and encodes the full message protocol:
+ * - **Receiving** (webview → host): subscribe with {@link on} / {@link onAny}.
+ * - **Sending** (host → webview): use {@link submit}, {@link reset}, {@link prefill},
+ *   {@link triggerValidation}, {@link updateDraft}, or the lower-level {@link send}.
+ *
+ * Wire details handled for you: outgoing messages are `JSON.stringify`'d (the webview
+ * parses inbound data with `JSON.parse`, so a raw object would be ignored), and
+ * incoming messages are validated by origin + source before being parsed.
+ *
+ * @example
+ * ```ts
+ * const iframe = document.querySelector("iframe")!;
+ * const webview = new CaptelloWebview(iframe, {
+ *   targetOrigin: "https://capture.captello.com",
+ * });
+ *
+ * webview.on(OutboundMessageType.FormLoadComplete, () => console.log("ready"));
+ * webview.on(OutboundMessageType.SubmissionBody, (msg) => save(msg.data));
+ *
+ * // later, drive the form:
+ * webview.submit();
+ *
+ * // on teardown:
+ * webview.destroy();
+ * ```
+ */
+declare class CaptelloWebview {
+    private readonly frame;
+    private readonly targetOrigin;
+    private readonly hostWindow;
+    private readonly matchSource;
+    private readonly listeners;
+    private readonly anyListeners;
+    private readonly boundHandler;
+    private destroyed;
+    private readonly queueUntilReady;
+    /** True once `form_load_complete` has been observed. */
+    private ready;
+    /** Messages sent before ready, flushed in order on load. */
+    private readonly outbox;
+    constructor(frame: ElementOrFrame, options?: CaptelloWebviewOptions);
+    /** `true` once the webview has reported `form_load_complete`. */
+    get isReady(): boolean;
+    /**
+     * Subscribe to a single outbound message type. Returns an unsubscribe function.
+     *
+     * @example webview.on(OutboundMessageType.FormErrorMessage, (m) => toast(m.data));
+     */
+    on<T extends OutboundMessageType>(type: T, listener: OutboundListener<T>): Unsubscribe;
+    /**
+     * Subscribe once: the listener is removed automatically after it fires the first
+     * time for `type`. Returns an unsubscribe function for cancelling early.
+     */
+    once<T extends OutboundMessageType>(type: T, listener: OutboundListener<T>): Unsubscribe;
+    /** Subscribe to every outbound message regardless of type. Returns an unsubscribe function. */
+    onAny(listener: AnyOutboundListener): Unsubscribe;
+    /**
+     * Low-level send: posts any inbound message to the webview as a JSON string.
+     * Prefer the typed helpers below; use this only for forward-compatibility.
+     *
+     * When `queueUntilReady` is enabled (the default) and the form hasn't reported
+     * `form_load_complete` yet, the message is buffered and flushed on load instead of
+     * posted immediately.
+     *
+     * @throws if the iframe's `contentWindow` is not available (not yet loaded /
+     *   detached) and the message can't be queued.
+     */
+    send(message: InboundMessage): void;
+    /** Posts a message immediately, bypassing the ready-queue. */
+    private postNow;
+    /** Marks the client ready and flushes any queued messages, in order. */
+    private markReadyAndFlush;
+    /** Programmatically submit the form (fire-and-forget). */
+    submit(): void;
+    /**
+     * Submit the form and await the outcome.
+     *
+     * Sends `submit_form`, then resolves with the {@link SubmissionBody} when the
+     * webview emits `submission_body`, or rejects with a {@link SubmissionError}
+     * (carrying the translated message) when it emits `form_error_message`. Rejects
+     * with a {@link SubmissionTimeoutError} if neither arrives within `timeoutMs`.
+     *
+     * This is the typed, leak-free version of the common "click submit, wait for the
+     * result" flow — listeners are always cleaned up, including on timeout.
+     *
+     * @param timeoutMs how long to wait before giving up. Defaults to 60_000.
+     * @example
+     * try {
+     *   const body = await webview.submitAndWait();
+     *   await persist(body);
+     * } catch (err) {
+     *   if (err instanceof SubmissionError) showToast(err.message);
+     * }
+     */
+    submitAndWait(timeoutMs?: number): Promise<SubmissionBody>;
+    /** Reset the form, clearing all entered values. */
+    reset(): void;
+    /** Switch the current submission into draft-update mode. */
+    updateDraft(): void;
+    /** Run validation against a target field, or `"all"` for the whole form. */
+    triggerValidation(target: ValidationTarget): void;
+    /** Pre-fill the form from a submission body (a received body or a partial). */
+    prefillSubmission(submission: SubmissionPrefill): void;
+    /** Pre-fill the form from a list of transcription field/value items. */
+    prefillInfo(info: PrefillInfoItem[]): void;
+    /** Pre-fill the form from a submission plus transcription items. */
+    prefillSubmissionAndInfo(data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    }): void;
+    /** Remove the `message` listener and drop all subscriptions. Idempotent. */
+    destroy(): void;
+    private handleMessage;
+}
+
+export { type AnyOutboundListener as A, type BusinessCardValue as B, type CaptelloWebviewOptions as C, type DisplayValueOptions as D, FormElementType as F, type InboundMessage as I, OutboundMessageType as O, type PrefillInfoItem as P, type SubmissionBody as S, type Unsubscribe as U, type ValidationTarget as V, type OutboundMessageMap as a, SubmissionError as b, SubmissionTimeoutError as c, type OutboundMessage as d, CaptelloWebview as e, type SubmissionPrefill as f, type AttachmentValue as g, type CompositeSubmissionValue as h, InboundMessageType as i, type OrderCheckboxSubmissionData as j, type OrderRadioSubmissionData as k, type OutboundListener as l, PrefillDataType as m, type SubmissionDisplayPair as n, type SubmissionQuestionData as o, type VisibleSubmissionDataItem as p, type VisibleSubmissionElementType as q, type VisibleSubmissionElementValueMap as r, parseOutboundMessage as s, parseVisibleSubmissionsData as t, toDisplayPairs as u, toDisplayValue as v };