@ozura/elements 0.1.0-beta.6 → 1.0.0

package/dist/server/server/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```ts
- * import { Ozura } from 'oz-elements/server';
+ * import { Ozura } from '@ozura/elements/server';
  *
  * const ozura = new Ozura({
  *   merchantId: process.env.MERCHANT_ID!,
@@ -36,6 +36,11 @@ export interface OzuraConfig {
     vaultKey: string;
     /** Ozura Pay API base URL. Defaults to staging. */
     apiUrl?: string;
+    /**
+     * Ozura Vault base URL. Used for `mintWaxKey` and `revokeWaxKey`.
+     * Defaults to the build-time vault URL (staging or production).
+     */
+    vaultUrl?: string;
     /** Request timeout in milliseconds. Default: 30000. */
     timeoutMs?: number;
     /** Max retry attempts for 5xx / network errors. Default: 2 (up to 3 total attempts). Set 0 to disable. */
@@ -47,6 +52,43 @@ export declare class OzuraError extends Error {
     readonly retryAfter?: number;
     constructor(message: string, statusCode: number, raw?: string, retryAfter?: number);
 }
+export interface MintWaxKeyResult {
+    /** Wax key UUID — pass as the `X-Wax-Key` header on vault tokenize calls. */
+    waxKey: string;
+    /** Seconds until the wax key expires. Typically 1800 (30 min). */
+    expiresInSeconds: number;
+}
+/**
+ * Options for {@link Ozura.mintWaxKey}.
+ */
+export interface MintWaxKeyOptions {
+    /**
+     * SDK-generated session UUID forwarded from the `fetchWaxKey` callback.
+     * Stored by the vault for correlation and audit — not used for authentication.
+     */
+    tokenizationSessionId?: string;
+    /**
+     * Maximum number of tokenize calls this wax key will accept before the vault
+     * marks it as consumed. Once consumed, further tokenize attempts return an
+     * auth/validation error and the client SDK automatically re-mints a fresh key.
+     *
+     * Keep this value small (3–5) to limit the blast radius if a key is intercepted.
+     * Set the same value in `VaultOptions.maxTokenizeCalls` so the client SDK can
+     * proactively refresh before hitting the wall, avoiding a user-visible delay.
+     *
+     * @default 3
+     */
+    maxTokenizeCalls?: number;
+    /**
+     * Maximum number of proxy calls this wax key will accept.
+     * Proxy calls are distinct from tokenize calls — they cover non-tokenize vault
+     * operations. Leave `undefined` to use the vault's built-in default.
+     *
+     * In most integrations you only need `maxTokenizeCalls`; set this only if you
+     * are explicitly using vault proxy endpoints.
+     */
+    maxProxyCalls?: number;
+}
 export interface CardSaleInput {
     /** From TokenResponse.token (frontend SDK). */
     token: string;
@@ -89,6 +131,7 @@ export declare class Ozura {
     private apiKey;
     private vaultKey;
     private apiUrl;
+    private vaultUrl;
     private timeoutMs;
     private retries;
     constructor(config: OzuraConfig);
@@ -105,6 +148,51 @@ export declare class Ozura {
      * Rate limit: 200 requests/minute per merchant.
      */
     listTransactions(input?: ListTransactionsInput): Promise<ListTransactionsResult>;
+    /**
+     * Mint a short-lived, use-limited wax key from the vault.
+     *
+     * Call this server-side to implement the `fetchWaxKey` callback required by
+     * `OzVault.create()` on the frontend. The wax key replaces the vault secret
+     * on every browser tokenize call — the secret never leaves your server.
+     *
+     * **Use limits:** by default each wax key accepts up to 3 tokenize calls
+     * (`maxTokenizeCalls: 3`). After that the vault marks the key as consumed and
+     * the client SDK transparently re-mints. Keep `maxTokenizeCalls` in sync with
+     * `VaultOptions.maxTokenizeCalls` so the SDK can proactively refresh before
+     * hitting the limit rather than waiting for a rejection.
+     *
+     * **Session correlation:** the `tokenizationSessionId` forwarded from the SDK's
+     * `fetchWaxKey` callback should be passed here so the vault can correlate the
+     * key with the checkout session in its audit log.
+     *
+     * @example
+     * // Next.js API route
+     * export async function POST(req: Request) {
+     *   const { sessionId } = await req.json();
+     *   const { waxKey } = await ozura.mintWaxKey({
+     *     tokenizationSessionId: sessionId,
+     *     maxTokenizeCalls: 3,
+     *   });
+     *   return Response.json({ waxKey });
+     * }
+     */
+    mintWaxKey(options?: MintWaxKeyOptions): Promise<MintWaxKeyResult>;
+    /**
+     * Revoke a previously minted wax key.
+     *
+     * Best-effort: never throws. Call this when the user's session ends (payment
+     * complete, cancelled, or expired) to close the exposure window before the
+     * vault TTL (30 min) elapses.
+     *
+     * - 200 = revoked successfully.
+     * - 404 = key already expired or not found — treated as success.
+     * - 503 = Redis error; the wax may still be valid. Retry if needed.
+     *
+     * @example
+     * // After a successful card sale:
+     * await ozura.revokeWaxKey(waxKey);
+     */
+    revokeWaxKey(waxKey: string): Promise<void>;
     /**
      * Execute a fetch with retry on 5xx / network errors.
      * 4xx errors (including 429) are never retried — they require caller action.
@@ -113,7 +201,72 @@ export declare class Ozura {
     private post;
     private getRaw;
     private handleResponse;
+    /**
+     * Parses a Pay API response JSON and throws `OzuraError` on HTTP errors or
+     * `success: false` payloads. Used by both `getRaw` and `handleResponse` to
+     * avoid duplicating the error-mapping logic.
+     */
+    private parseApiJson;
+}
+/** Minimal response shape required by {@link createMintWaxMiddleware}. */
+interface NodeLikeResponse {
+    json(data: unknown): void;
+    status(code: number): NodeLikeResponse;
+    /** Present on Node/Express `ServerResponse` — used for 429 `Retry-After`. */
+    setHeader?(name: string, value: string | number): void;
 }
+/**
+ * Creates a ready-to-use Fetch API route handler for minting wax keys.
+ *
+ * Drop-in for Next.js App Router, Cloudflare Workers, Vercel Edge, and any
+ * runtime built on the standard Web API `Request` / `Response`.
+ *
+ * The handler reads `sessionId` (or `tokenizationSessionId`) from the JSON
+ * request body, calls `ozura.mintWaxKey()`, and returns `{ waxKey }`.
+ * On error it returns `{ error }` with an appropriate HTTP status.
+ *
+ * @example
+ * // app/api/mint-wax/route.ts  (Next.js App Router)
+ * 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);
+ */
+export declare function createMintWaxHandler(ozura: Ozura): (req: Request) => Promise<Response>;
+/**
+ * Creates a ready-to-use Express / Connect middleware for minting wax keys.
+ *
+ * Requires `express.json()` (or equivalent body-parser) to be registered
+ * before this middleware so `req.body` is available.
+ *
+ * The middleware reads `sessionId` (or `tokenizationSessionId`) from
+ * `req.body`, calls `ozura.mintWaxKey()`, and sends `{ waxKey }`.
+ * On error it sends `{ error }` with an appropriate HTTP status.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
+ *
+ * const ozura = new Ozura({
+ *   merchantId: process.env.MERCHANT_ID!,
+ *   apiKey:     process.env.MERCHANT_API_KEY!,
+ *   vaultKey:   process.env.VAULT_API_KEY!,
+ * });
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
+ */
+export declare function createMintWaxMiddleware(ozura: Ozura): (req: {
+    body?: unknown;
+    headers?: unknown;
+}, res: NodeLikeResponse) => Promise<void>;
 /**
  * Extract the client IP address from a server request object.
  * Works with Express (`req.ip`), Fastify (`request.ip`), Next.js App Router
@@ -123,12 +276,123 @@ export declare class Ozura {
  * (Cloudflare) → `x-forwarded-for` (reverse proxy) → `x-real-ip` →
  * `socket.remoteAddress` → `"0.0.0.0"`.
  *
+ * **Proxy trust requirements — read before deploying:**
+ *
+ * - **`x-forwarded-for` / `x-real-ip`** are HTTP headers that any client can
+ *   set arbitrarily. They are only trustworthy when your server sits behind a
+ *   reverse proxy (nginx, AWS ALB, Cloudflare, etc.) that strips and rewrites
+ *   those headers. If your Node.js process is directly internet-accessible,
+ *   an attacker can spoof any IP value and bypass payment-processor
+ *   IP-based fraud checks.
+ * - **Express `req.ip`** resolves through `X-Forwarded-For` only when
+ *   `app.set('trust proxy', true)` (or a specific proxy count/subnet) is
+ *   configured. Without `trust proxy`, `req.ip` returns the direct socket
+ *   address (your load-balancer's IP, not the client's).
+ * - **`cf-connecting-ip`** is only trustworthy when Cloudflare is genuinely
+ *   in front of your server. Without Cloudflare, any client can send this
+ *   header with a fabricated value.
+ *
+ * In all cases, ensure your infrastructure strips untrusted forwarding headers
+ * before they reach your application.
+ *
  * @example
- * // Express / Fastify
+ * // Express — requires app.set('trust proxy', true) behind a proxy
  * clientIpAddress: getClientIp(req)
  *
  * // Next.js App Router
  * clientIpAddress: getClientIp(req)
  */
 export declare function getClientIp(req: Record<string, unknown>): string;
+/**
+ * Options for {@link createCardSaleHandler} and {@link createCardSaleMiddleware}.
+ *
+ * The only required option is `getAmount` — it must return the authoritative
+ * transaction amount from **your own** database or session. Never read the
+ * amount from the request body without validating it against your records;
+ * a malicious client could otherwise send an arbitrarily low amount.
+ */
+export interface CardSaleHandlerOptions {
+    /**
+     * Return the authoritative amount for this transaction as a decimal string
+     * (e.g. `"49.00"`). Source this from your own database or session — never
+     * trust the value the client sends in the request body.
+     *
+     * Receives the parsed request body so you can forward an `orderId` or
+     * similar identifier to look up the correct amount.
+     *
+     * @example
+     * getAmount: async (body) => {
+     *   const order = await db.orders.findById(body.orderId as string);
+     *   return order.total;
+     * }
+     */
+    getAmount: (body: Record<string, unknown>) => string | Promise<string>;
+    /**
+     * Return the ISO 4217 currency code for this transaction. Default: `"USD"`.
+     */
+    getCurrency?: (body: Record<string, unknown>) => string | Promise<string>;
+}
+/**
+ * Creates a ready-to-use Fetch API route handler for charging a tokenized card.
+ *
+ * Drop-in for Next.js App Router, Cloudflare Workers, Vercel Edge, and any
+ * runtime built on the standard Web API `Request` / `Response`.
+ *
+ * The handler reads `{ token, cvcSession, billing }` from the JSON request body,
+ * resolves the amount via `options.getAmount()`, calls `ozura.cardSale()`, and
+ * returns `{ transactionId, amount, cardLastFour, cardBrand }` on success.
+ * On error it returns `{ error }` with a normalized, user-facing message and
+ * an appropriate HTTP status.
+ *
+ * `clientIpAddress` is extracted automatically from the request headers.
+ *
+ * @example
+ * // app/api/charge/route.ts  (Next.js App Router)
+ * 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;
+ *   },
+ * });
+ */
+export declare function createCardSaleHandler(ozura: Ozura, options: CardSaleHandlerOptions): (req: Request) => Promise<Response>;
+/**
+ * Creates a ready-to-use Express / Connect middleware for charging a tokenized card.
+ *
+ * Requires `express.json()` (or equivalent body-parser) to be registered before
+ * this middleware so `req.body` is available.
+ *
+ * The middleware reads `{ token, cvcSession, billing }` from `req.body`, resolves
+ * the amount via `options.getAmount()`, calls `ozura.cardSale()`, and sends
+ * `{ transactionId, amount, cardLastFour, cardBrand }` on success.
+ * On error it sends `{ error }` with a normalized, user-facing message and an
+ * appropriate HTTP status.
+ *
+ * `clientIpAddress` is extracted automatically from the request object.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createCardSaleMiddleware } from '@ozura/elements/server';
+ *
+ * const app = express();
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * app.use(express.json());
+ * app.post('/api/charge', createCardSaleMiddleware(ozura, {
+ *   getAmount: async (body) => {
+ *     const order = await db.orders.findById(body.orderId as string);
+ *     return order.total;
+ *   },
+ * }));
+ */
+export declare function createCardSaleMiddleware(ozura: Ozura, options: CardSaleHandlerOptions): (req: {
+    body?: unknown;
+    headers?: unknown;
+}, res: NodeLikeResponse) => Promise<void>;
 export type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, TransactionType, TransactionBase, CardTransactionData, AchTransactionData, CryptoTransactionData, TransactionData, } from '../types';
+export { normalizeCardSaleError } from '../sdk/errors';

package/dist/server/types/index.d.ts

@@ -5,6 +5,9 @@ export interface ElementStyle {
     fontWeight?: string;
     fontStyle?: string;
     fontVariant?: string;
+    fontSmoothing?: string;
+    webkitFontSmoothing?: string;
+    mozOsxFontSmoothing?: string;
     letterSpacing?: string;
     lineHeight?: string;
     textAlign?: string;
@@ -55,8 +58,6 @@ export interface ElementStyle {
     minHeight?: string;
     maxHeight?: string;
     transition?: string;
-    /** Index signature for forward-compatibility with future CSS properties. */
-    [key: string]: string | undefined;
 }
 export interface ElementStyleConfig {
     /** Default styles applied to the input. */
@@ -74,7 +75,8 @@ export interface ElementOptions {
     style?: ElementStyleConfig;
     placeholder?: string;
     disabled?: boolean;
-    /** How long to wait (ms) for the iframe to load before emitting `loaderror`. Default: 10 000. */
+    /** How long to wait (ms) for the iframe to load before emitting `loaderror`. Default: 10 000.
+     * Only takes effect when this element's `onLoadError` option is provided or when `VaultOptions.onLoadError` is set. */
     loadTimeoutMs?: number;
 }
 export interface ElementChangeEvent {
@@ -118,7 +120,7 @@ export interface AppearanceVariables {
     colorText?: string;
     /** Input background color. Maps to `base.backgroundColor`. */
     colorBackground?: string;
-    /** Primary accent color. Maps to `focus.caretColor` and `focus.color`. */
+    /** Primary accent color. Maps to `focus.caretColor` and `base.caretColor`. */
     colorPrimary?: string;
     /** Error/invalid state text color. Maps to `invalid.color`. */
     colorDanger?: string;
@@ -153,6 +155,36 @@ export interface VaultOptions {
     /** System pub key required for tokenization. Obtain from Ozura admin.
      *  Sent as the `X-Pub-Key` header on tokenize requests. */
     pubKey: string;
+    /**
+     * Called by the SDK with a SDK-generated `tokenizationSessionId` UUID during
+     * `OzVault.create()`. Implement this to call your backend, which should mint a
+     * wax key from the vault using your vault secret and return it here.
+     *
+     * The wax key is a short-lived, session-scoped credential (TTL ~30 min).
+     * It replaces the vault secret on every browser tokenize call — the secret
+     * never leaves your server.
+     *
+     * **Server-side (recommended):** Use `ozura.mintWaxKey()` from `@ozura/elements/server`:
+     * @example
+     * // Your API route (e.g. Next.js App Router):
+     * // POST /api/mint-wax
+     * // const { sessionId } = await req.json();
+     * // const { waxKey } = await ozura.mintWaxKey({ tokenizationSessionId: sessionId });
+     * // return Response.json({ waxKey });
+     *
+     * **Client-side (fetchWaxKey callback):**
+     * @example
+     * fetchWaxKey: async (sessionId) => {
+     *   const res = await fetch('/api/mint-wax', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json' },
+     *     body: JSON.stringify({ sessionId }),
+     *   });
+     *   const { waxKey } = await res.json();
+     *   return waxKey;
+     * }
+     */
+    fetchWaxKey: (tokenizationSessionId: string) => Promise<string>;
     /** Base URL where the Ozura frame HTML/JS assets are served from.
      *  Defaults to the production CDN. Override for local development. */
     frameBaseUrl?: string;
@@ -175,8 +207,40 @@ export interface VaultOptions {
      * Use this to show a fallback UI (e.g. "Unable to load payment fields").
      */
     onLoadError?: () => void;
-    /** How long to wait (ms) for the tokenizer iframe before calling `onLoadError`. Default: 10 000. */
+    /** How long to wait (ms) for the tokenizer iframe before calling `onLoadError`. Default: 10 000.
+     * Only takes effect when `onLoadError` is also provided — setting this without `onLoadError` has no effect. */
     loadTimeoutMs?: number;
+    /**
+     * Called when the SDK silently re-mints the wax key during a tokenization
+     * attempt (expiry or consumption). The `createToken()` / `createBankToken()`
+     * promise stays pending until the refresh completes and the retry resolves.
+     * Use this to show a loading indicator while the re-mint round trip is in flight.
+     */
+    onWaxRefresh?: () => void;
+    /**
+     * Maximum number of tokenize calls each minted wax key accepts before the
+     * vault marks it as consumed. Should match the `maxTokenizeCalls` passed to
+     * `ozura.mintWaxKey()` on your server (both default to `3`).
+     *
+     * The SDK uses this value to proactively refresh the wax key after it has been
+     * fully consumed — before the next `createToken()` call is made — so users
+     * never experience a delay from a reactive re-mint. If the values are out of
+     * sync the reactive refresh path still catches consumption errors; this is
+     * purely an optimisation.
+     *
+     * @default 3
+     */
+    maxTokenizeCalls?: number;
+    /**
+     * Called once when the tokenizer iframe has loaded and is ready to accept
+     * tokenization requests. Useful in vanilla JS to re-evaluate submit-button
+     * readiness when the tokenizer becomes ready after all element iframes have
+     * already loaded.
+     *
+     * In React, use `useOzElements().ready` instead — it combines both tokenizer
+     * and element readiness automatically.
+     */
+    onReady?: () => void;
     /**
      * Global appearance configuration. Applies preset themes and/or variable
      * overrides to all elements created by this vault. Per-element `style`
@@ -248,8 +312,8 @@ export interface BankTokenizeOptions {
 export interface BankAccountMetadata {
     /** Last 4 digits of the account number. */
     last4: string;
-    /** US routing number (9 digits). */
-    routingNumber: string;
+    /** Last 4 digits of the routing number — sufficient for display and reconciliation. */
+    routingNumberLast4: string;
 }
 /** Non-sensitive card metadata returned alongside the token. */
 export interface CardMetadata {
@@ -264,6 +328,16 @@ export interface CardMetadata {
 }
 export interface TokenResponse {
     token: string;
+    /**
+     * CVC session token returned by the vault alongside the card token.
+     *
+     * Required by the Ozura Pay API `cardSale` endpoint. If this is absent it
+     * means the vault is not configured to return CVC sessions — `createToken()`
+     * will reject with an `OZ_TOKEN_ERROR` before this response is ever returned
+     * to the caller. In practice, this field is always present on successful
+     * tokenization; the optional type reflects only that the field is not part
+     * of the tokenized card data itself.
+     */
     cvcSession?: string;
     /** Non-sensitive card metadata — available immediately without a cardSale call. */
     card?: CardMetadata;
@@ -290,7 +364,6 @@ export interface BankTokenResponse {
  *
  * Headers required:
  *   x-api-key: <merchantApiKey>
- *   vault-api-key: <vaultApiKey>  (same key passed to OzVault)
  */
 export interface CardSaleRequest {
     /** Processor to use. If omitted, the Pay API auto-selects (Elavon → Nuvei → Worldpay). */
@@ -339,12 +412,12 @@ export interface CardSaleResponseData {
     amount: string;
     /** ISO 4217 currency code, e.g. "USD". */
     currency: string;
-    /** Surcharge amount applied, e.g. "0.00". */
-    surchargeAmount: string;
+    /** Surcharge amount applied, e.g. "1.50". Absent when no surcharge was configured. */
+    surchargeAmount?: string;
     /** Sales tax calculated by the Pay API based on billing address. */
     salesTaxAmount?: string;
-    /** Tip amount applied, e.g. "0.00". */
-    tipAmount: string;
+    /** Tip amount applied, e.g. "5.00". Absent when no tip was included in the request. */
+    tipAmount?: string;
     /** Last four digits of the card number. */
     cardLastFour: string;
     /** First six digits of the card number (BIN). */
@@ -379,12 +452,17 @@ export interface CardSaleResponseData {
  * Full response envelope from the Ozura Pay API cardSale endpoint.
  *
  * On success:  `{ success: true,  data: CardSaleResponseData }`
- * On failure:  HTTP 4xx/5xx with `{ error: string }` — pass `error` to
- *              `normalizeCardSaleError()` to get a user-facing message.
+ * On failure:  HTTP 4xx/5xx with `{ success: false, error: string }` — pass
+ *              `error` to `normalizeCardSaleError()` to get a user-facing message.
+ *
+ * Note: the server SDK `Ozura.cardSale()` throws `OzuraError` on failure rather
+ * than returning this shape. This type is only needed when calling the Pay API
+ * directly via `fetch`.
  */
 export interface CardSaleApiResponse {
     success: boolean;
-    data: CardSaleResponseData;
+    data?: CardSaleResponseData;
+    error?: string;
 }
 /**
  * Transaction types returned by the Pay API transQuery endpoint.
@@ -510,7 +588,7 @@ export interface TransactionQueryResponse {
     data: TransactionData[];
     pagination: TransactionQueryPagination;
 }
-export type OzMessageType = 'OZ_FRAME_READY' | 'OZ_INIT' | 'OZ_UPDATE' | 'OZ_CLEAR' | 'OZ_CHANGE' | 'OZ_FOCUS' | 'OZ_BLUR' | 'OZ_RESIZE' | 'OZ_SET_TOKENIZER_NAME' | 'OZ_BEGIN_COLLECT' | 'OZ_FIELD_VALUE' | 'OZ_TOKENIZE' | 'OZ_TOKEN_RESULT' | 'OZ_TOKEN_ERROR' | 'OZ_FOCUS_REQUEST' | 'OZ_BLUR_REQUEST' | 'OZ_SET_CVV_LENGTH' | 'OZ_BANK_TOKENIZE' | 'OZ_BANK_TOKEN_RESULT';
+export type OzMessageType = 'OZ_FRAME_READY' | 'OZ_INIT' | 'OZ_UPDATE' | 'OZ_CLEAR' | 'OZ_CHANGE' | 'OZ_FOCUS' | 'OZ_BLUR' | 'OZ_RESIZE' | 'OZ_BEGIN_COLLECT' | 'OZ_FIELD_VALUE' | 'OZ_TOKENIZE' | 'OZ_TOKEN_RESULT' | 'OZ_TOKEN_ERROR' | 'OZ_FOCUS_REQUEST' | 'OZ_BLUR_REQUEST' | 'OZ_SET_CVV_LENGTH' | 'OZ_BANK_TOKENIZE' | 'OZ_BANK_TOKEN_RESULT' | 'OZ_TOKENIZE_CANCEL';
 export interface OzMessage {
     __oz: true;
     vaultId: string;

package/dist/server/utils/appearance.d.ts

@@ -4,6 +4,15 @@ import type { Appearance, ElementStyleConfig } from '../types';
  * Resolution order: theme defaults → variable overrides.
  * The returned config is then used as the "base appearance" that
  * per-element `style` overrides merge on top of.
+ *
+ * @remarks
+ * - `appearance: undefined` → no styles injected (element iframes use their
+ *   own minimal built-in defaults).
+ * - `appearance: {}` or `appearance: { variables: {...} }` without an explicit
+ *   `theme` → the `'default'` theme is used as the base. Omitting `theme`
+ *   does NOT mean "no theme" — it means `theme: 'default'`. To opt out of
+ *   the preset themes entirely, use per-element `style` overrides without
+ *   passing an `appearance` prop at all.
  */
 export declare function resolveAppearance(appearance?: Appearance): ElementStyleConfig | undefined;
 /**

package/dist/server/utils/cardUtils.d.ts

@@ -21,6 +21,20 @@ export interface CardValidationResult {
     valid: boolean;
     error?: string;
 }
+/**
+ * Canonical card number validation: length check then Luhn.
+ *
+ * **Not called by `elementFrame.ts` at runtime.** The frame needs `complete`
+ * and `valid` as separate signals for field UX (show completion indicator
+ * before running Luhn), so it implements both checks inline via `isComplete()`
+ * and `isValid()`. Those methods MUST stay logically in sync with this
+ * function — any change to length bounds or error text here must be mirrored
+ * there, and vice-versa.
+ *
+ * Used by the unit test suite as the authoritative spec for the algorithm.
+ *
+ * @internal
+ */
 export declare function validateCardNumber(digits: string, brand: CardBrand | string): CardValidationResult;
 export interface ExpiryValidationResult {
     complete: boolean;

package/dist/server/utils/uuid.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generates a RFC 4122 v4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available (Chrome 92+, Firefox 95+,
+ * Safari 15.4+, Node 14.17+) and falls back to `crypto.getRandomValues()`
+ * for older environments (Safari 14, some embedded WebViews, older Node).
+ *
+ * Both paths use the same CSPRNG — the difference is only in API surface.
+ *
+ * @internal
+ */
+export declare function uuid(): string;

package/dist/types/frame/tokenizerFrame.d.ts

@@ -19,3 +19,35 @@
  * Exported for unit testing only — not part of the public SDK API.
  */
 export declare function isAllowedVaultOrigin(apiUrl: string): boolean;
+/** Exported for unit testing only — not part of the public SDK API. */
+export declare class TokenizerFrame {
+    private vaultId;
+    private hostOrigin;
+    /** Wax key delivered once via OZ_INIT. Used for all tokenize calls. */
+    private waxKey;
+    private pending;
+    private pendingBank;
+    constructor();
+    private onMessage;
+    /**
+     * Shared vault POST helper. Handles origin guard, header construction,
+     * the fetchWithRetry call, token extraction, empty-token error, and catch.
+     *
+     * Returns the raw response data augmented with a guaranteed non-empty
+     * `token` string, or `null` if an error was already reported via
+     * postMessage to `target`.
+     */
+    private postToVault;
+    private tokenize;
+    private tokenizeBank;
+    private static classifyHttpStatus;
+    /**
+     * Fetches with a 30s timeout and a single automatic retry for network
+     * errors only. 4xx and 5xx responses are not retried — 4xx inputs won't
+     * succeed on a second attempt, and 5xx may have already been processed
+     * server-side (idempotency cannot be guaranteed for the vault tokenize POST).
+     *
+     * Throws an Error with an `errorCode` property for downstream classification.
+     */
+    private fetchWithRetry;
+}

package/dist/types/sdk/OzElement.d.ts

@@ -33,10 +33,29 @@ export declare class OzElement {
      * (useful when integrating with React refs).
      */
     mount(target: string | HTMLElement): void;
+    /**
+     * Subscribe to an element event. Returns `this` for chaining.
+     * @param event - Event name: `'change'`, `'focus'`, `'blur'`, `'ready'`, or `'loaderror'`.
+     * @param callback - Handler invoked with the event payload.
+     */
     on(event: ElementEvent, callback: ElementCallback): this;
+    /**
+     * Remove a previously registered event handler.
+     * Has no effect if the handler is not registered.
+     */
     off(event: ElementEvent, callback: ElementCallback): this;
+    /**
+     * Subscribe to an event for a single invocation. The handler is automatically
+     * removed after it fires once.
+     */
     once(event: ElementEvent, callback: ElementCallback): this;
+    /**
+     * Dynamically update element options (placeholder, style, etc.) without
+     * re-mounting the iframe. Only the provided keys are merged; omitted keys
+     * retain their current values.
+     */
     update(options: Partial<ElementOptions>): void;
+    /** Clear the current field value without removing the element from the DOM. */
     clear(): void;
     /**
      * Removes the iframe from the DOM and resets internal state.
@@ -53,13 +72,25 @@ export declare class OzElement {
      * and prevents future use. Distinct from `unmount()` which allows re-mounting.
      */
     destroy(): void;
-    setTokenizerName(tokenizerName: string): void;
-    beginCollect(requestId: string): void;
-    /** Tell a CVV element how many digits to expect. Called automatically when card brand changes. */
+    /**
+     * Sends OZ_BEGIN_COLLECT to the element iframe, transferring `port` so the
+     * iframe can post its field value directly to the tokenizer without going
+     * through the merchant page (no named-window lookup required).
+     * @internal
+     */
+    beginCollect(requestId: string, port: MessagePort): void;
+    /**
+     * Tell a CVV element how many digits to expect. Called automatically when card brand changes.
+     * @internal
+     */
     setCvvLength(length: number): void;
+    /** @internal */
     handleMessage(msg: OzMessage): void;
     private emit;
     private post;
     private send;
+    /** Posts a message with transferable objects (e.g. MessagePort). Bypasses the
+     *  pending-message queue — only call when the frame is already ready. */
+    private sendWithTransfer;
 }
 export {};