@ozura/elements 1.1.0 → 1.2.0-next.27

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.
      *
@@ -382,7 +382,7 @@
      * it never holds raw card data — all sensitive values live in the iframe.
      */
     class OzElement {
-        constructor(elementType, options, vaultId, frameBaseUrl, fonts = [], appearanceStyle) {
+        constructor(elementType, options, vaultId, frameBaseUrl, fonts = [], appearanceStyle, onDestroy) {
             this.iframe = null;
             this._frameWindow = null;
             this._ready = false;
@@ -398,6 +398,7 @@
             this.fonts = fonts;
             this.appearanceStyle = appearanceStyle;
             this.frameId = `oz-${elementType}-${uuid()}`;
+            this._onDestroy = onDestroy;
         }
         /** The element type this proxy represents. */
         get type() {
@@ -553,9 +554,14 @@
          * and prevents future use. Distinct from `unmount()` which allows re-mounting.
          */
         destroy() {
+            var _a;
             this.unmount();
             this.handlers.clear();
             this._destroyed = true;
+            // Notify OzVault so it can prune the stale frameId entry from its elements
+            // and completionState maps. Without this, manually calling el.destroy() leaks
+            // map entries that grow unboundedly in SPA scenarios with repeated mount/unmount.
+            (_a = this._onDestroy) === null || _a === void 0 ? void 0 : _a.call(this);
         }
         // ─── Called by OzVault ───────────────────────────────────────────────────
         /**
@@ -896,13 +902,116 @@
      */
     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');
+                }
+            }
+            // Parse JSON separately from the ok-check so that a non-JSON error body
+            // (HTML error page, WAF block, CDN 503) produces the right error code.
+            // Previously res.json() was attempted before res.ok was checked; a parse
+            // failure on a 5xx HTML body would fall through as {} and produce a
+            // misleading 'validation' code when the real cause is a server/network issue.
+            let data = {};
+            try {
+                data = await res.json();
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new OzError(`Session endpoint returned HTTP ${res.status} with a non-JSON body`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+                }
+                // HTTP 200 but body isn't JSON — this is a misconfigured session endpoint.
+                throw new OzError('Session endpoint returned HTTP 200 but the response body is not valid JSON. Check your /api/oz-session implementation.', undefined, 'validation');
+            }
+            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';
+        if (!v || typeof v !== 'object')
+            return false;
+        const r = v;
+        return (typeof r.last4 === 'string' &&
+            typeof r.brand === 'string' &&
+            typeof r.expMonth === 'string' &&
+            typeof r.expYear === 'string');
     }
     function isBankAccountMetadata(v) {
-        return !!v && typeof v === 'object' && typeof v.last4 === 'string';
+        if (!v || typeof v !== 'object')
+            return false;
+        const r = v;
+        return typeof r.last4 === 'string' && typeof r.routingNumberLast4 === '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.
@@ -910,16 +1019,10 @@
      * Use the static `OzVault.create()` factory — do not call `new OzVault()` directly.
      *
      * @example
+     * // Recommended — pass sessionUrl and let the SDK call your backend automatically
      * const vault = await OzVault.create({
-     *   pubKey: 'pk_live_...',
-     *   fetchWaxKey: async (sessionId) => {
-     *     // Call your backend — which calls ozura.mintWaxKey() from @ozura/elements/server
-     *     const { waxKey } = await fetch('/api/mint-wax', {
-     *       method: 'POST',
-     *       body: JSON.stringify({ sessionId }),
-     *     }).then(r => r.json());
-     *     return waxKey;
-     *   },
+     *   pubKey: 'pk_prod_...',  // or 'pk_test_...' for test mode
+     *   sessionUrl: '/api/oz-session',  // backend endpoint that calls ozura.createSession()
      * });
      * const cardNum = vault.createElement('cardNumber');
      * cardNum.mount('#card-number');
@@ -935,7 +1038,7 @@
          * @internal
          */
         constructor(options, waxKey, tokenizationSessionId) {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             this.elements = new Map();
             this.elementsByType = new Map();
             this.bankElementsByType = new Map();
@@ -969,7 +1072,12 @@
             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.
+            // null means unlimited — use Infinity so the ">=" check never triggers.
+            const rawLimit = options.sessionLimit !== undefined
+                ? options.sessionLimit
+                : ((_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3);
+            this._maxTokenizeCalls = rawLimit === null ? Infinity : rawLimit;
             this._debug = (_c = options.debug) !== null && _c !== void 0 ? _c : false;
             this.boundHandleMessage = this.handleMessage.bind(this);
             window.addEventListener('message', this.boundHandleMessage);
@@ -985,7 +1093,8 @@
                     }
                 }, timeout);
             }
-            this._onWaxRefresh = options.onWaxRefresh;
+            // onSessionRefresh takes precedence over legacy onWaxRefresh
+            this._onWaxRefresh = (_e = options.onSessionRefresh) !== null && _e !== void 0 ? _e : options.onWaxRefresh;
             this._onReady = options.onReady;
             this.log('vault created', { vaultId: this.vaultId, frameBaseUrl: this.frameBaseUrl, maxTokenizeCalls: this._maxTokenizeCalls });
         }
@@ -993,51 +1102,63 @@
          * 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';
-                throw new OzError(`fetchWaxKey threw an error: ${msg}`, undefined, originalCode);
+                throw new OzError(`Session fetch threw an error: ${msg}`, undefined, originalCode);
             }
             signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
             if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
