@ozura/elements 1.0.2 → 1.1.0-next.22

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Ozura 
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Ozura 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -18,7 +18,7 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
 - [Quick start — React](#quick-start--react)
 - [Quick start — Vanilla JS](#quick-start--vanilla-js)
 - [Server setup](#server-setup)
-  - [Wax key endpoint](#wax-key-endpoint)
+  - [Session endpoint](#session-endpoint)
   - [Card sale endpoint](#card-sale-endpoint)
 - [Vanilla JS API](#vanilla-js-api)
   - [OzVault.create()](#ozvaultcreate)
@@ -26,7 +26,9 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
   - [vault.createToken()](#vaultcreatetokenoptions)
   - [vault.createBankElement()](#vaultcreatebankelement)
   - [vault.createBankToken()](#vaultcreatebanktokenoptions)
+  - [vault.reset()](#vaultreset)
   - [vault.destroy()](#vaultdestroy)
+  - [vault.debugState()](#vaultdebugstate)
   - [OzElement events](#ozelement-events)
 - [React API](#react-api)
   - [OzElements provider](#ozelements-provider)
@@ -40,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)
@@ -78,7 +81,7 @@ Merchant page
   └── [visible] element-frame.html    ← CVV           ─┘
 ```
 
-1. `OzVault.create()` mounts a hidden tokenizer iframe and fetches a short-lived **wax key** from your server.
+1. `OzVault.create()` mounts a hidden tokenizer iframe and fetches a short-lived **session key** from your server.
 2. Calling `vault.createElement()` mounts a visible input iframe for each field.
 3. `vault.createToken()` opens a direct `MessageChannel` between each element iframe and the tokenizer iframe. Raw values travel over those ports — they never pass through your JavaScript.
 4. The tokenizer POSTs directly to the vault API over HTTPS and returns a token to your page.
@@ -92,7 +95,7 @@ Your server only ever sees a token, never card data.
 | Credential | Format | Where it lives | Required for |
 |---|---|---|---|
 | **Vault pub key** | `pk_live_…` or `pk_prod_…` | Frontend env var (safe to expose) | All integrations |
-| **Vault API key** | `key_…` | Server env var — **never in the browser** | Minting wax keys (all integrations) |
+| **Vault API key** | `key_…` | Server env var — **never in the browser** | Creating sessions (all integrations) |
 | **Pay API key** | `ak_…` | Server env var only | OzuraPay merchants (card charging) |
 | **Merchant ID** | `ozu_…` | Server env var only | OzuraPay merchants (card charging) |
 
@@ -124,13 +127,13 @@ npm install react react-dom   # if not already installed
 
 ```tsx
 // 1. Wrap your checkout in <OzElements>
-import { OzElements, OzCard, useOzElements, createFetchWaxKey } from '@ozura/elements/react';
+import { OzElements, OzCard, useOzElements } from '@ozura/elements/react';
 
 function CheckoutPage() {
   return (
     <OzElements
       pubKey="pk_live_..."
-      fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+      sessionUrl="/api/oz-session"
     >
       <CheckoutForm />
     </OzElements>
@@ -139,25 +142,30 @@ function CheckoutPage() {
 
 // 2. Collect card data and tokenize
 function CheckoutForm() {
-  const { createToken, ready } = useOzElements();
+  const { createToken, reset, ready } = useOzElements();
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    const { token, cvcSession, billing } = await createToken({
-      billing: {
-        firstName: 'Jane',
-        lastName:  'Smith',
-        email:     'jane@example.com',
-        address: { line1: '123 Main St', city: 'Austin', state: 'TX', zip: '78701', country: 'US' },
-      },
-    });
-
-    // Send token to your server
-    await fetch('/api/charge', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ token, cvcSession, billing }),
-    });
+    try {
+      const { token, cvcSession, billing } = await createToken({
+        billing: {
+          firstName: 'Jane',
+          lastName:  'Smith',
+          email:     'jane@example.com',
+          address: { line1: '123 Main St', city: 'Austin', state: 'TX', zip: '78701', country: 'US' },
+        },
+      });
+
+      // Send token to your server
+      await fetch('/api/charge', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token, cvcSession, billing }),
+      });
+    } catch (err) {
+      reset();               // clear fields so the customer can re-enter
+      console.error(err);
+    }
   };
 
   return (
@@ -176,7 +184,7 @@ function CheckoutForm() {
 > 📖 [Card elements guide](https://docs.ozura.com/sdks/elements/card-elements) — full end-to-end example, field events, submit-button gating, and auto-advance behaviour.
 
 ```ts
-import { OzVault, createFetchWaxKey } from '@ozura/elements';
+import { OzVault } from '@ozura/elements';
 
 // Declare state BEFORE OzVault.create(). The onReady callback fires when the
 // tokenizer iframe loads — this can happen before create() resolves because the
@@ -191,7 +199,7 @@ function checkReady() {
 
 const vault = await OzVault.create({
   pubKey: 'pk_live_...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  sessionUrl: '/api/oz-session',
   onReady: () => { tokenizerIsReady = true; checkReady(); },   // tokenizer iframe loaded
 });
 
@@ -208,10 +216,15 @@ cvvEl.mount('#cvv');
 });
 
 async function pay() {
-  const { token, cvcSession, card } = await vault.createToken({
-    billing: { firstName: 'Jane', lastName: 'Smith' },
-  });
-  // POST { token, cvcSession } to your server
+  try {
+    const { token, cvcSession, card } = await vault.createToken({
+      billing: { firstName: 'Jane', lastName: 'Smith' },
+    });
+    // POST { token, cvcSession } to your server
+  } catch (err) {
+    vault.reset();           // clear fields; let customer re-enter
+    console.error(err);
+  }
 }
 
 // Clean up when done
@@ -224,50 +237,43 @@ vault.destroy();
 
 ## Server setup
 
-> 📖 [Server SDK guide](https://docs.ozura.com/sdks/elements/server) — wax key minting, card sale handler factories, IP extraction, and manual implementation patterns.
+> 📖 [Server SDK guide](https://docs.ozura.com/sdks/elements/server) — session creation, card sale handler factories, IP extraction, and manual implementation patterns.
 
-### Wax key endpoint
+### Session endpoint
 
-The SDK calls your `fetchWaxKey` function with a `tokenizationSessionId` UUID. Your backend must exchange it for a wax key from the vault.
+The SDK calls your session endpoint whenever it needs to start or refresh a payment session. Your backend creates a short-lived session key from the vault using your vault API key — the key never touches the browser.
 
 **Next.js App Router (recommended)**
 
 ```ts
-// app/api/mint-wax/route.ts
-import { Ozura, createMintWaxHandler } from '@ozura/elements/server';
+// app/api/oz-session/route.ts
+import { Ozura, createSessionHandler } from '@ozura/elements/server';
 
-const ozura = new Ozura({
-  merchantId: process.env.MERCHANT_ID!,
-  apiKey:     process.env.MERCHANT_API_KEY!,
-  vaultKey:   process.env.VAULT_API_KEY!,
-});
+const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
 
-export const POST = createMintWaxHandler(ozura);
+export const POST = createSessionHandler(ozura);
 ```
 
 **Express**
 
 ```ts
 import express from 'express';
-import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
+import { Ozura, createSessionMiddleware } from '@ozura/elements/server';
 
-const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
 const app = express();
 
 app.use(express.json());
-app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
+app.post('/api/oz-session', createSessionMiddleware(ozura));
 ```
 
-**Manual implementation**
+**Manual implementation** (for custom logic or auth checks)
 
 ```ts
-// POST /api/mint-wax
+// POST /api/oz-session
 const { sessionId } = await req.json();
-const { waxKey } = await ozura.mintWaxKey({
-  tokenizationSessionId: sessionId,
-  maxTokenizeCalls: 3,  // vault enforces this limit; must match VaultOptions.maxTokenizeCalls on the client
-});
-return Response.json({ waxKey });
+const { sessionKey } = await ozura.createSession({ sessionId });
+return Response.json({ sessionKey });
 ```
 
 ### Card sale endpoint
@@ -336,26 +342,29 @@ const result = await ozura.cardSale({
 const vault = await OzVault.create(options: VaultOptions): Promise<OzVault>
 ```
 
-Mounts the hidden tokenizer iframe and fetches the wax key concurrently. Both happen in parallel — by the time `create()` resolves, the iframe may already be ready.
+Mounts the hidden tokenizer iframe and fetches a session key concurrently. Both happen in parallel — by the time `create()` resolves, the iframe may already be ready.
 
 | Option | Type | Required | Description |
 |---|---|---|---|
 | `pubKey` | `string` | ✓ | Your public key from the Ozura admin. |
-| `fetchWaxKey` | `(sessionId: string) => Promise<string>` | ✓ | Called with the session ID; must return a wax key string from your server. Use `createFetchWaxKey('/api/mint-wax')` for the common case. |
+| `sessionUrl` | `string` | ✓ ¹ | URL of your session endpoint. The simplest option — pass the path and the SDK handles everything. |
+| `getSessionKey` | `(sessionId: string) => Promise<string>` | ✓ ¹ | Custom async callback for obtaining the session key. Use when you need custom headers or auth logic. |
+| `fetchWaxKey` | `(sessionId: string) => Promise<string>` | ✓ ¹ | **Deprecated.** Use `sessionUrl` or `getSessionKey` instead. |
 | `frameBaseUrl` | `string` | — | Base URL for iframe assets. Defaults to production CDN. Override for local dev (see [Local development](#local-development)). |
 | `fonts` | `FontSource[]` | — | Custom fonts to inject into all element iframes. |
 | `appearance` | `Appearance` | — | Global theme and variable overrides. |
 | `loadTimeoutMs` | `number` | — | Tokenizer iframe load timeout in ms. Default: `10000`. Only takes effect when `onLoadError` is also provided. |
 | `onLoadError` | `() => void` | — | Called if the tokenizer iframe fails to load within `loadTimeoutMs`. |
-| `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. |
+| `onSessionRefresh` | `() => void` | — | Called when the SDK silently refreshes the session mid-tokenization (key expired or consumed). |
+| `onReady` | `() => void` | — | Called once when the tokenizer iframe has loaded and is ready. Use in vanilla JS to re-check submit-button readiness. In React, `useOzElements().ready` handles this automatically. |
+| `sessionLimit` | `number` | — | Card submissions allowed per session before the SDK refreshes automatically. Default: `3`. Must match `sessionLimit` in your server-side `createSession` 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.
+¹ Exactly one of `sessionUrl`, `getSessionKey`, or `fetchWaxKey` is required.
 
-> **`createFetchWaxKey` retry behavior:** The built-in helper enforces a **10-second per-attempt timeout** and retries **once after 750 ms on pure network failures** (connection refused, DNS failure, offline). HTTP 4xx/5xx errors are never retried — they signal endpoint misconfiguration or invalid credentials and require developer action. Errors are thrown as `OzError` instances so you can inspect `err.errorCode` and `err.retryable`.
+Throws `OzError` if the session fetch rejects, returns an empty string, or returns a non-string value.
 
-> **Re-export identity:** `createFetchWaxKey` is exported from both `@ozura/elements` and `@ozura/elements/react`. They are identical — the same function. Use whichever matches your import context.
+> **`sessionUrl` retry behavior:** The SDK enforces a **10-second per-attempt timeout** and retries **once after 750 ms on pure network failures** (connection refused, DNS failure, offline). HTTP 4xx/5xx errors are never retried — they signal endpoint misconfiguration or invalid credentials and require developer action. Errors are thrown as `OzError` instances so you can inspect `err.errorCode`.
 
 ---
 
@@ -456,7 +465,7 @@ Throws `OzError` if:
 vault.tokenizeCount: number  // read-only getter
 ```
 
-Returns the number of successful `createToken()` / `createBankToken()` calls made against the current wax key. Resets to `0` each time the wax key is refreshed (proactively or reactively). Use this in vanilla JS to display "attempts remaining" feedback or gate the submit button:
+Returns the number of successful `createToken()` / `createBankToken()` calls made in the current session. Resets to `0` each time the session is refreshed (proactively or reactively). Use this in vanilla JS to display "attempts remaining" feedback or gate the submit button:
 
 ```ts
 const MAX = 3; // matches maxTokenizeCalls
@@ -541,6 +550,65 @@ useEffect(() => {
 
 ---
 
+### vault.reset()
+
+```ts
+vault.reset(): void
+```
+
+Clears all mounted card and bank element fields without destroying the vault, refreshing the session, or resetting the tokenization budget. Call this after a declined payment to let the customer re-enter their card details on the same checkout screen.
+
+The session key, its remaining budget, and all iframes are fully preserved — no network calls are made.
+
+**Session model:** One session covers the full checkout. The default `sessionLimit: 3` is enough for two declines and a final attempt. Use `vault.reset()` between declines — not `vault.destroy()` + recreate, which would waste the remaining budget and cause iframe flicker.
+
+```ts
+try {
+  const { token, cvcSession } = await vault.createToken({ billing });
+  await fetch('/api/charge', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token, cvcSession }),
+  });
+} catch (err) {
+  vault.reset();                   // clear fields; let customer re-enter
+  showError(err instanceof OzError ? err.message : 'Payment failed.');
+}
+```
+
+---
+
+### 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
@@ -576,11 +644,11 @@ Auto-advance is built in: the vault automatically moves focus from card number
 ### OzElements provider
 
 ```tsx
-import { OzElements, createFetchWaxKey } from '@ozura/elements/react';
+import { OzElements } from '@ozura/elements/react';
 
 <OzElements
   pubKey="pk_live_..."
-  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+  sessionUrl="/api/oz-session"
   appearance={{ theme: 'flat', variables: { colorPrimary: '#6366f1' } }}
   onLoadError={() => setPaymentUnavailable(true)}
 >
@@ -590,9 +658,9 @@ import { OzElements, createFetchWaxKey } from '@ozura/elements/react';
 
 All `VaultOptions` are accepted as props. The provider creates a single `OzVault` instance and destroys it on unmount.
 
-> **Prop changes and vault lifecycle:** Changing `pubKey`, `frameBaseUrl`, `loadTimeoutMs`, `appearance`, `fonts`, or `maxTokenizeCalls` destroys the current vault and creates a new one — all field iframes will remount. Changing `fetchWaxKey`, `onLoadError`, `onWaxRefresh`, or `onReady` updates the callback in place via refs without recreating the vault.
+> **Prop changes and vault lifecycle:** Changing `pubKey`, `sessionUrl`, `frameBaseUrl`, `loadTimeoutMs`, `appearance`, `fonts`, or `sessionLimit` destroys the current vault and creates a new one — all field iframes will remount. Changing `getSessionKey`, `fetchWaxKey`, `onLoadError`, `onSessionRefresh`, or `onReady` updates the callback in place via refs without recreating the vault.
 
-> **One card form per provider:** A vault holds one element per field type (`cardNumber`, `expiry`, `cvv`, etc.). Rendering two `<OzCard>` components under the same `<OzElements>` provider will cause the second to silently replace the first's iframes, breaking the first form. If you genuinely need two independent card forms on the same page, wrap each in its own `<OzElements>` provider with separate `pubKey` / `fetchWaxKey` configurations.
+> **One card form per provider:** A vault holds one element per field type (`cardNumber`, `expiry`, `cvv`, etc.). Rendering two `<OzCard>` components under the same `<OzElements>` provider will cause the second to silently replace the first's iframes, breaking the first form. If you genuinely need two independent card forms on the same page, wrap each in its own `<OzElements>` provider with separate `pubKey` / `sessionUrl` configurations.
 
 ---
 
@@ -700,7 +768,7 @@ import { OzBankAccountNumber, OzBankRoutingNumber } from '@ozura/elements/react'
 ### useOzElements()
 
 ```ts
-const { createToken, createBankToken, ready, initError, tokenizeCount } = useOzElements();
+const { createToken, createBankToken, reset, ready, initError, tokenizeCount } = useOzElements();
 ```
 
 Must be called from inside an `<OzElements>` provider tree.
@@ -709,9 +777,10 @@ Must be called from inside an `<OzElements>` provider tree.
 |---|---|---|
 | `createToken` | `(options?: TokenizeOptions) => Promise<TokenResponse>` | Tokenize mounted card elements. |
 | `createBankToken` | `(options: BankTokenizeOptions) => Promise<BankTokenResponse>` | Tokenize mounted bank elements. |
+| `reset` | `() => void` | Clear all mounted element fields without destroying the vault or refreshing the session. Call after a declined payment so the customer can re-enter their details. |
 | `ready` | `boolean` | `true` when the tokenizer **and** all mounted element iframes are ready. Gate your submit button on this. See note below. |
-| `initError` | `Error \| null` | Non-null if `OzVault.create()` failed (e.g. `fetchWaxKey` threw). Render a fallback UI. |
-| `tokenizeCount` | `number` | Number of successful tokenizations since the last wax key was minted. Resets on wax refresh or provider re-init. Useful for tracking calls against `maxTokenizeCalls`. |
+| `initError` | `Error \| null` | Non-null if `OzVault.create()` failed (e.g. session endpoint unreachable). Render a fallback UI. |
+| `tokenizeCount` | `number` | Number of successful tokenizations in the current session. Resets on session refresh or provider re-init. Useful for tracking calls against `sessionLimit`. |
 
 > **`ready` vs `vault.isReady`:** `ready` from `useOzElements()` is a composite — it combines `vault.isReady` (tokenizer loaded) with element readiness (all mounted input iframes loaded). `vault.isReady` alone is insufficient for gating a submit button. Always use `ready` from `useOzElements()` in React.
 
@@ -764,7 +833,7 @@ Apply a preset theme and/or variable overrides to all elements at once:
 // OzVault.create
 const vault = await OzVault.create({
   pubKey: '...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  sessionUrl: '/api/oz-session',
   appearance: {
     theme: 'flat',                    // 'default' | 'night' | 'flat'
     variables: {
@@ -784,7 +853,7 @@ const vault = await OzVault.create({
 });
 
 // React provider
-<OzElements pubKey="..." fetchWaxKey={...} appearance={{ theme: 'night' }}>
+<OzElements pubKey="..." sessionUrl="..." appearance={{ theme: 'night' }}>
 ```
 
 Per-element `style` takes precedence over `appearance` variables.
@@ -847,7 +916,7 @@ Billing is validated and normalized by both `vault.createToken()` and the server
 
 ## Error handling
 
-> 📖 [Error handling guide](https://docs.ozura.com/sdks/elements/error-handling) — `OzError` fields, every `errorCode` value, retry guidance, and wax key expiry behaviour.
+> 📖 [Error handling guide](https://docs.ozura.com/sdks/elements/error-handling) — `OzError` fields, every `errorCode` value, retry guidance, and session expiry behaviour.
 
 All SDK errors are instances of `OzError`:
 
@@ -885,7 +954,7 @@ try {
 | `raw` | `string` | Raw error string from the vault API, if available. |
 | `retryable` | `boolean` | `true` for `network`, `timeout`, `server`. `false` for `auth`, `validation`, `config`, `unknown`. |
 
-> **Wax key expiry is handled automatically.** When a wax key expires or is consumed between initialization and the user clicking Pay, the SDK silently re-mints a fresh key and retries the tokenization once. You will only receive an `auth` error if the re-mint itself fails — for example, if your `/api/mint-wax` backend endpoint is unreachable. A healthy `auth` error in production means your mint endpoint needs attention, not that the user's card is bad.
+> **Session expiry is handled automatically.** When a session expires or is consumed between initialization and the user clicking Pay, the SDK silently fetches a fresh session and retries the tokenization once. You will only receive an `auth` error if the session refresh itself fails — for example, if your `/api/oz-session` backend endpoint is unreachable. A healthy `auth` error in production means your session endpoint needs attention, not that the user's card is bad.
 
 **Error normalisation helpers** (for displaying errors from `cardSale` to users):
 
@@ -900,6 +969,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_...',
+  sessionUrl: '/api/oz-session',
+  debug: true,   // enables [OzVault] console.log output
+});
+```
+
+```tsx
+// React
+<OzElements pubKey="pk_live_..." sessionUrl="/api/oz-session" 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.
@@ -920,7 +1061,7 @@ const ozura = new Ozura({
 });
 ```
 
-> **Tokenize-only integrations** (mint wax keys + tokenize cards, no charging) only need `vaultKey`. The `merchantId` and `apiKey` fields are optional — they are validated lazily and only required when `cardSale()` is called.
+> **Tokenize-only integrations** (session creation + tokenize cards, no charging) only need `vaultKey`. The `merchantId` and `apiKey` fields are optional — they are validated lazily and only required when `cardSale()` is called.
 >
 > ```ts
 > const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
@@ -944,25 +1085,32 @@ const result = await ozura.cardSale({
 const surcharge = result.surchargeAmount ?? '0.00';
 const tip = result.tipAmount ?? '0.00';
 
-// Mint a wax key (for custom fetchWaxKey implementations)
-const { waxKey, expiresInSeconds } = await ozura.mintWaxKey({
-  tokenizationSessionId: sessionId,
-  maxTokenizeCalls: 3,  // must match VaultOptions.maxTokenizeCalls on the client (default: 3)
+// Create a session key (for custom session endpoint implementations)
+const { sessionKey, expiresInSeconds } = await ozura.createSession({
+  sessionId,
+  sessionLimit: 3,    // must match VaultOptions.sessionLimit on the client (default: 3)
+                      // pass null to remove the cap (vault default = unlimited)
+  // Optional — stored in vault audit log for correlation with your own records:
+  // orderId:    order.id,
+  // customerId: user.id,
+  // cartId:     cart.id,
+  // metadata:   { source: 'web' },
+  // ttlSeconds: 600,  // shorter TTL for quicker checkouts (default: 1800)
 });
 
-// Revoke a wax key — call on all three session-end paths
+// Revoke a session — call on all three session-end paths
 // Best-effort — never throws. Shortens the exposure window before the vault's ~30 min TTL.
-await ozura.revokeWaxKey(waxKey);
+await ozura.revokeSession(sessionKey);
 
 // Suggested pattern — wire all three exit paths:
 // 1. Payment success
 const result = await ozura.cardSale({ ... });
-await ozura.revokeWaxKey(waxKey);      // key is spent; close the window immediately
+await ozura.revokeSession(sessionKey);   // session is spent; close the window immediately
 
 // 2. User cancels checkout
 router.post('/api/cancel', async (req) => {
-  const { waxKey } = await db.session.get(req.sessionId);
-  await ozura.revokeWaxKey(waxKey);
+  const { sessionKey } = await db.session.get(req.sessionId);
+  await ozura.revokeSession(sessionKey);
   return Response.json({ ok: true });
 });
 
@@ -1001,18 +1149,18 @@ try {
 
 Rate limits: `cardSale` — 100 req/min per merchant. `listTransactions` — 200 req/min per merchant.
 
-> **Retry behavior:** `mintWaxKey` and `listTransactions` retry on 5xx and network errors using exponential backoff (1 s / 2 s / 4 s…) up to `retries + 1` total attempts. **`cardSale` is never retried** — it is a non-idempotent financial operation and the result of a duplicate charge cannot be predicted.
+> **Retry behavior:** `createSession` and `listTransactions` retry on 5xx and network errors using exponential backoff (1 s / 2 s / 4 s…) up to `retries + 1` total attempts. **`cardSale` is never retried** — it is a non-idempotent financial operation and the result of a duplicate charge cannot be predicted.
 
 ---
 
 ### Route handler factories
 
-The server package exports four factory functions covering two runtimes × two endpoints:
+The server package exports factory functions covering two runtimes × two endpoints:
 
 | Function | Runtime | Endpoint |
 |---|---|---|
-| `createMintWaxHandler` | Fetch API (Next.js App Router, Cloudflare, Vercel Edge) | `POST /api/mint-wax` |
-| `createMintWaxMiddleware` | Express / Connect | `POST /api/mint-wax` |
+| `createSessionHandler` | Fetch API (Next.js App Router, Cloudflare, Vercel Edge) | `POST /api/oz-session` |
+| `createSessionMiddleware` | Express / Connect | `POST /api/oz-session` |
 | `createCardSaleHandler` | Fetch API | `POST /api/charge` |
 | `createCardSaleMiddleware` | Express / Connect | `POST /api/charge` |
 
@@ -1050,7 +1198,7 @@ Set `frameBaseUrl` to point your vault at the local server:
 ```ts
 const vault = await OzVault.create({
   pubKey: 'pk_test_...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  sessionUrl: '/api/oz-session',
   frameBaseUrl: 'http://localhost:4242',  // local dev only
 });
 ```
@@ -1060,7 +1208,7 @@ Or in React:
 ```tsx
 <OzElements
   pubKey="pk_test_..."
-  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+  sessionUrl="/api/oz-session"
   frameBaseUrl="http://localhost:4242"
 >
 ```
@@ -1160,8 +1308,8 @@ Server-specific types are exported from `@ozura/elements/server`:
 import type {
   OzuraConfig,
   CardSaleInput,
-  MintWaxKeyOptions,
-  MintWaxKeyResult,
+  CreateSessionOptions,
+  CreateSessionResult,
   ListTransactionsInput,
 } from '@ozura/elements/server';
 ```