@captello/ulc-webview-sdk 1.1.0 → 1.3.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/embedded-app.d.ts

@@ -0,0 +1,93 @@
+import { F as FrameLike, U as Unsubscribe } from './client-CAMlFA8s.js';
+import { M as MobileHostRequest, a as MobileHostRequestType, b as MobileHostRequestMap, c as MobileHostResponse, S as ScannedPerson } from './mobile-app-protocol-Bt-UDbu5.js';
+export { A as AuthTokenMessage, d as MobileHostResponseMap, e as MobileHostResponseType, f as ScannerClosedMessage, g as ScannerResultMessage, p as parseMobileHostRequest, h as parseMobileHostResponse } from './mobile-app-protocol-Bt-UDbu5.js';
+
+/**
+ * `@captello/ulc-webview-sdk/embedded-app` — for the **Captello mobile app** (or any
+ * host playing its role) that embeds an application in an iframe and serves it native
+ * services over `postMessage`.
+ *
+ * {@link EmbeddedAppClient} wraps the iframe: it delivers the embedded application's
+ * requests to typed handlers and posts the app's responses back. The embedded
+ * application's own side is `MobileHostClient` (`@captello/ulc-webview-sdk/mobile-host`).
+ *
+ * Not to be confused with `CaptelloWebview`, which wraps an iframe of the *capture
+ * webview* — a different protocol (JSON strings, snake_case types).
+ *
+ * @example
+ * import { EmbeddedAppClient, MobileHostRequestType } from "@captello/ulc-webview-sdk/embedded-app";
+ *
+ * const embedded = new EmbeddedAppClient(iframe, { targetOrigin: new URL(iframe.src).origin });
+ * embedded.onRequest(MobileHostRequestType.RequestAuthToken, async () => {
+ *     embedded.sendAuthToken(await mintMagicToken());
+ * });
+ * embedded.onRequest(MobileHostRequestType.OpenScanner, async () => {
+ *     for (const person of await scan()) embedded.sendScannerResult(person);
+ *     embedded.sendScannerClosed();
+ * });
+ */
+
+/** Listener for a specific request type from the embedded application. */
+type MobileHostRequestListener<T extends MobileHostRequestType> = (request: MobileHostRequestMap[T]) => void;
+/** Listener for every request from the embedded application (used by {@link EmbeddedAppClient.onAnyRequest}). */
+type AnyMobileHostRequestListener = (request: MobileHostRequest) => void;
+interface EmbeddedAppClientOptions {
+    /**
+     * Origin to validate incoming requests against and to target outgoing responses.
+     * A full URL is accepted and reduced to its origin.
+     *
+     * Defaults to the iframe's `src` origin, read fresh on every send so a `src` bound
+     * after construction still works. When neither is available the client refuses to
+     * send rather than fall back to `"*"` — a response can carry an auth token, and
+     * `"*"` would hand it to whatever the frame navigated to.
+     */
+    targetOrigin?: string;
+    /** Window to listen on. Defaults to the global `window`. */
+    hostWindow?: Window;
+    /**
+     * Only accept requests whose `event.source` is the bound iframe's window. Defaults
+     * to `true`. Set `false` if the application relays through another window.
+     */
+    matchSource?: boolean;
+}
+/**
+ * Mobile-app-side client for an application embedded in an iframe.
+ *
+ * Attaches a single `message` listener on construction; call {@link destroy} when the
+ * iframe goes away.
+ */
+declare class EmbeddedAppClient {
+    private readonly frame;
+    private readonly hostWindow;
+    private readonly explicitOrigin;
+    private readonly matchSource;
+    private readonly listeners;
+    private readonly anyListeners;
+    private readonly boundHandler;
+    private destroyed;
+    constructor(frame: FrameLike, options?: EmbeddedAppClientOptions);
+    /** Subscribe to one request type. Returns a handle with `unsubscribe()` (also callable). */
+    onRequest<T extends MobileHostRequestType>(type: T, listener: MobileHostRequestListener<T>): Unsubscribe;
+    /** Subscribe to every request. */
+    onAnyRequest(listener: AnyMobileHostRequestListener): Unsubscribe;
+    /**
+     * Post a response into the embedded application. Returns `false` when nothing was
+     * sent: the client is destroyed, the iframe has no window, or no target origin could
+     * be resolved (see {@link EmbeddedAppClientOptions.targetOrigin}).
+     */
+    send(response: MobileHostResponse): boolean;
+    /** Answer a {@link MobileHostRequestType.RequestAuthToken} request. */
+    sendAuthToken(token: string): boolean;
+    /** Post one scanned person of the current scanner session. */
+    sendScannerResult(person: ScannedPerson): boolean;
+    /** Fail the current scanner session with a display-ready message. */
+    sendScannerError(message: string): boolean;
+    /** End the current scanner session; send after the last result, or on cancel. */
+    sendScannerClosed(): boolean;
+    /** Remove the `message` listener and drop every subscription. Safe to call more than once. */
+    destroy(): void;
+    private resolveOrigin;
+    private handleMessage;
+}
+
+export { type AnyMobileHostRequestListener, EmbeddedAppClient, type EmbeddedAppClientOptions, FrameLike, MobileHostRequest, type MobileHostRequestListener, MobileHostRequestMap, MobileHostRequestType, MobileHostResponse, ScannedPerson };

