@ozura/elements 0.1.0-beta.7 → 1.0.1

package/dist/react/sdk/OzVault.d.ts

@@ -10,7 +10,7 @@ import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOpt
  * const vault = await OzVault.create({
  *   pubKey: 'pk_live_...',
  *   fetchWaxKey: async (sessionId) => {
- *     // Call your backend — which calls ozura.mintWaxKey() from oz-elements/server
+ *     // Call your backend — which calls ozura.mintWaxKey() from @ozura/elements/server
  *     const { waxKey } = await fetch('/api/mint-wax', {
  *       method: 'POST',
  *       body: JSON.stringify({ sessionId }),
@@ -41,17 +41,25 @@ export declare class OzVault {
     private completionState;
     private tokenizerFrame;
     private tokenizerWindow;
-    private tokenizerName;
     private tokenizerReady;
     private _tokenizing;
     private _destroyed;
+    private _tokenizeSuccessCount;
+    private _maxTokenizeCalls;
     private boundHandleMessage;
     private _pendingMount;
+    private _storedFetchWaxKey;
+    private _waxRefreshing;
+    private _onWaxRefresh;
+    private _onReady;
     private loadErrorTimeoutId;
+    private _hiddenAt;
+    private boundHandleVisibility;
     /**
      * Internal constructor — use `OzVault.create()` instead.
      * The constructor mounts the tokenizer iframe immediately so it can start
      * loading in parallel while `fetchWaxKey` is being awaited.
+     * @internal
      */
     private constructor();
     /**
@@ -69,15 +77,39 @@ export declare class OzVault {
      * The returned vault is ready to create elements immediately. `createToken()`
      * additionally requires `vault.isReady` (tokenizer iframe loaded).
      *
-     * @throws {OzError} if `fetchWaxKey` throws or returns an empty string.
+     * @throws {OzError} if `fetchWaxKey` throws, returns a non-string value, or returns an empty/whitespace-only string.
      */
-    static create(options: VaultOptions): Promise<OzVault>;
+    static create(options: VaultOptions, signal?: AbortSignal): Promise<OzVault>;
     /**
      * True once the hidden tokenizer iframe has loaded and signalled ready.
      * Use this to gate the pay button when building custom UIs without React.
      * React consumers should use the `ready` value returned by `useOzElements()`.
+     *
+     * Once `true`, remains `true` for the lifetime of this vault instance.
+     * It only reverts to `false` after `vault.destroy()` is called, at which
+     * point the vault is unusable and a new instance must be created.
+     *
+     * @remarks
+     * This tracks **tokenizer readiness only** — it says nothing about whether
+     * the individual element iframes (card number, CVV, etc.) have loaded.
+     * A vault can be `isReady === true` while elements are still mounting.
+     * To gate a submit button correctly in vanilla JS, wait for every element's
+     * `'ready'` event in addition to this flag. In React, use the `ready` value
+     * from `useOzElements()` instead, which combines both checks automatically.
      */
     get isReady(): boolean;
+    /**
+     * Number of successful tokenize calls made against the current wax key.
+     *
+     * Resets to `0` each time the wax key is refreshed (proactively or reactively).
+     * Useful in vanilla JS integrations to display "attempts remaining" UI.
+     * In React, use `tokenizeCount` from `useOzElements()` instead.
+     *
+     * @example
+     * const remaining = 3 - vault.tokenizeCount;
+     * payButton.textContent = remaining > 0 ? `Pay (${remaining} attempts left)` : 'Pay';
+     */
+    get tokenizeCount(): number;
     /**
      * Creates a new OzElement of the given type. Call `.mount(selector)` on the
      * returned element to attach it to the DOM.
@@ -129,6 +161,17 @@ export declare class OzVault {
      * unmounts (e.g. in React's useEffect cleanup or a SPA route change).
      */
     destroy(): void;
+    /**
+     * Proactively re-mints the wax key when the page becomes visible again after
+     * a long idle period. Wax keys have a fixed TTL (~30 minutes); a user who
+     * leaves the tab in the background and returns could have an expired key.
+     * Rather than waiting for a failed tokenization to trigger the reactive
+     * refresh path, this pre-empts the failure when the vault is idle.
+     *
+     * Threshold: 20 minutes hidden. Chosen to be comfortably inside the ~30m TTL
+     * while avoiding spurious refreshes for brief tab-switches.
+     */
+    private handleVisibilityChange;
     private mountTokenizerFrame;
     private handleMessage;
     /**
@@ -138,5 +181,26 @@ export declare class OzVault {
      */
     private handleElementChange;
     private handleTokenizerMessage;
+    /**
+     * Returns true when an OZ_TOKEN_ERROR should trigger a wax key refresh.
+     *
+     * Primary path: vault returns 401/403 → errorCode 'auth'.
+     * Defensive path: vault returns 400 → errorCode 'validation', but the raw
+     * message contains wax-key-specific language (consumed, expired, invalid key,
+     * etc.). This avoids a hard dependency on the vault returning a unified HTTP
+     * status for consumed-key vs expired-key failures — both should refresh.
+     *
+     * Deliberately excludes 'network', 'timeout', and 'server' codes (transient
+     * errors are already retried in fetchWithRetry) and 'unknown' (too broad).
+     */
+    private isRefreshableAuthError;
+    /**
+     * Re-mints the wax key using the stored fetchWaxKey callback and updates
+     * the tokenizer with the new key. Used for transparent auto-refresh when
+     * the vault returns an auth error on tokenization.
+     *
+     * Only one refresh runs at a time — concurrent retries share the same promise.
+     */
+    private refreshWaxKey;
     private sendToTokenizer;
 }

package/dist/react/sdk/errors.d.ts

@@ -10,6 +10,8 @@
  * errorMapping.ts so the same error strings produce the same user-facing copy.
  */
 export type OzErrorCode = 'network' | 'timeout' | 'auth' | 'validation' | 'server' | 'config' | 'unknown';
+/** Returns true and narrows to OzErrorCode when `value` is a valid member of the union. */
+export declare function isOzErrorCode(value: unknown): value is OzErrorCode;
 export declare class OzError extends Error {
     /** The raw error string returned by the vault or cardSale API, if available. */
     readonly raw: string;
@@ -52,5 +54,12 @@ export declare function normalizeBankVaultError(raw: string): string;
  * Falls back to the original string when it's under 100 characters, or to a
  * generic message for long/opaque server errors — matching checkout's fallback
  * behaviour exactly.
+ *
+ * **Trade-off:** Short unrecognised strings (e.g. processor codes like
+ * `"PROC_TIMEOUT"`) are passed through verbatim. This intentionally mirrors
+ * checkout so the same raw Pay API errors produce the same user-facing text on
+ * both surfaces. If the Pay API ever returns internal codes that should never
+ * reach the UI, the fix belongs in the Pay API error normalisation layer rather
+ * than here.
  */
 export declare function normalizeCardSaleError(raw: string): string;

package/dist/react/sdk/index.d.ts

@@ -1,5 +1,34 @@
 export { OzVault } from './OzVault';
 export { OzElement } from './OzElement';
 export { OzError, normalizeVaultError, normalizeBankVaultError, normalizeCardSaleError } from './errors';
+/**
+ * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
+ *
+ * Calls your backend mint endpoint with `{ sessionId }` and returns the wax key string.
+ * Throws on non-OK responses or a missing `waxKey` field so the vault can surface the
+ * error through its normal error path.
+ *
+ * Each call enforces a 10-second per-attempt timeout. On a pure network-level
+ * failure (connection refused, DNS failure, etc.) the call is retried once after
+ * 750ms before throwing. HTTP errors (4xx/5xx) are never retried — they indicate
+ * an endpoint misconfiguration or an invalid key, not a transient failure.
+ *
+ * The mint endpoint is typically the one-line `createMintWaxHandler` / `createMintWaxMiddleware`
+ * from `@ozura/elements/server`.
+ *
+ * @param mintUrl - Absolute or relative URL of your wax-key mint endpoint, e.g. `'/api/mint-wax'`.
+ *
+ * @example
+ * // Vanilla JS
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_live_...',
+ *   fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+ * });
+ *
+ * @example
+ * // React
+ * <OzElements pubKey="pk_live_..." fetchWaxKey={createFetchWaxKey('/api/mint-wax')}>
+ */
+export declare function createFetchWaxKey(mintUrl: string): (sessionId: string) => Promise<string>;
 export type { OzErrorCode } from './errors';
 export type { ElementType, BankElementType, ElementOptions, ElementStyleConfig, ElementStyle, ElementChangeEvent, VaultOptions, TokenizeOptions, BankTokenizeOptions, TokenResponse, BankTokenResponse, CardMetadata, BankAccountMetadata, FontSource, CssFontSource, CustomFontSource, BillingDetails, BillingAddress, CardSaleRequest, CardSaleResponseData, CardSaleApiResponse, Appearance, AppearanceVariables, OzTheme, TransactionQueryParams, TransactionQueryPagination, TransactionQueryResponse, TransactionType, CardTransactionType, AchTransactionType, CryptoTransactionType, TransactionBase, CardTransactionData, AchTransactionData, CryptoTransactionData, TransactionData, } from '../types';

package/dist/react/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!,
@@ -28,11 +28,17 @@
  */
 import type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, TransactionData, TransactionType } from '../types';
 export interface OzuraConfig {
-    /** Your Ozura merchant ID (e.g. "ozu_..."). */
-    merchantId: string;
-    /** Merchant Pay API key — sent as x-api-key header. */
-    apiKey: string;
-    /** Vault API key — same key used in OzVault on the frontend. */
+    /**
+     * Your Ozura merchant ID (e.g. "ozu_...").
+     * Required for `cardSale()`. Tokenize-only integrations (mint + tokenize only) can omit this.
+     */
+    merchantId?: string;
+    /**
+     * Merchant Pay API key — sent as x-api-key header on charge requests.
+     * Required for `cardSale()`. Tokenize-only integrations can omit this.
+     */
+    apiKey?: string;
+    /** Vault API key — used for `mintWaxKey()` and `revokeWaxKey()`. Always required. */
     vaultKey: string;
     /** Ozura Pay API base URL. Defaults to staging. */
     apiUrl?: string;
@@ -58,6 +64,37 @@ export interface MintWaxKeyResult {
     /** 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;
@@ -96,8 +133,8 @@ export interface ListTransactionsResult {
     pagination: TransactionQueryPagination;
 }
 export declare class Ozura {
-    private merchantId;
-    private apiKey;
+    private merchantId?;
+    private apiKey?;
     private vaultKey;
     private apiUrl;
     private vaultUrl;
@@ -118,27 +155,34 @@ export declare class Ozura {
      */
     listTransactions(input?: ListTransactionsInput): Promise<ListTransactionsResult>;
     /**
-     * Mint a short-lived wax key from the vault.
+     * 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.
      *
-     * The `tokenizationSessionId` passed to `fetchWaxKey` by the SDK should be
-     * forwarded here for correlation; it is stored by the vault alongside the
-     * wax key but is not used for authentication.
+     * **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 });
+     *   const { waxKey } = await ozura.mintWaxKey({
+     *     tokenizationSessionId: sessionId,
+     *     maxTokenizeCalls: 3,
+     *   });
      *   return Response.json({ waxKey });
      * }
      */
-    mintWaxKey(options?: {
-        tokenizationSessionId?: string;
-    }): Promise<MintWaxKeyResult>;
+    mintWaxKey(options?: MintWaxKeyOptions): Promise<MintWaxKeyResult>;
     /**
      * Revoke a previously minted wax key.
      *
@@ -163,11 +207,19 @@ 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.
@@ -219,6 +271,7 @@ export declare function createMintWaxHandler(ozura: Ozura): (req: Request) => Pr
  */
 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.
@@ -229,12 +282,123 @@ export declare function createMintWaxMiddleware(ozura: Ozura): (req: {
  * (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/react/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;
@@ -162,7 +164,7 @@ export interface VaultOptions {
      * It replaces the vault secret on every browser tokenize call — the secret
      * never leaves your server.
      *
-     * **Server-side (recommended):** Use `ozura.mintWaxKey()` from `oz-elements/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
@@ -205,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`
@@ -278,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 {
@@ -294,9 +328,20 @@ export interface CardMetadata {
 }
 export interface TokenResponse {
     token: string;
-    cvcSession?: string;
-    /** Non-sensitive card metadata — available immediately without a cardSale call. */
-    card?: CardMetadata;
+    /**
+     * CVC session token returned by the vault alongside the card token.
+     *
+     * Required by the Ozura Pay API `cardSale` endpoint. The SDK validates this
+     * field before resolving `createToken()` — if it is absent the promise rejects
+     * with `OZ_TOKEN_ERROR`. In practice this field is always present on a
+     * successful tokenization.
+     */
+    cvcSession: string;
+    /**
+     * Non-sensitive card metadata — always present on successful tokenization.
+     * Available immediately; no `cardSale` call required.
+     */
+    card: CardMetadata;
     /**
      * Validated, normalized billing details — ready to spread into a cardSale request.
      * Only present when billing was passed to createToken().
@@ -368,12 +413,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). */
@@ -408,12 +453,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.
@@ -539,7 +589,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/react/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/react/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;