@ozura/elements 1.1.0 → 1.2.0

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

@@ -1,34 +1,14 @@
 export { OzVault } from './OzVault';
 export { OzElement } from './OzElement';
 export { OzError, normalizeVaultError, normalizeBankVaultError, normalizeCardSaleError } from './errors';
+export { createSessionFetcher } from './createSessionFetcher';
 /**
- * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
+ * @deprecated Use `sessionUrl` on `VaultOptions` / `OzElementsProps` instead —
+ * it calls `createSessionFetcher` internally and requires no extra code.
  *
- * 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')}>
+ * For custom request logic (auth headers etc.), use `createSessionFetcher` or
+ * write a `getSessionKey` callback inline.
  */
-export declare function createFetchWaxKey(mintUrl: string): (sessionId: string) => Promise<string>;
+export { createSessionFetcher as createFetchWaxKey } from './createSessionFetcher';
 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

@@ -38,12 +38,12 @@ export interface OzuraConfig {
      * Required for `cardSale()`. Tokenize-only integrations can omit this.
      */
     apiKey?: string;
-    /** Vault API key — used for `mintWaxKey()` and `revokeWaxKey()`. Always required. */
+    /** Vault API key — used for `createSession()` and `revokeSession()`. Always required. */
     vaultKey: string;
     /** Ozura Pay API base URL. Defaults to staging. */
     apiUrl?: string;
     /**
-     * Ozura Vault base URL. Used for `mintWaxKey` and `revokeWaxKey`.
+     * Ozura Vault base URL. Used for `createSession` and `revokeSession`.
      * Defaults to the build-time vault URL (staging or production).
      */
     vaultUrl?: string;
@@ -58,41 +58,81 @@ 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). */
+/**
+ * Result of {@link Ozura.createSession} / {@link Ozura.mintWaxKey}.
+ */
+export interface CreateSessionResult {
+    /** Session key — the SDK transmits this on every tokenize call. */
+    sessionKey: string;
+    /** Seconds until the session expires. Typically 1800 (30 min). */
     expiresInSeconds: number;
 }
 /**
- * Options for {@link Ozura.mintWaxKey}.
+ * Options for {@link Ozura.createSession} / {@link Ozura.mintWaxKey}.
  */
