@ozura/elements 1.0.2-next.17 → 1.0.2-next.19

package/README.md

@@ -28,6 +28,7 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
   - [vault.createBankToken()](#vaultcreatebanktokenoptions)
   - [vault.reset()](#vaultreset)
   - [vault.destroy()](#vaultdestroy)
+  - [vault.debugState()](#vaultdebugstate)
   - [OzElement events](#ozelement-events)
 - [React API](#react-api)
   - [OzElements provider](#ozelements-provider)
@@ -41,6 +42,7 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
   - [Custom fonts](#custom-fonts)
 - [Billing details](#billing-details)
 - [Error handling](#error-handling)
+- [Debug mode](#debug-mode)
 - [Server utilities](#server-utilities)
   - [Ozura class](#ozura-class)
   - [Route handler factories](#route-handler-factories)
@@ -361,6 +363,7 @@ Mounts the hidden tokenizer iframe and fetches the wax key concurrently. Both ha
 | `onWaxRefresh` | `() => void` | — | Called when the SDK silently re-mints an expired wax key mid-tokenization. |
 | `onReady` | `() => void` | — | Called once when the tokenizer iframe has loaded and is ready. Use in vanilla JS to re-check submit-button readiness when the tokenizer becomes ready after all element iframes have already fired. In React, `useOzElements().ready` handles this automatically. |
 | `maxTokenizeCalls` | `number` | — | Maximum successful `createToken` calls per wax key before the key is considered consumed. Default: `3`. Must match `maxTokenizeCalls` in your server-side `mintWaxKey` call. |
+| `debug` | `boolean` | — | Enables structured `[OzVault]`-prefixed `console.log` output at every lifecycle event. Safe to use in production — no sensitive data is ever logged. Default: `false`. See [Debug mode](#debug-mode) for details. |
 
 Throws `OzError` if `fetchWaxKey` rejects, returns an empty string, or returns a non-string value.
 
@@ -580,6 +583,37 @@ try {
 
 ---
 
+### vault.debugState()
+
+```ts
+vault.debugState(): Record<string, unknown>
+```
+
+Returns a structured snapshot of the vault's internal state. Always available regardless of whether `debug: true` is set. Useful for attaching to support tickets or dumping on error.
+
+```ts
+console.log(vault.debugState());
+// {
+//   vaultId: 'vault_abc12...',
+//   isReady: true,
+//   tokenizing: null,
+//   destroyed: false,
+//   waxKeyPresent: true,
+//   tokenizeSuccessCount: 1,
+//   maxTokenizeCalls: 3,
+//   resetCount: 0,
+//   elements: ['cardNumber', 'expirationDate', 'cvv'],
+//   bankElements: [],
+//   completionState: { 'a1b2c3d4': true, 'e5f6a7b8': true, '...' : false },
+//   pendingTokenizations: 0,
+//   pendingBankTokenizations: 0,
+// }
+```
+
+No sensitive data is returned: wax keys, tokens, CVC sessions, and billing fields are never included.
+
+---
+
 ### OzElement events
 
 ```ts
@@ -940,6 +974,78 @@ const display = normalizeCardSaleError(err.message); // cardSale API errors
 
 ---
 
+## Debug mode
+
+Pass `debug: true` in `VaultOptions` (or as a prop on `<OzElements>`) to activate structured console logging at every SDK lifecycle event.
+
+```ts
+const vault = await OzVault.create({
+  pubKey: 'pk_live_...',
+  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  debug: true,   // enables [OzVault] console.log output
+});
+```
+
+```tsx
+// React
+<OzElements pubKey="pk_live_..." fetchWaxKey={...} debug>
+  ...
+</OzElements>
+```
+
+Each log entry is a `[OzVault] <message>` prefixed `console.log` call. Events logged include:
+
+| Event | When it fires |
+|---|---|
+| `vault created` | Constructor completes |
+| `wax key received` | `fetchWaxKey` resolves |
+| `mounting tokenizer iframe` | Tokenizer iframe creation begins |
+| `tokenizer iframe ready` | Tokenizer iframe handshake complete |
+| `element iframe ready` | Each card/bank input iframe loads |
+| `field changed` | Per-field `change` event (empty/complete/valid/auto-advance state) |
+| `auto-advance` | Focus moves automatically between card fields |
+| `createToken() called` | Entry to `createToken()` |
+| `OZ_TOKENIZE sent` | Tokenize request dispatched to iframe |
+| `token received` | Token result returned (with elapsed ms) |
+| `token error` | Vault or network error during tokenize |
+| `proactive wax key refresh triggered` | Budget exhausted; refresh starting |
+| `wax key refresh started/succeeded/failed` | Refresh lifecycle |
+| `tab hidden` / `tab visible` | `visibilitychange` events |
+| `reset() called` | `vault.reset()` entry |
+| `destroy() called` | `vault.destroy()` entry |
+
+**Security:** No sensitive data is ever logged. Wax keys, tokens, CVC sessions, and billing fields appear only as boolean presence flags (`waxKeyPresent: true`). Frame IDs and request IDs are truncated.
+
+### vault.debugState()
+
+`vault.debugState()` is always available — regardless of whether `debug: true` was set — and returns a one-time snapshot for attaching to bug reports:
+
+```ts
+console.log(vault.debugState());
+```
+
+Sample output:
+
+```json
+{
+  "vaultId": "vault_abc12...",
+  "isReady": true,
+  "tokenizing": null,
+  "destroyed": false,
+  "waxKeyPresent": true,
+  "tokenizeSuccessCount": 1,
+  "maxTokenizeCalls": 3,
+  "resetCount": 0,
+  "elements": ["cardNumber", "expirationDate", "cvv"],
+  "bankElements": [],
+  "completionState": { "a1b2c3d4": true, "e5f6a7b8": true, "c9d0e1f2": false },
+  "pendingTokenizations": 0,
+  "pendingBankTokenizations": 0
+}
+```
+
+---
+
 ## Server utilities
 
 > 📖 [Server SDK guide](https://docs.ozura.com/sdks/elements/server) — `Ozura` class methods, route handler factories, `getClientIp`, error types, and rate limits.

package/dist/oz-elements.esm.js

@@ -929,7 +929,7 @@ class OzVault {
      * @internal
      */
     constructor(options, waxKey, tokenizationSessionId) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         this.elements = new Map();
         this.elementsByType = new Map();
         this.bankElementsByType = new Map();
@@ -964,13 +964,14 @@ class OzVault {
         this.resolvedAppearance = resolveAppearance(options.appearance);
         this.vaultId = `vault-${uuid()}`;
         this._maxTokenizeCalls = (_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3;
+        this._debug = (_c = options.debug) !== null && _c !== void 0 ? _c : false;
         this.boundHandleMessage = this.handleMessage.bind(this);
         window.addEventListener('message', this.boundHandleMessage);
         this.boundHandleVisibility = this.handleVisibilityChange.bind(this);
         document.addEventListener('visibilitychange', this.boundHandleVisibility);
         this.mountTokenizerFrame();
         if (options.onLoadError) {
-            const timeout = (_c = options.loadTimeoutMs) !== null && _c !== void 0 ? _c : 10000;
+            const timeout = (_d = options.loadTimeoutMs) !== null && _d !== void 0 ? _d : 10000;
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
@@ -980,6 +981,7 @@ class OzVault {
         }
         this._onWaxRefresh = options.onWaxRefresh;
         this._onReady = options.onReady;
+        this.log('vault created', { vaultId: this.vaultId, frameBaseUrl: this.frameBaseUrl, maxTokenizeCalls: this._maxTokenizeCalls });
     }
     /**
      * Creates and returns a ready `OzVault` instance.
@@ -1049,6 +1051,7 @@ class OzVault {
         if (vault.tokenizerReady) {
             vault.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey });
         }
+        vault.log('wax key received — vault ready');
         return vault;
     }
     /**
@@ -1190,6 +1193,7 @@ class OzVault {
         const readyBankElements = [accountEl, routingEl];
         this._tokenizing = 'bank';
         const requestId = `req-${uuid()}`;
+        this.log('createBankToken() called');
         return new Promise((resolve, reject) => {
             const resetCountAtStart = this._resetCount;
             const cleanup = () => {
@@ -1206,6 +1210,7 @@ class OzVault {
             });
             try {
                 const bankChannels = readyBankElements.map(() => new MessageChannel());
+                const bankTokenizeStartMs = Date.now();
                 this.sendToTokenizer({
                     type: 'OZ_BANK_TOKENIZE',
                     requestId,
@@ -1216,6 +1221,7 @@ class OzVault {
                     lastName: options.lastName.trim(),
                     fieldCount: readyBankElements.length,
                 }, bankChannels.map(ch => ch.port1));
+                this.log('OZ_BANK_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyBankElements.length });
                 readyBankElements.forEach((el, i) => el.beginCollect(requestId, bankChannels[i].port2));
                 const bankTimeoutId = setTimeout(() => {
                     if (this.bankTokenizeResolvers.has(requestId)) {
@@ -1226,8 +1232,10 @@ class OzVault {
                     }
                 }, 30000);
                 const bankPendingEntry = this.bankTokenizeResolvers.get(requestId);
-                if (bankPendingEntry)
+                if (bankPendingEntry) {
                     bankPendingEntry.timeoutId = bankTimeoutId;
+                    bankPendingEntry.tokenizeStartMs = bankTokenizeStartMs;
+                }
             }
             catch (err) {
                 this.bankTokenizeResolvers.delete(requestId);
@@ -1298,6 +1306,7 @@ class OzVault {
         }
         this._tokenizing = 'card';
         const requestId = `req-${uuid()}`;
+        this.log('createToken() called');
         return new Promise((resolve, reject) => {
             // Capture the reset generation so cleanup() only zeros _tokenizing when it
             // still belongs to this invocation — not a newer one that started after a reset.
@@ -1318,6 +1327,7 @@ class OzVault {
             try {
                 // Tell tokenizer frame to expect N field values, then tokenize
                 const cardChannels = readyElements.map(() => new MessageChannel());
+                const tokenizeStartMs = Date.now();
                 this.sendToTokenizer({
                     type: 'OZ_TOKENIZE',
                     requestId,
@@ -1328,6 +1338,11 @@ class OzVault {
                     lastName,
                     fieldCount: readyElements.length,
                 }, cardChannels.map(ch => ch.port1));
+                this.log('OZ_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyElements.length });
+                // Store start time for elapsed-ms logging on result
+                const cardEntry = this.tokenizeResolvers.get(requestId);
+                if (cardEntry)
+                    cardEntry.tokenizeStartMs = tokenizeStartMs;
                 // Tell each ready element frame to send its raw value to the tokenizer
                 readyElements.forEach((el, i) => el.beginCollect(requestId, cardChannels[i].port2));
                 const cardTimeoutId = setTimeout(() => {
@@ -1374,6 +1389,8 @@ class OzVault {
     reset() {
         if (this._destroyed)
             return;
+        const cancelling = Boolean(this._tokenizing);
+        this.log('reset() called', { tokenizing: this._tokenizing, cancelling });
         if (this._tokenizing) {
             this._tokenizing = null;
             this._resetCount++;
@@ -1414,6 +1431,7 @@ class OzVault {
         if (this._destroyed)
             return;
         this._destroyed = true;
+        this.log('destroy() called');
         window.removeEventListener('message', this.boundHandleMessage);
         document.removeEventListener('visibilitychange', this.boundHandleVisibility);
         if (this._pendingMount) {
@@ -1468,13 +1486,17 @@ class OzVault {
         const REFRESH_THRESHOLD_MS = 20 * 60 * 1000; // 20 minutes
         if (document.hidden) {
             this._hiddenAt = Date.now();
+            this.log('tab hidden');
         }
         else {
-            if (this._hiddenAt !== null &&
-                Date.now() - this._hiddenAt >= REFRESH_THRESHOLD_MS &&
-                this._storedFetchWaxKey &&
+            const hiddenMs = this._hiddenAt !== null ? Date.now() - this._hiddenAt : 0;
+            const willRefresh = (this._hiddenAt !== null &&
+                hiddenMs >= REFRESH_THRESHOLD_MS &&
+                Boolean(this._storedFetchWaxKey) &&
                 !this._tokenizing &&
-                !this._waxRefreshing) {
+                !this._waxRefreshing);
+            this.log('tab visible', { hiddenMs, willRefresh });
+            if (willRefresh) {
                 this.refreshWaxKey().catch((err) => {
                     // Proactive refresh failure is non-fatal — the reactive path on the
                     // next createToken() call will handle it, including the auth retry.
@@ -1484,6 +1506,56 @@ class OzVault {
             this._hiddenAt = null;
         }
     }
+    // ─── Debug ───────────────────────────────────────────────────────────────
+    /**
+     * Emits a `[OzVault]`-prefixed entry to `console.log`. No-op when `debug` is
+     * not set. Never called with sensitive values — callers use presence flags only.
+     */
+    log(message, data) {
+        if (!this._debug)
+            return;
+        if (data !== undefined) {
+            console.log(`[OzVault] ${message}`, data);
+        }
+        else {
+            console.log(`[OzVault] ${message}`);
+        }
+    }
+    /**
+     * Returns a plain-object snapshot of the vault's current internal state.
+     * Safe to attach to bug reports — no wax keys, tokens, or billing data included.
+     *
+     * Available on all vault instances regardless of whether `debug` was enabled.
+     *
+     * @example
+     * console.log(vault.debugState());
+     * // {
+     * //   vaultId: 'vault-abc123',
+     * //   isReady: true,
+     * //   tokenizing: null,
+     * //   destroyed: false,
+     * //   waxKeyPresent: true,
+     * //   elements: ['cardNumber', 'expirationDate', 'cvv'],
+     * //   ...
+     * // }
+     */
+    debugState() {
+        return {
+            vaultId: this.vaultId,
+            isReady: this.tokenizerReady,
+            tokenizing: this._tokenizing,
+            destroyed: this._destroyed,
+            waxKeyPresent: Boolean(this.waxKey),
+            tokenizeSuccessCount: this._tokenizeSuccessCount,
+            maxTokenizeCalls: this._maxTokenizeCalls,
+            resetCount: this._resetCount,
+            elements: [...this.elementsByType.keys()],
+            bankElements: [...this.bankElementsByType.keys()],
+            completionState: Object.fromEntries([...this.completionState.entries()].map(([id, v]) => [id.slice(0, 8), v])),
+            pendingTokenizations: this.tokenizeResolvers.size,
+            pendingBankTokenizations: this.bankTokenizeResolvers.size,
+        };
+    }
     mountTokenizerFrame() {
         const mount = () => {
             this._pendingMount = null;
@@ -1495,6 +1567,7 @@ class OzVault {
             iframe.src = `${this.frameBaseUrl}/frame/tokenizer-frame.html#vaultId=${encodeURIComponent(this.vaultId)}${parentOrigin ? `&parentOrigin=${encodeURIComponent(parentOrigin)}` : ''}`;
             document.body.appendChild(iframe);
             this.tokenizerFrame = iframe;
+            this.log('mounting tokenizer iframe');
         };
         if (document.readyState === 'loading') {
             this._pendingMount = mount;
@@ -1535,6 +1608,7 @@ class OzVault {
                             `SDK expects v${PROTOCOL_VERSION}, frame reported v${typeof msg.__ozVersion === 'number' ? msg.__ozVersion : '(none)'}. ` +
                             'Deploy the matching frame assets to elements.ozura.com and purge the Azure CDN cache.');
                     }
+                    this.log('element iframe ready', { type: el.type, frameIdPrefix: frameId.slice(0, 8) });
                 }
                 // Intercept OZ_CHANGE before forwarding — handle auto-advance and CVV sync
                 if (msg.type === 'OZ_CHANGE') {
@@ -1558,6 +1632,7 @@ class OzVault {
         // Require valid too — avoids advancing at 13 digits for unknown-brand cards
         // where isComplete() fires before the user has finished typing.
         const justCompleted = complete && valid && !wasComplete;
+        this.log('field changed', { type: el.type, complete, valid, justCompleted });
         // Sync CVV length when card brand changes
         if (el.type === 'cardNumber') {
             const brand = msg.cardBrand;
@@ -1569,15 +1644,17 @@ class OzVault {
         // Auto-advance focus on completion
         if (justCompleted) {
             if (el.type === 'cardNumber') {
+                this.log('auto-advance', { from: 'cardNumber', to: 'expirationDate' });
                 (_b = this.elementsByType.get('expirationDate')) === null || _b === void 0 ? void 0 : _b.focus();
             }
             else if (el.type === 'expirationDate') {
+                this.log('auto-advance', { from: 'expirationDate', to: 'cvv' });
                 (_c = this.elementsByType.get('cvv')) === null || _c === void 0 ? void 0 : _c.focus();
             }
         }
     }
     handleTokenizerMessage(msg) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         switch (msg.type) {
             case 'OZ_FRAME_READY':
                 if (msg.__ozVersion !== PROTOCOL_VERSION) {
@@ -1597,6 +1674,7 @@ class OzVault {
                 // sent again from create() once the key is available.
                 this.sendToTokenizer(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})));
                 (_c = this._onReady) === null || _c === void 0 ? void 0 : _c.call(this);
+                this.log('tokenizer iframe ready', { protocolVersion: (_d = msg.__ozVersion) !== null && _d !== void 0 ? _d : null });
                 break;
             case 'OZ_TOKEN_RESULT': {
                 if (typeof msg.requestId !== 'string' || !msg.requestId) {
@@ -1621,11 +1699,18 @@ class OzVault {
                     }
                     pending.resolve(Object.assign(Object.assign({ token,
                         cvcSession }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
+                    this.log('token received', {
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        cvcSessionPresent: true,
+                        cardMetadataPresent: Boolean(card),
+                    });
                     // Increment the per-key success counter and proactively refresh once
                     // the budget is exhausted so the next createToken() call uses a fresh
                     // key without waiting for a vault rejection.
                     this._tokenizeSuccessCount++;
                     if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.log('proactive wax key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
                         this.refreshWaxKey().catch((err) => {
                             console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
                         });
@@ -1645,9 +1730,11 @@ class OzVault {
                     this.tokenizeResolvers.delete(msg.requestId);
                     if (pending.timeoutId != null)
                         clearTimeout(pending.timeoutId);
+                    const willRefresh = this.isRefreshableAuthError(errorCode, raw) && !pending.retried && Boolean(this._storedFetchWaxKey);
+                    this.log('token error', { errorCode, willRefresh });
                     // Auto-refresh: if the wax key expired or was consumed and we haven't
                     // already retried for this request, transparently re-mint and retry.
-                    if (this.isRefreshableAuthError(errorCode, raw) && !pending.retried && this._storedFetchWaxKey) {
+                    if (willRefresh) {
                         const resetCountAtRetry = this._resetCount;
                         this.refreshWaxKey().then(() => {
                             if (this._destroyed) {
@@ -1775,9 +1862,15 @@ class OzVault {
                     }
                     const bank = isBankAccountMetadata(msg.bank) ? msg.bank : undefined;
                     pending.resolve(Object.assign({ token }, (bank ? { bank } : {})));
+                    this.log('bank token received', {
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        bankMetadataPresent: Boolean(bank),
+                    });
                     // Same proactive refresh logic as card tokenization.
                     this._tokenizeSuccessCount++;
                     if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.log('proactive wax key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
                         this.refreshWaxKey().catch((err) => {
                             console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
                         });
@@ -1833,6 +1926,7 @@ class OzVault {
         }
         const newSessionId = uuid();
         (_a = this._onWaxRefresh) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.log('wax key refresh started');
         this._waxRefreshing = this._storedFetchWaxKey(newSessionId)
             .then(newWaxKey => {
             if (typeof newWaxKey !== 'string' || !newWaxKey.trim()) {
@@ -1846,6 +1940,11 @@ class OzVault {
             if (!this._destroyed && this.tokenizerReady) {
                 this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey: newWaxKey });
             }
+            this.log('wax key refresh succeeded');
+        })
+            .catch((err) => {
+            this.log('wax key refresh failed', { error: err instanceof Error ? err.message : String(err) });
+            throw err;
         })
             .finally(() => {
             this._waxRefreshing = null;