@captello/ulc-webview-sdk 1.0.0 → 1.2.0

package/dist/client-CAMlFA8s.d.ts

@@ -0,0 +1,898 @@
+/**
+ * Types for 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 {@link VisibleSubmissionDataItem}, discriminated by
+ * `element_type`, where `element_value`'s shape depends on the type. Narrow on
+ * `element_type` to get a precisely-typed `element_value` and render it however you
+ * like:
+ *
+ * @example
+ * for (const item of submission.visible_submissions_data ?? []) {
+ *   switch (item.element_type) {
+ *     case FormElementType.email:
+ *       row(item.element_title, item.element_value); // element_value: string
+ *       break;
+ *     case FormElementType.checkbox:
+ *       // element_value: string[] | OrderCheckboxSubmissionData
+ *       break;
+ *     // …
+ *   }
+ * }
+ */
+/**
+ * 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"
+}
+/**
+ * `simple_name` value: the visible sub-fields keyed by their transcription identifier
+ * (`ll_field_unique_identifier`), the same identifiers used by prefill. Hidden sub-fields are
+ * omitted, so keys are optional.
+ */
+type NameSubmissionValue = {
+    FirstName?: string;
+    LastName?: string;
+};
+/**
+ * `address` value: the visible sub-fields keyed by their transcription identifier
+ * (`ll_field_unique_identifier`). Hidden sub-fields are omitted, so keys are optional.
+ */
+type AddressSubmissionValue = {
+    StreetAddress?: string;
+    StreetAddress2?: string;
+    City?: string;
+    State?: string;
+    Zipcode?: string;
+    Country?: 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]: NameSubmissionValue;
+    [FormElementType.address]: AddressSubmissionValue;
+};
+/** 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];
+
+/**
+ * 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. `action` indicates whether it was a new submission or an update. */
+    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",
+    /**
+     * The user pressed the transcribe button (shown only when the embed URL enables
+     * it via `show_transcribe_button`): the host should transcribe the request's
+     * scan images and answer with an inbound
+     * {@link InboundMessageType.TranscribeScannerResult}.
+     */
+    TranscribeScannerRequest = "transcribe_scanner_request"
+}
+/**
+ * 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` (narrow on it for a precisely-typed
+     * `element_value`). See {@link VisibleSubmissionDataItem}. 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;
+}
+/**
+ * Submitted values flat-keyed by element / sub-element id (e.g. `"element_12"`, `"element_12_3"`).
+ *
+ * This is the webview's own internal shape rather than the submissions API's: it is what a
+ * received {@link SubmissionBody} carries, and what the backend stores verbatim for a draft and
+ * hands back unchanged — hence the name. Either can be passed to
+ * {@link SubmissionPrefill.data} as-is, so an `onSubmissionBody` payload round-trips.
+ *
+ * Contrast {@link SubmissionPrefillDataItem}, the array shape the submissions API returns.
+ */
+type DraftSubmissionData = Record<string, unknown>;
+/**
+ * One submitted value in {@link SubmissionPrefill.data}. Mirrors the submissions API's
+ * `SubmissionDataResponse` shape, so a `submission.data` array fetched from that API can
+ * be passed straight through as-is.
+ */
+interface SubmissionPrefillDataItem {
+    element_id: string;
+    element_title: string;
+    value: string;
+    /** Present only when the element has sub-elements (e.g. a simple name or address). */
+    value_splitted?: Record<string, string>;
+}
+/**
+ * Loose submission shape accepted when **pre-filling** the form (host → webview).
+ *
+ * Distinct from {@link SubmissionBody} in that every field is optional — assemble a partial
+ * object from your own data rather than populating a whole body.
+ *
+ * `data` accepts either shape a host is likely to be holding, and the webview normalizes
+ * whichever it receives:
+ * - {@link SubmissionPrefillDataItem}`[]` — one entry per element, as the submissions API
+ *   returns it for a submitted submission. Pass a fetched `submission.data` array straight
+ *   through.
+ * - {@link DraftSubmissionData} — values flat-keyed by element / sub-element id. This is the
+ *   shape a received {@link SubmissionBody} carries, and the shape a draft is stored and
+ *   returned in, so `onSubmissionBody` payloads round-trip directly.
+ */
+interface SubmissionPrefill {
+    /**
+     * Submitted values, as either the submissions API's array (see
+     * {@link SubmissionPrefillDataItem}) or a flat {@link DraftSubmissionData} record.
+     */
+    data?: SubmissionPrefillDataItem[] | DraftSubmissionData;
+    [key: string]: unknown;
+}
+interface FormLoadCompleteMessage {
+    type: OutboundMessageType.FormLoadComplete;
+}
+interface FormSubmitSuccessMessage {
+    type: OutboundMessageType.FormSubmitSuccess;
+    action: "create" | "update";
+}
+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;
+}
+/**
+ * Webview → host: the user pressed the transcribe button. Answer with a
+ * {@link TranscribeScannerResultMessage} (see
+ * {@link CaptelloWebview.onTranscribeScannerRequest} for the handler that does this
+ * for you). The webview shows a pending state on the button and gives up with a
+ * user-facing error if no result arrives in time.
+ *
+ * Host processing is a convention, not a one-off: future operations get their own
+ * `*_request` / `*_result` message pairs shaped like this one.
+ */
+interface TranscribeScannerRequestMessage {
+    type: OutboundMessageType.TranscribeScannerRequest;
+    /** Correlation id — echo it back verbatim in the result. */
+    request_id: string;
+    /** The scanner (badge/barcode) element whose scan should be transcribed (e.g. `"element_6"`). */
+    element_id: string;
+    /** Public URLs of the uploaded scan images (the scanner element's image value). */
+    image_urls: string[];
+    /** The draft submission token the webview was loaded with, when it has one. */
+    draft_submission_token?: string;
+}
+/** Discriminated union of every message the webview can emit to its host. */
+type OutboundMessage = FormLoadCompleteMessage | FormSubmitSuccessMessage | FormErrorMessageMessage | SubmissionBodyMessage | ConnexionsProfileRedirectMessage | ConnexionsDownloadVcardMessage | TranscribeScannerRequestMessage;
+/** 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. */
+    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",
+    /** Answer to an outbound {@link OutboundMessageType.TranscribeScannerRequest}. */
+    TranscribeScannerResult = "transcribe_scanner_result"
+}
+/**
+ * Shape selector for {@link InboundMessageType.FormPrefill} payloads.
+ *
+ * Vestigial: the webview keys only off the message `type` and reads `data` directly —
+ * it never inspects `data_type`. Confirmed by mutation-testing the integration spec (a
+ * deliberately wrong value changed nothing). Kept because it is part of the shipped wire
+ * shape and older webview builds may still read it; `prefill()` sets it for you.
+ */
+declare enum PrefillDataType {
+    UlcSubmissionAndInfo = "ulc_submission_and_info"
+}
+/** Targets for {@link InboundMessageType.TriggerValidation}. */
+type ValidationTarget = "invitation_code" | "email" | "all";
+/**
+ * A single transcription field/value item for the `info` prefill array.
+ *
+ * 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 PrefillMessage {
+    type: InboundMessageType.FormPrefill;
+    data_type: PrefillDataType.UlcSubmissionAndInfo;
+    data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    };
+}
+/**
+ * One transcribed field in {@link TranscribeScannerResultData.fields}.
+ *
+ * Semantically the same thing as a {@link PrefillInfoItem} but in the transcription
+ * service's camelCase wire casing — `llFieldIdentifier` carries the same values as
+ * `ll_field_unique_identifier` (e.g. `"FirstName"`, `"Email"`), and it is what the
+ * webview matches form elements by. The webview ignores fields with an empty `value`
+ * rather than blanking already-filled inputs.
+ */
+interface TranscribedScannerField {
+    /** Catalog field identifier the webview matches on, e.g. `"FirstName"`. */
+    llFieldIdentifier: string;
+    /** Catalog field id — metadata, not used for matching. */
+    llFieldId?: number;
+    /** Display name as the transcription service reports it. */
+    llFieldNameName?: string;
+    value: string;
+}
+/** Success payload of a {@link TranscribeScannerResultMessage}. */
+interface TranscribeScannerResultData {
+    fields: TranscribedScannerField[];
+    /** How the transcription was produced, e.g. `"ocr_transcription"`. */
+    submissionType?: string;
+}
+/**
+ * Host → webview: the answer to a {@link TranscribeScannerRequestMessage}. Send
+ * `data` with the transcribed fields on success, or `error` (display-ready text) on
+ * failure. `request_id` should echo the request's; the webview also accepts a result
+ * without one while exactly one request is pending, for hosts that answer strictly
+ * one at a time.
+ */
+interface TranscribeScannerResultMessage {
+    type: InboundMessageType.TranscribeScannerResult;
+    /** The `request_id` of the request being answered, verbatim. */
+    request_id?: string;
+    /** Transcribed fields (success). */
+    data?: TranscribeScannerResultData;
+    /** Display-ready error text (failure) — leave `data` unset. */
+    error?: string;
+}
+/** Discriminated union of every message the host can send into the webview. */
+type InboundMessage = SubmitMessage | ResetMessage | UpdateDraftMessage | TriggerValidationMessage | PrefillMessage | TranscribeScannerResultMessage;
+/**
+ * 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;
+/**
+ * Handler for {@link CaptelloWebview.onTranscribeScannerRequest}. Receives the full
+ * request (`element_id`, `image_urls`, `draft_submission_token`) plus a
+ * {@link TranscribeScannerReply}, and answers in either style:
+ *
+ * - **return** the transcribed fields (a promise is fine) — the promise-based style, or
+ * - **call `reply.resolve(...)` / `reply.reject(...)`** whenever the work finishes —
+ *   for callback-style code that can't hand back a promise.
+ *
+ * Returning nothing hands ownership to `reply`, leaving the request open until it
+ * answers. A thrown error / rejection becomes an error result; if it's an `Error`, its
+ * `message` is shown to the user by the webview, so throw display-ready messages.
+ */
+type TranscribeScannerRequestHandler = (request: TranscribeScannerRequestMessage, reply: TranscribeScannerReply) => TranscribeScannerResultData | void | Promise<TranscribeScannerResultData | void>;
+/**
+ * The second argument handed to a {@link TranscribeScannerRequestHandler} — everything
+ * needed to answer one request, so the handler never has to reach back out to the
+ * client or touch `postMessage` itself.
+ *
+ * Use it when the transcription can't hand back a promise: a callback-style AJAX
+ * wrapper, an event bus, a method that returns `void` and finishes whenever it
+ * finishes. Pass it along to whatever does the work and let that code answer:
+ *
+ * ```js
+ * webview.onTranscribeScannerRequest((request, reply) => {
+ *   transcribeService(request.image_urls,
+ *     (fields) => reply.resolve({ fields, submissionType: "ocr_transcription" }),
+ *     () => reply.reject("Transcription failed."),
+ *   );
+ * });
+ * ```
+ *
+ * A handler that returns a value (or a promise of one) is answered from that return
+ * value and can ignore this entirely — the promise style is unchanged.
+ *
+ * The first answer wins: once `resolve`, `reject`, or the handler's own return value
+ * has answered, later calls are ignored rather than posting a second result.
+ */
+interface TranscribeScannerReply {
+    /** Answer with the transcribed fields. */
+    resolve(data: TranscribeScannerResultData): void;
+    /**
+     * Fail the request. `error` is shown to the user by the webview verbatim, so pass
+     * display-ready text.
+     */
+    reject(error: string): void;
+    /** `true` once this request has been answered, by either path. */
+    readonly answered: boolean;
+}
+/**
+ * Identifies the transcribe request being answered by
+ * {@link CaptelloWebview.resolveTranscribeScannerRequest} /
+ * {@link CaptelloWebview.rejectTranscribeScannerRequest} — the request message itself,
+ * or its bare `request_id`.
+ *
+ * `null`/`undefined` sends an un-correlated result, which the webview accepts only
+ * while exactly one request is pending. Pass the request whenever you have it.
+ */
+type TranscribeScannerRequestRef = TranscribeScannerRequestMessage | string | null | undefined;
+/** The `unsubscribe()` side of a subscription handle. */
+interface Subscription {
+    /** Remove the listener. Safe to call more than once. */
+    unsubscribe(): void;
+}
+/**
+ * Handle returned by every `on*` method. It is an object carrying
+ * {@link Subscription.unsubscribe}, and is also directly callable:
+ *
+ * ```ts
+ * const sub = webview.on(OutboundMessageType.SubmissionBody, save);
+ * sub.unsubscribe(); // preferred — reads clearly at the call site
+ * sub();             // equivalent
+ * ```
+ *
+ * Both do the same thing; the callable form keeps older `const off = ...; off()`
+ * code working.
+ */
+type Unsubscribe = (() => void) & Subscription;
+/**
+ * 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"`).
+     *
+     * A full URL is accepted and reduced to its origin, so you can pass the embed URL
+     * or the webview base URL you already have on hand rather than deriving the origin
+     * yourself.
+     *
+     * 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 `prefill(...)` 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;
+    /**
+     * If `true` (default), the client calls {@link CaptelloWebview.destroy} on itself
+     * once the bound iframe is removed from the document — so a host that tears down a
+     * panel, modal, or route doesn't leak the `message` listener or have to remember a
+     * matching `destroy()`.
+     *
+     * Removal is detected with a `MutationObserver`, and an ancestor being removed
+     * counts: what matters is that the iframe is no longer connected to the document.
+     * Only ever fires after the iframe has been seen connected, so constructing against
+     * a not-yet-inserted element is not mistaken for a teardown.
+     *
+     * Requires a real DOM element and `MutationObserver`; with a `{ contentWindow }`
+     * stand-in, or in a non-DOM environment, there is nothing to observe and this is
+     * inert. Set `false` to manage the lifetime entirely yourself — e.g. when you
+     * deliberately detach and re-insert the same iframe element.
+     */
+    autoDestroy?: boolean;
+    /**
+     * If `true`, the client may learn its webview window from the **first** inbound
+     * message instead of being handed an iframe — see {@link attach}, which is the
+     * supported way to switch this on.
+     *
+     * Only ever adopts a sender that has already cleared the origin check and parsed as
+     * a well-formed Captello message, so with `targetOrigin` set to the webview's origin
+     * only the webview can be adopted. Every later message is source-matched against
+     * whatever was adopted, so this is as strict as an explicit iframe after the first
+     * message. Under the default `targetOrigin: "*"` that gate is absent — one more
+     * reason to set it in production.
+     *
+     * An explicitly passed iframe always wins; nothing is adopted while one resolves.
+     *
+     * @default false
+     */
+    adoptSource?: boolean;
+}
+/** Options for {@link attach}. Same as the client's, minus the ones it manages itself. */
+type AttachOptions = Omit<CaptelloWebviewOptions, "adoptSource">;
+/**
+ * Attaches to the embedded Captello webview **without an iframe reference**.
+ *
+ * This is the drop-in replacement for a hand-rolled global
+ * `window.addEventListener("message", …)` dispatcher. Call it once, register your
+ * handlers, and you are done — there is nothing to query from the DOM, no ordering to
+ * get right relative to when the iframe is created, and no teardown to remember.
+ *
+ * ```js
+ * const webview = CaptelloSdk.attach({ targetOrigin: CAPTURE_PORTAL_WEB_VIEW_BASE });
+ *
+ * webview.on(CaptelloSdk.OutboundMessageType.FormErrorMessage, (m) => showError(m.data));
+ * webview.on(CaptelloSdk.OutboundMessageType.SubmissionBody, (m) => save(m.data));
+ * webview.onTranscribeScannerRequest((request, reply) => transcribe(request, reply));
+ * ```
+ *
+ * How it finds the form: the first inbound message that clears the origin check **and**
+ * parses as a well-formed Captello message identifies the webview. That sender becomes
+ * the target for sends and the window every later message is source-matched against —
+ * so after the first message this is as strict as passing the iframe. Set
+ * `targetOrigin` to the webview's origin and only the webview can ever be adopted.
+ *
+ * Teardown is still automatic: a removed iframe's window reports `closed`, which is
+ * readable cross-origin, so the client notices its form going away and destroys itself.
+ * Pass `autoDestroy: false` to own the lifetime yourself.
+ *
+ * The trade-off versus {@link CaptelloWebview}: until the form speaks once there is no
+ * window to post to, so an unprompted `submit()` / `prefill()` before then has nowhere
+ * to go. With the default `queueUntilReady` those sends are buffered and flushed on
+ * `form_load_complete`, which covers the normal case. If you drive the form
+ * unprompted from page load and can hold the element, prefer
+ * `new CaptelloWebview(iframe, …)`.
+ */
+declare function attach(options?: AttachOptions): CaptelloWebview;
+/**
+ * The webview's iframe — the element itself, or any object exposing its
+ * `contentWindow` (useful for test doubles).
+ *
+ * The caller is responsible for the iframe being mounted before constructing the
+ * client: messages are source-matched against its `contentWindow` from the very first
+ * one, and sends post to it directly.
+ *
+ * When a real DOM element is passed, the client also tears itself down automatically
+ * once that element leaves the document — see
+ * {@link CaptelloWebviewOptions.autoDestroy}.
+ */
+type FrameLike = 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;
+    /** Watches for the iframe leaving the document — see `autoDestroy`. */
+    private frameObserver?;
+    /** The webview window learned from an inbound message — see `adoptSource`. */
+    private adoptedWindow;
+    private readonly adoptSource;
+    private readonly autoDestroy;
+    /** Watches an adopted window for `closed` — see `watchAdoptedWindow`. */
+    private adoptedPoll?;
+    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: FrameLike, options?: CaptelloWebviewOptions);
+    /**
+     * Tears the client down once the bound iframe leaves the document.
+     *
+     * Observes the whole document subtree because the iframe usually goes away with an
+     * ancestor (a panel or modal being emptied), which produces no mutation on the
+     * iframe's own parent. `isConnected` is the actual test, so removal at any depth
+     * counts; the observer only bothers checking when a mutation actually removed
+     * something.
+     */
+    /**
+     * Tears the client down once an adopted webview window goes away.
+     *
+     * With no iframe element there is nothing to observe in the DOM, but a removed
+     * iframe's `contentWindow` reports `closed === true` — and `closed` is readable
+     * cross-origin — so a cheap periodic check is enough. Verified in Chromium against a
+     * genuinely cross-origin iframe.
+     */
+    private watchAdoptedWindow;
+    private watchForFrameRemoval;
+    /** `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 form fields from a submission body, transcription items, or both. */
+    prefill(data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    }): void;
+    /**
+     * Answer the webview's transcribe requests (its transcribe button — shown when the
+     * embed URL sets `showTranscribeButton` — sends `transcribe_scanner_request` when
+     * pressed).
+     *
+     * The handler receives the request (`element_id`, `image_urls`,
+     * `draft_submission_token`) and a {@link TranscribeScannerReply}, and answers in
+     * whichever style suits the transcription code. Either way the result is posted for
+     * you — the host never builds or stringifies a `transcribe_scanner_result`.
+     *
+     * **Return the fields** when the work is promise-based:
+     *
+     * ```js
+     * webview.onTranscribeScannerRequest(async ({ image_urls }) => {
+     *   const fields = await transcribe(image_urls);
+     *   return { fields, submissionType: "ocr_transcription" };
+     * });
+     * ```
+     *
+     * **Or answer through `reply`** when it isn't — a callback-style AJAX wrapper, an
+     * event bus, a method that returns `void`. Hand `reply` to whatever does the work:
+     *
+     * ```js
+     * webview.onTranscribeScannerRequest((request, reply) => {
+     *   transcribeService(request.image_urls,
+     *     (fields) => reply.resolve({ fields, submissionType: "ocr_transcription" }),
+     *     () => reply.reject("Transcription failed."),
+     *   );
+     * });
+     * ```
+     *
+     * A handler that returns nothing is taken to own the reply, so the request stays
+     * open until `reply` answers it. A thrown error / rejected promise is sent as an
+     * error result; an `Error`'s `message` is shown to the user by the webview, so throw
+     * display-ready messages. The first answer wins — a second is ignored.
+     *
+     * Returns an unsubscribe function.
+     */
+    onTranscribeScannerRequest(handler: TranscribeScannerRequestHandler): Unsubscribe;
+    /**
+     * Answer a transcribe request **later**, from code that can't hand back a promise
+     * — a callback-style AJAX wrapper, an event bus, a method that returns `void`.
+     *
+     * Pair it with a plain `on(OutboundMessageType.TranscribeScannerRequest, ...)`
+     * subscription: hold on to the request (or just its `request_id`), and call this
+     * once the transcription lands. Prefer {@link onTranscribeScannerRequest} when
+     * your transcription code is already promise-based — it does this for you.
+     *
+     * Accepts the request message itself or its bare `request_id`. The reply is
+     * `JSON.stringify`'d and posted immediately, bypassing the ready-queue: a received
+     * request already proves the webview is live and listening. Replying after
+     * {@link destroy}, or after the iframe is detached, is a silent no-op — by then
+     * there is nobody left to answer, and the webview times its own button out.
+     *
+     * @example
+     * webview.on(OutboundMessageType.TranscribeScannerRequest, (request) => {
+     *   ajax.send("Scanner", "transcribe", { image_urls: request.image_urls },
+     *     (res) => webview.resolveTranscribeScannerRequest(request, {
+     *       fields: res.fields,
+     *       submissionType: "ocr_transcription",
+     *     }),
+     *     () => webview.rejectTranscribeScannerRequest(request, "Transcription failed."),
+     *   );
+     * });
+     */
+    resolveTranscribeScannerRequest(request: TranscribeScannerRequestRef, data: TranscribeScannerResultData): void;
+    /**
+     * Fail a transcribe request answered via
+     * {@link resolveTranscribeScannerRequest}'s deferred flow. `error` is shown to the
+     * user verbatim by the webview, so pass display-ready text.
+     *
+     * Same delivery semantics as {@link resolveTranscribeScannerRequest}: posted
+     * immediately, and a no-op once the client is destroyed or the iframe detached.
+     */
+    rejectTranscribeScannerRequest(request: TranscribeScannerRequestRef, error: string): void;
+    /**
+     * Posts a `transcribe_scanner_result`, bypassing the ready-queue. A received
+     * request proves the webview is live and listening, even if this client attached
+     * after form load and never saw `form_load_complete`; queuing here could stall the
+     * reply forever while the webview's button sits in its pending state until timeout.
+     */
+    private sendTranscribeScannerResult;
+    /** Remove the `message` listener and drop all subscriptions. Idempotent. */
+    destroy(): void;
+    private handleMessage;
+}
+
+export { type AddressSubmissionValue as A, type BusinessCardValue as B, type CaptelloWebviewOptions as C, type DraftSubmissionData as D, parseOutboundMessage as E, type FrameLike as F, type InboundMessage as I, type NameSubmissionValue as N, OutboundMessageType as O, type PrefillInfoItem as P, type SubmissionBody as S, type TranscribeScannerRequestHandler as T, type Unsubscribe as U, type ValidationTarget as V, type OutboundMessageMap as a, SubmissionError as b, SubmissionTimeoutError as c, type OutboundMessage as d, type SubmissionPrefill as e, CaptelloWebview as f, type AnyOutboundListener as g, type AttachOptions as h, type AttachmentValue as i, FormElementType as j, InboundMessageType as k, type OrderCheckboxSubmissionData as l, type OrderRadioSubmissionData as m, type OutboundListener as n, type SubmissionPrefillDataItem as o, type SubmissionQuestionData as p, type TranscribeScannerReply as q, type TranscribeScannerRequestMessage as r, type TranscribeScannerRequestRef as s, type TranscribeScannerResultData as t, type TranscribeScannerResultMessage as u, type TranscribedScannerField as v, type VisibleSubmissionDataItem as w, type VisibleSubmissionElementType as x, type VisibleSubmissionElementValueMap as y, attach as z };