@captello/ulc-webview-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lead Liaison, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,424 @@
+# @captello/ulc-webview-sdk
+
+Typed SDK for embedding the **Captello capture webview** in a host application
+(React, plain JS, or any framework). It encodes the exact `postMessage` contract
+the webview speaks, so integrators don't have to reverse-engineer message strings.
+
+It provides:
+
+1. **The message protocol** — enums and discriminated-union types for every
+   message the webview emits and accepts.
+2. **`CaptelloWebview`** — a host-side client that wraps an `<iframe>` and handles
+   the send/receive wire details (JSON-string encoding, origin/source filtering).
+3. **`buildEmbedUrl`** — a typed builder for the webview's query-string contract.
+4. **Submission rendering** — `toDisplayPairs` / `parseVisibleSubmissionsData` to turn a
+   submission's `visible_submissions_data` into typed key/value rows.
+5. **Promise helpers** (`@captello/ulc-webview-sdk/promises`) — one-shot `await`-style
+   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.
+
+The core package is framework-agnostic with no runtime dependencies; React is an
+optional peer dependency used only by the `/react` entry point.
+
+## Install
+
+```bash
+pnpm add @captello/ulc-webview-sdk
+```
+
+## Quick start
+
+```ts
+import {
+    CaptelloWebview,
+    buildEmbedUrl,
+    targetOriginFromUrl,
+    FormMode,
+    LauncherType,
+    OutboundMessageType,
+} from "@captello/ulc-webview-sdk";
+
+// 1. Build the embed URL.
+const src = buildEmbedUrl("https://capture.captello.com/", {
+    formId: 1234,
+    mode: FormMode.Submit,
+    launcher: LauncherType.EventGenWeb,
+    language: "en",
+});
+
+// 2. Point an iframe at it.
+const iframe = document.createElement("iframe");
+iframe.src = src;
+document.body.appendChild(iframe);
+
+// 3. Wire up the client (scope messages to the webview's origin).
+const webview = new CaptelloWebview(iframe, {
+    targetOrigin: targetOriginFromUrl(src),
+});
+
+webview.on(OutboundMessageType.FormLoadComplete, () => {
+    console.log("form is ready");
+});
+
+webview.on(OutboundMessageType.SubmissionBody, (msg) => {
+    // Embedded forms hand the submission to the host instead of submitting directly.
+    persist(msg.data);
+});
+
+webview.on(OutboundMessageType.FormErrorMessage, (msg) => {
+    showToast(msg.data); // already translated & display-ready
+});
+
+// 4. Drive the form programmatically.
+submitButton.onclick = () => webview.submit();
+
+// 5. Tear down when the iframe is removed.
+webview.destroy();
+```
+
+### Submit and await the result
+
+For the common "click submit, then act on the outcome" flow, use `submitAndWait()`
+instead of wiring `submit()` to separate listeners. It resolves with the submission
+body on `submission_body`, rejects with a `SubmissionError` on `form_error_message`,
+and rejects with a `SubmissionTimeoutError` if neither arrives in time — cleaning up
+its listeners in every case.
+
+```ts
+import { SubmissionError } from "@captello/ulc-webview-sdk";
+
+try {
+    const body = await webview.submitAndWait(); // default 60s timeout
+    await persistSubmission(body);
+    closeDialog();
+} catch (err) {
+    if (err instanceof SubmissionError) {
+        showToast(err.message); // translated, display-ready
+    } else {
+        // SubmissionTimeoutError or a send failure
+    }
+}
+```
+
+## React — `@captello/ulc-webview-sdk/react`
+
+The React adapter is the smoothest way to integrate. `useCaptelloWebview` owns a
+`CaptelloWebview` for the iframe's lifetime: it builds the embed URL, creates the client
+when the iframe mounts, wires outbound messages to typed callbacks, tracks readiness,
+and destroys the client on unmount. You get back `iframeProps` to spread, an `isReady`
+flag, and stable senders — so a typical form is just the hook plus an `<iframe>`.
+
+`react` is an optional peer dependency (React 18+).
+
+```tsx
+import { FormMode, LauncherType, ActionButtonPosition, type SubmissionBody } from "@captello/ulc-webview-sdk";
+import { useCaptelloWebview } from "@captello/ulc-webview-sdk/react";
+
+function UlcForm({
+    eventWebAccessToken,
+    onSubmitted,
+}: {
+    eventWebAccessToken: string;
+    onSubmitted: (body: SubmissionBody) => void;
+}) {
+    const { iframeProps, isReady, submit, prefillInfo } = useCaptelloWebview({
+        embedUrl: {
+            baseUrl: "https://capture.captello.com/capture/submission",
+            eventWebAccessToken,
+            actionButtonPosition: ActionButtonPosition.Hidden, // b=2
+            mode: FormMode.Submit,
+            launcher: LauncherType.EventGenWeb,
+        },
+        onSubmissionBody: (m) => onSubmitted(m.data),
+        onFormErrorMessage: (m) => showToast(m.data),
+    });
+
+    return (
+        <>
+            {!isReady && <Spinner />}
+            <iframe {...iframeProps} title="UlcForm" allow="camera; microphone" />
+            <button onClick={submit}>Submit</button>
+        </>
+    );
+}
+```
+
+What the hook handles for you:
+
+- **URL + origin.** Pass `embedUrl: { baseUrl, ...EmbedUrlOptions }` and the hook builds
+  the URL, derives `targetOrigin`, and returns it as `iframeProps.src` — no separate
+  `buildEmbedUrl` / `targetOriginFromUrl` / manual `src` wiring to keep in sync. (Prefer
+  to own the `src`? Omit `embedUrl`, pass `targetOrigin`, and use the returned `ref`.)
+- **Readiness.** `isReady` and `status` (`"loading" | "ready" | "error"`) — no manual
+  `useState` + `onFormLoadComplete` for a spinner.
+- **Prefill timing.** Sends made before the form loads are queued and flushed on
+  `form_load_complete`, so you can `prefillInfo(...)` as soon as you have data — no
+  gating on readiness, and no silently-dropped messages.
+- **No memoization.** Callbacks are read fresh via a ref, so inline arrow functions
+  won't re-subscribe or re-create the client. The client is recreated only when
+  `targetOrigin` (or `embedUrl`) / `hostWindow` / `matchSource` / `queueUntilReady` change.
+- **Stable senders** (`submit`, `reset`, `updateDraft`, `triggerValidation`,
+  `prefillInfo`, `prefillSubmission`, `prefillSubmissionAndInfo`, `submitAndWait`) — safe
+  in deps or passed to children. `getClient()` returns the live client for escape hatches.
+
+### Callback props
+
+`useCaptelloWebview` accepts a callback per outbound message — `onFormLoadComplete`,
+`onFormErrorMessage`, `onSubmissionBody`, `onFormSubmitSuccess`,
+`onConnexionsProfileRedirect`, `onConnexionsDownloadVcard` — plus `onAnyMessage` (fires
+for every message, after the specific handler). All are optional. Connection options
+(`embedUrl` or `targetOrigin`, `hostWindow`, `matchSource`, `queueUntilReady`) go in the
+same object.
+
+### Without the adapter
+
+If you don't want the hook, create a `CaptelloWebview` yourself in an effect against an
+iframe ref, subscribe with `.on(...)`, and call `.destroy()` on unmount. Hold the client
+in a ref (or context) so sibling components can drive it without querying the DOM.
+
+## The message contract
+
+**Wire format:** every message is a JSON **string** with a `type` discriminator.
+The SDK handles this for you — `CaptelloWebview` `JSON.stringify`s outgoing messages
+(the webview parses inbound data with `JSON.parse`, so a raw object would be silently
+ignored) and parses + validates incoming ones. Direction is named from the webview's
+point of view.
+
+### Outbound — webview → host (you listen)
+
+| `type`                        | Constant                                        | Payload                | Meaning                                       |
+| ----------------------------- | ----------------------------------------------- | ---------------------- | --------------------------------------------- |
+| `form_load_complete`          | `OutboundMessageType.FormLoadComplete`          | —                      | Form finished loading/rendering.              |
+| `form_error_message`          | `OutboundMessageType.FormErrorMessage`          | `data: string`         | Translated, display-ready error message.      |
+| `submission_body`             | `OutboundMessageType.SubmissionBody`            | `data: SubmissionBody` | Full submission for the host to persist.      |
+| `form_submit_success`         | `OutboundMessageType.FormSubmitSuccess`         | —                      | Submission succeeded (kiosk / quick-capture). |
+| `connexions_profile_redirect` | `OutboundMessageType.ConnexionsProfileRedirect` | —                      | Host should perform the profile redirect.     |
+| `connexions_download_vcard`   | `OutboundMessageType.ConnexionsDownloadVcard`   | —                      | Host should trigger the vCard download.       |
+
+### Inbound — host → webview (you send)
+
+| `type`               | Method                                                                                  | Notes                                              |
+| -------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `submit_form`        | `webview.submit()`                                                                      | Submit as if the user pressed the button.          |
+| `reset_form`         | `webview.reset()`                                                                       | Clear all entered values.                          |
+| `update_draft`       | `webview.updateDraft()`                                                                 | Switch to draft-update mode.                       |
+| `trigger_validation` | `webview.triggerValidation(target)`                                                     | `target`: `"email" \| "invitation_code" \| "all"`. |
+| `form_prefill`       | `webview.prefillSubmission(...)` / `prefillInfo(...)` / `prefillSubmissionAndInfo(...)` | Three payload shapes (see below).                  |
+
+### Prefill variants (`form_prefill`)
+
+`form_prefill` carries a `data_type` selecting the payload shape:
+
+- `PrefillDataType.UlcSubmission` → `prefillSubmission(submission)` — a `SubmissionPrefill`
+  (a received `SubmissionBody` round-tripped, or a partial `{ data?, ...} ` you assemble).
+- `PrefillDataType.Info` → `prefillInfo(items)` — a list of `PrefillInfoItem`. The webview
+  matches each item by `ll_field_unique_identifier` (e.g. `"FirstName"`, `"Email"`);
+  `ll_field_id` is optional metadata (number or string) and `value` may be a string or boolean.
+- `PrefillDataType.UlcSubmissionAndInfo` → `prefillSubmissionAndInfo({ submission, info })`.
+
+## Rendering a submission as key/value pairs
+
+A `submission_body` payload includes `visible_submissions_data` — one entry per filled,
+visible element, discriminated by `element_type` (so `element_value`'s shape depends on
+the type: strings, string arrays, composites like name/address, order quantities, etc.).
+
+To turn that into rows for the UI, use `toDisplayPairs` (parse + flatten in one call):
+
+```ts
+import { toDisplayPairs, OutboundMessageType } from "@captello/ulc-webview-sdk";
+
+webview.on(OutboundMessageType.SubmissionBody, (msg) => {
+    const rows = toDisplayPairs(msg.data);
+    // rows: { elementId: string; label: string; value: string }[]
+    rows.forEach((r) => addRow(r.label, r.value));
+});
+```
+
+`toDisplayPairs` (and the lower-level `parseVisibleSubmissionsData`) accept `unknown` —
+pass the whole `submission_body` data, the `visible_submissions_data` array itself, or
+any value; entries that don't match the contract (structural/unknown types, missing
+fields) are dropped, so the result is always safe to map over.
+
+For custom rendering, parse to typed items and narrow on `element_type`:
+
+```ts
+import { parseVisibleSubmissionsData, FormElementType } from "@captello/ulc-webview-sdk";
+
+for (const item of parseVisibleSubmissionsData(msg.data)) {
+    if (item.element_type === FormElementType.checkbox) {
+        item.element_value; // string[] | OrderCheckboxSubmissionData — precisely typed
+    }
+}
+```
+
+`toDisplayValue(item, options?)` flattens one item; `options` accepts `listSeparator`
+(default `", "`), `booleanLabels` (default `{ true: "Yes", false: "No" }`), and
+`emptyText` (default `""`).
+
+## `buildEmbedUrl(baseUrl, options)`
+
+Maps friendly option names onto the webview's short query keys. Existing params on
+`baseUrl` are preserved; options override matching keys.
+
+| Option                      | Query key   | Notes                                                                             |
+| --------------------------- | ----------- | --------------------------------------------------------------------------------- |
+| `formId`                    | `f`         |                                                                                   |
+| `submissionToken`           | `s`         |                                                                                   |
+| `stationId`                 | `st`        |                                                                                   |
+| `mode`                      | `m`         | `FormMode` enum.                                                                  |
+| `eventWebAccessToken`       | `e`         |                                                                                   |
+| `activationId`              | `a`         |                                                                                   |
+| `language`                  | `l`         |                                                                                   |
+| `actionButtonPosition`      | `b`         | `ActionButtonPosition` enum: `Fixed` (`"0"`), `Bottom` (`"1"`), `Hidden` (`"2"`). |
+| `formType`                  | `form_type` | `"template" \| "device"`.                                                         |
+| `launcher`                  | `launcher`  | `LauncherType` enum.                                                              |
+| `submissionType`            | `t`         | `"normal" \| "drafted"`.                                                          |
+| `submitButtonBottomPadding` | `sbbp`      |                                                                                   |
+| `useIn`                     | `useIn`     | `"outbound" \| "inbound" \| "notes"`.                                             |
+| `platform`                  | `platform`  | `"web" \| "mobile"`.                                                              |
+| `hideEmail`                 | `he`        | Boolean → `"1"` when true, omitted when false.                                    |
+| `connexionsEmbedMode`       | `cem`       | Boolean → `"1"`.                                                                  |
+| `emro`                      | `emro`      | Boolean → `"1"`. Edit mode read-only.                                             |
+| `extraParams`               | (verbatim)  | Appended as-is; `undefined`/`null` skipped.                                       |
+
+## `CaptelloWebview` API
+
+```ts
+new CaptelloWebview(iframe, {
+  targetOrigin?: string;      // recommend the webview origin; defaults to "*"
+  hostWindow?: Window;        // defaults to global window
+  matchSource?: boolean;      // default true: only accept messages from this iframe
+  queueUntilReady?: boolean;  // default true: buffer sends until form_load_complete
+});
+```
+
+- `isReady` — `true` once the form has reported `form_load_complete`.
+- `on(type, listener) => unsubscribe` — subscribe to one outbound type.
+- `once(type, listener) => unsubscribe` — fire at most once.
+- `onAny(listener) => unsubscribe` — every outbound message.
+- `submit()`, `reset()`, `updateDraft()`, `triggerValidation(target)` — inbound helpers.
+- `submitAndWait(timeoutMs?)` — submit and await `submission_body` / `form_error_message` (see above).
+- `prefillSubmission(...)`, `prefillInfo(...)`, `prefillSubmissionAndInfo(...)`.
+- `send(message)` — low-level escape hatch for any `InboundMessage`.
+- `destroy()` — detach the listener and drop subscriptions (idempotent).
+
+**Send queueing.** With `queueUntilReady` (default `true`), any send before the webview
+reports `form_load_complete` is buffered and flushed, in order, on load — so calling
+`prefillInfo(...)` right after mount won't be silently dropped. A client that attaches
+_after_ the form already loaded won't observe `form_load_complete`; either create the
+client with the iframe, or pass `queueUntilReady: false` to send immediately. The
+one-shot `/promises` helpers set `queueUntilReady: false` automatically.
+
+### Security note
+
+Always set `targetOrigin` to the webview's origin in production. With the default
+`"*"`, the client accepts messages from any origin and posts without an origin check —
+acceptable only for trusted/local development. `targetOriginFromUrl(embedUrl)` derives
+it from the URL you built.
+
+## Promise helpers — `@captello/ulc-webview-sdk/promises`
+
+A separate entry point with one-shot, `await`-style helpers for imperative flows.
+Where `CaptelloWebview` is a long-lived client you subscribe to, these take an iframe
+directly, create a short-lived client internally, wait for the relevant message, and
+tear it down — convenient when you just want to "submit and get the body" without
+managing a client instance.
+
+```ts
+import { submitForm, waitForFormLoad, waitForMessage, SubmissionError } from "@captello/ulc-webview-sdk/promises";
+import { OutboundMessageType } from "@captello/ulc-webview-sdk";
+
+await waitForFormLoad(iframe, { targetOrigin }); // resolves on form_load_complete
+
+try {
+    const body = await submitForm(iframe, { targetOrigin }); // submit + await result
+    await persist(body);
+} catch (err) {
+    if (err instanceof SubmissionError) showToast(err.message);
+}
+
+// generic: await the next message of any outbound type
+const msg = await waitForMessage(iframe, OutboundMessageType.SubmissionBody, { targetOrigin });
+```
+
+| Helper                               | Resolves / rejects                                                                                         |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `submitForm(frame, opts?)`           | resolves `SubmissionBody`; rejects `SubmissionError` (on `form_error_message`) or `SubmissionTimeoutError` |
+| `waitForFormLoad(frame, opts?)`      | resolves `void` on `form_load_complete`; rejects `MessageTimeoutError`                                     |
+| `waitForMessage(frame, type, opts?)` | resolves the typed message; rejects `MessageTimeoutError`                                                  |
+
+`opts` is `{ targetOrigin?, hostWindow?, matchSource?, timeoutMs? }` (`timeoutMs`
+defaults to 60_000; `0`/`Infinity` waits indefinitely). All helpers remove their
+internal listener before settling, including on timeout.
+
+> Note: these catch a _future_ message. If the form may already have loaded before you
+> call `waitForFormLoad` (e.g. you attach late), create a long-lived `CaptelloWebview`
+> before the iframe navigates instead.
+
+## Migrating an existing integration
+
+Host apps that integrated before this SDK typically hand-rolled the same three pieces:
+their own copy of the message-type strings, a manual `URLSearchParams` builder with the
+short keys, and ad-hoc `window.addEventListener("message")` / `iframe.contentWindow.postMessage`
+calls. Replace them as follows.
+
+**1. Message-type constants → SDK enums.** Delete local copies (e.g. `UlcFormActionTypeSent`,
+`UlcFormActionTypeReceived`, `UlcFormDataType`) and import `InboundMessageType`,
+`OutboundMessageType`, `PrefillDataType`.
+
+**2. Manual URL building → `buildEmbedUrl`.**
+
+```ts
+// before
+const src = `${base}/capture/submission?e=${token}&b=2&m=submit&launcher=event_gen_web` + (code ? `&l=${code}` : "");
+
+// after
+const src = buildEmbedUrl(`${base}/capture/submission`, {
+    eventWebAccessToken: token,
+    actionButtonPosition: ActionButtonPosition.Hidden,
+    mode: FormMode.Submit,
+    launcher: LauncherType.EventGenWeb,
+    language: code || undefined,
+});
+```
+
+**3. Manual listeners → `client.on(...)`.** Replace the `messageListener` +
+`safeJsonParse(e.data)` + `if (type === ...)` chain with typed subscriptions; the SDK
+parses, validates origin/source, and cleans up on `destroy()`.
+
+**4. Hand-rolled submit promise → `submitAndWait()`.** A common pattern is a custom
+promise that posts `submit_form`, listens for `submission_body`/`form_error_message`,
+dedupes listeners, and times out. That whole helper collapses to:
+
+```ts
+const body = await client.submitAndWait(); // throws SubmissionError on form_error_message
+```
+
+**5. `document.querySelector("#ulcForm").contentWindow.postMessage(...)` → client methods.**
+Hold the `CaptelloWebview` instance in a ref/context and call `submit()` / `reset()` /
+`prefillInfo()` instead of re-querying the DOM and stringifying messages by hand.
+
+**Prefill notes for migrators.** `prefillInfo` items are matched by
+`ll_field_unique_identifier`; `ll_field_id` is optional (number or string) and `value`
+may be a string or boolean — so existing payloads with numeric ids and boolean values
+type-check as-is. `prefillSubmission` accepts a loose `SubmissionPrefill`, so a
+previously-received `SubmissionBody` (or a partial `{ email?, data?, ... }`) can be passed
+back directly.
+
+**Out of scope.** If your app is _itself_ embedded inside the webview shell and talks to
+_its_ parent via `window.parent.postMessage` (e.g. relaying `email`/`clientId`, or custom
+`NAVIGATE_BACK` / scanner messages), that is a separate channel from the capture-form
+contract — keep that code; this SDK only models host ↔ capture-webview messaging.
+
+## Development
+
+```bash
+pnpm install   # from the repo root (pnpm workspace) or this package
+pnpm build     # bundle ESM + CJS + .d.ts into dist/
+pnpm typecheck
+```
+
+## License
+
+MIT © Lead Liaison, LLC. See [LICENSE](./LICENSE).

