@ozura/elements 1.0.2 → 1.1.0-next.22

package/dist/react/index.esm.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { createContext, useContext, useRef, useEffect, useState, useCallback, useMemo } from 'react';
+import { createContext, useContext, useRef, useCallback, useState, useMemo, useEffect } from 'react';
 
 const THEME_DEFAULT = {
     base: {
@@ -355,7 +355,7 @@ class OzElement {
      * (useful when integrating with React refs).
      */
     mount(target) {
-        var _a;
+        var _a, _b;
         if (this._destroyed)
             throw new OzError('Cannot mount a destroyed element.');
         if (this.iframe)
@@ -372,7 +372,13 @@ class OzElement {
         iframe.setAttribute('scrolling', 'no');
         iframe.setAttribute('allowtransparency', 'true');
         iframe.style.cssText = 'border:none;width:100%;height:46px;display:block;overflow:hidden;';
-        iframe.title = `Secure ${this.elementType} input`;
+        iframe.title = `Secure ${(_a = {
+            cardNumber: 'card number',
+            expirationDate: 'expiration date',
+            cvv: 'CVV',
+            accountNumber: 'account number',
+            routingNumber: 'routing number',
+        }[this.elementType]) !== null && _a !== void 0 ? _a : this.elementType} input`;
         // Note: the `sandbox` attribute is intentionally NOT set. Field values are
         // delivered to the tokenizer iframe via a MessageChannel port (transferred
         // in OZ_BEGIN_COLLECT), so no window.parent named-frame lookup is needed.
@@ -386,7 +392,7 @@ class OzElement {
         container.appendChild(iframe);
         this.iframe = iframe;
         this._frameWindow = iframe.contentWindow;
-        const timeout = (_a = this.options.loadTimeoutMs) !== null && _a !== void 0 ? _a : 10000;
+        const timeout = (_b = this.options.loadTimeoutMs) !== null && _b !== void 0 ? _b : 10000;
         this._loadTimer = setTimeout(() => {
             if (!this._ready && !this._destroyed) {
                 this.emit('loaderror', { elementType: this.elementType, error: `${this.elementType} iframe failed to load within ${timeout}ms` });
@@ -819,13 +825,105 @@ function validateBilling(billing) {
     return { valid: errors.length === 0, errors, normalized };
 }
 
+/**
+ * Shared postMessage protocol constants.
+ *
+ * PROTOCOL_VERSION must be incremented any time a breaking change is made to
+ * the postMessage message shape (new required fields, renamed types, removed
+ * fields, changed semantics). The SDK reads this value from OZ_FRAME_READY
+ * messages and warns when the frame and SDK are out of sync.
+ *
+ * Non-breaking additions (new optional fields, new message types that old
+ * frames can safely ignore) do NOT require a version bump.
+ */
+const PROTOCOL_VERSION = 1;
+
+/**
+ * Creates a `getSessionKey` callback for `OzVault.create()` and `<OzElements>`.
+ *
+ * This is the recommended way to wire the SDK to your backend session endpoint.
+ * If you don't need custom headers or auth logic, pass `sessionUrl` directly to
+ * `OzVault.create()` or `<OzElements>` — it calls this helper internally.
+ *
+ * The callback POSTs `{ sessionId }` to `url` and reads `sessionKey` (or the
+ * legacy `waxKey`) from the JSON response, so it is compatible with both the
+ * new `createSessionMiddleware` and the old `createMintWaxMiddleware` backends.
+ *
+ * Each call enforces a **10-second timeout**. On pure network failures
+ * (offline, DNS, connection refused) the request is retried **once after 750ms**.
+ * HTTP 4xx/5xx errors are never retried — they indicate misconfiguration.
+ *
+ * @param url - Absolute or relative URL of your session endpoint, e.g. `'/api/oz-session'`.
+ *
+ * @example
+ * // Simplest — just pass sessionUrl, no need to call this directly
+ * const vault = await OzVault.create({ pubKey: 'pk_live_...', sessionUrl: '/api/oz-session' });
+ *
+ * @example
+ * // Manual — use when you need custom headers
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_live_...',
+ *   getSessionKey: createSessionFetcher('/api/oz-session'),
+ * });
+ */
+function createSessionFetcher(url) {
+    const TIMEOUT_MS = 10000;
+    // Each attempt gets its own AbortController so a timeout on attempt 1 does
+    // not bleed into the retry.
+    const attemptFetch = (sessionId) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        return fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId }),
+            signal: controller.signal,
+        }).finally(() => clearTimeout(timer));
+    };
+    return async (sessionId) => {
+        let res;
+        try {
+            res = await attemptFetch(sessionId);
+        }
+        catch (firstErr) {
+            // Timeout/abort — don't retry, we already waited the full duration.
+            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
+                throw new OzError(`Session endpoint timed out after ${TIMEOUT_MS / 1000}s (${url})`, undefined, 'timeout');
+            }
+            // Pure network error — retry once after a short pause.
+            await new Promise(resolve => setTimeout(resolve, 750));
+            try {
+                res = await attemptFetch(sessionId);
+            }
+            catch (retryErr) {
+                const msg = retryErr instanceof Error ? retryErr.message : 'Network error';
+                throw new OzError(`Could not reach session endpoint (${url}): ${msg}`, undefined, 'network');
+            }
+        }
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            throw new OzError(typeof data.error === 'string' && data.error
+                ? data.error
+                : `Session endpoint returned HTTP ${res.status}`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+        }
+        // Accept both new `sessionKey` and legacy `waxKey` for backward compatibility
+        // with backends that haven't migrated to createSessionMiddleware yet.
+        const key = (typeof data.sessionKey === 'string' ? data.sessionKey : '') ||
+            (typeof data.waxKey === 'string' ? data.waxKey : '');
+        if (!key.trim()) {
+            throw new OzError('Session endpoint response is missing sessionKey. Check your /api/oz-session implementation.', undefined, 'validation');
+        }
+        return key;
+    };
+}
+
 function isCardMetadata(v) {
     return !!v && typeof v === 'object' && typeof v.last4 === 'string';
 }
 function isBankAccountMetadata(v) {
     return !!v && typeof v === 'object' && typeof v.last4 === 'string';
 }
-const DEFAULT_FRAME_BASE_URL = "https://elements.ozura.com";
+const DEFAULT_FRAME_BASE_URL = "https://lively-hill-097170c0f.4.azurestaticapps.net";
 /**
  * The main entry point for OzElements. Creates and manages iframe-based
  * card input elements that keep raw card data isolated from the merchant page.
@@ -858,7 +956,7 @@ class OzVault {
      * @internal
      */
     constructor(options, waxKey, tokenizationSessionId) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e, _f;
         this.elements = new Map();
         this.elementsByType = new Map();
         this.bankElementsByType = new Map();
@@ -871,6 +969,9 @@ class OzVault {
         this.tokenizerReady = false;
         this._tokenizing = null;
         this._destroyed = false;
+        // Incremented every time reset() cancels an active tokenization so that
+        // any in-flight wax-key refresh retry can detect it was superseded.
+        this._resetCount = 0;
         // Tracks successful tokenizations against the per-key call budget so the SDK
         // can proactively refresh the wax key after it has been consumed rather than
         // waiting for the next createToken() call to fail.
@@ -889,14 +990,16 @@ class OzVault {
         this.fonts = (_a = options.fonts) !== null && _a !== void 0 ? _a : [];
         this.resolvedAppearance = resolveAppearance(options.appearance);
         this.vaultId = `vault-${uuid()}`;
-        this._maxTokenizeCalls = (_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3;
+        // sessionLimit takes precedence over legacy maxTokenizeCalls
+        this._maxTokenizeCalls = (_c = (_b = options.sessionLimit) !== null && _b !== void 0 ? _b : options.maxTokenizeCalls) !== null && _c !== void 0 ? _c : 3;
+        this._debug = (_d = options.debug) !== null && _d !== void 0 ? _d : false;
         this.boundHandleMessage = this.handleMessage.bind(this);
         window.addEventListener('message', this.boundHandleMessage);
         this.boundHandleVisibility = this.handleVisibilityChange.bind(this);
         document.addEventListener('visibilitychange', this.boundHandleVisibility);
         this.mountTokenizerFrame();
         if (options.onLoadError) {
-            const timeout = (_c = options.loadTimeoutMs) !== null && _c !== void 0 ? _c : 10000;
+            const timeout = (_e = options.loadTimeoutMs) !== null && _e !== void 0 ? _e : 10000;
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
@@ -904,54 +1007,68 @@ class OzVault {
                 }
             }, timeout);
         }
-        this._onWaxRefresh = options.onWaxRefresh;
+        // onSessionRefresh takes precedence over legacy onWaxRefresh
+        this._onWaxRefresh = (_f = options.onSessionRefresh) !== null && _f !== void 0 ? _f : options.onWaxRefresh;
         this._onReady = options.onReady;
+        this.log('vault created', { vaultId: this.vaultId, frameBaseUrl: this.frameBaseUrl, maxTokenizeCalls: this._maxTokenizeCalls });
     }
     /**
      * Creates and returns a ready `OzVault` instance.
      *
      * Internally this:
-     * 1. Generates a `tokenizationSessionId` (UUID).
+     * 1. Generates a session UUID.
      * 2. Starts loading the hidden tokenizer iframe immediately.
-     * 3. Calls `options.fetchWaxKey(tokenizationSessionId)` concurrently — your
-     *    backend mints a session-bound wax key from the vault and returns it.
-     * 4. Resolves with the vault instance once the wax key is stored. The iframe
+     * 3. Fetches a session key from your backend concurrently — either via
+     *    `sessionUrl` (simplest), `getSessionKey` (custom headers/auth), or the
+     *    deprecated `fetchWaxKey` callback.
+     * 4. Resolves with the vault instance once the session key is stored. The iframe
      *    has been loading the whole time, so `isReady` may already be true or
      *    will fire shortly after.
      *
      * The returned vault is ready to create elements immediately. `createToken()`
      * additionally requires `vault.isReady` (tokenizer iframe loaded).
      *
-     * @throws {OzError} if `fetchWaxKey` throws, returns a non-string value, or returns an empty/whitespace-only string.
+     * @throws {OzError} if the session fetch fails, times out, or returns an empty string.
      */
     static async create(options, signal) {
         if (!options.pubKey || !options.pubKey.trim()) {
             throw new OzError('pubKey is required in options. Obtain your public key from the Ozura admin.');
         }
-        if (typeof options.fetchWaxKey !== 'function') {
-            throw new OzError('fetchWaxKey must be a function. See OzVault.create() docs for the expected signature.');
+        // Normalize the session callback. Priority: sessionUrl > getSessionKey > fetchWaxKey (deprecated).
+        // This allows merchants to use the clean new API without touching legacy code.
+        let resolvedFetchKey;
+        if (options.sessionUrl) {
+            resolvedFetchKey = createSessionFetcher(options.sessionUrl);
+        }
+        else if (typeof options.getSessionKey === 'function') {
+            resolvedFetchKey = options.getSessionKey;
+        }
+        else if (typeof options.fetchWaxKey === 'function') {
+            resolvedFetchKey = options.fetchWaxKey;
+        }
+        else {
+            throw new OzError('A session URL or callback is required. Pass sessionUrl, getSessionKey, or fetchWaxKey to OzVault.create().');
         }
         const tokenizationSessionId = uuid();
         // Construct the vault immediately — this mounts the tokenizer iframe so it
-        // starts loading while fetchWaxKey is in flight. The waxKey field starts
-        // empty and is set below before create() returns.
+        // starts loading while the session fetch is in flight.
         const vault = new OzVault(options, '', tokenizationSessionId);
         // If the caller provides an AbortSignal (e.g. React useEffect cleanup),
         // destroy the vault immediately on abort so the tokenizer iframe and message
-        // listener are removed synchronously rather than waiting for fetchWaxKey to
-        // settle. This eliminates the brief double-iframe window in React StrictMode.
+        // listener are removed synchronously rather than waiting for the session fetch
+        // to settle. This eliminates the brief double-iframe window in React StrictMode.
         const onAbort = () => vault.destroy();
         signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onAbort, { once: true });
         let waxKey;
         try {
-            waxKey = await options.fetchWaxKey(tokenizationSessionId);
+            waxKey = await resolvedFetchKey(tokenizationSessionId);
         }
         catch (err) {
             signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
             vault.destroy();
             if (signal === null || signal === void 0 ? void 0 : signal.aborted)
                 throw new OzError('OzVault.create() was cancelled.');
-            // Preserve errorCode/retryable from OzError (e.g. timeout/network from createFetchWaxKey)
+            // Preserve errorCode/retryable from OzError (e.g. timeout/network from createSessionFetcher)
             // so callers can distinguish transient failures from config errors.
             const originalCode = err instanceof OzError ? err.errorCode : undefined;
             const msg = err instanceof Error ? err.message : 'Unknown error';
@@ -968,13 +1085,14 @@ class OzVault {
         }
         // Static methods can access private fields of instances of the same class.
         vault.waxKey = waxKey;
-        vault._storedFetchWaxKey = options.fetchWaxKey;
+        vault._storedFetchWaxKey = resolvedFetchKey;
         // If the tokenizer iframe fired OZ_FRAME_READY before fetchWaxKey resolved,
         // the OZ_INIT sent at that point had an empty waxKey. Send a follow-up now
         // so the tokenizer has the key stored before any createToken() call.
         if (vault.tokenizerReady) {
             vault.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey });
         }
+        vault.log('wax key received — vault ready');
         return vault;
     }
     /**
@@ -1116,8 +1234,13 @@ class OzVault {
         const readyBankElements = [accountEl, routingEl];
         this._tokenizing = 'bank';
         const requestId = `req-${uuid()}`;
+        this.log('createBankToken() called');
         return new Promise((resolve, reject) => {
-            const cleanup = () => { this._tokenizing = null; };
+            const resetCountAtStart = this._resetCount;
+            const cleanup = () => {
+                if (this._resetCount === resetCountAtStart)
+                    this._tokenizing = null;
+            };
             this.bankTokenizeResolvers.set(requestId, {
                 resolve: (v) => { cleanup(); resolve(v); },
                 reject: (e) => { cleanup(); reject(e); },
@@ -1128,6 +1251,7 @@ class OzVault {
             });
             try {
                 const bankChannels = readyBankElements.map(() => new MessageChannel());
+                const bankTokenizeStartMs = Date.now();
                 this.sendToTokenizer({
                     type: 'OZ_BANK_TOKENIZE',
                     requestId,
@@ -1138,6 +1262,7 @@ class OzVault {
                     lastName: options.lastName.trim(),
                     fieldCount: readyBankElements.length,
                 }, bankChannels.map(ch => ch.port1));
+                this.log('OZ_BANK_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyBankElements.length });
                 readyBankElements.forEach((el, i) => el.beginCollect(requestId, bankChannels[i].port2));
                 const bankTimeoutId = setTimeout(() => {
                     if (this.bankTokenizeResolvers.has(requestId)) {
@@ -1148,8 +1273,10 @@ class OzVault {
                     }
                 }, 30000);
                 const bankPendingEntry = this.bankTokenizeResolvers.get(requestId);
-                if (bankPendingEntry)
+                if (bankPendingEntry) {
                     bankPendingEntry.timeoutId = bankTimeoutId;
+                    bankPendingEntry.tokenizeStartMs = bankTokenizeStartMs;
+                }
             }
             catch (err) {
                 this.bankTokenizeResolvers.delete(requestId);
@@ -1220,8 +1347,15 @@ class OzVault {
         }
         this._tokenizing = 'card';
         const requestId = `req-${uuid()}`;
+        this.log('createToken() called');
         return new Promise((resolve, reject) => {
-            const cleanup = () => { this._tokenizing = null; };
+            // Capture the reset generation so cleanup() only zeros _tokenizing when it
+            // still belongs to this invocation — not a newer one that started after a reset.
+            const resetCountAtStart = this._resetCount;
+            const cleanup = () => {
+                if (this._resetCount === resetCountAtStart)
+                    this._tokenizing = null;
+            };
             this.tokenizeResolvers.set(requestId, {
                 resolve: (v) => { cleanup(); resolve(v); },
                 reject: (e) => { cleanup(); reject(e); },
@@ -1234,6 +1368,7 @@ class OzVault {
             try {
                 // Tell tokenizer frame to expect N field values, then tokenize
                 const cardChannels = readyElements.map(() => new MessageChannel());
+                const tokenizeStartMs = Date.now();
                 this.sendToTokenizer({
                     type: 'OZ_TOKENIZE',
                     requestId,
@@ -1244,6 +1379,11 @@ class OzVault {
                     lastName,
                     fieldCount: readyElements.length,
                 }, cardChannels.map(ch => ch.port1));
+                this.log('OZ_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyElements.length });
+                // Store start time for elapsed-ms logging on result
+                const cardEntry = this.tokenizeResolvers.get(requestId);
+                if (cardEntry)
+                    cardEntry.tokenizeStartMs = tokenizeStartMs;
                 // Tell each ready element frame to send its raw value to the tokenizer
                 readyElements.forEach((el, i) => el.beginCollect(requestId, cardChannels[i].port2));
                 const cardTimeoutId = setTimeout(() => {
@@ -1265,6 +1405,63 @@ class OzVault {
             }
         });
     }
+    /**
+     * Clears all mounted element fields without tearing down the vault.
+     *
+     * Call this after a failed payment (e.g. card declined) to let the customer
+     * re-enter their details. The vault instance, tokenizer iframe, wax key, and
+     * tokenization budget counter are all preserved — no network calls are made.
+     *
+     * **Wax key session model:** by design, one wax key covers the full checkout
+     * session. The default `max_tokenize_calls: 3` supports two declined attempts
+     * and one final attempt on the same key. Do not call `vault.destroy()` and
+     * recreate the vault between declines — that unnecessarily re-mints the key
+     * and discards the remaining budget.
+     *
+     * @example
+     * try {
+     *   const { token, cvcSession } = await vault.createToken({ billing });
+     *   await chargeCard(token, cvcSession);
+     * } catch (err) {
+     *   vault.reset();       // clear fields; let customer re-enter
+     *   showError(err.message);
+     * }
+     */
+    reset() {
+        if (this._destroyed)
+            return;
+        const cancelling = Boolean(this._tokenizing);
+        this.log('reset() called', { tokenizing: this._tokenizing, cancelling });
+        if (this._tokenizing) {
+            this._tokenizing = null;
+            this._resetCount++;
+            this.tokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+                if (timeoutId != null)
+                    clearTimeout(timeoutId);
+                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                reject(new OzError('Vault was reset while tokenization was in progress.'));
+            });
+            this.tokenizeResolvers.clear();
+            this.bankTokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+                if (timeoutId != null)
+                    clearTimeout(timeoutId);
+                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                reject(new OzError('Vault was reset while tokenization was in progress.'));
+            });
+            this.bankTokenizeResolvers.clear();
+        }
+        // Clear field values in all mounted element iframes
+        this.elementsByType.forEach(el => el.clear());
+        this.bankElementsByType.forEach(el => el.clear());
+        // Reset per-element completion state so auto-advance starts fresh on re-entry
+        for (const frameId of this.completionState.keys()) {
+            this.completionState.set(frameId, false);
+        }
+        // NOTE: _tokenizeSuccessCount is intentionally NOT reset.
+        // It reflects real server-side wax key budget consumption. Zeroing it
+        // would desync the proactive refresh logic from the vault's state and
+        // risk triggering a mid-session re-mint on what should be a clean retry.
+    }
     /**
      * Tears down the vault: removes all element iframes, the tokenizer iframe,
      * and the global message listener. Call this when the checkout component
@@ -1275,6 +1472,7 @@ class OzVault {
         if (this._destroyed)
             return;
         this._destroyed = true;
+        this.log('destroy() called');
         window.removeEventListener('message', this.boundHandleMessage);
         document.removeEventListener('visibilitychange', this.boundHandleVisibility);
         if (this._pendingMount) {
@@ -1329,13 +1527,17 @@ class OzVault {
         const REFRESH_THRESHOLD_MS = 20 * 60 * 1000; // 20 minutes
         if (document.hidden) {
             this._hiddenAt = Date.now();
+            this.log('tab hidden');
         }
         else {
-            if (this._hiddenAt !== null &&
-                Date.now() - this._hiddenAt >= REFRESH_THRESHOLD_MS &&
-                this._storedFetchWaxKey &&
+            const hiddenMs = this._hiddenAt !== null ? Date.now() - this._hiddenAt : 0;
+            const willRefresh = (this._hiddenAt !== null &&
+                hiddenMs >= REFRESH_THRESHOLD_MS &&
+                Boolean(this._storedFetchWaxKey) &&
                 !this._tokenizing &&
-                !this._waxRefreshing) {
+                !this._waxRefreshing);
+            this.log('tab visible', { hiddenMs, willRefresh });
+            if (willRefresh) {
                 this.refreshWaxKey().catch((err) => {
                     // Proactive refresh failure is non-fatal — the reactive path on the
                     // next createToken() call will handle it, including the auth retry.
@@ -1345,6 +1547,56 @@ class OzVault {
             this._hiddenAt = null;
         }
     }
+    // ─── Debug ───────────────────────────────────────────────────────────────
+    /**
+     * Emits a `[OzVault]`-prefixed entry to `console.log`. No-op when `debug` is
+     * not set. Never called with sensitive values — callers use presence flags only.
+     */
+    log(message, data) {
+        if (!this._debug)
+            return;
+        if (data !== undefined) {
+            console.log(`[OzVault] ${message}`, data);
+        }
+        else {
+            console.log(`[OzVault] ${message}`);
+        }
+    }
+    /**
+     * Returns a plain-object snapshot of the vault's current internal state.
+     * Safe to attach to bug reports — no wax keys, tokens, or billing data included.
+     *
+     * Available on all vault instances regardless of whether `debug` was enabled.
+     *
+     * @example
+     * console.log(vault.debugState());
+     * // {
+     * //   vaultId: 'vault-abc123',
+     * //   isReady: true,
+     * //   tokenizing: null,
+     * //   destroyed: false,
+     * //   waxKeyPresent: true,
+     * //   elements: ['cardNumber', 'expirationDate', 'cvv'],
+     * //   ...
+     * // }
+     */
+    debugState() {
+        return {
+            vaultId: this.vaultId,
+            isReady: this.tokenizerReady,
+            tokenizing: this._tokenizing,
+            destroyed: this._destroyed,
+            waxKeyPresent: Boolean(this.waxKey),
+            tokenizeSuccessCount: this._tokenizeSuccessCount,
+            maxTokenizeCalls: this._maxTokenizeCalls,
+            resetCount: this._resetCount,
+            elements: [...this.elementsByType.keys()],
+            bankElements: [...this.bankElementsByType.keys()],
+            completionState: Object.fromEntries([...this.completionState.entries()].map(([id, v]) => [id.slice(0, 8), v])),
+            pendingTokenizations: this.tokenizeResolvers.size,
+            pendingBankTokenizations: this.bankTokenizeResolvers.size,
+        };
+    }
     mountTokenizerFrame() {
         const mount = () => {
             this._pendingMount = null;
@@ -1356,6 +1608,7 @@ class OzVault {
             iframe.src = `${this.frameBaseUrl}/frame/tokenizer-frame.html#vaultId=${encodeURIComponent(this.vaultId)}${parentOrigin ? `&parentOrigin=${encodeURIComponent(parentOrigin)}` : ''}`;
             document.body.appendChild(iframe);
             this.tokenizerFrame = iframe;
+            this.log('mounting tokenizer iframe');
         };
         if (document.readyState === 'loading') {
             this._pendingMount = mount;
@@ -1391,6 +1644,12 @@ class OzVault {
                 // the previous session and justCompleted never fires, breaking auto-advance.
                 if (msg.type === 'OZ_FRAME_READY') {
                     this.completionState.set(frameId, false);
+                    if (msg.__ozVersion !== PROTOCOL_VERSION) {
+                        console.warn(`[OzVault] Protocol version mismatch on element frame "${frameId}" — ` +
+                            `SDK expects v${PROTOCOL_VERSION}, frame reported v${typeof msg.__ozVersion === 'number' ? msg.__ozVersion : '(none)'}. ` +
+                            'Deploy the matching frame assets to elements.ozura.com and purge the Azure CDN cache.');
+                    }
+                    this.log('element iframe ready', { type: el.type, frameIdPrefix: frameId.slice(0, 8) });
                 }
                 // Intercept OZ_CHANGE before forwarding — handle auto-advance and CVV sync
                 if (msg.type === 'OZ_CHANGE') {
@@ -1414,6 +1673,7 @@ class OzVault {
         // Require valid too — avoids advancing at 13 digits for unknown-brand cards
         // where isComplete() fires before the user has finished typing.
         const justCompleted = complete && valid && !wasComplete;
+        this.log('field changed', { type: el.type, complete, valid, justCompleted });
         // Sync CVV length when card brand changes
         if (el.type === 'cardNumber') {
             const brand = msg.cardBrand;
@@ -1425,17 +1685,25 @@ class OzVault {
         // Auto-advance focus on completion
         if (justCompleted) {
             if (el.type === 'cardNumber') {
+                this.log('auto-advance', { from: 'cardNumber', to: 'expirationDate' });
                 (_b = this.elementsByType.get('expirationDate')) === null || _b === void 0 ? void 0 : _b.focus();
             }
             else if (el.type === 'expirationDate') {
+                this.log('auto-advance', { from: 'expirationDate', to: 'cvv' });
                 (_c = this.elementsByType.get('cvv')) === null || _c === void 0 ? void 0 : _c.focus();
             }
         }
     }
     handleTokenizerMessage(msg) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         switch (msg.type) {
             case 'OZ_FRAME_READY':
+                if (msg.__ozVersion !== PROTOCOL_VERSION) {
+                    console.warn(`[OzVault] Protocol version mismatch — SDK expects v${PROTOCOL_VERSION}, ` +
+                        `tokenizer frame reported v${typeof msg.__ozVersion === 'number' ? msg.__ozVersion : '(none)'}. ` +
+                        'This usually means the deployed frame files are stale. ' +
+                        'Deploy the matching frame assets to elements.ozura.com and purge the Azure CDN cache.');
+                }
                 this.tokenizerReady = true;
                 if (this.loadErrorTimeoutId != null) {
                     clearTimeout(this.loadErrorTimeoutId);
@@ -1447,6 +1715,7 @@ class OzVault {
                 // sent again from create() once the key is available.
                 this.sendToTokenizer(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})));
                 (_c = this._onReady) === null || _c === void 0 ? void 0 : _c.call(this);
+                this.log('tokenizer iframe ready', { protocolVersion: (_d = msg.__ozVersion) !== null && _d !== void 0 ? _d : null });
                 break;
             case 'OZ_TOKEN_RESULT': {
                 if (typeof msg.requestId !== 'string' || !msg.requestId) {
@@ -1471,11 +1740,18 @@ class OzVault {
                     }
                     pending.resolve(Object.assign(Object.assign({ token,
                         cvcSession }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
+                    this.log('token received', {
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        cvcSessionPresent: true,
+                        cardMetadataPresent: Boolean(card),
+                    });
                     // Increment the per-key success counter and proactively refresh once
                     // the budget is exhausted so the next createToken() call uses a fresh
                     // key without waiting for a vault rejection.
                     this._tokenizeSuccessCount++;
                     if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.log('proactive wax key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
                         this.refreshWaxKey().catch((err) => {
                             console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
                         });
@@ -1495,14 +1771,25 @@ class OzVault {
                     this.tokenizeResolvers.delete(msg.requestId);
                     if (pending.timeoutId != null)
                         clearTimeout(pending.timeoutId);
+                    const willRefresh = this.isRefreshableAuthError(errorCode, raw) && !pending.retried && Boolean(this._storedFetchWaxKey);
+                    this.log('token error', { errorCode, willRefresh });
                     // Auto-refresh: if the wax key expired or was consumed and we haven't
                     // already retried for this request, transparently re-mint and retry.
-                    if (this.isRefreshableAuthError(errorCode, raw) && !pending.retried && this._storedFetchWaxKey) {
+                    if (willRefresh) {
+                        const resetCountAtRetry = this._resetCount;
                         this.refreshWaxKey().then(() => {
                             if (this._destroyed) {
                                 pending.reject(new OzError('Vault destroyed during wax key refresh.'));
                                 return;
                             }
+                            if (this._resetCount !== resetCountAtRetry) {
+                                // reset() was called while the wax key was refreshing — the fields
+                                // have been cleared and _tokenizing was zeroed. Reject the original
+                                // promise so it doesn't stay pending, and bail out without starting
+                                // a new retry (which would tokenize against empty fields).
+                                pending.reject(new OzError('Vault was reset while tokenization was in progress.'));
+                                return;
+                            }
                             const newRequestId = `req-${uuid()}`;
                             // _tokenizing is still 'card' (cleanup() hasn't been called yet)
                             this.tokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, pending), { retried: true }));
@@ -1549,11 +1836,16 @@ class OzVault {
                     if (bankPending.timeoutId != null)
                         clearTimeout(bankPending.timeoutId);
                     if (this.isRefreshableAuthError(errorCode, raw) && !bankPending.retried && this._storedFetchWaxKey) {
+                        const resetCountAtRetry = this._resetCount;
                         this.refreshWaxKey().then(() => {
                             if (this._destroyed) {
                                 bankPending.reject(new OzError('Vault destroyed during wax key refresh.'));
                                 return;
                             }
+                            if (this._resetCount !== resetCountAtRetry) {
+                                bankPending.reject(new OzError('Vault was reset while tokenization was in progress.'));
+                                return;
+                            }
                             const newRequestId = `req-${uuid()}`;
                             this.bankTokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, bankPending), { retried: true }));
                             try {
@@ -1611,9 +1903,15 @@ class OzVault {
                     }
                     const bank = isBankAccountMetadata(msg.bank) ? msg.bank : undefined;
                     pending.resolve(Object.assign({ token }, (bank ? { bank } : {})));
+                    this.log('bank token received', {
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        bankMetadataPresent: Boolean(bank),
+                    });
                     // Same proactive refresh logic as card tokenization.
                     this._tokenizeSuccessCount++;
                     if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.log('proactive wax key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
                         this.refreshWaxKey().catch((err) => {
                             console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
                         });
@@ -1669,6 +1967,7 @@ class OzVault {
         }
         const newSessionId = uuid();
         (_a = this._onWaxRefresh) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.log('wax key refresh started');
         this._waxRefreshing = this._storedFetchWaxKey(newSessionId)
             .then(newWaxKey => {
             if (typeof newWaxKey !== 'string' || !newWaxKey.trim()) {
@@ -1682,6 +1981,11 @@ class OzVault {
             if (!this._destroyed && this.tokenizerReady) {
                 this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey: newWaxKey });
             }
+            this.log('wax key refresh succeeded');
+        })
+            .catch((err) => {
+            this.log('wax key refresh failed', { error: err instanceof Error ? err.message : String(err) });
+            throw err;
         })
             .finally(() => {
             this._waxRefreshing = null;
@@ -1695,84 +1999,6 @@ class OzVault {
     }
 }
 
-/**
- * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
- *
- * Calls your backend mint endpoint with `{ sessionId }` and returns the wax key string.
- * Throws on non-OK responses or a missing `waxKey` field so the vault can surface the
- * error through its normal error path.
- *
- * Each call enforces a 10-second per-attempt timeout. On a pure network-level
- * failure (connection refused, DNS failure, etc.) the call is retried once after
- * 750ms before throwing. HTTP errors (4xx/5xx) are never retried — they indicate
- * an endpoint misconfiguration or an invalid key, not a transient failure.
- *
- * The mint endpoint is typically the one-line `createMintWaxHandler` / `createMintWaxMiddleware`
- * from `@ozura/elements/server`.
- *
- * @param mintUrl - Absolute or relative URL of your wax-key mint endpoint, e.g. `'/api/mint-wax'`.
- *
- * @example
- * // Vanilla JS
- * const vault = await OzVault.create({
- *   pubKey: 'pk_live_...',
- *   fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
- * });
- *
- * @example
- * // React
- * <OzElements pubKey="pk_live_..." fetchWaxKey={createFetchWaxKey('/api/mint-wax')}>
- */
-function createFetchWaxKey(mintUrl) {
-    const TIMEOUT_MS = 10000;
-    // Each attempt gets its own AbortController so a timeout on attempt 1 does
-    // not bleed into the retry. Uses AbortController + setTimeout instead of
-    // AbortSignal.timeout() to support environments without that API.
-    const attemptFetch = (sessionId) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-        return fetch(mintUrl, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId }),
-            signal: controller.signal,
-        }).finally(() => clearTimeout(timer));
-    };
-    return async (sessionId) => {
-        let res;
-        try {
-            res = await attemptFetch(sessionId);
-        }
-        catch (firstErr) {
-            // Abort/timeout should not be retried — the server received nothing or
-            // we already waited the full timeout duration.
-            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
-                throw new OzError(`Wax key mint timed out after ${TIMEOUT_MS / 1000}s (${mintUrl})`, undefined, 'timeout');
-            }
-            // Pure network error (offline, DNS, connection refused) — retry once
-            // after a short pause in case of a transient blip.
-            await new Promise(resolve => setTimeout(resolve, 750));
-            try {
-                res = await attemptFetch(sessionId);
-            }
-            catch (retryErr) {
-                const msg = retryErr instanceof Error ? retryErr.message : 'Network error';
-                throw new OzError(`Could not reach wax key mint endpoint (${mintUrl}): ${msg}`, undefined, 'network');
-            }
-        }
-        const data = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            throw new OzError(typeof data.error === 'string' && data.error
-                ? data.error
-                : `Wax key mint failed (HTTP ${res.status})`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
-        }
-        if (typeof data.waxKey !== 'string' || !data.waxKey.trim()) {
-            throw new OzError('Mint endpoint response is missing waxKey. Check your /api/mint-wax implementation.', undefined, 'validation');
-        }
-        return data.waxKey;
-    };
-}
-
 const OzContext = createContext({
     vault: null,
     initError: null,
@@ -1789,7 +2015,7 @@ const OzContext = createContext({
  * All `<OzCardNumber />`, `<OzExpiry />`, and `<OzCvv />` children must be
  * rendered inside this provider.
  */
-function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, onWaxRefresh, onReady, appearance, maxTokenizeCalls, children }) {
+function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, onSessionRefresh, onWaxRefresh, onReady, appearance, sessionLimit, maxTokenizeCalls, debug, children }) {
     const [vault, setVault] = useState(null);
     const [initError, setInitError] = useState(null);
     const [mountedCount, setMountedCount] = useState(0);
@@ -1797,13 +2023,14 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
     const [tokenizeCount, setTokenizeCount] = useState(0);
     const onLoadErrorRef = useRef(onLoadError);
     onLoadErrorRef.current = onLoadError;
-    const onWaxRefreshRef = useRef(onWaxRefresh);
-    onWaxRefreshRef.current = onWaxRefresh;
+    const onWaxRefreshRef = useRef(onSessionRefresh !== null && onSessionRefresh !== void 0 ? onSessionRefresh : onWaxRefresh);
+    onWaxRefreshRef.current = onSessionRefresh !== null && onSessionRefresh !== void 0 ? onSessionRefresh : onWaxRefresh;
     const onReadyRef = useRef(onReady);
     onReadyRef.current = onReady;
-    // Keep a ref to fetchWaxKey so changes don't trigger vault recreation
-    const fetchWaxKeyRef = useRef(fetchWaxKey);
-    fetchWaxKeyRef.current = fetchWaxKey;
+    // Keep a ref to the session callback so changes don't trigger vault recreation.
+    // Priority mirrors OzVault.create(): sessionUrl > getSessionKey > fetchWaxKey.
+    const getSessionKeyRef = useRef(getSessionKey !== null && getSessionKey !== void 0 ? getSessionKey : fetchWaxKey);
+    getSessionKeyRef.current = getSessionKey !== null && getSessionKey !== void 0 ? getSessionKey : fetchWaxKey;
     const appearanceKey = useMemo(() => appearance ? JSON.stringify(appearance) : '', [appearance]);
     const fontsKey = useMemo(() => fonts ? JSON.stringify(fonts) : '', [fonts]);
     useEffect(() => {
@@ -1830,7 +2057,9 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
         // synchronously rather than waiting for the promise to settle. Without this,
         // two hidden iframes and two window listeners briefly coexist.
         const abortController = new AbortController();
-        OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey, fetchWaxKey: (sessionId) => fetchWaxKeyRef.current(sessionId) }, (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: fireLoadError, loadTimeoutMs } : {})), { 
+        OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey }, (sessionUrl
+            ? { sessionUrl }
+            : { getSessionKey: (sessionId) => getSessionKeyRef.current(sessionId) })), (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: fireLoadError, loadTimeoutMs } : {})), { 
             // Always install onWaxRefresh internally so we can reset tokenizeCount
             // when any wax key refresh occurs (reactive TTL expiry, post-budget
             // proactive, or visibility-change proactive). Without this the React
@@ -1852,11 +2081,12 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
             // the retry tokenization completes (a full fetchWaxKey + tokenize round-
             // trip separates them), so the count correctly resets to 0 then rises to
             // 1 after the retry notifyTokenize fires.
-            onWaxRefresh: () => {
+            onSessionRefresh: () => {
                 var _a;
                 Promise.resolve().then(() => setTokenizeCount(0));
                 (_a = onWaxRefreshRef.current) === null || _a === void 0 ? void 0 : _a.call(onWaxRefreshRef);
-            } }), (onReadyRef.current ? { onReady: () => { var _a; return (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef); } } : {})), (maxTokenizeCalls !== undefined ? { maxTokenizeCalls } : {})), abortController.signal).then(v => {
+            }, onReady: () => { var _a; return (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef); } }), (sessionLimit !== undefined ? { sessionLimit }
+            : maxTokenizeCalls !== undefined ? { maxTokenizeCalls } : {})), (debug ? { debug: true } : {})), abortController.signal).then(v => {
             if (cancelled) {
                 v.destroy();
                 return;
@@ -1889,7 +2119,7 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
             setVault(null);
             setInitError(null);
         };
-    }, [pubKey, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey, maxTokenizeCalls]);
+    }, [pubKey, sessionUrl, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey, sessionLimit, maxTokenizeCalls, debug]);
     const notifyMount = useCallback(() => setMountedCount(n => n + 1), []);
     const notifyReady = useCallback(() => setReadyCount(n => n + 1), []);
     const notifyUnmount = useCallback(() => {
@@ -1922,8 +2152,11 @@ function useOzElements() {
         notifyTokenize();
         return result;
     }, [vault, notifyTokenize]);
+    const reset = useCallback(() => {
+        vault === null || vault === void 0 ? void 0 : vault.reset();
+    }, [vault]);
     const ready = vault !== null && vault.isReady && mountedCount > 0 && readyCount >= mountedCount;
-    return { createToken, createBankToken, ready, initError, tokenizeCount };
+    return { createToken, createBankToken, reset, ready, initError, tokenizeCount };
 }
 const SKELETON_STYLE = {
     height: 46,
@@ -2018,6 +2251,71 @@ const OzCardNumber = (props) => jsx(OzFieldBase, Object.assign({ type: "cardNumb
 const OzExpiry = (props) => jsx(OzFieldBase, Object.assign({ type: "expirationDate", variant: "card" }, props));
 /** Renders a PCI-isolated CVV input inside an Ozura iframe. */
 const OzCvv = (props) => jsx(OzFieldBase, Object.assign({ type: "cvv", variant: "card" }, props));
+// ─── Shared composite-component hook ─────────────────────────────────────────
+/**
+ * Shared plumbing for OzCard and OzBankCard.
+ *
+ * Manages:
+ *  - Callback refs (onChange, onReady, onFocus, onBlur) kept in sync on every render
+ *  - Vault-change detection: resets `readyFieldTypes` and `onReadyFiredRef` when the
+ *    vault instance is replaced (e.g. after fetchWaxKey changes or the provider remounts)
+ *  - Per-field ready tracking: creates one stable handler per named field; fires the
+ *    `onReady` callback once all `fieldNames.length` fields have reported ready
+ *  - Error state
+ *  - Layout helpers: `gapStr`, `renderLabel`
+ *
+ * @internal — not exported; used only by OzCard and OzBankCard.
+ */
+function useCardBase({ vault, fieldNames, onChange, onReady, onFocus, onBlur, gap = 8, labelStyle, labelClassName, }) {
+    const totalFields = fieldNames.length;
+    const readyFieldTypes = useRef(new Set());
+    const onReadyFiredRef = useRef(false);
+    const vaultRef = useRef(vault);
+    const onChangeRef = useRef(onChange);
+    const onReadyRef = useRef(onReady);
+    const onFocusRef = useRef(onFocus);
+    const onBlurRef = useRef(onBlur);
+    useEffect(() => { onChangeRef.current = onChange; }, [onChange]);
+    useEffect(() => { onReadyRef.current = onReady; }, [onReady]);
+    useEffect(() => { onFocusRef.current = onFocus; }, [onFocus]);
+    useEffect(() => { onBlurRef.current = onBlur; }, [onBlur]);
+    useEffect(() => {
+        if (vault !== vaultRef.current) {
+            vaultRef.current = vault;
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
+        }
+        return () => {
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
+        };
+    }, [vault]);
+    // One stable handler per named field — recreated only when total field count changes.
+    // Field names are static (card = 3 fields, bank = 2 fields) so `totalFields` alone
+    // is a sufficient dependency; a JSON dep would create a new map on every render.
+    // CONTRACT: `fieldNames` must be a static literal — callers must not pass a dynamic
+    // array that changes length without also changing field count.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const readyHandlers = useMemo(() => {
+        const handlers = {};
+        for (const name of fieldNames) {
+            handlers[name] = () => {
+                var _a;
+                readyFieldTypes.current.add(name);
+                if (readyFieldTypes.current.size >= totalFields && !onReadyFiredRef.current) {
+                    onReadyFiredRef.current = true;
+                    (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+                }
+            };
+        }
+        return handlers;
+    }, [totalFields]); // totalFields captures fieldNames.length; field names are static
+    const [error, setError] = useState();
+    const gapStr = typeof gap === 'string' ? gap : `${gap}px`;
+    const resolvedLabelStyle = useMemo(() => (labelStyle ? Object.assign(Object.assign({}, DEFAULT_LABEL_STYLE), labelStyle) : DEFAULT_LABEL_STYLE), [labelStyle]);
+    const renderLabel = useCallback((text) => renderFieldLabel(text, labelClassName, resolvedLabelStyle), [labelClassName, resolvedLabelStyle]);
+    return { onChangeRef, onFocusRef, onBlurRef, readyHandlers, error, setError, gapStr, renderLabel };
+}
 const DEFAULT_ERROR_STYLE = {
     color: '#dc2626',
     fontSize: 13,
@@ -2060,62 +2358,22 @@ function mergeStyles(base, override) {
 function OzCard({ style, styles, classNames, labels, labelStyle, labelClassName, layout = 'default', gap = 8, hideErrors = false, errorStyle, errorClassName, renderError, onChange, onReady, onFocus, onBlur, disabled, className, placeholders, }) {
     var _a, _b, _c;
     const { vault } = useContext(OzContext);
+    const { onChangeRef, onFocusRef, onBlurRef, readyHandlers, error, setError, gapStr, renderLabel, } = useCardBase({
+        vault,
+        fieldNames: ['cardNumber', 'expiry', 'cvv'],
+        onChange,
+        onReady,
+        onFocus,
+        onBlur,
+        gap,
+        labelStyle,
+        labelClassName,
+    });
     const fieldState = useRef({
         cardNumber: null,
         expiry: null,
         cvv: null,
     });
-    const readyFieldTypes = useRef(new Set());
-    const onReadyFiredRef = useRef(false);
-    const vaultRef = useRef(vault);
-    const onChangeRef = useRef(onChange);
-    const onReadyRef = useRef(onReady);
-    const onFocusRef = useRef(onFocus);
-    const onBlurRef = useRef(onBlur);
-    useEffect(() => { onChangeRef.current = onChange; }, [onChange]);
-    useEffect(() => { onReadyRef.current = onReady; }, [onReady]);
-    useEffect(() => { onFocusRef.current = onFocus; }, [onFocus]);
-    useEffect(() => { onBlurRef.current = onBlur; }, [onBlur]);
-    // When the vault is recreated (e.g. appearance/fonts props change on OzElements),
-    // context readyCount is reset but this ref is not. Reset so onReady fires once when all 3 are ready.
-    // The cleanup resets readyFieldTypes when the component unmounts (covers React StrictMode double-invoke
-    // and SPA scenarios where the parent re-mounts this component).
-    useEffect(() => {
-        if (vault !== vaultRef.current) {
-            vaultRef.current = vault;
-            readyFieldTypes.current = new Set();
-            onReadyFiredRef.current = false;
-        }
-        return () => {
-            readyFieldTypes.current = new Set();
-            onReadyFiredRef.current = false;
-        };
-    }, [vault]);
-    const [error, setError] = useState();
-    const handleCardNumberReady = useCallback(() => {
-        var _a;
-        readyFieldTypes.current.add('cardNumber');
-        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
-            onReadyFiredRef.current = true;
-            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
-        }
-    }, []);
-    const handleExpiryReady = useCallback(() => {
-        var _a;
-        readyFieldTypes.current.add('expiry');
-        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
-            onReadyFiredRef.current = true;
-            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
-        }
-    }, []);
-    const handleCvvReady = useCallback(() => {
-        var _a;
-        readyFieldTypes.current.add('cvv');
-        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
-            onReadyFiredRef.current = true;
-            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
-        }
-    }, []);
     const emitChange = useCallback(() => {
         var _a;
         const { cardNumber, expiry, cvv } = fieldState.current;
@@ -2130,20 +2388,16 @@ function OzCard({ style, styles, classNames, labels, labelStyle, labelClassName,
             error: err,
             fields: Object.assign({}, fieldState.current),
         });
-    }, []);
-    const gapStr = typeof gap === 'string' ? gap : `${gap}px`;
-    const resolvedLabelStyle = labelStyle
-        ? Object.assign(Object.assign({}, DEFAULT_LABEL_STYLE), labelStyle) : DEFAULT_LABEL_STYLE;
-    const renderLabel = (text) => renderFieldLabel(text, labelClassName, resolvedLabelStyle);
+    }, [setError, onChangeRef]);
     const showError = !hideErrors && error;
     const errorNode = showError
         ? renderError
             ? renderError(error)
             : (jsx("div", { role: "alert", className: errorClassName, style: errorStyle ? Object.assign(Object.assign({}, DEFAULT_ERROR_STYLE), errorStyle) : DEFAULT_ERROR_STYLE, children: error }))
         : null;
-    const cardNumberField = (jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cardNumber), jsx(OzCardNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cardNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.cardNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cardNumber) !== null && _a !== void 0 ? _a : 'Card number', disabled: disabled, onChange: (e) => { fieldState.current.cardNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cardNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cardNumber'); }, onReady: handleCardNumberReady })] }));
-    const expiryField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.expiry), jsx(OzExpiry, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.expiry), className: classNames === null || classNames === void 0 ? void 0 : classNames.expiry, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.expiry) !== null && _b !== void 0 ? _b : 'MM / YY', disabled: disabled, onChange: (e) => { fieldState.current.expiry = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'expiry'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'expiry'); }, onReady: handleExpiryReady })] }));
-    const cvvField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cvv), jsx(OzCvv, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cvv), className: classNames === null || classNames === void 0 ? void 0 : classNames.cvv, placeholder: (_c = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cvv) !== null && _c !== void 0 ? _c : 'CVV', disabled: disabled, onChange: (e) => { fieldState.current.cvv = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cvv'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cvv'); }, onReady: handleCvvReady })] }));
+    const cardNumberField = (jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cardNumber), jsx(OzCardNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cardNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.cardNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cardNumber) !== null && _a !== void 0 ? _a : 'Card number', disabled: disabled, onChange: (e) => { fieldState.current.cardNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cardNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cardNumber'); }, onReady: readyHandlers['cardNumber'] })] }));
+    const expiryField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.expiry), jsx(OzExpiry, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.expiry), className: classNames === null || classNames === void 0 ? void 0 : classNames.expiry, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.expiry) !== null && _b !== void 0 ? _b : 'MM / YY', disabled: disabled, onChange: (e) => { fieldState.current.expiry = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'expiry'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'expiry'); }, onReady: readyHandlers['expiry'] })] }));
+    const cvvField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cvv), jsx(OzCvv, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cvv), className: classNames === null || classNames === void 0 ? void 0 : classNames.cvv, placeholder: (_c = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cvv) !== null && _c !== void 0 ? _c : 'CVV', disabled: disabled, onChange: (e) => { fieldState.current.cvv = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cvv'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cvv'); }, onReady: readyHandlers['cvv'] })] }));
     if (layout === 'rows') {
         return (jsxs("div", { className: className, style: { width: '100%', display: 'flex', flexDirection: 'column', gap: gapStr }, children: [cardNumberField, expiryField, cvvField, errorNode] }));
     }
