@ozura/elements 1.1.0 → 1.2.0-next.27

package/dist/oz-elements.esm.js

@@ -1,144 +1,3 @@
-/**
- * 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',
@@ -303,6 +162,147 @@ function mergeAppearanceWithElementStyle(appearance, elementStyle) {
     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.
  *
@@ -376,7 +376,7 @@ function sanitizeOptions(options) {
  * 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;
@@ -392,6 +392,7 @@ class OzElement {
         this.fonts = fonts;
         this.appearanceStyle = appearanceStyle;
         this.frameId = `oz-${elementType}-${uuid()}`;
+        this._onDestroy = onDestroy;
     }
     /** The element type this proxy represents. */
     get type() {
@@ -547,9 +548,14 @@ class OzElement {
      * 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 ───────────────────────────────────────────────────
     /**
@@ -890,13 +896,116 @@ function validateBilling(billing) {
  */
 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.
@@ -904,16 +1013,10 @@ const DEFAULT_FRAME_BASE_URL = "https://elements.ozura.com";
  * 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');
@@ -929,7 +1032,7 @@ class OzVault {
      * @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();
@@ -963,7 +1066,12 @@ class OzVault {
         this.fonts = (_a = options.fonts) !== null && _a !== void 0 ? _a : [];
         this.resolvedAppearance = resolveAppearance(options.appearance);
         this.vaultId = `vault-${uuid()}`;
-        this._maxTokenizeCalls = (_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3;
+        // sessionLimit takes precedence over legacy maxTokenizeCalls.
+        // 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);
@@ -979,7 +1087,8 @@ class OzVault {
                 }
             }, 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 });
     }
@@ -987,51 +1096,63 @@ class OzVault {
      * 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) {
@@ -1040,11 +1161,11 @@ class OzVault {
         }
         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.
@@ -1131,7 +1252,12 @@ class OzVault {
             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;
@@ -1710,9 +1836,9 @@ class OzVault {
                     // 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);
                         });
                     }
                 }
@@ -1788,61 +1914,65 @@ class OzVault {
                     }
                     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': {
@@ -1870,9 +2000,9 @@ class OzVault {
                     // 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);
                         });
                     }
                 }
@@ -1958,83 +2088,5 @@ class OzVault {
     }
 }
 
-/**
- * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
- *
- * Calls your backend mint endpoint with `{ sessionId }` and returns the wax key string.
- * Throws on non-OK responses or a missing `waxKey` field so the vault can surface the
- * error through its normal error path.
- *
- * Each call enforces a 10-second per-attempt timeout. On a pure network-level
- * failure (connection refused, DNS failure, etc.) the call is retried once after
- * 750ms before throwing. HTTP errors (4xx/5xx) are never retried — they indicate
- * an endpoint misconfiguration or an invalid key, not a transient failure.
- *
- * The mint endpoint is typically the one-line `createMintWaxHandler` / `createMintWaxMiddleware`
- * from `@ozura/elements/server`.
- *
- * @param mintUrl - Absolute or relative URL of your wax-key mint endpoint, e.g. `'/api/mint-wax'`.
- *
- * @example
- * // Vanilla JS
- * const vault = await OzVault.create({
- *   pubKey: 'pk_live_...',
- *   fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
- * });
- *
- * @example
- * // React
- * <OzElements pubKey="pk_live_..." fetchWaxKey={createFetchWaxKey('/api/mint-wax')}>
- */
-function createFetchWaxKey(mintUrl) {
-    const TIMEOUT_MS = 10000;
-    // Each attempt gets its own AbortController so a timeout on attempt 1 does
-    // not bleed into the retry. Uses AbortController + setTimeout instead of
-    // AbortSignal.timeout() to support environments without that API.
-    const attemptFetch = (sessionId) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-        return fetch(mintUrl, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId }),
-            signal: controller.signal,
-        }).finally(() => clearTimeout(timer));
-    };
-    return async (sessionId) => {
-        let res;
-        try {
-            res = await attemptFetch(sessionId);
-        }
-        catch (firstErr) {
-            // Abort/timeout should not be retried — the server received nothing or
-            // we already waited the full timeout duration.
-            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
-                throw new OzError(`Wax key mint timed out after ${TIMEOUT_MS / 1000}s (${mintUrl})`, undefined, 'timeout');
-            }
-            // Pure network error (offline, DNS, connection refused) — retry once
-            // after a short pause in case of a transient blip.
-            await new Promise(resolve => setTimeout(resolve, 750));
-            try {
-                res = await attemptFetch(sessionId);
-            }
-            catch (retryErr) {
-                const msg = retryErr instanceof Error ? retryErr.message : 'Network error';
-                throw new OzError(`Could not reach wax key mint endpoint (${mintUrl}): ${msg}`, undefined, 'network');
-            }
-        }
-        const data = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            throw new OzError(typeof data.error === 'string' && data.error
-                ? data.error
-                : `Wax key mint failed (HTTP ${res.status})`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
-        }
-        if (typeof data.waxKey !== 'string' || !data.waxKey.trim()) {
-            throw new OzError('Mint endpoint response is missing waxKey. Check your /api/mint-wax implementation.', undefined, 'validation');
-        }
-        return data.waxKey;
-    };
-}
-
-export { OzElement, OzError, OzVault, createFetchWaxKey, normalizeBankVaultError, normalizeCardSaleError, normalizeVaultError };
+export { OzElement, OzError, OzVault, createSessionFetcher as createFetchWaxKey, createSessionFetcher, normalizeBankVaultError, normalizeCardSaleError, normalizeVaultError };
 //# sourceMappingURL=oz-elements.esm.js.map