package/dist/chunk-ETF52K7K.js

@@ -0,0 +1,91 @@
+// src/embed-url.ts
+var EmbedParam = /* @__PURE__ */ ((EmbedParam2) => {
+  EmbedParam2["FormId"] = "f";
+  EmbedParam2["SubmissionToken"] = "s";
+  EmbedParam2["StationId"] = "st";
+  EmbedParam2["Mode"] = "m";
+  EmbedParam2["EventWebAccessToken"] = "e";
+  EmbedParam2["ActivationId"] = "a";
+  EmbedParam2["Language"] = "l";
+  EmbedParam2["ActionButtonPosition"] = "b";
+  EmbedParam2["FormType"] = "form_type";
+  EmbedParam2["Launcher"] = "launcher";
+  EmbedParam2["SubmissionType"] = "t";
+  EmbedParam2["SubmitButtonBottomPadding"] = "sbbp";
+  EmbedParam2["Platform"] = "platform";
+  EmbedParam2["HideEmail"] = "he";
+  EmbedParam2["ConnexionsEmbedMode"] = "cem";
+  EmbedParam2["Emro"] = "emro";
+  EmbedParam2["UseIn"] = "useIn";
+  return EmbedParam2;
+})(EmbedParam || {});
+var FormMode = /* @__PURE__ */ ((FormMode2) => {
+  FormMode2["Preview"] = "preview";
+  FormMode2["Submit"] = "submit";
+  FormMode2["Edit"] = "edit";
+  FormMode2["View"] = "view";
+  return FormMode2;
+})(FormMode || {});
+var LauncherType = /* @__PURE__ */ ((LauncherType2) => {
+  LauncherType2["EventGenMobile"] = "event_gen_mobile";
+  LauncherType2["EventGenWeb"] = "event_gen_web";
+  LauncherType2["WebApp"] = "webapp";
+  LauncherType2["Mmp"] = "MMP";
+  return LauncherType2;
+})(LauncherType || {});
+var ActionButtonPosition = /* @__PURE__ */ ((ActionButtonPosition2) => {
+  ActionButtonPosition2["Fixed"] = "0";
+  ActionButtonPosition2["Bottom"] = "1";
+  ActionButtonPosition2["Hidden"] = "2";
+  return ActionButtonPosition2;
+})(ActionButtonPosition || {});
+var OPTION_TO_PARAM = [
+  ["formId", "f" /* FormId */],
+  ["submissionToken", "s" /* SubmissionToken */],
+  ["stationId", "st" /* StationId */],
+  ["mode", "m" /* Mode */],
+  ["eventWebAccessToken", "e" /* EventWebAccessToken */],
+  ["activationId", "a" /* ActivationId */],
+  ["language", "l" /* Language */],
+  ["actionButtonPosition", "b" /* ActionButtonPosition */],
+  ["formType", "form_type" /* FormType */],
+  ["launcher", "launcher" /* Launcher */],
+  ["submissionType", "t" /* SubmissionType */],
+  ["submitButtonBottomPadding", "sbbp" /* SubmitButtonBottomPadding */],
+  ["useIn", "useIn" /* UseIn */],
+  ["platform", "platform" /* Platform */]
+];
+var BOOLEAN_OPTION_TO_PARAM = [
+  ["hideEmail", "he" /* HideEmail */],
+  ["connexionsEmbedMode", "cem" /* ConnexionsEmbedMode */],
+  ["emro", "emro" /* Emro */]
+];
+function buildEmbedUrl(baseUrl, options = {}) {
+  const url = new URL(baseUrl);
+  for (const [optionKey, paramKey] of OPTION_TO_PARAM) {
+    const value = options[optionKey];
+    if (value !== void 0 && value !== null && value !== "") {
+      url.searchParams.set(paramKey, String(value));
+    }
+  }
+  for (const [optionKey, paramKey] of BOOLEAN_OPTION_TO_PARAM) {
+    if (options[optionKey]) {
+      url.searchParams.set(paramKey, "1");
+    }
+  }
+  if (options.extraParams) {
+    for (const [key, value] of Object.entries(options.extraParams)) {
+      if (value !== void 0 && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function targetOriginFromUrl(embedUrl) {
+  return new URL(embedUrl).origin;
+}
+
+export { ActionButtonPosition, EmbedParam, FormMode, LauncherType, buildEmbedUrl, targetOriginFromUrl };
+//# sourceMappingURL=chunk-ETF52K7K.js.map
+//# sourceMappingURL=chunk-ETF52K7K.js.map

package/dist/chunk-ETF52K7K.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embed-url.ts"],"names":["EmbedParam","FormMode","LauncherType","ActionButtonPosition"],"mappings":";AAUO,IAAK,UAAA,qBAAAA,WAAAA,KAAL;AACH,EAAAA,YAAA,QAAA,CAAA,GAAS,GAAA;AACT,EAAAA,YAAA,iBAAA,CAAA,GAAkB,GAAA;AAClB,EAAAA,YAAA,WAAA,CAAA,GAAY,IAAA;AACZ,EAAAA,YAAA,MAAA,CAAA,GAAO,GAAA;AACP,EAAAA,YAAA,qBAAA,CAAA,GAAsB,GAAA;AACtB,EAAAA,YAAA,cAAA,CAAA,GAAe,GAAA;AACf,EAAAA,YAAA,UAAA,CAAA,GAAW,GAAA;AACX,EAAAA,YAAA,sBAAA,CAAA,GAAuB,GAAA;AACvB,EAAAA,YAAA,UAAA,CAAA,GAAW,WAAA;AACX,EAAAA,YAAA,UAAA,CAAA,GAAW,UAAA;AACX,EAAAA,YAAA,gBAAA,CAAA,GAAiB,GAAA;AACjB,EAAAA,YAAA,2BAAA,CAAA,GAA4B,MAAA;AAC5B,EAAAA,YAAA,UAAA,CAAA,GAAW,UAAA;AACX,EAAAA,YAAA,WAAA,CAAA,GAAY,IAAA;AACZ,EAAAA,YAAA,qBAAA,CAAA,GAAsB,KAAA;AAEtB,EAAAA,YAAA,MAAA,CAAA,GAAO,MAAA;AAEP,EAAAA,YAAA,OAAA,CAAA,GAAQ,OAAA;AAnBA,EAAA,OAAAA,WAAAA;AAAA,CAAA,EAAA,UAAA,IAAA,EAAA;AAuBL,IAAK,QAAA,qBAAAC,SAAAA,KAAL;AACH,EAAAA,UAAA,SAAA,CAAA,GAAU,SAAA;AACV,EAAAA,UAAA,QAAA,CAAA,GAAS,QAAA;AACT,EAAAA,UAAA,MAAA,CAAA,GAAO,MAAA;AACP,EAAAA,UAAA,MAAA,CAAA,GAAO,MAAA;AAJC,EAAA,OAAAA,SAAAA;AAAA,CAAA,EAAA,QAAA,IAAA,EAAA;AAQL,IAAK,YAAA,qBAAAC,aAAAA,KAAL;AACH,EAAAA,cAAA,gBAAA,CAAA,GAAiB,kBAAA;AACjB,EAAAA,cAAA,aAAA,CAAA,GAAc,eAAA;AACd,EAAAA,cAAA,QAAA,CAAA,GAAS,QAAA;AACT,EAAAA,cAAA,KAAA,CAAA,GAAM,KAAA;AAJE,EAAA,OAAAA,aAAAA;AAAA,CAAA,EAAA,YAAA,IAAA,EAAA;AAkBL,IAAK,oBAAA,qBAAAC,qBAAAA,KAAL;AACH,EAAAA,sBAAA,OAAA,CAAA,GAAQ,GAAA;AACR,EAAAA,sBAAA,QAAA,CAAA,GAAS,GAAA;AACT,EAAAA,sBAAA,QAAA,CAAA,GAAS,GAAA;AAHD,EAAA,OAAAA,qBAAAA;AAAA,CAAA,EAAA,oBAAA,IAAA,EAAA;AA6CZ,IAAM,eAAA,GAAsE;AAAA,EACxE,CAAC,UAAU,GAAA,cAAiB;AAAA,EAC5B,CAAC,mBAAmB,GAAA,uBAA0B;AAAA,EAC9C,CAAC,aAAa,IAAA,iBAAoB;AAAA,EAClC,CAAC,QAAQ,GAAA,YAAe;AAAA,EACxB,CAAC,uBAAuB,GAAA,2BAA8B;AAAA,EACtD,CAAC,gBAAgB,GAAA,oBAAuB;AAAA,EACxC,CAAC,YAAY,GAAA,gBAAmB;AAAA,EAChC,CAAC,wBAAwB,GAAA,4BAA+B;AAAA,EACxD,CAAC,YAAY,WAAA,gBAAmB;AAAA,EAChC,CAAC,YAAY,UAAA,gBAAmB;AAAA,EAChC,CAAC,kBAAkB,GAAA,sBAAyB;AAAA,EAC5C,CAAC,6BAA6B,MAAA,iCAAoC;AAAA,EAClE,CAAC,SAAS,OAAA,aAAgB;AAAA,EAC1B,CAAC,YAAY,UAAA;AACjB,CAAA;AAIA,IAAM,uBAAA,GAA8E;AAAA,EAChF,CAAC,aAAa,IAAA,iBAAoB;AAAA,EAClC,CAAC,uBAAuB,KAAA,2BAA8B;AAAA,EACtD,CAAC,QAAQ,MAAA;AACb,CAAA;AAkBO,SAAS,aAAA,CAAc,OAAA,EAAiB,OAAA,GAA2B,EAAC,EAAW;AAClF,EAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,OAAO,CAAA;AAE3B,EAAA,KAAA,MAAW,CAAC,SAAA,EAAW,QAAQ,CAAA,IAAK,eAAA,EAAiB;AACjD,IAAA,MAAM,KAAA,GAAQ,QAAQ,SAAS,CAAA;AAC/B,IAAA,IAAI,KAAA,KAAU,MAAA,IAAa,KAAA,KAAU,IAAA,IAAQ,UAAU,EAAA,EAAI;AACvD,MAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,QAAA,EAAU,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,IAChD;AAAA,EACJ;AAEA,EAAA,KAAA,MAAW,CAAC,SAAA,EAAW,QAAQ,CAAA,IAAK,uBAAA,EAAyB;AACzD,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACpB,MAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,QAAA,EAAU,GAAG,CAAA;AAAA,IACtC;AAAA,EACJ;AAEA,EAAA,IAAI,QAAQ,WAAA,EAAa;AACrB,IAAA,KAAA,MAAW,CAAC,KAAK,KAAK,CAAA,IAAK,OAAO,OAAA,CAAQ,OAAA,CAAQ,WAAW,CAAA,EAAG;AAC5D,MAAA,IAAI,KAAA,KAAU,MAAA,IAAa,KAAA,KAAU,IAAA,EAAM;AACvC,QAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,GAAA,EAAK,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,MAC3C;AAAA,IACJ;AAAA,EACJ;AAEA,EAAA,OAAO,IAAI,QAAA,EAAS;AACxB;AAQO,SAAS,oBAAoB,QAAA,EAA0B;AAC1D,EAAA,OAAO,IAAI,GAAA,CAAI,QAAQ,CAAA,CAAE,MAAA;AAC7B","file":"chunk-ETF52K7K.js","sourcesContent":["/**\n * Builder for the Captello capture webview embed URL.\n *\n * The webview reads its configuration from query-string params. The short keys\n * below are the contract the webview expects (see the webview's `PARAMS` enum);\n * this builder maps friendly option names onto those keys so hosts never have to\n * hard-code `\"f\"`, `\"m\"`, etc.\n */\n\n/** Query-param keys understood by the webview. */\nexport enum EmbedParam {\n    FormId = \"f\",\n    SubmissionToken = \"s\",\n    StationId = \"st\",\n    Mode = \"m\",\n    EventWebAccessToken = \"e\",\n    ActivationId = \"a\",\n    Language = \"l\",\n    ActionButtonPosition = \"b\",\n    FormType = \"form_type\",\n    Launcher = \"launcher\",\n    SubmissionType = \"t\",\n    SubmitButtonBottomPadding = \"sbbp\",\n    Platform = \"platform\",\n    HideEmail = \"he\",\n    ConnexionsEmbedMode = \"cem\",\n    /** Edit mode read-only: locks email-mapped and invitation-code elements. */\n    Emro = \"emro\",\n    /** Context for filtering form-fill actions (e.g. MMP outbound/inbound/notes). */\n    UseIn = \"useIn\",\n}\n\n/** Form render mode (the webview's `FormMode`). */\nexport enum FormMode {\n    Preview = \"preview\",\n    Submit = \"submit\",\n    Edit = \"edit\",\n    View = \"view\",\n}\n\n/** Identifies the host embedding the webview (the webview's `LAUNCHER_TYPES`). */\nexport enum LauncherType {\n    EventGenMobile = \"event_gen_mobile\",\n    EventGenWeb = \"event_gen_web\",\n    WebApp = \"webapp\",\n    Mmp = \"MMP\",\n}\n\n/** `form_type` discriminator. */\nexport type FormType = \"template\" | \"device\";\n\n/** `t` (submission type) discriminator. */\nexport type SubmissionType = \"normal\" | \"drafted\";\n\n/**\n * Action-button position param (`b`), mirroring the webview's `CTABtnPosition`.\n * The wire values are numeric strings; use {@link ActionButtonPosition} for the\n * readable names.\n */\nexport enum ActionButtonPosition {\n    Fixed = \"0\",\n    Bottom = \"1\",\n    Hidden = \"2\",\n}\n\n/** Context for filtering form-fill actions, sent as the `useIn` param. */\nexport type UseInContext = \"outbound\" | \"inbound\" | \"notes\";\n\n/**\n * Options for {@link buildEmbedUrl}. Every field is optional; only the ones you set\n * are written to the URL. `formId` is effectively required for a real embed but is\n * left optional so callers can build preview/partial URLs.\n */\nexport interface EmbedUrlOptions {\n    formId?: string | number;\n    submissionToken?: string;\n    stationId?: string | number;\n    mode?: FormMode;\n    eventWebAccessToken?: string;\n    activationId?: string | number;\n    /** Two-letter language code, e.g. `\"en\"`, `\"de\"`. */\n    language?: string;\n    actionButtonPosition?: ActionButtonPosition;\n    formType?: FormType;\n    launcher?: LauncherType;\n    submissionType?: SubmissionType;\n    submitButtonBottomPadding?: string | number;\n    /** Context for filtering form-fill actions (the `useIn` param). */\n    useIn?: UseInContext;\n    platform?: \"web\" | \"mobile\";\n    hideEmail?: boolean;\n    /** Connexions embed mode: suppress in-webview redirect/vCard download. */\n    connexionsEmbedMode?: boolean;\n    /** Edit mode read-only. */\n    emro?: boolean;\n    /**\n     * Extra query params to append verbatim (e.g. prospect tracking params the\n     * webview forwards on submit). Values are stringified; `undefined`/`null` skipped.\n     */\n    extraParams?: Record<string, string | number | boolean | undefined | null>;\n}\n\n// Maps each option onto its query key. Order here defines the order params are\n// written, which keeps generated URLs stable and diffable.\nconst OPTION_TO_PARAM: ReadonlyArray<[keyof EmbedUrlOptions, EmbedParam]> = [\n    [\"formId\", EmbedParam.FormId],\n    [\"submissionToken\", EmbedParam.SubmissionToken],\n    [\"stationId\", EmbedParam.StationId],\n    [\"mode\", EmbedParam.Mode],\n    [\"eventWebAccessToken\", EmbedParam.EventWebAccessToken],\n    [\"activationId\", EmbedParam.ActivationId],\n    [\"language\", EmbedParam.Language],\n    [\"actionButtonPosition\", EmbedParam.ActionButtonPosition],\n    [\"formType\", EmbedParam.FormType],\n    [\"launcher\", EmbedParam.Launcher],\n    [\"submissionType\", EmbedParam.SubmissionType],\n    [\"submitButtonBottomPadding\", EmbedParam.SubmitButtonBottomPadding],\n    [\"useIn\", EmbedParam.UseIn],\n    [\"platform\", EmbedParam.Platform],\n];\n\n// Boolean flags are encoded as \"1\" when true and omitted when false/unset, matching\n// how the webview reads them (`Boolean(queryParams[key])` / presence checks).\nconst BOOLEAN_OPTION_TO_PARAM: ReadonlyArray<[keyof EmbedUrlOptions, EmbedParam]> = [\n    [\"hideEmail\", EmbedParam.HideEmail],\n    [\"connexionsEmbedMode\", EmbedParam.ConnexionsEmbedMode],\n    [\"emro\", EmbedParam.Emro],\n];\n\n/**\n * Builds an absolute embed URL from a base capture URL and typed options.\n *\n * Existing query params on `baseUrl` are preserved; options override params with\n * the same key. The base may be any capture origin/path, e.g.\n * `\"https://capture.captello.com/\"`.\n *\n * @example\n * buildEmbedUrl(\"https://capture.captello.com/\", {\n *   formId: 1234,\n *   mode: FormMode.Submit,\n *   launcher: LauncherType.EventGenWeb,\n *   language: \"en\",\n * });\n * // → \"https://capture.captello.com/?f=1234&m=submit&launcher=event_gen_web&l=en\"\n */\nexport function buildEmbedUrl(baseUrl: string, options: EmbedUrlOptions = {}): string {\n    const url = new URL(baseUrl);\n\n    for (const [optionKey, paramKey] of OPTION_TO_PARAM) {\n        const value = options[optionKey];\n        if (value !== undefined && value !== null && value !== \"\") {\n            url.searchParams.set(paramKey, String(value));\n        }\n    }\n\n    for (const [optionKey, paramKey] of BOOLEAN_OPTION_TO_PARAM) {\n        if (options[optionKey]) {\n            url.searchParams.set(paramKey, \"1\");\n        }\n    }\n\n    if (options.extraParams) {\n        for (const [key, value] of Object.entries(options.extraParams)) {\n            if (value !== undefined && value !== null) {\n                url.searchParams.set(key, String(value));\n            }\n        }\n    }\n\n    return url.toString();\n}\n\n/**\n * Extracts the origin of an embed URL — convenient for passing as the client's\n * `targetOrigin` so messages are scoped to the webview's origin.\n *\n * @example targetOriginFromUrl(\"https://capture.captello.com/?f=1\") // \"https://capture.captello.com\"\n */\nexport function targetOriginFromUrl(embedUrl: string): string {\n    return new URL(embedUrl).origin;\n}\n"]}