@@ -2164,49 +2418,21 @@ const OzBankRoutingNumber = (props) => jsx(OzFieldBase, Object.assign({ type: "r
 function OzBankCard({ style, styles, classNames, labels, labelStyle, labelClassName, gap = 8, hideErrors = false, errorStyle, errorClassName, renderError, onChange, onReady, onFocus, onBlur, disabled, className, placeholders, }) {
     var _a, _b;
     const { vault } = useContext(OzContext);
+    const { onChangeRef, onFocusRef, onBlurRef, readyHandlers, error, setError, gapStr, renderLabel, } = useCardBase({
+        vault,
+        fieldNames: ['accountNumber', 'routingNumber'],
+        onChange,
+        onReady,
+        onFocus,
+        onBlur,
+        gap,
+        labelStyle,
+        labelClassName,
+    });
     const fieldState = useRef({
         accountNumber: null,
         routingNumber: null,
     });
-    const readyFieldTypes = useRef(new Set());
-    const onReadyFiredRef = useRef(false);
-    const vaultRef = useRef(vault);
-    const onChangeRef = useRef(onChange);
-    const onReadyRef = useRef(onReady);
-    const onFocusRef = useRef(onFocus);
-    const onBlurRef = useRef(onBlur);
-    useEffect(() => { onChangeRef.current = onChange; }, [onChange]);
-    useEffect(() => { onReadyRef.current = onReady; }, [onReady]);
-    useEffect(() => { onFocusRef.current = onFocus; }, [onFocus]);
-    useEffect(() => { onBlurRef.current = onBlur; }, [onBlur]);
-    useEffect(() => {
-        if (vault !== vaultRef.current) {
-            vaultRef.current = vault;
-            readyFieldTypes.current = new Set();
-            onReadyFiredRef.current = false;
-        }
-        return () => {
-            readyFieldTypes.current = new Set();
-            onReadyFiredRef.current = false;
-        };
-    }, [vault]);
-    const [error, setError] = useState();
-    const handleAccountReady = useCallback(() => {
-        var _a;
-        readyFieldTypes.current.add('accountNumber');
-        if (readyFieldTypes.current.size >= 2 && !onReadyFiredRef.current) {
-            onReadyFiredRef.current = true;
-            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
-        }
-    }, []);
-    const handleRoutingReady = useCallback(() => {
-        var _a;
-        readyFieldTypes.current.add('routingNumber');
-        if (readyFieldTypes.current.size >= 2 && !onReadyFiredRef.current) {
-            onReadyFiredRef.current = true;
-            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
-        }
-    }, []);
     const emitChange = useCallback(() => {
         var _a;
         const { accountNumber, routingNumber } = fieldState.current;
@@ -2219,19 +2445,15 @@ function OzBankCard({ style, styles, classNames, labels, labelStyle, labelClassN
             error: err,
             fields: Object.assign({}, fieldState.current),
         });
-    }, []);
-    const gapStr = typeof gap === 'string' ? gap : `${gap}px`;
-    const resolvedLabelStyle = labelStyle
-        ? Object.assign(Object.assign({}, DEFAULT_LABEL_STYLE), labelStyle) : DEFAULT_LABEL_STYLE;
-    const renderLabel = (text) => renderFieldLabel(text, labelClassName, resolvedLabelStyle);
+    }, [setError, onChangeRef]);
     const showError = !hideErrors && error;
     const errorNode = showError
         ? renderError
             ? renderError(error)
             : (jsx("div", { role: "alert", className: errorClassName, style: errorStyle ? Object.assign(Object.assign({}, DEFAULT_ERROR_STYLE), errorStyle) : DEFAULT_ERROR_STYLE, children: error }))
         : null;
-    return (jsxs("div", { className: className, style: { width: '100%', display: 'flex', flexDirection: 'column', gap: gapStr }, children: [jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.accountNumber), jsx(OzBankAccountNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.accountNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.accountNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.accountNumber) !== null && _a !== void 0 ? _a : 'Account number', disabled: disabled, onChange: (e) => { fieldState.current.accountNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'accountNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'accountNumber'); }, onReady: handleAccountReady })] }), jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.routingNumber), jsx(OzBankRoutingNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.routingNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.routingNumber, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.routingNumber) !== null && _b !== void 0 ? _b : 'Routing number', disabled: disabled, onChange: (e) => { fieldState.current.routingNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'routingNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'routingNumber'); }, onReady: handleRoutingReady })] }), errorNode] }));
+    return (jsxs("div", { className: className, style: { width: '100%', display: 'flex', flexDirection: 'column', gap: gapStr }, children: [jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.accountNumber), jsx(OzBankAccountNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.accountNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.accountNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.accountNumber) !== null && _a !== void 0 ? _a : 'Account number', disabled: disabled, onChange: (e) => { fieldState.current.accountNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'accountNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'accountNumber'); }, onReady: readyHandlers['accountNumber'] })] }), jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.routingNumber), jsx(OzBankRoutingNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.routingNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.routingNumber, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.routingNumber) !== null && _b !== void 0 ? _b : 'Routing number', disabled: disabled, onChange: (e) => { fieldState.current.routingNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'routingNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'routingNumber'); }, onReady: readyHandlers['routingNumber'] })] }), errorNode] }));
 }
 
-export { OzBankAccountNumber, OzBankCard, OzBankRoutingNumber, OzCard, OzCardNumber, OzCvv, OzElements, OzExpiry, createFetchWaxKey, useOzElements };
+export { OzBankAccountNumber, OzBankCard, OzBankRoutingNumber, OzCard, OzCardNumber, OzCvv, OzElements, OzExpiry, createSessionFetcher as createFetchWaxKey, useOzElements };
 //# sourceMappingURL=index.esm.js.map