@ozura/elements 1.3.1 → 1.4.0

package/dist/vue/index.esm.js

@@ -1114,7 +1114,7 @@ class OzVault {
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
-                    options.onLoadError();
+                    options.onLoadError({ source: 'tokenizer' });
                 }
             }, timeout);
         }
@@ -1247,6 +1247,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.
@@ -1329,17 +1372,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');
@@ -1365,14 +1420,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();
@@ -1381,8 +1429,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 });
@@ -2104,7 +2152,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,
@@ -2271,6 +2319,7 @@ const OzElements = 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 },
     },
@@ -2281,6 +2330,8 @@ const OzElements = defineComponent({
         const mountedCount = ref(0);
         const readyCount = ref(0);
         const tokenizeCount = ref(0);
+        const changeTick = ref(0);
+        const notifyChange = () => { changeTick.value++; };
         const notifyMount = () => { mountedCount.value++; };
         let readyEmitted = false;
         const notifyReady = () => {
@@ -2306,17 +2357,32 @@ const OzElements = defineComponent({
             mountedCount,
             readyCount,
             tokenizeCount,
+            changeTick,
             notifyMount,
             notifyReady,
             notifyUnmount,
             notifyTokenize,
+            notifyChange,
         });
         let createdVault = null;
         let abortController = null;
         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
@@ -2338,6 +2404,12 @@ const OzElements = 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);
+                }
             });
         });
         onUnmounted(() => {
@@ -2359,7 +2431,7 @@ function useOzElements() {
     if (!ctx) {
         throw new Error('[OzVault] useOzElements() must be called inside <OzElements>');
     }
-    const { vault, initError, mountedCount, readyCount, tokenizeCount, notifyTokenize } = ctx;
+    const { vault, initError, mountedCount, readyCount, tokenizeCount, changeTick, notifyTokenize, notifyChange } = ctx;
     const ready = computed(() => vault.value !== null &&
         vault.value.isReady &&
         mountedCount.value > 0 &&
@@ -2368,20 +2440,49 @@ function useOzElements() {
         if (!vault.value) {
             throw new Error('[OzVault] vault is not ready — wait for ready before calling createToken()');
         }
-        const result = await vault.value.createToken(options);
-        notifyTokenize();
-        return result;
+        // Start the call so vault._tokenizing flips synchronously, then bump changeTick
+        // so `isTokenizing` recomputes as `true`; bump again on settle. (vault.isTokenizing
+        // is a plain getter — nothing else would recompute the computed while in flight.)
+        const promise = vault.value.createToken(options);
+        notifyChange();
+        try {
+            const result = await promise;
+            notifyTokenize();
+            return result;
+        }
+        finally {
+            notifyChange();
+        }
     };
     const createBankToken = async (options) => {
         if (!vault.value) {
             throw new Error('[OzVault] vault is not ready — wait for ready before calling createBankToken()');
         }
-        const result = await vault.value.createBankToken(options);
-        notifyTokenize();
-        return result;
+        const promise = vault.value.createBankToken(options);
+        notifyChange();
+        try {
+            const result = await promise;
+            notifyTokenize();
+            return result;
+        }
+        finally {
+            notifyChange();
+        }
+    };
+    const reset = () => {
+        var _a;
+        (_a = vault.value) === null || _a === void 0 ? void 0 : _a.reset();
+        // reset() clears completion state and cancels any in-flight tokenization;
+        // bump changeTick so the derived computeds below recompute.
+        notifyChange();
     };
-    const reset = () => { var _a; (_a = vault.value) === null || _a === void 0 ? void 0 : _a.reset(); };
-    return { createToken, createBankToken, ready, initError, tokenizeCount, reset };
+    // `void changeTick.value` registers a reactive dependency so these recompute when
+    // notifyChange() fires (field change / tokenize start-stop). vault.isComplete and
+    // vault.isTokenizing read non-reactive internal Maps/flags that Vue cannot track.
+    const isComplete = computed(() => { var _a, _b; void changeTick.value; return (_b = (_a = vault.value) === null || _a === void 0 ? void 0 : _a.isComplete) !== null && _b !== void 0 ? _b : false; });
+    const isBankComplete = computed(() => { var _a, _b; void changeTick.value; return (_b = (_a = vault.value) === null || _a === void 0 ? void 0 : _a.isBankComplete) !== null && _b !== void 0 ? _b : false; });
+    const isTokenizing = computed(() => { var _a, _b; void changeTick.value; return (_b = (_a = vault.value) === null || _a === void 0 ? void 0 : _a.isTokenizing) !== null && _b !== void 0 ? _b : false; });
+    return { createToken, createBankToken, ready, initError, tokenizeCount, reset, isComplete, isBankComplete, isTokenizing };
 }
 function createFieldComponent(displayName, mountElement) {
     return defineComponent({
@@ -2397,7 +2498,7 @@ function createFieldComponent(displayName, mountElement) {
             if (!ctx) {
                 throw new Error('[OzVault] useOzElements() must be called inside <OzElements>');
             }
-            const { vault, notifyMount, notifyReady, notifyUnmount } = ctx;
+            const { vault, notifyMount, notifyReady, notifyUnmount, notifyChange } = ctx;
             const containerRef = ref(null);
             let element = null;
             let notifyMountCalled = false;
@@ -2412,7 +2513,7 @@ function createFieldComponent(displayName, mountElement) {
                 notifyMountCalled = true;
                 notifyMount();
                 element.on('ready', () => notifyReady());
-                element.on('change', (e) => emit('change', e));
+                element.on('change', (e) => { emit('change', e); notifyChange(); });
                 element.on('focus', () => emit('focus'));
                 element.on('blur', () => emit('blur'));
                 element.mount(containerRef.value);
@@ -2444,4 +2545,3 @@ const OzBankAccountNumber = createFieldComponent('OzBankAccountNumber', (v, opts
 const OzBankRoutingNumber = createFieldComponent('OzBankRoutingNumber', (v, opts) => v.createBankElement('routingNumber', opts));
 
 export { OzBankAccountNumber, OzBankRoutingNumber, OzCardNumber, OzCvv, OzElements, OzExpiry, useOzElements };
-//# sourceMappingURL=index.esm.js.map

package/dist/vue/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/vue/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/vue/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;
@@ -167,6 +187,9 @@ export declare const OzElements: import("vue").DefineComponent<import("vue").Ext
     appearance: Appearance;
     onSessionRefresh: () => void;
     onReady: () => void;
+    onLoadError: (info?: {
+        source: "tokenizer";
+    }) => void;
     sessionLimit: number | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export interface UseOzElementsReturn {
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "PCI-compliant card tokenization SDK for the Ozura Vault — collect card data in iframe-isolated fields and tokenize without PCI scope",
   "main": "dist/oz-elements.umd.js",
   "module": "dist/oz-elements.esm.js",