@ozura/elements 0.1.0-beta.6 → 1.0.0

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;
@@ -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/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;

package/dist/react/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/server/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;
+}