@captello/ulc-webview-sdk 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,108 @@
+import { RefCallback } from 'react';
+import { a as OutboundMessageMap, O as OutboundMessageType, d as OutboundMessage, C as CaptelloWebviewOptions, e as CaptelloWebview, V as ValidationTarget, P as PrefillInfoItem, f as SubmissionPrefill, S as SubmissionBody } from './client-3IBxKbIE.cjs';
+export { b as SubmissionError, c as SubmissionTimeoutError, U as Unsubscribe } from './client-3IBxKbIE.cjs';
+import { EmbedUrlOptions } from './index.cjs';
+
+/**
+ * React adapter for the Captello webview SDK — `@captello/ulc-webview-sdk/react`.
+ *
+ * {@link useCaptelloWebview} owns a {@link CaptelloWebview} for the lifetime of an
+ * iframe: it creates the client once the iframe mounts, wires the outbound messages
+ * you care about to typed callbacks, tracks readiness, and destroys the client on
+ * unmount. You get back `iframeProps` to spread onto your `<iframe>` (or a bare `ref`),
+ * an `isReady` flag, and stable senders (`submit`, `reset`, `prefillInfo`, …).
+ *
+ * Sends made before the form loads are queued by the client and flushed on
+ * `form_load_complete`, so you can call `prefillInfo(...)` as soon as you have data —
+ * no need to gate on readiness yourself.
+ *
+ * Callbacks are held in a ref and always called fresh, so you do NOT need to memoize
+ * them — passing inline arrow functions will not re-subscribe or re-create the client.
+ *
+ * `react` is an optional peer dependency; importing this entry point requires React 18+.
+ *
+ * @example
+ * function UlcForm({ token, onSubmitted }: { token: string; onSubmitted: (b: SubmissionBody) => void }) {
+ *   const { iframeProps, isReady, submit } = useCaptelloWebview({
+ *     embedUrl: {
+ *       baseUrl: "https://capture.captello.com/capture/submission",
+ *       eventWebAccessToken: token,
+ *       mode: FormMode.Submit,
+ *       launcher: LauncherType.EventGenWeb,
+ *     },
+ *     onSubmissionBody: (m) => onSubmitted(m.data),
+ *   });
+ *   return (
+ *     <>
+ *       {!isReady && <Spinner />}
+ *       <iframe {...iframeProps} title="UlcForm" allow="camera; microphone" />
+ *       <button onClick={submit}>Submit</button>
+ *     </>
+ *   );
+ * }
+ */
+
+/** Per-message-type callback props accepted by {@link useCaptelloWebview}. */
+interface CaptelloWebviewCallbacks {
+    onFormLoadComplete?: (message: OutboundMessageMap[OutboundMessageType.FormLoadComplete]) => void;
+    onFormErrorMessage?: (message: OutboundMessageMap[OutboundMessageType.FormErrorMessage]) => void;
+    onSubmissionBody?: (message: OutboundMessageMap[OutboundMessageType.SubmissionBody]) => void;
+    onFormSubmitSuccess?: (message: OutboundMessageMap[OutboundMessageType.FormSubmitSuccess]) => void;
+    onConnexionsProfileRedirect?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsProfileRedirect]) => void;
+    onConnexionsDownloadVcard?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsDownloadVcard]) => void;
+    /** Catch-all: called for every outbound message, after the specific handler above. */
+    onAnyMessage?: (message: OutboundMessage) => void;
+}
+/** Embed-URL config: a base URL plus {@link EmbedUrlOptions}. */
+interface EmbedUrlConfig extends EmbedUrlOptions {
+    /** The capture base URL, e.g. `"https://capture.captello.com/capture/submission"`. */
+    baseUrl: string;
+}
+/**
+ * Options for {@link useCaptelloWebview}.
+ *
+ * Provide **either** `embedUrl` (the hook builds the URL and derives `targetOrigin`,
+ * returning `iframeProps.src`) **or** your own `targetOrigin` (you set the iframe `src`
+ * yourself). Plus message callbacks and the usual client options.
+ */
+interface UseCaptelloWebviewOptions extends CaptelloWebviewOptions, CaptelloWebviewCallbacks {
+    /** Build the iframe URL and derive `targetOrigin` from it. Sets `iframeProps.src`. */
+    embedUrl?: EmbedUrlConfig;
+}
+/** Readiness of the embedded form. */
+type CaptelloWebviewStatus = "loading" | "ready" | "error";
+/** Props to spread onto the `<iframe>`. `src` is present only when `embedUrl` is given. */
+interface CaptelloIframeProps {
+    ref: RefCallback<HTMLIFrameElement | null>;
+    src?: string;
+}
+/** What {@link useCaptelloWebview} returns. */
+interface UseCaptelloWebviewResult {
+    /** Spread onto your iframe: `<iframe {...iframeProps} />`. Includes `src` if `embedUrl` was given. */
+    iframeProps: CaptelloIframeProps;
+    /** The iframe ref callback (same as `iframeProps.ref`), if you'd rather set `src` yourself. */
+    ref: RefCallback<HTMLIFrameElement | null>;
+    /** `true` once the form has reported `form_load_complete`. */
+    isReady: boolean;
+    /** `"loading"` → `"ready"`; flips to `"error"` if a `form_error_message` arrives. */
+    status: CaptelloWebviewStatus;
+    /** The live client, or `null` before the iframe mounts. For escape-hatch use. */
+    getClient: () => CaptelloWebview | null;
+    submit: () => void;
+    reset: () => void;
+    updateDraft: () => void;
+    triggerValidation: (target: ValidationTarget) => void;
+    prefillInfo: (info: PrefillInfoItem[]) => void;
+    prefillSubmission: (submission: SubmissionPrefill) => void;
+    prefillSubmissionAndInfo: (data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    }) => void;
+    submitAndWait: (timeoutMs?: number) => Promise<SubmissionBody>;
+}
+/**
+ * Binds a {@link CaptelloWebview} to an iframe's lifecycle. See the module doc for usage.
+ */
+declare function useCaptelloWebview(options: UseCaptelloWebviewOptions): UseCaptelloWebviewResult;
+
+export { type CaptelloIframeProps, CaptelloWebview, type CaptelloWebviewCallbacks, type CaptelloWebviewStatus, type EmbedUrlConfig, type UseCaptelloWebviewOptions, type UseCaptelloWebviewResult, useCaptelloWebview };

