@captello/ulc-webview-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,594 @@
+'use strict';
+
+// src/messages.ts
+var OutboundMessageType = /* @__PURE__ */ ((OutboundMessageType2) => {
+  OutboundMessageType2["FormLoadComplete"] = "form_load_complete";
+  OutboundMessageType2["FormErrorMessage"] = "form_error_message";
+  OutboundMessageType2["SubmissionBody"] = "submission_body";
+  OutboundMessageType2["FormSubmitSuccess"] = "form_submit_success";
+  OutboundMessageType2["ConnexionsProfileRedirect"] = "connexions_profile_redirect";
+  OutboundMessageType2["ConnexionsDownloadVcard"] = "connexions_download_vcard";
+  return OutboundMessageType2;
+})(OutboundMessageType || {});
+var InboundMessageType = /* @__PURE__ */ ((InboundMessageType2) => {
+  InboundMessageType2["Submit"] = "submit_form";
+  InboundMessageType2["Reset"] = "reset_form";
+  InboundMessageType2["FormPrefill"] = "form_prefill";
+  InboundMessageType2["UpdateDraft"] = "update_draft";
+  InboundMessageType2["TriggerValidation"] = "trigger_validation";
+  return InboundMessageType2;
+})(InboundMessageType || {});
+var PrefillDataType = /* @__PURE__ */ ((PrefillDataType2) => {
+  PrefillDataType2["UlcSubmission"] = "ulc_submission";
+  PrefillDataType2["Info"] = "info";
+  PrefillDataType2["UlcSubmissionAndInfo"] = "ulc_submission_and_info";
+  return PrefillDataType2;
+})(PrefillDataType || {});
+var OUTBOUND_TYPES = new Set(Object.values(OutboundMessageType));
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseOutboundMessage(data) {
+  let value = data;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (!isPlainObject(value)) return null;
+  if (typeof value["type"] !== "string" || !OUTBOUND_TYPES.has(value["type"])) return null;
+  return value;
+}
+
+// src/client.ts
+var SubmissionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SubmissionError";
+  }
+};
+var SubmissionTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Captello webview did not respond to submit within ${timeoutMs}ms.`);
+    this.timeoutMs = timeoutMs;
+    this.name = "SubmissionTimeoutError";
+  }
+};
+function devWarn(message) {
+  try {
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production") {
+      console.warn(message);
+    }
+  } catch {
+  }
+}
+var CaptelloWebview = class {
+  constructor(frame, options = {}) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.anyListeners = /* @__PURE__ */ new Set();
+    this.destroyed = false;
+    /** True once `form_load_complete` has been observed. */
+    this.ready = false;
+    /** Messages sent before ready, flushed in order on load. */
+    this.outbox = [];
+    if (!frame) {
+      throw new Error("CaptelloWebview: an iframe element (or { contentWindow }) is required.");
+    }
+    this.frame = frame;
+    this.targetOrigin = options.targetOrigin ?? "*";
+    this.matchSource = options.matchSource ?? true;
+    this.queueUntilReady = options.queueUntilReady ?? true;
+    const hostWindow = options.hostWindow ?? (typeof window !== "undefined" ? window : void 0);
+    if (!hostWindow) {
+      throw new Error(
+        "CaptelloWebview: no host window available. Pass `hostWindow` when constructing outside a browser."
+      );
+    }
+    this.hostWindow = hostWindow;
+    this.boundHandler = (event) => this.handleMessage(event);
+    this.hostWindow.addEventListener("message", this.boundHandler);
+  }
+  /** `true` once the webview has reported `form_load_complete`. */
+  get isReady() {
+    return this.ready;
+  }
+  /* -------------------------------------------------------------- *
+   * Receiving (webview → host)
+   * -------------------------------------------------------------- */
+  /**
+   * Subscribe to a single outbound message type. Returns an unsubscribe function.
+   *
+   * @example webview.on(OutboundMessageType.FormErrorMessage, (m) => toast(m.data));
+   */
+  on(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+    return () => {
+      set?.delete(listener);
+    };
+  }
+  /**
+   * Subscribe once: the listener is removed automatically after it fires the first
+   * time for `type`. Returns an unsubscribe function for cancelling early.
+   */
+  once(type, listener) {
+    const off = this.on(type, (message) => {
+      off();
+      listener(message);
+    });
+    return off;
+  }
+  /** Subscribe to every outbound message regardless of type. Returns an unsubscribe function. */
+  onAny(listener) {
+    this.anyListeners.add(listener);
+    return () => {
+      this.anyListeners.delete(listener);
+    };
+  }
+  /* -------------------------------------------------------------- *
+   * Sending (host → webview)
+   * -------------------------------------------------------------- */
+  /**
+   * Low-level send: posts any inbound message to the webview as a JSON string.
+   * Prefer the typed helpers below; use this only for forward-compatibility.
+   *
+   * When `queueUntilReady` is enabled (the default) and the form hasn't reported
+   * `form_load_complete` yet, the message is buffered and flushed on load instead of
+   * posted immediately.
+   *
+   * @throws if the iframe's `contentWindow` is not available (not yet loaded /
+   *   detached) and the message can't be queued.
+   */
+  send(message) {
+    if (this.destroyed) {
+      throw new Error("CaptelloWebview: cannot send after destroy().");
+    }
+    if (this.queueUntilReady && !this.ready) {
+      this.outbox.push(message);
+      return;
+    }
+    this.postNow(message);
+  }
+  /** Posts a message immediately, bypassing the ready-queue. */
+  postNow(message) {
+    const target = this.frame.contentWindow;
+    if (!target) {
+      throw new Error(
+        "CaptelloWebview: iframe.contentWindow is null. Wait for the iframe to load before sending."
+      );
+    }
+    target.postMessage(JSON.stringify(message), this.targetOrigin);
+  }
+  /** Marks the client ready and flushes any queued messages, in order. */
+  markReadyAndFlush() {
+    if (this.ready) return;
+    this.ready = true;
+    const queued = this.outbox.splice(0);
+    for (const message of queued) {
+      try {
+        this.postNow(message);
+      } catch {
+      }
+    }
+  }
+  /** Programmatically submit the form (fire-and-forget). */
+  submit() {
+    this.send({ type: "submit_form" /* Submit */ });
+  }
+  /**
+   * Submit the form and await the outcome.
+   *
+   * Sends `submit_form`, then resolves with the {@link SubmissionBody} when the
+   * webview emits `submission_body`, or rejects with a {@link SubmissionError}
+   * (carrying the translated message) when it emits `form_error_message`. Rejects
+   * with a {@link SubmissionTimeoutError} if neither arrives within `timeoutMs`.
+   *
+   * This is the typed, leak-free version of the common "click submit, wait for the
+   * result" flow — listeners are always cleaned up, including on timeout.
+   *
+   * @param timeoutMs how long to wait before giving up. Defaults to 60_000.
+   * @example
+   * try {
+   *   const body = await webview.submitAndWait();
+   *   await persist(body);
+   * } catch (err) {
+   *   if (err instanceof SubmissionError) showToast(err.message);
+   * }
+   */
+  submitAndWait(timeoutMs = 6e4) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timer;
+      const cleanup = () => {
+        settled = true;
+        offSuccess();
+        offError();
+        if (timer !== void 0) clearTimeout(timer);
+      };
+      const offSuccess = this.on("submission_body" /* SubmissionBody */, (message) => {
+        if (settled) return;
+        cleanup();
+        resolve(message.data);
+      });
+      const offError = this.on("form_error_message" /* FormErrorMessage */, (message) => {
+        if (settled) return;
+        cleanup();
+        reject(new SubmissionError(message.data));
+      });
+      if (timeoutMs > 0 && timeoutMs !== Infinity) {
+        timer = setTimeout(() => {
+          if (settled) return;
+          cleanup();
+          reject(new SubmissionTimeoutError(timeoutMs));
+        }, timeoutMs);
+      }
+      try {
+        this.send({ type: "submit_form" /* Submit */ });
+      } catch (err) {
+        if (!settled) {
+          cleanup();
+          reject(err);
+        }
+      }
+    });
+  }
+  /** Reset the form, clearing all entered values. */
+  reset() {
+    this.send({ type: "reset_form" /* Reset */ });
+  }
+  /** Switch the current submission into draft-update mode. */
+  updateDraft() {
+    this.send({ type: "update_draft" /* UpdateDraft */ });
+  }
+  /** Run validation against a target field, or `"all"` for the whole form. */
+  triggerValidation(target) {
+    this.send({ type: "trigger_validation" /* TriggerValidation */, target });
+  }
+  /** Pre-fill the form from a submission body (a received body or a partial). */
+  prefillSubmission(submission) {
+    this.send({
+      type: "form_prefill" /* FormPrefill */,
+      data_type: "ulc_submission" /* UlcSubmission */,
+      data: submission
+    });
+  }
+  /** Pre-fill the form from a list of transcription field/value items. */
+  prefillInfo(info) {
+    this.send({
+      type: "form_prefill" /* FormPrefill */,
+      data_type: "info" /* Info */,
+      data: info
+    });
+  }
+  /** Pre-fill the form from a submission plus transcription items. */
+  prefillSubmissionAndInfo(data) {
+    this.send({
+      type: "form_prefill" /* FormPrefill */,
+      data_type: "ulc_submission_and_info" /* UlcSubmissionAndInfo */,
+      data
+    });
+  }
+  /* -------------------------------------------------------------- *
+   * Lifecycle
+   * -------------------------------------------------------------- */
+  /** Remove the `message` listener and drop all subscriptions. Idempotent. */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.hostWindow.removeEventListener("message", this.boundHandler);
+    this.listeners.clear();
+    this.anyListeners.clear();
+    this.outbox.length = 0;
+  }
+  /* -------------------------------------------------------------- *
+   * Internals
+   * -------------------------------------------------------------- */
+  handleMessage(event) {
+    if (this.destroyed) return;
+    if (this.targetOrigin !== "*" && event.origin !== this.targetOrigin) {
+      if (parseOutboundMessage(event.data)) {
+        devWarn(
+          `[captello-sdk] Ignored a Captello message from origin "${event.origin}" (expected "${this.targetOrigin}"). Check the targetOrigin you passed.`
+        );
+      }
+      return;
+    }
+    if (this.matchSource) {
+      const expected = this.frame.contentWindow;
+      if (expected && event.source !== expected) {
+        if (parseOutboundMessage(event.data)) {
+          devWarn(
+            "[captello-sdk] Ignored a Captello message from an unexpected source window (not the bound iframe). If the webview relays through another window, set matchSource: false."
+          );
+        }
+        return;
+      }
+    }
+    const message = parseOutboundMessage(event.data);
+    if (!message) return;
+    if (message.type === "form_load_complete" /* FormLoadComplete */) {
+      this.markReadyAndFlush();
+    }
+    const set = this.listeners.get(message.type);
+    if (set) {
+      for (const listener of [...set]) listener(message);
+    }
+    if (this.anyListeners.size) {
+      for (const listener of [...this.anyListeners]) listener(message);
+    }
+  }
+};
+
+// 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;
+}
+
+// src/submission-data.ts
+var FormElementType = /* @__PURE__ */ ((FormElementType2) => {
+  FormElementType2["email"] = "email";
+  FormElementType2["section"] = "section_block";
+  FormElementType2["html_block"] = "section";
+  FormElementType2["url"] = "url";
+  FormElementType2["text"] = "text";
+  FormElementType2["select"] = "select";
+  FormElementType2["radio"] = "radio";
+  FormElementType2["simple_name"] = "simple_name";
+  FormElementType2["textarea"] = "textarea";
+  FormElementType2["time"] = "time";
+  FormElementType2["address"] = "address";
+  FormElementType2["money"] = "money";
+  FormElementType2["number"] = "number";
+  FormElementType2["date"] = "date";
+  FormElementType2["phone"] = "phone";
+  FormElementType2["simple_phone"] = "simple_phone";
+  FormElementType2["checkbox"] = "checkbox";
+  FormElementType2["image"] = "image";
+  FormElementType2["business_card"] = "business_card";
+  FormElementType2["signature"] = "signature";
+  FormElementType2["barcode"] = "barcode";
+  FormElementType2["separator"] = "column_separator";
+  FormElementType2["activation"] = "activation";
+  FormElementType2["document"] = "documents";
+  FormElementType2["datetime"] = "datetime";
+  FormElementType2["meeting"] = "meeting";
+  FormElementType2["audio"] = "audio";
+  FormElementType2["rating"] = "rating";
+  FormElementType2["assign_owner"] = "assign_owner";
+  FormElementType2["boolean"] = "boolean";
+  FormElementType2["engagem_feeder"] = "engagem_feeder";
+  FormElementType2["speaker_section"] = "speaker_section_block";
+  FormElementType2["session_section"] = "session_section_block";
+  FormElementType2["image_placeholder"] = "image_placeholder";
+  FormElementType2["star_rating"] = "star_survey";
+  FormElementType2["attachments"] = "attachments";
+  return FormElementType2;
+})(FormElementType || {});
+var VALUED_ELEMENT_TYPES = /* @__PURE__ */ new Set([
+  "email" /* email */,
+  "url" /* url */,
+  "text" /* text */,
+  "textarea" /* textarea */,
+  "money" /* money */,
+  "number" /* number */,
+  "phone" /* phone */,
+  "simple_phone" /* simple_phone */,
+  "date" /* date */,
+  "time" /* time */,
+  "datetime" /* datetime */,
+  "audio" /* audio */,
+  "rating" /* rating */,
+  "star_survey" /* star_rating */,
+  "assign_owner" /* assign_owner */,
+  "signature" /* signature */,
+  "barcode" /* barcode */,
+  "meeting" /* meeting */,
+  "activation" /* activation */,
+  "checkbox" /* checkbox */,
+  "radio" /* radio */,
+  "select" /* select */,
+  "image" /* image */,
+  "documents" /* document */,
+  "engagem_feeder" /* engagem_feeder */,
+  "business_card" /* business_card */,
+  "boolean" /* boolean */,
+  "attachments" /* attachments */,
+  "simple_name" /* simple_name */,
+  "address" /* address */
+]);
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVisibleItem(value) {
+  if (!isPlainObject2(value)) return false;
+  return typeof value["element_id"] === "string" && typeof value["element_title"] === "string" && typeof value["element_type"] === "string" && VALUED_ELEMENT_TYPES.has(value["element_type"]) && "element_value" in value;
+}
+function parseVisibleSubmissionsData(data) {
+  let list = data;
+  if (isPlainObject2(data) && "visible_submissions_data" in data) {
+    list = data["visible_submissions_data"];
+  }
+  if (!Array.isArray(list)) return [];
+  return list.filter(isVisibleItem);
+}
+var DEFAULT_OPTIONS = {
+  listSeparator: ", ",
+  booleanLabels: { true: "Yes", false: "No" },
+  emptyText: ""
+};
+function isOrderCheckbox(value) {
+  return isPlainObject2(value) && Array.isArray(value["values"]);
+}
+function isOrderRadio(value) {
+  return isPlainObject2(value) && typeof value["value"] === "string";
+}
+function withQuantity(value, quantity) {
+  return quantity > 1 ? `${value} (x${quantity})` : value;
+}
+function joinNonEmpty(parts, sep) {
+  return parts.map((p) => (p ?? "").toString().trim()).filter(Boolean).join(sep);
+}
+function toDisplayValue(item, options = {}) {
+  const opts = {
+    listSeparator: options.listSeparator ?? DEFAULT_OPTIONS.listSeparator,
+    booleanLabels: options.booleanLabels ?? DEFAULT_OPTIONS.booleanLabels,
+    emptyText: options.emptyText ?? DEFAULT_OPTIONS.emptyText
+  };
+  const sep = opts.listSeparator;
+  const value = item.element_value;
+  switch (item.element_type) {
+    case "simple_name" /* simple_name */:
+      return joinNonEmpty(Object.values(value), " ") || opts.emptyText;
+    case "address" /* address */:
+      return joinNonEmpty(Object.values(value), sep) || opts.emptyText;
+    case "boolean" /* boolean */:
+      return value ? opts.booleanLabels.true : opts.booleanLabels.false;
+    case "checkbox" /* checkbox */:
+      if (Array.isArray(value)) return joinNonEmpty(value, sep) || opts.emptyText;
+      if (isOrderCheckbox(value)) {
+        const items = value.values.map((v) => withQuantity(v.value, v.quantity));
+        return joinNonEmpty([...items, value.note], sep) || opts.emptyText;
+      }
+      return opts.emptyText;
+    case "radio" /* radio */:
+    case "select" /* select */:
+      if (typeof value === "string") return value || opts.emptyText;
+      if (isOrderRadio(value)) {
+        return joinNonEmpty([withQuantity(value.value, value.quantity), value.note], sep) || opts.emptyText;
+      }
+      return opts.emptyText;
+    case "image" /* image */:
+      return joinNonEmpty(value, sep) || opts.emptyText;
+    case "documents" /* document */:
+      return joinNonEmpty(value.map(String), sep) || opts.emptyText;
+    case "attachments" /* attachments */:
+      return joinNonEmpty(
+        value.map((a) => a.name),
+        sep
+      ) || opts.emptyText;
+    case "engagem_feeder" /* engagem_feeder */:
+      return value.map((q) => joinNonEmpty([q.question, q.answers.join("/")], ": ")).filter(Boolean).join("; ") || opts.emptyText;
+    case "business_card" /* business_card */: {
+      const bc = value;
+      return joinNonEmpty([bc.front, bc.back], sep) || opts.emptyText;
+    }
+    default:
+      return typeof value === "string" ? value || opts.emptyText : opts.emptyText;
+  }
+}
+function toDisplayPairs(data, options) {
+  return parseVisibleSubmissionsData(data).map((item) => ({
+    elementId: item.element_id,
+    label: item.element_title,
+    value: toDisplayValue(item, options)
+  }));
+}
+
+exports.ActionButtonPosition = ActionButtonPosition;
+exports.CaptelloWebview = CaptelloWebview;
+exports.EmbedParam = EmbedParam;
+exports.FormElementType = FormElementType;
+exports.FormMode = FormMode;
+exports.InboundMessageType = InboundMessageType;
+exports.LauncherType = LauncherType;
+exports.OutboundMessageType = OutboundMessageType;
+exports.PrefillDataType = PrefillDataType;
+exports.SubmissionError = SubmissionError;
+exports.SubmissionTimeoutError = SubmissionTimeoutError;
+exports.buildEmbedUrl = buildEmbedUrl;
+exports.parseOutboundMessage = parseOutboundMessage;
+exports.parseVisibleSubmissionsData = parseVisibleSubmissionsData;
+exports.targetOriginFromUrl = targetOriginFromUrl;
+exports.toDisplayPairs = toDisplayPairs;
+exports.toDisplayValue = toDisplayValue;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map