@nium/nium-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,163 @@
+/** Environments supported by the SDK */
+type NiumEnv = 'local' | 'sandbox' | 'qa' | 'production';
+/** Module types that map to web-onboard routes */
+type NiumElementType = 'payment' | 'tax' | 'identity' | 'full';
+/** Configuration passed to `init()` */
+interface NiumInitOptions {
+    /** Target environment */
+    env: NiumEnv;
+    /** Session code returned by marketplace-service /init */
+    sessionCode: string;
+    /** Optional locale (defaults to 'en') */
+    locale?: string;
+    /** Override the hosted form base URL (useful for local dev) */
+    hostedFormUrl?: string;
+}
+/** Theme options for embedded components */
+interface NiumTheme {
+    primaryColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+}
+/** Prefill data for the payment (beneficiary) form */
+interface NiumPaymentPrefill {
+    name?: {
+        first?: string;
+        last?: string;
+    };
+    email?: string;
+    entityType?: 'individual' | 'business';
+}
+/** Options passed to `createElement()` */
+interface NiumElementOptions {
+    /** Pre-fill form fields */
+    prefill?: NiumPaymentPrefill;
+    /** Custom theme overrides */
+    theme?: NiumTheme;
+    /** Custom minimum height for the iframe (default: 400) */
+    customizations?: {
+        minHeight?: number;
+    };
+}
+interface NiumReadyEvent {
+    type: 'ready';
+}
+interface NiumResizeEvent {
+    type: 'resize';
+    height: number;
+}
+interface NiumChangeEvent {
+    type: 'change';
+    data: Record<string, unknown>;
+}
+interface NiumSubmitResult {
+    beneficiaryId?: string;
+    filerHashId?: string;
+    status: 'success';
+}
+interface NiumSubmitEvent {
+    type: 'submit';
+    result: NiumSubmitResult;
+}
+interface NiumErrorEvent {
+    type: 'error';
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+interface NiumCancelEvent {
+    type: 'cancel';
+}
+type NiumEvent = NiumReadyEvent | NiumResizeEvent | NiumChangeEvent | NiumSubmitEvent | NiumErrorEvent | NiumCancelEvent;
+/** Map of event type string -> payload */
+interface NiumEventMap {
+    ready: NiumReadyEvent;
+    resize: NiumResizeEvent;
+    change: NiumChangeEvent;
+    submit: NiumSubmitEvent;
+    error: NiumErrorEvent;
+    cancel: NiumCancelEvent;
+}
+/** Callback signature for a given event type */
+type NiumEventCallback<T extends keyof NiumEventMap> = (event: NiumEventMap[T]) => void;
+
+/**
+ * NiumElement wraps a hidden iframe pointing at the web-onboard hosted forms.
+ * It translates internal postMessage events into typed callbacks and exposes
+ * a programmatic `submit()` method (Airwallex-style).
+ */
+declare class NiumElement {
+    private readonly iframeSrc;
+    private readonly elementType;
+    private readonly options;
+    private iframe;
+    private container;
+    private listeners;
+    private boundMessageHandler;
+    private destroyed;
+    private readonly origin;
+    private pendingSubmit;
+    constructor(iframeSrc: string, elementType: NiumElementType, options: NiumElementOptions, origin: string);
+    /** Mount the iframe into a DOM element (selector string or HTMLElement). */
+    mount(target: string | HTMLElement): void;
+    /** Remove the iframe from the DOM. The element can be re-mounted later. */
+    unmount(): void;
+    /** Permanently destroy the element. Removes from DOM and clears all listeners. */
+    destroy(): void;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const result = await element.submit()
+     * console.log(result.beneficiaryId)
+     * ```
+     */
+    submit(): Promise<NiumSubmitResult>;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): () => void;
+    /** Remove a specific listener. */
+    off<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): void;
+    private handleMessage;
+}
+
+/**
+ * Initialize the SDK. Must be called once before `createElement`.
+ *
+ * @example
+ * ```ts
+ * import { init, createElement } from '@nium/nium-sdk'
+ *
+ * await init({
+ *   env: 'sandbox',
+ *   sessionCode: '<code-from-server>',
+ * })
+ *
+ * const element = await createElement('payment')
+ * element.mount('#container')
+ *
+ * // Option A: listen for submit events
+ * element.on('submit', (e) => console.log(e.result))
+ *
+ * // Option B: programmatic submit from parent
+ * const result = await element.submit()
+ * ```
+ */
+declare const init: (options: NiumInitOptions) => Promise<void>;
+/**
+ * Create an embeddable element for a specific onboarding module.
+ *
+ * @param type - The module to render: 'payment' | 'tax' | 'identity' | 'full'
+ * @param options - Optional configuration (prefill, theme, customizations)
+ * @returns A NiumElement that can be mounted, listened to, submitted, and destroyed
+ */
+declare const createElement: (type: NiumElementType, options?: NiumElementOptions) => Promise<NiumElement>;
+
+export { type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumInitOptions, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/** Environments supported by the SDK */
+type NiumEnv = 'local' | 'sandbox' | 'qa' | 'production';
+/** Module types that map to web-onboard routes */
+type NiumElementType = 'payment' | 'tax' | 'identity' | 'full';
+/** Configuration passed to `init()` */
+interface NiumInitOptions {
+    /** Target environment */
+    env: NiumEnv;
+    /** Session code returned by marketplace-service /init */
+    sessionCode: string;
+    /** Optional locale (defaults to 'en') */
+    locale?: string;
+    /** Override the hosted form base URL (useful for local dev) */
+    hostedFormUrl?: string;
+}
+/** Theme options for embedded components */
+interface NiumTheme {
+    primaryColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+}
+/** Prefill data for the payment (beneficiary) form */
+interface NiumPaymentPrefill {
+    name?: {
+        first?: string;
+        last?: string;
+    };
+    email?: string;
+    entityType?: 'individual' | 'business';
+}
+/** Options passed to `createElement()` */
+interface NiumElementOptions {
+    /** Pre-fill form fields */
+    prefill?: NiumPaymentPrefill;
+    /** Custom theme overrides */
+    theme?: NiumTheme;
+    /** Custom minimum height for the iframe (default: 400) */
+    customizations?: {
+        minHeight?: number;
+    };
+}
+interface NiumReadyEvent {
+    type: 'ready';
+}
+interface NiumResizeEvent {
+    type: 'resize';
+    height: number;
+}
+interface NiumChangeEvent {
+    type: 'change';
+    data: Record<string, unknown>;
+}
+interface NiumSubmitResult {
+    beneficiaryId?: string;
+    filerHashId?: string;
+    status: 'success';
+}
+interface NiumSubmitEvent {
+    type: 'submit';
+    result: NiumSubmitResult;
+}
+interface NiumErrorEvent {
+    type: 'error';
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+interface NiumCancelEvent {
+    type: 'cancel';
+}
+type NiumEvent = NiumReadyEvent | NiumResizeEvent | NiumChangeEvent | NiumSubmitEvent | NiumErrorEvent | NiumCancelEvent;
+/** Map of event type string -> payload */
+interface NiumEventMap {
+    ready: NiumReadyEvent;
+    resize: NiumResizeEvent;
+    change: NiumChangeEvent;
+    submit: NiumSubmitEvent;
+    error: NiumErrorEvent;
+    cancel: NiumCancelEvent;
+}
+/** Callback signature for a given event type */
+type NiumEventCallback<T extends keyof NiumEventMap> = (event: NiumEventMap[T]) => void;
+
+/**
+ * NiumElement wraps a hidden iframe pointing at the web-onboard hosted forms.
+ * It translates internal postMessage events into typed callbacks and exposes
+ * a programmatic `submit()` method (Airwallex-style).
+ */
+declare class NiumElement {
+    private readonly iframeSrc;
+    private readonly elementType;
+    private readonly options;
+    private iframe;
+    private container;
+    private listeners;
+    private boundMessageHandler;
+    private destroyed;
+    private readonly origin;
+    private pendingSubmit;
+    constructor(iframeSrc: string, elementType: NiumElementType, options: NiumElementOptions, origin: string);
+    /** Mount the iframe into a DOM element (selector string or HTMLElement). */
+    mount(target: string | HTMLElement): void;
+    /** Remove the iframe from the DOM. The element can be re-mounted later. */
+    unmount(): void;
+    /** Permanently destroy the element. Removes from DOM and clears all listeners. */
+    destroy(): void;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const result = await element.submit()
+     * console.log(result.beneficiaryId)
+     * ```
+     */
+    submit(): Promise<NiumSubmitResult>;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): () => void;
+    /** Remove a specific listener. */
+    off<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): void;
+    private handleMessage;
+}
+
+/**
+ * Initialize the SDK. Must be called once before `createElement`.
+ *
+ * @example
+ * ```ts
+ * import { init, createElement } from '@nium/nium-sdk'
+ *
+ * await init({
+ *   env: 'sandbox',
+ *   sessionCode: '<code-from-server>',
+ * })
+ *
+ * const element = await createElement('payment')
+ * element.mount('#container')
+ *
+ * // Option A: listen for submit events
+ * element.on('submit', (e) => console.log(e.result))
+ *
+ * // Option B: programmatic submit from parent
+ * const result = await element.submit()
+ * ```
+ */
+declare const init: (options: NiumInitOptions) => Promise<void>;
+/**
+ * Create an embeddable element for a specific onboarding module.
+ *
+ * @param type - The module to render: 'payment' | 'tax' | 'identity' | 'full'
+ * @param options - Optional configuration (prefill, theme, customizations)
+ * @returns A NiumElement that can be mounted, listened to, submitted, and destroyed
+ */
+declare const createElement: (type: NiumElementType, options?: NiumElementOptions) => Promise<NiumElement>;
+
+export { type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumInitOptions, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };

