@ozura/elements 1.0.1 → 1.0.2

package/README.md

@@ -1,1130 +1,1192 @@
-# @ozura/elements
-
-PCI-isolated card and bank account tokenization SDK for the Ozura Vault.
-
-Card data is collected inside Ozura-hosted iframes so raw numbers never touch your JavaScript bundle, your server logs, or your network traffic. The tokenizer communicates directly with the vault using `MessageChannel` port transfers — the merchant page acts as a layout host only.
-
----
-
-## Table of contents
-
-- [How it works](#how-it-works)
-- [Installation](#installation)
-- [Quick start — React](#quick-start--react)
-- [Quick start — Vanilla JS](#quick-start--vanilla-js)
-- [Server setup](#server-setup)
-  - [Wax key endpoint](#wax-key-endpoint)
-  - [Card sale endpoint](#card-sale-endpoint)
-- [Vanilla JS API](#vanilla-js-api)
-  - [OzVault.create()](#ozvaultcreate)
-  - [vault.createElement()](#vaultcreateelementtypeoptions)
-  - [vault.createToken()](#vaultcreatetokenoptions)
-  - [vault.createBankElement()](#vaultcreatebankelement)
-  - [vault.createBankToken()](#vaultcreatebanktokenoptions)
-  - [vault.destroy()](#vaultdestroy)
-  - [OzElement events](#ozelement-events)
-- [React API](#react-api)
-  - [OzElements provider](#ozelements-provider)
-  - [OzCard](#ozcard)
-  - [Individual field components](#individual-field-components)
-  - [OzBankCard](#ozbankcard)
-  - [useOzElements()](#useozelements)
-- [Styling](#styling)
-  - [Per-element styles](#per-element-styles)
-  - [Global appearance](#global-appearance)
-  - [Custom fonts](#custom-fonts)
-- [Billing details](#billing-details)
-- [Error handling](#error-handling)
-- [Server utilities](#server-utilities)
-  - [Ozura class](#ozura-class)
-  - [Route handler factories](#route-handler-factories)
-- [Local development](#local-development)
-- [Content Security Policy](#content-security-policy)
-- [TypeScript reference](#typescript-reference)
-
----
-
-## How it works
-
-```
-Merchant page
-  ├── OzVault (manages tokenizer iframe + element iframes)
-  ├── [hidden]  tokenizer-frame.html  ← Ozura origin
-  ├── [visible] element-frame.html    ← card number   ─┐ MessageChannel
-  ├── [visible] element-frame.html    ← expiry         ├─ port transfer
-  └── [visible] element-frame.html    ← CVV           ─┘
-```
-
-1. `OzVault.create()` mounts a hidden tokenizer iframe and fetches a short-lived **wax 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.
-
-Your server only ever sees a token, never card data.
-
----
-
-## Credentials
-
-| 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) |
-| **Pay API key** | `ak_…` | Server env var only | OzuraPay merchants (card charging) |
-| **Merchant ID** | `ozu_…` | Server env var only | OzuraPay merchants (card charging) |
-
-If you are not routing payments through OzuraPay you only need the vault pub key (frontend) and vault API key (backend).
-
----
-
-## Installation
-
-```bash
-npm install @ozura/elements
-```
-
-React and React DOM are peer dependencies (optional — only needed for `@ozura/elements/react`):
-
-```bash
-npm install react react-dom   # if not already installed
-```
-
-**Requirements:** Node ≥ 18, React ≥ 17 (React peer).
-
----
-
-## Quick start — React
-
-```tsx
-// 1. Wrap your checkout in <OzElements>
-import { OzElements, OzCard, useOzElements, createFetchWaxKey } from '@ozura/elements/react';
-
-function CheckoutPage() {
-  return (
-    <OzElements
-      pubKey="pk_live_..."
-      fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
-    >
-      <CheckoutForm />
-    </OzElements>
-  );
-}
-
-// 2. Collect card data and tokenize
-function CheckoutForm() {
-  const { createToken, 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 }),
-    });
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <OzCard onChange={(state) => console.log(state.cardBrand)} />
-      <button type="submit" disabled={!ready}>Pay</button>
-    </form>
-  );
-}
-```
-
----
-
-## Quick start — Vanilla JS
-
-```ts
-import { OzVault, createFetchWaxKey } 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
-// iframe loads concurrently with fetchWaxKey. At that moment, `vault` is still
-// undefined. Do not reference `vault` inside onReady.
-let readyCount = 0;
-let tokenizerIsReady = false;
-
-function checkReady() {
-  if (readyCount === 3 && tokenizerIsReady) enablePayButton();
-}
-
-const vault = await OzVault.create({
-  pubKey: 'pk_live_...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
-  onReady: () => { tokenizerIsReady = true; checkReady(); },   // tokenizer iframe loaded
-});
-
-const cardNumberEl  = vault.createElement('cardNumber');
-const expiryEl      = vault.createElement('expirationDate');
-const cvvEl         = vault.createElement('cvv');
-
-cardNumberEl.mount('#card-number');
-expiryEl.mount('#expiry');
-cvvEl.mount('#cvv');
-
-[cardNumberEl, expiryEl, cvvEl].forEach(el => {
-  el.on('ready', () => { readyCount++; checkReady(); });
-});
-
-async function pay() {
-  const { token, cvcSession, card } = await vault.createToken({
-    billing: { firstName: 'Jane', lastName: 'Smith' },
-  });
-  // POST { token, cvcSession } to your server
-}
-
-// Clean up when done
-vault.destroy();
-```
-
-> **Gating the submit button in vanilla JS** requires checking both `vault.isReady` (tokenizer iframe loaded) **and** every element's `ready` event (input iframes loaded). In React, `useOzElements().ready` combines both automatically.
-
----
-
-## Server setup
-
-### Wax key endpoint
-
-The SDK calls your `fetchWaxKey` function with a `tokenizationSessionId` UUID. Your backend must exchange it for a wax key from the vault.
-
-**Next.js App Router (recommended)**
-
-```ts
-// app/api/mint-wax/route.ts
-import { Ozura, createMintWaxHandler } 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!,
-});
-
-export const POST = createMintWaxHandler(ozura);
-```
-
-**Express**
-
-```ts
-import express from 'express';
-import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
-
-const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
-const app = express();
-
-app.use(express.json());
-app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
-```
-
-**Manual implementation**
-
-```ts
-// POST /api/mint-wax
-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 });
-```
-
-### Card sale endpoint
-
-After `createToken()` resolves on the frontend, POST `{ token, cvcSession, billing }` to your server to charge the card.
-
-**Next.js App Router**
-
-```ts
-// app/api/charge/route.ts
-import { Ozura, createCardSaleHandler } from '@ozura/elements/server';
-
-const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
-
-export const POST = createCardSaleHandler(ozura, {
-  getAmount: async (body) => {
-    const order = await db.orders.findById(body.orderId as string);
-    return order.total; // decimal string, e.g. "49.00"
-  },
-  // getCurrency: async (body) => 'USD',  // optional, defaults to "USD"
-});
-```
-
-**Express**
-
-```ts
-app.post('/api/charge', createCardSaleMiddleware(ozura, {
-  getAmount: async (body) => {
-    const order = await db.orders.findById(body.orderId as string);
-    return order.total; // decimal string, e.g. "49.00"
-  },
-  // getCurrency: async (body) => 'USD',  // optional, defaults to "USD"
-}));
-```
-
-> `createCardSaleMiddleware` always terminates the request — it does not call `next()` and cannot be composed in a middleware chain.
-
-**Manual implementation**
-
-```ts
-const { token, cvcSession, billing } = await req.json();
-const result = await ozura.cardSale({
-  token,
-  cvcSession,
-  amount: '49.00',
-  currency: 'USD',
-  billing,
-  // Take the first IP from the forwarded-for chain; fall back to socket address.
-  // req is a Fetch API Request (Next.js App Router / Vercel Edge).
-  clientIpAddress: req.headers.get('x-forwarded-for')?.split(',')[0].trim()
-    ?? req.headers.get('x-real-ip')
-    ?? '',
-});
-// result.transactionId, result.amount, result.cardLastFour, result.cardBrand
-```
-
----
-
-## Vanilla JS API
-
-### OzVault.create(options)
-
-```ts
-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.
-
-| 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. |
-| `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. |
-
-Throws `OzError` if `fetchWaxKey` rejects, returns an empty string, or returns a non-string value.
-
-> **`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`.
-
-> **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.
-
----
-
-### vault.createElement(type, options?)
-
-```ts
-vault.createElement(type: ElementType, options?: ElementOptions): OzElement
-```
-
-Creates and returns an element iframe. Call `.mount(target)` to attach it to the DOM.
-
-`ElementType`: `'cardNumber'` | `'cvv'` | `'expirationDate'`
-
-```ts
-const cardEl = vault.createElement('cardNumber', {
-  placeholder: '1234 5678 9012 3456',
-  style: {
-    base:     { color: '#1a1a1a', fontSize: '16px' },
-    focus:    { borderColor: '#6366f1' },
-    invalid:  { color: '#dc2626' },
-    complete: { color: '#16a34a' },
-  },
-});
-
-cardEl.mount('#card-number-container');
-```
-
-`ElementOptions`:
-
-| Option | Type | Description |
-|---|---|---|
-| `style` | `ElementStyleConfig` | Per-state style overrides. See [Styling](#styling). |
-| `placeholder` | `string` | Placeholder text (max 100 characters). |
-| `disabled` | `boolean` | Disables the input. |
-| `loadTimeoutMs` | `number` | Iframe load timeout in ms. Default: `10000`. |
-
-**OzElement methods:**
-
-| Method | Description |
-|---|---|
-| `.mount(target)` | Mount the iframe. Accepts a CSS selector string or `HTMLElement`. |
-| `.unmount()` | Remove the iframe from the DOM. The element can be re-mounted. |
-| `.destroy()` | Permanently destroy the element. Cannot be re-mounted. |
-| `.update(options)` | Update placeholder, style, or disabled state without re-mounting. **Merge semantics** — only provided keys are applied; omitted keys retain their values. To reset a property, pass it with an empty string (e.g. `{ style: { base: { color: '' } } }`). To fully reset all styles, destroy and recreate the element. |
-| `.clear()` | Clear the field value. |
-| `.focus()` | Programmatically focus the input. |
-| `.blur()` | Programmatically blur the input. |
-| `.on(event, fn)` | Subscribe to an event. Returns `this` for chaining. |
-| `.off(event, fn)` | Remove an event handler. |
-| `.once(event, fn)` | Subscribe for a single invocation. |
-| `.isReady` | `true` once the iframe has loaded and signalled ready. |
-
----
-
-### vault.createToken(options?)
-
-```ts
-vault.createToken(options?: TokenizeOptions): Promise<TokenResponse>
-```
-
-Tokenizes all mounted and ready card elements. Raw values travel directly from element iframes to the tokenizer iframe via `MessageChannel` — they never pass through your page's JavaScript.
-
-Returns a `TokenResponse`:
-
-```ts
-interface TokenResponse {
-  token:      string;           // Vault token — pass to cardSale
-  cvcSession: string;           // CVC session — always present; pass to cardSale
-  card: {                       // Card metadata — always present on success
-    last4:    string;           // e.g. "4242"
-    brand:    string;           // e.g. "visa"
-    expMonth: string;           // e.g. "09"
-    expYear:  string;           // e.g. "2027"
-  };
-  billing?: BillingDetails;     // Normalized billing — only present if billing was passed in
-}
-```
-
-`TokenizeOptions`:
-
-| Option | Type | Description |
-|---|---|---|
-| `billing` | `BillingDetails` | Validated and normalized billing details. Returned in `TokenResponse.billing`. |
-| `firstName` | `string` | **Deprecated.** Pass inside `billing` instead. |
-| `lastName` | `string` | **Deprecated.** Pass inside `billing` instead. |
-
-Throws `OzError` if:
-- The vault is not ready (`errorCode: 'unknown'`)
-- A tokenization is already in progress
-- Billing validation fails (`errorCode: 'validation'`)
-- No elements are mounted
-- The vault returns an error (`errorCode` reflects the HTTP status)
-- The request times out after 30 seconds (`errorCode: 'timeout'`) — this timeout is separate from `loadTimeoutMs` and is not configurable
-
-**`vault.tokenizeCount`**
-
-```ts
-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:
-
-```ts
-const MAX = 3; // matches maxTokenizeCalls
-const remaining = MAX - vault.tokenizeCount;
-payButton.textContent = `Pay (${remaining} attempt${remaining === 1 ? '' : 's'} remaining)`;
-```
-
-In React, use `tokenizeCount` from `useOzElements()` instead — it is a reactive state value and will trigger re-renders automatically.
-
----
-
-### vault.createBankElement()
-
-```ts
-vault.createBankElement(type: BankElementType, options?: ElementOptions): OzElement
-```
-
-Creates a bank account element. `BankElementType`: `'accountNumber'` | `'routingNumber'`.
-
-```ts
-const accountEl = vault.createBankElement('accountNumber');
-const routingEl = vault.createBankElement('routingNumber');
-accountEl.mount('#account-number');
-routingEl.mount('#routing-number');
-```
-
----
-
-### vault.createBankToken(options)
-
-```ts
-vault.createBankToken(options: BankTokenizeOptions): Promise<BankTokenResponse>
-```
-
-Tokenizes the mounted `accountNumber` and `routingNumber` elements. Both must be mounted and ready.
-
-```ts
-interface BankTokenizeOptions {
-  firstName: string;  // Account holder first name (required, max 50 chars)
-  lastName:  string;  // Account holder last name (required, max 50 chars)
-}
-
-interface BankTokenResponse {
-  token: string;
-  bank?: {
-    last4:               string;  // Last 4 digits of account number
-    routingNumberLast4:  string;
-  };
-}
-```
-
-> **Note:** OzuraPay does not currently support bank account payments. Use the bank token with your own ACH processor. Bank tokens can be passed to any ACH-capable processor directly.
-
-> **Card tokens and processors:** Card tokenization returns a `cvcSession` alongside the `token`. OzuraPay's charge API requires `cvcSession`. If you are routing to a non-Ozura processor, pass the `token` directly — your processor's documentation will tell you whether a CVC session token is required.
-
----
-
-### vault.destroy()
-
-```ts
-vault.destroy(): void
-```
-
-Tears down the vault: removes all element and tokenizer iframes, clears the `message` event listener, rejects any pending `createToken()` / `createBankToken()` promises, and cancels active timeout handles. Call this when the checkout component unmounts.
-
-```ts
-// React useEffect cleanup — the cancel flag prevents a vault from leaking
-// if the component unmounts before OzVault.create() resolves.
-useEffect(() => {
-  let cancelled = false;
-  let vault: OzVault | null = null;
-  OzVault.create(options).then(v => {
-    if (cancelled) { v.destroy(); return; }
-    vault = v;
-  });
-  return () => {
-    cancelled = true;
-    vault?.destroy();
-  };
-}, []);
-```
-
----
-
-### OzElement events
-
-```ts
-element.on('change', (event: ElementChangeEvent) => { ... });
-element.on('focus',  () => { ... });
-element.on('blur',   () => { ... });
-element.on('ready',  () => { ... });
-element.on('loaderror', (payload: { elementType: string; error: string }) => { ... });
-```
-
-`ElementChangeEvent`:
-
-| Field | Type | Description |
-|---|---|---|
-| `empty` | `boolean` | `true` when the field is empty. |
-| `complete` | `boolean` | `true` when the field has enough digits to be complete. |
-| `valid` | `boolean` | `true` when the value passes all validation (Luhn, expiry date, etc.). |
-| `error` | `string \| undefined` | User-facing error message when `valid` is `false` and the field has been touched. |
-| `cardBrand` | `string \| undefined` | Detected brand — only on `cardNumber` fields (e.g. `"visa"`, `"amex"`). |
-| `month` | `string \| undefined` | Parsed 2-digit month — only on `expirationDate` fields. |
-| `year` | `string \| undefined` | Parsed 2-digit year — only on `expirationDate` fields. |
-
-> **Expiry data and PCI scope:** The expiry `onChange` event delivers parsed `month` and `year` to your handler for display purposes (e.g. "Card expires MM/YY"). These are not PANs or CVVs, but they are cardholder data. If your PCI scope requires zero cardholder data on the merchant page, do not read, log, or store these fields.
-
-Auto-advance is built in: the vault automatically moves focus from card number → expiry → CVV when each field completes. No additional code required.
-
----
-
-## React API
-
-### OzElements provider
-
-```tsx
-import { OzElements, createFetchWaxKey } from '@ozura/elements/react';
-
-<OzElements
-  pubKey="pk_live_..."
-  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
-  appearance={{ theme: 'flat', variables: { colorPrimary: '#6366f1' } }}
-  onLoadError={() => setPaymentUnavailable(true)}
->
-  {children}
-</OzElements>
-```
-
-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.
-
-> **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.
-
----
-
-### OzCard
-
-Drop-in combined card component. Renders card number, expiry, and CVV with a configurable layout.
-
-```tsx
-import { OzCard } from '@ozura/elements/react';
-
-<OzCard
-  layout="default"       // "default" (number on top, expiry+CVV below) | "rows" (stacked)
-  onChange={(state) => {
-    // state.complete   — all three fields complete + valid
-    // state.cardBrand  — detected brand
-    // state.error      — first error across all fields
-    // state.fields     — per-field ElementChangeEvent objects
-  }}
-  onReady={() => console.log('all card fields loaded')}
-  disabled={isSubmitting}
-  labels={{ cardNumber: 'Card Number', expiry: 'Expiry', cvv: 'CVV' }}
-  placeholders={{ cardNumber: '1234 5678 9012 3456', expiry: 'MM/YY', cvv: '···' }}
-/>
-```
-
-`OzCardProps` (full):
-
-| Prop | Type | Description |
-|---|---|---|
-| `layout` | `'default' \| 'rows'` | `'default'`: number full-width, expiry+CVV side by side. `'rows'`: all stacked. |
-| `gap` | `number \| string` | Gap between fields. Default: `8` (px). |
-| `style` | `ElementStyleConfig` | Shared style applied to all three inputs. |
-| `styles` | `{ cardNumber?, expiry?, cvv? }` | Per-field overrides merged on top of `style`. |
-| `classNames` | `{ cardNumber?, expiry?, cvv?, row? }` | CSS class names for field wrappers and the expiry+CVV row. |
-| `labels` | `{ cardNumber?, expiry?, cvv? }` | Optional label text above each field. |
-| `labelStyle` | `React.CSSProperties` | Style applied to all `<label>` elements. |
-| `labelClassName` | `string` | Class applied to all `<label>` elements. |
-| `placeholders` | `{ cardNumber?, expiry?, cvv? }` | Custom placeholder text per field. |
-| `hideErrors` | `boolean` | Suppress the built-in error display. Handle via `onChange`. |
-| `errorStyle` | `React.CSSProperties` | Style for the built-in error container. |
-| `errorClassName` | `string` | Class for the built-in error container. |
-| `renderError` | `(error: string) => ReactNode` | Custom error renderer. |
-| `onChange` | `(state: OzCardState) => void` | Fires on any field change. |
-| `onReady` | `() => void` | Fires once all three iframes have loaded. |
-| `onFocus` | `(field: 'cardNumber' \| 'expiry' \| 'cvv') => void` | |
-| `onBlur` | `(field: 'cardNumber' \| 'expiry' \| 'cvv') => void` | |
-| `disabled` | `boolean` | Disable all inputs. |
-| `className` | `string` | Class for the outer wrapper. |
-
----
-
-### Individual field components
-
-For custom layouts where `OzCard` is too opinionated:
-
-```tsx
-import { OzCardNumber, OzExpiry, OzCvv } from '@ozura/elements/react';
-
-<OzCardNumber onChange={handleChange} placeholder="Card number" />
-<OzExpiry     onChange={handleChange} />
-<OzCvv        onChange={handleChange} />
-```
-
-All accept `OzFieldProps`:
-
-| Prop | Type | Description |
-|---|---|---|
-| `style` | `ElementStyleConfig` | Input styles. |
-| `placeholder` | `string` | Placeholder text. |
-| `disabled` | `boolean` | Disables the input. |
-| `loadTimeoutMs` | `number` | Iframe load timeout in ms. |
-| `onChange` | `(event: ElementChangeEvent) => void` | |
-| `onFocus` | `() => void` | |
-| `onBlur` | `() => void` | |
-| `onReady` | `() => void` | |
-| `onLoadError` | `(error: string) => void` | |
-| `className` | `string` | Class for the outer wrapper div. |
-
----
-
-### OzBankCard
-
-```tsx
-import { OzBankCard } from '@ozura/elements/react';
-
-<OzBankCard
-  onChange={(state) => {
-    // state.complete, state.error, state.fields.accountNumber, state.fields.routingNumber
-  }}
-  labels={{ accountNumber: 'Account Number', routingNumber: 'Routing Number' }}
-/>
-```
-
-Or use individual bank components:
-
-```tsx
-import { OzBankAccountNumber, OzBankRoutingNumber } from '@ozura/elements/react';
-
-<OzBankAccountNumber onChange={handleChange} />
-<OzBankRoutingNumber onChange={handleChange} />
-```
-
----
-
-### useOzElements()
-
-```ts
-const { createToken, createBankToken, ready, initError, tokenizeCount } = useOzElements();
-```
-
-Must be called from inside an `<OzElements>` provider tree.
-
-| Return | Type | Description |
-|---|---|---|
-| `createToken` | `(options?: TokenizeOptions) => Promise<TokenResponse>` | Tokenize mounted card elements. |
-| `createBankToken` | `(options: BankTokenizeOptions) => Promise<BankTokenResponse>` | Tokenize mounted bank elements. |
-| `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`. |
-
-> **`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.
-
----
-
-## Styling
-
-### Per-element styles
-
-Styles apply inside each iframe's `<input>` element. Only an explicit allowlist of CSS properties is accepted (typography, spacing, borders, box-shadow, cursor, transitions). Values containing `url()`, `var()`, `expression()`, `javascript:`, or CSS breakout characters are blocked on both the SDK and iframe sides. Use literal values instead of CSS custom properties (`var(--token)` is rejected). When a value is stripped, the browser falls back to the element's default (unstyled) appearance for that property — the failure is silent with no error or console warning. Resolve design tokens to literal values before passing them in.
-
-```ts
-const style: ElementStyleConfig = {
-  base: {
-    color:           '#1a1a1a',
-    fontSize:        '16px',
-    fontFamily:      '"Inter", sans-serif',
-    padding:         '10px 12px',
-    backgroundColor: '#ffffff',
-    borderRadius:    '6px',
-    border:          '1px solid #d1d5db',
-  },
-  focus: {
-    borderColor: '#6366f1',
-    boxShadow:   '0 0 0 3px rgba(99,102,241,0.15)',
-    outline:     'none',
-  },
-  invalid: {
-    borderColor: '#ef4444',
-    color:       '#dc2626',
-  },
-  complete: {
-    borderColor: '#22c55e',
-  },
-  placeholder: {
-    color: '#9ca3af',
-  },
-};
-```
-
-State precedence: `placeholder` applies to the `::placeholder` pseudo-element. `focus`, `invalid`, and `complete` merge on top of `base`.
-
-### Global appearance
-
-Apply a preset theme and/or variable overrides to all elements at once:
-
-```ts
-// OzVault.create
-const vault = await OzVault.create({
-  pubKey: '...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
-  appearance: {
-    theme: 'flat',                    // 'default' | 'night' | 'flat'
-    variables: {
-      colorText:        '#1a1a1a',
-      colorBackground:  '#ffffff',
-      colorPrimary:     '#6366f1',    // focus caret + color
-      colorDanger:      '#dc2626',    // invalid state
-      colorSuccess:     '#16a34a',    // complete state
-      colorPlaceholder: '#9ca3af',
-      fontFamily:       '"Inter", sans-serif',
-      fontSize:         '15px',
-      fontWeight:       '400',
-      padding:          '10px 14px',
-      letterSpacing:    '0.01em',
-    },
-  },
-});
-
-// React provider
-<OzElements pubKey="..." fetchWaxKey={...} appearance={{ theme: 'night' }}>
-```
-
-Per-element `style` takes precedence over `appearance` variables.
-
-> **`appearance: {}` is not "no theme":** Passing `appearance: {}` or `appearance: { variables: { ... } }` without a `theme` key applies the `'default'` preset as a base. To render elements with no preset styling, omit `appearance` entirely and use per-element `style` overrides.
->
-> | `appearance` value | Result |
-> |---|---|
-> | *(omitted entirely)* | No preset — element uses minimal built-in defaults |
-> | `{}` | Equivalent to `{ theme: 'default' }` — full default theme applied |
-> | `{ theme: 'night' }` | Night theme |
-> | `{ variables: { colorText: '#333' } }` | Default theme + variable overrides |
-
-### Custom fonts
-
-Fonts are injected into each iframe so they render inside the input fields:
-
-```ts
-fonts: [
-  // Google Fonts or any HTTPS CSS URL
-  { cssSrc: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap' },
-
-  // Custom @font-face
-  {
-    family:  'BrandFont',
-    src:     'url(https://cdn.example.com/brand-font.woff2)',
-    weight:  '400',
-    style:   'normal',
-    display: 'swap',
-  },
-]
-```
-
-Font `src` values must start with `url(https://...)`. HTTP and data URIs are rejected.
-
----
-
-## Billing details
-
-```ts
-interface BillingDetails {
-  firstName: string;   // 1–50 characters
-  lastName:  string;   // 1–50 characters
-  email?:    string;   // Valid email, max 50 characters
-  phone?:    string;   // E.164 format, e.g. "+15551234567", max 50 characters
-  address?: {
-    line1:   string;   // 1–50 characters
-    line2?:  string;   // Optional, omitted from cardSale if blank
-    city:    string;   // 1–50 characters
-    state:   string;   // For US/CA: normalized to 2-letter abbreviation
-    zip:     string;   // 1–50 characters
-    country: string;   // ISO 3166-1 alpha-2, e.g. "US"
-  };
-}
-```
-
-Billing is validated and normalized by both `vault.createToken()` and the server-side handler factories. `TokenResponse.billing` contains the normalized result ready to spread into a `cardSale` call.
-
----
-
-## Error handling
-
-All SDK errors are instances of `OzError`:
-
-```ts
-import { OzError } from '@ozura/elements';
-
-try {
-  const { token } = await vault.createToken({ billing });
-} catch (err) {
-  if (err instanceof OzError) {
-    switch (err.errorCode) {
-      case 'network':     // Connection failure — show retry UI
-      case 'timeout':     // 30s deadline exceeded — safe to retry
-      case 'server':      // 5xx from vault — transient, safe to retry
-        if (err.retryable) showRetryPrompt();
-        break;
-
-      case 'auth':        // Bad pub key / API key — configuration issue
-      case 'validation':  // Bad card data — show field-level error
-      case 'config':      // frameBaseUrl not in permitted allowlist
-      case 'unknown':
-        showError(err.message);
-        break;
-    }
-  }
-}
-```
-
-`OzError` fields:
-
-| Field | Type | Description |
-|---|---|---|
-| `message` | `string` | Human-readable, consumer-facing error message. |
-| `errorCode` | `OzErrorCode` | `'network' \| 'timeout' \| 'auth' \| 'validation' \| 'server' \| 'config' \| 'unknown'` |
-| `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.
-
-**Error normalisation helpers** (for displaying errors from `cardSale` to users):
-
-```ts
-import { normalizeVaultError, normalizeBankVaultError, normalizeCardSaleError } from '@ozura/elements';
-
-// Maps vault tokenize error strings to user-facing copy
-const display = normalizeVaultError(err.raw);       // card flows
-const display = normalizeBankVaultError(err.raw);   // bank/ACH flows
-const display = normalizeCardSaleError(err.message); // cardSale API errors
-```
-
----
-
-## Server utilities
-
-### Ozura class
-
-```ts
-import { Ozura, OzuraError } 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!,
-  // apiUrl:   'https://api.ozura.com',  // override Pay API URL
-  // vaultUrl: 'https://vault.ozura.com', // override vault URL
-  timeoutMs: 30000,    // default
-  retries:   2,        // max retry attempts for 5xx/network errors (3 total attempts)
-});
-```
-
-> **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.
->
-> ```ts
-> const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
-> ```
-
-**Methods:**
-
-```ts
-// Charge a tokenized card
-const result = await ozura.cardSale({
-  token:           tokenResponse.token,
-  cvcSession:      tokenResponse.cvcSession,
-  amount:          '49.00',
-  currency:        'USD',          // default: 'USD'
-  billing:         tokenResponse.billing,
-  clientIpAddress: '1.2.3.4',     // fetch server-side, never from the browser
-  // surchargePercent, tipAmount, salesTaxExempt, processor
-});
-// result.transactionId, result.amount, result.cardLastFour, result.cardBrand
-// result.surchargeAmount and result.tipAmount are optional — only present when non-zero
-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)
-});
-
-// Revoke a wax key — 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);
-
-// 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
-
-// 2. User cancels checkout
-router.post('/api/cancel', async (req) => {
-  const { waxKey } = await db.session.get(req.sessionId);
-  await ozura.revokeWaxKey(waxKey);
-  return Response.json({ ok: true });
-});
-
-// 3. Page/tab close (best-effort — browser may not deliver this)
-//    Use sendBeacon so the request survives navigation / tab close.
-window.addEventListener('visibilitychange', () => {
-  if (document.visibilityState === 'hidden') {
-    navigator.sendBeacon('/api/cancel', JSON.stringify({ sessionId }));
-  }
-});
-
-// List transactions
-const { transactions, pagination } = await ozura.listTransactions({
-  dateFrom:        '2025-01-01',
-  dateTo:          '2025-12-31',
-  transactionType: 'CreditCardSale',
-  page:            1,
-  limit:           50,
-});
-```
-
-**`OzuraError`** (thrown by all `Ozura` methods):
-
-```ts
-try {
-  await ozura.cardSale(input);
-} catch (err) {
-  if (err instanceof OzuraError) {
-    err.statusCode;   // HTTP status code
-    err.message;      // Normalized message
-    err.raw;          // Raw API response string
-    err.retryAfter;   // Seconds (only present on 429)
-  }
-}
-```
-
-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.
-
----
-
-### Route handler factories
-
-The server package exports four 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` |
-| `createCardSaleHandler` | Fetch API | `POST /api/charge` |
-| `createCardSaleMiddleware` | Express / Connect | `POST /api/charge` |
-
-`createCardSaleHandler` / `createCardSaleMiddleware` accept a `CardSaleHandlerOptions` object:
-
-```ts
-interface CardSaleHandlerOptions {
-  /**
-   * Required. Return the charge amount as a decimal string.
-   * Never trust the amount from the request body — resolve it from your database.
-   */
-  getAmount: (body: Record<string, unknown>) => Promise<string>;
-
-  /**
-   * Optional. Return the ISO 4217 currency code. Default: "USD".
-   */
-  getCurrency?: (body: Record<string, unknown>) => Promise<string>;
-}
-```
-
-Both handler factories validate `Content-Type: application/json`, run `validateBilling()`, extract the client IP from standard proxy headers, and return normalized `{ transactionId, amount, cardLastFour, cardBrand }` on success.
-
----
-
-## Local development
-
-The repository includes a development server at `dev-server.mjs` that serves the built frame assets and proxies vault API requests:
-
-```bash
-npm run dev   # build + start dev server on http://localhost:4242
-```
-
-Set `frameBaseUrl` to point your vault at the local server:
-
-```ts
-const vault = await OzVault.create({
-  pubKey: 'pk_test_...',
-  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
-  frameBaseUrl: 'http://localhost:4242',  // local dev only
-});
-```
-
-Or in React:
-
-```tsx
-<OzElements
-  pubKey="pk_test_..."
-  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
-  frameBaseUrl="http://localhost:4242"
->
-```
-
-Configure environment variables for the dev server:
-
-```bash
-VAULT_URL=https://vault-staging.example.com
-VAULT_API_KEY=vk_test_...
-```
-
----
-
-## Content Security Policy
-
-The SDK loads iframes from the Ozura frame origin. Add the following directives to your CSP:
-
-```
-frame-src https://elements.ozura.com;
-```
-
-If loading custom fonts via `fonts[].cssSrc`, also allow the font stylesheet origin:
-
-```
-style-src  https://fonts.googleapis.com;
-font-src   https://fonts.gstatic.com;
-```
-
-To verify your CSP after a build:
-
-```bash
-npm run check:csp
-```
-
----
-
-## TypeScript reference
-
-All public types are exported from `@ozura/elements`:
-
-```ts
-import type {
-  // Element types
-  ElementType,           // 'cardNumber' | 'cvv' | 'expirationDate'
-  BankElementType,       // 'accountNumber' | 'routingNumber'
-  ElementOptions,
-  ElementStyleConfig,
-  ElementStyle,
-  ElementChangeEvent,
-
-  // Vault config
-  VaultOptions,
-  FontSource,
-  CssFontSource,
-  CustomFontSource,
-  Appearance,
-  AppearanceVariables,
-  OzTheme,               // 'default' | 'night' | 'flat'
-
-  // Tokenization
-  TokenizeOptions,
-  BankTokenizeOptions,
-  TokenResponse,
-  BankTokenResponse,
-  CardMetadata,
-  BankAccountMetadata,
-
-  // Billing
-  BillingDetails,
-  BillingAddress,
-
-  // Card sale
-  CardSaleRequest,
-  CardSaleResponseData,
-  CardSaleApiResponse,
-
-  // Transactions
-  TransactionQueryParams,
-  TransactionQueryPagination,
-  TransactionQueryResponse,
-  TransactionType,
-  TransactionData,
-  CardTransactionData,
-  AchTransactionData,
-  CryptoTransactionData,
-
-  // Errors
-  OzErrorCode,
-} from '@ozura/elements';
-```
-
-Server-specific types are exported from `@ozura/elements/server`:
-
-```ts
-import type {
-  OzuraConfig,
-  CardSaleInput,
-  MintWaxKeyOptions,
-  MintWaxKeyResult,
-  ListTransactionsInput,
-} from '@ozura/elements/server';
-```
-
-React-specific types are exported from `@ozura/elements/react`:
-
-```ts
-import type { OzFieldProps, OzCardProps, OzCardState, OzBankCardProps, OzBankCardState } from '@ozura/elements/react';
-```
+# @ozura/elements
+
+PCI-isolated card and bank account tokenization SDK for the Ozura Vault.
+
+Card data is collected inside Ozura-hosted iframes so raw numbers never touch your JavaScript bundle, your server logs, or your network traffic. The tokenizer communicates directly with the vault using `MessageChannel` port transfers — the merchant page acts as a layout host only.
+
+> **📖 Full documentation:** [docs.ozura.com/sdks/elements/overview](https://docs.ozura.com/sdks/elements/overview)
+>
+> The docs include step-by-step guides, interactive examples, a complete API reference, and styling walkthroughs. If you are starting a new integration, the docs are the best place to begin.
+
+---
+
+## Table of contents
+
+- [Full documentation](#full-documentation)
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Quick start — React](#quick-start--react)
+- [Quick start — Vanilla JS](#quick-start--vanilla-js)
+- [Server setup](#server-setup)
+  - [Wax key endpoint](#wax-key-endpoint)
+  - [Card sale endpoint](#card-sale-endpoint)
+- [Vanilla JS API](#vanilla-js-api)
+  - [OzVault.create()](#ozvaultcreate)
+  - [vault.createElement()](#vaultcreateelementtypeoptions)
+  - [vault.createToken()](#vaultcreatetokenoptions)
+  - [vault.createBankElement()](#vaultcreatebankelement)
+  - [vault.createBankToken()](#vaultcreatebanktokenoptions)
+  - [vault.destroy()](#vaultdestroy)
+  - [OzElement events](#ozelement-events)
+- [React API](#react-api)
+  - [OzElements provider](#ozelements-provider)
+  - [OzCard](#ozcard)
+  - [Individual field components](#individual-field-components)
+  - [OzBankCard](#ozbankcard)
+  - [useOzElements()](#useozelements)
+- [Styling](#styling)
+  - [Per-element styles](#per-element-styles)
+  - [Global appearance](#global-appearance)
+  - [Custom fonts](#custom-fonts)
+- [Billing details](#billing-details)
+- [Error handling](#error-handling)
+- [Server utilities](#server-utilities)
+  - [Ozura class](#ozura-class)
+  - [Route handler factories](#route-handler-factories)
+- [Local development](#local-development)
+- [Content Security Policy](#content-security-policy)
+- [TypeScript reference](#typescript-reference)
+
+---
+
+## Full documentation
+
+The README covers the most common integration patterns. The hosted docs at **[docs.ozura.com/sdks/elements](https://docs.ozura.com/sdks/elements/overview)** go deeper on every topic:
+
+| Page | URL |
+|---|---|
+| Overview | [docs.ozura.com/sdks/elements/overview](https://docs.ozura.com/sdks/elements/overview) |
+| Installation & setup | [docs.ozura.com/sdks/elements/installation](https://docs.ozura.com/sdks/elements/installation) |
+| Card elements | [docs.ozura.com/sdks/elements/card-elements](https://docs.ozura.com/sdks/elements/card-elements) |
+| Bank elements | [docs.ozura.com/sdks/elements/bank-elements](https://docs.ozura.com/sdks/elements/bank-elements) |
+| React integration | [docs.ozura.com/sdks/elements/react](https://docs.ozura.com/sdks/elements/react) |
+| Styling | [docs.ozura.com/sdks/elements/styling](https://docs.ozura.com/sdks/elements/styling) |
+| Error handling | [docs.ozura.com/sdks/elements/error-handling](https://docs.ozura.com/sdks/elements/error-handling) |
+| Server SDK | [docs.ozura.com/sdks/elements/server](https://docs.ozura.com/sdks/elements/server) |
+| API reference | [docs.ozura.com/sdks/elements/api-reference](https://docs.ozura.com/sdks/elements/api-reference) |
+
+---
+
+## How it works
+
+```
+Merchant page
+  ├── OzVault (manages tokenizer iframe + element iframes)
+  ├── [hidden]  tokenizer-frame.html  ← Ozura origin
+  ├── [visible] element-frame.html    ← card number   ─┐ MessageChannel
+  ├── [visible] element-frame.html    ← expiry         ├─ port transfer
+  └── [visible] element-frame.html    ← CVV           ─┘
+```
+
+1. `OzVault.create()` mounts a hidden tokenizer iframe and fetches a short-lived **wax 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.
+
+Your server only ever sees a token, never card data.
+
+---
+
+## Credentials
+
+| 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) |
+| **Pay API key** | `ak_…` | Server env var only | OzuraPay merchants (card charging) |
+| **Merchant ID** | `ozu_…` | Server env var only | OzuraPay merchants (card charging) |
+
+If you are not routing payments through OzuraPay you only need the vault pub key (frontend) and vault API key (backend).
+
+---
+
+## Installation
+
+> 📖 [Installation guide](https://docs.ozura.com/sdks/elements/installation) — npm, yarn, CDN setup, and TypeScript configuration.
+
+```bash
+npm install @ozura/elements
+```
+
+React and React DOM are peer dependencies (optional — only needed for `@ozura/elements/react`):
+
+```bash
+npm install react react-dom   # if not already installed
+```
+
+**Requirements:** Node ≥ 18, React ≥ 17 (React peer).
+
+---
+
+## Quick start — React
+
+> 📖 [React integration guide](https://docs.ozura.com/sdks/elements/react) — provider setup, pre-built components, hook reference, and full examples.
+
+```tsx
+// 1. Wrap your checkout in <OzElements>
+import { OzElements, OzCard, useOzElements, createFetchWaxKey } from '@ozura/elements/react';
+
+function CheckoutPage() {
+  return (
+    <OzElements
+      pubKey="pk_live_..."
+      fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+    >
+      <CheckoutForm />
+    </OzElements>
+  );
+}
+
+// 2. Collect card data and tokenize
+function CheckoutForm() {
+  const { createToken, 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 }),
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <OzCard onChange={(state) => console.log(state.cardBrand)} />
+      <button type="submit" disabled={!ready}>Pay</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Quick start — Vanilla JS
+
+> 📖 [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';
+
+// Declare state BEFORE OzVault.create(). The onReady callback fires when the
+// tokenizer iframe loads — this can happen before create() resolves because the
+// iframe loads concurrently with fetchWaxKey. At that moment, `vault` is still
+// undefined. Do not reference `vault` inside onReady.
+let readyCount = 0;
+let tokenizerIsReady = false;
+
+function checkReady() {
+  if (readyCount === 3 && tokenizerIsReady) enablePayButton();
+}
+
+const vault = await OzVault.create({
+  pubKey: 'pk_live_...',
+  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  onReady: () => { tokenizerIsReady = true; checkReady(); },   // tokenizer iframe loaded
+});
+
+const cardNumberEl  = vault.createElement('cardNumber');
+const expiryEl      = vault.createElement('expirationDate');
+const cvvEl         = vault.createElement('cvv');
+
+cardNumberEl.mount('#card-number');
+expiryEl.mount('#expiry');
+cvvEl.mount('#cvv');
+
+[cardNumberEl, expiryEl, cvvEl].forEach(el => {
+  el.on('ready', () => { readyCount++; checkReady(); });
+});
+
+async function pay() {
+  const { token, cvcSession, card } = await vault.createToken({
+    billing: { firstName: 'Jane', lastName: 'Smith' },
+  });
+  // POST { token, cvcSession } to your server
+}
+
+// Clean up when done
+vault.destroy();
+```
+
+> **Gating the submit button in vanilla JS** requires checking both `vault.isReady` (tokenizer iframe loaded) **and** every element's `ready` event (input iframes loaded). In React, `useOzElements().ready` combines both automatically.
+
+---
+
+## 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.
+
+### Wax key endpoint
+
+The SDK calls your `fetchWaxKey` function with a `tokenizationSessionId` UUID. Your backend must exchange it for a wax key from the vault.
+
+**Next.js App Router (recommended)**
+
+```ts
+// app/api/mint-wax/route.ts
+import { Ozura, createMintWaxHandler } 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!,
+});
+
+export const POST = createMintWaxHandler(ozura);
+```
+
+**Express**
+
+```ts
+import express from 'express';
+import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
+
+const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+const app = express();
+
+app.use(express.json());
+app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
+```
+
+**Manual implementation**
+
+```ts
+// POST /api/mint-wax
+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 });
+```
+
+### Card sale endpoint
+
+After `createToken()` resolves on the frontend, POST `{ token, cvcSession, billing }` to your server to charge the card.
+
+**Next.js App Router**
+
+```ts
+// app/api/charge/route.ts
+import { Ozura, createCardSaleHandler } from '@ozura/elements/server';
+
+const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+
+export const POST = createCardSaleHandler(ozura, {
+  getAmount: async (body) => {
+    const order = await db.orders.findById(body.orderId as string);
+    return order.total; // decimal string, e.g. "49.00"
+  },
+  // getCurrency: async (body) => 'USD',  // optional, defaults to "USD"
+});
+```
+
+**Express**
+
+```ts
+app.post('/api/charge', createCardSaleMiddleware(ozura, {
+  getAmount: async (body) => {
+    const order = await db.orders.findById(body.orderId as string);
+    return order.total; // decimal string, e.g. "49.00"
+  },
+  // getCurrency: async (body) => 'USD',  // optional, defaults to "USD"
+}));
+```
+
+> `createCardSaleMiddleware` always terminates the request — it does not call `next()` and cannot be composed in a middleware chain.
+
+**Manual implementation**
+
+```ts
+const { token, cvcSession, billing } = await req.json();
+const result = await ozura.cardSale({
+  token,
+  cvcSession,
+  amount: '49.00',
+  currency: 'USD',
+  billing,
+  // Take the first IP from the forwarded-for chain; fall back to socket address.
+  // req is a Fetch API Request (Next.js App Router / Vercel Edge).
+  clientIpAddress: req.headers.get('x-forwarded-for')?.split(',')[0].trim()
+    ?? req.headers.get('x-real-ip')
+    ?? '',
+});
+// result.transactionId, result.amount, result.cardLastFour, result.cardBrand
+```
+
+---
+
+## Vanilla JS API
+
+> 📖 [API reference](https://docs.ozura.com/sdks/elements/api-reference) — complete type definitions and method signatures for every class.
+
+### OzVault.create(options)
+
+```ts
+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.
+
+| 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. |
+| `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. |
+
+Throws `OzError` if `fetchWaxKey` rejects, returns an empty string, or returns a non-string value.
+
+> **`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`.
+
+> **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.
+
+---
+
+### vault.createElement(type, options?)
+
+```ts
+vault.createElement(type: ElementType, options?: ElementOptions): OzElement
+```
+
+Creates and returns an element iframe. Call `.mount(target)` to attach it to the DOM.
+
+`ElementType`: `'cardNumber'` | `'cvv'` | `'expirationDate'`
+
+```ts
+const cardEl = vault.createElement('cardNumber', {
+  placeholder: '1234 5678 9012 3456',
+  style: {
+    base:     { color: '#1a1a1a', fontSize: '16px' },
+    focus:    { borderColor: '#6366f1' },
+    invalid:  { color: '#dc2626' },
+    complete: { color: '#16a34a' },
+  },
+});
+
+cardEl.mount('#card-number-container');
+```
+
+`ElementOptions`:
+
+| Option | Type | Description |
+|---|---|---|
+| `style` | `ElementStyleConfig` | Per-state style overrides. See [Styling](#styling). |
+| `placeholder` | `string` | Placeholder text (max 100 characters). |
+| `disabled` | `boolean` | Disables the input. |
+| `loadTimeoutMs` | `number` | Iframe load timeout in ms. Default: `10000`. |
+
+**OzElement methods:**
+
+| Method | Description |
+|---|---|
+| `.mount(target)` | Mount the iframe. Accepts a CSS selector string or `HTMLElement`. |
+| `.unmount()` | Remove the iframe from the DOM. The element can be re-mounted. |
+| `.destroy()` | Permanently destroy the element. Cannot be re-mounted. |
+| `.update(options)` | Update placeholder, style, or disabled state without re-mounting. **Merge semantics** — only provided keys are applied; omitted keys retain their values. To reset a property, pass it with an empty string (e.g. `{ style: { base: { color: '' } } }`). To fully reset all styles, destroy and recreate the element. |
+| `.clear()` | Clear the field value. |
+| `.focus()` | Programmatically focus the input. |
+| `.blur()` | Programmatically blur the input. |
+| `.on(event, fn)` | Subscribe to an event. Returns `this` for chaining. |
+| `.off(event, fn)` | Remove an event handler. |
+| `.once(event, fn)` | Subscribe for a single invocation. |
+| `.isReady` | `true` once the iframe has loaded and signalled ready. |
+
+---
+
+### vault.createToken(options?)
+
+```ts
+vault.createToken(options?: TokenizeOptions): Promise<TokenResponse>
+```
+
+Tokenizes all mounted and ready card elements. Raw values travel directly from element iframes to the tokenizer iframe via `MessageChannel` — they never pass through your page's JavaScript.
+
+Returns a `TokenResponse`:
+
+```ts
+interface TokenResponse {
+  token:      string;           // Vault token — pass to cardSale
+  cvcSession: string;           // CVC session — always present; pass to cardSale
+  card?: {                      // Card metadata — present when vault returns all four fields
+    last4:    string;           // e.g. "4242"
+    brand:    string;           // e.g. "visa"
+    expMonth: string;           // e.g. "09"
+    expYear:  string;           // e.g. "2027"
+  };
+  billing?: BillingDetails;     // Normalized billing — only present if billing was passed in
+}
+```
+
+`TokenizeOptions`:
+
+| Option | Type | Description |
+|---|---|---|
+| `billing` | `BillingDetails` | Validated and normalized billing details. Returned in `TokenResponse.billing`. |
+| `firstName` | `string` | **Deprecated.** Pass inside `billing` instead. |
+| `lastName` | `string` | **Deprecated.** Pass inside `billing` instead. |
+
+Throws `OzError` if:
+- The vault is not ready (`errorCode: 'unknown'`)
+- A tokenization is already in progress
+- Billing validation fails (`errorCode: 'validation'`)
+- No elements are mounted
+- The vault returns an error (`errorCode` reflects the HTTP status)
+- The request times out after 30 seconds (`errorCode: 'timeout'`) — this timeout is separate from `loadTimeoutMs` and is not configurable
+
+**`vault.tokenizeCount`**
+
+```ts
+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:
+
+```ts
+const MAX = 3; // matches maxTokenizeCalls
+const remaining = MAX - vault.tokenizeCount;
+payButton.textContent = `Pay (${remaining} attempt${remaining === 1 ? '' : 's'} remaining)`;
+```
+
+In React, use `tokenizeCount` from `useOzElements()` instead — it is a reactive state value and will trigger re-renders automatically.
+
+---
+
+### vault.createBankElement()
+
+```ts
+vault.createBankElement(type: BankElementType, options?: ElementOptions): OzElement
+```
+
+Creates a bank account element. `BankElementType`: `'accountNumber'` | `'routingNumber'`.
+
+```ts
+const accountEl = vault.createBankElement('accountNumber');
+const routingEl = vault.createBankElement('routingNumber');
+accountEl.mount('#account-number');
+routingEl.mount('#routing-number');
+```
+
+---
+
+### vault.createBankToken(options)
+
+```ts
+vault.createBankToken(options: BankTokenizeOptions): Promise<BankTokenResponse>
+```
+
+Tokenizes the mounted `accountNumber` and `routingNumber` elements. Both must be mounted and ready.
+
+```ts
+interface BankTokenizeOptions {
+  firstName: string;  // Account holder first name (required, max 50 chars)
+  lastName:  string;  // Account holder last name (required, max 50 chars)
+}
+
+interface BankTokenResponse {
+  token: string;
+  bank?: {
+    last4:               string;  // Last 4 digits of account number
+    routingNumberLast4:  string;
+  };
+}
+```
+
+> **Note:** OzuraPay does not currently support bank account payments. Use the bank token with your own ACH processor. Bank tokens can be passed to any ACH-capable processor directly.
+
+> **Card tokens and processors:** Card tokenization returns a `cvcSession` alongside the `token`. OzuraPay's charge API requires `cvcSession`. If you are routing to a non-Ozura processor, pass the `token` directly — your processor's documentation will tell you whether a CVC session token is required.
+
+---
+
+### vault.destroy()
+
+```ts
+vault.destroy(): void
+```
+
+Tears down the vault: removes all element and tokenizer iframes, clears the `message` event listener, rejects any pending `createToken()` / `createBankToken()` promises, and cancels active timeout handles. Call this when the checkout component unmounts.
+
+```ts
+// React useEffect cleanup — the cancel flag prevents a vault from leaking
+// if the component unmounts before OzVault.create() resolves.
+useEffect(() => {
+  let cancelled = false;
+  let vault: OzVault | null = null;
+  OzVault.create(options).then(v => {
+    if (cancelled) { v.destroy(); return; }
+    vault = v;
+  });
+  return () => {
+    cancelled = true;
+    vault?.destroy();
+  };
+}, []);
+```
+
+---
+
+### OzElement events
+
+```ts
+element.on('change', (event: ElementChangeEvent) => { ... });
+element.on('focus',  () => { ... });
+element.on('blur',   () => { ... });
+element.on('ready',  () => { ... });
+element.on('loaderror', (payload: { elementType: string; error: string }) => { ... });
+```
+
+`ElementChangeEvent`:
+
+| Field | Type | Description |
+|---|---|---|
+| `empty` | `boolean` | `true` when the field is empty. |
+| `complete` | `boolean` | `true` when the field has enough digits to be complete. |
+| `valid` | `boolean` | `true` when the value passes all validation (Luhn, expiry date, etc.). |
+| `error` | `string \| undefined` | User-facing error message when `valid` is `false` and the field has been touched. |
+| `cardBrand` | `string \| undefined` | Detected brand — only on `cardNumber` fields (e.g. `"visa"`, `"amex"`). |
+| `month` | `string \| undefined` | Parsed 2-digit month — only on `expirationDate` fields. |
+| `year` | `string \| undefined` | Parsed 2-digit year — only on `expirationDate` fields. |
+
+> **Expiry data and PCI scope:** The expiry `onChange` event delivers parsed `month` and `year` to your handler for display purposes (e.g. "Card expires MM/YY"). These are not PANs or CVVs, but they are cardholder data. If your PCI scope requires zero cardholder data on the merchant page, do not read, log, or store these fields.
+
+Auto-advance is built in: the vault automatically moves focus from card number → expiry → CVV when each field completes. No additional code required.
+
+---
+
+## React API
+
+> 📖 [React guide](https://docs.ozura.com/sdks/elements/react) — `OzElements` provider, `useOzElements` hook, pre-built `OzCard` and `OzBankCard` components, and StrictMode behaviour.
+
+### OzElements provider
+
+```tsx
+import { OzElements, createFetchWaxKey } from '@ozura/elements/react';
+
+<OzElements
+  pubKey="pk_live_..."
+  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+  appearance={{ theme: 'flat', variables: { colorPrimary: '#6366f1' } }}
+  onLoadError={() => setPaymentUnavailable(true)}
+>
+  {children}
+</OzElements>
+```
+
+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.
+
+> **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.
+
+---
+
+### OzCard
+
+Drop-in combined card component. Renders card number, expiry, and CVV with a configurable layout.
+
+```tsx
+import { OzCard } from '@ozura/elements/react';
+
+<OzCard
+  layout="default"       // "default" (number on top, expiry+CVV below) | "rows" (stacked)
+  onChange={(state) => {
+    // state.complete   — all three fields complete + valid
+    // state.cardBrand  — detected brand
+    // state.error      — first error across all fields
+    // state.fields     — per-field ElementChangeEvent objects
+  }}
+  onReady={() => console.log('all card fields loaded')}
+  disabled={isSubmitting}
+  labels={{ cardNumber: 'Card Number', expiry: 'Expiry', cvv: 'CVV' }}
+  placeholders={{ cardNumber: '1234 5678 9012 3456', expiry: 'MM/YY', cvv: '···' }}
+/>
+```
+
+`OzCardProps` (full):
+
+| Prop | Type | Description |
+|---|---|---|
+| `layout` | `'default' \| 'rows'` | `'default'`: number full-width, expiry+CVV side by side. `'rows'`: all stacked. |
+| `gap` | `number \| string` | Gap between fields. Default: `8` (px). |
+| `style` | `ElementStyleConfig` | Shared style applied to all three inputs. |
+| `styles` | `{ cardNumber?, expiry?, cvv? }` | Per-field overrides merged on top of `style`. |
+| `classNames` | `{ cardNumber?, expiry?, cvv?, row? }` | CSS class names for field wrappers and the expiry+CVV row. |
+| `labels` | `{ cardNumber?, expiry?, cvv? }` | Optional label text above each field. |
+| `labelStyle` | `React.CSSProperties` | Style applied to all `<label>` elements. |
+| `labelClassName` | `string` | Class applied to all `<label>` elements. |
+| `placeholders` | `{ cardNumber?, expiry?, cvv? }` | Custom placeholder text per field. |
+| `hideErrors` | `boolean` | Suppress the built-in error display. Handle via `onChange`. |
+| `errorStyle` | `React.CSSProperties` | Style for the built-in error container. |
+| `errorClassName` | `string` | Class for the built-in error container. |
+| `renderError` | `(error: string) => ReactNode` | Custom error renderer. |
+| `onChange` | `(state: OzCardState) => void` | Fires on any field change. |
+| `onReady` | `() => void` | Fires once all three iframes have loaded. |
+| `onFocus` | `(field: 'cardNumber' \| 'expiry' \| 'cvv') => void` | |
+| `onBlur` | `(field: 'cardNumber' \| 'expiry' \| 'cvv') => void` | |
+| `disabled` | `boolean` | Disable all inputs. |
+| `className` | `string` | Class for the outer wrapper. |
+
+---
+
+### Individual field components
+
+For custom layouts where `OzCard` is too opinionated:
+
+```tsx
+import { OzCardNumber, OzExpiry, OzCvv } from '@ozura/elements/react';
+
+<OzCardNumber onChange={handleChange} placeholder="Card number" />
+<OzExpiry     onChange={handleChange} />
+<OzCvv        onChange={handleChange} />
+```
+
+All accept `OzFieldProps`:
+
+| Prop | Type | Description |
+|---|---|---|
+| `style` | `ElementStyleConfig` | Input styles. |
+| `placeholder` | `string` | Placeholder text. |
+| `disabled` | `boolean` | Disables the input. |
+| `loadTimeoutMs` | `number` | Iframe load timeout in ms. |
+| `onChange` | `(event: ElementChangeEvent) => void` | |
+| `onFocus` | `() => void` | |
+| `onBlur` | `() => void` | |
+| `onReady` | `() => void` | |
+| `onLoadError` | `(error: string) => void` | |
+| `className` | `string` | Class for the outer wrapper div. |
+
+---
+
+### OzBankCard
+
+```tsx
+import { OzBankCard } from '@ozura/elements/react';
+
+<OzBankCard
+  onChange={(state) => {
+    // state.complete, state.error, state.fields.accountNumber, state.fields.routingNumber
+  }}
+  labels={{ accountNumber: 'Account Number', routingNumber: 'Routing Number' }}
+/>
+```
+
+Or use individual bank components:
+
+```tsx
+import { OzBankAccountNumber, OzBankRoutingNumber } from '@ozura/elements/react';
+
+<OzBankAccountNumber onChange={handleChange} />
+<OzBankRoutingNumber onChange={handleChange} />
+```
+
+---
+
+### useOzElements()
+
+```ts
+const { createToken, createBankToken, ready, initError, tokenizeCount } = useOzElements();
+```
+
+Must be called from inside an `<OzElements>` provider tree.
+
+| Return | Type | Description |
+|---|---|---|
+| `createToken` | `(options?: TokenizeOptions) => Promise<TokenResponse>` | Tokenize mounted card elements. |
+| `createBankToken` | `(options: BankTokenizeOptions) => Promise<BankTokenResponse>` | Tokenize mounted bank elements. |
+| `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`. |
+
+> **`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.
+
+---
+
+## Styling
+
+> 📖 [Styling guide](https://docs.ozura.com/sdks/elements/styling) — full property allowlist, theme variables, `appearance` options, custom fonts, and `var()` limitations.
+
+### Per-element styles
+
+Styles apply inside each iframe's `<input>` element. Only an explicit allowlist of CSS properties is accepted (typography, spacing, borders, box-shadow, cursor, transitions). Values containing `url()`, `var()`, `expression()`, `javascript:`, or CSS breakout characters are blocked on both the SDK and iframe sides. Use literal values instead of CSS custom properties (`var(--token)` is rejected). When a value is stripped, the browser falls back to the element's default (unstyled) appearance for that property — the failure is silent with no error or console warning. Resolve design tokens to literal values before passing them in.
+
+```ts
+const style: ElementStyleConfig = {
+  base: {
+    color:           '#1a1a1a',
+    fontSize:        '16px',
+    fontFamily:      '"Inter", sans-serif',
+    padding:         '10px 12px',
+    backgroundColor: '#ffffff',
+    borderRadius:    '6px',
+    border:          '1px solid #d1d5db',
+  },
+  focus: {
+    borderColor: '#6366f1',
+    boxShadow:   '0 0 0 3px rgba(99,102,241,0.15)',
+    outline:     'none',
+  },
+  invalid: {
+    borderColor: '#ef4444',
+    color:       '#dc2626',
+  },
+  complete: {
+    borderColor: '#22c55e',
+  },
+  placeholder: {
+    color: '#9ca3af',
+  },
+};
+```
+
+State precedence: `placeholder` applies to the `::placeholder` pseudo-element. `focus`, `invalid`, and `complete` merge on top of `base`.
+
+### Global appearance
+
+Apply a preset theme and/or variable overrides to all elements at once:
+
+```ts
+// OzVault.create
+const vault = await OzVault.create({
+  pubKey: '...',
+  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  appearance: {
+    theme: 'flat',                    // 'default' | 'night' | 'flat'
+    variables: {
+      colorText:        '#1a1a1a',
+      colorBackground:  '#ffffff',
+      colorPrimary:     '#6366f1',    // focus caret + color
+      colorDanger:      '#dc2626',    // invalid state
+      colorSuccess:     '#16a34a',    // complete state
+      colorPlaceholder: '#9ca3af',
+      fontFamily:       '"Inter", sans-serif',
+      fontSize:         '15px',
+      fontWeight:       '400',
+      padding:          '10px 14px',
+      letterSpacing:    '0.01em',
+    },
+  },
+});
+
+// React provider
+<OzElements pubKey="..." fetchWaxKey={...} appearance={{ theme: 'night' }}>
+```
+
+Per-element `style` takes precedence over `appearance` variables.
+
+> **`appearance: {}` is not "no theme":** Passing `appearance: {}` or `appearance: { variables: { ... } }` without a `theme` key applies the `'default'` preset as a base. To render elements with no preset styling, omit `appearance` entirely and use per-element `style` overrides.
+>
+> | `appearance` value | Result |
+> |---|---|
+> | *(omitted entirely)* | No preset — element uses minimal built-in defaults |
+> | `{}` | Equivalent to `{ theme: 'default' }` — full default theme applied |
+> | `{ theme: 'night' }` | Night theme |
+> | `{ variables: { colorText: '#333' } }` | Default theme + variable overrides |
+
+### Custom fonts
+
+Fonts are injected into each iframe so they render inside the input fields:
+
+```ts
+fonts: [
+  // Google Fonts or any HTTPS CSS URL
+  { cssSrc: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap' },
+
+  // Custom @font-face
+  {
+    family:  'BrandFont',
+    src:     'url(https://cdn.example.com/brand-font.woff2)',
+    weight:  '400',
+    style:   'normal',
+    display: 'swap',
+  },
+]
+```
+
+Font `src` values must start with `url(https://...)`. HTTP and data URIs are rejected.
+
+---
+
+## Billing details
+
+```ts
+interface BillingDetails {
+  firstName: string;   // 1–50 characters
+  lastName:  string;   // 1–50 characters
+  email?:    string;   // Valid email, max 50 characters
+  phone?:    string;   // E.164 format, e.g. "+15551234567", max 50 characters
+  address?: {
+    line1:   string;   // 1–50 characters
+    line2?:  string;   // Optional, omitted from cardSale if blank
+    city:    string;   // 1–50 characters
+    state:   string;   // For US/CA: normalized to 2-letter abbreviation
+    zip:     string;   // 1–50 characters
+    country: string;   // ISO 3166-1 alpha-2, e.g. "US"
+  };
+}
+```
+
+Billing is validated and normalized by both `vault.createToken()` and the server-side handler factories. `TokenResponse.billing` contains the normalized result ready to spread into a `cardSale` call.
+
+---
+
+## 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.
+
+All SDK errors are instances of `OzError`:
+
+```ts
+import { OzError } from '@ozura/elements';
+
+try {
+  const { token } = await vault.createToken({ billing });
+} catch (err) {
+  if (err instanceof OzError) {
+    switch (err.errorCode) {
+      case 'network':     // Connection failure — show retry UI
+      case 'timeout':     // 30s deadline exceeded — safe to retry
+      case 'server':      // 5xx from vault — transient, safe to retry
+        if (err.retryable) showRetryPrompt();
+        break;
+
+      case 'auth':        // Bad pub key / API key — configuration issue
+      case 'validation':  // Bad card data — show field-level error
+      case 'config':      // frameBaseUrl not in permitted allowlist
+      case 'unknown':
+        showError(err.message);
+        break;
+    }
+  }
+}
+```
+
+`OzError` fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable, consumer-facing error message. |
+| `errorCode` | `OzErrorCode` | `'network' \| 'timeout' \| 'auth' \| 'validation' \| 'server' \| 'config' \| 'unknown'` |
+| `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.
+
+**Error normalisation helpers** (for displaying errors from `cardSale` to users):
+
+```ts
+import { normalizeVaultError, normalizeBankVaultError, normalizeCardSaleError } from '@ozura/elements';
+
+// Maps vault tokenize error strings to user-facing copy
+const display = normalizeVaultError(err.raw);       // card flows
+const display = normalizeBankVaultError(err.raw);   // bank/ACH flows
+const display = normalizeCardSaleError(err.message); // cardSale API errors
+```
+
+---
+
+## Server utilities
+
+> 📖 [Server SDK guide](https://docs.ozura.com/sdks/elements/server) — `Ozura` class methods, route handler factories, `getClientIp`, error types, and rate limits.
+
+### Ozura class
+
+```ts
+import { Ozura, OzuraError } 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!,
+  // apiUrl:   'https://api.ozura.com',  // override Pay API URL
+  // vaultUrl: 'https://vault.ozura.com', // override vault URL
+  timeoutMs: 30000,    // default
+  retries:   2,        // max retry attempts for 5xx/network errors (3 total attempts)
+});
+```
+
+> **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.
+>
+> ```ts
+> const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
+> ```
+
+**Methods:**
+
+```ts
+// Charge a tokenized card
+const result = await ozura.cardSale({
+  token:           tokenResponse.token,
+  cvcSession:      tokenResponse.cvcSession,
+  amount:          '49.00',
+  currency:        'USD',          // default: 'USD'
+  billing:         tokenResponse.billing,
+  clientIpAddress: '1.2.3.4',     // fetch server-side, never from the browser
+  // surchargePercent, tipAmount, salesTaxExempt, processor
+});
+// result.transactionId, result.amount, result.cardLastFour, result.cardBrand
+// result.surchargeAmount and result.tipAmount are optional — only present when non-zero
+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)
+});
+
+// Revoke a wax key — 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);
+
+// 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
+
+// 2. User cancels checkout
+router.post('/api/cancel', async (req) => {
+  const { waxKey } = await db.session.get(req.sessionId);
+  await ozura.revokeWaxKey(waxKey);
+  return Response.json({ ok: true });
+});
+
+// 3. Page/tab close (best-effort — browser may not deliver this)
+//    Use sendBeacon so the request survives navigation / tab close.
+window.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'hidden') {
+    navigator.sendBeacon('/api/cancel', JSON.stringify({ sessionId }));
+  }
+});
+
+// List transactions
+const { transactions, pagination } = await ozura.listTransactions({
+  dateFrom:        '2025-01-01',
+  dateTo:          '2025-12-31',
+  transactionType: 'CreditCardSale',
+  page:            1,
+  limit:           50,
+});
+```
+
+**`OzuraError`** (thrown by all `Ozura` methods):
+
+```ts
+try {
+  await ozura.cardSale(input);
+} catch (err) {
+  if (err instanceof OzuraError) {
+    err.statusCode;   // HTTP status code
+    err.message;      // Normalized message
+    err.raw;          // Raw API response string
+    err.retryAfter;   // Seconds (only present on 429)
+  }
+}
+```
+
+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.
+
+---
+
+### Route handler factories
+
+The server package exports four 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` |
+| `createCardSaleHandler` | Fetch API | `POST /api/charge` |
+| `createCardSaleMiddleware` | Express / Connect | `POST /api/charge` |
+
+`createCardSaleHandler` / `createCardSaleMiddleware` accept a `CardSaleHandlerOptions` object:
+
+```ts
+interface CardSaleHandlerOptions {
+  /**
+   * Required. Return the charge amount as a decimal string.
+   * Never trust the amount from the request body — resolve it from your database.
+   */
+  getAmount: (body: Record<string, unknown>) => Promise<string>;
+
+  /**
+   * Optional. Return the ISO 4217 currency code. Default: "USD".
+   */
+  getCurrency?: (body: Record<string, unknown>) => Promise<string>;
+}
+```
+
+Both handler factories validate `Content-Type: application/json`, run `validateBilling()`, extract the client IP from standard proxy headers, and return normalized `{ transactionId, amount, cardLastFour, cardBrand }` on success.
+
+---
+
+## Local development
+
+The repository includes a development server at `dev-server.mjs` that serves the built frame assets and proxies vault API requests:
+
+```bash
+npm run dev   # build + start dev server on http://localhost:4242
+```
+
+Set `frameBaseUrl` to point your vault at the local server:
+
+```ts
+const vault = await OzVault.create({
+  pubKey: 'pk_test_...',
+  fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+  frameBaseUrl: 'http://localhost:4242',  // local dev only
+});
+```
+
+Or in React:
+
+```tsx
+<OzElements
+  pubKey="pk_test_..."
+  fetchWaxKey={createFetchWaxKey('/api/mint-wax')}
+  frameBaseUrl="http://localhost:4242"
+>
+```
+
+Configure environment variables for the dev server:
+
+```bash
+VAULT_URL=https://vault-staging.example.com
+VAULT_API_KEY=vk_test_...
+```
+
+---
+
+## Content Security Policy
+
+The SDK loads iframes from the Ozura frame origin. Add the following directives to your CSP:
+
+```
+frame-src https://elements.ozura.com;
+```
+
+If loading custom fonts via `fonts[].cssSrc`, also allow the font stylesheet origin:
+
+```
+style-src  https://fonts.googleapis.com;
+font-src   https://fonts.gstatic.com;
+```
+
+To verify your CSP after a build:
+
+```bash
+npm run check:csp
+```
+
+---
+
+## TypeScript reference
+
+> 📖 [API reference](https://docs.ozura.com/sdks/elements/api-reference) — every interface, union, and enum fully annotated with JSDoc.
+
+All public types are exported from `@ozura/elements`:
+
+```ts
+import type {
+  // Element types
+  ElementType,           // 'cardNumber' | 'cvv' | 'expirationDate'
+  BankElementType,       // 'accountNumber' | 'routingNumber'
+  ElementOptions,
+  ElementStyleConfig,
+  ElementStyle,
+  ElementChangeEvent,
+
+  // Vault config
+  VaultOptions,
+  FontSource,
+  CssFontSource,
+  CustomFontSource,
+  Appearance,
+  AppearanceVariables,
+  OzTheme,               // 'default' | 'night' | 'flat'
+
+  // Tokenization
+  TokenizeOptions,
+  BankTokenizeOptions,
+  TokenResponse,
+  BankTokenResponse,
+  CardMetadata,
+  BankAccountMetadata,
+
+  // Billing
+  BillingDetails,
+  BillingAddress,
+
+  // Card sale
+  CardSaleRequest,
+  CardSaleResponseData,
+  CardSaleApiResponse,
+
+  // Transactions
+  TransactionQueryParams,
+  TransactionQueryPagination,
+  TransactionQueryResponse,
+  TransactionType,
+  TransactionData,
+  CardTransactionData,
+  AchTransactionData,
+  CryptoTransactionData,
+
+  // Errors
+  OzErrorCode,
+} from '@ozura/elements';
+```
+
+Server-specific types are exported from `@ozura/elements/server`:
+
+```ts
+import type {
+  OzuraConfig,
+  CardSaleInput,
+  MintWaxKeyOptions,
+  MintWaxKeyResult,
+  ListTransactionsInput,
+} from '@ozura/elements/server';
+```
+
+React-specific types are exported from `@ozura/elements/react`:
+
+```ts
+import type { OzFieldProps, OzCardProps, OzCardState, OzBankCardProps, OzBankCardState } from '@ozura/elements/react';
+```
+
+---
+
+## Need help?
+
+The full documentation — including interactive examples, a complete API reference, and integration walkthroughs — lives at:
+
+**[docs.ozura.com/sdks/elements/overview](https://docs.ozura.com/sdks/elements/overview)**
+
+| I want to… | Go to |
+|---|---|
+| Get started from scratch | [Installation](https://docs.ozura.com/sdks/elements/installation) |
+| Build a card payment form | [Card elements](https://docs.ozura.com/sdks/elements/card-elements) |
+| Build an ACH / bank form | [Bank elements](https://docs.ozura.com/sdks/elements/bank-elements) |
+| Use the React components | [React guide](https://docs.ozura.com/sdks/elements/react) |
+| Style the input fields | [Styling](https://docs.ozura.com/sdks/elements/styling) |
+| Handle errors correctly | [Error handling](https://docs.ozura.com/sdks/elements/error-handling) |
+| Set up the server side | [Server SDK](https://docs.ozura.com/sdks/elements/server) |
+| Look up a type or method | [API reference](https://docs.ozura.com/sdks/elements/api-reference) |