@captello/ulc-webview-sdk 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.3.0
+
+### Minor Changes
+
+- 2e7ba33: The mobile-app channel now has both sides, under names that say who hosts whom.
+
+    The SDK covers two different embedding directions, and 1.2.0's `/app` entry blurred
+    them. They are now named explicitly:
+
+    | Who embeds whom                         | Client                                                                         |
+    | --------------------------------------- | ------------------------------------------------------------------------------ |
+    | Your page embeds the capture webview    | `CaptelloWebview` (unchanged)                                                  |
+    | The Captello mobile app embeds your app | `MobileHostClient` in your app · **new** `EmbeddedAppClient` in the mobile app |
+
+    - **`@captello/ulc-webview-sdk/mobile-host`** — `MobileHostClient` replaces 1.2.0's
+      `CaptelloAppHost`; `MobileHostRequestType` / `MobileHostResponseType` replace
+      `AppRequestType` / `AppResponseType`. Options are `mobileHostWindow` / `embeddedWindow`.
+      Behaviour is unchanged.
+    - **`@captello/ulc-webview-sdk/embedded-app`** — new. `EmbeddedAppClient(iframe)` is the
+      mobile app's side: typed `onRequest(type, listener)` / `onAnyRequest`, and
+      `sendAuthToken`, `sendScannerResult`, `sendScannerError`, `sendScannerClosed`, or
+      `send(response)` for the rest. Requests are accepted only from the bound iframe and,
+      once known, its origin; the target origin is read from `iframe.src` unless given, and
+      the client refuses to send with neither rather than fall back to `"*"`.
+    - **`@captello/ulc-webview-sdk/app`** (1.2.0) is removed. It shipped hours earlier with no
+      consumer, so the rename is not carried as aliases.
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -18,9 +18,13 @@ It provides:
    utilities like `submitForm(iframe)` and `waitForFormLoad(iframe)`.
 6. **React adapter** (`@captello/ulc-webview-sdk/react`) — a `useCaptelloWebview` hook that
    manages the client lifecycle and returns an iframe ref plus typed senders.
-7. **App-host client** (`@captello/ulc-webview-sdk/app`) — for pages that run _inside_ the
-   Captello mobile app: `CaptelloAppHost` talks to the app for an auth token, the badge
-   scanner, and navigation.
+7. **The mobile-app channel** — the SDK's second, separate protocol, for when the
+   **Captello mobile app** is the host and embeds an application:
+    - `@captello/ulc-webview-sdk/mobile-host` — `MobileHostClient`, used by the _embedded
+      application_ (the meeting platform, Connexions) to reach the mobile app for an auth
+      token, the badge scanner, and navigation.
+    - `@captello/ulc-webview-sdk/embedded-app` — `EmbeddedAppClient`, used by the _mobile
+      app_ to serve those requests through the iframe it hosts.
 
 The core package is framework-agnostic with no runtime dependencies; React is an
 optional peer dependency used only by the `/react` entry point.
@@ -647,23 +651,27 @@ internal listener before settling, including on timeout.
 > call `waitForFormLoad` (e.g. you attach late), create a long-lived `CaptelloWebview`
 > before the iframe navigates instead.
 
-## Inside the Captello app — `@captello/ulc-webview-sdk/app`
+## The mobile-app channel — `/mobile-host` and `/embedded-app`
 