package/dist/index.js

@@ -0,0 +1,251 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  NiumElement: () => NiumElement,
+  createElement: () => createElement,
+  init: () => init
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/element.ts
+var NiumElement = class {
+  constructor(iframeSrc, elementType, options, origin) {
+    this.iframe = null;
+    this.container = null;
+    this.listeners = {};
+    this.boundMessageHandler = null;
+    this.destroyed = false;
+    // Pending submit() promise — resolved/rejected when 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(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}`);
+    }
+    if (this.iframe && this.container === el) {
+      return;
+    }
+    if (this.iframe) {
+      this.unmount();
+    }
+    this.container = el;
+    const minHeight = this.options.customizations?.minHeight ?? 400;
+    const iframe = document.createElement("iframe");
+    iframe.src = this.iframeSrc;
+    iframe.style.width = "100%";
+    iframe.style.border = "none";
+    iframe.style.overflow = "hidden";
+    iframe.style.minHeight = `${minHeight}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);
+  }
+  /** Remove the iframe from the DOM. The element can be re-mounted later. */
+  unmount() {
+    if (this.iframe && this.iframe.parentNode) {
+      this.iframe.parentNode.removeChild(this.iframe);
+    }
+    this.iframe = null;
+    this.container = null;
+    if (this.boundMessageHandler) {
+      window.removeEventListener("message", this.boundMessageHandler);
+      this.boundMessageHandler = null;
+    }
+  }
+  /** Permanently destroy the element. Removes from DOM and clears all listeners. */
+  destroy() {
+    this.unmount();
+    this.listeners = {};
+    this.pendingSubmit = null;
+    this.destroyed = true;
+  }
+  // ---------------------------------------------------------------------------
+  // Programmatic submit (Airwallex-style)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const result = await element.submit()
+   * console.log(result.beneficiaryId)
+   * ```
+   */
+  async submit() {
+    if (!this.iframe?.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"));
+    }
+    return new Promise((resolve, reject) => {
+      this.pendingSubmit = { resolve, reject };
+      this.iframe.contentWindow.postMessage(
+        { type: "nium: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];
+    set.add(callback);
+    return () => {
+      set.delete(callback);
+    };
+  }
+  /** Remove a specific listener. */
+  off(event, callback) {
+    const set = this.listeners[event];
+    if (set) {
+      set.delete(callback);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+  handleMessage(event) {
+    if (event.origin !== this.origin) {
+      return;
+    }
+    const data = event.data;
+    if (!data?.type?.startsWith("nium:")) {
+      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 (eventName === "submit" && this.pendingSubmit) {
+      const result = payload.result;
+      if (result) {
+        this.pendingSubmit.resolve(result);
+      }
+      this.pendingSubmit = null;
+    }
+    if (eventName === "error" && this.pendingSubmit) {
+      const err = payload.error;
+      this.pendingSubmit.reject(new Error(err?.message ?? "Submit failed"));
+      this.pendingSubmit = null;
+    }
+    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);
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/index.ts
+var initConfig = null;
+var ENV_URLS = {
+  local: "http://localhost:3000",
+  sandbox: "https://onboard.sandbox.niumops.com",
+  qa: "https://onboard-qa.nium.com",
+  production: "https://onboard.niumops.com"
+};
+var ELEMENT_ROUTES = {
+  payment: "/sdk/beneficiary-form",
+  tax: "/sdk/tax-form",
+  identity: "/sdk/identity-form",
+  full: "/sdk/full-form"
+};
+var init = async (options) => {
+  if (!options.sessionCode) {
+    throw new Error("@nium/nium-sdk: sessionCode is required");
+  }
+  if (!options.env) {
+    throw new Error("@nium/nium-sdk: env is required");
+  }
+  initConfig = options;
+};
+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}`);
+  url.searchParams.set("code", initConfig.sessionCode);
+  if (initConfig.locale) {
+    url.searchParams.set("locale", initConfig.locale);
+  }
+  if (options.prefill) {
+    url.searchParams.set(
+      "prefill",
+      btoa(JSON.stringify(options.prefill))
+    );
+  }
+  if (options.theme) {
+    url.searchParams.set(
+      "theme",
+      btoa(JSON.stringify(options.theme))
+    );
+  }
+  return new NiumElement(url.toString(), type, options, origin);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NiumElement,
+  createElement,
+  init
+});

package/dist/index.mjs

@@ -0,0 +1,222 @@
+// src/element.ts
+var NiumElement = class {
+  constructor(iframeSrc, elementType, options, origin) {
+    this.iframe = null;
+    this.container = null;
+    this.listeners = {};
+    this.boundMessageHandler = null;
+    this.destroyed = false;
+    // Pending submit() promise — resolved/rejected when 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(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}`);
+    }
+    if (this.iframe && this.container === el) {
+      return;
+    }
+    if (this.iframe) {
+      this.unmount();
+    }
+    this.container = el;
+    const minHeight = this.options.customizations?.minHeight ?? 400;
+    const iframe = document.createElement("iframe");
+    iframe.src = this.iframeSrc;
+    iframe.style.width = "100%";
+    iframe.style.border = "none";
+    iframe.style.overflow = "hidden";
+    iframe.style.minHeight = `${minHeight}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);
+  }
+  /** Remove the iframe from the DOM. The element can be re-mounted later. */
+  unmount() {
+    if (this.iframe && this.iframe.parentNode) {
+      this.iframe.parentNode.removeChild(this.iframe);
+    }
+    this.iframe = null;
+    this.container = null;
+    if (this.boundMessageHandler) {
+      window.removeEventListener("message", this.boundMessageHandler);
+      this.boundMessageHandler = null;
+    }
+  }
+  /** Permanently destroy the element. Removes from DOM and clears all listeners. */
+  destroy() {
+    this.unmount();
+    this.listeners = {};
+    this.pendingSubmit = null;
+    this.destroyed = true;
+  }
+  // ---------------------------------------------------------------------------
+  // Programmatic submit (Airwallex-style)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const result = await element.submit()
+   * console.log(result.beneficiaryId)
+   * ```
+   */
+  async submit() {
+    if (!this.iframe?.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"));
+    }
+    return new Promise((resolve, reject) => {
+      this.pendingSubmit = { resolve, reject };
+      this.iframe.contentWindow.postMessage(
+        { type: "nium: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];
+    set.add(callback);
+    return () => {
+      set.delete(callback);
+    };
+  }
+  /** Remove a specific listener. */
+  off(event, callback) {
+    const set = this.listeners[event];
+    if (set) {
+      set.delete(callback);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+  handleMessage(event) {
+    if (event.origin !== this.origin) {
+      return;
+    }
+    const data = event.data;
+    if (!data?.type?.startsWith("nium:")) {
+      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 (eventName === "submit" && this.pendingSubmit) {
+      const result = payload.result;
+      if (result) {
+        this.pendingSubmit.resolve(result);
+      }
+      this.pendingSubmit = null;
+    }
+    if (eventName === "error" && this.pendingSubmit) {
+      const err = payload.error;
+      this.pendingSubmit.reject(new Error(err?.message ?? "Submit failed"));
+      this.pendingSubmit = null;
+    }
+    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);
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/index.ts
+var initConfig = null;
+var ENV_URLS = {
+  local: "http://localhost:3000",
+  sandbox: "https://onboard.sandbox.niumops.com",
+  qa: "https://onboard-qa.nium.com",
+  production: "https://onboard.niumops.com"
+};
+var ELEMENT_ROUTES = {
+  payment: "/sdk/beneficiary-form",
+  tax: "/sdk/tax-form",
+  identity: "/sdk/identity-form",
+  full: "/sdk/full-form"
+};
+var init = async (options) => {
+  if (!options.sessionCode) {
+    throw new Error("@nium/nium-sdk: sessionCode is required");
+  }
+  if (!options.env) {
+    throw new Error("@nium/nium-sdk: env is required");
+  }
+  initConfig = options;
+};
+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}`);
+  url.searchParams.set("code", initConfig.sessionCode);
+  if (initConfig.locale) {
+    url.searchParams.set("locale", initConfig.locale);
+  }
+  if (options.prefill) {
+    url.searchParams.set(
+      "prefill",
+      btoa(JSON.stringify(options.prefill))
+    );
+  }
+  if (options.theme) {
+    url.searchParams.set(
+      "theme",
+      btoa(JSON.stringify(options.theme))
+    );
+  }
+  return new NiumElement(url.toString(), type, options, origin);
+};
+export {
+  NiumElement,
+  createElement,
+  init
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@nium/nium-sdk",
+  "version": "0.1.0",
+  "description": "NIUM Onboarding SDK - Embed hosted onboarding forms with a clean JavaScript API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "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": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}