package/dist/react.d.ts

@@ -0,0 +1,108 @@
+import { RefCallback } from 'react';
+import { a as OutboundMessageMap, O as OutboundMessageType, d as OutboundMessage, C as CaptelloWebviewOptions, e as CaptelloWebview, V as ValidationTarget, P as PrefillInfoItem, f as SubmissionPrefill, S as SubmissionBody } from './client-3IBxKbIE.js';
+export { b as SubmissionError, c as SubmissionTimeoutError, U as Unsubscribe } from './client-3IBxKbIE.js';
+import { EmbedUrlOptions } from './index.js';
+
+/**
+ * React adapter for the Captello webview SDK — `@captello/ulc-webview-sdk/react`.
+ *
+ * {@link useCaptelloWebview} owns a {@link CaptelloWebview} for the lifetime of an
+ * iframe: it creates the client once the iframe mounts, wires the outbound messages
+ * you care about to typed callbacks, tracks readiness, and destroys the client on
+ * unmount. You get back `iframeProps` to spread onto your `<iframe>` (or a bare `ref`),
+ * an `isReady` flag, and stable senders (`submit`, `reset`, `prefillInfo`, …).
+ *
+ * Sends made before the form loads are queued by the client and flushed on
+ * `form_load_complete`, so you can call `prefillInfo(...)` as soon as you have data —
+ * no need to gate on readiness yourself.
+ *
+ * Callbacks are held in a ref and always called fresh, so you do NOT need to memoize
+ * them — passing inline arrow functions will not re-subscribe or re-create the client.
+ *
+ * `react` is an optional peer dependency; importing this entry point requires React 18+.
+ *
+ * @example
+ * function UlcForm({ token, onSubmitted }: { token: string; onSubmitted: (b: SubmissionBody) => void }) {
+ *   const { iframeProps, isReady, submit } = useCaptelloWebview({
+ *     embedUrl: {
+ *       baseUrl: "https://capture.captello.com/capture/submission",
+ *       eventWebAccessToken: token,
+ *       mode: FormMode.Submit,
+ *       launcher: LauncherType.EventGenWeb,
+ *     },
+ *     onSubmissionBody: (m) => onSubmitted(m.data),
+ *   });
+ *   return (
+ *     <>
+ *       {!isReady && <Spinner />}
+ *       <iframe {...iframeProps} title="UlcForm" allow="camera; microphone" />
+ *       <button onClick={submit}>Submit</button>
+ *     </>
+ *   );
+ * }
+ */
+
+/** Per-message-type callback props accepted by {@link useCaptelloWebview}. */
+interface CaptelloWebviewCallbacks {
+    onFormLoadComplete?: (message: OutboundMessageMap[OutboundMessageType.FormLoadComplete]) => void;
+    onFormErrorMessage?: (message: OutboundMessageMap[OutboundMessageType.FormErrorMessage]) => void;
+    onSubmissionBody?: (message: OutboundMessageMap[OutboundMessageType.SubmissionBody]) => void;
+    onFormSubmitSuccess?: (message: OutboundMessageMap[OutboundMessageType.FormSubmitSuccess]) => void;
+    onConnexionsProfileRedirect?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsProfileRedirect]) => void;
+    onConnexionsDownloadVcard?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsDownloadVcard]) => void;
+    /** Catch-all: called for every outbound message, after the specific handler above. */
+    onAnyMessage?: (message: OutboundMessage) => void;
+}
+/** Embed-URL config: a base URL plus {@link EmbedUrlOptions}. */
+interface EmbedUrlConfig extends EmbedUrlOptions {
+    /** The capture base URL, e.g. `"https://capture.captello.com/capture/submission"`. */
+    baseUrl: string;
+}
+/**
+ * Options for {@link useCaptelloWebview}.
+ *
+ * Provide **either** `embedUrl` (the hook builds the URL and derives `targetOrigin`,
+ * returning `iframeProps.src`) **or** your own `targetOrigin` (you set the iframe `src`
+ * yourself). Plus message callbacks and the usual client options.
+ */
+interface UseCaptelloWebviewOptions extends CaptelloWebviewOptions, CaptelloWebviewCallbacks {
+    /** Build the iframe URL and derive `targetOrigin` from it. Sets `iframeProps.src`. */
+    embedUrl?: EmbedUrlConfig;
+}
+/** Readiness of the embedded form. */
+type CaptelloWebviewStatus = "loading" | "ready" | "error";
+/** Props to spread onto the `<iframe>`. `src` is present only when `embedUrl` is given. */
+interface CaptelloIframeProps {
+    ref: RefCallback<HTMLIFrameElement | null>;
+    src?: string;
+}
+/** What {@link useCaptelloWebview} returns. */
+interface UseCaptelloWebviewResult {
+    /** Spread onto your iframe: `<iframe {...iframeProps} />`. Includes `src` if `embedUrl` was given. */
+    iframeProps: CaptelloIframeProps;
+    /** The iframe ref callback (same as `iframeProps.ref`), if you'd rather set `src` yourself. */
+    ref: RefCallback<HTMLIFrameElement | null>;
+    /** `true` once the form has reported `form_load_complete`. */
+    isReady: boolean;
+    /** `"loading"` → `"ready"`; flips to `"error"` if a `form_error_message` arrives. */
+    status: CaptelloWebviewStatus;
+    /** The live client, or `null` before the iframe mounts. For escape-hatch use. */
+    getClient: () => CaptelloWebview | null;
+    submit: () => void;
+    reset: () => void;
+    updateDraft: () => void;
+    triggerValidation: (target: ValidationTarget) => void;
+    prefillInfo: (info: PrefillInfoItem[]) => void;
+    prefillSubmission: (submission: SubmissionPrefill) => void;
+    prefillSubmissionAndInfo: (data: {
+        submission?: SubmissionPrefill;
+        info?: PrefillInfoItem[];
+    }) => void;
+    submitAndWait: (timeoutMs?: number) => Promise<SubmissionBody>;
+}
+/**
+ * Binds a {@link CaptelloWebview} to an iframe's lifecycle. See the module doc for usage.
+ */
+declare function useCaptelloWebview(options: UseCaptelloWebviewOptions): UseCaptelloWebviewResult;
+
+export { type CaptelloIframeProps, CaptelloWebview, type CaptelloWebviewCallbacks, type CaptelloWebviewStatus, type EmbedUrlConfig, type UseCaptelloWebviewOptions, type UseCaptelloWebviewResult, useCaptelloWebview };

