@ozura/elements 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/types/frame/tokenizerFrame.d.ts

@@ -4,17 +4,17 @@
  * Collects raw card field values sent by element frames (same-origin),
  * assembles the vault tokenization payload, and POSTs it directly to the
  * vault API. The merchant page never sees raw card data.
+ *
+ * The vault URL is determined by __VAULT_API_URL__, injected at build time.
+ * The tokenizer ignores any apiUrl sent by the SDK in OZ_TOKENIZE messages —
+ * an attacker who XSSes the merchant page cannot redirect where card data is
+ * sent because the destination is hardcoded in this Ozura-controlled bundle.
  */
 /**
- * Returns true when the given URL is a valid target for card data.
- *
- * The only requirement is that it is a parseable absolute URL using HTTPS
- * (or HTTP for localhost in dev). Merchant-specific domain allowlisting is
- * intentionally NOT done here — the vault API authenticates every request
- * via the merchant's private API key, so there is no security benefit to
- * restricting which HTTPS hosts the tokenizer may POST to. Baking a domain
- * allowlist into the frame bundle would force an SDK republish on every new
- * merchant onboarding, which is the wrong operational model.
+ * Defense-in-depth guard: only allows the build-time vault URL origin.
+ * The tokenizer already uses VAULT_API_URL directly and never reads
+ * the merchant-supplied apiUrl, so this is a secondary safety net —
+ * not the primary security boundary.
  *
  * Exported for unit testing only — not part of the public SDK API.
  */

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

