@ozura/elements 0.1.0-beta.7 → 1.0.0

package/README.md

@@ -1,887 +1,1121 @@
-# OzElements
-
-PCI-compliant card tokenization SDK for the Ozura Vault.
-
-OzElements renders secure, iframe-isolated card input fields on your page and tokenizes card data directly to the Ozura Vault. Your JavaScript never touches raw card numbers, CVVs, or expiry dates — the iframes handle everything. You get back a token. Use it with your own payment processor, your own backend systems, or with the Ozura Pay API.
-
-You need a **vault public key** (`pk_…`) for the browser SDK and your **vault API key** on the server only — it mints short-lived **wax keys** so the secret never reaches the browser. **Integration expectations and examples are in this README** (section [Wax keys (merchant integration)](#wax-keys-merchant-integration)). [WAX_KEY_IMPLEMENTATION.md](./WAX_KEY_IMPLEMENTATION.md) is an optional deep dive (design history, dev server, security notes).
-
----
-
-## Why this exists
-
-If you need to collect card data, you have a PCI compliance problem. OzElements solves it.
-
-The Ozura Vault stores and tokenizes sensitive card data. OzElements is the frontend SDK for the vault — it gives you drop-in card fields that are fully isolated inside Ozura-controlled iframes. Your page never sees raw card data, which keeps your PCI scope minimal (SAQ-A).
-
-**You don't need to be an OzuraPay merchant to use this.** You need vault credentials: a **public key** for the browser and the **vault API key** on your server (for minting wax only). Once you have a token, you can use it however you want — with your own processor, your own systems, or optionally with the Ozura Pay API.
-
----
-
-## How it works
-
-```
-Your page (yoursite.com)
-│
-│  import { OzVault } from '@ozura/elements'
-│
-│  const vault = await OzVault.create({ pubKey, fetchWaxKey });
-│
-│  const cardNumber = vault.createElement('cardNumber', { style: { ... } });
-│  cardNumber.mount('#card-number');
-│  cardNumber.on('change', ({ valid, cardBrand }) => { ... });
-│
-│  const { token, cvcSession } = await vault.createToken();
-│  // token is yours — use it with any system
-│
-├── <iframe src="https://elements.ozura.com/frame/element-frame.html">
-│     <input type="tel" />   ← your JS cannot access this
-│   </iframe>
-│
-└── <iframe style="display:none" src="https://elements.ozura.com/frame/tokenizer-frame.html">
-      Receives raw values from element iframes (same-origin).
-      POSTs directly to vault /tokenize.
-      Returns token + cvcSession to the SDK.
-    </iframe>
-```
-
-Raw card data travels one path: element iframe → tokenizer iframe (direct same-origin `postMessage`). Your SDK only ever sees metadata (valid/complete/cardBrand) and the final token.
-
-The tokenizer POSTs to the vault with **`X-Wax-Key`** (minted on your backend). The vault secret must **never** appear in the browser or in tokenize requests.
-
----
-
-## Installation
-
-```bash
-npm install @ozura/elements
-```
-
-Or via script tag (UMD) from jsDelivr (served from npm after you publish):
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@ozura/elements/dist/oz-elements.umd.js"></script>
-```
-
-For production, pin a version: `.../npm/@ozura/elements@1.0.0/dist/oz-elements.umd.js`
-
----
-
-## Quick start
-
-```js
-import { OzVault } from '@ozura/elements';
-
-const vault = await OzVault.create({
-  pubKey: 'your_pub_key',
-  fetchWaxKey: async (sessionId) => {
-    // Your backend mints a session-bound wax key using the vault secret
-    const { waxKey } = await fetch('/api/mint-wax', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ sessionId }),
-    }).then(r => r.json());
-    return waxKey;
-  },
-});
-
-const cardNumber = vault.createElement('cardNumber', {
-  style: {
-    base:    { color: '#1a1a2e', fontSize: '16px', fontFamily: 'Inter, sans-serif' },
-    focus:   { color: '#1a1a2e' },
-    invalid: { color: '#dc2626' },
-  },
-});
-
-const expiry = vault.createElement('expirationDate');
-const cvv    = vault.createElement('cvv');
-
-cardNumber.mount('#card-number');
-expiry.mount('#expiry');
-cvv.mount('#cvv');
-
-cardNumber.on('change', ({ valid, complete, cardBrand }) => {
-  console.log(cardBrand); // 'visa' | 'mastercard' | 'amex' | ...
-});
-
-document.getElementById('tokenize').addEventListener('click', async () => {
-  const { token, cvcSession } = await vault.createToken();
-
-  console.log('Token:', token);
-  console.log('CVC Session:', cvcSession);
-
-  // The token is yours — send it to your backend and use it however you want:
-  // • With your own payment processor
-  // • With the Ozura Pay API (see "OzuraPay integration" below)
-  // • With any system that accepts tokenized card data
-  await fetch('/api/tokenized', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ token, cvcSession }),
-  });
-});
-```
-
----
-
-## Wax keys (merchant integration)
-
-The vault `/tokenize` call must not use your vault secret from the browser. Instead:
-
-1. During `OzVault.create()`, the SDK generates a `sessionId` (UUID) and calls **`fetchWaxKey(sessionId)`** once.
-2. Your **`fetchWaxKey`** implementation should `POST` to **your** backend (e.g. `/api/mint-wax`) with that `sessionId`.
-3. Your backend uses the **vault API key only on the server** to mint a short-lived **wax key** from the vault, then returns `{ waxKey }` to the browser.
-4. The hidden tokenizer iframe sends **`X-Wax-Key`** (and related headers) to the vault — **never `X-API-Key`**.
-
-### Vault mint contract (your backend → vault)
-
-Your server calls the vault (the SDK’s `Ozura.mintWaxKey` does this for you):
-
-| | |
-|---|---|
-| **Method / URL** | `POST {vaultBaseUrl}/internal/wax-session` |
-| **Auth** | `X-API-Key: <vault API key>` (server only) |
-| **Body** | `{ "checkout_session_id": "<sessionId>" }` — optional; correlates with the SDK session. `{}` is valid. |
-| **Success** | HTTP **201** · `{ "data": { "wax_key": "<uuid>", "expires_in_seconds": 1800 } }` (TTL is typically 30 minutes) |
-| **Errors** | JSON such as `{ "message", "error_code" }` — treat like any API error |
-
-If your vault hostname differs from the default used by published iframe builds, pass **`vaultUrl`** on `Ozura` so mint/revoke hit the correct host.
-
-### One-line handlers (`@ozura/elements/server`)
-
-Both helpers accept **`sessionId`** or **`tokenizationSessionId`** in the JSON body. They respond with **`{ waxKey }`** on success.
-
-**Next.js App Router** (or any runtime with `Request` / `Response`):
-
-```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!,
-  // vaultUrl: process.env.VAULT_URL,  // optional override
-});
-
-export const POST = createMintWaxHandler(ozura);
-```
-
-**Express** (register JSON body parsing **before** the middleware):
-
-```ts
-import express from 'express';
-import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
-
-const app = express();
-const ozura = new Ozura({
-  merchantId: process.env.MERCHANT_ID!,
-  apiKey:     process.env.MERCHANT_API_KEY!,
-  vaultKey:   process.env.VAULT_API_KEY!,
-});
-
-app.use(express.json());
-app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
-```
-
-### Manual route
-
-Use this if you need to persist `waxKey` server-side for later revocation:
-
-```ts
-app.post('/api/mint-wax', async (req, res) => {
-  const sessionId = req.body?.sessionId ?? req.body?.tokenizationSessionId;
-  const { waxKey, expiresInSeconds } = await ozura.mintWaxKey(
-    typeof sessionId === 'string' && sessionId
-      ? { tokenizationSessionId: sessionId }
-      : {},
-  );
-  // await saveWaxForSession(sessionId, waxKey);
-  res.json({ waxKey });
-});
-```
-
-`mintWaxKey` throws **`OzuraError`** on failure (vault 4xx/5xx). The one-line handlers catch that and respond with **`{ error: string }`**: HTTP status is the vault status when ≥ 400, otherwise **502** (e.g. network failure).
-
-### Browser: handle mint failures
-
-Check the response from your mint endpoint before calling `createToken`:
-
-```js
-fetchWaxKey: async (sessionId) => {
-  const res = await fetch('/api/mint-wax', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ sessionId }),
-  });
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) {
-    throw new Error(typeof data.error === 'string' ? data.error : 'Could not mint wax key');
-  }
-  if (!data.waxKey) throw new Error('Mint response missing waxKey');
-  return data.waxKey;
-},
-```
-
-### Optional: revoke when the checkout session ends
-
-To shorten exposure before TTL, call **`await ozura.revokeWaxKey(waxKey)`** from your server when the session completes successfully, the user cancels, or your session times out. It is best-effort (does not throw). **Do not** revoke on card decline — the user may fix the card and call `createToken()` again without a full new `OzVault.create()`.
-
-### Expired or consumed wax
-
-If tokenization fails with an auth-style error after the wax key expired or was consumed, create a **new** vault instance: `await OzVault.create({ pubKey, fetchWaxKey })` so `fetchWaxKey` runs again.
-
-### More detail
-
-[WAX_KEY_IMPLEMENTATION.md](./WAX_KEY_IMPLEMENTATION.md) covers revocation scenarios, local dev-server behaviour, and security notes in depth.
-
----
-
-## API
-
-### `OzVault.create(options)`
-
-Returns `Promise<OzVault>`. The static factory is the only way to create a vault — the constructor is private.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `options.pubKey` | `string` | required | System pub key for the tokenize endpoint. Obtain from Ozura admin. |
-| `options.fetchWaxKey` | `(sessionId: string) => Promise<string>` | required | Called once during `create()`. Receives an SDK-generated session UUID; your implementation passes it to your backend, which mints a session-bound wax key from the vault using your vault secret. Returns the wax key string. |
-| `options.frameBaseUrl` | `string` | `https://elements.ozura.com` | Where iframe assets are served from |
-| `options.fonts` | `FontSource[]` | `[]` | Custom fonts to inject into element iframes |
-| `options.appearance` | `ElementStyleConfig` | — | Default style applied to all created elements |
-| `options.onLoadError` | `() => void` | — | Called if the tokenizer iframe fails to load within `loadTimeoutMs` |
-| `options.loadTimeoutMs` | `number` | `10000` | Timeout in ms before `onLoadError` fires |
-
-Implement **`/api/mint-wax`** on your server using `@ozura/elements/server` — see [Wax keys (merchant integration)](#wax-keys-merchant-integration) for Next.js, Express, manual mint, errors, and optional revocation.
-
-### `vault.createElement(type, options?)`
-
-`type`: `'cardNumber'` | `'cvv'` | `'expirationDate'`
-
-| Option | Type | Description |
-|---|---|---|
-| `style.base` | `object` | CSS properties applied by default |
-| `style.focus` | `object` | CSS properties applied on focus |
-| `style.invalid` | `object` | CSS properties applied when input is invalid |
-| `placeholder` | `string` | Override default placeholder text |
-| `disabled` | `boolean` | Disable the input |
-
-### `vault.createToken(options?)`
-
-Triggers tokenization across all mounted elements. Returns a Promise with the vault token.
-
-```ts
-// Minimal — just tokenize the card data
-const { token, cvcSession } = await vault.createToken();
-
-// With billing — validates and normalizes billing details alongside tokenization.
-// Useful if you plan to pass billing to a payment API (e.g. Ozura Pay API).
-const { token, cvcSession, billing } = await vault.createToken({
-  billing: {
-    firstName: string;       // required, 1–50 chars
-    lastName: string;        // required, 1–50 chars
-    email?: string;          // valid address, max 50 chars
-    phone?: string;          // E.164 format e.g. "+15551234567"
-    address?: {
-      line1: string;         // required if address provided
-      line2?: string;        // omitted from output if blank
-      city: string;
-      state: string;         // "California" auto-normalised → "CA" for US/CA
-      zip: string;
-      country: string;       // ISO 3166-1 alpha-2, e.g. "US"
-    };
-  };
-
-  // Deprecated — use billing.firstName/lastName instead:
-  firstName?: string;
-  lastName?: string;
-});
-```
-
-`TokenResponse` fields:
-
-| Field | Description |
-|---|---|
-| `token` | Vault token referencing the stored card data |
-| `cvcSession` | CVC session ID for use with payment APIs |
-| `billing` | Validated, normalized billing details (only present when `billing` was passed) |
-
-**Validation** thrown as `OzError` before any network call: empty firstName/lastName, fields > 50 chars, invalid email format, non-E.164 phone, address fields 0 or > 50 chars.
-
-### `vault.isReady`
-
-`boolean` — `true` once the hidden tokenizer iframe has loaded. For React, use the `ready` value from `useOzElements()` instead (which also tracks field iframe readiness).
-
-### `vault.destroy()`
-
-Tears down the vault completely: removes the global message listener, rejects any in-flight `createToken()` promises, unmounts all element iframes, and removes the tokenizer iframe. Call this when your checkout component unmounts.
-
-```js
-// React useEffect cleanup / SPA route change
-return () => vault.destroy();
-```
-
-### `element.mount(target)`
-
-Injects the element iframe into a container. Accepts either a CSS selector string or a direct `HTMLElement` reference (required when using React refs).
-
-```js
-element.mount('#card-number');        // CSS selector
-element.mount(containerRef.current); // HTMLElement (React)
-```
-
-### `element.unmount()`
-
-Removes the iframe from the DOM and resets internal state. Called automatically by `vault.destroy()`. Safe to call manually when swapping payment methods in a SPA.
-
-### `element.on(event, callback)`
-
-| Event | Payload | Description |
-|---|---|---|
-| `ready` | — | Iframe loaded and initialised |
-| `change` | `ElementChangeEvent` | Input value changed |
-| `focus` | — | Input focused |
-| `blur` | — | Input blurred |
-
-**`ElementChangeEvent` shape:**
-
-| Field | Type | Present on |
-|---|---|---|
-| `empty` | `boolean` | all elements |
-| `complete` | `boolean` | all elements |
-| `valid` | `boolean` | all elements |
-| `error` | `string \| undefined` | all — set when complete but invalid |
-| `cardBrand` | `string \| undefined` | `cardNumber` only |
-| `month` | `string \| undefined` | `expirationDate` only (`"01"`–`"12"`) |
-| `year` | `string \| undefined` | `expirationDate` only (2-digit, e.g. `"27"`) |
-
-### `element.clear()`
-
-Clears the current value in the iframe input and resets validation state.
-
-### `element.update(options)`
-
-Updates `style`, `placeholder`, or `disabled` on a mounted element without remounting the iframe.
-
----
-
-## Server SDK (`@ozura/elements/server`)
-
-Import `Ozura` and optional wax helpers from `@ozura/elements/server`:
-
-| Export | Role |
-|--------|------|
-| `new Ozura({ merchantId, apiKey, vaultKey, apiUrl?, vaultUrl?, … })` | Pay API (`cardSale`, `listTransactions`) and vault wax calls |
-| `ozura.mintWaxKey({ tokenizationSessionId? })` | `POST /internal/wax-session` — implement or use helpers below |
-| `ozura.revokeWaxKey(waxKey)` | Best-effort revoke when the checkout session ends |
-| `createMintWaxHandler(ozura)` | Fetch API handler (Next.js App Router, Workers, Edge) → `{ waxKey }` |
-| `createMintWaxMiddleware(ozura)` | Express / Connect middleware → `{ waxKey }` |
-| `getClientIp(req)` | Helper for `cardSale` client IP |
-
-See [Wax keys (merchant integration)](#wax-keys-merchant-integration) in this README for vault contract, examples, and client error handling. Extra depth (dev server, threat notes): [WAX_KEY_IMPLEMENTATION.md](./WAX_KEY_IMPLEMENTATION.md).
-
----
-
-## React
-
-```bash
-npm install @ozura/elements
-```
-
-Import from the `/react` subpath:
-
-```tsx
-import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from '@ozura/elements/react';
-```
-
-### Example
-
-```tsx
-import { useState } from 'react';
-import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from '@ozura/elements/react';
-import { normalizeCardSaleError } from '@ozura/elements';
-
-const fieldStyle = {
-  base:    { color: '#111827', fontSize: '16px', fontFamily: 'Inter, sans-serif' },
-  focus:   { color: '#111827' },
-  invalid: { color: '#dc2626' },
-};
-
-function CheckoutForm() {
-  const { createToken, ready } = useOzElements();
-
-  const [form, setForm] = useState({
-    firstName: '', lastName: '', email: '', phone: '',
-    address1: '', city: '', state: '', zip: '', country: 'US',
-  });
-  const [error, setError] = useState('');
-
-  const set = (field: string) => (e: React.ChangeEvent<HTMLInputElement>) =>
-    setForm(f => ({ ...f, [field]: e.target.value }));
-
-  const handlePay = async () => {
-    setError('');
-    try {
-      const { token, cvcSession, billing } = await createToken({
-        billing: {
-          firstName: form.firstName,
-          lastName:  form.lastName,
-          email:     form.email   || undefined,
-          phone:     form.phone   || undefined,
-          ...(form.address1 ? {
-            address: {
-              line1:   form.address1,
-              city:    form.city,
-              state:   form.state,
-              zip:     form.zip,
-              country: form.country.toUpperCase(),
-            },
-          } : {}),
-        },
-      });
-
-      // Send token + cvcSession + billing to your server → Ozura Pay API cardSale
-      const res = await fetch('/api/charge', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token, cvcSession, billing, amount: '49.00', currency: 'USD' }),
-      });
-
-      if (!res.ok) {
-        const data = await res.json();
-        setError(normalizeCardSaleError(data.error ?? 'Payment failed'));
-      }
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'An error occurred');
-    }
-  };
-
-  return (
-    <div>
-      {/* Billing fields — plain inputs, not PCI-sensitive */}
-      <input placeholder="First name" value={form.firstName} onChange={set('firstName')} />
-      <input placeholder="Last name"  value={form.lastName}  onChange={set('lastName')} />
-      <input placeholder="Email"      value={form.email}     onChange={set('email')} />
-      <input placeholder="Phone (+15551234567)" value={form.phone} onChange={set('phone')} />
-      <input placeholder="Street address" value={form.address1} onChange={set('address1')} />
-      <input placeholder="City"  value={form.city}    onChange={set('city')} />
-      <input placeholder="State" value={form.state}   onChange={set('state')} />
-      <input placeholder="ZIP"   value={form.zip}     onChange={set('zip')} />
-      <input placeholder="Country (US)" value={form.country} onChange={set('country')} maxLength={2} />
-
-      {/* Card fields — iframe-isolated, raw card data never touches this component */}
-      <OzCardNumber style={fieldStyle} />
-      <OzExpiry style={fieldStyle} />
-      <OzCvv style={fieldStyle} />
-
-      {error && <p style={{ color: 'red' }}>{error}</p>}
-      <button onClick={handlePay} disabled={!ready}>Pay $49.00</button>
-    </div>
-  );
-}
-
-export default function App() {
-  return (
-    <OzElements
-      pubKey="your_pub_key"
-      fetchWaxKey={async (sessionId) => {
-        const { waxKey } = await fetch('/api/mint-wax', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ sessionId }),
-        }).then(r => r.json());
-        return waxKey;
-      }}
-      frameBaseUrl="https://elements.ozura.com"
-    >
-      <CheckoutForm />
-    </OzElements>
-  );
-}
-```
-
-### `<OzElements>` props
-
-| Prop | Type | Description |
-|---|---|---|
-| `fetchWaxKey` | `(sessionId: string) => Promise<string>` | Called once on mount. Pass the received `sessionId` to your backend; your backend mints a wax key from the vault and returns it. |
-| `pubKey` | `string` | System pub key for the tokenize endpoint |
-| `frameBaseUrl` | `string?` | Where iframe assets are hosted |
-| `fonts` | `FontSource[]?` | Custom fonts to inject into element iframes |
-| `onLoadError` | `() => void?` | Called if vault init fails (fetchWaxKey error or tokenizer iframe timeout) |
-| `loadTimeoutMs` | `number?` | Timeout before `onLoadError` fires (default: 10 000) |
-| `appearance` | `Appearance?` | Global theme / variable overrides |
-
-### `useOzElements()` return
-
-| Value | Type | Description |
-|---|---|---|
-| `createToken` | `(opts?) => Promise<{ token, cvcSession }>` | Tokenizes all mounted fields |
-| `ready` | `boolean` | `true` when all field iframes have loaded |
-
-### Field component props (`OzCardNumber`, `OzExpiry`, `OzCvv`)
-
-| Prop | Type | Description |
-|---|---|---|
-| `style` | `ElementStyleConfig?` | `{ base, focus, invalid }` CSS property objects |
-| `placeholder` | `string?` | Override default placeholder |
-| `disabled` | `boolean?` | Disable the input |
-| `onChange` | `(e: ElementChangeEvent) => void` | Keystroke callback |
-| `onFocus` | `() => void` | Focus callback |
-| `onBlur` | `() => void` | Blur callback |
-| `onReady` | `() => void` | Iframe ready callback |
-| `className` | `string?` | CSS class on the wrapper `<div>` |
-
----
-
-## OzuraPay Integration (Optional)
-
-If you're an OzuraPay merchant and want to charge cards through Ozura's processors, you can use your vault tokens with the Ozura Pay API. **You must be onboarded as an OzuraPay merchant first** — this gives you a merchant ID and a Pay API key, which are required alongside your vault API key.
-
-| Credential | Where it goes |
-|-----------|---------------|
-| Vault API key | **Server only.** Browser calls `fetchWaxKey` → your backend mints a wax key with this secret; never send the secret in the browser. Pay API `cardSale` also sends it as `vault-api-key` from the server. |
-| Pay API key | Backend only: `x-api-key` header |
-| Merchant ID | Backend only: `merchantId` in request body |
-
-For the full credential setup, billing form field requirements, validation rules, and constraints, see [DOCS-REFRAME.md](./DOCS-REFRAME.md#using-tokens-with-ozurapay--prerequisites-and-credentials).
-
-### 1 — Collect card data + billing in one call
-
-```js
-import { OzVault, normalizeCardSaleError } from '@ozura/elements';
-
-const vault = await OzVault.create({
-  pubKey: 'your_pub_key',
-  fetchWaxKey: async (sessionId) => {
-    const { waxKey } = await fetch('/api/mint-wax', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ sessionId }),
-    }).then(r => r.json());
-    return waxKey;
-  },
-});
-
-// … mount card elements …
-
-async function handlePay(formValues) {
-  let tokenResult;
-  try {
-    tokenResult = await vault.createToken({
-      billing: {
-        firstName: formValues.firstName,    // validated 1–50 chars
-        lastName:  formValues.lastName,
-        email:     formValues.email,        // validated email format
-        phone:     formValues.phone,        // must be E.164: "+15551234567"
-        address: {
-          line1:   formValues.address1,
-          line2:   formValues.address2,     // omitted from output if blank
-          city:    formValues.city,
-          state:   formValues.state,        // "California" → "CA" auto-normalized
-          zip:     formValues.zip,
-          country: formValues.country,      // "US", "CA", "GB" …
-        },
-      },
-    });
-  } catch (err) {
-    // Validation errors thrown here — show directly to user
-    showError(err.message);
-    return;
-  }
-
-  const { token, cvcSession, billing } = tokenResult;
-
-  // 2 — Fetch client IP from your own server (never api.ipify.org — ad-blockers block it)
-  const ipRes = await fetch('/api/client-ip');
-  const { ip } = await ipRes.json();
-
-  // 3 — POST to your server, which calls cardSale
-  const res = await fetch('/api/charge', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      ozuraCardToken:  token,
-      ozuraCvcSession: cvcSession,
-      billingFirstName: billing.firstName,
-      billingLastName:  billing.lastName,
-      billingEmail:     billing.email,
-      billingPhone:     billing.phone,       // already E.164
-      billingAddress1:  billing.address.line1,
-      billingAddress2:  billing.address.line2, // omit key if undefined
-      billingCity:      billing.address.city,
-      billingState:     billing.address.state, // already 2-letter
-      billingZipcode:   billing.address.zip,
-      billingCountry:   billing.address.country,
-      clientIpAddress:  ip,
-      amount:           '49.00',
-      currency:         'USD',
-      salesTaxExempt:   false,
-      surchargePercent: '0.00',
-      tipAmount:        '0.00',
-    }),
-  });
-
-  const data = await res.json();
-
-  if (!res.ok) {
-    showError(normalizeCardSaleError(data.error ?? res.statusText));
-  } else {
-    showSuccess(data.transactionId);
-  }
-}
-```
-
-### 2 — Server-side cardSale call
-
-Your server proxies to the Ozura Pay API with **two API keys** in the headers:
-
-```js
-// Node.js / Express example
-import type { CardSaleRequest, CardSaleApiResponse } from '@ozura/elements';
-
-app.post('/api/charge', async (req, res) => {
-  const body = req.body;
-
-  const payload: CardSaleRequest = {
-    processor:        'elavon',
-    merchantId:       process.env.MERCHANT_ID,
-    amount:           body.amount,
-    currency:         body.currency,
-    ozuraCardToken:   body.ozuraCardToken,
-    ozuraCvcSession:  body.ozuraCvcSession,
-    billingFirstName: body.billingFirstName,
-    billingLastName:  body.billingLastName,
-    billingEmail:     body.billingEmail,
-    billingPhone:     body.billingPhone,
-    billingAddress1:  body.billingAddress1,
-    ...(body.billingAddress2 ? { billingAddress2: body.billingAddress2 } : {}),
-    billingCity:      body.billingCity,
-    billingState:     body.billingState,
-    billingZipcode:   body.billingZipcode,
-    billingCountry:   body.billingCountry,
-    clientIpAddress:  body.clientIpAddress,
-    salesTaxExempt:   body.salesTaxExempt,
-    surchargePercent: '0.00',
-    tipAmount:        '0.00',
-  };
-
-  const response = await fetch(`${process.env.OZURA_API_URL}/api/v1/cardSale`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-api-key':     process.env.MERCHANT_API_KEY,  // merchant Pay API key
-      'vault-api-key': process.env.VAULT_API_KEY,     // same key used in OzVault
-    },
-    body: JSON.stringify(payload),
-    signal: AbortSignal.timeout(30_000),
-  });
-
-  if (!response.ok) {
-    const err = await response.json().catch(() => ({}));
-    // Pass err.error through normalizeCardSaleError on the client side
-    return res.status(response.status).json({ error: err.error ?? 'cardSale failed' });
-  }
-
-  const result: CardSaleApiResponse = await response.json();
-
-  if (!result.success) {
-    return res.status(402).json({ error: 'Payment was not successful' });
-  }
-
-  const txn = result.data;
-
-  // ⚠️ Store txn.transactionId in your database NOW — before responding to the client.
-  // You need it for refunds and to prevent duplicate charges on network retry.
-  await db.transactions.insertOne({
-    transactionId:  txn.transactionId,
-    amount:         txn.amount,
-    currency:       txn.currency,
-    cardLastFour:   txn.cardLastFour,
-    cardBrand:      txn.cardBrand,
-    cardExpMonth:   txn.cardExpMonth,
-    cardExpYear:    txn.cardExpYear,
-    billingName:    `${txn.billingFirstName} ${txn.billingLastName}`,
-    transDate:      txn.transDate,
-    createdAt:      new Date(),
-  });
-
-  res.json({ transactionId: txn.transactionId, cardLastFour: txn.cardLastFour });
-});
-```
-
-### 3 — cardSale response shape
-
-```ts
-import type { CardSaleApiResponse, CardSaleResponseData } from '@ozura/elements';
-
-// Successful response shape from POST /api/v1/cardSale:
-// {
-//   success: true,
-//   data: {
-//     transactionId:  "txn_...",       ← store this immediately
-//     amount:         "49.00",
-//     currency:       "USD",
-//     surchargeAmount:"0.00",
-//     tipAmount:      "0.00",
-//     cardLastFour:   "4242",
-//     cardExpMonth:   "09",
-//     cardExpYear:    "2027",          ← 4-digit year
-//     cardBrand:      "visa",
-//     transDate:      "2026-02-20T...",
-//     ozuraMerchantId:"...",
-//     billingFirstName, billingLastName, billingEmail, billingPhone,
-//     billingAddress1, billingAddress2?, billingCity, billingState,
-//     billingZipcode, billingCountry
-//   }
-// }
-//
-// Error response (4xx/5xx): { error: string }
-// → pass error to normalizeCardSaleError() for a user-facing message
-```
-
-### 3 — Client IP endpoint
-
-The Pay API requires a real IP address. Fetch it server-side — do **not** use `api.ipify.org` from the client (blocked by most ad-blockers):
-
-```js
-app.get('/api/client-ip', (req, res) => {
-  const ip =
-    req.headers['x-forwarded-for']?.split(',')[0].trim() ??
-    req.socket.remoteAddress ??
-    '0.0.0.0';
-  res.json({ ip });
-});
-```
-
-### `normalizeCardSaleError(raw)`
-
-Maps raw Pay API error strings to user-friendly copy. Uses the same key table as the Ozura checkout frontend — identical errors produce identical messages on both surfaces:
-
-```js
-import { normalizeCardSaleError } from '@ozura/elements';
-
-normalizeCardSaleError('Insufficient Funds')
-// → "Your card has insufficient funds. Please use a different payment method."
-
-normalizeCardSaleError('CVV Verification Failed')
-// → "The CVV code you entered is incorrect. Please check and try again."
-
-normalizeCardSaleError('Card expired')
-// → "Your card has expired. Please use a different card."
-```
-
-### TypeScript: `CardSaleRequest`
-
-Import the interface to type your cardSale payload and catch missing fields at compile time:
-
-```ts
-import type { CardSaleRequest } from '@ozura/elements';
-
-const payload: CardSaleRequest = {
-  processor:        'elavon',
-  merchantId:       '…',
-  amount:           '49.00',
-  currency:         'USD',
-  ozuraCardToken:   token,
-  ozuraCvcSession:  cvcSession,
-  billingFirstName: billing.firstName,
-  billingLastName:  billing.lastName,
-  billingEmail:     billing.email!,
-  billingPhone:     billing.phone!,
-  billingAddress1:  billing.address!.line1,
-  billingCity:      billing.address!.city,
-  billingState:     billing.address!.state,
-  billingZipcode:   billing.address!.zip,
-  billingCountry:   billing.address!.country,
-  clientIpAddress:  ip,
-  salesTaxExempt:   false,
-  surchargePercent: '0.00',
-  tipAmount:        '0.00',
-};
-```
-
----
-
-## Testing
-
-```bash
-npm test               # run once
-npm run test:watch     # watch mode
-npm run test:coverage  # with V8 coverage report
-```
-
-The test suite covers: Luhn algorithm, card brand detection, card number formatting, expiry validation, and error normalisation.
-
----
-
-## Development
-
-```bash
-npm install
-npm run dev      # build + serve demo at http://localhost:4242/demo/index.html
-npm run watch    # rebuild on save
-npm run build    # production build
-```
-
-Build outputs in `dist/`:
-
-| File | Format | Use |
-|---|---|---|
-| `oz-elements.esm.js` | ESM | `import { OzVault } from '@ozura/elements'` |
-| `oz-elements.umd.js` | UMD | `<script>` tag / CDN |
-| `frame/element-frame.js` | IIFE | loaded by element iframes |
-| `frame/tokenizer-frame.js` | IIFE | loaded by tokenizer iframe |
-| `react/index.esm.js` | ESM | `import ... from '@ozura/elements/react'` |
-| `react/index.cjs.js` | CJS | `require('@ozura/elements/react')` |
-| `server/index.*.js` | ESM + CJS | `import { Ozura, createMintWaxHandler } from '@ozura/elements/server'` |
-
-Maintainer notes: [DEVELOPMENT.md](./DEVELOPMENT.md). Merchants: [Wax keys (merchant integration)](#wax-keys-merchant-integration) in this file; supplementary detail in [WAX_KEY_IMPLEMENTATION.md](./WAX_KEY_IMPLEMENTATION.md).
-
----
-
-## Roadmap
-
-### v0.1 — Core SDK ✅
-- [x] Iframe-isolated card number, CVV, and expiration date elements
-- [x] Luhn validation, real-time formatting, card brand detection
-- [x] postMessage protocol between host SDK and iframes
-- [x] Tokenizer iframe — assembles card data and POSTs directly to vault
-- [x] Style customization (base / focus / invalid states)
-- [x] Rollup build — ESM, UMD, and IIFE frame bundles
-- [x] Working demo page
-- [x] CORS resolved for dev environment (local proxy server)
-
-### v0.2 — Developer experience ✅
-- [x] Card brand SVG icon inside the card number field (updates in real time)
-- [x] Auto-advance focus: card number → expiry → CVV on completion
-- [x] `element.clear()`, `element.update()`, `element.unmount()` fully wired
-- [x] Field-level error strings in change events
-- [x] `OzVault.destroy()` for full lifecycle cleanup
-- [x] `OzVault.isReady` getter
-- [x] `element.mount()` accepts `HTMLElement` as well as a CSS selector
-- [x] Unit test suite (Vitest + jsdom) — 168 tests, 0 failures
-- [ ] Published to npm as `@ozura/elements`
-- [ ] CDN delivery for UMD build (optional for v1)
-
-### v0.3 — React ✅
-- [x] `<OzElements>` provider — creates and owns an `OzVault` instance
-- [x] `<OzCardNumber />`, `<OzExpiry />`, `<OzCvv />` field components
-- [x] `useOzElements()` hook — `createToken` + `ready` flag
-- [x] ESM + CJS React bundle, exported at `@ozura/elements/react`
-- [ ] Published as a standalone `@oz/react-elements` package (optional; subpath export is sufficient for v1)
-
-### v1.0 — Production ready
-- [x] Production iframe hosting at `elements.ozura.com`
-- [x] postMessage security covered (unit + E2E tests; see `docs/AUDIT.md`)
-- [x] Security audit (consolidated in `docs/AUDIT.md`; all findings resolved or closed)
-- [ ] Publish `@ozura/elements@1.0.0` to npm
-- [ ] Public documentation site (or link to ozura-documentation)
-- [ ] ACH / bank account element (pending Pay API support) — post-v1
-- [ ] Saved payment method support (returning customers) — post-v1
-
----
-
-## License
-
-MIT — Copyright 2025 Ozura
+# @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 so the onReady callback isn't in a TDZ
+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`.
+
+---
+
+### 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 — pass to cardSale
+  card?: {
+    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
+}
+```
+
+> **`cvcSession` is always present on a successful tokenization.** Although the TypeScript type marks it optional, `createToken()` rejects before returning if `cvcSession` is absent — this would indicate a vault misconfiguration. Always forward both `token` and `cvcSession` to your charge endpoint.
+
+`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).
+
+```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)
+});
+```
+
+**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';
+```