@ozura/elements 0.1.0-beta.6 → 1.0.0

package/README.md

@@ -1,720 +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.
-
-All you need is a vault API key.
-
----
-
-## 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 just need a vault API key. 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 = new OzVault('vault_api_key');
-│
-│  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.
-
----
-
-## 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 = new OzVault('your_vault_api_key', {
-  pubKey: 'your_pub_key',
-});
-
-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 }),
-  });
-});
-```
-
----
-
-## API
-
-### `new OzVault(apiKey, options)`
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `apiKey` | `string` | required | Your Ozura vault API key |
-| `options.pubKey` | `string` | required | System pub key for the tokenize endpoint. Obtain from Ozura admin. |
-| `options.apiUrl` | `string` | Ozura prod vault | Vault base URL |
-| `options.frameBaseUrl` | `string` | `https://elements.ozura.com` | Where iframe assets are served from |
-
-### `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.
-
----
-
-## 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
-      apiKey="your_vault_api_key"
-      pubKey="your_pub_key"
-      frameBaseUrl="https://elements.ozura.com"
-    >
-      <CheckoutForm />
-    </OzElements>
-  );
-}
-```
-
-### `<OzElements>` props
-
-| Prop | Type | Description |
-|---|---|---|
-| `apiKey` | `string` | Your Ozura vault API key |
-| `apiUrl` | `string?` | Vault API base URL |
-| `frameBaseUrl` | `string?` | Where iframe assets are hosted |
-
-### `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 | Frontend: `new OzVault(vaultApiKey)`. Backend: `vault-api-key` header |
-| 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 = new OzVault('vault_api_key_here', {
-  pubKey: 'your_pub_key',
-});
-
-// … 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 build    # production build
-npm run watch    # rebuild on save
-```
-
-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')` |
-
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for architecture detail, security model, and pre-production requirements.
-
----
-
-## 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';
+```