@ozura/elements 1.3.1-next.68 → 1.3.1-next.70

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;
@@ -204,6 +227,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,29 @@ 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;
+    /**
+     * `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.

package/dist/server/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;
@@ -168,6 +188,9 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
     appearance: Appearance;
     onSessionRefresh: () => void;
     onReady: () => void;
+    onLoadError: (info?: {
+        source: "tokenizer";
+    }) => void;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export interface UseOzElementsReturn {
     /**
@@ -204,6 +227,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/types/sdk/OzVault.d.ts

@@ -107,6 +107,29 @@ 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;
+    /**
+     * `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/types/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/types/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;
@@ -168,6 +188,9 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
     appearance: Appearance;
     onSessionRefresh: () => void;
     onReady: () => void;
+    onLoadError: (info?: {
+        source: "tokenizer";
+    }) => void;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export interface UseOzElementsReturn {
     /**
@@ -204,6 +227,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/vue/index.cjs.js

@@ -1116,7 +1116,7 @@ class OzVault {
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
-                    options.onLoadError();
+                    options.onLoadError({ source: 'tokenizer' });
                 }
             }, timeout);
         }
@@ -1249,6 +1249,39 @@ 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() {
+        if (this.elements.size === 0)
+            return false;
+        for (const frameId of this.elements.keys()) {
+            if (this.completionState.get(frameId) !== true)
+                return false;
+        }
+        return 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.
@@ -1331,17 +1364,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');
@@ -1367,14 +1412,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();
@@ -1383,8 +1421,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 });
@@ -2106,7 +2144,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,
@@ -2273,6 +2311,7 @@ const OzElements = vue.defineComponent({
         debug: { type: Boolean, default: undefined },
         onSessionRefresh: { type: Function, default: undefined },
         onReady: { type: Function, default: undefined },
+        onLoadError: { type: Function, default: undefined },
         sessionLimit: { type: Number, default: undefined },
         maxTokenizeCalls: { type: Number, default: undefined },
     },
@@ -2318,7 +2357,20 @@ const OzElements = vue.defineComponent({
         vue.onMounted(() => {
             const ac = new AbortController();
             abortController = ac;
-            OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey: props.pubKey }, (props.sessionUrl ? { sessionUrl: props.sessionUrl } : {})), (props.getSessionKey ? { getSessionKey: props.getSessionKey } : {})), (props.frameBaseUrl ? { frameBaseUrl: props.frameBaseUrl } : {})), (props.fonts ? { fonts: props.fonts } : {})), (props.appearance ? { appearance: props.appearance } : {})), (props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {})), (props.debug ? { debug: props.debug } : {})), { 
+            // Guard: onLoadError must fire at most once per mount cycle. It can be
+            // triggered by two independent paths — the vault's iframe load timeout
+            // (inside OzVault constructor) and the .catch below when create() rejects
+            // after the timeout has already fired. Without this flag both paths would
+            // call the callback, mirroring the same guard used in the React provider.
+            let loadErrorFired = false;
+            const fireLoadError = () => {
+                var _a;
+                if (loadErrorFired)
+                    return;
+                loadErrorFired = true;
+                (_a = props.onLoadError) === null || _a === void 0 ? void 0 : _a.call(props, { source: 'tokenizer' });
+            };
+            OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey: props.pubKey }, (props.sessionUrl ? { sessionUrl: props.sessionUrl } : {})), (props.getSessionKey ? { getSessionKey: props.getSessionKey } : {})), (props.frameBaseUrl ? { frameBaseUrl: props.frameBaseUrl } : {})), (props.fonts ? { fonts: props.fonts } : {})), (props.appearance ? { appearance: props.appearance } : {})), (props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {})), (props.onLoadError ? { onLoadError: fireLoadError } : {})), (props.debug ? { debug: props.debug } : {})), { 
                 // Session lifecycle — wire refresh callback and reset tokenizeCount so the
                 // counter stays accurate across proactive key refreshes (mirrors React provider).
                 // Deferred by one microtask for the same reason as React: notifyTokenize fires
@@ -2340,6 +2392,12 @@ const OzElements = vue.defineComponent({
                 if (ac.signal.aborted)
                     return;
                 initError.value = err instanceof Error ? err : new Error('OzVault.create() failed.');
+                if (props.onLoadError) {
+                    fireLoadError();
+                }
+                else {
+                    console.error('[OzElements] OzVault.create() failed. Provide an `onLoadError` prop to handle this gracefully.', err);
+                }
             });
         });
         vue.onUnmounted(() => {