@ozura/elements 0.1.0-beta.1

package/dist/server/sdk/OzElement.d.ts

@@ -0,0 +1,65 @@
+import { ElementType, BankElementType, ElementOptions, ElementStyleConfig, FontSource, OzMessage } from '../types';
+type AnyElementType = ElementType | BankElementType;
+type ElementEvent = 'ready' | 'change' | 'focus' | 'blur' | 'loaderror';
+type ElementCallback = (payload?: unknown) => void;
+/**
+ * A proxy for one Ozura iframe element. Merchants interact with this object;
+ * it never holds raw card data — all sensitive values live in the iframe.
+ */
+export declare class OzElement {
+    private elementType;
+    private options;
+    private vaultId;
+    readonly frameId: string;
+    private frameBaseUrl;
+    private frameOrigin;
+    private fonts;
+    private appearanceStyle;
+    private iframe;
+    private _frameWindow;
+    private _ready;
+    private _destroyed;
+    private _loadTimer;
+    private pendingMessages;
+    private handlers;
+    constructor(elementType: AnyElementType, options: ElementOptions, vaultId: string, frameBaseUrl: string, fonts?: FontSource[], appearanceStyle?: ElementStyleConfig);
+    /** The element type this proxy represents. */
+    get type(): AnyElementType;
+    /** True once the element iframe has loaded and signalled ready. */
+    get isReady(): boolean;
+    /**
+     * Mounts the element iframe into a container.
+     * Accepts either a CSS selector string or a direct HTMLElement reference
+     * (useful when integrating with React refs).
+     */
+    mount(target: string | HTMLElement): void;
+    on(event: ElementEvent, callback: ElementCallback): this;
+    off(event: ElementEvent, callback: ElementCallback): this;
+    once(event: ElementEvent, callback: ElementCallback): this;
+    update(options: Partial<ElementOptions>): void;
+    clear(): void;
+    /**
+     * Removes the iframe from the DOM and resets internal state.
+     * Called automatically by `OzVault.destroy()`. Safe to call manually
+     * for partial teardown (e.g. swapping payment method in a SPA).
+     */
+    unmount(): void;
+    /** Programmatically focus this element's input. Used internally for auto-advance. */
+    focus(): void;
+    /** Programmatically blur this element's input. */
+    blur(): void;
+    /**
+     * Permanently destroys this element: unmounts it, clears all event handlers,
+     * 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. */
+    setCvvLength(length: number): void;
+    handleMessage(msg: OzMessage): void;
+    private emit;
+    private post;
+    private send;
+}
+export {};

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

@@ -0,0 +1,106 @@
+import { OzElement } from './OzElement';
+import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse } from '../types';
+/**
+ * The main entry point for OzElements. Creates and manages iframe-based
+ * card input elements that keep raw card data isolated from the merchant page.
+ *
+ * @example
+ * const vault = new OzVault('your_vault_api_key');
+ * const cardNum = vault.createElement('cardNumber');
+ * cardNum.mount('#card-number');
+ * const { token, cvcSession } = await vault.createToken({
+ *   billing: { firstName: 'Jane', lastName: 'Doe' },
+ * });
+ */
+export declare class OzVault {
+    private apiKey;
+    private pubKey;
+    private apiUrl;
+    private frameBaseUrl;
+    private frameOrigin;
+    private fonts;
+    private resolvedAppearance;
+    readonly vaultId: string;
+    private elements;
+    private elementsByType;
+    private bankElementsByType;
+    private tokenizeResolvers;
+    private bankTokenizeResolvers;
+    private completionState;
+    private tokenizerFrame;
+    private tokenizerWindow;
+    private tokenizerName;
+    private tokenizerReady;
+    private _tokenizing;
+    private _destroyed;
+    private boundHandleMessage;
+    private _pendingMount;
+    private loadErrorTimeoutId;
+    constructor(apiKey: string, options: VaultOptions);
+    /**
+     * 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()`.
+     */
+    get isReady(): boolean;
+    /**
+     * Creates a new OzElement of the given type. Call `.mount(selector)` on the
+     * returned element to attach it to the DOM.
+     */
+    createElement(type: ElementType, options?: ElementOptions): OzElement;
+    /** Returns the existing element of the given type, or null if none has been created. */
+    getElement(type: ElementType): OzElement | null;
+    /**
+     * Creates a bank account input element (accountNumber or routingNumber).
+     * Call `.mount(selector)` on the returned element to attach it to the DOM.
+     *
+     * @example
+     * const accountEl = vault.createBankElement('accountNumber');
+     * const routingEl = vault.createBankElement('routingNumber');
+     * accountEl.mount('#account-number');
+     * routingEl.mount('#routing-number');
+     */
+    createBankElement(type: BankElementType, options?: ElementOptions): OzElement;
+    /** Returns the existing bank element of the given type, or null if none has been created. */
+    getBankElement(type: BankElementType): OzElement | null;
+    /**
+     * Tokenizes mounted bank account elements. Raw account and routing numbers
+     * never leave the Ozura-origin iframes — the tokenizer iframe POSTs directly
+     * to the vault API.
+     *
+     * Returns a token that can be used with any ACH-capable payment processor.
+     *
+     * **Note:** OzuraPay does not currently support bank account payments.
+     * Use this token with your own ACH processor backend.
+     *
+     * @example
+     * const { token, bank } = await vault.createBankToken({
+     *   firstName: 'Jane',
+     *   lastName: 'Smith',
+     * });
+     */
+    createBankToken(options: BankTokenizeOptions): Promise<BankTokenResponse>;
+    /**
+     * Tokenizes all mounted elements. Raw card data never leaves the Ozura-origin
+     * iframes — the tokenizer iframe POSTs directly to the vault API.
+     *
+     * Returns a token and cvcSession that can be passed to the Ozura Pay API.
+     */
+    createToken(options?: TokenizeOptions): Promise<TokenResponse>;
+    /**
+     * Tears down the vault: removes all element iframes, the tokenizer iframe,
+     * and the global message listener. Call this when the checkout component
+     * unmounts (e.g. in React's useEffect cleanup or a SPA route change).
+     */
+    destroy(): void;
+    private mountTokenizerFrame;
+    private handleMessage;
+    /**
+     * Handles side-effects that the SDK manages internally when a field changes:
+     * - CVV length sync when card brand changes
+     * - Auto-advance focus when a field completes
+     */
+    private handleElementChange;
+    private handleTokenizerMessage;
+    private sendToTokenizer;
+}