@@ -1046,11 +1167,11 @@
             }
             if (typeof waxKey !== 'string' || !waxKey.trim()) {
                 vault.destroy();
-                throw new OzError('fetchWaxKey must return a non-empty wax key string. Check your mint endpoint.');
+                throw new OzError('Session fetch returned an empty key. Check your session endpoint response — it must return { sessionKey: "..." }.');
             }
             // 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.
@@ -1137,7 +1258,12 @@
                 this.completionState.delete(existing.frameId);
                 existing.destroy();
             }
-            const el = new OzElement(type, options, this.vaultId, this.frameBaseUrl, this.fonts, this.resolvedAppearance);
+            const el = new OzElement(type, options, this.vaultId, this.frameBaseUrl, this.fonts, this.resolvedAppearance, () => {
+                // Prune vault-level maps when the element is manually destroyed so they
+                // don't grow unboundedly in SPA scenarios with repeated mount/unmount cycles.
+                this.elements.delete(el.frameId);
+                this.completionState.delete(el.frameId);
+            });
             this.elements.set(el.frameId, el);
             typeMap.set(type, el);
             return el;
@@ -1716,9 +1842,9 @@
                         // 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.log('proactive session 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);
+                                console.warn('[OzVault] Post-budget session key refresh failed:', err instanceof Error ? err.message : err);
                             });
                         }
                     }
@@ -1794,61 +1920,65 @@
                         }
                         pending.reject(new OzError(normalizeVaultError(raw), raw, errorCode));
                     }
-                    // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR
-                    const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
-                    if (bankPending) {
-                        this.bankTokenizeResolvers.delete(msg.requestId);
-                        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 {
-                                    const retryBankChannels = bankPending.readyElements.map(() => new MessageChannel());
-                                    this.sendToTokenizer({
-                                        type: 'OZ_BANK_TOKENIZE',
-                                        requestId: newRequestId,
-                                        waxKey: this.waxKey,
-                                        tokenizationSessionId: this.tokenizationSessionId,
-                                        pubKey: this.pubKey,
-                                        firstName: bankPending.firstName,
-                                        lastName: bankPending.lastName,
-                                        fieldCount: bankPending.fieldCount,
-                                    }, retryBankChannels.map(ch => ch.port1));
-                                    bankPending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryBankChannels[i].port2));
-                                    const retryBankTimeoutId = setTimeout(() => {
-                                        if (this.bankTokenizeResolvers.has(newRequestId)) {
-                                            this.bankTokenizeResolvers.delete(newRequestId);
-                                            this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
-                                            bankPending.reject(new OzError('Bank tokenization timed out after wax key refresh.', undefined, 'timeout'));
-                                        }
-                                    }, 30000);
-                                    const retryBankEntry = this.bankTokenizeResolvers.get(newRequestId);
-                                    if (retryBankEntry)
-                                        retryBankEntry.timeoutId = retryBankTimeoutId;
-                                }
-                                catch (setupErr) {
-                                    this.bankTokenizeResolvers.delete(newRequestId);
-                                    bankPending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry bank tokenization failed to start'));
-                                }
-                            }).catch((refreshErr) => {
-                                const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
-                                bankPending.reject(new OzError(msg, undefined, 'auth'));
-                            });
-                            break;
+                    else {
+                        // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR.
+                        // Use else-if rather than sequential checks so a UUID collision (however
+                        // improbable) can never trigger double-rejection of two unrelated resolvers.
+                        const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
+                        if (bankPending) {
+                            this.bankTokenizeResolvers.delete(msg.requestId);
+                            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 {
+                                        const retryBankChannels = bankPending.readyElements.map(() => new MessageChannel());
+                                        this.sendToTokenizer({
+                                            type: 'OZ_BANK_TOKENIZE',
+                                            requestId: newRequestId,
+                                            waxKey: this.waxKey,
+                                            tokenizationSessionId: this.tokenizationSessionId,
+                                            pubKey: this.pubKey,
+                                            firstName: bankPending.firstName,
+                                            lastName: bankPending.lastName,
+                                            fieldCount: bankPending.fieldCount,
+                                        }, retryBankChannels.map(ch => ch.port1));
+                                        bankPending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryBankChannels[i].port2));
+                                        const retryBankTimeoutId = setTimeout(() => {
+                                            if (this.bankTokenizeResolvers.has(newRequestId)) {
+                                                this.bankTokenizeResolvers.delete(newRequestId);
+                                                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
+                                                bankPending.reject(new OzError('Bank tokenization timed out after wax key refresh.', undefined, 'timeout'));
+                                            }
+                                        }, 30000);
+                                        const retryBankEntry = this.bankTokenizeResolvers.get(newRequestId);
+                                        if (retryBankEntry)
+                                            retryBankEntry.timeoutId = retryBankTimeoutId;
+                                    }
+                                    catch (setupErr) {
+                                        this.bankTokenizeResolvers.delete(newRequestId);
+                                        bankPending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry bank tokenization failed to start'));
+                                    }
+                                }).catch((refreshErr) => {
+                                    const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                                    bankPending.reject(new OzError(msg, undefined, 'auth'));
+                                });
+                                break;
+                            }
+                            bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
                         }
-                        bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
-                    }
+                    } // end else (bank path)
                     break;
                 }
                 case 'OZ_BANK_TOKEN_RESULT': {
@@ -1876,9 +2006,9 @@
                         // 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.log('proactive session 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);
+                                console.warn('[OzVault] Post-budget session key refresh failed:', err instanceof Error ? err.message : err);
                             });
                         }
                     }
@@ -1964,88 +2094,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;