@captello/ulc-webview-sdk 1.1.0 → 1.2.0

package/dist/{client-cZpygJTD.d.ts → client-CAMlFA8s.d.ts}

@@ -202,7 +202,14 @@ declare enum OutboundMessageType {
     /** 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"
+    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}.
@@ -306,8 +313,29 @@ interface ConnexionsProfileRedirectMessage {
 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;
+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;
@@ -323,9 +351,18 @@ declare enum InboundMessageType {
     /** Switch the current submission into draft-update mode. */
     UpdateDraft = "update_draft",
     /** Run validation against a target field (or the whole form). */
-    TriggerValidation = "trigger_validation"
+    TriggerValidation = "trigger_validation",
+    /** Answer to an outbound {@link OutboundMessageType.TranscribeScannerRequest}. */
+    TranscribeScannerResult = "transcribe_scanner_result"
 }
-/** Shape selector for {@link InboundMessageType.FormPrefill} payloads. */
+/**
+ * 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"
 }
@@ -365,8 +402,48 @@ interface PrefillMessage {
         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;
+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.
@@ -380,8 +457,84 @@ declare function parseOutboundMessage(data: unknown): OutboundMessage | null;
 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;
+/**
+ * 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.
@@ -401,7 +554,11 @@ 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"`), e.g. `new URL(embedUrl).origin`.
+     * `"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.
@@ -429,8 +586,90 @@ interface CaptelloWebviewOptions {
      * 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;
 }
-type ElementOrFrame = HTMLIFrameElement | {
+/** 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;
 };
 /**
@@ -464,6 +703,14 @@ type ElementOrFrame = HTMLIFrameElement | {
  */
 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;