package/dist/server/sdk/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * errors.ts — error types and normalisation for OzElements.
+ *
+ * Two normalisation functions:
+ *  - normalizeVaultError  — maps raw vault /tokenize errors to user-facing messages
+ *  - normalizeCardSaleError — maps raw cardSale API errors to user-facing messages
+ *
+ * Error keys in normalizeCardSaleError are taken directly from checkout's
+ * errorMapping.ts so the same error strings produce the same user-facing copy.
+ */
+export type OzErrorCode = 'network' | 'timeout' | 'auth' | 'validation' | 'server' | 'config' | 'unknown';
+export declare class OzError extends Error {
+    /** The raw error string returned by the vault or cardSale API, if available. */
+    readonly raw: string;
+    /**
+     * Structured error code classifying the failure.
+     * - `network` — connection failure or DNS resolution error
+     * - `timeout` — the request exceeded the 30s deadline
+     * - `auth` — 401/403 from the vault (bad API key or pub key)
+     * - `validation` — 400 from the vault (bad card data, missing fields)
+     * - `server` — 5xx from the vault (transient backend issue)
+     * - `config` — vault API URL is not in the permitted allowlist (SDK misconfiguration)
+     * - `unknown` — unclassifiable error
+     */
+    readonly errorCode: OzErrorCode;
+    /**
+     * `true` when the error is likely transient and worth retrying
+     * (`network`, `timeout`, `server`). `false` for permanent failures
+     * (`auth`, `validation`) where retrying with the same input won't help.
+     */
+    readonly retryable: boolean;
+    constructor(message: string, raw?: string, errorCode?: OzErrorCode);
+}
+/**
+ * Maps a raw vault /tokenize error string to a user-facing message for card flows.
+ * Falls back to the original string if no pattern matches.
+ */
+export declare function normalizeVaultError(raw: string): string;
+/**
+ * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
+ * Uses bank-specific pattern matching so card-specific messages are never shown for
+ * bank errors. Falls back to the original string if no pattern matches.
+ */
+export declare function normalizeBankVaultError(raw: string): string;
+/**
+ * Maps a raw Ozura Pay API cardSale error string to a user-facing message.
+ *
+ * Uses the exact same error key table as checkout's `getUserFriendlyError()` in
+ * errorMapping.ts so both surfaces produce identical copy for the same errors.
+ *
+ * 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.
+ */
+export declare function normalizeCardSaleError(raw: string): string;

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

@@ -0,0 +1,5 @@
+export { OzVault } from './OzVault';
+export { OzElement } from './OzElement';
+export { OzError, normalizeVaultError, normalizeCardSaleError } from './errors';
+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, } from '../types';

