@nium/nium-sdk 0.1.9 → 0.1.11

package/dist/index.mjs

@@ -1,164 +1,231 @@
+// src/types.ts
+var NIUM_MSG_PREFIX = "nium:";
+
 // src/element.ts
+var DEFAULT_MIN_HEIGHT_PX = 400;
+var DEFAULT_MAX_HEIGHT_PX = 804;
+var KNOWN_EVENT_NAMES = /* @__PURE__ */ new Set([
+  "ready",
+  "resize",
+  "change",
+  "submit",
+  "error",
+  "cancel"
+]);
+var describeMountTarget = (target) => typeof target === "string" ? target : `<${target.tagName.toLowerCase()}>`;
 var NiumElement = class {
   constructor(iframeSrc, elementType, options, origin) {
     this.iframe = null;
     this.container = null;
     this.listeners = {};
-    this.boundMessageHandler = null;
+    this.messageHandler = null;
     this.destroyed = false;
-    // Pending submit() promise — resolved/rejected when iframe responds
+    /** Pending `submit()` promise — resolved/rejected when the iframe responds. */
     this.pendingSubmit = null;
     this.iframeSrc = iframeSrc;
     this.elementType = elementType;
     this.options = options;
     this.origin = origin;
   }
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Lifecycle
-  // ---------------------------------------------------------------------------
-  /** Mount the iframe into a DOM element (selector string or HTMLElement). */
+  // -------------------------------------------------------------------------
+  /**
+   * Mount the iframe into a DOM element. The target may be a CSS selector or
+   * an `HTMLElement` reference. Calling `mount` on an already-mounted element
+   * with the same container is a no-op; a different container triggers an
+   * automatic unmount first.
+   */
   mount(target) {
     if (this.destroyed) {
       throw new Error("@nium/nium-sdk: Cannot mount a destroyed element");
     }
-    const el = typeof target === "string" ? document.querySelector(target) : target;
-    if (!el) {
-      throw new Error(`@nium/nium-sdk: Mount target not found: ${target}`);
+    const container = typeof target === "string" ? document.querySelector(target) : target;
+    if (!container) {
+      throw new Error(
+        `@nium/nium-sdk: Mount target not found: ${describeMountTarget(target)}`
+      );
     }
-    if (this.iframe && this.container === el) {
+    if (this.iframe && this.container === container) {
       return;
     }
     if (this.iframe) {
       this.unmount();
     }
-    this.container = el;
-    const minHeight = this.options.customizations?.minHeight ?? 400;
-    const maxHeight = this.options.customizations?.maxHeight ?? 804;
-    const iframe = document.createElement("iframe");
-    iframe.src = this.iframeSrc;
-    iframe.style.width = "100%";
-    iframe.style.border = "none";
-    iframe.style.minHeight = `${minHeight}px`;
-    iframe.style.maxHeight = `${maxHeight}px`;
-    iframe.setAttribute("allow", "clipboard-write");
-    iframe.setAttribute("title", `NIUM ${this.elementType} onboarding`);
-    this.iframe = iframe;
-    el.appendChild(iframe);
-    this.boundMessageHandler = this.handleMessage.bind(this);
-    window.addEventListener("message", this.boundMessageHandler);
+    this.container = container;
+    this.iframe = this.createIframe();
+    container.appendChild(this.iframe);
+    this.messageHandler = (event) => this.handleMessage(event);
+    window.addEventListener("message", this.messageHandler);
   }
-  /** Remove the iframe from the DOM. The element can be re-mounted later. */
+  /**
+   * Remove the iframe from the DOM and stop listening for messages. The
+   * element can be mounted again later.
+   */
   unmount() {
-    if (this.iframe && this.iframe.parentNode) {
-      this.iframe.parentNode.removeChild(this.iframe);
-    }
+    this.iframe?.remove();
     this.iframe = null;
     this.container = null;
-    if (this.boundMessageHandler) {
-      window.removeEventListener("message", this.boundMessageHandler);
-      this.boundMessageHandler = null;
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
     }
   }
-  /** Permanently destroy the element. Removes from DOM and clears all listeners. */
+  /**
+   * Permanently destroy the element. Removes it from the DOM, clears every
+   * listener, and rejects any pending `submit()`. A destroyed element cannot
+   * be re-mounted.
+   */
   destroy() {
     this.unmount();
     this.listeners = {};
+    this.pendingSubmit?.reject(new Error("@nium/nium-sdk: Element was destroyed"));
     this.pendingSubmit = null;
     this.destroyed = true;
   }
-  // ---------------------------------------------------------------------------
-  // Programmatic submit (Airwallex-style)
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
+  // Programmatic submit
+  // -------------------------------------------------------------------------
   /**
-   * Programmatically trigger form submission from the parent app.
-   *
-   * Sends a `nium:submit-request` message to the iframe. The hosted form
-   * validates and submits, then responds with `nium:submit` (success) or
-   * `nium:error` (failure).
-   *
-   * @returns Promise that resolves with the submit result or rejects with an error.
+   * Programmatically trigger form submission from the parent application.
    *
-   * @example
-   * ```ts
-   * const result = await element.submit()
-   * console.log(result.beneficiaryId)
-   * ```
+   * Posts a `nium:submit-request` message to the iframe; the hosted form
+   * validates, submits, and responds with `nium:submit` (resolve) or
+   * `nium:error` (reject).
    */
   async submit() {
-    if (!this.iframe?.contentWindow) {
+    const contentWindow = this.iframe?.contentWindow;
+    if (!contentWindow) {
       throw new Error("@nium/nium-sdk: Element is not mounted");
     }
-    if (this.pendingSubmit) {
-      this.pendingSubmit.reject(new Error("Superseded by a new submit() call"));
-    }
+    this.pendingSubmit?.reject(
+      new Error("@nium/nium-sdk: Superseded by a new submit() call")
+    );
     return new Promise((resolve, reject) => {
       this.pendingSubmit = { resolve, reject };
-      this.iframe.contentWindow.postMessage(
-        { type: "nium:submit-request", payload: {} },
+      contentWindow.postMessage(
+        { type: `${NIUM_MSG_PREFIX}submit-request`, payload: {} },
         this.origin
       );
     });
   }
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Events
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   /** Subscribe to an event. Returns an unsubscribe function. */
   on(event, callback) {
-    if (!this.listeners[event]) {
-      this.listeners[event] = /* @__PURE__ */ new Set();
-    }
-    const set = this.listeners[event];
+    const set = this.listeners[event] ?? /* @__PURE__ */ new Set();
     set.add(callback);
+    this.listeners[event] = set;
     return () => {
       set.delete(callback);
     };
   }
-  /** Remove a specific listener. */
+  /** Remove a previously registered listener. */
   off(event, callback) {
-    const set = this.listeners[event];
-    if (set) {
-      set.delete(callback);
-    }
+    this.listeners[event]?.delete(callback);
   }
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
   // Internal
-  // ---------------------------------------------------------------------------
+  // -------------------------------------------------------------------------
+  createIframe() {
+    const { minHeight = DEFAULT_MIN_HEIGHT_PX, maxHeight = DEFAULT_MAX_HEIGHT_PX } = this.options.customizations ?? {};
+    const iframe = document.createElement("iframe");
+    iframe.src = this.iframeSrc;
+    iframe.title = `NIUM ${this.elementType} onboarding`;
+    iframe.setAttribute("allow", "clipboard-write");
+    Object.assign(iframe.style, {
+      width: "100%",
+      border: "none",
+      minHeight: `${minHeight}px`,
+      maxHeight: `${maxHeight}px`
+    });
+    return iframe;
+  }
+  /** Top-level `postMessage` handler. Delegates to focused helpers per event. */
   handleMessage(event) {
-    if (event.origin !== this.origin) {
+    const message = this.parseTrustedMessage(event);
+    if (!message) {
       return;
     }
+    const { name, payload } = message;
+    this.applySideEffects(name, payload);
+    if (KNOWN_EVENT_NAMES.has(name)) {
+      this.dispatchEvent(name, payload);
+    }
+  }
+  /**
+   * Validates the message origin and prefix, and returns the stripped event
+   * name + payload. Returns `null` for untrusted or malformed messages so
+   * they can be silently dropped.
+   */
+  parseTrustedMessage(event) {
+    if (event.origin !== this.origin) {
+      return null;
+    }
     const data = event.data;
-    if (!data?.type?.startsWith("nium:")) {
+    if (!data?.type?.startsWith(NIUM_MSG_PREFIX)) {
+      return null;
+    }
+    return {
+      name: data.type.slice(NIUM_MSG_PREFIX.length),
+      payload: data.payload ?? {}
+    };
+  }
+  /**
+   * Handles built-in side effects that the SDK performs on behalf of the
+   * consumer: iframe auto-resize on `resize`, and `submit()` promise
+   * resolution on `submit` / `error`.
+   */
+  applySideEffects(name, payload) {
+    if (name === "resize") {
+      this.applyResize(payload);
       return;
     }
-    const eventName = data.type.slice(5);
-    const payload = data.payload ?? {};
-    if (eventName === "resize" && this.iframe && "height" in payload) {
-      this.iframe.style.height = `${payload.height}px`;
+    if (name === "submit") {
+      this.resolvePendingSubmit(payload);
+      return;
     }
-    if (eventName === "submit" && this.pendingSubmit) {
-      const result = payload.result;
-      if (result) {
-        this.pendingSubmit.resolve(result);
-      }
-      this.pendingSubmit = null;
+    if (name === "error") {
+      this.rejectPendingSubmit(payload);
+    }
+  }
+  applyResize(payload) {
+    const height = payload.height;
+    if (this.iframe && typeof height === "number") {
+      this.iframe.style.height = `${height}px`;
+    }
+  }
+  resolvePendingSubmit(payload) {
+    if (!this.pendingSubmit) {
+      return;
+    }
+    const { result } = payload;
+    if (result) {
+      this.pendingSubmit.resolve(result);
     }
-    if (eventName === "error" && this.pendingSubmit) {
-      const err = payload.error;
-      this.pendingSubmit.reject(new Error(err?.message ?? "Submit failed"));
-      this.pendingSubmit = null;
+    this.pendingSubmit = null;
+  }
+  rejectPendingSubmit(payload) {
+    if (!this.pendingSubmit) {
+      return;
     }
-    if (eventName in { ready: 1, resize: 1, change: 1, submit: 1, error: 1, cancel: 1 }) {
-      const typedEvent = { type: eventName, ...payload };
-      const set = this.listeners[eventName];
-      if (set) {
-        for (const cb of set) {
-          try {
-            cb(typedEvent);
-          } catch (err) {
-            console.error(`@nium/nium-sdk: Error in "${eventName}" listener:`, err);
-          }
-        }
+    const { error } = payload;
+    this.pendingSubmit.reject(new Error(error?.message ?? "Submit failed"));
+    this.pendingSubmit = null;
+  }
+  /** Dispatch a typed event payload to every registered listener. */
+  dispatchEvent(name, payload) {
+    const set = this.listeners[name];
+    if (!set || set.size === 0) {
+      return;
+    }
+    const typedEvent = { type: name, ...payload };
+    for (const callback of set) {
+      try {
+        callback(typedEvent);
+      } catch (err) {
+        console.error(`@nium/nium-sdk: Error in "${name}" listener:`, err);
       }
     }
   }
@@ -169,7 +236,8 @@ var initConfig = null;
 var ENV_URLS = {
   local: "http://localhost:3000",
   qa: "https://onboard-qa.nium.com",
-  sandbox: "https://onboard-sandbox.nium.com/",
+  preprod: "https://onboard-preprod.nium.com",
+  sandbox: "https://onboard-sandbox.nium.com",
   production: "https://onboard.nium.com"
 };
 var ELEMENT_ROUTES = {
@@ -178,80 +246,91 @@ var ELEMENT_ROUTES = {
   identity: "/sdk/identity-form",
   full: "/sdk/full-form"
 };
-var init = async (options) => {
-  if (!options.authCode && !options.sessionToken) {
-    throw new Error("@nium/nium-sdk: authCode or sessionToken is required");
+var encodeBase64Json = (value) => {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCodePoint(byte);
   }
-  if (!options.env) {
-    throw new Error("@nium/nium-sdk: env is required");
-  }
-  initConfig = options;
+  return btoa(binary);
 };
-var createElement = async (type, options = {}) => {
-  if (!initConfig) {
-    throw new Error(
-      "@nium/nium-sdk: Must call init() before createElement()"
-    );
-  }
-  const rawBaseUrl = initConfig.hostedFormUrl ?? ENV_URLS[initConfig.env];
-  const baseUrl = rawBaseUrl.replace(/\/+$/, "");
-  const origin = new URL(baseUrl).origin;
-  const route = ELEMENT_ROUTES[type];
-  const url = new URL(`${baseUrl}${route}`);
-  if (initConfig.authCode) {
-    url.searchParams.set("authCode", initConfig.authCode);
-  }
-  if (initConfig.codeVerifier) {
-    url.searchParams.set("codeVerifier", initConfig.codeVerifier);
-  }
-  if (initConfig.clientId) {
-    url.searchParams.set("clientId", initConfig.clientId);
-  }
-  if (initConfig.sessionToken) {
-    url.searchParams.set("sessionToken", initConfig.sessionToken);
+var setParam = (url, key, value) => {
+  if (value !== void 0 && value !== "") {
+    url.searchParams.set(key, value);
   }
-  if (options.customerHashId) {
-    url.searchParams.set("customerHashId", options.customerHashId);
-  }
-  if (options.intent) {
-    if (options.intent === "update_beneficiary" && !options.beneficiaryHashId) {
-      throw new Error("@nium/nium-sdk: beneficiaryHashId is required for update_beneficiary intent");
-    }
-    if (options.intent === "update_beneficiary" && options.prefill) {
-      throw new Error("@nium/nium-sdk: prefill is not allowed for update_beneficiary intent. Existing data is fetched automatically.");
-    }
-    url.searchParams.set("intent", options.intent);
+};
+var setEncodedParam = (url, key, value) => {
+  if (value !== void 0 && value !== null) {
+    url.searchParams.set(key, encodeBase64Json(value));
   }
-  if (options.beneficiaryHashId) {
-    url.searchParams.set("beneficiaryHashId", options.beneficiaryHashId);
+};
+var assertRequired = (source, keys, method) => {
+  const missing = keys.filter((key) => !source[key]);
+  if (missing.length === 0) {
+    return;
   }
-  if (initConfig.locale) {
-    url.searchParams.set("locale", initConfig.locale);
+  const suffix = missing.length > 1 ? "s" : "";
+  throw new Error(
+    `@nium/nium-sdk: ${method}() missing required option${suffix}: ${missing.join(", ")}`
+  );
+};
+var assertIntentContract = (options) => {
+  if (options.intent !== "update_beneficiary") {
+    return;
   }
-  if (options.prefill) {
-    url.searchParams.set(
-      "prefill",
-      btoa(JSON.stringify(options.prefill))
+  if (!options.beneficiaryHashId) {
+    throw new Error(
+      "@nium/nium-sdk: beneficiaryHashId is required for update_beneficiary intent"
     );
   }
-  if (options.theme) {
-    url.searchParams.set(
-      "theme",
-      btoa(JSON.stringify(options.theme))
+  if (options.prefill) {
+    throw new Error(
+      "@nium/nium-sdk: prefill is not allowed for update_beneficiary intent. Existing data is fetched automatically."
     );
   }
+};
+var resolveBaseUrl = (config) => {
+  const raw = config.hostedFormUrl ?? ENV_URLS[config.env];
+  const baseUrl = raw.replace(/\/+$/, "");
+  return { baseUrl, origin: new URL(baseUrl).origin };
+};
+var buildIframeUrl = (baseUrl, type, config, options) => {
+  const url = new URL(`${baseUrl}${ELEMENT_ROUTES[type]}`);
+  setParam(url, "authCode", config.authCode);
+  setParam(url, "codeVerifier", config.codeVerifier);
+  setParam(url, "clientId", config.clientId);
+  setParam(url, "sessionToken", config.sessionToken);
+  setParam(url, "locale", config.locale);
+  setParam(url, "customerHashId", options.customerHashId);
+  setParam(url, "intent", options.intent);
+  setParam(url, "beneficiaryHashId", options.beneficiaryHashId);
+  setEncodedParam(url, "prefill", options.prefill);
+  setEncodedParam(url, "theme", options.theme);
   const iframeCustomizations = {
     ...options.customizations?.fields ? { fields: options.customizations.fields } : {},
     ...options.customizations?.sections ? { sections: options.customizations.sections } : {}
   };
   if (Object.keys(iframeCustomizations).length > 0) {
-    url.searchParams.set(
-      "customizations",
-      btoa(
-        JSON.stringify(iframeCustomizations)
-      )
-    );
+    setEncodedParam(url, "customizations", iframeCustomizations);
+  }
+  return url;
+};
+var init = async (options) => {
+  assertRequired(
+    options,
+    ["env", "authCode", "codeVerifier", "clientId"],
+    "init"
+  );
+  initConfig = options;
+};
+var createElement = async (type, options = {}) => {
+  if (!initConfig) {
+    throw new Error("@nium/nium-sdk: Must call init() before createElement()");
   }
+  assertRequired(options, ["customerHashId", "intent"], "createElement");
+  assertIntentContract(options);
+  const { baseUrl, origin } = resolveBaseUrl(initConfig);
+  const url = buildIframeUrl(baseUrl, type, initConfig, options);
   return new NiumElement(url.toString(), type, options, origin);
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nium/nium-sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "NIUM Onboarding SDK - Embed hosted onboarding forms with a clean JavaScript API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -8,12 +8,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "type": "tsc --noEmit",
-    "lint": "eslint src/"
-  },
   "devDependencies": {
     "@rollup/rollup-darwin-arm64": "^4.60.1",
     "tsup": "^8.0.0",
@@ -22,5 +16,11 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "type": "tsc --noEmit",
+    "lint": "eslint src/"
   }
-}
+}