@ozura/elements 1.1.0 → 1.2.0

package/dist/react/index.cjs.js

@@ -840,6 +840,85 @@ 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');
+            }
+        }
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            throw new OzError(typeof data.error === 'string' && data.error
+                ? data.error
+                : `Session endpoint returned HTTP ${res.status}`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+        }
+        // Accept both new `sessionKey` and legacy `waxKey` for backward compatibility
+        // with backends that haven't migrated to createSessionMiddleware yet.
+        const key = (typeof data.sessionKey === 'string' ? data.sessionKey : '') ||
+            (typeof data.waxKey === 'string' ? data.waxKey : '');
+        if (!key.trim()) {
+            throw new OzError('Session endpoint response is missing sessionKey. Check your /api/oz-session implementation.', undefined, 'validation');
+        }
+        return key;
+    };
+}
+
 function isCardMetadata(v) {
     return !!v && typeof v === 'object' && typeof v.last4 === 'string';
 }
@@ -879,7 +958,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();
@@ -913,7 +992,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);
@@ -929,7 +1013,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 });
     }
@@ -937,51 +1022,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) {
@@ -990,11 +1087,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.
@@ -1660,9 +1757,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);
                         });
                     }
                 }
@@ -1820,9 +1917,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);
                         });
                     }
                 }
@@ -1908,84 +2005,6 @@ class OzVault {
     }
 }
 