@@ -476,7 +723,26 @@ declare class CaptelloWebview {
     private ready;
     /** Messages sent before ready, flushed in order on load. */
     private readonly outbox;
-    constructor(frame: ElementOrFrame, options?: CaptelloWebviewOptions);
+    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;
     /**
@@ -542,9 +808,91 @@ declare class CaptelloWebview {
         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, FormElementType as F, type InboundMessage as I, type NameSubmissionValue as N, 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, type SubmissionPrefill as e, CaptelloWebview as f, type AnyOutboundListener as g, type AttachmentValue as h, InboundMessageType as i, type OrderCheckboxSubmissionData as j, type OrderRadioSubmissionData as k, type OutboundListener as l, type SubmissionPrefillDataItem as m, type SubmissionQuestionData as n, type VisibleSubmissionDataItem as o, type VisibleSubmissionElementType as p, type VisibleSubmissionElementValueMap as q, parseOutboundMessage as r };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AddressSubmissionValue, g as AnyOutboundListener, h as AttachmentValue, B as BusinessCardValue, f as CaptelloWebview, C as CaptelloWebviewOptions, D as DraftSubmissionData, F as FormElementType, I as InboundMessage, i as InboundMessageType, N as NameSubmissionValue, j as OrderCheckboxSubmissionData, k as OrderRadioSubmissionData, l as OutboundListener, d as OutboundMessage, a as OutboundMessageMap, O as OutboundMessageType, P as PrefillInfoItem, S as SubmissionBody, b as SubmissionError, e as SubmissionPrefill, m as SubmissionPrefillDataItem, n as SubmissionQuestionData, c as SubmissionTimeoutError, U as Unsubscribe, V as ValidationTarget, o as VisibleSubmissionDataItem, p as VisibleSubmissionElementType, q as VisibleSubmissionElementValueMap, r as parseOutboundMessage } from './client-cZpygJTD.js';
+export { A as AddressSubmissionValue, g as AnyOutboundListener, h as AttachOptions, i as AttachmentValue, B as BusinessCardValue, f as CaptelloWebview, C as CaptelloWebviewOptions, D as DraftSubmissionData, j as FormElementType, F as FrameLike, I as InboundMessage, k as InboundMessageType, N as NameSubmissionValue, l as OrderCheckboxSubmissionData, m as OrderRadioSubmissionData, n as OutboundListener, d as OutboundMessage, a as OutboundMessageMap, O as OutboundMessageType, P as PrefillInfoItem, S as SubmissionBody, b as SubmissionError, e as SubmissionPrefill, o as SubmissionPrefillDataItem, p as SubmissionQuestionData, c as SubmissionTimeoutError, q as TranscribeScannerReply, T as TranscribeScannerRequestHandler, r as TranscribeScannerRequestMessage, s as TranscribeScannerRequestRef, t as TranscribeScannerResultData, u as TranscribeScannerResultMessage, v as TranscribedScannerField, U as Unsubscribe, V as ValidationTarget, w as VisibleSubmissionDataItem, x as VisibleSubmissionElementType, y as VisibleSubmissionElementValueMap, z as attach, E as parseOutboundMessage } from './client-CAMlFA8s.js';
 
 /**
  * Builder for the Captello capture webview embed URL.
@@ -28,7 +28,14 @@ declare enum EmbedParam {
     /** Edit mode read-only: locks email-mapped and invitation-code elements. */
     Emro = "emro",
     /** Context for filtering form-fill actions (e.g. MMP outbound/inbound/notes). */
-    UseIn = "useIn"
+    UseIn = "useIn",
+    /**
+     * Show the transcribe button: the form renders a button that emits a
+     * `host_processing_request` with `processing_type: "transcribe_scanner_request"`.
+     * Only enable it when the host answers those requests (e.g. via
+     * `CaptelloWebview.onProcessingRequest`).
+     */
+    ShowTranscribeButton = "show_transcribe_button"
 }
 /** Form render mode (the webview's `FormMode`). */
 declare enum FormMode {
@@ -100,6 +107,13 @@ interface EmbedUrlOptions {
     connexionsEmbedMode?: boolean;
     /** Edit mode read-only. */
     emro?: boolean;
+    /**
+     * Show the transcribe button in the form (emits `host_processing_request` with
+     * `processing_type: "transcribe_scanner_request"` when pressed). Enable only when
+     * the host answers those requests (e.g. via `CaptelloWebview.onProcessingRequest`) —
+     * otherwise the button times out with an error for the user.
+     */
+    showTranscribeButton?: boolean;
     /**
      * Extra query params to append verbatim (e.g. prospect tracking params the
      * webview forwards on submit). Values are stringified; `undefined`/`null` skipped.

package/dist/index.js

@@ -1,5 +1,5 @@
-export { ActionButtonPosition, EmbedParam, FormMode, Language, LauncherType, buildEmbedUrl } from './chunk-4E7OW4RJ.js';
-export { CaptelloWebview, InboundMessageType, OutboundMessageType, SubmissionError, SubmissionTimeoutError, parseOutboundMessage } from './chunk-UUEUW2WL.js';
+export { ActionButtonPosition, EmbedParam, FormMode, Language, LauncherType, buildEmbedUrl } from './chunk-ZX4AKPWF.js';
+export { CaptelloWebview, InboundMessageType, OutboundMessageType, SubmissionError, SubmissionTimeoutError, attach, parseOutboundMessage } from './chunk-ZPVXZW2B.js';
 
 // src/submission-data.ts
 var FormElementType = /* @__PURE__ */ ((FormElementType2) => {

package/dist/promises.d.ts

@@ -1,5 +1,5 @@
-import { C as CaptelloWebviewOptions, S as SubmissionBody, O as OutboundMessageType, a as OutboundMessageMap } from './client-cZpygJTD.js';
-export { b as SubmissionError, c as SubmissionTimeoutError } from './client-cZpygJTD.js';
+import { C as CaptelloWebviewOptions, F as FrameLike, S as SubmissionBody, O as OutboundMessageType, a as OutboundMessageMap } from './client-CAMlFA8s.js';
+export { b as SubmissionError, c as SubmissionTimeoutError } from './client-CAMlFA8s.js';
 
 /**
  * Promise-based, one-shot helpers for imperative flows — `@captello/ulc-webview-sdk/promises`.
@@ -17,9 +17,7 @@ export { b as SubmissionError, c as SubmissionTimeoutError } from './client-cZpy
  */
 
 /** Frame accepted by the helpers — an `<iframe>` or anything exposing `contentWindow`. */
-type ElementOrFrame = HTMLIFrameElement | {
-    contentWindow: Window | null;
-};
+type ElementOrFrame = FrameLike;
 /** Options shared by every promise helper. */
 interface WaitOptions extends Pick<CaptelloWebviewOptions, "targetOrigin" | "hostWindow" | "matchSource"> {
     /**

package/dist/promises.js

@@ -1,5 +1,5 @@
-import { CaptelloWebview } from './chunk-UUEUW2WL.js';
-export { SubmissionError, SubmissionTimeoutError } from './chunk-UUEUW2WL.js';
+import { CaptelloWebview } from './chunk-ZPVXZW2B.js';
+export { SubmissionError, SubmissionTimeoutError } from './chunk-ZPVXZW2B.js';
 
 // src/promises.ts
 var DEFAULT_TIMEOUT_MS = 6e4;

package/dist/promises.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/promises.ts"],"names":[],"mappings":";;;;AAkCA,IAAM,kBAAA,GAAqB,GAAA;AAGpB,IAAM,mBAAA,GAAN,cAAkC,KAAA,CAAM;AAAA,EAC3C,WAAA,CACoB,aACA,SAAA,EAClB;AACE,IAAA,KAAA,CAAM,CAAA,gBAAA,EAAmB,SAAS,CAAA,gBAAA,EAAmB,WAAW,CAAA,4BAAA,CAA8B,CAAA;AAH9E,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AACA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,qBAAA;AAAA,EAChB;AACJ;AAEA,SAAS,cAAc,OAAA,EAA8C;AACjE,EAAA,OAAO;AAAA,IACH,cAAc,OAAA,CAAQ,YAAA;AAAA,IACtB,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,aAAa,OAAA,CAAQ,WAAA;AAAA;AAAA;AAAA,IAGrB,eAAA,EAAiB;AAAA,GACrB;AACJ;AASO,SAAS,cAAA,CACZ,KAAA,EACA,IAAA,EACA,OAAA,GAAuB,EAAC,EACM;AAC9B,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,kBAAA;AACvC,EAAA,OAAO,IAAI,OAAA,CAA+B,CAAC,OAAA,EAAS,MAAA,KAAW;AAC3D,IAAA,MAAM,SAAS,IAAI,eAAA,CAAgB,KAAA,EAAO,aAAA,CAAc,OAAO,CAAC,CAAA;AAChE,IAAA,IAAI,KAAA;AAEJ,IAAA,MAAM,MAAA,GAAS,CAAC,EAAA,KAAmB;AAC/B,MAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAC3C,MAAA,MAAA,CAAO,OAAA,EAAQ;AACf,MAAA,EAAA,EAAG;AAAA,IACP,CAAA;AAEA,IAAA,MAAA,CAAO,IAAA,CAAK,MAAM,CAAC,OAAA,KAAY,OAAO,MAAM,OAAA,CAAQ,OAAO,CAAC,CAAC,CAAA;AAE7D,IAAA,IAAI,SAAA,GAAY,CAAA,IAAK,SAAA,KAAc,QAAA,EAAU;AACzC,MAAA,KAAA,GAAQ,UAAA,CAAW,MAAM,MAAA,CAAO,MAAM,MAAA,CAAO,IAAI,mBAAA,CAAoB,IAAA,EAAM,SAAS,CAAC,CAAC,CAAA,EAAG,SAAS,CAAA;AAAA,IACtG;AAAA,EACJ,CAAC,CAAA;AACL;AAUO,SAAS,eAAA,CAAgB,KAAA,EAAuB,OAAA,GAAuB,EAAC,EAAkB;AAC7F,EAAA,OAAO,eAAe,KAAA,EAAA,oBAAA,yBAA6C,OAAO,CAAA,CAAE,IAAA,CAAK,MAAM,MAAS,CAAA;AACpG;AAkBO,SAAS,UAAA,CAAW,KAAA,EAAuB,OAAA,GAAuB,EAAC,EAA4B;AAClG,EAAA,MAAM,SAAS,IAAI,eAAA,CAAgB,KAAA,EAAO,aAAA,CAAc,OAAO,CAAC,CAAA;AAChE,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,kBAAA;AACvC,EAAA,OAAO,MAAA,CAAO,cAAc,SAAS,CAAA,CAAE,QAAQ,MAAM,MAAA,CAAO,SAAS,CAAA;AACzE","file":"promises.js","sourcesContent":["/**\n * Promise-based, one-shot helpers for imperative flows — `@captello/ulc-webview-sdk/promises`.\n *\n * Where {@link CaptelloWebview} is a long-lived client you subscribe to, these are\n * fire-once-and-await utilities that take an iframe directly: create a short-lived\n * client internally, wait for the relevant message, then tear it down. Ideal for\n * `await`-style code (e.g. \"submit and get the body\", \"wait until the form loads\").\n *\n * @example\n * import { submitForm, waitForFormLoad } from \"@captello/ulc-webview-sdk/promises\";\n *\n * await waitForFormLoad(iframe, { targetOrigin });\n * const body = await submitForm(iframe, { targetOrigin });\n */\n\nimport { CaptelloWebview } from \"./client\";\nimport type { CaptelloWebviewOptions } from \"./client\";\nimport { OutboundMessageType } from \"./messages\";\nimport type { OutboundMessageMap, SubmissionBody } from \"./messages\";\n\nexport { SubmissionError, SubmissionTimeoutError } from \"./client\";\n\n/** Frame accepted by the helpers — an `<iframe>` or anything exposing `contentWindow`. */\ntype ElementOrFrame = HTMLIFrameElement | { contentWindow: Window | null };\n\n/** Options shared by every promise helper. */\nexport interface WaitOptions extends Pick<CaptelloWebviewOptions, \"targetOrigin\" | \"hostWindow\" | \"matchSource\"> {\n    /**\n     * How long to wait before rejecting. Defaults to 60_000ms. Pass `0` or `Infinity`\n     * to wait indefinitely (the caller is then responsible for not leaking the wait).\n     */\n    timeoutMs?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 60_000;\n\n/** Rejection reason from {@link waitForMessage} / {@link waitForFormLoad} on timeout. */\nexport class MessageTimeoutError extends Error {\n    constructor(\n        public readonly messageType: string,\n        public readonly timeoutMs: number,\n    ) {\n        super(`Timed out after ${timeoutMs}ms waiting for \"${messageType}\" from the Captello webview.`);\n        this.name = \"MessageTimeoutError\";\n    }\n}\n\nfunction clientOptions(options: WaitOptions): CaptelloWebviewOptions {\n    return {\n        targetOrigin: options.targetOrigin,\n        hostWindow: options.hostWindow,\n        matchSource: options.matchSource,\n        // One-shot helpers act on a form assumed already loaded; never buffer their\n        // sends waiting for a form_load_complete that may have already fired.\n        queueUntilReady: false,\n    };\n}\n\n/**\n * Resolves with the next outbound message of `type` from the webview, or rejects with\n * a {@link MessageTimeoutError} if none arrives within the timeout. The internal\n * listener is always removed before settling.\n *\n * @example const msg = await waitForMessage(iframe, OutboundMessageType.SubmissionBody, { targetOrigin });\n */\nexport function waitForMessage<T extends OutboundMessageType>(\n    frame: ElementOrFrame,\n    type: T,\n    options: WaitOptions = {},\n): Promise<OutboundMessageMap[T]> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    return new Promise<OutboundMessageMap[T]>((resolve, reject) => {\n        const client = new CaptelloWebview(frame, clientOptions(options));\n        let timer: ReturnType<typeof setTimeout> | undefined;\n\n        const settle = (fn: () => void) => {\n            if (timer !== undefined) clearTimeout(timer);\n            client.destroy();\n            fn();\n        };\n\n        client.once(type, (message) => settle(() => resolve(message)));\n\n        if (timeoutMs > 0 && timeoutMs !== Infinity) {\n            timer = setTimeout(() => settle(() => reject(new MessageTimeoutError(type, timeoutMs))), timeoutMs);\n        }\n    });\n}\n\n/**\n * Resolves once the webview reports `form_load_complete`, or rejects with a\n * {@link MessageTimeoutError} on timeout.\n *\n * Note: this only catches a *future* load event. If the form may have already loaded\n * before you call this (e.g. you attach late), prefer subscribing with a long-lived\n * {@link CaptelloWebview} created before the iframe navigates.\n */\nexport function waitForFormLoad(frame: ElementOrFrame, options: WaitOptions = {}): Promise<void> {\n    return waitForMessage(frame, OutboundMessageType.FormLoadComplete, options).then(() => undefined);\n}\n\n/**\n * Submits the form and awaits the outcome: resolves with the {@link SubmissionBody} on\n * `submission_body`, rejects with a `SubmissionError` (translated message) on\n * `form_error_message`, or a `SubmissionTimeoutError` if neither arrives in time.\n *\n * Standalone equivalent of {@link CaptelloWebview.submitAndWait} for code that doesn't\n * hold a long-lived client — it creates one, submits, and tears it down.\n *\n * @example\n * try {\n *   const body = await submitForm(iframeRef.current!, { targetOrigin });\n *   await persist(body);\n * } catch (err) {\n *   if (err instanceof SubmissionError) showToast(err.message);\n * }\n */\nexport function submitForm(frame: ElementOrFrame, options: WaitOptions = {}): Promise<SubmissionBody> {\n    const client = new CaptelloWebview(frame, clientOptions(options));\n    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    return client.submitAndWait(timeoutMs).finally(() => client.destroy());\n}\n"]}
+{"version":3,"sources":["../src/promises.ts"],"names":[],"mappings":";;;;AAkCA,IAAM,kBAAA,GAAqB,GAAA;AAGpB,IAAM,mBAAA,GAAN,cAAkC,KAAA,CAAM;AAAA,EAC3C,WAAA,CACoB,aACA,SAAA,EAClB;AACE,IAAA,KAAA,CAAM,CAAA,gBAAA,EAAmB,SAAS,CAAA,gBAAA,EAAmB,WAAW,CAAA,4BAAA,CAA8B,CAAA;AAH9E,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AACA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAGhB,IAAA,IAAA,CAAK,IAAA,GAAO,qBAAA;AAAA,EAChB;AACJ;AAEA,SAAS,cAAc,OAAA,EAA8C;AACjE,EAAA,OAAO;AAAA,IACH,cAAc,OAAA,CAAQ,YAAA;AAAA,IACtB,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,aAAa,OAAA,CAAQ,WAAA;AAAA;AAAA;AAAA,IAGrB,eAAA,EAAiB;AAAA,GACrB;AACJ;AASO,SAAS,cAAA,CACZ,KAAA,EACA,IAAA,EACA,OAAA,GAAuB,EAAC,EACM;AAC9B,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,kBAAA;AACvC,EAAA,OAAO,IAAI,OAAA,CAA+B,CAAC,OAAA,EAAS,MAAA,KAAW;AAC3D,IAAA,MAAM,SAAS,IAAI,eAAA,CAAgB,KAAA,EAAO,aAAA,CAAc,OAAO,CAAC,CAAA;AAChE,IAAA,IAAI,KAAA;AAEJ,IAAA,MAAM,MAAA,GAAS,CAAC,EAAA,KAAmB;AAC/B,MAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAC3C,MAAA,MAAA,CAAO,OAAA,EAAQ;AACf,MAAA,EAAA,EAAG;AAAA,IACP,CAAA;AAEA,IAAA,MAAA,CAAO,IAAA,CAAK,MAAM,CAAC,OAAA,KAAY,OAAO,MAAM,OAAA,CAAQ,OAAO,CAAC,CAAC,CAAA;AAE7D,IAAA,IAAI,SAAA,GAAY,CAAA,IAAK,SAAA,KAAc,QAAA,EAAU;AACzC,MAAA,KAAA,GAAQ,UAAA,CAAW,MAAM,MAAA,CAAO,MAAM,MAAA,CAAO,IAAI,mBAAA,CAAoB,IAAA,EAAM,SAAS,CAAC,CAAC,CAAA,EAAG,SAAS,CAAA;AAAA,IACtG;AAAA,EACJ,CAAC,CAAA;AACL;AAUO,SAAS,eAAA,CAAgB,KAAA,EAAuB,OAAA,GAAuB,EAAC,EAAkB;AAC7F,EAAA,OAAO,eAAe,KAAA,EAAA,oBAAA,yBAA6C,OAAO,CAAA,CAAE,IAAA,CAAK,MAAM,MAAS,CAAA;AACpG;AAkBO,SAAS,UAAA,CAAW,KAAA,EAAuB,OAAA,GAAuB,EAAC,EAA4B;AAClG,EAAA,MAAM,SAAS,IAAI,eAAA,CAAgB,KAAA,EAAO,aAAA,CAAc,OAAO,CAAC,CAAA;AAChE,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,kBAAA;AACvC,EAAA,OAAO,MAAA,CAAO,cAAc,SAAS,CAAA,CAAE,QAAQ,MAAM,MAAA,CAAO,SAAS,CAAA;AACzE","file":"promises.js","sourcesContent":["/**\n * Promise-based, one-shot helpers for imperative flows — `@captello/ulc-webview-sdk/promises`.\n *\n * Where {@link CaptelloWebview} is a long-lived client you subscribe to, these are\n * fire-once-and-await utilities that take an iframe directly: create a short-lived\n * client internally, wait for the relevant message, then tear it down. Ideal for\n * `await`-style code (e.g. \"submit and get the body\", \"wait until the form loads\").\n *\n * @example\n * import { submitForm, waitForFormLoad } from \"@captello/ulc-webview-sdk/promises\";\n *\n * await waitForFormLoad(iframe, { targetOrigin });\n * const body = await submitForm(iframe, { targetOrigin });\n */\n\nimport { CaptelloWebview } from \"./client\";\nimport type { CaptelloWebviewOptions, FrameLike } from \"./client\";\nimport { OutboundMessageType } from \"./messages\";\nimport type { OutboundMessageMap, SubmissionBody } from \"./messages\";\n\nexport { SubmissionError, SubmissionTimeoutError } from \"./client\";\n\n/** Frame accepted by the helpers — an `<iframe>` or anything exposing `contentWindow`. */\ntype ElementOrFrame = FrameLike;\n\n/** Options shared by every promise helper. */\nexport interface WaitOptions extends Pick<CaptelloWebviewOptions, \"targetOrigin\" | \"hostWindow\" | \"matchSource\"> {\n    /**\n     * How long to wait before rejecting. Defaults to 60_000ms. Pass `0` or `Infinity`\n     * to wait indefinitely (the caller is then responsible for not leaking the wait).\n     */\n    timeoutMs?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 60_000;\n\n/** Rejection reason from {@link waitForMessage} / {@link waitForFormLoad} on timeout. */\nexport class MessageTimeoutError extends Error {\n    constructor(\n        public readonly messageType: string,\n        public readonly timeoutMs: number,\n    ) {\n        super(`Timed out after ${timeoutMs}ms waiting for \"${messageType}\" from the Captello webview.`);\n        this.name = \"MessageTimeoutError\";\n    }\n}\n\nfunction clientOptions(options: WaitOptions): CaptelloWebviewOptions {\n    return {\n        targetOrigin: options.targetOrigin,\n        hostWindow: options.hostWindow,\n        matchSource: options.matchSource,\n        // One-shot helpers act on a form assumed already loaded; never buffer their\n        // sends waiting for a form_load_complete that may have already fired.\n        queueUntilReady: false,\n    };\n}\n\n/**\n * Resolves with the next outbound message of `type` from the webview, or rejects with\n * a {@link MessageTimeoutError} if none arrives within the timeout. The internal\n * listener is always removed before settling.\n *\n * @example const msg = await waitForMessage(iframe, OutboundMessageType.SubmissionBody, { targetOrigin });\n */\nexport function waitForMessage<T extends OutboundMessageType>(\n    frame: ElementOrFrame,\n    type: T,\n    options: WaitOptions = {},\n): Promise<OutboundMessageMap[T]> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    return new Promise<OutboundMessageMap[T]>((resolve, reject) => {\n        const client = new CaptelloWebview(frame, clientOptions(options));\n        let timer: ReturnType<typeof setTimeout> | undefined;\n\n        const settle = (fn: () => void) => {\n            if (timer !== undefined) clearTimeout(timer);\n            client.destroy();\n            fn();\n        };\n\n        client.once(type, (message) => settle(() => resolve(message)));\n\n        if (timeoutMs > 0 && timeoutMs !== Infinity) {\n            timer = setTimeout(() => settle(() => reject(new MessageTimeoutError(type, timeoutMs))), timeoutMs);\n        }\n    });\n}\n\n/**\n * Resolves once the webview reports `form_load_complete`, or rejects with a\n * {@link MessageTimeoutError} on timeout.\n *\n * Note: this only catches a *future* load event. If the form may have already loaded\n * before you call this (e.g. you attach late), prefer subscribing with a long-lived\n * {@link CaptelloWebview} created before the iframe navigates.\n */\nexport function waitForFormLoad(frame: ElementOrFrame, options: WaitOptions = {}): Promise<void> {\n    return waitForMessage(frame, OutboundMessageType.FormLoadComplete, options).then(() => undefined);\n}\n\n/**\n * Submits the form and awaits the outcome: resolves with the {@link SubmissionBody} on\n * `submission_body`, rejects with a `SubmissionError` (translated message) on\n * `form_error_message`, or a `SubmissionTimeoutError` if neither arrives in time.\n *\n * Standalone equivalent of {@link CaptelloWebview.submitAndWait} for code that doesn't\n * hold a long-lived client — it creates one, submits, and tears it down.\n *\n * @example\n * try {\n *   const body = await submitForm(iframeRef.current!, { targetOrigin });\n *   await persist(body);\n * } catch (err) {\n *   if (err instanceof SubmissionError) showToast(err.message);\n * }\n */\nexport function submitForm(frame: ElementOrFrame, options: WaitOptions = {}): Promise<SubmissionBody> {\n    const client = new CaptelloWebview(frame, clientOptions(options));\n    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    return client.submitAndWait(timeoutMs).finally(() => client.destroy());\n}\n"]}

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { CSSProperties, IframeHTMLAttributes, ReactNode, RefCallback } from 'react';
-import { C as CaptelloWebviewOptions, S as SubmissionBody, d as OutboundMessage, e as SubmissionPrefill, P as PrefillInfoItem, f as CaptelloWebview, V as ValidationTarget } from './client-cZpygJTD.js';
-export { b as SubmissionError, c as SubmissionTimeoutError, U as Unsubscribe } from './client-cZpygJTD.js';
+import { C as CaptelloWebviewOptions, S as SubmissionBody, d as OutboundMessage, e as SubmissionPrefill, P as PrefillInfoItem, T as TranscribeScannerRequestHandler, f as CaptelloWebview, V as ValidationTarget } from './client-CAMlFA8s.js';
+export { b as SubmissionError, c as SubmissionTimeoutError, U as Unsubscribe } from './client-CAMlFA8s.js';
 import { EmbedUrlOptions } from './index.js';
 
 /**
@@ -80,6 +80,16 @@ interface UseCaptelloWebviewOptions extends Omit<CaptelloWebviewOptions, "target
      * defaultFormValues={{ info: [{ ll_field_unique_identifier: "Email", value: user.email }] }}
      */
     defaultFormValues?: DefaultFormValues;
+    /**
+     * Answer the form's transcribe requests (its transcribe button, shown when the
+     * embed URL sets `showTranscribeButton`). Same semantics as
+     * {@link CaptelloWebview.onTranscribeScannerRequest}: return the fields (a promise
+     * is fine) and they are sent back as the result, or answer through the `reply`
+     * second argument when the work is callback-style; a thrown `Error`'s message is
+     * shown to the user. Must be set from the first render (it is wired when the iframe
+     * attaches); the latest function is always the one invoked, so inline closures are fine.
+     */
+    onTranscribeScannerRequest?: TranscribeScannerRequestHandler;
 }
 /** Readiness of the embedded form. */
 type CaptelloWebviewStatus = "loading" | "ready" | "error";

package/dist/react.js

@@ -1,6 +1,6 @@
-import { buildEmbedUrl } from './chunk-4E7OW4RJ.js';
-import { CaptelloWebview, OutboundMessageType } from './chunk-UUEUW2WL.js';
-export { CaptelloWebview, SubmissionError, SubmissionTimeoutError } from './chunk-UUEUW2WL.js';
+import { buildEmbedUrl } from './chunk-ZX4AKPWF.js';
+import { CaptelloWebview, OutboundMessageType } from './chunk-ZPVXZW2B.js';
+export { CaptelloWebview, SubmissionError, SubmissionTimeoutError } from './chunk-ZPVXZW2B.js';
 import { forwardRef, useState, useRef, useCallback, useImperativeHandle, useEffect } from 'react';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
@@ -77,6 +77,17 @@ function useCaptelloWebview(options) {
           })
         );
       }
+      if (optionsRef.current.onTranscribeScannerRequest) {
+        offs.push(
+          client.onTranscribeScannerRequest((request, reply) => {
+            const handler = optionsRef.current.onTranscribeScannerRequest;
+            if (!handler) {
+              throw new Error("Transcription failed.");
+            }
+            return handler(request, reply);
+          })
+        );
+      }
       teardown.current = () => {
         for (const off of offs) off();
         client.destroy();