@ozura/elements 0.1.0-beta.1

package/README.md

@@ -0,0 +1,717 @@
+# 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 'oz-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 oz-elements
+```
+
+Or via script tag (UMD):
+
+```html
+<script src="https://cdn.ozura.com/oz-elements/oz-elements.umd.js"></script>
+```
+
+---
+
+## Quick start
+
+```js
+import { OzVault } from 'oz-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 oz-elements
+```
+
+Import from the `/react` subpath:
+
+```tsx
+import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from 'oz-elements/react';
+```
+
+### Example
+
+```tsx
+import { useState } from 'react';
+import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from 'oz-elements/react';
+import { normalizeCardSaleError } from 'oz-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 'oz-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 'oz-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 'oz-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 'oz-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 'oz-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 'oz-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 'oz-elements/react'` |
+| `react/index.cjs.js` | CJS | `require('oz-elements/react')` |
+
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for architecture detail, security model, and internal progress log.
+
+---
+
+## 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 `oz-elements`
+- [ ] CDN delivery for UMD build
+
+### 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 `oz-elements/react`
+- [ ] Published as a standalone `@oz/react-elements` package
+
+### v1.0 — Production ready
+- [x] Production iframe hosting at `elements.ozura.com`
+- [ ] postMessage integration tests
+- [ ] Security audit
+- [ ] Public documentation site
+- [ ] ACH / bank account element (pending Pay API support)
+- [ ] Saved payment method support (returning customers)
+
+---
+
+## License
+
+MIT — Copyright 2025 Ozura