@@ -15,7 +15,6 @@ import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOpt
 export declare class OzVault {
     private apiKey;
     private pubKey;
-    private apiUrl;
     private frameBaseUrl;
     private frameOrigin;
     private fonts;
@@ -63,6 +62,7 @@ export declare class OzVault {
     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;
+    private createElementInto;
     /**
      * Tokenizes mounted bank account elements. Raw account and routing numbers
      * never leave the Ozura-origin iframes — the tokenizer iframe POSTs directly

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

@@ -1,9 +1,10 @@
 /**
  * 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
+ * Three normalisation functions:
+ *  - normalizeVaultError      — maps raw vault /tokenize errors to user-facing messages (card flows)
+ *  - normalizeBankVaultError   — maps raw vault /tokenize errors to user-facing messages (bank/ACH flows)
+ *  - 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.

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

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

@@ -26,7 +26,7 @@
  * console.log(result.transactionId);
  * ```
  */
-import type { BillingDetails, CardSaleResponseData, TransactionQueryPagination } from '../types';
+import type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, TransactionData, TransactionType } from '../types';
 export interface OzuraConfig {
     /** Your Ozura merchant ID (e.g. "ozu_..."). */
     merchantId: string;
@@ -69,9 +69,11 @@ export interface CardSaleInput {
     tipAmount?: string;
 }
 export interface ListTransactionsInput {
+    /** Look up a single transaction by ID. When set, dateFrom/dateTo are not required. */
+    transactionId?: string;
     dateFrom?: string;
     dateTo?: string;
-    transactionType?: string;
+    transactionType?: TransactionType;
     page?: number;
     limit?: number;
     fields?: string;
@@ -79,7 +81,7 @@ export interface ListTransactionsInput {
     sortOrder?: 'asc' | 'desc';
 }
 export interface ListTransactionsResult {
-    transactions: CardSaleResponseData[];
+    transactions: TransactionData[];
     pagination: TransactionQueryPagination;
 }
 export declare class Ozura {
@@ -97,17 +99,6 @@ export declare class Ozura {
      * 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.
      *
@@ -120,14 +111,17 @@ export declare class Ozura {
      */
     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`.
+ * (`req.headers.get(…)`), and raw Node.js `IncomingMessage`.
+ *
+ * Header priority: `req.ip` (framework-resolved) → `cf-connecting-ip`
+ * (Cloudflare) → `x-forwarded-for` (reverse proxy) → `x-real-ip` →
+ * `socket.remoteAddress` → `"0.0.0.0"`.
  *
  * @example
  * // Express / Fastify
@@ -137,4 +131,4 @@ export declare class Ozura {
  * clientIpAddress: getClientIp(req)
  */
 export declare function getClientIp(req: Record<string, unknown>): string;
-export type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, } from '../types';
+export type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, TransactionType, TransactionBase, CardTransactionData, AchTransactionData, CryptoTransactionData, TransactionData, } from '../types';

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

@@ -150,8 +150,6 @@ export interface Appearance {
     variables?: AppearanceVariables;
 }
 export interface VaultOptions {
-    /** Base URL of the vault API. Defaults to the Ozura production vault. */
-    apiUrl?: string;
     /** System pub key required for tokenization. Obtain from Ozura admin.
      *  Sent as the `X-Pub-Key` header on tokenize requests. */
     pubKey: string;
@@ -388,6 +386,95 @@ export interface CardSaleApiResponse {
     success: boolean;
     data: CardSaleResponseData;
 }
+/**
+ * Transaction types returned by the Pay API transQuery endpoint.
+ * Mirrors the `TransactionType` enum in PayAPI-BE.
+ */
+export type TransactionType = 'CreditCardSale' | 'CreditCardReversal' | 'CreditCardReturn' | 'CreditCardVoid' | 'AchSale' | 'AchReversal' | 'AchReturn' | 'AchVoid' | 'CryptoSale' | 'CryptoReturn' | 'CryptoWithdrawal';
+export type CardTransactionType = 'CreditCardSale' | 'CreditCardReversal' | 'CreditCardReturn' | 'CreditCardVoid';
+export type AchTransactionType = 'AchSale' | 'AchReversal' | 'AchReturn' | 'AchVoid';
+export type CryptoTransactionType = 'CryptoSale' | 'CryptoReturn' | 'CryptoWithdrawal';
+/**
+ * Shared fields returned by transQuery for all transaction types.
+ *
+ * Note: transQuery returns billing fields as `firstName`, `lastName`, etc.
+ * (the MongoDB field names), NOT the `billingFirstName` format used by the
+ * cardSale endpoint response. This is a backend inconsistency — these types
+ * reflect what the API actually returns.
+ */
+export interface TransactionBase {
+    transactionId: string;
+    originalTransactionId?: string;
+    relatedTransactionIds?: string[];
+    transactionType: TransactionType;
+    amount: string;
+    currentAmount?: string;
+    surchargeAmount?: string;
+    tipAmount?: string;
+    currency: string;
+    status: string;
+    createdAt: string;
+    clientIpAddress?: string;
+    isVoided?: boolean;
+    isPartiallyReturned?: boolean;
+    isFullyReturned?: boolean;
+    isReversed?: boolean;
+    ozuraUserDetails?: {
+        ozuraUserId?: string;
+        ozuraMerchantId?: string;
+    };
+    avsResponseCode?: string;
+    cvvResponseCode?: string;
+    salesTaxData?: Record<string, unknown>;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    address1?: string;
+    address2?: string;
+    city?: string;
+    state?: string;
+    zipcode?: string;
+    country?: string;
+}
+/** Card transaction returned by transQuery. */
+export interface CardTransactionData extends TransactionBase {
+    transactionType: CardTransactionType;
+    cardLastFour?: string;
+    cardBin?: string;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    cardBrand?: string;
+    isCreditCard?: boolean;
+}
+/** ACH transaction returned by transQuery. */
+export interface AchTransactionData extends TransactionBase {
+    transactionType: AchTransactionType;
+    ddaAccountType?: string;
+    accountNumber?: string;
+    routingNumber?: string;
+}
+/** Crypto transaction returned by transQuery. */
+export interface CryptoTransactionData extends TransactionBase {
+    transactionType: CryptoTransactionType;
+    originalSourceAddress?: string;
+    originalDepositAddress?: string;
+    network?: string;
+    mintDetails?: {
+        mintTransactionHash?: string;
+    };
+}
+/**
+ * Discriminated union of all transaction types returned by transQuery.
+ * Narrow via `transactionType` to access type-specific fields:
+ *
+ * ```ts
+ * if (tx.transactionType === 'CreditCardSale') {
+ *   console.log(tx.cardLastFour); // TS knows this exists
+ * }
+ * ```
+ */
+export type TransactionData = CardTransactionData | AchTransactionData | CryptoTransactionData;
 /** Query params for GET /api/v1/transQuery. */
 export interface TransactionQueryParams {
     merchantId: string;
@@ -397,8 +484,8 @@ export interface TransactionQueryParams {
     dateFrom?: string;
     /** Date range end, format "YYYY-MM-DD HH:MM:SS". */
     dateTo?: string;
-    /** Filter by type, e.g. "sale", "refund". */
-    transactionType?: string;
+    /** Filter by transaction type, e.g. "CreditCardSale", "AchSale". */
+    transactionType?: TransactionType;
     /** 1-based page number. Default: 1. */
     page?: number;
     /** Results per page. Default: 50, max: 100. */
@@ -420,7 +507,7 @@ export interface TransactionQueryPagination {
 }
 export interface TransactionQueryResponse {
     success: boolean;
-    data: CardSaleResponseData[];
+    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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "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",
@@ -72,7 +72,7 @@
     "url": "https://github.com/Ozura-Inc/pci-vault-elements"
   },
   "engines": {
-    "node": ">=18 <24"
+    "node": ">=18"
   },
   "sideEffects": false,
   "devDependencies": {