@ozura/elements 1.2.1 → 1.2.4-next.47

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

@@ -0,0 +1,256 @@
+/**
+ * @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 PropType, 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: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    pubKey: {
+        type: StringConstructor;
+        required: true;
+    };
+    sessionUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    getSessionKey: {
+        type: PropType<(sessionId: string) => Promise<string>>;
+        default: undefined;
+    };
+    frameBaseUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    fonts: {
+        type: PropType<FontSource[]>;
+        default: undefined;
+    };
+    appearance: {
+        type: PropType<Appearance>;
+        default: undefined;
+    };
+    loadTimeoutMs: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "ready"[], "ready", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    pubKey: {
+        type: StringConstructor;
+        required: true;
+    };
+    sessionUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    getSessionKey: {
+        type: PropType<(sessionId: string) => Promise<string>>;
+        default: undefined;
+    };
+    frameBaseUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    fonts: {
+        type: PropType<FontSource[]>;
+        default: undefined;
+    };
+    appearance: {
+        type: PropType<Appearance>;
+        default: undefined;
+    };
+    loadTimeoutMs: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onReady?: ((...args: any[]) => any) | undefined;
+}>, {
+    debug: boolean;
+    fonts: FontSource[];
+    loadTimeoutMs: number;
+    frameBaseUrl: string;
+    sessionUrl: string;
+    getSessionKey: (sessionId: string) => Promise<string>;
+    appearance: Appearance;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, 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: import("vue").DefineComponent<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("blur" | "change" | "focus")[], "blur" | "change" | "focus", import("vue").PublicProps, Readonly<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    onFocus?: ((...args: any[]) => any) | undefined;
+    onBlur?: ((...args: any[]) => any) | undefined;
+}>, {
+    style: import("../types").ElementStyleConfig | undefined;
+    placeholder: string;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Expiry date field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzExpiry: import("vue").DefineComponent<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("blur" | "change" | "focus")[], "blur" | "change" | "focus", import("vue").PublicProps, Readonly<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    onFocus?: ((...args: any[]) => any) | undefined;
+    onBlur?: ((...args: any[]) => any) | undefined;
+}>, {
+    style: import("../types").ElementStyleConfig | undefined;
+    placeholder: string;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** CVV / CVC field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzCvv: import("vue").DefineComponent<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("blur" | "change" | "focus")[], "blur" | "change" | "focus", import("vue").PublicProps, Readonly<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    onFocus?: ((...args: any[]) => any) | undefined;
+    onBlur?: ((...args: any[]) => any) | undefined;
+}>, {
+    style: import("../types").ElementStyleConfig | undefined;
+    placeholder: string;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Bank account number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzBankAccountNumber: import("vue").DefineComponent<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("blur" | "change" | "focus")[], "blur" | "change" | "focus", import("vue").PublicProps, Readonly<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    onFocus?: ((...args: any[]) => any) | undefined;
+    onBlur?: ((...args: any[]) => any) | undefined;
+}>, {
+    style: import("../types").ElementStyleConfig | undefined;
+    placeholder: string;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Bank routing number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+export declare const OzBankRoutingNumber: import("vue").DefineComponent<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("blur" | "change" | "focus")[], "blur" | "change" | "focus", import("vue").PublicProps, Readonly<{
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    style?: import("../types").ElementStyleConfig | undefined;
+}> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    onFocus?: ((...args: any[]) => any) | undefined;
+    onBlur?: ((...args: any[]) => any) | undefined;
+}>, {
+    style: import("../types").ElementStyleConfig | undefined;
+    placeholder: string;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export type { ElementChangeEvent, TokenizeOptions, TokenResponse, BankTokenizeOptions, BankTokenResponse, Appearance, FontSource, } from '../types';

package/dist/server/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/server/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/server/index.cjs.js

@@ -87,13 +87,14 @@ function validateEmail(email) {
 // ─── Phone ───────────────────────────────────────────────────────────────────
 /**
  * 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"
  */
 function validateE164Phone(phone) {
-    return /^\+[1-9]\d{6,49}$/.test(phone) && phone.length <= 50;
+    return /^\+[1-9]\d{6,14}$/.test(phone);
 }
 // ─── Field length ─────────────────────────────────────────────────────────────
 /** Returns true when the string is non-empty and ≤50 characters (cardSale schema). */
