@ozura/elements 0.1.0-beta.7 → 1.0.0

package/dist/types/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!,
@@ -58,6 +58,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;
@@ -118,27 +149,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 +201,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 +265,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 +276,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/types/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/types/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/types/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/types/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "0.1.0-beta.7",
+  "version": "1.0.0",
   "description": "PCI-compliant card tokenization SDK for the Ozura Vault — collect card data in iframe-isolated fields and tokenize without PCI scope",
   "main": "dist/oz-elements.umd.js",
   "module": "dist/oz-elements.esm.js",
@@ -12,12 +12,12 @@
       "require": "./dist/oz-elements.umd.js"
     },
     "./react": {
-      "types": "./dist/react/index.d.ts",
+      "types": "./dist/react/react/index.d.ts",
       "import": "./dist/react/index.esm.js",
       "require": "./dist/react/index.cjs.js"
     },
     "./server": {
-      "types": "./dist/server/index.d.ts",
+      "types": "./dist/server/server/index.d.ts",
       "import": "./dist/server/index.esm.js",
       "require": "./dist/server/index.cjs.js"
     }
@@ -41,7 +41,8 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright test --project=mock",
     "test:e2e:live": "playwright test --project=live",
-    "prepublishOnly": "npm run build"
+    "check:csp": "node scripts/check-csp.mjs",
+    "prepublishOnly": "cross-env NODE_ENV=production npm run build"
   },
   "peerDependencies": {
     "react": ">=17",
@@ -80,6 +81,8 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^22.14.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",