-export interface MintWaxKeyOptions {
+export interface CreateSessionOptions {
     /**
-     * SDK-generated session UUID forwarded from the `fetchWaxKey` callback.
-     * Stored by the vault for correlation and audit — not used for authentication.
+     * SDK-generated session UUID forwarded from the `getSessionKey` /
+     * `fetchWaxKey` callback. Stored by the vault for correlation and audit.
      */
-    tokenizationSessionId?: string;
+    sessionId?: 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.
+     * Maximum number of card submissions this session accepts before the SDK
+     * automatically refreshes it. Keep this in sync with `sessionLimit` in
+     * `VaultOptions` so the client can proactively refresh without a user-
+     * visible delay.
      *
-     * 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.
+     * Pass `null` to remove the cap entirely (the vault will accept unlimited
+     * tokenize calls until the session TTL elapses). Only do this for flows
+     * where the same session genuinely needs more than 3 submissions.
      *
      * @default 3
      */
-    maxTokenizeCalls?: number;
+    sessionLimit?: number | null;
     /**
-     * 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.
+     * Maximum number of proxy calls this session accepts.
+     * Only relevant if you use vault proxy endpoints directly.
+     * Pass `null` to remove the proxy cap.
+     */
+    maxProxyCalls?: number | null;
+    /**
+     * Your internal order or checkout ID. Stored alongside the session in the
+     * vault audit log so you can correlate vault events with your own records.
+     */
+    orderId?: string;
+    /**
+     * Your internal customer ID. Stored in the vault audit log for correlation.
+     */
+    customerId?: string;
+    /**
+     * Your internal cart or basket ID. Stored in the vault audit log for correlation.
      */
+    cartId?: string;
+    /**
+     * Arbitrary key/value metadata (string values only) stored with the session
+     * in the vault audit log. Max 16 keys, 64-char keys, 256-char values.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Session lifetime in seconds (60–1800). Defaults to 1800 (30 minutes).
+     * Only set this if your checkout flow is shorter than 30 minutes and you want
+     * the session to expire sooner as a defense-in-depth measure.
+     */
+    ttlSeconds?: number;
+}
+/** @deprecated Use {@link CreateSessionResult} instead. */
+export interface MintWaxKeyResult {
+    /** @deprecated Use `sessionKey` from {@link CreateSessionResult} instead. */
+    waxKey: string;
+    /** Seconds until the session expires. Typically 1800 (30 min). */
+    expiresInSeconds: number;
+}
+/** @deprecated Use {@link CreateSessionOptions} instead. */
+export interface MintWaxKeyOptions {
+    /** @deprecated Use `sessionId` from {@link CreateSessionOptions} instead. */
+    tokenizationSessionId?: string;
+    /** @deprecated Use `sessionLimit` from {@link CreateSessionOptions} instead. */
+    maxTokenizeCalls?: number;
     maxProxyCalls?: number;
 }
 export interface CardSaleInput {
@@ -155,48 +195,52 @@ export declare class Ozura {
      */
     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.
+     * Creates a short-lived payment session key from the vault.
      *
-     * **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.
+     * Call this from your session endpoint (created with `createSessionMiddleware`
+     * or `createSessionHandler`) to issue a key that the frontend SDK will use for
+     * tokenization. The vault secret never leaves your server.
      *
-     * **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.
+     * **Use limits:** each session key accepts up to `sessionLimit` (default 3)
+     * card submissions. After that the SDK automatically fetches a new session.
+     * Set `sessionLimit` to the same value in `VaultOptions` / `OzElementsProps`
+     * so the client can refresh proactively before hitting the limit.
      *
      * @example
-     * // Next.js API route
+     * // Manual route (Next.js App Router)
      * export async function POST(req: Request) {
      *   const { sessionId } = await req.json();
-     *   const { waxKey } = await ozura.mintWaxKey({
-     *     tokenizationSessionId: sessionId,
-     *     maxTokenizeCalls: 3,
-     *   });
-     *   return Response.json({ waxKey });
+     *   const { sessionKey } = await ozura.createSession({ sessionId });
+     *   return Response.json({ sessionKey });
      * }
+     *
+     * @example
+     * // One-liner with createSessionMiddleware (Express)
+     * app.post('/api/oz-session', createSessionMiddleware(ozura));
      */
-    mintWaxKey(options?: MintWaxKeyOptions): Promise<MintWaxKeyResult>;
+    createSession(options?: CreateSessionOptions): Promise<CreateSessionResult>;
     /**
-     * Revoke a previously minted wax key.
+     * Revokes a payment session 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.
+     * Best-effort: never throws. Call this when the user's checkout ends (payment
+     * complete, cancelled, or abandoned) to close the key's 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.
+     * - 503 = Redis error; the key may still be valid. Retry if needed.
      *
      * @example
      * // After a successful card sale:
-     * await ozura.revokeWaxKey(waxKey);
+     * await ozura.revokeSession(sessionKey);
+     */
+    revokeSession(sessionKey: string): Promise<void>;
+    /**
+     * @deprecated Use {@link createSession} instead.
+     */
+    mintWaxKey(options?: MintWaxKeyOptions): Promise<MintWaxKeyResult>;
+    /**
+     * @deprecated Use {@link revokeSession} instead.
      */
     revokeWaxKey(waxKey: string): Promise<void>;
     /**
@@ -214,7 +258,7 @@ export declare class Ozura {
      */
     private parseApiJson;
 }
-/** Minimal response shape required by {@link createMintWaxMiddleware}. */
+/** Minimal response shape required by {@link createSessionMiddleware}. */
 interface NodeLikeResponse {
     json(data: unknown): void;
     status(code: number): NodeLikeResponse;
@@ -222,52 +266,60 @@ interface NodeLikeResponse {
     setHeader?(name: string, value: string | number): void;
 }
 /**
- * Creates a ready-to-use Fetch API route handler for minting wax keys.
+ * Creates a ready-to-use Fetch API route handler for payment session creation.
  *
  * 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 }`.
+ * The handler reads `sessionId` from the JSON request body, calls
+ * `ozura.createSession()`, and returns `{ sessionKey }`.
  * 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';
+ * Pair with `sessionUrl` on the frontend — no other configuration needed.
  *
- * const ozura = new Ozura({
- *   merchantId: process.env.MERCHANT_ID!,
- *   apiKey:     process.env.MERCHANT_API_KEY!,
- *   vaultKey:   process.env.VAULT_API_KEY!,
- * });
+ * @example
+ * // app/api/oz-session/route.ts  (Next.js App Router)
+ * import { Ozura, createSessionHandler } from '@ozura/elements/server';
  *
- * export const POST = createMintWaxHandler(ozura);
+ * const ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
+ * export const POST = createSessionHandler(ozura);
  */
-export declare function createMintWaxHandler(ozura: Ozura): (req: Request) => Promise<Response>;
+export declare function createSessionHandler(ozura: Ozura): (req: Request) => Promise<Response>;
 /**
- * Creates a ready-to-use Express / Connect middleware for minting wax keys.
+ * Creates a ready-to-use Express / Connect middleware for payment session creation.
  *
  * 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 }`.
+ * The middleware reads `sessionId` from `req.body`, calls
+ * `ozura.createSession()`, and sends `{ sessionKey }`.
  * On error it sends `{ error }` with an appropriate HTTP status.
  *
+ * Pair with `sessionUrl` on the frontend — no other configuration needed.
+ *
  * @example
  * // Express
  * import express from 'express';
- * import { Ozura, createMintWaxMiddleware } from '@ozura/elements/server';
+ * import { Ozura, createSessionMiddleware } 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 ozura = new Ozura({ vaultKey: process.env.VAULT_API_KEY! });
  *
  * const app = express();
  * app.use(express.json());
- * app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
+ * app.post('/api/oz-session', createSessionMiddleware(ozura));
+ */
+export declare function createSessionMiddleware(ozura: Ozura): (req: {
+    body?: unknown;
+    headers?: unknown;
+}, res: NodeLikeResponse) => Promise<void>;
+/**
+ * @deprecated Use {@link createSessionHandler} instead.
+ * Returns `{ waxKey }` for backward compatibility with old `createFetchWaxKey` backends.
+ */
+export declare function createMintWaxHandler(ozura: Ozura): (req: Request) => Promise<Response>;
+/**
+ * @deprecated Use {@link createSessionMiddleware} instead.
+ * Sends `{ waxKey }` for backward compatibility with old `createFetchWaxKey` clients.
  */
 export declare function createMintWaxMiddleware(ozura: Ozura): (req: {
     body?: unknown;

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

@@ -156,35 +156,49 @@ export interface VaultOptions {
      *  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.
+     * URL of your backend session endpoint. The simplest way to connect the SDK
+     * to your server — just pass the path and the SDK handles everything else.
      *
-     * 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.
+     * The endpoint should be created with `createSessionMiddleware` or
+     * `createSessionHandler` from `@ozura/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
-     * // const { sessionId } = await req.json();
-     * // const { waxKey } = await ozura.mintWaxKey({ tokenizationSessionId: sessionId });
-     * // return Response.json({ waxKey });
+     * // Backend (Express)
+     * app.post('/api/oz-session', createSessionMiddleware(ozura));
+     *
+     * // Frontend
+     * OzVault.create({ pubKey: 'pk_live_...', sessionUrl: '/api/oz-session' })
+     */
+    sessionUrl?: string;
+    /**
+     * Custom async function to obtain a session key from your backend.
+     * Use this when you need custom headers, auth tokens, or request logic that
+     * `sessionUrl` cannot provide.
+     *
+     * Receives an SDK-generated session UUID; your implementation passes it to
+     * your backend, which calls `ozura.createSession()` and returns the key.
+     *
+     * For the common case, prefer `sessionUrl` — it wraps this automatically.
      *
-     * **Client-side (fetchWaxKey callback):**
      * @example
-     * fetchWaxKey: async (sessionId) => {
-     *   const res = await fetch('/api/mint-wax', {
+     * getSessionKey: async (sessionId) => {
+     *   const res = await fetch('/api/oz-session', {
      *     method: 'POST',
-     *     headers: { 'Content-Type': 'application/json' },
+     *     headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
      *     body: JSON.stringify({ sessionId }),
      *   });
-     *   const { waxKey } = await res.json();
-     *   return waxKey;
+     *   const { sessionKey } = await res.json();
+     *   return sessionKey;
      * }
      */
-    fetchWaxKey: (tokenizationSessionId: string) => Promise<string>;
+    getSessionKey?: (sessionId: string) => Promise<string>;
+    /**
+     * @deprecated Use `sessionUrl` or `getSessionKey` instead.
+     *
+     * Legacy callback name. Equivalent to `getSessionKey` — both are supported
+     * and work identically. `fetchWaxKey` will be removed in a future major version.
+     */
+    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;
@@ -211,25 +225,36 @@ export interface VaultOptions {
      * 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.
+     * Called when the SDK silently refreshes the payment session mid-checkout
+     * (e.g. after the session is consumed or expires). The `createToken()` /
+     * `createBankToken()` promise stays pending until the refresh completes.
+     * Use this to show a loading indicator while the refresh is in progress.
+     */
+    onSessionRefresh?: () => void;
+    /**
+     * @deprecated Use `onSessionRefresh` instead.
      */
     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`).
+     * Maximum number of card submissions allowed per session before the SDK
+     * automatically refreshes the session in the background. Defaults to `3`.
+     *
+     * Must match the `sessionLimit` (or `maxTokenizeCalls`) passed to
+     * `ozura.createSession()` on your server. Both default to `3` so you only
+     * need this if you override the server-side value.
      *
-     * 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.
+     * Pass `null` to disable the proactive refresh cap entirely (unlimited
+     * tokenizations per session). Only use this when your server-side
+     * `createSession()` also passes `sessionLimit: null`.
      *
      * @default 3
      */
+    sessionLimit?: number | null;
+    /**
+     * @deprecated Use `sessionLimit` instead.
+     * Maximum number of tokenize calls per session. Equivalent to `sessionLimit`.
+     * @default 3
+     */
     maxTokenizeCalls?: number;
     /**
      * Called once when the tokenizer iframe has loaded and is ready to accept