@ozura/elements 1.2.1 → 1.2.3

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

@@ -22,6 +22,8 @@ export declare class ElementFrame {
     private vaultId;
     private frameId;
     private hostOrigin;
+    /** Mirrors the parent vault's debug flag — set via OZ_INIT. */
+    private debug;
     private rawValue;
     private cardBrand;
     private cvvMaxLength;
@@ -64,6 +66,13 @@ export declare class ElementFrame {
     private reapplyStateStyles;
     private applyPlaceholderStyles;
     private fontsInjected;
+    /**
+     * Allowed hostnames for cssSrc font stylesheets. Restricting to known font
+     * CDNs prevents a merchant from loading arbitrary third-party stylesheets
+     * inside the PCI-isolated iframe, which could otherwise be used to load
+     * tracking scripts via @import or attempt CSS-based data extraction.
+     */
+    private static readonly ALLOWED_FONT_HOSTS;
     private injectFonts;
     /**
      * Delivers this field's raw value to the tokenizer iframe via the MessagePort

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

@@ -23,11 +23,27 @@ export declare function isAllowedVaultOrigin(apiUrl: string): boolean;
 export declare class TokenizerFrame {
     private vaultId;
     private hostOrigin;
-    /** Wax key delivered once via OZ_INIT. Used for all tokenize calls. */
+    /**
+     * Session key — delivered via OZ_INIT on first ready and again after each
+     * auto-refresh. The latest value is always used for tokenize calls.
+     */
     private waxKey;
     private pending;
     private pendingBank;
+    /** Mirrors the parent vault's debug flag — set via OZ_INIT. When true, the frame relays debug-level info in addition to errors/warnings. */
+    private debug;
     constructor();
+    /**
+     * Relays a message to the parent window as OZ_DEBUG_LOG so it surfaces in
+     * the merchant page's DevTools console rather than the hidden tokenizer-frame
+     * context.
+     *
+     * Level semantics:
+     *   'error' — always relayed (genuine failure)
+     *   'warn'  — always relayed (developer misconfiguration)
+     *   'log'   — only relayed when debug mode is enabled (lifecycle / timing info)
+     */
+    private postDebugLog;
     private onMessage;
     /**
      * Shared vault POST helper. Handles origin guard, header construction,

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

@@ -22,7 +22,10 @@ export declare class OzElement {
     private _loadTimer;
     private pendingMessages;
     private handlers;
-    constructor(elementType: AnyElementType, options: ElementOptions, vaultId: string, frameBaseUrl: string, fonts?: FontSource[], appearanceStyle?: ElementStyleConfig);
+    /** Called by OzVault when this element is destroyed so it can remove stale map entries. @internal */
+    private _onDestroy;
+    private debug;
+    constructor(elementType: AnyElementType, options: ElementOptions, vaultId: string, frameBaseUrl: string, fonts?: FontSource[], appearanceStyle?: ElementStyleConfig, onDestroy?: () => void, debug?: boolean);
     /** The element type this proxy represents. */
     get type(): AnyElementType;
     /** True once the element iframe has loaded and signalled ready. */

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

@@ -7,16 +7,10 @@ import { ElementType, BankElementType, ElementOptions, VaultOptions, TokenizeOpt
  * Use the static `OzVault.create()` factory — do not call `new OzVault()` directly.
  *
  * @example
+ * // Recommended — pass sessionUrl and let the SDK call your backend automatically
  * 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;
- *   },
+ *   pubKey: 'pk_prod_...',  // or 'pk_test_...' for test mode
+ *   sessionUrl: '/api/oz-session',  // backend endpoint that calls ozura.createSession()
  * });
  * const cardNum = vault.createElement('cardNumber');
  * cardNum.mount('#card-number');

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

@@ -17,12 +17,12 @@
  *
  * @example
  * // Simplest — just pass sessionUrl, no need to call this directly
- * const vault = await OzVault.create({ pubKey: 'pk_live_...', sessionUrl: '/api/oz-session' });
+ * const vault = await OzVault.create({ pubKey: 'pk_prod_...', sessionUrl: '/api/oz-session' });
  *
  * @example
  * // Manual — use when you need custom headers
  * const vault = await OzVault.create({
- *   pubKey: 'pk_live_...',
+ *   pubKey: 'pk_prod_...',
  *   getSessionKey: createSessionFetcher('/api/oz-session'),
  * });
  */

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