package/dist/server/server/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @ozura/server — Server-side SDK for the Ozura Pay API.
+ *
+ * Wraps cardSale and transaction query endpoints with typed methods,
+ * automatic field mapping, retry logic, and error handling.
+ *
+ * @example
+ * ```ts
+ * import { Ozura } from 'oz-elements/server';
+ *
+ * const ozura = new Ozura({
+ *   merchantId: process.env.MERCHANT_ID!,
+ *   apiKey: process.env.MERCHANT_API_KEY!,
+ *   vaultKey: process.env.VAULT_API_KEY!,
+ * });
+ *
+ * const result = await ozura.cardSale({
+ *   token: tokenResponse.token,
+ *   cvcSession: tokenResponse.cvcSession,
+ *   amount: '49.00',
+ *   currency: 'USD',
+ *   billing: tokenResponse.billing,
+ *   clientIpAddress: req.ip,
+ * });
+ *
+ * console.log(result.transactionId);
+ * ```
+ */
+import type { BillingDetails, CardSaleResponseData, TransactionQueryPagination } from '../types';
+export interface OzuraConfig {
+    /** Your Ozura merchant ID (e.g. "ozu_..."). */
+    merchantId: string;
+    /** Merchant Pay API key — sent as x-api-key header. */
+    apiKey: string;
+    /** Vault API key — same key used in OzVault on the frontend. */
+    vaultKey: string;
+    /** Ozura Pay API base URL. Defaults to staging. */
+    apiUrl?: 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. */
+    retries?: number;
+}
+export declare class OzuraError extends Error {
+    readonly statusCode: number;
+    readonly raw: string;
+    readonly retryAfter?: number;
+    constructor(message: string, statusCode: number, raw?: string, retryAfter?: number);
+}
+export interface CardSaleInput {
+    /** From TokenResponse.token (frontend SDK). */
+    token: string;
+    /** From TokenResponse.cvcSession (frontend SDK). */
+    cvcSession: string;
+    /** Decimal string, e.g. "49.00". */
+    amount: string;
+    /** ISO 4217, e.g. "USD". Default: "USD". */
+    currency?: string;
+    /** Billing from TokenResponse.billing, or assemble manually. */
+    billing: BillingDetails;
+    /** Client IP address — fetch server-side, never from the browser. */
+    clientIpAddress: string;
+    salesTaxExempt?: boolean;
+    /** Processor to use. If omitted, the Pay API auto-selects. */
+    processor?: 'elavon' | 'nuvei' | 'worldpay';
+    /** Defaults to "0.00". */
+    surchargePercent?: string;
+    /** Defaults to "0.00". */
+    tipAmount?: string;
+}
+export interface ListTransactionsInput {
+    dateFrom?: string;
+    dateTo?: string;
+    transactionType?: string;
+    page?: number;
+    limit?: number;
+    fields?: string;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+export interface ListTransactionsResult {
+    transactions: CardSaleResponseData[];
+    pagination: TransactionQueryPagination;
+}
+export declare class Ozura {
+    private merchantId;
+    private apiKey;
+    private vaultKey;
+    private apiUrl;
+    private timeoutMs;
+    private retries;
+    constructor(config: OzuraConfig);
+    /**
+     * Charge a tokenized card. Maps the friendly `CardSaleInput` shape to the
+     * Pay API's flat field format and handles headers, defaults, and errors.
+     *
+     * Rate limit: 100 requests/minute per merchant.
+     */
+    cardSale(input: CardSaleInput): Promise<CardSaleResponseData>;
+    /**
+     * Retrieve a single transaction by ID.
+     *
+     * **Known issue:** The Pay API requires the API key as a query parameter
+     * (`access_token`), which means it can appear in server logs, CDN caches,
+     * and HTTP Referer headers. This is a Pay API design issue — the SDK will
+     * switch to header-based auth once the backend supports it.
+     *
+     * Rate limit: 100 requests/minute per merchant.
+     */
+    getTransaction(transactionId: string): Promise<CardSaleResponseData>;
+    /**
+     * List transactions by date range with pagination.
+     *
+     * Rate limit: 200 requests/minute per merchant.
+     */
+    listTransactions(input?: ListTransactionsInput): Promise<ListTransactionsResult>;
+    /**
+     * Execute a fetch with retry on 5xx / network errors.
+     * 4xx errors (including 429) are never retried — they require caller action.
+     */
+    private fetchWithRetry;
+    private post;
+    private get;
+    private getRaw;
+    private handleResponse;
+}
+/**
+ * Extract the client IP address from a server request object.
+ * Works with Express (`req.ip`), Fastify (`request.ip`), Next.js App Router
+ * (`req.headers.get('x-forwarded-for')`), and raw Node.js `IncomingMessage`.
+ *
+ * @example
+ * // Express / Fastify
+ * clientIpAddress: getClientIp(req)
+ *
+ * // Next.js App Router
+ * clientIpAddress: getClientIp(req)
+ */
+export declare function getClientIp(req: Record<string, unknown>): string;
+export type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, } from '../types';