package/dist/react.js

@@ -0,0 +1,112 @@
+import { buildEmbedUrl, targetOriginFromUrl } from './chunk-ETF52K7K.js';
+import { CaptelloWebview, OutboundMessageType } from './chunk-ZMYMZK2A.js';
+export { CaptelloWebview, SubmissionError, SubmissionTimeoutError } from './chunk-ZMYMZK2A.js';
+import { useRef, useState, useCallback, useEffect } from 'react';
+
+var CALLBACK_BY_TYPE = {
+  ["form_load_complete" /* FormLoadComplete */]: "onFormLoadComplete",
+  ["form_error_message" /* FormErrorMessage */]: "onFormErrorMessage",
+  ["submission_body" /* SubmissionBody */]: "onSubmissionBody",
+  ["form_submit_success" /* FormSubmitSuccess */]: "onFormSubmitSuccess",
+  ["connexions_profile_redirect" /* ConnexionsProfileRedirect */]: "onConnexionsProfileRedirect",
+  ["connexions_download_vcard" /* ConnexionsDownloadVcard */]: "onConnexionsDownloadVcard"
+};
+function useCaptelloWebview(options) {
+  const { embedUrl, matchSource, queueUntilReady, hostWindow } = options;
+  const src = embedUrl ? buildEmbedUrl(embedUrl.baseUrl, embedUrl) : void 0;
+  const targetOrigin = src ? targetOriginFromUrl(src) : options.targetOrigin;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const clientRef = useRef(null);
+  const frameRef = useRef(null);
+  const teardown = useRef(null);
+  const [status, setStatus] = useState("loading");
+  const attach = useCallback(
+    (frame) => {
+      teardown.current?.();
+      teardown.current = null;
+      clientRef.current = null;
+      frameRef.current = frame;
+      setStatus("loading");
+      if (!frame) return;
+      const client = new CaptelloWebview(frame, {
+        targetOrigin,
+        hostWindow: optionsRef.current.hostWindow,
+        matchSource: optionsRef.current.matchSource,
+        queueUntilReady: optionsRef.current.queueUntilReady
+      });
+      clientRef.current = client;
+      const offs = [];
+      for (const type of Object.values(OutboundMessageType)) {
+        offs.push(
+          client.on(type, (message) => {
+            if (type === "form_load_complete" /* FormLoadComplete */) setStatus("ready");
+            else if (type === "form_error_message" /* FormErrorMessage */) setStatus("error");
+            const handler = optionsRef.current[CALLBACK_BY_TYPE[type]];
+            handler?.(message);
+            optionsRef.current.onAnyMessage?.(message);
+          })
+        );
+      }
+      teardown.current = () => {
+        for (const off of offs) off();
+        client.destroy();
+      };
+    },
+    // Re-create the client only when connection-level inputs change.
+    // Callbacks are read via optionsRef, so they intentionally aren't deps.
+    [targetOrigin, matchSource, queueUntilReady, hostWindow]
+  );
+  useEffect(() => {
+    if (frameRef.current) attach(frameRef.current);
+    return () => {
+      teardown.current?.();
+      teardown.current = null;
+      clientRef.current = null;
+    };
+  }, [attach]);
+  const getClient = useCallback(() => clientRef.current, []);
+  const submit = useCallback(() => clientRef.current?.submit(), []);
+  const reset = useCallback(() => clientRef.current?.reset(), []);
+  const updateDraft = useCallback(() => clientRef.current?.updateDraft(), []);
+  const triggerValidation = useCallback(
+    (target) => clientRef.current?.triggerValidation(target),
+    []
+  );
+  const prefillInfo = useCallback((info) => clientRef.current?.prefillInfo(info), []);
+  const prefillSubmission = useCallback(
+    (submission) => clientRef.current?.prefillSubmission(submission),
+    []
+  );
+  const prefillSubmissionAndInfo = useCallback(
+    (data) => clientRef.current?.prefillSubmissionAndInfo(data),
+    []
+  );
+  const submitAndWait = useCallback((timeoutMs) => {
+    const client = clientRef.current;
+    if (!client) {
+      return Promise.reject(new Error("CaptelloWebview: iframe is not mounted yet."));
+    }
+    return client.submitAndWait(timeoutMs);
+  }, []);
+  const iframeProps = src ? { ref: attach, src } : { ref: attach };
+  return {
+    iframeProps,
+    ref: attach,
+    isReady: status === "ready",
+    status,
+    getClient,
+    submit,
+    reset,
+    updateDraft,
+    triggerValidation,
+    prefillInfo,
+    prefillSubmission,
+    prefillSubmissionAndInfo,
+    submitAndWait
+  };
+}
+
+export { useCaptelloWebview };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react.ts"],"names":[],"mappings":"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","file":"react.js","sourcesContent":["/**\n * React adapter for the Captello webview SDK — `@captello/ulc-webview-sdk/react`.\n *\n * {@link useCaptelloWebview} owns a {@link CaptelloWebview} for the lifetime of an\n * iframe: it creates the client once the iframe mounts, wires the outbound messages\n * you care about to typed callbacks, tracks readiness, and destroys the client on\n * unmount. You get back `iframeProps` to spread onto your `<iframe>` (or a bare `ref`),\n * an `isReady` flag, and stable senders (`submit`, `reset`, `prefillInfo`, …).\n *\n * Sends made before the form loads are queued by the client and flushed on\n * `form_load_complete`, so you can call `prefillInfo(...)` as soon as you have data —\n * no need to gate on readiness yourself.\n *\n * Callbacks are held in a ref and always called fresh, so you do NOT need to memoize\n * them — passing inline arrow functions will not re-subscribe or re-create the client.\n *\n * `react` is an optional peer dependency; importing this entry point requires React 18+.\n *\n * @example\n * function UlcForm({ token, onSubmitted }: { token: string; onSubmitted: (b: SubmissionBody) => void }) {\n *   const { iframeProps, isReady, submit } = useCaptelloWebview({\n *     embedUrl: {\n *       baseUrl: \"https://capture.captello.com/capture/submission\",\n *       eventWebAccessToken: token,\n *       mode: FormMode.Submit,\n *       launcher: LauncherType.EventGenWeb,\n *     },\n *     onSubmissionBody: (m) => onSubmitted(m.data),\n *   });\n *   return (\n *     <>\n *       {!isReady && <Spinner />}\n *       <iframe {...iframeProps} title=\"UlcForm\" allow=\"camera; microphone\" />\n *       <button onClick={submit}>Submit</button>\n *     </>\n *   );\n * }\n */\n\nimport { useCallback, useEffect, useRef, useState, type RefCallback } from \"react\";\n\nimport { CaptelloWebview } from \"./client\";\nimport type { CaptelloWebviewOptions, Unsubscribe } from \"./client\";\nimport { buildEmbedUrl, targetOriginFromUrl } from \"./embed-url\";\nimport type { EmbedUrlOptions } from \"./embed-url\";\nimport { OutboundMessageType } from \"./messages\";\nimport type {\n    OutboundMessage,\n    OutboundMessageMap,\n    PrefillInfoItem,\n    SubmissionBody,\n    SubmissionPrefill,\n    ValidationTarget,\n} from \"./messages\";\n\n/** Per-message-type callback props accepted by {@link useCaptelloWebview}. */\nexport interface CaptelloWebviewCallbacks {\n    onFormLoadComplete?: (message: OutboundMessageMap[OutboundMessageType.FormLoadComplete]) => void;\n    onFormErrorMessage?: (message: OutboundMessageMap[OutboundMessageType.FormErrorMessage]) => void;\n    onSubmissionBody?: (message: OutboundMessageMap[OutboundMessageType.SubmissionBody]) => void;\n    onFormSubmitSuccess?: (message: OutboundMessageMap[OutboundMessageType.FormSubmitSuccess]) => void;\n    onConnexionsProfileRedirect?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsProfileRedirect]) => void;\n    onConnexionsDownloadVcard?: (message: OutboundMessageMap[OutboundMessageType.ConnexionsDownloadVcard]) => void;\n    /** Catch-all: called for every outbound message, after the specific handler above. */\n    onAnyMessage?: (message: OutboundMessage) => void;\n}\n\n/** Embed-URL config: a base URL plus {@link EmbedUrlOptions}. */\nexport interface EmbedUrlConfig extends EmbedUrlOptions {\n    /** The capture base URL, e.g. `\"https://capture.captello.com/capture/submission\"`. */\n    baseUrl: string;\n}\n\n/**\n * Options for {@link useCaptelloWebview}.\n *\n * Provide **either** `embedUrl` (the hook builds the URL and derives `targetOrigin`,\n * returning `iframeProps.src`) **or** your own `targetOrigin` (you set the iframe `src`\n * yourself). Plus message callbacks and the usual client options.\n */\nexport interface UseCaptelloWebviewOptions extends CaptelloWebviewOptions, CaptelloWebviewCallbacks {\n    /** Build the iframe URL and derive `targetOrigin` from it. Sets `iframeProps.src`. */\n    embedUrl?: EmbedUrlConfig;\n}\n\n/** Readiness of the embedded form. */\nexport type CaptelloWebviewStatus = \"loading\" | \"ready\" | \"error\";\n\n/** Props to spread onto the `<iframe>`. `src` is present only when `embedUrl` is given. */\nexport interface CaptelloIframeProps {\n    ref: RefCallback<HTMLIFrameElement | null>;\n    src?: string;\n}\n\n/** What {@link useCaptelloWebview} returns. */\nexport interface UseCaptelloWebviewResult {\n    /** Spread onto your iframe: `<iframe {...iframeProps} />`. Includes `src` if `embedUrl` was given. */\n    iframeProps: CaptelloIframeProps;\n    /** The iframe ref callback (same as `iframeProps.ref`), if you'd rather set `src` yourself. */\n    ref: RefCallback<HTMLIFrameElement | null>;\n    /** `true` once the form has reported `form_load_complete`. */\n    isReady: boolean;\n    /** `\"loading\"` → `\"ready\"`; flips to `\"error\"` if a `form_error_message` arrives. */\n    status: CaptelloWebviewStatus;\n    /** The live client, or `null` before the iframe mounts. For escape-hatch use. */\n    getClient: () => CaptelloWebview | null;\n    submit: () => void;\n    reset: () => void;\n    updateDraft: () => void;\n    triggerValidation: (target: ValidationTarget) => void;\n    prefillInfo: (info: PrefillInfoItem[]) => void;\n    prefillSubmission: (submission: SubmissionPrefill) => void;\n    prefillSubmissionAndInfo: (data: { submission?: SubmissionPrefill; info?: PrefillInfoItem[] }) => void;\n    submitAndWait: (timeoutMs?: number) => Promise<SubmissionBody>;\n}\n\nconst CALLBACK_BY_TYPE: Record<OutboundMessageType, keyof CaptelloWebviewCallbacks> = {\n    [OutboundMessageType.FormLoadComplete]: \"onFormLoadComplete\",\n    [OutboundMessageType.FormErrorMessage]: \"onFormErrorMessage\",\n    [OutboundMessageType.SubmissionBody]: \"onSubmissionBody\",\n    [OutboundMessageType.FormSubmitSuccess]: \"onFormSubmitSuccess\",\n    [OutboundMessageType.ConnexionsProfileRedirect]: \"onConnexionsProfileRedirect\",\n    [OutboundMessageType.ConnexionsDownloadVcard]: \"onConnexionsDownloadVcard\",\n};\n\n/**\n * Binds a {@link CaptelloWebview} to an iframe's lifecycle. See the module doc for usage.\n */\nexport function useCaptelloWebview(options: UseCaptelloWebviewOptions): UseCaptelloWebviewResult {\n    const { embedUrl, matchSource, queueUntilReady, hostWindow } = options;\n\n    // Resolve the URL + the targetOrigin to use. embedUrl wins; otherwise use the\n    // explicit targetOrigin. Recompute only when the URL-affecting inputs change.\n    const src = embedUrl ? buildEmbedUrl(embedUrl.baseUrl, embedUrl) : undefined;\n    const targetOrigin = src ? targetOriginFromUrl(src) : options.targetOrigin;\n\n    // Latest options/callbacks, read fresh inside listeners so callers needn't memoize.\n    const optionsRef = useRef(options);\n    optionsRef.current = options;\n\n    const clientRef = useRef<CaptelloWebview | null>(null);\n    const frameRef = useRef<HTMLIFrameElement | null>(null);\n    const teardown = useRef<(() => void) | null>(null);\n\n    const [status, setStatus] = useState<CaptelloWebviewStatus>(\"loading\");\n\n    const attach = useCallback(\n        (frame: HTMLIFrameElement | null) => {\n            // Tear down any previous client (ref changed or unmounting).\n            teardown.current?.();\n            teardown.current = null;\n            clientRef.current = null;\n            frameRef.current = frame;\n            setStatus(\"loading\");\n\n            if (!frame) return;\n\n            const client = new CaptelloWebview(frame, {\n                targetOrigin,\n                hostWindow: optionsRef.current.hostWindow,\n                matchSource: optionsRef.current.matchSource,\n                queueUntilReady: optionsRef.current.queueUntilReady,\n            });\n            clientRef.current = client;\n\n            const offs: Unsubscribe[] = [];\n            for (const type of Object.values(OutboundMessageType)) {\n                offs.push(\n                    client.on(type, (message) => {\n                        if (type === OutboundMessageType.FormLoadComplete) setStatus(\"ready\");\n                        else if (type === OutboundMessageType.FormErrorMessage) setStatus(\"error\");\n\n                        const handler = optionsRef.current[CALLBACK_BY_TYPE[type]] as\n                            | ((m: typeof message) => void)\n                            | undefined;\n                        handler?.(message);\n                        optionsRef.current.onAnyMessage?.(message);\n                    }),\n                );\n            }\n\n            teardown.current = () => {\n                for (const off of offs) off();\n                client.destroy();\n            };\n        },\n        // Re-create the client only when connection-level inputs change.\n        // Callbacks are read via optionsRef, so they intentionally aren't deps.\n        [targetOrigin, matchSource, queueUntilReady, hostWindow],\n    );\n\n    useEffect(() => {\n        if (frameRef.current) attach(frameRef.current);\n        return () => {\n            teardown.current?.();\n            teardown.current = null;\n            clientRef.current = null;\n        };\n    }, [attach]);\n\n    const getClient = useCallback(() => clientRef.current, []);\n\n    const submit = useCallback(() => clientRef.current?.submit(), []);\n    const reset = useCallback(() => clientRef.current?.reset(), []);\n    const updateDraft = useCallback(() => clientRef.current?.updateDraft(), []);\n    const triggerValidation = useCallback(\n        (target: ValidationTarget) => clientRef.current?.triggerValidation(target),\n        [],\n    );\n    const prefillInfo = useCallback((info: PrefillInfoItem[]) => clientRef.current?.prefillInfo(info), []);\n    const prefillSubmission = useCallback(\n        (submission: SubmissionPrefill) => clientRef.current?.prefillSubmission(submission),\n        [],\n    );\n    const prefillSubmissionAndInfo = useCallback(\n        (data: { submission?: SubmissionPrefill; info?: PrefillInfoItem[] }) =>\n            clientRef.current?.prefillSubmissionAndInfo(data),\n        [],\n    );\n    const submitAndWait = useCallback((timeoutMs?: number) => {\n        const client = clientRef.current;\n        if (!client) {\n            return Promise.reject(new Error(\"CaptelloWebview: iframe is not mounted yet.\"));\n        }\n        return client.submitAndWait(timeoutMs);\n    }, []);\n\n    const iframeProps: CaptelloIframeProps = src ? { ref: attach, src } : { ref: attach };\n\n    return {\n        iframeProps,\n        ref: attach,\n        isReady: status === \"ready\",\n        status,\n        getClient,\n        submit,\n        reset,\n        updateDraft,\n        triggerValidation,\n        prefillInfo,\n        prefillSubmission,\n        prefillSubmissionAndInfo,\n        submitAndWait,\n    };\n}\n\nexport { CaptelloWebview, SubmissionError, SubmissionTimeoutError } from \"./client\";\nexport type { Unsubscribe } from \"./client\";\n"]}