@@ -51,6 +51,13 @@ export interface OzuraConfig {
     timeoutMs?: number;
     /** Max retry attempts for 5xx / network errors. Default: 2 (up to 3 total attempts). Set 0 to disable. */
     retries?: number;
+    /**
+     * Enables structured debug logging to the server console.
+     * Logs method, path, HTTP status, and duration for every Pay API and vault request.
+     * Request bodies are included with sensitive fields (tokens, session keys) redacted.
+     * Never enable in production — for local development and CI debugging only.
+     */
+    debug?: boolean;
 }
 export declare class OzuraError extends Error {
     readonly statusCode: number;
@@ -155,6 +162,17 @@ export interface CardSaleInput {
     surchargePercent?: string;
     /** Defaults to "0.00". */
     tipAmount?: string;
+    /**
+     * Who initiated the transaction. Default: `'cit'` (customer-initiated) — correct
+     * for standard web checkouts. Override for MIT recurring charges (`'mit'`) or
+     * unscheduled credential-on-file charges (`'ucof'`).
+     */
+    transactionInitiationType?: 'cit' | 'mit' | 'ucof' | 'refund';
+    /**
+     * Channel through which the transaction is processed. Default: `'ecommerce'`.
+     * Override for MOTO (`'moto'`) or recurring scheduled charges (`'recurring'`).
+     */
+    transactionChannel?: 'cardPresent' | 'ecommerce' | 'moto' | 'recurring';
 }
 export interface ListTransactionsInput {
     /** Look up a single transaction by ID. When set, dateFrom/dateTo are not required. */
@@ -180,7 +198,15 @@ export declare class Ozura {
     private vaultUrl;
     private timeoutMs;
     private retries;
+    private debug;
     constructor(config: OzuraConfig);
+    /** Emits a `[Ozura]`-prefixed entry to `console.log`. No-op when `debug` is not set. */
+    private log;
+    /**
+     * Returns a copy of `body` with known-sensitive fields replaced by `'[REDACTED]'`.
+     * Used to make debug logs safe to emit without leaking vault tokens or session keys.
+     */
+    private static redactBody;
     /**
      * Charge a tokenized card. Maps the friendly `CardSaleInput` shape to the
      * Pay API's flat field format and handles headers, defaults, and errors.

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

@@ -418,27 +418,46 @@ export interface CardSaleRequest {
     amount: string;
     /** ISO 4217, e.g. "USD". */
     currency: string;
-    /** From TokenResponse.token */
-    ozuraCardToken: string;
+    /**
+     * Who initiated the transaction. Required by the Pay API.
+     * - `'cit'`  — Customer-Initiated Transaction (default for web checkouts).
+     * - `'mit'`  — Merchant-Initiated (scheduled recurring charge, customer not present).
+     * - `'ucof'` — Unscheduled Credential-on-File (threshold billing, account-updater, etc.).
+     * - `'refund'` — Voids, returns, reversals (not a stored-credential use).
+     */
+    transactionInitiationType: 'cit' | 'mit' | 'ucof' | 'refund';
+    /**
+     * Channel through which the transaction is processed. Required by the Pay API.
+     * - `'ecommerce'`  — Online, customer self-serve (default for web checkouts).
+     * - `'moto'`       — Mail order / telephone order.
+     * - `'cardPresent'`— POS / in-person.
+     * - `'recurring'`  — Scheduled MIT charge; never the initial CIT charge.
+     */
+    transactionChannel: 'cardPresent' | 'ecommerce' | 'moto' | 'recurring';
+    /** From TokenResponse.token. The vault token representing the stored card. */
+    ozuraVaultToken: string;
     /** From TokenResponse.cvcSession */
     ozuraCvcSession: string;
     billingFirstName: string;
     billingLastName: string;
-    /** Optional but must be non-empty if provided — Pay API enforces minLength 1. Omit the key rather than send "". */
+    /**
+     * Required by the Pay API (minLength 1). Optional here so merchants can omit it
+     * in rare server-side-only flows, but the Pay API will reject the request if absent.
+     */
     billingEmail?: string;
-    /** E.164 format, max 50 chars. Optional but must be non-empty if provided. */
+    /** E.164 format, max 50 chars. Required by the Pay API; optional here for flexibility. */
     billingPhone?: string;
-    /** Optional but must be non-empty if provided. */
+    /** Required by the Pay API; optional here for flexibility. Must be non-empty if provided. */
     billingAddress1?: string;
-    /** Omit entirely if blank — schema enforces minLength 1 if present. */
+    /** Omit entirely if blank — Pay API schema enforces minLength 1 if present. */
     billingAddress2?: string;
-    /** Optional but must be non-empty if provided. */
+    /** Required by the Pay API; optional here for flexibility. Must be non-empty if provided. */
     billingCity?: string;
-    /** 2-letter state/province code. Optional but must be non-empty if provided. */
+    /** 2-letter state/province code. Required by the Pay API; optional here for flexibility. */
     billingState?: string;
-    /** Optional but must be non-empty if provided. */
+    /** Required by the Pay API; optional here for flexibility. Must be non-empty if provided. */
     billingZipcode?: string;
-    /** ISO 3166-1 alpha-2. Defaults to 'US'. */
+    /** ISO 3166-1 alpha-2. Required by the Pay API. Defaults to 'US' in `Ozura.cardSale()`. */
     billingCountry?: string;
     /** Fetch from your server — use an internal route, not api.ipify.org (ad-blockers block it). */
     clientIpAddress: string;
@@ -637,7 +656,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_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 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' | 'OZ_DEBUG_LOG';
 export interface OzMessage {
     __oz: true;
     /** Protocol version stamped by the frame on OZ_FRAME_READY. Read by the SDK to detect stale CDN frames. */

package/dist/types/utils/billingUtils.d.ts

@@ -14,7 +14,8 @@ import { BillingDetails } from '../types';
 export declare function validateEmail(email: string): boolean;
 /**
  * Validates E.164 phone format: starts with +, 1–3 digit country code,
- * followed by 7–12 digits, total ≤50 characters.
+ * followed by 7–12 digits, max 15 digits total (E.164 spec cap = 16 chars
+ * including the leading +).
  *
  * Matches the output of checkout's formatPhoneForAPI() function.
  * Examples: "+15551234567", "+447911123456", "+61412345678"

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

@@ -0,0 +1,88 @@
+/**
+ * @ozura/elements/vue — Vue 3 wrapper for OzElements.
+ *
+ * Provides a context-based provider that creates and manages an OzVault instance,
+ * five individual field components, and a composable to access createToken +
+ * readiness state from anywhere inside the provider tree.
+ *
+ * Quick start:
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from '@ozura/elements/vue';
+ * const { createToken, ready } = useOzElements();
+ * </script>
+ *
+ * <template>
+ *   <OzElements pub-key="pk_live_..." session-url="/api/oz-session">
+ *     <OzCardNumber />
+ *     <OzExpiry />
+ *     <OzCvv />
+ *     <button :disabled="!ready" @click="createToken()">Pay</button>
+ *   </OzElements>
+ * </template>
+ * ```
+ */
+import { type Ref, type ComputedRef } from 'vue';
+import type { TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse, FontSource, Appearance } from '../types';
+export interface OzElementsProps {
+    pubKey: string;
+    sessionUrl?: string;
+    getSessionKey?: (sessionId: string) => Promise<string>;
+    frameBaseUrl?: string;
+    fonts?: FontSource[];
+    appearance?: Appearance;
+    loadTimeoutMs?: number;
+    debug?: boolean;
+}
+/**
+ * Creates and owns an OzVault instance for the lifetime of this component.
+ * All field components must be rendered inside this provider.
+ */
+export declare const OzElements: any;
+export interface UseOzElementsReturn {
+    /**
+     * Tokenizes all mounted card fields. Resolves with a token and cvcSession
+     * that can be passed to the Ozura Pay API endpoint.
+     */
+    createToken: (options?: TokenizeOptions) => Promise<TokenResponse>;
+    /**
+     * Tokenizes mounted bank account fields (accountNumber + routingNumber).
+     */
+    createBankToken: (options: BankTokenizeOptions) => Promise<BankTokenResponse>;
+    /**
+     * True when the vault tokenizer and all mounted field iframes are ready.
+     * Gate your submit button on this.
+     */
+    ready: ComputedRef<boolean>;
+    /**
+     * Non-null when OzVault.create() rejected during initialization.
+     */
+    initError: Ref<Error | null>;
+    /**
+     * Number of successful tokenizations since the last session refresh.
+     */
+    tokenizeCount: Ref<number>;
+    /**
+     * Clears all mounted element fields without destroying the vault.
+     */
+    reset: () => void;
+}
+/**
+ * Returns createToken, createBankToken, ready, initError, tokenizeCount, and reset.
+ * Must be called from inside an <OzElements> provider tree.
+ *
+ * @throws {Error} if called outside an <OzElements> provider
+ */
+export declare function useOzElements(): UseOzElementsReturn;
+/** Card number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzCardNumber: any;
+/** Expiry date field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzExpiry: any;
+/** CVV / CVC field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzCvv: any;
+/** Bank account number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzBankAccountNumber: any;
+/** Bank routing number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzBankRoutingNumber: any;
+export type { ElementChangeEvent, TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse, Appearance, FontSource, } from '../types';

package/dist/vue/frame/protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared postMessage protocol constants.
+ *
+ * PROTOCOL_VERSION must be incremented any time a breaking change is made to
+ * the postMessage message shape (new required fields, renamed types, removed
+ * fields, changed semantics). The SDK reads this value from OZ_FRAME_READY
+ * messages and warns when the frame and SDK are out of sync.
+ *
+ * Non-breaking additions (new optional fields, new message types that old
+ * frames can safely ignore) do NOT require a version bump.
+ */
+export declare const PROTOCOL_VERSION = 1;