@nium/nium-sdk 0.1.10 → 0.1.11

package/dist/index.d.mts

@@ -1,27 +1,47 @@
-/** Environments supported by the SDK */
-type NiumEnv = 'local' | 'sandbox' | 'qa' | 'production' | string;
-/** Module types that map to web-onboard routes */
+/**
+ * Public type definitions for `@nium/nium-sdk`.
+ *
+ * These types are intentionally framework-agnostic. They describe the shape of
+ * configuration accepted by {@link init} and {@link createElement}, the events
+ * emitted by a mounted element, and the postMessage contract with the hosted
+ * form.
+ *
+ * Any change here is a public API change — keep it additive where possible.
+ */
+/**
+ * A "loose autocomplete" string union: editors will suggest the listed
+ * literals while still accepting any other string. Prefer this over a bare
+ * `Literal | string` union, which collapses to `string` and loses intellisense
+ * (and trips `sonarjs/S6571`).
+ */
+type LooseStringUnion<T extends string> = T | (string & Record<never, never>);
+/** Target environment for the hosted onboarding form. */
+type NiumEnv = 'local' | 'qa' | 'preprod' | 'sandbox' | 'production';
+/** Supported module types. Each maps to a dedicated route inside web-onboard. */
 type NiumElementType = 'payment' | 'tax' | 'identity' | 'full';
-/** Configuration passed to `init()` */
+/** Configuration accepted by the top-level `init()` call. */
 interface NiumInitOptions {
-    /** Target environment */
+    /** Target environment; determines the default hosted form URL. */
     env: NiumEnv;
-    /** Optional locale (defaults to 'en') */
+    /** BCP-47 locale code (for example `en`, `en-GB`, `es`). Defaults to `en`. */
     locale?: string;
-    /** Override the hosted form base URL (useful for local dev) */
+    /** Override the hosted form base URL. Primarily for local development. */
     hostedFormUrl?: string;
-    /** Authorization code from NIAM oauth/authcode */
+    /** Short-lived authorization code obtained from NIAM via OAuth 2.1 / PKCE. */
     authCode?: string;
-    /** PKCE code verifier corresponding to the code challenge sent to get authCode */
+    /** PKCE code verifier that matches the code challenge used to obtain `authCode`. */
     codeVerifier?: string;
-    /** Customer hash ID */
+    /** Identifier of the customer the form is being rendered for. */
     customerHashId?: string;
-    /** Client ID */
+    /** NIUM client identifier. */
     clientId?: string;
-    /** Pre-exchanged session token (temporary — bypasses auth code exchange) */
+    /** Pre-exchanged session token. When present, `authCode`/`codeVerifier` are bypassed. */
     sessionToken?: string;
 }