-The mobile app embeds web pages (the meeting platform, Connexions) and offers them native
-services over `postMessage`. `CaptelloAppHost` is the page-side client for that channel —
-the mirror image of `CaptelloWebview`: here the Captello **app** is the host and your page
-is the child.
+The SDK covers two embedding directions, and they are different protocols. Keep them apart:
+
+| Who embeds whom                             | Host                | Embedded              | Client to use                                                             | Wire                            |
+| ------------------------------------------- | ------------------- | --------------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| **Your page embeds the capture webview**    | your page           | Captello capture form | `CaptelloWebview` (everything above this section)                         | JSON strings, `snake_case`      |
+| **The Captello mobile app embeds your app** | Captello mobile app | your application      | `MobileHostClient` (in your app), `EmbeddedAppClient` (in the mobile app) | plain objects, `SCREAMING_CASE` |
+
+### In the embedded application — `MobileHostClient`
 
 ```ts
-import { CaptelloAppHost, ScannerError } from "@captello/ulc-webview-sdk/app";
+import { MobileHostClient, ScannerError } from "@captello/ulc-webview-sdk/mobile-host";
 
-const app = new CaptelloAppHost(); // listens on window, posts to window.parent
+const mobileHost = new MobileHostClient(); // listens on window, posts to window.parent
 
-const token = await app.requestAuthToken(); // exchange it for a session, then:
-app.notifyReady(); // the app hides its spinner
+const token = await mobileHost.requestAuthToken(); // exchange it for a session, then:
+mobileHost.notifyReady(); // the mobile app hides its spinner
 
 try {
-    const people = await app.openScanner(); // resolves when the scanner closes
+    const people = await mobileHost.openScanner(); // resolves when the scanner closes
     const [first] = people; // undefined if the user cancelled
     if (first) fillForm(first.fields, first.badgeId);
 } catch (e) {
@@ -675,24 +683,46 @@ try {
 for a group scan. Each `ScannedPerson` is `{ badgeId, fields }`, where `fields` is a
 `PrefillInfoItem[]` keyed by `ll_field_unique_identifier`, so it can be fed straight into a
 capture form's `prefill({ info })`. A badge with no lookup data still arrives with its
-`badgeId` and empty `fields`.
+`badgeId` and empty `fields`. `send(request)` posts any other `MobileHostRequest`;
+`on(MobileHostResponseType.X, listener)` subscribes to any response. `targetOrigin`
+defaults to `"*"` here: the mobile app's webview origin differs per platform and an
+application only uses this channel when it is running inside the app.
+
+### In the mobile app — `EmbeddedAppClient`
+
+```ts
+import { EmbeddedAppClient, MobileHostRequestType } from "@captello/ulc-webview-sdk/embedded-app";
+
+const embedded = new EmbeddedAppClient(iframe); // target origin read from iframe.src
+
+embedded.onRequest(MobileHostRequestType.RequestAuthToken, async () => {
+    embedded.sendAuthToken(await mintMagicToken());
+});
+embedded.onRequest(MobileHostRequestType.OpenScanner, async () => {
+    for (const person of await runScanner()) embedded.sendScannerResult(person);
+    embedded.sendScannerClosed();
+});
+embedded.onRequest(MobileHostRequestType.NavigateBack, () => modal.dismiss());
+
+// when the iframe goes away:
+embedded.destroy();
+```
 
-The wire format differs from the capture-webview channel: messages are **plain objects**
-(not JSON strings) with SCREAMING_CASE types. The client handles both directions; for
-anything without a dedicated method, `send(request)` posts any `AppRequest` and
-`on(AppResponseType.X, listener)` subscribes to any response.
+Requests are only accepted from the bound iframe's window (`matchSource`) and, once a
+target origin is known, from that origin. Responses can carry an auth token, so with no
+`targetOrigin` option and no parsable `iframe.src` the client refuses to send rather than
+fall back to `"*"`.
 
-| Page → app (`AppRequestType`)                                                   | Method                 | App → page (`AppResponseType`)                                                   |
-| ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- |
-| `APP_READY`                                                                     | `notifyReady()`        | —                                                                                |
-| `ERROR`                                                                         | `notifyError(message)` | —                                                                                |
-| `NAVIGATE_BACK`                                                                 | `navigateBack()`       | —                                                                                |
-| `REQUEST_AUTH_TOKEN`                                                            | `requestAuthToken()`   | `AUTH_TOKEN { token }`                                                           |
-| `OPEN_ULC_FORM_SCANNER`                                                         | `openScanner()`        | `ULC_FORM_SCANNER_RESULT { badgeId, result }` ×N, then `ULC_FORM_SCANNER_CLOSED` |
-| `OPEN_URL`, `COPY_TEXT`, `SHARE_URL`, `SAVE_VCARD`, `ADD_TO_WALLET`, `SYNC_APP` | `send({ type, ... })`  | `COPIED_*`, `SAVE_VCARD_*`, `ADD_TO_WALLET_*` acks                               |
+### Wire reference
 
-`targetOrigin` defaults to `"*"` here: the app's webview origin differs per platform and a
-page only uses this channel when it is running inside the app.
+| Embedded app → mobile app (`MobileHostRequestType`)                             | `MobileHostClient`     | Mobile app → embedded app (`MobileHostResponseType`)                             | `EmbeddedAppClient`                                                         |
+| ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `APP_READY`                                                                     | `notifyReady()`        | —                                                                                | —                                                                           |
+| `ERROR { message }`                                                             | `notifyError(message)` | —                                                                                | —                                                                           |
+| `NAVIGATE_BACK`                                                                 | `navigateBack()`       | —                                                                                | —                                                                           |
+| `REQUEST_AUTH_TOKEN`                                                            | `requestAuthToken()`   | `AUTH_TOKEN { token }`                                                           | `sendAuthToken(token)`                                                      |
+| `OPEN_ULC_FORM_SCANNER`                                                         | `openScanner()`        | `ULC_FORM_SCANNER_RESULT { badgeId, result }` ×N, then `ULC_FORM_SCANNER_CLOSED` | `sendScannerResult(person)`, `sendScannerError(msg)`, `sendScannerClosed()` |
+| `OPEN_URL`, `COPY_TEXT`, `SHARE_URL`, `SAVE_VCARD`, `ADD_TO_WALLET`, `SYNC_APP` | `send({ type, ... })`  | `COPIED_*`, `SAVE_VCARD_*`, `ADD_TO_WALLET_*` acks                               | `send({ type })`                                                            |
 
 ## Migrating an existing integration
 
@@ -894,8 +924,9 @@ Two layers, deliberately split:
   origin filtering, `event.source` identity, and a removed iframe's `closed` flag — jsdom
   reports `closed` as `undefined`, so `attach()`'s teardown is unprovable without a browser.
   The webview here is a stub, so this proves the client's behaviour, not that both sides
-  agree. `e2e/app-host.spec.ts` does the same for `CaptelloAppHost`: a stub app on one
-  origin embeds a page on the other and the two exchange plain-object messages.
+  agree. `e2e/mobile-app-channel.spec.ts` does the same for the mobile-app channel: a stub
+  mobile app on one origin (`EmbeddedAppClient`) embeds an application on the other
+  (`MobileHostClient`), so both shipped clients are proven against each other.
 - **`e2e/sdk-integration.spec.ts` in the app repo** (`pnpm exec playwright test e2e/sdk-integration.spec.ts`)
   — the SDK against the **real webview**, cross-origin. This is the layer that catches
   protocol drift between the two, because neither side is a stub: it waits for a real

package/dist/chunk-XI5MIDBA.js

@@ -0,0 +1,60 @@
+// src/mobile-app-protocol.ts
+var MobileHostRequestType = /* @__PURE__ */ ((MobileHostRequestType2) => {
+  MobileHostRequestType2["AppReady"] = "APP_READY";
+  MobileHostRequestType2["Error"] = "ERROR";
+  MobileHostRequestType2["NavigateBack"] = "NAVIGATE_BACK";
+  MobileHostRequestType2["RequestAuthToken"] = "REQUEST_AUTH_TOKEN";
+  MobileHostRequestType2["OpenScanner"] = "OPEN_ULC_FORM_SCANNER";
+  MobileHostRequestType2["OpenUrl"] = "OPEN_URL";
+  MobileHostRequestType2["CopyText"] = "COPY_TEXT";
+  MobileHostRequestType2["ShareUrl"] = "SHARE_URL";
+  MobileHostRequestType2["SaveVCard"] = "SAVE_VCARD";
+  MobileHostRequestType2["AddToWallet"] = "ADD_TO_WALLET";
+  MobileHostRequestType2["SyncApp"] = "SYNC_APP";
+  return MobileHostRequestType2;
+})(MobileHostRequestType || {});
+var MobileHostResponseType = /* @__PURE__ */ ((MobileHostResponseType2) => {
+  MobileHostResponseType2["AuthToken"] = "AUTH_TOKEN";
+  MobileHostResponseType2["ScannerResult"] = "ULC_FORM_SCANNER_RESULT";
+  MobileHostResponseType2["ScannerClosed"] = "ULC_FORM_SCANNER_CLOSED";
+  MobileHostResponseType2["CopiedSuccess"] = "COPIED_SUCCESS";
+  MobileHostResponseType2["CopiedError"] = "COPIED_ERROR";
+  MobileHostResponseType2["SaveVCardSuccess"] = "SAVE_VCARD_SUCCESS";
+  MobileHostResponseType2["SaveVCardError"] = "SAVE_VCARD_ERROR";
+  MobileHostResponseType2["AddToWalletSuccess"] = "ADD_TO_WALLET_SUCCESS";
+  MobileHostResponseType2["AddToWalletError"] = "ADD_TO_WALLET_ERROR";
+  return MobileHostResponseType2;
+})(MobileHostResponseType || {});
+var REQUEST_TYPES = new Set(Object.values(MobileHostRequestType));
+var RESPONSE_TYPES = new Set(Object.values(MobileHostResponseType));
+function parseTyped(data, types) {
+  let value = data;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value;
+  if (typeof record["type"] !== "string" || !types.has(record["type"])) return null;
+  return record;
+}
+function parseMobileHostRequest(data) {
+  return parseTyped(data, REQUEST_TYPES);
+}
+function parseMobileHostResponse(data) {
+  return parseTyped(data, RESPONSE_TYPES);
+}
+function makeSubscription(off) {
+  const handle = () => {
+    off();
+  };
+  handle.unsubscribe = off;
+  return handle;
+}
+
+export { MobileHostRequestType, MobileHostResponseType, makeSubscription, parseMobileHostRequest, parseMobileHostResponse };
+//# sourceMappingURL=chunk-XI5MIDBA.js.map
+//# sourceMappingURL=chunk-XI5MIDBA.js.map

package/dist/chunk-XI5MIDBA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mobile-app-protocol.ts"],"names":["MobileHostRequestType","MobileHostResponseType"],"mappings":";AA2BO,IAAK,qBAAA,qBAAAA,sBAAAA,KAAL;AAEH,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,OAAA,CAAA,GAAQ,OAAA;AAER,EAAAA,uBAAA,cAAA,CAAA,GAAe,eAAA;AAEf,EAAAA,uBAAA,kBAAA,CAAA,GAAmB,oBAAA;AAMnB,EAAAA,uBAAA,aAAA,CAAA,GAAc,uBAAA;AAEd,EAAAA,uBAAA,SAAA,CAAA,GAAU,UAAA;AAEV,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,WAAA,CAAA,GAAY,YAAA;AAEZ,EAAAA,uBAAA,aAAA,CAAA,GAAc,eAAA;AAEd,EAAAA,uBAAA,SAAA,CAAA,GAAU,UAAA;AA1BF,EAAA,OAAAA,sBAAAA;AAAA,CAAA,EAAA,qBAAA,IAAA,EAAA;AAgGL,IAAK,sBAAA,qBAAAC,uBAAAA,KAAL;AAEH,EAAAA,wBAAA,WAAA,CAAA,GAAY,YAAA;AAEZ,EAAAA,wBAAA,eAAA,CAAA,GAAgB,yBAAA;AAEhB,EAAAA,wBAAA,eAAA,CAAA,GAAgB,yBAAA;AAChB,EAAAA,wBAAA,eAAA,CAAA,GAAgB,gBAAA;AAChB,EAAAA,wBAAA,aAAA,CAAA,GAAc,cAAA;AACd,EAAAA,wBAAA,kBAAA,CAAA,GAAmB,oBAAA;AACnB,EAAAA,wBAAA,gBAAA,CAAA,GAAiB,kBAAA;AACjB,EAAAA,wBAAA,oBAAA,CAAA,GAAqB,uBAAA;AACrB,EAAAA,wBAAA,kBAAA,CAAA,GAAmB,qBAAA;AAZX,EAAA,OAAAA,uBAAAA;AAAA,CAAA,EAAA,sBAAA,IAAA,EAAA;AAoFZ,IAAM,gBAAqC,IAAI,GAAA,CAAI,MAAA,CAAO,MAAA,CAAO,qBAAqB,CAAC,CAAA;AACvF,IAAM,iBAAsC,IAAI,GAAA,CAAI,MAAA,CAAO,MAAA,CAAO,sBAAsB,CAAC,CAAA;AAEzF,SAAS,UAAA,CAAW,MAAe,KAAA,EAA4D;AAC3F,EAAA,IAAI,KAAA,GAAiB,IAAA;AACrB,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC3B,IAAA,IAAI;AACA,MAAA,KAAA,GAAQ,IAAA,CAAK,MAAM,KAAK,CAAA;AAAA,IAC5B,CAAA,CAAA,MAAQ;AACJ,MAAA,OAAO,IAAA;AAAA,IACX;AAAA,EACJ;AACA,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,KAAA,KAAU,QAAQ,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG,OAAO,IAAA;AAChF,EAAA,MAAM,MAAA,GAAS,KAAA;AACf,EAAA,IAAI,OAAO,MAAA,CAAO,MAAM,CAAA,KAAM,QAAA,IAAY,CAAC,KAAA,CAAM,GAAA,CAAI,MAAA,CAAO,MAAM,CAAC,CAAA,EAAG,OAAO,IAAA;AAC7E,EAAA,OAAO,MAAA;AACX;AAOO,SAAS,uBAAuB,IAAA,EAAyC;AAC5E,EAAA,OAAO,UAAA,CAAW,MAAM,aAAa,CAAA;AACzC;AAOO,SAAS,wBAAwB,IAAA,EAA0C;AAC9E,EAAA,OAAO,UAAA,CAAW,MAAM,cAAc,CAAA;AAC1C;AAGO,SAAS,iBAAiB,GAAA,EAA8B;AAC3D,EAAA,MAAM,SAAU,MAAM;AAClB,IAAA,GAAA,EAAI;AAAA,EACR,CAAA;AACA,EAAA,MAAA,CAAO,WAAA,GAAc,GAAA;AACrB,EAAA,OAAO,MAAA;AACX","file":"chunk-XI5MIDBA.js","sourcesContent":["/**\n * The message protocol between the **Captello mobile app** and an **application it\n * embeds** (the meeting platform, Connexions, …).\n *\n * This is the second of the SDK's two channels, and the roles are the reverse of the\n * capture-webview channel:\n *\n * | Channel                                   | Host                | Embedded            | Client on each side                                  |\n * | ----------------------------------------- | ------------------- | ------------------- | ---------------------------------------------------- |\n * | A host page embeds the capture webview    | your page           | capture webview     | `CaptelloWebview` (host side)                        |\n * | The mobile app embeds an application      | Captello mobile app | your application    | `EmbeddedAppClient` (app side), `MobileHostClient` (embedded side) |\n *\n * Wire format (match it exactly — it differs from the capture-webview channel):\n * - Messages are posted as **plain objects**, not JSON strings.\n * - `type` values are SCREAMING_CASE.\n * - {@link MobileHostRequestType} (embedded application → mobile app) and\n *   {@link MobileHostResponseType} (mobile app → embedded application) are disjoint.\n */\n\nimport type { Unsubscribe } from \"./client\";\nimport type { PrefillInfoItem } from \"./messages\";\n\n/* ------------------------------------------------------------------ *\n * Requests: embedded application → mobile app\n * ------------------------------------------------------------------ */\n\n/** Message `type` values an embedded application sends to the Captello mobile app. */\nexport enum MobileHostRequestType {\n    /** The application finished loading; the app hides its loading spinner. */\n    AppReady = \"APP_READY\",\n    /** A user-facing error; the app shows `message`. */\n    Error = \"ERROR\",\n    /** Close the application (the app dismisses the modal or pops the route). */\n    NavigateBack = \"NAVIGATE_BACK\",\n    /** Ask for a magic token; answered with {@link MobileHostResponseType.AuthToken}. */\n    RequestAuthToken = \"REQUEST_AUTH_TOKEN\",\n    /**\n     * Open the app's badge scanner. Answered with one\n     * {@link MobileHostResponseType.ScannerResult} per scanned person, then\n     * {@link MobileHostResponseType.ScannerClosed}.\n     */\n    OpenScanner = \"OPEN_ULC_FORM_SCANNER\",\n    /** Open `url` in the system browser. */\n    OpenUrl = \"OPEN_URL\",\n    /** Copy `text` to the clipboard; acknowledged with `COPIED_SUCCESS` / `COPIED_ERROR`. */\n    CopyText = \"COPY_TEXT\",\n    /** Open the native share sheet. */\n    ShareUrl = \"SHARE_URL\",\n    /** Save a vCard to the contacts; acknowledged with `SAVE_VCARD_SUCCESS` / `SAVE_VCARD_ERROR`. */\n    SaveVCard = \"SAVE_VCARD\",\n    /** Add a wallet pass; acknowledged with `ADD_TO_WALLET_SUCCESS` / `ADD_TO_WALLET_ERROR`. */\n    AddToWallet = \"ADD_TO_WALLET\",\n    /** Ask the app to synchronize its data. */\n    SyncApp = \"SYNC_APP\",\n}\n\nexport interface AppReadyRequest {\n    type: MobileHostRequestType.AppReady;\n}\nexport interface ErrorRequest {\n    type: MobileHostRequestType.Error;\n    message: string;\n}\nexport interface NavigateBackRequest {\n    type: MobileHostRequestType.NavigateBack;\n}\nexport interface RequestAuthTokenRequest {\n    type: MobileHostRequestType.RequestAuthToken;\n}\nexport interface OpenScannerRequest {\n    type: MobileHostRequestType.OpenScanner;\n}\nexport interface OpenUrlRequest {\n    type: MobileHostRequestType.OpenUrl;\n    url: string;\n}\nexport interface CopyTextRequest {\n    type: MobileHostRequestType.CopyText;\n    text: string;\n}\nexport interface ShareUrlRequest {\n    type: MobileHostRequestType.ShareUrl;\n    title: string;\n    text: string;\n}\nexport interface SaveVCardRequest {\n    type: MobileHostRequestType.SaveVCard;\n    /** vCard text. */\n    text: string;\n}\nexport interface AddToWalletRequest {\n    type: MobileHostRequestType.AddToWallet;\n    /** Base64 pass data, with or without a `data:` prefix. */\n    text: string;\n}\nexport interface SyncAppRequest {\n    type: MobileHostRequestType.SyncApp;\n}\n\n/** Discriminated union of every message an embedded application can send to the mobile app. */\nexport type MobileHostRequest =\n    | AppReadyRequest\n    | ErrorRequest\n    | NavigateBackRequest\n    | RequestAuthTokenRequest\n    | OpenScannerRequest\n    | OpenUrlRequest\n    | CopyTextRequest\n    | ShareUrlRequest\n    | SaveVCardRequest\n    | AddToWalletRequest\n    | SyncAppRequest;\n\n/** Maps each request `type` to its full message shape (used by {@link EmbeddedAppClient.onRequest}). */\nexport type MobileHostRequestMap = {\n    [M in MobileHostRequest as M[\"type\"]]: M;\n};\n\n/* ------------------------------------------------------------------ *\n * Responses: mobile app → embedded application\n * ------------------------------------------------------------------ */\n\n/** Message `type` values the Captello mobile app sends to an embedded application. */\nexport enum MobileHostResponseType {\n    /** Answer to {@link MobileHostRequestType.RequestAuthToken}. */\n    AuthToken = \"AUTH_TOKEN\",\n    /** One scanned person (or a scanner failure) after {@link MobileHostRequestType.OpenScanner}. */\n    ScannerResult = \"ULC_FORM_SCANNER_RESULT\",\n    /** The scanner session ended: every result was posted, or the user cancelled. */\n    ScannerClosed = \"ULC_FORM_SCANNER_CLOSED\",\n    CopiedSuccess = \"COPIED_SUCCESS\",\n    CopiedError = \"COPIED_ERROR\",\n    SaveVCardSuccess = \"SAVE_VCARD_SUCCESS\",\n    SaveVCardError = \"SAVE_VCARD_ERROR\",\n    AddToWalletSuccess = \"ADD_TO_WALLET_SUCCESS\",\n    AddToWalletError = \"ADD_TO_WALLET_ERROR\",\n}\n\n/** Mobile app → embedded application: the magic token requested with {@link MobileHostRequestType.RequestAuthToken}. */\nexport interface AuthTokenMessage {\n    type: MobileHostResponseType.AuthToken;\n    token: string;\n}\n\n/**\n * Mobile app → embedded application: one scanned person, or a scanner failure.\n *\n * The app posts one of these per person the scanner captured — several for a group\n * scan — then a {@link ScannerClosedMessage}. `result` holds the looked-up attendee\n * fields in the same shape {@link PrefillInfoItem} uses, so they can be fed straight to\n * a capture form's `prefill({ info })`. It is empty (not absent) when the badge had no\n * lookup data; the badge can still be linked via `badgeId`.\n *\n * On failure `result` is absent and `message` carries the error text.\n */\nexport interface ScannerResultMessage {\n    type: MobileHostResponseType.ScannerResult;\n    /**\n     * Badge ID the person was scanned from. Empty for business cards and manual search.\n     * Absent altogether on app builds that predate multi-person sessions — those post a\n     * single result and never a {@link ScannerClosedMessage}.\n     */\n    badgeId?: string;\n    /** Looked-up attendee fields (success). */\n    result?: PrefillInfoItem[];\n    /** Error text (failure) — `result` is absent. */\n    message?: string;\n}\n\n/** Mobile app → embedded application: the scanner session ended. Follows the last {@link ScannerResultMessage}. */\nexport interface ScannerClosedMessage {\n    type: MobileHostResponseType.ScannerClosed;\n}\n\ninterface AckMessage<T extends MobileHostResponseType> {\n    type: T;\n}\n\n/** Discriminated union of every message the mobile app can send to an embedded application. */\nexport type MobileHostResponse =\n    | AuthTokenMessage\n    | ScannerResultMessage\n    | ScannerClosedMessage\n    | AckMessage<MobileHostResponseType.CopiedSuccess>\n    | AckMessage<MobileHostResponseType.CopiedError>\n    | AckMessage<MobileHostResponseType.SaveVCardSuccess>\n    | AckMessage<MobileHostResponseType.SaveVCardError>\n    | AckMessage<MobileHostResponseType.AddToWalletSuccess>\n    | AckMessage<MobileHostResponseType.AddToWalletError>;\n\n/** Maps each response `type` to its full message shape (used by {@link MobileHostClient.on}). */\nexport type MobileHostResponseMap = {\n    [M in MobileHostResponse as M[\"type\"]]: M;\n};\n\n/** One person captured by the mobile app's scanner. */\nexport interface ScannedPerson {\n    /** Badge ID the person was scanned from; empty for business cards and manual search. */\n    badgeId: string;\n    /** Looked-up attendee fields; empty when the badge had no lookup data. */\n    fields: PrefillInfoItem[];\n}\n\n/* ------------------------------------------------------------------ *\n * Runtime guards / parsing\n * ------------------------------------------------------------------ */\n\nconst REQUEST_TYPES: ReadonlySet<string> = new Set(Object.values(MobileHostRequestType));\nconst RESPONSE_TYPES: ReadonlySet<string> = new Set(Object.values(MobileHostResponseType));\n\nfunction parseTyped(data: unknown, types: ReadonlySet<string>): Record<string, unknown> | null {\n    let value: unknown = data;\n    if (typeof value === \"string\") {\n        try {\n            value = JSON.parse(value);\n        } catch {\n            return null;\n        }\n    }\n    if (typeof value !== \"object\" || value === null || Array.isArray(value)) return null;\n    const record = value as Record<string, unknown>;\n    if (typeof record[\"type\"] !== \"string\" || !types.has(record[\"type\"])) return null;\n    return record;\n}\n\n/**\n * Parses a raw `MessageEvent.data` value into a typed {@link MobileHostRequest}, or\n * returns `null` if it is not a recognized request. Plain objects are the wire format;\n * a JSON string is accepted too for robustness.\n */\nexport function parseMobileHostRequest(data: unknown): MobileHostRequest | null {\n    return parseTyped(data, REQUEST_TYPES) as unknown as MobileHostRequest | null;\n}\n\n/**\n * Parses a raw `MessageEvent.data` value into a typed {@link MobileHostResponse}, or\n * returns `null` if it is not a recognized response. Plain objects are the wire format;\n * a JSON string is accepted too for robustness.\n */\nexport function parseMobileHostResponse(data: unknown): MobileHostResponse | null {\n    return parseTyped(data, RESPONSE_TYPES) as unknown as MobileHostResponse | null;\n}\n\n/** @internal Builds the callable-with-`unsubscribe()` handle every `on*` method returns. */\nexport function makeSubscription(off: () => void): Unsubscribe {\n    const handle = (() => {\n        off();\n    }) as Unsubscribe;\n    handle.unsubscribe = off;\n    return handle;\n}\n"]}

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

package/dist/embedded-app.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embedded-app.ts"],"names":[],"mappings":"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","file":"embedded-app.js","sourcesContent":["/**\n * `@captello/ulc-webview-sdk/embedded-app` — for the **Captello mobile app** (or any\n * host playing its role) that embeds an application in an iframe and serves it native\n * services over `postMessage`.\n *\n * {@link EmbeddedAppClient} wraps the iframe: it delivers the embedded application's\n * requests to typed handlers and posts the app's responses back. The embedded\n * application's own side is `MobileHostClient` (`@captello/ulc-webview-sdk/mobile-host`).\n *\n * Not to be confused with `CaptelloWebview`, which wraps an iframe of the *capture\n * webview* — a different protocol (JSON strings, snake_case types).\n *\n * @example\n * import { EmbeddedAppClient, MobileHostRequestType } from \"@captello/ulc-webview-sdk/embedded-app\";\n *\n * const embedded = new EmbeddedAppClient(iframe, { targetOrigin: new URL(iframe.src).origin });\n * embedded.onRequest(MobileHostRequestType.RequestAuthToken, async () => {\n *     embedded.sendAuthToken(await mintMagicToken());\n * });\n * embedded.onRequest(MobileHostRequestType.OpenScanner, async () => {\n *     for (const person of await scan()) embedded.sendScannerResult(person);\n *     embedded.sendScannerClosed();\n * });\n */\n\nimport type { FrameLike, Unsubscribe } from \"./client\";\nimport {\n    makeSubscription,\n    MobileHostRequestType,\n    MobileHostResponseType,\n    parseMobileHostRequest,\n} from \"./mobile-app-protocol\";\nimport type { MobileHostRequest, MobileHostRequestMap, MobileHostResponse, ScannedPerson } from \"./mobile-app-protocol\";\n\nexport {\n    MobileHostRequestType,\n    MobileHostResponseType,\n    parseMobileHostRequest,\n    parseMobileHostResponse,\n} from \"./mobile-app-protocol\";\nexport type {\n    MobileHostRequest,\n    MobileHostRequestMap,\n    MobileHostResponse,\n    MobileHostResponseMap,\n    AuthTokenMessage,\n    ScannerResultMessage,\n    ScannerClosedMessage,\n    ScannedPerson,\n} from \"./mobile-app-protocol\";\nexport type { FrameLike } from \"./client\";\n\n/** Listener for a specific request type from the embedded application. */\nexport type MobileHostRequestListener<T extends MobileHostRequestType> = (request: MobileHostRequestMap[T]) => void;\n\n/** Listener for every request from the embedded application (used by {@link EmbeddedAppClient.onAnyRequest}). */\nexport type AnyMobileHostRequestListener = (request: MobileHostRequest) => void;\n\nexport interface EmbeddedAppClientOptions {\n    /**\n     * Origin to validate incoming requests against and to target outgoing responses.\n     * A full URL is accepted and reduced to its origin.\n     *\n     * Defaults to the iframe's `src` origin, read fresh on every send so a `src` bound\n     * after construction still works. When neither is available the client refuses to\n     * send rather than fall back to `\"*\"` — a response can carry an auth token, and\n     * `\"*\"` would hand it to whatever the frame navigated to.\n     */\n    targetOrigin?: string;\n    /** Window to listen on. Defaults to the global `window`. */\n    hostWindow?: Window;\n    /**\n     * Only accept requests whose `event.source` is the bound iframe's window. Defaults\n     * to `true`. Set `false` if the application relays through another window.\n     */\n    matchSource?: boolean;\n}\n\nfunction toOrigin(value: string | undefined): string | undefined {\n    if (!value) return undefined;\n    if (value === \"*\") return value;\n    try {\n        return new URL(value).origin;\n    } catch {\n        return undefined;\n    }\n}\n\n/**\n * Mobile-app-side client for an application embedded in an iframe.\n *\n * Attaches a single `message` listener on construction; call {@link destroy} when the\n * iframe goes away.\n */\nexport class EmbeddedAppClient {\n    private readonly frame: FrameLike;\n    private readonly hostWindow: Window;\n    private readonly explicitOrigin: string | undefined;\n    private readonly matchSource: boolean;\n    private readonly listeners = new Map<\n        MobileHostRequestType,\n        Set<MobileHostRequestListener<MobileHostRequestType>>\n    >();\n    private readonly anyListeners = new Set<AnyMobileHostRequestListener>();\n    private readonly boundHandler = (event: MessageEvent) => this.handleMessage(event);\n    private destroyed = false;\n\n    constructor(frame: FrameLike, options: EmbeddedAppClientOptions = {}) {\n        if (!frame) {\n            throw new Error(\"EmbeddedAppClient: a mounted iframe element (or { contentWindow }) is required.\");\n        }\n        const hostWindow = options.hostWindow ?? (typeof window !== \"undefined\" ? window : undefined);\n        if (!hostWindow) {\n            throw new Error(\n                \"EmbeddedAppClient: no host window available. Pass `hostWindow` when constructing outside a browser.\",\n            );\n        }\n        this.frame = frame;\n        this.hostWindow = hostWindow;\n        this.explicitOrigin = toOrigin(options.targetOrigin);\n        this.matchSource = options.matchSource ?? true;\n        this.hostWindow.addEventListener(\"message\", this.boundHandler);\n    }\n\n    /** Subscribe to one request type. Returns a handle with `unsubscribe()` (also callable). */\n    onRequest<T extends MobileHostRequestType>(type: T, listener: MobileHostRequestListener<T>): Unsubscribe {\n        let set = this.listeners.get(type);\n        if (!set) {\n            set = new Set();\n            this.listeners.set(type, set);\n        }\n        set.add(listener as MobileHostRequestListener<MobileHostRequestType>);\n        return makeSubscription(() => {\n            set?.delete(listener as MobileHostRequestListener<MobileHostRequestType>);\n        });\n    }\n\n    /** Subscribe to every request. */\n    onAnyRequest(listener: AnyMobileHostRequestListener): Unsubscribe {\n        this.anyListeners.add(listener);\n        return makeSubscription(() => {\n            this.anyListeners.delete(listener);\n        });\n    }\n\n    /**\n     * Post a response into the embedded application. Returns `false` when nothing was\n     * sent: the client is destroyed, the iframe has no window, or no target origin could\n     * be resolved (see {@link EmbeddedAppClientOptions.targetOrigin}).\n     */\n    send(response: MobileHostResponse): boolean {\n        if (this.destroyed) return false;\n        const target = this.frame.contentWindow;\n        const origin = this.resolveOrigin();\n        if (!target || !origin) return false;\n        target.postMessage(response, origin);\n        return true;\n    }\n\n    /** Answer a {@link MobileHostRequestType.RequestAuthToken} request. */\n    sendAuthToken(token: string): boolean {\n        return this.send({ type: MobileHostResponseType.AuthToken, token });\n    }\n\n    /** Post one scanned person of the current scanner session. */\n    sendScannerResult(person: ScannedPerson): boolean {\n        return this.send({\n            type: MobileHostResponseType.ScannerResult,\n            badgeId: person.badgeId,\n            result: person.fields,\n        });\n    }\n\n    /** Fail the current scanner session with a display-ready message. */\n    sendScannerError(message: string): boolean {\n        return this.send({ type: MobileHostResponseType.ScannerResult, message });\n    }\n\n    /** End the current scanner session; send after the last result, or on cancel. */\n    sendScannerClosed(): boolean {\n        return this.send({ type: MobileHostResponseType.ScannerClosed });\n    }\n\n    /** Remove the `message` listener and drop every subscription. Safe to call more than once. */\n    destroy(): void {\n        if (this.destroyed) return;\n        this.destroyed = true;\n        this.hostWindow.removeEventListener(\"message\", this.boundHandler);\n        this.listeners.clear();\n        this.anyListeners.clear();\n    }\n\n    private resolveOrigin(): string | undefined {\n        if (this.explicitOrigin) return this.explicitOrigin;\n        const src = \"src\" in this.frame ? (this.frame as { src?: string }).src : undefined;\n        return toOrigin(src);\n    }\n\n    private handleMessage(event: MessageEvent): void {\n        if (this.matchSource && event.source !== this.frame.contentWindow) return;\n        const origin = this.resolveOrigin();\n        if (origin && origin !== \"*\" && event.origin !== origin) return;\n        const request = parseMobileHostRequest(event.data);\n        if (!request) return;\n        for (const listener of Array.from(this.anyListeners)) {\n            listener(request);\n        }\n        const set = this.listeners.get(request.type);\n        if (!set) return;\n        for (const listener of Array.from(set)) {\n            listener(request);\n        }\n    }\n}\n"]}