-/**
- * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
- *
- * Calls your backend mint endpoint with `{ sessionId }` and returns the wax key string.
- * Throws on non-OK responses or a missing `waxKey` field so the vault can surface the
- * error through its normal error path.
- *
- * Each call enforces a 10-second per-attempt timeout. On a pure network-level
- * failure (connection refused, DNS failure, etc.) the call is retried once after
- * 750ms before throwing. HTTP errors (4xx/5xx) are never retried — they indicate
- * an endpoint misconfiguration or an invalid key, not a transient failure.
- *
- * The mint endpoint is typically the one-line `createMintWaxHandler` / `createMintWaxMiddleware`
- * from `@ozura/elements/server`.
- *
- * @param mintUrl - Absolute or relative URL of your wax-key mint endpoint, e.g. `'/api/mint-wax'`.
- *
- * @example
- * // Vanilla JS
- * const vault = await OzVault.create({
- *   pubKey: 'pk_live_...',
- *   fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
- * });
- *
- * @example
- * // React
- * <OzElements pubKey="pk_live_..." fetchWaxKey={createFetchWaxKey('/api/mint-wax')}>
- */
-function createFetchWaxKey(mintUrl) {
-    const TIMEOUT_MS = 10000;
-    // Each attempt gets its own AbortController so a timeout on attempt 1 does
-    // not bleed into the retry. Uses AbortController + setTimeout instead of
-    // AbortSignal.timeout() to support environments without that API.
-    const attemptFetch = (sessionId) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-        return fetch(mintUrl, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId }),
-            signal: controller.signal,
-        }).finally(() => clearTimeout(timer));
-    };
-    return async (sessionId) => {
-        let res;
-        try {
-            res = await attemptFetch(sessionId);
-        }
-        catch (firstErr) {
-            // Abort/timeout should not be retried — the server received nothing or
-            // we already waited the full timeout duration.
-            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
-                throw new OzError(`Wax key mint timed out after ${TIMEOUT_MS / 1000}s (${mintUrl})`, undefined, 'timeout');
-            }
-            // Pure network error (offline, DNS, connection refused) — retry once
-            // after a short pause in case of a transient blip.
-            await new Promise(resolve => setTimeout(resolve, 750));
-            try {
-                res = await attemptFetch(sessionId);
-            }
-            catch (retryErr) {
-                const msg = retryErr instanceof Error ? retryErr.message : 'Network error';
-                throw new OzError(`Could not reach wax key mint endpoint (${mintUrl}): ${msg}`, undefined, 'network');
-            }
-        }
-        const data = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            throw new OzError(typeof data.error === 'string' && data.error
-                ? data.error
-                : `Wax key mint failed (HTTP ${res.status})`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
-        }
-        if (typeof data.waxKey !== 'string' || !data.waxKey.trim()) {
-            throw new OzError('Mint endpoint response is missing waxKey. Check your /api/mint-wax implementation.', undefined, 'validation');
-        }
-        return data.waxKey;
-    };
-}
-
 const OzContext = react.createContext({
     vault: null,
     initError: null,
@@ -2002,7 +2021,7 @@ const OzContext = react.createContext({
  * All `<OzCardNumber />`, `<OzExpiry />`, and `<OzCvv />` children must be
  * rendered inside this provider.
  */
-function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, onWaxRefresh, onReady, appearance, maxTokenizeCalls, debug, children }) {
+function OzElements({ sessionUrl, getSessionKey, fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, onSessionRefresh, onWaxRefresh, onReady, appearance, sessionLimit, maxTokenizeCalls, debug, children }) {
     const [vault, setVault] = react.useState(null);
     const [initError, setInitError] = react.useState(null);
     const [mountedCount, setMountedCount] = react.useState(0);
@@ -2010,13 +2029,14 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
     const [tokenizeCount, setTokenizeCount] = react.useState(0);
     const onLoadErrorRef = react.useRef(onLoadError);
     onLoadErrorRef.current = onLoadError;
-    const onWaxRefreshRef = react.useRef(onWaxRefresh);
-    onWaxRefreshRef.current = onWaxRefresh;
+    const onWaxRefreshRef = react.useRef(onSessionRefresh !== null && onSessionRefresh !== void 0 ? onSessionRefresh : onWaxRefresh);
+    onWaxRefreshRef.current = onSessionRefresh !== null && onSessionRefresh !== void 0 ? onSessionRefresh : onWaxRefresh;
     const onReadyRef = react.useRef(onReady);
     onReadyRef.current = onReady;
-    // Keep a ref to fetchWaxKey so changes don't trigger vault recreation
-    const fetchWaxKeyRef = react.useRef(fetchWaxKey);
-    fetchWaxKeyRef.current = fetchWaxKey;
+    // Keep a ref to the session callback so changes don't trigger vault recreation.
+    // Priority mirrors OzVault.create(): sessionUrl > getSessionKey > fetchWaxKey.
+    const getSessionKeyRef = react.useRef(getSessionKey !== null && getSessionKey !== void 0 ? getSessionKey : fetchWaxKey);
+    getSessionKeyRef.current = getSessionKey !== null && getSessionKey !== void 0 ? getSessionKey : fetchWaxKey;
     const appearanceKey = react.useMemo(() => appearance ? JSON.stringify(appearance) : '', [appearance]);
     const fontsKey = react.useMemo(() => fonts ? JSON.stringify(fonts) : '', [fonts]);
     react.useEffect(() => {
@@ -2043,7 +2063,11 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
         // synchronously rather than waiting for the promise to settle. Without this,
         // two hidden iframes and two window listeners briefly coexist.
         const abortController = new AbortController();
-        OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey, fetchWaxKey: (sessionId) => fetchWaxKeyRef.current(sessionId) }, (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: fireLoadError, loadTimeoutMs } : {})), { 
+        OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey }, (sessionUrl
+            ? { sessionUrl }
+            : getSessionKeyRef.current
+                ? { getSessionKey: (sessionId) => getSessionKeyRef.current(sessionId) }
+                : {})), (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: fireLoadError, loadTimeoutMs } : {})), { 
             // Always install onWaxRefresh internally so we can reset tokenizeCount
             // when any wax key refresh occurs (reactive TTL expiry, post-budget
             // proactive, or visibility-change proactive). Without this the React
@@ -2065,11 +2089,12 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
             // the retry tokenization completes (a full fetchWaxKey + tokenize round-
             // trip separates them), so the count correctly resets to 0 then rises to
             // 1 after the retry notifyTokenize fires.
-            onWaxRefresh: () => {
+            onSessionRefresh: () => {
                 var _a;
                 Promise.resolve().then(() => setTokenizeCount(0));
                 (_a = onWaxRefreshRef.current) === null || _a === void 0 ? void 0 : _a.call(onWaxRefreshRef);
-            }, onReady: () => { var _a; return (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef); } }), (maxTokenizeCalls !== undefined ? { maxTokenizeCalls } : {})), (debug ? { debug: true } : {})), abortController.signal).then(v => {
+            }, onReady: () => { var _a; return (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef); } }), (sessionLimit !== undefined ? { sessionLimit }
+            : maxTokenizeCalls !== undefined ? { maxTokenizeCalls } : {})), (debug ? { debug: true } : {})), abortController.signal).then(v => {
             if (cancelled) {
                 v.destroy();
                 return;
@@ -2102,7 +2127,7 @@ function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loa
             setVault(null);
             setInitError(null);
         };
-    }, [pubKey, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey, maxTokenizeCalls, debug]);
+    }, [pubKey, sessionUrl, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey, sessionLimit, maxTokenizeCalls, debug]);
     const notifyMount = react.useCallback(() => setMountedCount(n => n + 1), []);
     const notifyReady = react.useCallback(() => setReadyCount(n => n + 1), []);
     const notifyUnmount = react.useCallback(() => {
@@ -2446,6 +2471,7 @@ exports.OzCardNumber = OzCardNumber;
 exports.OzCvv = OzCvv;
 exports.OzElements = OzElements;
 exports.OzExpiry = OzExpiry;
-exports.createFetchWaxKey = createFetchWaxKey;
+exports.createFetchWaxKey = createSessionFetcher;
+exports.createSessionFetcher = createSessionFetcher;
 exports.useOzElements = useOzElements;
 //# sourceMappingURL=index.cjs.js.map