-/** Theme options for embedded components */
+/**
+ * Theme overrides applied to the embedded form. Every property is optional;
+ * unspecified values fall back to the form's default design tokens.
+ */
 interface NiumTheme {
     borderRadius?: string;
     fontFamily?: string;
@@ -35,23 +55,24 @@ interface NiumTheme {
     labelBackgroundColor?: string;
     radioColor?: string;
 }
-/** Per-field UI customization options for SDK beneficiary form fields. */
+/** Per-field UI customization for the beneficiary form. */
 interface NiumFieldCustomization {
     hidden?: boolean;
     disabled?: boolean;
 }
-/** Per-section UI customization options for SDK beneficiary form sections. */
+/** Per-section UI customization for the beneficiary form. */
 interface NiumSectionCustomization {
     hidden?: boolean;
 }
-/** Supported beneficiary form field paths for `customizations.fields`. */
-type NiumBeneficiaryFieldPath = 'name' | 'entityType' | 'line1' | 'line2' | 'city' | 'state' | 'postalCode' | 'countryCode' | 'communicationPreference' | 'contactNumber' | 'email' | 'termsCheckbox' | 'helperText';
-type NiumBeneficiarySectionPath = 'demographicInfo' | 'communicationPreferences' | 'accountType' | 'bankAccountDetails';
-type NiumBeneficiaryFieldCustomizations = Partial<Record<NiumBeneficiaryFieldPath | string, NiumFieldCustomization>>;
-type NiumBeneficiarySectionCustomizations = Partial<Record<NiumBeneficiarySectionPath | string, NiumSectionCustomization>>;
-/** Intent for the payment (beneficiary) form */
+/** Known field paths on the beneficiary form; additional paths are accepted. */
+type NiumBeneficiaryFieldPath = LooseStringUnion<'name' | 'entityType' | 'line1' | 'line2' | 'city' | 'state' | 'postalCode' | 'countryCode' | 'communicationPreference' | 'contactNumber' | 'email' | 'termsCheckbox' | 'helperText'>;
+/** Known section paths on the beneficiary form; additional paths are accepted. */
+type NiumBeneficiarySectionPath = LooseStringUnion<'demographicInfo' | 'communicationPreferences' | 'accountType' | 'bankAccountDetails'>;
+type NiumBeneficiaryFieldCustomizations = Partial<Record<NiumBeneficiaryFieldPath, NiumFieldCustomization>>;
+type NiumBeneficiarySectionCustomizations = Partial<Record<NiumBeneficiarySectionPath, NiumSectionCustomization>>;
+/** Intent driving how the payment form behaves on submit. */
 type NiumPaymentIntent = 'create_beneficiary' | 'return_payload' | 'update_beneficiary';
-/** Prefill data for the payment (beneficiary) form */
+/** Prefill payload for the payment (beneficiary) form. */
 interface NiumPaymentPrefill {
     name?: string;
     email?: string;
@@ -66,23 +87,27 @@ interface NiumPaymentPrefill {
         countryCode?: string;
     };
 }
-/** Options passed to `createElement()` */
+/** Options accepted by {@link createElement}. */
 interface NiumElementOptions {
-    /** Customer hash ID */
+    /** Customer identifier. Required. */
     customerHashId?: string;
-    /** Pre-fill form fields */
+    /** Initial values for the form. Ignored for `update_beneficiary`. */
     prefill?: NiumPaymentPrefill;
-    /** Custom theme overrides */
+    /** Visual theme overrides. */
     theme?: NiumTheme;
-    /** Form intent: 'create_beneficiary' creates and returns beneficiaryId + payload; 'return_payload' returns payload only; 'update_beneficiary' updates an existing beneficiary */
+    /** Behaviour of the submit action. Required. */
     intent?: NiumPaymentIntent;
-    /** Beneficiary hash ID (required for 'update_beneficiary' intent) */
+    /** Beneficiary identifier. Required when `intent === 'update_beneficiary'`. */
     beneficiaryHashId?: string;
-    /** Custom minimum height for the iframe (default: 400) */
+    /** Iframe sizing and field/section visibility. */
     customizations?: {
+        /** Minimum iframe height in pixels. Default: 400. */
         minHeight?: number;
+        /** Maximum iframe height in pixels. Default: 804. */
         maxHeight?: number;
+        /** Per-field visibility/disabled overrides. */
         fields?: NiumBeneficiaryFieldCustomizations;
+        /** Per-section visibility overrides. */
         sections?: NiumBeneficiarySectionCustomizations;
     };
 }
@@ -97,6 +122,7 @@ interface NiumChangeEvent {
     type: 'change';
     data: Record<string, unknown>;
 }
+/** Opaque result payload returned by the hosted form on successful submit. */
 type NiumSubmitResult = Record<string, unknown>;
 interface NiumSubmitEvent {
     type: 'submit';
@@ -113,7 +139,7 @@ interface NiumCancelEvent {
     type: 'cancel';
 }
 type NiumEvent = NiumReadyEvent | NiumResizeEvent | NiumChangeEvent | NiumSubmitEvent | NiumErrorEvent | NiumCancelEvent;
-/** Map of event type string -> payload */
+/** Event name → event payload map. */
 interface NiumEventMap {
     ready: NiumReadyEvent;
     resize: NiumResizeEvent;
@@ -122,57 +148,101 @@ interface NiumEventMap {
     error: NiumErrorEvent;
     cancel: NiumCancelEvent;
 }
-/** Callback signature for a given event type */
+/** Callback signature for a given event name. */
 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).
+ * A mounted instance of a hosted NIUM form. Created by {@link createElement}
+ * and rendered via {@link NiumElement.mount}.
+ *
+ * The element wraps a single iframe pointing at the web-onboard hosted form
+ * and translates its postMessage events into typed callbacks. It also exposes
+ * a programmatic {@link NiumElement.submit} method for parent-driven submits.
+ *
+ * Lifecycle:
+ *   `new` → `mount()` → events → `submit()` | `destroy()`
+ *
+ * A destroyed element cannot be re-mounted; create a new one instead.
  */
 declare class NiumElement {
     private readonly iframeSrc;
     private readonly elementType;
     private readonly options;
+    private readonly origin;
     private iframe;
     private container;
     private listeners;
-    private boundMessageHandler;
+    private messageHandler;
     private destroyed;
-    private readonly origin;
+    /** Pending `submit()` promise — resolved/rejected when the iframe responds. */
     private pendingSubmit;
     constructor(iframeSrc: string, elementType: NiumElementType, options: NiumElementOptions, origin: string);
-    /** 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: string | HTMLElement): void;
-    /** 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(): void;
-    /** 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(): 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).
+     * Programmatically trigger form submission from the parent application.
      *
-     * @returns Promise that resolves with the submit result or rejects with an error.
-     *
-     * @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).
      */
     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. */
+    /** Remove a previously registered listener. */
     off<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): void;
+    private createIframe;
+    /** Top-level `postMessage` handler. Delegates to focused helpers per event. */
     private handleMessage;
+    /**
+     * 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.
+     */
+    private parseTrustedMessage;
+    /**
+     * 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`.
+     */
+    private applySideEffects;
+    private applyResize;
+    private resolvePendingSubmit;
+    private rejectPendingSubmit;
+    /** Dispatch a typed event payload to every registered listener. */
+    private dispatchEvent;
 }
 
 /**
- * Initialize the SDK. Must be called once before `createElement`.
+ * Entry point for `@nium/nium-sdk`.
+ *
+ * Public surface:
+ *  - {@link init}          — configure the SDK (environment + auth)
+ *  - {@link createElement} — build a mountable hosted form element
+ *  - {@link NiumElement}   — the element class, re-exported for type use
+ *  - Type re-exports       — every public type consumed by integrators
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Initialize the SDK. Must be called exactly once before {@link createElement}.
  *
  * @example
  * ```ts
@@ -181,15 +251,20 @@ declare class NiumElement {
  * await init({
  *   env: 'sandbox',
  *   authCode: '<auth-code-from-niam>',
+ *   codeVerifier: '<pkce-code-verifier>',
+ *   clientId: '<nium-client-id>',
  * })
  *
- * const element = await createElement('payment')
+ * const element = await createElement('payment', {
+ *   customerHashId: '<customer-hash-id>',
+ *   intent: 'create_beneficiary',
+ * })
  * element.mount('#container')
  *
- * // Option A: listen for submit events
+ * // Option A — react to form-driven submit
  * element.on('submit', (e) => console.log(e.result))
  *
- * // Option B: programmatic submit from parent
+ * // Option B — drive submit from the parent app
  * const result = await element.submit()
  * ```
  */
@@ -197,10 +272,12 @@ 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
+ * @param type    Module to render: `'payment' | 'tax' | 'identity' | 'full'`
+ * @param options Per-element configuration (customer, intent, prefill, theme,
+ *                customizations).
+ * @returns A {@link NiumElement} that can be mounted, listened to, submitted,
+ *          and destroyed.
  */
 declare const createElement: (type: NiumElementType, options?: NiumElementOptions) => Promise<NiumElement>;
 
-export { type NiumBeneficiaryFieldCustomizations, type NiumBeneficiaryFieldPath, type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumFieldCustomization, type NiumInitOptions, type NiumPaymentIntent, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };
+export { type NiumBeneficiaryFieldCustomizations, type NiumBeneficiaryFieldPath, type NiumBeneficiarySectionCustomizations, type NiumBeneficiarySectionPath, type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumFieldCustomization, type NiumInitOptions, type NiumPaymentIntent, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSectionCustomization, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };

package/dist/index.d.ts

@@ -1,27 +1,47 @@
-/** Environments supported by the SDK */
-type NiumEnv = 'local' | 'sandbox' | 'qa' | 'production' | string;
-/** Module types that map to web-onboard routes */
+/**
+ * Public type definitions for `@nium/nium-sdk`.
+ *
+ * These types are intentionally framework-agnostic. They describe the shape of
+ * configuration accepted by {@link init} and {@link createElement}, the events
+ * emitted by a mounted element, and the postMessage contract with the hosted
+ * form.
+ *
+ * Any change here is a public API change — keep it additive where possible.
+ */
+/**
+ * A "loose autocomplete" string union: editors will suggest the listed
+ * literals while still accepting any other string. Prefer this over a bare
+ * `Literal | string` union, which collapses to `string` and loses intellisense
+ * (and trips `sonarjs/S6571`).
+ */
+type LooseStringUnion<T extends string> = T | (string & Record<never, never>);
+/** Target environment for the hosted onboarding form. */
+type NiumEnv = 'local' | 'qa' | 'preprod' | 'sandbox' | 'production';
+/** Supported module types. Each maps to a dedicated route inside web-onboard. */
 type NiumElementType = 'payment' | 'tax' | 'identity' | 'full';
-/** Configuration passed to `init()` */
+/** Configuration accepted by the top-level `init()` call. */
 interface NiumInitOptions {
-    /** Target environment */
+    /** Target environment; determines the default hosted form URL. */
     env: NiumEnv;
-    /** Optional locale (defaults to 'en') */
+    /** BCP-47 locale code (for example `en`, `en-GB`, `es`). Defaults to `en`. */
     locale?: string;
-    /** Override the hosted form base URL (useful for local dev) */
+    /** Override the hosted form base URL. Primarily for local development. */
     hostedFormUrl?: string;
-    /** Authorization code from NIAM oauth/authcode */
+    /** Short-lived authorization code obtained from NIAM via OAuth 2.1 / PKCE. */
     authCode?: string;
-    /** PKCE code verifier corresponding to the code challenge sent to get authCode */
+    /** PKCE code verifier that matches the code challenge used to obtain `authCode`. */
     codeVerifier?: string;
-    /** Customer hash ID */
+    /** Identifier of the customer the form is being rendered for. */
     customerHashId?: string;
-    /** Client ID */
+    /** NIUM client identifier. */
     clientId?: string;
-    /** Pre-exchanged session token (temporary — bypasses auth code exchange) */
+    /** Pre-exchanged session token. When present, `authCode`/`codeVerifier` are bypassed. */
     sessionToken?: string;
 }
-/** Theme options for embedded components */
+/**
+ * Theme overrides applied to the embedded form. Every property is optional;
+ * unspecified values fall back to the form's default design tokens.
+ */
 interface NiumTheme {
     borderRadius?: string;
     fontFamily?: string;
@@ -35,23 +55,24 @@ interface NiumTheme {
     labelBackgroundColor?: string;
     radioColor?: string;
 }
-/** Per-field UI customization options for SDK beneficiary form fields. */
+/** Per-field UI customization for the beneficiary form. */
 interface NiumFieldCustomization {
     hidden?: boolean;
     disabled?: boolean;
 }
-/** Per-section UI customization options for SDK beneficiary form sections. */
+/** Per-section UI customization for the beneficiary form. */
 interface NiumSectionCustomization {
     hidden?: boolean;
 }
-/** Supported beneficiary form field paths for `customizations.fields`. */
-type NiumBeneficiaryFieldPath = 'name' | 'entityType' | 'line1' | 'line2' | 'city' | 'state' | 'postalCode' | 'countryCode' | 'communicationPreference' | 'contactNumber' | 'email' | 'termsCheckbox' | 'helperText';
-type NiumBeneficiarySectionPath = 'demographicInfo' | 'communicationPreferences' | 'accountType' | 'bankAccountDetails';
-type NiumBeneficiaryFieldCustomizations = Partial<Record<NiumBeneficiaryFieldPath | string, NiumFieldCustomization>>;
-type NiumBeneficiarySectionCustomizations = Partial<Record<NiumBeneficiarySectionPath | string, NiumSectionCustomization>>;
-/** Intent for the payment (beneficiary) form */
+/** Known field paths on the beneficiary form; additional paths are accepted. */
+type NiumBeneficiaryFieldPath = LooseStringUnion<'name' | 'entityType' | 'line1' | 'line2' | 'city' | 'state' | 'postalCode' | 'countryCode' | 'communicationPreference' | 'contactNumber' | 'email' | 'termsCheckbox' | 'helperText'>;
+/** Known section paths on the beneficiary form; additional paths are accepted. */
+type NiumBeneficiarySectionPath = LooseStringUnion<'demographicInfo' | 'communicationPreferences' | 'accountType' | 'bankAccountDetails'>;
+type NiumBeneficiaryFieldCustomizations = Partial<Record<NiumBeneficiaryFieldPath, NiumFieldCustomization>>;
+type NiumBeneficiarySectionCustomizations = Partial<Record<NiumBeneficiarySectionPath, NiumSectionCustomization>>;
+/** Intent driving how the payment form behaves on submit. */
 type NiumPaymentIntent = 'create_beneficiary' | 'return_payload' | 'update_beneficiary';
-/** Prefill data for the payment (beneficiary) form */
+/** Prefill payload for the payment (beneficiary) form. */
 interface NiumPaymentPrefill {
     name?: string;
     email?: string;
@@ -66,23 +87,27 @@ interface NiumPaymentPrefill {
         countryCode?: string;
     };
 }
-/** Options passed to `createElement()` */
+/** Options accepted by {@link createElement}. */
 interface NiumElementOptions {
-    /** Customer hash ID */
+    /** Customer identifier. Required. */
     customerHashId?: string;
-    /** Pre-fill form fields */
+    /** Initial values for the form. Ignored for `update_beneficiary`. */
     prefill?: NiumPaymentPrefill;
-    /** Custom theme overrides */
+    /** Visual theme overrides. */
     theme?: NiumTheme;
-    /** Form intent: 'create_beneficiary' creates and returns beneficiaryId + payload; 'return_payload' returns payload only; 'update_beneficiary' updates an existing beneficiary */
+    /** Behaviour of the submit action. Required. */
     intent?: NiumPaymentIntent;
-    /** Beneficiary hash ID (required for 'update_beneficiary' intent) */
+    /** Beneficiary identifier. Required when `intent === 'update_beneficiary'`. */
     beneficiaryHashId?: string;
-    /** Custom minimum height for the iframe (default: 400) */
+    /** Iframe sizing and field/section visibility. */
     customizations?: {
+        /** Minimum iframe height in pixels. Default: 400. */
         minHeight?: number;
+        /** Maximum iframe height in pixels. Default: 804. */
         maxHeight?: number;
+        /** Per-field visibility/disabled overrides. */
         fields?: NiumBeneficiaryFieldCustomizations;
+        /** Per-section visibility overrides. */
         sections?: NiumBeneficiarySectionCustomizations;
     };
 }
@@ -97,6 +122,7 @@ interface NiumChangeEvent {
     type: 'change';
     data: Record<string, unknown>;
 }
+/** Opaque result payload returned by the hosted form on successful submit. */
 type NiumSubmitResult = Record<string, unknown>;
 interface NiumSubmitEvent {
     type: 'submit';
@@ -113,7 +139,7 @@ interface NiumCancelEvent {
     type: 'cancel';
 }
 type NiumEvent = NiumReadyEvent | NiumResizeEvent | NiumChangeEvent | NiumSubmitEvent | NiumErrorEvent | NiumCancelEvent;
-/** Map of event type string -> payload */
+/** Event name → event payload map. */
 interface NiumEventMap {
     ready: NiumReadyEvent;
     resize: NiumResizeEvent;
@@ -122,57 +148,101 @@ interface NiumEventMap {
     error: NiumErrorEvent;
     cancel: NiumCancelEvent;
 }
-/** Callback signature for a given event type */
+/** Callback signature for a given event name. */
 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).
+ * A mounted instance of a hosted NIUM form. Created by {@link createElement}
+ * and rendered via {@link NiumElement.mount}.
+ *
+ * The element wraps a single iframe pointing at the web-onboard hosted form
+ * and translates its postMessage events into typed callbacks. It also exposes
+ * a programmatic {@link NiumElement.submit} method for parent-driven submits.
+ *
+ * Lifecycle:
+ *   `new` → `mount()` → events → `submit()` | `destroy()`
+ *
+ * A destroyed element cannot be re-mounted; create a new one instead.
  */
 declare class NiumElement {
     private readonly iframeSrc;
     private readonly elementType;
     private readonly options;
+    private readonly origin;
     private iframe;
     private container;
     private listeners;
-    private boundMessageHandler;
+    private messageHandler;
     private destroyed;
-    private readonly origin;
+    /** Pending `submit()` promise — resolved/rejected when the iframe responds. */
     private pendingSubmit;
     constructor(iframeSrc: string, elementType: NiumElementType, options: NiumElementOptions, origin: string);
-    /** 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: string | HTMLElement): void;
-    /** 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(): void;
-    /** 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(): 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).
+     * Programmatically trigger form submission from the parent application.
      *
-     * @returns Promise that resolves with the submit result or rejects with an error.
-     *
-     * @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).
      */
     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. */
+    /** Remove a previously registered listener. */
     off<K extends keyof NiumEventMap>(event: K, callback: NiumEventCallback<K>): void;
+    private createIframe;
+    /** Top-level `postMessage` handler. Delegates to focused helpers per event. */
     private handleMessage;
+    /**
+     * 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.
+     */
+    private parseTrustedMessage;
+    /**
+     * 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`.
+     */
+    private applySideEffects;
+    private applyResize;
+    private resolvePendingSubmit;
+    private rejectPendingSubmit;
+    /** Dispatch a typed event payload to every registered listener. */
+    private dispatchEvent;
 }
 
 /**
- * Initialize the SDK. Must be called once before `createElement`.
+ * Entry point for `@nium/nium-sdk`.
+ *
+ * Public surface:
+ *  - {@link init}          — configure the SDK (environment + auth)
+ *  - {@link createElement} — build a mountable hosted form element
+ *  - {@link NiumElement}   — the element class, re-exported for type use
+ *  - Type re-exports       — every public type consumed by integrators
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Initialize the SDK. Must be called exactly once before {@link createElement}.
  *
  * @example
  * ```ts
@@ -181,15 +251,20 @@ declare class NiumElement {
  * await init({
  *   env: 'sandbox',
  *   authCode: '<auth-code-from-niam>',
+ *   codeVerifier: '<pkce-code-verifier>',
+ *   clientId: '<nium-client-id>',
  * })
  *
- * const element = await createElement('payment')
+ * const element = await createElement('payment', {
+ *   customerHashId: '<customer-hash-id>',
+ *   intent: 'create_beneficiary',
+ * })
  * element.mount('#container')
  *
- * // Option A: listen for submit events
+ * // Option A — react to form-driven submit
  * element.on('submit', (e) => console.log(e.result))
  *
- * // Option B: programmatic submit from parent
+ * // Option B — drive submit from the parent app
  * const result = await element.submit()
  * ```
  */
@@ -197,10 +272,12 @@ 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
+ * @param type    Module to render: `'payment' | 'tax' | 'identity' | 'full'`
+ * @param options Per-element configuration (customer, intent, prefill, theme,
+ *                customizations).
+ * @returns A {@link NiumElement} that can be mounted, listened to, submitted,
+ *          and destroyed.
  */
 declare const createElement: (type: NiumElementType, options?: NiumElementOptions) => Promise<NiumElement>;
 
-export { type NiumBeneficiaryFieldCustomizations, type NiumBeneficiaryFieldPath, type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumFieldCustomization, type NiumInitOptions, type NiumPaymentIntent, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };
+export { type NiumBeneficiaryFieldCustomizations, type NiumBeneficiaryFieldPath, type NiumBeneficiarySectionCustomizations, type NiumBeneficiarySectionPath, type NiumCancelEvent, type NiumChangeEvent, NiumElement, type NiumElementOptions, type NiumElementType, type NiumEnv, type NiumErrorEvent, type NiumEvent, type NiumEventCallback, type NiumEventMap, type NiumFieldCustomization, type NiumInitOptions, type NiumPaymentIntent, type NiumPaymentPrefill, type NiumReadyEvent, type NiumResizeEvent, type NiumSectionCustomization, type NiumSubmitEvent, type NiumSubmitResult, type NiumTheme, createElement, init };