@@ -293,8 +294,8 @@ function validateBilling(billing) {
  * ```
  */
 // ─── Configuration ───────────────────────────────────────────────────────────
-const DEFAULT_API_URL = "https://payapi.v2.ozurapay.com";
-const DEFAULT_VAULT_URL = "https://api.ozuravault.com";
+const DEFAULT_API_URL = "https://ozurapay-pay-api-v2-staging-c8abbdfhfbd3c5em.eastus-01.azurewebsites.net";
+const DEFAULT_VAULT_URL = "https://pci-vault-staging-drc0duhcakf4g4fr.eastus-01.azurewebsites.net";
 const DEFAULT_TIMEOUT = 30000;
 // ─── Error ───────────────────────────────────────────────────────────────────
 class OzuraError extends Error {
@@ -334,7 +335,7 @@ function timeoutSignal(ms) {
 // ─── Main class ──────────────────────────────────────────────────────────────
 class Ozura {
     constructor(config) {
-        var _a, _b;
+        var _a, _b, _c;
         if (!config.vaultKey)
             throw new OzuraError('vaultKey is required', 0);
         this.merchantId = config.merchantId;
@@ -344,6 +345,30 @@ class Ozura {
         this.vaultUrl = config.vaultUrl || DEFAULT_VAULT_URL;
         this.timeoutMs = (_a = config.timeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT;
         this.retries = (_b = config.retries) !== null && _b !== void 0 ? _b : DEFAULT_RETRIES;
+        this.debug = (_c = config.debug) !== null && _c !== void 0 ? _c : false;
+    }
+    /** Emits a `[Ozura]`-prefixed entry to `console.log`. No-op when `debug` is not set. */
+    log(message, data) {
+        if (!this.debug)
+            return;
+        if (data !== undefined) {
+            console.log(`[Ozura] ${message}`, data);
+        }
+        else {
+            console.log(`[Ozura] ${message}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    static redactBody(body) {
+        const SENSITIVE = new Set(['ozuraVaultToken', 'ozuraCvcSession', 'wax_key', 'waxKey']);
+        const result = {};
+        for (const [k, v] of Object.entries(body)) {
+            result[k] = SENSITIVE.has(k) ? '[REDACTED]' : v;
+        }
+        return result;
     }
     /**
      * Charge a tokenized card. Maps the friendly `CardSaleInput` shape to the
@@ -352,11 +377,12 @@ class Ozura {
      * Rate limit: 100 requests/minute per merchant.
      */
     async cardSale(input) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         if (!this.merchantId)
             throw new OzuraError('merchantId is required for cardSale(). Add it to the Ozura constructor config.', 0);
         if (!this.apiKey)
             throw new OzuraError('apiKey is required for cardSale(). Add it to the Ozura constructor config.', 0);
+        this.log('cardSale', { merchantId: this.merchantId, amount: input.amount, currency: input.currency || 'USD' });
         const billing = input.billing;
         // Build body with required fields, then conditionally add optional billing
         // fields only when non-empty. The Pay API enforces minLength:1 on these
@@ -366,30 +392,33 @@ class Ozura {
             merchantId: this.merchantId,
             amount: input.amount,
             currency: input.currency || 'USD',
-            ozuraCardToken: input.token,
+            // Pay API requires these two fields. Default to standard web-checkout values.
+            transactionInitiationType: (_a = input.transactionInitiationType) !== null && _a !== void 0 ? _a : 'cit',
+            transactionChannel: (_b = input.transactionChannel) !== null && _b !== void 0 ? _b : 'ecommerce',
+            ozuraVaultToken: input.token,
             ozuraCvcSession: input.cvcSession,
             billingFirstName: billing.firstName,
             billingLastName: billing.lastName,
             clientIpAddress: input.clientIpAddress,
-            salesTaxExempt: (_a = input.salesTaxExempt) !== null && _a !== void 0 ? _a : false,
-            surchargePercent: (_b = input.surchargePercent) !== null && _b !== void 0 ? _b : '0.00',
-            tipAmount: (_c = input.tipAmount) !== null && _c !== void 0 ? _c : '0.00',
+            salesTaxExempt: (_c = input.salesTaxExempt) !== null && _c !== void 0 ? _c : false,
+            surchargePercent: (_d = input.surchargePercent) !== null && _d !== void 0 ? _d : '0.00',
+            tipAmount: (_e = input.tipAmount) !== null && _e !== void 0 ? _e : '0.00',
         };
         if (billing.email)
             body.billingEmail = billing.email;
         if (billing.phone)
             body.billingPhone = billing.phone;
-        if ((_d = billing.address) === null || _d === void 0 ? void 0 : _d.line1)
+        if ((_f = billing.address) === null || _f === void 0 ? void 0 : _f.line1)
             body.billingAddress1 = billing.address.line1;
-        if ((_e = billing.address) === null || _e === void 0 ? void 0 : _e.line2)
+        if ((_g = billing.address) === null || _g === void 0 ? void 0 : _g.line2)
             body.billingAddress2 = billing.address.line2;
-        if ((_f = billing.address) === null || _f === void 0 ? void 0 : _f.city)
+        if ((_h = billing.address) === null || _h === void 0 ? void 0 : _h.city)
             body.billingCity = billing.address.city;
-        if ((_g = billing.address) === null || _g === void 0 ? void 0 : _g.state)
+        if ((_j = billing.address) === null || _j === void 0 ? void 0 : _j.state)
             body.billingState = billing.address.state;
-        if ((_h = billing.address) === null || _h === void 0 ? void 0 : _h.zip)
+        if ((_k = billing.address) === null || _k === void 0 ? void 0 : _k.zip)
             body.billingZipcode = billing.address.zip;
-        body.billingCountry = ((_j = billing.address) === null || _j === void 0 ? void 0 : _j.country) || 'US';
+        body.billingCountry = ((_l = billing.address) === null || _l === void 0 ? void 0 : _l.country) || 'US';
         if (input.processor) {
             body.processor = input.processor;
         }
@@ -457,7 +486,8 @@ class Ozura {
      * app.post('/api/oz-session', createSessionMiddleware(ozura));
      */
     async createSession(options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
+        this.log('createSession', { sessionId: options === null || options === void 0 ? void 0 : options.sessionId, sessionLimit: (_a = options === null || options === void 0 ? void 0 : options.sessionLimit) !== null && _a !== void 0 ? _a : 3 });
         const body = {};
         if (options === null || options === void 0 ? void 0 : options.sessionId) {
             body.checkout_session_id = options.sessionId;
@@ -467,7 +497,7 @@ class Ozura {
         // sessionLimit: number → use that value.
         if ((options === null || options === void 0 ? void 0 : options.sessionLimit) === null) ;
         else {
-            body.max_tokenize_calls = (_a = options === null || options === void 0 ? void 0 : options.sessionLimit) !== null && _a !== void 0 ? _a : 3;
+            body.max_tokenize_calls = (_b = options === null || options === void 0 ? void 0 : options.sessionLimit) !== null && _b !== void 0 ? _b : 3;
         }
         // maxProxyCalls: null → omit (unlimited). undefined → omit (vault default).
         if ((options === null || options === void 0 ? void 0 : options.maxProxyCalls) != null) {
@@ -483,6 +513,7 @@ class Ozura {
             body.metadata = options.metadata;
         if ((options === null || options === void 0 ? void 0 : options.ttlSeconds) != null)
             body.ttl_seconds = options.ttlSeconds;
+        const sessionStartMs = Date.now();
         const res = await this.fetchWithRetry(`${this.vaultUrl}/internal/wax-session`, {
             method: 'POST',
             headers: {
@@ -492,15 +523,16 @@ class Ozura {
             body: JSON.stringify(body),
         });
         const json = await res.json().catch(() => ({}));
-        if (res.status === 201) {
+        this.log(`createSession → ${res.status} (${Date.now() - sessionStartMs}ms)`);
+        if (res.ok) {
             const data = json.data;
-            const sessionKey = String((_b = data === null || data === void 0 ? void 0 : data.wax_key) !== null && _b !== void 0 ? _b : '');
+            const sessionKey = String((_c = data === null || data === void 0 ? void 0 : data.wax_key) !== null && _c !== void 0 ? _c : '');
             if (!sessionKey) {
                 throw new OzuraError('Vault session response missing data.wax_key', res.status, JSON.stringify(json));
             }
             return {
                 sessionKey,
-                expiresInSeconds: Number((_c = data === null || data === void 0 ? void 0 : data.expires_in_seconds) !== null && _c !== void 0 ? _c : 1800),
+                expiresInSeconds: Number((_d = data === null || data === void 0 ? void 0 : data.expires_in_seconds) !== null && _d !== void 0 ? _d : 1800),
             };
         }
         const errorCode = json.error_code || '';
@@ -622,11 +654,20 @@ class Ozura {
         if (includeVaultKey) {
             headers['vault-api-key'] = this.vaultKey;
         }
-        const res = await this.fetchWithRetry(`${this.apiUrl}${path}`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(body),
-        }, maxRetries);
+        const postStartMs = Date.now();
+        let res;
+        try {
+            res = await this.fetchWithRetry(`${this.apiUrl}${path}`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            }, maxRetries);
+        }
+        catch (err) {
+            this.log(`POST ${path} ERROR (${Date.now() - postStartMs}ms)`, { error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        this.log(`POST ${path} → ${res.status} (${Date.now() - postStartMs}ms)`, Ozura.redactBody(body));
         return this.handleResponse(res);
     }
     async getRaw(path) {