@ozura/elements 0.1.0-beta.6 → 1.0.0

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

@@ -4,8 +4,20 @@ import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOpt
  * The main entry point for OzElements. Creates and manages iframe-based
  * card input elements that keep raw card data isolated from the merchant page.
  *
+ * Use the static `OzVault.create()` factory — do not call `new OzVault()` directly.
+ *
  * @example
- * const vault = new OzVault('your_vault_api_key');
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_live_...',
+ *   fetchWaxKey: async (sessionId) => {
+ *     // Call your backend — which calls ozura.mintWaxKey() from @ozura/elements/server
+ *     const { waxKey } = await fetch('/api/mint-wax', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ sessionId }),
+ *     }).then(r => r.json());
+ *     return waxKey;
+ *   },
+ * });
  * const cardNum = vault.createElement('cardNumber');
  * cardNum.mount('#card-number');
  * const { token, cvcSession } = await vault.createToken({
@@ -13,7 +25,8 @@ import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOpt
  * });
  */
 export declare class OzVault {
-    private apiKey;
+    private waxKey;
+    private tokenizationSessionId;
     private pubKey;
     private frameBaseUrl;
     private frameOrigin;
@@ -28,20 +41,75 @@ 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;
-    constructor(apiKey: string, options: VaultOptions);
+    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();
+    /**
+     * Creates and returns a ready `OzVault` instance.
+     *
+     * Internally this:
+     * 1. Generates a `tokenizationSessionId` (UUID).
+     * 2. Starts loading the hidden tokenizer iframe immediately.
+     * 3. Calls `options.fetchWaxKey(tokenizationSessionId)` concurrently — your
+     *    backend mints a session-bound wax key from the vault and returns it.
+     * 4. Resolves with the vault instance once the wax key is stored. The iframe
+     *    has been loading the whole time, so `isReady` may already be true or
+     *    will fire shortly after.
+     *
+     * The returned vault is ready to create elements immediately. `createToken()`
+     * additionally requires `vault.isReady` (tokenizer iframe loaded).
+     *
+     * @throws {OzError} if `fetchWaxKey` throws, returns a non-string value, or returns an empty/whitespace-only string.
+     */
+    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.
@@ -93,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;
     /**
@@ -102,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';

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