@ozura/elements 1.0.2 → 1.1.0-next.22

package/dist/oz-elements.umd.js

@@ -4,147 +4,6 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.OzElements = {}));
 })(this, (function (exports) { 'use strict';
 
-    /**
-     * errors.ts — error types and normalisation for OzElements.
-     *
-     * Three normalisation functions:
-     *  - normalizeVaultError      — maps raw vault /tokenize errors to user-facing messages (card flows)
-     *  - normalizeBankVaultError   — maps raw vault /tokenize errors to user-facing messages (bank/ACH flows)
-     *  - normalizeCardSaleError    — maps raw cardSale API errors to user-facing messages
-     *
-     * Error keys in normalizeCardSaleError are taken directly from checkout's
-     * errorMapping.ts so the same error strings produce the same user-facing copy.
-     */
-    const OZ_ERROR_CODES = new Set(['network', 'timeout', 'auth', 'validation', 'server', 'config', 'unknown']);
-    /** Returns true and narrows to OzErrorCode when `value` is a valid member of the union. */
-    function isOzErrorCode(value) {
-        return typeof value === 'string' && OZ_ERROR_CODES.has(value);
-    }
-    class OzError extends Error {
-        constructor(message, raw, errorCode) {
-            super(message);
-            this.name = 'OzError';
-            this.raw = raw !== null && raw !== void 0 ? raw : message;
-            this.errorCode = errorCode !== null && errorCode !== void 0 ? errorCode : 'unknown';
-            this.retryable = this.errorCode === 'network' || this.errorCode === 'timeout' || this.errorCode === 'server';
-        }
-    }
-    /** Shared patterns that apply to both card and bank vault errors. */
-    function normalizeCommonVaultError(msg) {
-        if (msg.includes('api key') || msg.includes('unauthorized') || msg.includes('authentication') || msg.includes('forbidden')) {
-            return 'Authentication failed. Check your vault API key configuration.';
-        }
-        if (msg.includes('network') || msg.includes('failed to fetch') || msg.includes('networkerror')) {
-            return 'A network error occurred. Please check your connection and try again.';
-        }
-        if (msg.includes('timeout') || msg.includes('timed out')) {
-            return 'The request timed out. Please try again.';
-        }
-        if (msg.includes('http 5') || msg.includes('500') || msg.includes('502') || msg.includes('503')) {
-            return 'A server error occurred. Please try again shortly.';
-        }
-        return null;
-    }
-    /**
-     * Maps a raw vault /tokenize error string to a user-facing message for card flows.
-     * Falls back to the original string if no pattern matches.
-     */
-    function normalizeVaultError(raw) {
-        const msg = raw.toLowerCase();
-        if (msg.includes('card number') || msg.includes('invalid card') || msg.includes('luhn')) {
-            return 'The card number is invalid. Please check and try again.';
-        }
-        if (msg.includes('expir')) {
-            return 'The card expiration date is invalid or the card has expired.';
-        }
-        if (msg.includes('cvv') || msg.includes('cvc') || msg.includes('security code')) {
-            return 'The CVV code is invalid. Please check and try again.';
-        }
-        if (msg.includes('insufficient') || msg.includes('funds')) {
-            return 'Your card has insufficient funds. Please use a different card.';
-        }
-        if (msg.includes('declined') || msg.includes('do not honor')) {
-            return 'Your card was declined. Please try a different card or contact your bank.';
-        }
-        const common = normalizeCommonVaultError(msg);
-        if (common)
-            return common;
-        return raw;
-    }
-    /**
-     * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
-     * Uses bank-specific pattern matching so card-specific messages are never shown for
-     * bank errors. Falls back to the original string if no pattern matches.
-     */
-    function normalizeBankVaultError(raw) {
-        const msg = raw.toLowerCase();
-        if (msg.includes('account number') || msg.includes('account_number') || msg.includes('invalid account')) {
-            return 'The bank account number is invalid. Please check and try again.';
-        }
-        if (msg.includes('routing number') || msg.includes('routing_number') || msg.includes('invalid routing') || /\baba\b/.test(msg)) {
-            return 'The routing number is invalid. Please check and try again.';
-        }
-        const common = normalizeCommonVaultError(msg);
-        if (common)
-            return common;
-        return raw;
-    }
-    // ─── cardSale error map (mirrors checkout/src/utils/errorMapping.ts exactly) ─
-    const CARD_SALE_ERROR_MAP = [
-        ['Insufficient Funds', 'Your card has insufficient funds. Please use a different payment method.'],
-        ['Invalid card number', 'The card number you entered is invalid. Please check and try again.'],
-        ['Card expired', 'Your card has expired. Please use a different card.'],
-        ['CVV Verification Failed', 'The CVV code you entered is incorrect. Please check and try again.'],
-        ['Address Verification Failed', 'The billing address does not match your card. Please verify your address.'],
-        ['Do Not Honor', 'Your card was declined. Please contact your bank or use a different payment method.'],
-        ['Declined', 'Your card was declined. Please contact your bank or use a different payment method.'],
-        ['Surcharge is currently not supported', 'Surcharge fees are not supported at this time.'],
-        ['Surcharge percent must be between', 'Surcharge fees are not supported at this time.'],
-        ['Forbidden - API key', 'Authentication failed. Please refresh the page.'],
-        ['Api Key is invalid', 'Authentication failed. Please refresh the page.'],
-        ['API key not found', 'Authentication failed. Please refresh the page.'],
-        ['Access token expired', 'Your session has expired. Please refresh the page.'],
-        ['Access token is invalid', 'Authentication failed. Please refresh the page.'],
-        ['Unauthorized', 'Authentication failed. Please refresh the page.'],
-        ['Too Many Requests', 'Too many requests. Please wait a moment and try again.'],
-        ['Rate limit exceeded', 'System is busy. Please wait a moment and try again.'],
-        ['No processor integrations found', 'Payment processing is not configured for this merchant. Please contact the merchant for assistance.'],
-        ['processor integration', 'Payment processing is temporarily unavailable. Please try again later or contact the merchant.'],
-        ['Invalid zipcode', 'The ZIP code you entered is invalid. Please check and try again.'],
-        ['failed to save to database', 'Your payment was processed but we encountered an issue. Please contact support.'],
-        ['CASHBACK UNAVAIL', 'This transaction type is not supported. Please try again or use a different payment method.'],
-    ];
-    /**
-     * Maps a raw Ozura Pay API cardSale error string to a user-facing message.
-     *
-     * Uses the exact same error key table as checkout's `getUserFriendlyError()` in
-     * errorMapping.ts so both surfaces produce identical copy for the same errors.
-     *
-     * Falls back to the original string when it's under 100 characters, or to a
-     * generic message for long/opaque server errors — matching checkout's fallback
-     * behaviour exactly.
-     *
-     * **Trade-off:** Short unrecognised strings (e.g. processor codes like
-     * `"PROC_TIMEOUT"`) are passed through verbatim. This intentionally mirrors
-     * checkout so the same raw Pay API errors produce the same user-facing text on
-     * both surfaces. If the Pay API ever returns internal codes that should never
-     * reach the UI, the fix belongs in the Pay API error normalisation layer rather
-     * than here.
-     */
-    function normalizeCardSaleError(raw) {
-        if (!raw)
-            return 'Payment processing failed. Please try again.';
-        for (const [key, message] of CARD_SALE_ERROR_MAP) {
-            if (raw.toLowerCase().includes(key.toLowerCase())) {
-                return message;
-            }
-        }
-        // Checkout fallback: pass through short errors, genericise long ones
-        if (raw.length < 100)
-            return raw;
-        return 'Payment processing failed. Please try again or contact support.';
-    }
-
     const THEME_DEFAULT = {
         base: {
             color: '#1a1a2e',
@@ -309,6 +168,147 @@
         return mergeStyleConfigs(appearance, elementStyle);
     }
 
+    /**
+     * errors.ts — error types and normalisation for OzElements.
+     *
+     * Three normalisation functions:
+     *  - normalizeVaultError      — maps raw vault /tokenize errors to user-facing messages (card flows)
+     *  - normalizeBankVaultError   — maps raw vault /tokenize errors to user-facing messages (bank/ACH flows)
+     *  - normalizeCardSaleError    — maps raw cardSale API errors to user-facing messages
+     *
+     * Error keys in normalizeCardSaleError are taken directly from checkout's
+     * errorMapping.ts so the same error strings produce the same user-facing copy.
+     */
+    const OZ_ERROR_CODES = new Set(['network', 'timeout', 'auth', 'validation', 'server', 'config', 'unknown']);
+    /** Returns true and narrows to OzErrorCode when `value` is a valid member of the union. */
+    function isOzErrorCode(value) {
+        return typeof value === 'string' && OZ_ERROR_CODES.has(value);
+    }
+    class OzError extends Error {
+        constructor(message, raw, errorCode) {
+            super(message);
+            this.name = 'OzError';
+            this.raw = raw !== null && raw !== void 0 ? raw : message;
+            this.errorCode = errorCode !== null && errorCode !== void 0 ? errorCode : 'unknown';
+            this.retryable = this.errorCode === 'network' || this.errorCode === 'timeout' || this.errorCode === 'server';
+        }
+    }
+    /** Shared patterns that apply to both card and bank vault errors. */
+    function normalizeCommonVaultError(msg) {
+        if (msg.includes('api key') || msg.includes('unauthorized') || msg.includes('authentication') || msg.includes('forbidden')) {
+            return 'Authentication failed. Check your vault API key configuration.';
+        }
+        if (msg.includes('network') || msg.includes('failed to fetch') || msg.includes('networkerror')) {
+            return 'A network error occurred. Please check your connection and try again.';
+        }
+        if (msg.includes('timeout') || msg.includes('timed out')) {
+            return 'The request timed out. Please try again.';
+        }
+        if (msg.includes('http 5') || msg.includes('500') || msg.includes('502') || msg.includes('503')) {
+            return 'A server error occurred. Please try again shortly.';
+        }
+        return null;
+    }
+    /**
+     * Maps a raw vault /tokenize error string to a user-facing message for card flows.
+     * Falls back to the original string if no pattern matches.
+     */
+    function normalizeVaultError(raw) {
+        const msg = raw.toLowerCase();
+        if (msg.includes('card number') || msg.includes('invalid card') || msg.includes('luhn')) {
+            return 'The card number is invalid. Please check and try again.';
+        }
+        if (msg.includes('expir')) {
+            return 'The card expiration date is invalid or the card has expired.';
+        }
+        if (msg.includes('cvv') || msg.includes('cvc') || msg.includes('security code')) {
+            return 'The CVV code is invalid. Please check and try again.';
+        }
+        if (msg.includes('insufficient') || msg.includes('funds')) {
+            return 'Your card has insufficient funds. Please use a different card.';
+        }
+        if (msg.includes('declined') || msg.includes('do not honor')) {
+            return 'Your card was declined. Please try a different card or contact your bank.';
+        }
+        const common = normalizeCommonVaultError(msg);
+        if (common)
+            return common;
+        return raw;
+    }
+    /**
+     * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
+     * Uses bank-specific pattern matching so card-specific messages are never shown for
+     * bank errors. Falls back to the original string if no pattern matches.
+     */
+    function normalizeBankVaultError(raw) {
+        const msg = raw.toLowerCase();
+        if (msg.includes('account number') || msg.includes('account_number') || msg.includes('invalid account')) {
+            return 'The bank account number is invalid. Please check and try again.';
+        }
+        if (msg.includes('routing number') || msg.includes('routing_number') || msg.includes('invalid routing') || /\baba\b/.test(msg)) {
+            return 'The routing number is invalid. Please check and try again.';
+        }
+        const common = normalizeCommonVaultError(msg);
+        if (common)
+            return common;
+        return raw;
+    }
+    // ─── cardSale error map (mirrors checkout/src/utils/errorMapping.ts exactly) ─
+    const CARD_SALE_ERROR_MAP = [
+        ['Insufficient Funds', 'Your card has insufficient funds. Please use a different payment method.'],
+        ['Invalid card number', 'The card number you entered is invalid. Please check and try again.'],
+        ['Card expired', 'Your card has expired. Please use a different card.'],
+        ['CVV Verification Failed', 'The CVV code you entered is incorrect. Please check and try again.'],
+        ['Address Verification Failed', 'The billing address does not match your card. Please verify your address.'],
+        ['Do Not Honor', 'Your card was declined. Please contact your bank or use a different payment method.'],
+        ['Declined', 'Your card was declined. Please contact your bank or use a different payment method.'],
+        ['Surcharge is currently not supported', 'Surcharge fees are not supported at this time.'],
+        ['Surcharge percent must be between', 'Surcharge fees are not supported at this time.'],
+        ['Forbidden - API key', 'Authentication failed. Please refresh the page.'],
+        ['Api Key is invalid', 'Authentication failed. Please refresh the page.'],
+        ['API key not found', 'Authentication failed. Please refresh the page.'],
+        ['Access token expired', 'Your session has expired. Please refresh the page.'],
+        ['Access token is invalid', 'Authentication failed. Please refresh the page.'],
+        ['Unauthorized', 'Authentication failed. Please refresh the page.'],
+        ['Too Many Requests', 'Too many requests. Please wait a moment and try again.'],
+        ['Rate limit exceeded', 'System is busy. Please wait a moment and try again.'],
+        ['No processor integrations found', 'Payment processing is not configured for this merchant. Please contact the merchant for assistance.'],
+        ['processor integration', 'Payment processing is temporarily unavailable. Please try again later or contact the merchant.'],
+        ['Invalid zipcode', 'The ZIP code you entered is invalid. Please check and try again.'],
+        ['failed to save to database', 'Your payment was processed but we encountered an issue. Please contact support.'],
+        ['CASHBACK UNAVAIL', 'This transaction type is not supported. Please try again or use a different payment method.'],
+    ];
+    /**
+     * Maps a raw Ozura Pay API cardSale error string to a user-facing message.
+     *
+     * Uses the exact same error key table as checkout's `getUserFriendlyError()` in
+     * errorMapping.ts so both surfaces produce identical copy for the same errors.
+     *
+     * Falls back to the original string when it's under 100 characters, or to a
+     * generic message for long/opaque server errors — matching checkout's fallback
+     * behaviour exactly.
+     *
+     * **Trade-off:** Short unrecognised strings (e.g. processor codes like
+     * `"PROC_TIMEOUT"`) are passed through verbatim. This intentionally mirrors
+     * checkout so the same raw Pay API errors produce the same user-facing text on
+     * both surfaces. If the Pay API ever returns internal codes that should never
+     * reach the UI, the fix belongs in the Pay API error normalisation layer rather
+     * than here.
+     */
+    function normalizeCardSaleError(raw) {
+        if (!raw)
+            return 'Payment processing failed. Please try again.';
+        for (const [key, message] of CARD_SALE_ERROR_MAP) {
+            if (raw.toLowerCase().includes(key.toLowerCase())) {
+                return message;
+            }
+        }
+        // Checkout fallback: pass through short errors, genericise long ones
+        if (raw.length < 100)
+            return raw;
+        return 'Payment processing failed. Please try again or contact support.';
+    }
+
     /**
      * Generates a RFC 4122 v4 UUID.
      *
@@ -413,7 +413,7 @@
          * (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)
@@ -430,7 +430,13 @@
             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.
@@ -444,7 +450,7 @@
             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` });
@@ -877,13 +883,105 @@
         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.
@@ -916,7 +1014,7 @@
          * @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();
@@ -929,6 +1027,9 @@
             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.
@@ -947,14 +1048,16 @@
             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) {
@@ -962,54 +1065,68 @@
                     }
                 }, 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';
@@ -1026,13 +1143,14 @@
             }
             // 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;
         }
         /**
@@ -1174,8 +1292,13 @@
             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); },
@@ -1186,6 +1309,7 @@
                 });
                 try {
                     const bankChannels = readyBankElements.map(() => new MessageChannel());
+                    const bankTokenizeStartMs = Date.now();
                     this.sendToTokenizer({
                         type: 'OZ_BANK_TOKENIZE',
                         requestId,
@@ -1196,6 +1320,7 @@
                         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)) {
@@ -1206,8 +1331,10 @@
                         }
                     }, 30000);
                     const bankPendingEntry = this.bankTokenizeResolvers.get(requestId);
-                    if (bankPendingEntry)
+                    if (bankPendingEntry) {
                         bankPendingEntry.timeoutId = bankTimeoutId;
+                        bankPendingEntry.tokenizeStartMs = bankTokenizeStartMs;
+                    }
                 }
                 catch (err) {
                     this.bankTokenizeResolvers.delete(requestId);
@@ -1278,8 +1405,15 @@
             }
             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); },
@@ -1292,6 +1426,7 @@
                 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,
@@ -1302,6 +1437,11 @@
                         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(() => {
@@ -1323,6 +1463,63 @@
                 }
             });
         }
+        /**
+         * 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
@@ -1333,6 +1530,7 @@
             if (this._destroyed)
                 return;
             this._destroyed = true;
+            this.log('destroy() called');
             window.removeEventListener('message', this.boundHandleMessage);
             document.removeEventListener('visibilitychange', this.boundHandleVisibility);
             if (this._pendingMount) {
@@ -1387,13 +1585,17 @@
             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.
@@ -1403,6 +1605,56 @@
                 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;
@@ -1414,6 +1666,7 @@
                 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;
@@ -1449,6 +1702,12 @@
                     // 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') {
@@ -1472,6 +1731,7 @@
             // 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;
@@ -1483,17 +1743,25 @@
             // 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);
@@ -1505,6 +1773,7 @@
                     // 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) {
@@ -1529,11 +1798,18 @@
                         }
                         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);
                             });
@@ -1553,14 +1829,25 @@
                         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 }));
@@ -1607,11 +1894,16 @@
                         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 {
@@ -1669,9 +1961,15 @@
                         }
                         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);
                             });
@@ -1727,6 +2025,7 @@
             }
             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()) {
@@ -1740,6 +2039,11 @@
                 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;
@@ -1753,88 +2057,11 @@
         }
     }
 
-    /**
-     * 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;
-        };
-    }
-
     exports.OzElement = OzElement;
     exports.OzError = OzError;
     exports.OzVault = OzVault;
-    exports.createFetchWaxKey = createFetchWaxKey;
+    exports.createFetchWaxKey = createSessionFetcher;
+    exports.createSessionFetcher = createSessionFetcher;
     exports.normalizeBankVaultError = normalizeBankVaultError;
     exports.normalizeCardSaleError = normalizeCardSaleError;
     exports.normalizeVaultError = normalizeVaultError;