@ozura/elements 0.1.0-beta.7 → 1.0.0

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;
@@ -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,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;
@@ -368,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). */
@@ -408,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.
@@ -539,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 {};

package/dist/types/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/types/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/types/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';