@ozura/elements 1.3.1 → 1.4.0

package/dist/react/index.esm.js

@@ -1115,7 +1115,7 @@ class OzVault {
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
-                    options.onLoadError();
+                    options.onLoadError({ source: 'tokenizer' });
                 }
             }, timeout);
         }
@@ -1248,6 +1248,49 @@ class OzVault {
     get tokenizeCount() {
         return this._tokenizeSuccessCount;
     }
+    /**
+     * `true` when every mounted field has reported `complete && valid` via its
+     * last `change` event. `false` if no fields have been created, or if any
+     * field is incomplete or invalid.
+     *
+     * Use this to gate the pay button in vanilla JS integrations without having
+     * to wire up individual `change` event listeners:
+     *
+     * @example
+     * vault.getElement('cardNumber')!.on('change', () => {
+     *   payBtn.disabled = !vault.isComplete;
+     * });
+     */
+    get isComplete() {
+        return this.allComplete([...this.elementsByType.values()]);
+    }
+    /**
+     * Like {@link isComplete}, but for bank-account elements created via
+     * {@link createBankElement}. Card and bank fields are tracked separately so a
+     * card-only checkout is never gated on bank fields (and vice versa), matching
+     * the `createToken()` / `createBankToken()` split. A vault with both card and
+     * bank elements exposes each completion state independently.
+     */
+    get isBankComplete() {
+        return this.allComplete([...this.bankElementsByType.values()]);
+    }
+    /** True iff the set is non-empty and every element has reported complete-and-valid. */
+    allComplete(els) {
+        if (els.length === 0)
+            return false;
+        return els.every(el => this.completionState.get(el.frameId) === true);
+    }
+    /**
+     * `true` while a `createToken()` or `createBankToken()` call is in progress
+     * (including the transparent wax-key refresh phase). Use this to keep the pay
+     * button disabled during tokenization to prevent double-submission.
+     *
+     * @example
+     * payBtn.disabled = vault.isTokenizing;
+     */
+    get isTokenizing() {
+        return this._tokenizing !== null;
+    }
     /**
      * Creates a new OzElement of the given type. Call `.mount(selector)` on the
      * returned element to attach it to the DOM.
@@ -1330,17 +1373,29 @@ class OzVault {
                 ? 'A card tokenization is already in progress. Wait for it to complete before calling createBankToken().'
                 : 'A bank tokenization is already in progress. Wait for it to complete before calling createBankToken() again.');
         }
-        if (!((_a = options.firstName) === null || _a === void 0 ? void 0 : _a.trim())) {
-            throw new OzError('firstName is required for bank account tokenization.');
-        }
-        if (!((_b = options.lastName) === null || _b === void 0 ? void 0 : _b.trim())) {
-            throw new OzError('lastName is required for bank account tokenization.');
-        }
-        if (options.firstName.trim().length > 50) {
-            throw new OzError('firstName must be 50 characters or fewer.');
+        // Validate billing details if provided — billing.firstName/lastName take
+        // precedence over the top-level params (mirrors createToken() behaviour).
+        let normalizedBankBilling;
+        let bankFirstName = ((_a = options.firstName) !== null && _a !== void 0 ? _a : '').trim();
+        let bankLastName = ((_b = options.lastName) !== null && _b !== void 0 ? _b : '').trim();
+        if (options.billing) {
+            const result = validateBilling(options.billing);
+            if (!result.valid) {
+                throw new OzError(`Invalid billing details: ${result.errors.join('; ')}`);
+            }
+            normalizedBankBilling = result.normalized;
+            bankFirstName = normalizedBankBilling.firstName;
+            bankLastName = normalizedBankBilling.lastName;
         }
-        if (options.lastName.trim().length > 50) {
-            throw new OzError('lastName must be 50 characters or fewer.');
+        else {
+            if (!bankFirstName)
+                throw new OzError('firstName is required for bank account tokenization.');
+            if (!bankLastName)
+                throw new OzError('lastName is required for bank account tokenization.');
+            if (bankFirstName.length > 50)
+                throw new OzError('firstName must be 50 characters or fewer.');
+            if (bankLastName.length > 50)
+                throw new OzError('lastName must be 50 characters or fewer.');
         }
         const accountEl = this.bankElementsByType.get('accountNumber');
         const routingEl = this.bankElementsByType.get('routingNumber');
@@ -1366,14 +1421,7 @@ class OzVault {
                 if (this._resetCount === resetCountAtStart)
                     this._tokenizing = null;
             };
-            this.bankTokenizeResolvers.set(requestId, {
-                resolve: (v) => { cleanup(); resolve(v); },
-                reject: (e) => { cleanup(); reject(e); },
-                firstName: options.firstName.trim(),
-                lastName: options.lastName.trim(),
-                readyElements: readyBankElements,
-                fieldCount: readyBankElements.length,
-            });
+            this.bankTokenizeResolvers.set(requestId, Object.assign(Object.assign({ resolve: (v) => { cleanup(); resolve(v); }, reject: (e) => { cleanup(); reject(e); }, firstName: bankFirstName, lastName: bankLastName }, (normalizedBankBilling ? { billing: normalizedBankBilling } : {})), { readyElements: readyBankElements, fieldCount: readyBankElements.length }));
             try {
                 const bankChannels = readyBankElements.map(() => new MessageChannel());
                 const bankTokenizeStartMs = Date.now();
@@ -1382,8 +1430,8 @@ class OzVault {
                     requestId,
                     tokenizationSessionId: this.tokenizationSessionId,
                     pubKey: (_a = this.pubKey) !== null && _a !== void 0 ? _a : '',
-                    firstName: options.firstName.trim(),
-                    lastName: options.lastName.trim(),
+                    firstName: bankFirstName,
+                    lastName: bankLastName,
                     fieldCount: readyBankElements.length,
                 }, bankChannels.map(ch => ch.port1));
                 this.log('OZ_BANK_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyBankElements.length });
@@ -2105,7 +2153,7 @@ class OzVault {
                         break;
                     }
                     const bank = isBankAccountMetadata(msg.bank) ? msg.bank : undefined;
-                    pending.resolve(Object.assign({ token }, (bank ? { bank } : {})));
+                    pending.resolve(Object.assign(Object.assign({ token }, (bank ? { bank } : {})), (pending.billing ? { billing: pending.billing } : {})));
                     this.log('bank token received', {
                         elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
                         tokenPresent: true,
@@ -2235,9 +2283,11 @@ const OzContext = createContext({
     notifyUnmount: () => { },
     notifyMount: () => { },
     notifyTokenize: () => { },
+    notifyChange: () => { },
     mountedCount: 0,
     readyCount: 0,
     tokenizeCount: 0,
+    changeTick: 0,
 });
 /**
  * Creates and owns an OzVault instance for the lifetime of this component.
@@ -2250,6 +2300,7 @@ function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseU
     const [mountedCount, setMountedCount] = useState(0);
     const [readyCount, setReadyCount] = useState(0);
     const [tokenizeCount, setTokenizeCount] = useState(0);
+    const [changeTick, setChangeTick] = useState(0);
     const onLoadErrorRef = useRef(onLoadError);
     onLoadErrorRef.current = onLoadError;
     const onWaxRefreshRef = useRef(onSessionRefresh !== null && onSessionRefresh !== void 0 ? onSessionRefresh : onWaxRefresh);
@@ -2288,7 +2339,7 @@ function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseU
             if (loadErrorFired)
                 return;
             loadErrorFired = true;
-            (_a = onLoadErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onLoadErrorRef);
+            (_a = onLoadErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onLoadErrorRef, { source: 'tokenizer' });
         };
         // AbortController passed to create() so that if this effect's cleanup runs
         // while fetchWaxKey is still in-flight (React StrictMode double-invoke or
@@ -2372,7 +2423,8 @@ function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseU
         setReadyCount(n => Math.max(0, n - 1));
     }, []);
     const notifyTokenize = useCallback(() => setTokenizeCount(n => n + 1), []);
-    const value = useMemo(() => ({ vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, mountedCount, readyCount, tokenizeCount }), [vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, mountedCount, readyCount, tokenizeCount]);
+    const notifyChange = useCallback(() => setChangeTick(n => n + 1), []);
+    const value = useMemo(() => ({ vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, notifyChange, mountedCount, readyCount, tokenizeCount, changeTick }), [vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, notifyChange, mountedCount, readyCount, tokenizeCount, changeTick]);
     return jsx(OzContext.Provider, { value: value, children: children });
 }
 /**
@@ -2380,28 +2432,53 @@ function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseU
  * an `<OzElements>` provider tree.
  */
 function useOzElements() {
-    const { vault, initError, mountedCount, readyCount, notifyTokenize, tokenizeCount } = useContext(OzContext);
+    var _a, _b, _c;
+    const { vault, initError, mountedCount, readyCount, notifyTokenize, notifyChange, tokenizeCount } = useContext(OzContext);
     const createToken = useCallback(async (options) => {
         if (!vault) {
             return Promise.reject(new OzError('useOzElements must be called inside an <OzElements> provider.'));
         }
-        const result = await vault.createToken(options);
-        notifyTokenize();
-        return result;
-    }, [vault, notifyTokenize]);
+        // Start the call so vault._tokenizing flips synchronously, then notify so
+        // `isTokenizing` re-renders as `true`. Notify again on settle so it returns
+        // to `false`. (vault.isTokenizing is a plain getter — nothing else would
+        // trigger a render while the call is in flight.)
+        const promise = vault.createToken(options);
+        notifyChange();
+        try {
+            const result = await promise;
+            notifyTokenize();
+            return result;
+        }
+        finally {
+            notifyChange();
+        }
+    }, [vault, notifyTokenize, notifyChange]);
     const createBankToken = useCallback(async (options) => {
         if (!vault) {
             return Promise.reject(new OzError('useOzElements must be called inside an <OzElements> provider.'));
         }
-        const result = await vault.createBankToken(options);
-        notifyTokenize();
-        return result;
-    }, [vault, notifyTokenize]);
+        const promise = vault.createBankToken(options);
+        notifyChange();
+        try {
+            const result = await promise;
+            notifyTokenize();
+            return result;
+        }
+        finally {
+            notifyChange();
+        }
+    }, [vault, notifyTokenize, notifyChange]);
     const reset = useCallback(() => {
         vault === null || vault === void 0 ? void 0 : vault.reset();
-    }, [vault]);
+        // reset() clears completion state and cancels any in-flight tokenization, so
+        // re-render to refresh the derived isComplete / isTokenizing getters below.
+        notifyChange();
+    }, [vault, notifyChange]);
     const ready = vault !== null && vault.isReady && mountedCount > 0 && readyCount >= mountedCount;