package/dist/embedded-app.js

@@ -0,0 +1,119 @@
+import { makeSubscription, parseMobileHostRequest } from './chunk-XI5MIDBA.js';
+export { MobileHostRequestType, MobileHostResponseType, parseMobileHostRequest, parseMobileHostResponse } from './chunk-XI5MIDBA.js';
+
+// src/embedded-app.ts
+function toOrigin(value) {
+  if (!value) return void 0;
+  if (value === "*") return value;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return void 0;
+  }
+}
+var EmbeddedAppClient = class {
+  constructor(frame, options = {}) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.anyListeners = /* @__PURE__ */ new Set();
+    this.boundHandler = (event) => this.handleMessage(event);
+    this.destroyed = false;
+    if (!frame) {
+      throw new Error("EmbeddedAppClient: a mounted iframe element (or { contentWindow }) is required.");
+    }
+    const hostWindow = options.hostWindow ?? (typeof window !== "undefined" ? window : void 0);
+    if (!hostWindow) {
+      throw new Error(
+        "EmbeddedAppClient: no host window available. Pass `hostWindow` when constructing outside a browser."
+      );
+    }
+    this.frame = frame;
+    this.hostWindow = hostWindow;
+    this.explicitOrigin = toOrigin(options.targetOrigin);
+    this.matchSource = options.matchSource ?? true;
+    this.hostWindow.addEventListener("message", this.boundHandler);
+  }
+  /** Subscribe to one request type. Returns a handle with `unsubscribe()` (also callable). */
+  onRequest(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+    return makeSubscription(() => {
+      set?.delete(listener);
+    });
+  }
+  /** Subscribe to every request. */
+  onAnyRequest(listener) {
+    this.anyListeners.add(listener);
+    return makeSubscription(() => {
+      this.anyListeners.delete(listener);
+    });
+  }
+  /**
+   * Post a response into the embedded application. Returns `false` when nothing was
+   * sent: the client is destroyed, the iframe has no window, or no target origin could
+   * be resolved (see {@link EmbeddedAppClientOptions.targetOrigin}).
+   */
+  send(response) {
+    if (this.destroyed) return false;
+    const target = this.frame.contentWindow;
+    const origin = this.resolveOrigin();
+    if (!target || !origin) return false;
+    target.postMessage(response, origin);
+    return true;
+  }
+  /** Answer a {@link MobileHostRequestType.RequestAuthToken} request. */
+  sendAuthToken(token) {
+    return this.send({ type: "AUTH_TOKEN" /* AuthToken */, token });
+  }
+  /** Post one scanned person of the current scanner session. */
+  sendScannerResult(person) {
+    return this.send({
+      type: "ULC_FORM_SCANNER_RESULT" /* ScannerResult */,
+      badgeId: person.badgeId,
+      result: person.fields
+    });
+  }
+  /** Fail the current scanner session with a display-ready message. */
+  sendScannerError(message) {
+    return this.send({ type: "ULC_FORM_SCANNER_RESULT" /* ScannerResult */, message });
+  }
+  /** End the current scanner session; send after the last result, or on cancel. */
+  sendScannerClosed() {
+    return this.send({ type: "ULC_FORM_SCANNER_CLOSED" /* ScannerClosed */ });
+  }
+  /** Remove the `message` listener and drop every subscription. Safe to call more than once. */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.hostWindow.removeEventListener("message", this.boundHandler);
+    this.listeners.clear();
+    this.anyListeners.clear();
+  }
+  resolveOrigin() {
+    if (this.explicitOrigin) return this.explicitOrigin;
+    const src = "src" in this.frame ? this.frame.src : void 0;
+    return toOrigin(src);
+  }
+  handleMessage(event) {
+    if (this.matchSource && event.source !== this.frame.contentWindow) return;
+    const origin = this.resolveOrigin();
+    if (origin && origin !== "*" && event.origin !== origin) return;
+    const request = parseMobileHostRequest(event.data);
+    if (!request) return;
+    for (const listener of Array.from(this.anyListeners)) {
+      listener(request);
+    }
+    const set = this.listeners.get(request.type);
+    if (!set) return;
+    for (const listener of Array.from(set)) {
+      listener(request);
+    }
+  }
+};
+
+export { EmbeddedAppClient };
+//# sourceMappingURL=embedded-app.js.map
+//# sourceMappingURL=embedded-app.js.map