package/package.json

@@ -0,0 +1,82 @@
+{
+    "name": "@captello/ulc-webview-sdk",
+    "version": "0.1.0",
+    "description": "Typed SDK for embedding the Captello capture webview: message protocol, host client, and embed-URL builder.",
+    "author": "Lead Liaison",
+    "license": "MIT",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "typesVersions": {
+        "*": {
+            "promises": [
+                "./dist/promises.d.ts"
+            ],
+            "react": [
+                "./dist/react.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        },
+        "./promises": {
+            "types": "./dist/promises.d.ts",
+            "import": "./dist/promises.js",
+            "require": "./dist/promises.cjs"
+        },
+        "./react": {
+            "types": "./dist/react.d.ts",
+            "import": "./dist/react.js",
+            "require": "./dist/react.cjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "typecheck": "tsc --noEmit",
+        "typecheck:test": "tsc -p tsconfig.test.json",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist"
+    },
+    "keywords": [
+        "captello",
+        "webview",
+        "iframe",
+        "postmessage",
+        "embed",
+        "sdk"
+    ],
+    "peerDependencies": {
+        "react": ">=18"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@testing-library/react": "16.1.0",
+        "@types/react": "19.2.2",
+        "jsdom": "25.0.1",
+        "react": "19.2.2",
+        "react-dom": "19.2.2",
+        "tsup": "8.3.5",
+        "typescript": "5.9.3",
+        "vitest": "2.1.9"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}