-    return { createToken, createBankToken, reset, ready, initError, tokenizeCount };
+    const isComplete = (_a = vault === null || vault === void 0 ? void 0 : vault.isComplete) !== null && _a !== void 0 ? _a : false;
+    const isBankComplete = (_b = vault === null || vault === void 0 ? void 0 : vault.isBankComplete) !== null && _b !== void 0 ? _b : false;
+    const isTokenizing = (_c = vault === null || vault === void 0 ? void 0 : vault.isTokenizing) !== null && _c !== void 0 ? _c : false;
+    return { createToken, createBankToken, reset, ready, initError, tokenizeCount, isComplete, isBankComplete, isTokenizing };
 }
 const SKELETON_STYLE = {
     height: 46,
@@ -2436,7 +2513,7 @@ function OzFieldBase({ type, variant, style, placeholder, disabled, loadTimeoutM
     const elementRef = useRef(null);
     const [loaded, setLoaded] = useState(false);
     const [loadError, setLoadError] = useState(null);
-    const { vault, notifyMount, notifyReady, notifyUnmount } = useContext(OzContext);
+    const { vault, notifyMount, notifyReady, notifyUnmount, notifyChange } = useContext(OzContext);
     const onChangeRef = useRef(onChange);
     const onFocusRef = useRef(onFocus);
     const onBlurRef = useRef(onBlur);
@@ -2468,7 +2545,7 @@ function OzFieldBase({ type, variant, style, placeholder, disabled, loadTimeoutM
             notifyReady();
             (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
         });
-        element.on('change', (e) => { var _a; return (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, e); });
+        element.on('change', (e) => { var _a; (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, e); notifyChange(); });
         element.on('focus', () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef); });
         element.on('blur', () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef); });
         element.on('loaderror', (e) => {
@@ -2701,4 +2778,3 @@ function OzBankCard({ style, styles, classNames, labels, labelStyle, labelClassN
 }
 
 export { OzBankAccountNumber, OzBankCard, OzBankRoutingNumber, OzCard, OzCardNumber, OzCvv, OzElements, OzExpiry, createSessionFetcher as createFetchWaxKey, createSessionFetcher, useOzElements };
-//# sourceMappingURL=index.esm.js.map

package/dist/react/react/index.d.ts

@@ -93,7 +93,9 @@ export interface OzElementsProps {
      */
     fonts?: FontSource[];
     /** Called if the tokenizer iframe fails to load within `loadTimeoutMs`. */
-    onLoadError?: () => void;
+    onLoadError?: (info?: {
+        source: 'tokenizer';
+    }) => void;
     /** How long to wait (ms) for the tokenizer iframe before calling `onLoadError`. Default: 10 000. */
     loadTimeoutMs?: number;
     /**
@@ -223,6 +225,32 @@ export interface UseOzElementsReturn {
      * if (attemptsLeft === 1) <p>Last payment attempt available.</p>;
      */
     tokenizeCount: number;
+    /**
+     * `true` when every mounted field has reported `complete && valid`.
+     * Use this to gate the pay button without wiring individual `onChange`
+     * listeners — reacts in real time as the customer fills in fields.
+     *
+     * @example
+     * const { ready, isComplete, createToken } = useOzElements();
+     * <button disabled={!ready || !isComplete} onClick={() => createToken()}>Pay</button>
+     */
+    isComplete: boolean;
+    /**
+     * Like `isComplete`, but for bank-account fields (`OzBankCard` /
+     * `createBankElement`). Card and bank completion are tracked independently, so
+     * a card-only form isn't gated on bank fields and vice versa.
+     */
+    isBankComplete: boolean;
+    /**
+     * `true` while `createToken()` or `createBankToken()` is in progress,
+     * including the transparent wax-key refresh phase. Use this to keep the
+     * pay button disabled and prevent double-submission.
+     *
+     * @example
+     * const { isTokenizing, createToken } = useOzElements();
+     * <button disabled={isTokenizing} onClick={() => createToken()}>Pay</button>
+     */
+    isTokenizing: boolean;
 }
 /**
  * Returns `createToken` and the `ready` flag. Must be called from inside

package/dist/react/sdk/OzVault.d.ts

@@ -107,6 +107,39 @@ export declare class OzVault {
      * payButton.textContent = remaining > 0 ? `Pay (${remaining} attempts left)` : 'Pay';
      */
     get tokenizeCount(): number;
+    /**
+     * `true` when every mounted field has reported `complete && valid` via its
+     * last `change` event. `false` if no fields have been created, or if any
+     * field is incomplete or invalid.
+     *
+     * Use this to gate the pay button in vanilla JS integrations without having
+     * to wire up individual `change` event listeners:
+     *
+     * @example
+     * vault.getElement('cardNumber')!.on('change', () => {
+     *   payBtn.disabled = !vault.isComplete;
+     * });
+     */
+    get isComplete(): boolean;
+    /**
+     * Like {@link isComplete}, but for bank-account elements created via
+     * {@link createBankElement}. Card and bank fields are tracked separately so a
+     * card-only checkout is never gated on bank fields (and vice versa), matching
+     * the `createToken()` / `createBankToken()` split. A vault with both card and
+     * bank elements exposes each completion state independently.
+     */
+    get isBankComplete(): boolean;
+    /** True iff the set is non-empty and every element has reported complete-and-valid. */
+    private allComplete;
+    /**
+     * `true` while a `createToken()` or `createBankToken()` call is in progress
+     * (including the transparent wax-key refresh phase). Use this to keep the pay
+     * button disabled during tokenization to prevent double-submission.
+     *
+     * @example
+     * payBtn.disabled = vault.isTokenizing;
+     */
+    get isTokenizing(): boolean;
     /**
      * Creates a new OzElement of the given type. Call `.mount(selector)` on the
      * returned element to attach it to the DOM.

package/dist/react/types/index.d.ts

@@ -223,8 +223,14 @@ export interface VaultOptions {
     /**
      * Called if the tokenizer iframe fails to signal ready within `loadTimeoutMs`.
      * Use this to show a fallback UI (e.g. "Unable to load payment fields").
+     *
+     * Receives an optional `info` object with a `source` field identifying which
+     * iframe timed out. Currently always `'tokenizer'` — element-level load errors
+     * fire the `loaderror` event on the individual element instead.
      */
-    onLoadError?: () => void;
+    onLoadError?: (info?: {
+        source: 'tokenizer';
+    }) => void;
     /** How long to wait (ms) for the tokenizer iframe before calling `onLoadError`. Default: 10 000.
      * Only takes effect when `onLoadError` is also provided — setting this without `onLoadError` has no effect. */
     loadTimeoutMs?: number;
@@ -350,10 +356,24 @@ export interface TokenizeOptions {
 }
 /** Options for `vault.createBankToken()`. */
 export interface BankTokenizeOptions {
-    /** Account holder first name. Required. */
-    firstName: string;
-    /** Account holder last name. Required. */
-    lastName: string;
+    /**
+     * Account holder first name.
+     * Required when `billing` is not provided.
+     * @deprecated Pass firstName inside `billing` instead.
+     */
+    firstName?: string;
+    /**
+     * Account holder last name.
+     * Required when `billing` is not provided.
+     * @deprecated Pass lastName inside `billing` instead.
+     */
+    lastName?: string;
+    /**
+     * Billing details for the account holder. When provided, `billing.firstName`
+     * and `billing.lastName` take precedence over the top-level fields.
+     * The normalized details are echoed back in `BankTokenResponse.billing`.
+     */
+    billing?: BillingDetails;
 }
 /** Non-sensitive bank account metadata returned alongside the token. */
 export interface BankAccountMetadata {
@@ -406,6 +426,11 @@ export interface BankTokenResponse {
     token: string;
     /** Non-sensitive bank account metadata. */
     bank?: BankAccountMetadata;
+    /**
+     * Validated, normalized billing details — echoed back when billing was
+     * passed to createBankToken(). Ready to spread into your ACH processor request.
+     */
+    billing?: BillingDetails;
 }
 /**
  * Full request body for the Ozura Pay API cardSale endpoint.

package/dist/react/vue/index.d.ts

@@ -24,7 +24,7 @@
  * ```
  */
 import { type Ref, type PropType, type ComputedRef } from 'vue';
-import type { TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse, FontSource, Appearance } from '../types';
+import type { ElementOptions, TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse, FontSource, Appearance } from '../types';
 export interface OzElementsProps {
     /** Omit when using a test vault key from a Test project at ozuravault.com.
      *  Required for production vault keys. */
@@ -40,6 +40,14 @@ export interface OzElementsProps {
     onSessionRefresh?: () => void;
     /** Called once when the vault tokenizer and all mounted field iframes are ready. */
     onReady?: () => void;
+    /**
+     * Called if the tokenizer iframe fails to signal ready within `loadTimeoutMs`.
+     * Use this to show a fallback UI (e.g. "Payment fields failed to load").
+     * Receives an optional info object with `source: 'tokenizer'`.
+     */
+    onLoadError?: (info?: {
+        source: 'tokenizer';
+    }) => void;
     /**
      * Maximum number of tokenize calls before the vault proactively refreshes the session.
      * Must match the `sessionLimit` passed to `createSession()` on your server.
@@ -94,6 +102,12 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
         type: PropType<() => void>;
         default: undefined;
     };
+    onLoadError: {
+        type: PropType<(info?: {
+            source: "tokenizer";
+        }) => void>;
+        default: undefined;
+    };
     sessionLimit: {
         type: PropType<number | null>;
         default: undefined;
@@ -145,6 +159,12 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
         type: PropType<() => void>;
         default: undefined;
     };
+    onLoadError: {
+        type: PropType<(info?: {
+            source: "tokenizer";
+        }) => void>;
+        default: undefined;
+    };
     sessionLimit: {
         type: PropType<number | null>;
         default: undefined;
@@ -164,6 +184,9 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
     maxTokenizeCalls: number;
     sessionUrl: string;
     getSessionKey: (sessionId: string) => Promise<string>;
+    onLoadError: (info?: {
+        source: "tokenizer";
+    }) => void;
     onSessionRefresh: () => void;
     onReady: () => void;
     appearance: Appearance;
@@ -196,6 +219,32 @@ export interface UseOzElementsReturn {
      * Clears all mounted element fields without destroying the vault.
      */
     reset: () => void;
+    /**
+     * `true` when every mounted field has reported `complete && valid`.
+     * Use this to gate the pay button without wiring individual `@change`
+     * listeners — reacts in real time as the customer fills in fields.
+     *
+     * @example
+     * const { ready, isComplete, createToken } = useOzElements();
+     * // <button :disabled="!ready || !isComplete" @click="createToken()">Pay</button>
+     */
+    isComplete: ComputedRef<boolean>;
+    /**
+     * Like `isComplete`, but for bank-account fields (`createBankElement`). Card
+     * and bank completion are tracked independently, so a card-only form isn't
+     * gated on bank fields and vice versa.
+     */
+    isBankComplete: ComputedRef<boolean>;
+    /**
+     * `true` while `createToken()` or `createBankToken()` is in progress,
+     * including the transparent wax-key refresh phase. Use this to keep the
+     * pay button disabled and prevent double-submission.
+     *
+     * @example
+     * const { isTokenizing, createToken } = useOzElements();
+     * // <button :disabled="isTokenizing" @click="createToken()">Pay</button>
+     */
+    isTokenizing: ComputedRef<boolean>;
 }
 /**
  * Returns createToken, createBankToken, ready, initError, tokenizeCount, and reset.
@@ -204,6 +253,12 @@ export interface UseOzElementsReturn {
  * @throws {Error} if called outside an <OzElements> provider
  */
 export declare function useOzElements(): UseOzElementsReturn;
+/** Props accepted by all individual field components (OzCardNumber, OzExpiry, OzCvv, etc.). */
+export interface OzFieldProps {
+    placeholder?: string;
+    disabled?: boolean;
+    style?: ElementOptions['style'];
+}
 /** Card number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
 export declare const OzCardNumber: import("vue").DefineComponent<{
     placeholder?: string | undefined;

package/dist/server/sdk/OzVault.d.ts

@@ -107,6 +107,39 @@ export declare class OzVault {
      * payButton.textContent = remaining > 0 ? `Pay (${remaining} attempts left)` : 'Pay';
      */
     get tokenizeCount(): number;
+    /**
+     * `true` when every mounted field has reported `complete && valid` via its
+     * last `change` event. `false` if no fields have been created, or if any
+     * field is incomplete or invalid.
+     *
+     * Use this to gate the pay button in vanilla JS integrations without having
+     * to wire up individual `change` event listeners:
+     *
+     * @example
+     * vault.getElement('cardNumber')!.on('change', () => {
+     *   payBtn.disabled = !vault.isComplete;
+     * });
+     */
+    get isComplete(): boolean;
+    /**
+     * Like {@link isComplete}, but for bank-account elements created via
+     * {@link createBankElement}. Card and bank fields are tracked separately so a
+     * card-only checkout is never gated on bank fields (and vice versa), matching
+     * the `createToken()` / `createBankToken()` split. A vault with both card and
+     * bank elements exposes each completion state independently.
+     */
+    get isBankComplete(): boolean;
+    /** True iff the set is non-empty and every element has reported complete-and-valid. */
+    private allComplete;
+    /**
+     * `true` while a `createToken()` or `createBankToken()` call is in progress
+     * (including the transparent wax-key refresh phase). Use this to keep the pay
+     * button disabled during tokenization to prevent double-submission.
+     *
+     * @example
+     * payBtn.disabled = vault.isTokenizing;
+     */
+    get isTokenizing(): boolean;
     /**
      * Creates a new OzElement of the given type. Call `.mount(selector)` on the
      * returned element to attach it to the DOM.

package/dist/server/types/index.d.ts

@@ -223,8 +223,14 @@ export interface VaultOptions {
     /**
      * Called if the tokenizer iframe fails to signal ready within `loadTimeoutMs`.
      * Use this to show a fallback UI (e.g. "Unable to load payment fields").
+     *
+     * Receives an optional `info` object with a `source` field identifying which
+     * iframe timed out. Currently always `'tokenizer'` — element-level load errors
+     * fire the `loaderror` event on the individual element instead.
      */
-    onLoadError?: () => void;
+    onLoadError?: (info?: {
+        source: 'tokenizer';
+    }) => void;
     /** How long to wait (ms) for the tokenizer iframe before calling `onLoadError`. Default: 10 000.
      * Only takes effect when `onLoadError` is also provided — setting this without `onLoadError` has no effect. */
     loadTimeoutMs?: number;
@@ -350,10 +356,24 @@ export interface TokenizeOptions {
 }
 /** Options for `vault.createBankToken()`. */
 export interface BankTokenizeOptions {
-    /** Account holder first name. Required. */
-    firstName: string;
-    /** Account holder last name. Required. */
-    lastName: string;
+    /**
+     * Account holder first name.
+     * Required when `billing` is not provided.
+     * @deprecated Pass firstName inside `billing` instead.
+     */
+    firstName?: string;
+    /**
+     * Account holder last name.
+     * Required when `billing` is not provided.
+     * @deprecated Pass lastName inside `billing` instead.
+     */
+    lastName?: string;
+    /**
+     * Billing details for the account holder. When provided, `billing.firstName`
+     * and `billing.lastName` take precedence over the top-level fields.
+     * The normalized details are echoed back in `BankTokenResponse.billing`.
+     */
+    billing?: BillingDetails;
 }
 /** Non-sensitive bank account metadata returned alongside the token. */
 export interface BankAccountMetadata {
@@ -406,6 +426,11 @@ export interface BankTokenResponse {
     token: string;
     /** Non-sensitive bank account metadata. */
     bank?: BankAccountMetadata;
+    /**
+     * Validated, normalized billing details — echoed back when billing was
+     * passed to createBankToken(). Ready to spread into your ACH processor request.
+     */
+    billing?: BillingDetails;
 }
 /**
  * Full request body for the Ozura Pay API cardSale endpoint.