@ozura/elements 0.1.0-beta.6 → 1.0.0

package/dist/server/index.cjs.js

@@ -1,5 +1,269 @@
 'use strict';
 
+/**
+ * errors.ts — error types and normalisation for OzElements.
+ *
+ * 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.
+ */
+// ─── cardSale error map (mirrors checkout/src/utils/errorMapping.ts exactly) ─
+const CARD_SALE_ERROR_MAP = [
+    ['Insufficient Funds', 'Your card has insufficient funds. Please use a different payment method.'],
+    ['Invalid card number', 'The card number you entered is invalid. Please check and try again.'],
+    ['Card expired', 'Your card has expired. Please use a different card.'],
+    ['CVV Verification Failed', 'The CVV code you entered is incorrect. Please check and try again.'],
+    ['Address Verification Failed', 'The billing address does not match your card. Please verify your address.'],
+    ['Do Not Honor', 'Your card was declined. Please contact your bank or use a different payment method.'],
+    ['Declined', 'Your card was declined. Please contact your bank or use a different payment method.'],
+    ['Surcharge is currently not supported', 'Surcharge fees are not supported at this time.'],
+    ['Surcharge percent must be between', 'Surcharge fees are not supported at this time.'],
+    ['Forbidden - API key', 'Authentication failed. Please refresh the page.'],
+    ['Api Key is invalid', 'Authentication failed. Please refresh the page.'],
+    ['API key not found', 'Authentication failed. Please refresh the page.'],
+    ['Access token expired', 'Your session has expired. Please refresh the page.'],
+    ['Access token is invalid', 'Authentication failed. Please refresh the page.'],
+    ['Unauthorized', 'Authentication failed. Please refresh the page.'],
+    ['Too Many Requests', 'Too many requests. Please wait a moment and try again.'],
+    ['Rate limit exceeded', 'System is busy. Please wait a moment and try again.'],
+    ['No processor integrations found', 'Payment processing is not configured for this merchant. Please contact the merchant for assistance.'],
+    ['processor integration', 'Payment processing is temporarily unavailable. Please try again later or contact the merchant.'],
+    ['Invalid zipcode', 'The ZIP code you entered is invalid. Please check and try again.'],
+    ['failed to save to database', 'Your payment was processed but we encountered an issue. Please contact support.'],
+    ['CASHBACK UNAVAIL', 'This transaction type is not supported. Please try again or use a different payment method.'],
+];
+/**
+ * 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.
+ *
+ * **Trade-off:** Short unrecognised strings (e.g. processor codes like
+ * `"PROC_TIMEOUT"`) are passed through verbatim. This intentionally mirrors
+ * checkout so the same raw Pay API errors produce the same user-facing text on
+ * both surfaces. If the Pay API ever returns internal codes that should never
+ * reach the UI, the fix belongs in the Pay API error normalisation layer rather
+ * than here.
+ */
+function normalizeCardSaleError(raw) {
+    if (!raw)
+        return 'Payment processing failed. Please try again.';
+    for (const [key, message] of CARD_SALE_ERROR_MAP) {
+        if (raw.toLowerCase().includes(key.toLowerCase())) {
+            return message;
+        }
+    }
+    // Checkout fallback: pass through short errors, genericise long ones
+    if (raw.length < 100)
+        return raw;
+    return 'Payment processing failed. Please try again or contact support.';
+}
+
+/**
+ * billingUtils.ts — billing detail validation and normalization.
+ *
+ * Mirrors the validation in checkout/page.tsx (pre-flight checks before cardSale)
+ * so that billing data passed to createToken() is guaranteed schema-compliant and
+ * ready to forward directly to the Ozura Pay API cardSale endpoint.
+ *
+ * All string fields enforced to 1–50 characters (cardSale schema constraint).
+ * State is normalized to 2-letter abbreviation for US and CA.
+ * Phone must be E.164 format (matches checkout's formatPhoneForAPI output).
+ */
+// ─── Email ────────────────────────────────────────────────────────────────────
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Returns true when the email is syntactically valid and ≤50 characters. */
+function validateEmail(email) {
+    return EMAIL_RE.test(email) && email.length <= 50;
+}
+// ─── Phone ───────────────────────────────────────────────────────────────────
+/**
+ * Validates E.164 phone format: starts with +, 1–3 digit country code,
+ * followed by 7–12 digits, total ≤50 characters.
+ *
+ * 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;
+}
+// ─── Field length ─────────────────────────────────────────────────────────────
+/** Returns true when the string is non-empty and ≤50 characters (cardSale schema). */
+function isValidBillingField(value) {
+    return value.length > 0 && value.length <= 50;
+}
+// ─── US state normalization ───────────────────────────────────────────────────
+// Mirrors checkout's convertStateToAbbreviation() so the same input variants work.
+const US_STATES = {
+    alabama: 'AL', alaska: 'AK', arizona: 'AZ', arkansas: 'AR',
+    california: 'CA', colorado: 'CO', connecticut: 'CT', delaware: 'DE',
+    'district of columbia': 'DC', florida: 'FL', georgia: 'GA', hawaii: 'HI',
+    idaho: 'ID', illinois: 'IL', indiana: 'IN', iowa: 'IA', kansas: 'KS',
+    kentucky: 'KY', louisiana: 'LA', maine: 'ME', maryland: 'MD',
+    massachusetts: 'MA', michigan: 'MI', minnesota: 'MN', mississippi: 'MS',
+    missouri: 'MO', montana: 'MT', nebraska: 'NE', nevada: 'NV',
+    'new hampshire': 'NH', 'new jersey': 'NJ', 'new mexico': 'NM', 'new york': 'NY',
+    'north carolina': 'NC', 'north dakota': 'ND', ohio: 'OH', oklahoma: 'OK',
+    oregon: 'OR', pennsylvania: 'PA', 'rhode island': 'RI', 'south carolina': 'SC',
+    'south dakota': 'SD', tennessee: 'TN', texas: 'TX', utah: 'UT',
+    vermont: 'VT', virginia: 'VA', washington: 'WA', 'west virginia': 'WV',
+    wisconsin: 'WI', wyoming: 'WY',
+    // US territories
+    'puerto rico': 'PR', guam: 'GU', 'virgin islands': 'VI',
+    'us virgin islands': 'VI', 'u.s. virgin islands': 'VI',
+    'american samoa': 'AS', 'northern mariana islands': 'MP',
+    'commonwealth of the northern mariana islands': 'MP',
+    // Military / diplomatic addresses
+    'armed forces europe': 'AE', 'armed forces pacific': 'AP',
+    'armed forces americas': 'AA',
+};
+const US_ABBREVS = new Set(Object.values(US_STATES));
+const CA_PROVINCES = {
+    alberta: 'AB', 'british columbia': 'BC', manitoba: 'MB', 'new brunswick': 'NB',
+    'newfoundland and labrador': 'NL', 'nova scotia': 'NS', ontario: 'ON',
+    'prince edward island': 'PE', quebec: 'QC', saskatchewan: 'SK',
+    'northwest territories': 'NT', nunavut: 'NU', yukon: 'YT',
+};
+const CA_ABBREVS = new Set(Object.values(CA_PROVINCES));
+/**
+ * Converts a full US state or Canadian province name to its 2-letter abbreviation.
+ * If already a valid abbreviation (case-insensitive), returns it uppercased.
+ * For non-US/CA countries, returns the input uppercased unchanged.
+ *
+ * Matches checkout's convertStateToAbbreviation() behaviour exactly.
+ */
+function normalizeState(state, country) {
+    var _a, _b;
+    const upper = state.trim().toUpperCase();
+    const lower = state.trim().toLowerCase();
+    if (country === 'US') {
+        if (US_ABBREVS.has(upper))
+            return upper;
+        return (_a = US_STATES[lower]) !== null && _a !== void 0 ? _a : upper;
+    }
+    if (country === 'CA') {
+        if (CA_ABBREVS.has(upper))
+            return upper;
+        return (_b = CA_PROVINCES[lower]) !== null && _b !== void 0 ? _b : upper;
+    }
+    return upper;
+}
+// ─── Postal code validation ───────────────────────────────────────────────────
+const POSTAL_PATTERNS = {
+    US: /^\d{5}(-?\d{4})?$/, // 5-digit or ZIP+4 (with or without hyphen)
+    CA: /^[A-Za-z]\d[A-Za-z]\s?\d[A-Za-z]\d$/, // A1A 1A1
+    GB: /^[A-Za-z]{1,2}\d[A-Za-z\d]?\s?\d[A-Za-z]{2}$/,
+    DE: /^\d{5}$/,
+    FR: /^\d{5}$/,
+    ES: /^\d{5}$/,
+    IT: /^\d{5}$/,
+    AU: /^\d{4}$/,
+    NL: /^\d{4}\s?[A-Za-z]{2}$/,
+    BR: /^\d{5}-?\d{3}$/,
+    JP: /^\d{3}-?\d{4}$/,
+    IN: /^\d{6}$/,
+};
+/**
+ * Validates a postal/ZIP code against country-specific format rules.
+ * For countries without a specific pattern, falls back to generic 1–50 char check.
+ */
+function validatePostalCode(zip, country) {
+    if (!zip || zip.length === 0)
+        return { valid: false, error: 'Postal code is required' };
+    if (zip.length > 50)
+        return { valid: false, error: 'Postal code must be 50 characters or fewer' };
+    const pattern = POSTAL_PATTERNS[country.toUpperCase()];
+    if (pattern && !pattern.test(zip)) {
+        return { valid: false, error: `Invalid postal code format for ${country.toUpperCase()}` };
+    }
+    return { valid: true };
+}
+/**
+ * Validates and normalizes billing details against the Ozura cardSale API schema.
+ *
+ * Rules applied (same as checkout's pre-flight validation in page.tsx):
+ * - firstName, lastName: required, 1–50 chars
+ * - email: optional; if provided, must be valid format and ≤50 chars
+ * - phone: optional; if provided, must be E.164 and ≤50 chars
+ * - address fields: if address is provided, line1/city/state/zip/country are
+ *   required (1–50 chars each); line2 is optional and omitted from normalized
+ *   output if blank (cardSale schema: minLength 1 if present)
+ * - state: normalized to 2-letter abbreviation for US and CA
+ */
+function validateBilling(billing) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+    const errors = [];
+    const firstName = (_b = (_a = billing.firstName) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+    const lastName = (_d = (_c = billing.lastName) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _d !== void 0 ? _d : '';
+    const email = (_f = (_e = billing.email) === null || _e === void 0 ? void 0 : _e.trim()) !== null && _f !== void 0 ? _f : '';
+    const phone = (_h = (_g = billing.phone) === null || _g === void 0 ? void 0 : _g.trim()) !== null && _h !== void 0 ? _h : '';
+    if (!isValidBillingField(firstName)) {
+        errors.push('billing.firstName must be 1–50 characters');
+    }
+    if (!isValidBillingField(lastName)) {
+        errors.push('billing.lastName must be 1–50 characters');
+    }
+    if (email && !validateEmail(email)) {
+        errors.push('billing.email must be a valid address (max 50 characters)');
+    }
+    if (phone && !validateE164Phone(phone)) {
+        errors.push('billing.phone must be E.164 format, e.g. "+15551234567" (max 50 characters)');
+    }
+    let normalizedAddress;
+    if (billing.address) {
+        const a = billing.address;
+        const country = (_k = (_j = a.country) === null || _j === void 0 ? void 0 : _j.trim().toUpperCase()) !== null && _k !== void 0 ? _k : '';
+        const line1 = (_m = (_l = a.line1) === null || _l === void 0 ? void 0 : _l.trim()) !== null && _m !== void 0 ? _m : '';
+        const line2 = (_p = (_o = a.line2) === null || _o === void 0 ? void 0 : _o.trim()) !== null && _p !== void 0 ? _p : '';
+        const city = (_r = (_q = a.city) === null || _q === void 0 ? void 0 : _q.trim()) !== null && _r !== void 0 ? _r : '';
+        const zip = (_t = (_s = a.zip) === null || _s === void 0 ? void 0 : _s.trim()) !== null && _t !== void 0 ? _t : '';
+        const state = normalizeState((_v = (_u = a.state) === null || _u === void 0 ? void 0 : _u.trim()) !== null && _v !== void 0 ? _v : '', country);
+        if (!isValidBillingField(line1))
+            errors.push('billing.address.line1 must be 1–50 characters');
+        if (line2 && !isValidBillingField(line2))
+            errors.push('billing.address.line2 must be 1–50 characters if provided');
+        if (!isValidBillingField(city))
+            errors.push('billing.address.city must be 1–50 characters');
+        if (!isValidBillingField(state)) {
+            errors.push('billing.address.state must be 1–50 characters');
+        }
+        else if (country === 'US' && !US_ABBREVS.has(state)) {
+            errors.push(`billing.address.state "${state}" is not a recognized US state or territory abbreviation (e.g. "CA", "NY", "PR")`);
+        }
+        else if (country === 'CA' && !CA_ABBREVS.has(state)) {
+            errors.push(`billing.address.state "${state}" is not a recognized Canadian province or territory abbreviation (e.g. "ON", "BC", "QC")`);
+        }
+        // cardSale backend uses strict enum validation on country — must be exactly 2 uppercase letters
+        if (!/^[A-Z]{2}$/.test(country)) {
+            errors.push('billing.address.country must be a 2-letter ISO 3166-1 alpha-2 code (e.g. "US", "CA", "GB")');
+        }
+        if (!isValidBillingField(zip)) {
+            errors.push('billing.address.zip must be 1–50 characters');
+        }
+        else if (/^[A-Z]{2}$/.test(country)) {
+            const postalResult = validatePostalCode(zip, country);
+            if (!postalResult.valid) {
+                errors.push(`billing.address.zip: ${postalResult.error}`);
+            }
+        }
+        normalizedAddress = Object.assign(Object.assign({ line1 }, (line2 ? { line2 } : {})), { city,
+            state,
+            zip,
+            country });
+    }
+    const normalized = Object.assign(Object.assign(Object.assign({ firstName,
+        lastName }, (email ? { email } : {})), (phone ? { phone } : {})), (normalizedAddress ? { address: normalizedAddress } : {}));
+    return { valid: errors.length === 0, errors, normalized };
+}
+
 /**
  * @ozura/server — Server-side SDK for the Ozura Pay API.
  *
@@ -8,7 +272,7 @@
  *
  * @example
  * ```ts
- * import { Ozura } from 'oz-elements/server';
+ * import { Ozura } from '@ozura/elements/server';
  *
  * const ozura = new Ozura({
  *   merchantId: process.env.MERCHANT_ID!,
@@ -29,7 +293,8 @@
  * ```
  */
 // ─── Configuration ───────────────────────────────────────────────────────────
-const DEFAULT_API_URL = "https://ozurapay-pay-api-v2-staging-c8abbdfhfbd3c5em.eastus-01.azurewebsites.net";
+const DEFAULT_API_URL = "https://payapi.v2.ozurapay.com";
+const DEFAULT_VAULT_URL = "https://api.ozuravault.com";
 const DEFAULT_TIMEOUT = 30000;
 // ─── Error ───────────────────────────────────────────────────────────────────
 class OzuraError extends Error {
@@ -49,6 +314,23 @@ function isRetryable(status) {
 async function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Returns an AbortSignal that aborts after `ms` milliseconds.
+ *
+ * Uses `AbortSignal.timeout()` when available (Node 17.3+ / 18.0+) and
+ * falls back to a manual `AbortController` + `setTimeout` for Node 16 and
+ * other older runtimes. Both paths produce an `AbortError`-family signal;
+ * the catch sites in this file only use `err.message` so the difference in
+ * `err.name` (`'AbortError'` vs `'TimeoutError'`) is inconsequential.
+ */
+function timeoutSignal(ms) {
+    if (typeof AbortSignal.timeout === 'function') {
+        return AbortSignal.timeout(ms);
+    }
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), ms);
+    return controller.signal;
+}
 // ─── Main class ──────────────────────────────────────────────────────────────
 class Ozura {
     constructor(config) {
@@ -63,6 +345,7 @@ class Ozura {
         this.apiKey = config.apiKey;
         this.vaultKey = config.vaultKey;
         this.apiUrl = config.apiUrl || DEFAULT_API_URL;
+        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;
     }
@@ -132,17 +415,119 @@ class Ozura {
         const raw = await this.getRaw(`/api/v1/transQuery?${qs}`);
         return { transactions: raw.data, pagination: raw.pagination };
     }
+    // ─── Wax key helpers ─────────────────────────────────────────────────────
+    /**
+     * 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.
+     *
+     * **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.
+     *
+     * **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.
+     *
+     * @example
+     * // Next.js API route
+     * export async function POST(req: Request) {
+     *   const { sessionId } = await req.json();
+     *   const { waxKey } = await ozura.mintWaxKey({
+     *     tokenizationSessionId: sessionId,
+     *     maxTokenizeCalls: 3,
+     *   });
+     *   return Response.json({ waxKey });
+     * }
+     */
+    async mintWaxKey(options) {
+        var _a, _b, _c;
+        const body = {};
+        if (options === null || options === void 0 ? void 0 : options.tokenizationSessionId) {
+            body.checkout_session_id = options.tokenizationSessionId;
+        }
+        // Always send max_tokenize_calls — default 3 if not overridden.
+        body.max_tokenize_calls = (_a = options === null || options === void 0 ? void 0 : options.maxTokenizeCalls) !== null && _a !== void 0 ? _a : 3;
+        if ((options === null || options === void 0 ? void 0 : options.maxProxyCalls) !== undefined) {
+            body.max_proxy_calls = options.maxProxyCalls;
+        }
+        const res = await this.fetchWithRetry(`${this.vaultUrl}/internal/wax-session`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.vaultKey,
+            },
+            body: JSON.stringify(body),
+        });
+        const json = await res.json().catch(() => ({}));
+        if (res.status === 201) {
+            const data = json.data;
+            const waxKey = String((_b = data === null || data === void 0 ? void 0 : data.wax_key) !== null && _b !== void 0 ? _b : '');
+            if (!waxKey) {
+                throw new OzuraError('Vault mint response missing data.wax_key', res.status, JSON.stringify(json));
+            }
+            return {
+                waxKey,
+                expiresInSeconds: Number((_c = data === null || data === void 0 ? void 0 : data.expires_in_seconds) !== null && _c !== void 0 ? _c : 1800),
+            };
+        }
+        const errorCode = json.error_code || '';
+        const message = json.message || json.error || `Wax mint failed (HTTP ${res.status})`;
+        throw new OzuraError(errorCode ? `${message} [${errorCode}]` : message, res.status, errorCode || JSON.stringify(json));
+    }
+    /**
+     * Revoke a previously minted wax 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.
+     *
+     * - 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.
+     *
+     * @example
+     * // After a successful card sale:
+     * await ozura.revokeWaxKey(waxKey);
+     */
+    async revokeWaxKey(waxKey) {
+        var _a, _b;
+        if (!waxKey)
+            return;
+        try {
+            const res = await fetch(`${this.vaultUrl}/internal/wax-session/revoke`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.vaultKey,
+                },
+                body: JSON.stringify({ wax_key: waxKey }),
+                signal: timeoutSignal(3000),
+            });
+            if (res.status === 200 || res.status === 404)
+                return;
+            const json = await res.json().catch(() => ({}));
+            console.warn('[Ozura] revokeWaxKey: unexpected status', res.status, (_b = (_a = json.error_code) !== null && _a !== void 0 ? _a : json.message) !== null && _b !== void 0 ? _b : '');
+        }
+        catch (err) {
+            console.warn('[Ozura] revokeWaxKey: best-effort call failed:', err instanceof Error ? err.message : err);
+        }
+    }
     // ─── HTTP helpers ────────────────────────────────────────────────────────
     /**
      * Execute a fetch with retry on 5xx / network errors.
      * 4xx errors (including 429) are never retried — they require caller action.
      */
-    async fetchWithRetry(url, init) {
+    async fetchWithRetry(url, init, maxRetries = this.retries) {
         let lastError;
-        for (let attempt = 0; attempt <= this.retries; attempt++) {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                const res = await fetch(url, Object.assign(Object.assign({}, init), { signal: AbortSignal.timeout(this.timeoutMs) }));
-                if (isRetryable(res.status) && attempt < this.retries) {
+                const res = await fetch(url, Object.assign(Object.assign({}, init), { signal: timeoutSignal(this.timeoutMs) }));
+                if (isRetryable(res.status) && attempt < maxRetries) {
                     // Consume/cancel body so the connection is released (undici holds socket until body is drained)
                     if (res.body) {
                         try {
@@ -160,7 +545,7 @@ class Ozura {
             }
             catch (err) {
                 lastError = err;
-                if (attempt < this.retries) {
+                if (attempt < maxRetries) {
                     const backoff = Math.min(1000 * 2 ** attempt, 8000);
                     await sleep(backoff);
                     continue;
@@ -176,7 +561,14 @@ class Ozura {
         }
         throw new OzuraError('Network error', 0);
     }
-    async post(path, body, includeVaultKey) {
+    async post(path, body, includeVaultKey, maxRetries) {
+        // Enforce: the server SDK sends x-api-key on every request, so it must
+        // never be used to call the vault tokenize endpoint. Tokenization is
+        // client-side only (OzVault + tokenizerFrame). Surface misuse immediately.
+        if (/\/tokenize\b/i.test(path)) {
+            throw new OzuraError('The server SDK must not call the vault tokenize endpoint. ' +
+                'Tokenization must be performed client-side via the OzVault SDK.', 0);
+        }
         const headers = {
             'Content-Type': 'application/json',
             'x-api-key': this.apiKey,
@@ -188,41 +580,151 @@ class Ozura {
             method: 'POST',
             headers,
             body: JSON.stringify(body),
-        });
+        }, maxRetries);
         return this.handleResponse(res);
     }
     async getRaw(path) {
+        // Enforce: same rule as post() — x-api-key must never reach /tokenize.
+        if (/\/tokenize\b/i.test(path)) {
+            throw new OzuraError('The server SDK must not call the vault tokenize endpoint. ' +
+                'Tokenization must be performed client-side via the OzVault SDK.', 0);
+        }
         const res = await this.fetchWithRetry(`${this.apiUrl}${path}`, {
             method: 'GET',
             headers: { 'x-api-key': this.apiKey },
         });
-        const json = await res.json().catch(() => ({ error: res.statusText }));
-        if (!res.ok) {
-            const retryAfter = res.status === 429
-                ? Number(res.headers.get('retry-after') || json.retryAfter) || undefined
-                : undefined;
-            throw new OzuraError(json.error || `HTTP ${res.status}`, res.status, json.error, retryAfter);
-        }
-        if (json.success === false) {
-            throw new OzuraError(json.error || 'Request was not successful', res.status, json.error);
-        }
-        return json;
+        return (await this.parseApiJson(res));
     }
     async handleResponse(res) {
         var _a;
+        const json = await this.parseApiJson(res);
+        return ((_a = json.data) !== null && _a !== void 0 ? _a : json);
+    }
+    /**
+     * Parses a Pay API response JSON and throws `OzuraError` on HTTP errors or
+     * `success: false` payloads. Used by both `getRaw` and `handleResponse` to
+     * avoid duplicating the error-mapping logic.
+     */
+    async parseApiJson(res) {
         const json = await res.json().catch(() => ({ error: res.statusText }));
         if (!res.ok) {
             const retryAfter = res.status === 429
                 ? Number(res.headers.get('retry-after') || json.retryAfter) || undefined
                 : undefined;
-            throw new OzuraError(json.error || `HTTP ${res.status}`, res.status, json.error, retryAfter);
+            throw new OzuraError(json.error || `HTTP ${res.status}`, res.status, typeof json.error === 'string' ? json.error : undefined, retryAfter);
         }
         if (json.success === false) {
-            throw new OzuraError(json.error || 'Request was not successful', res.status, json.error);
+            throw new OzuraError(json.error || 'Request was not successful', res.status, typeof json.error === 'string' ? json.error : undefined);
         }
-        return ((_a = json.data) !== null && _a !== void 0 ? _a : json);
+        return json;
     }
 }
+/**
+ * Creates a ready-to-use Fetch API route handler for minting wax keys.
+ *
+ * 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 }`.
+ * 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';
+ *
+ * const ozura = new Ozura({
+ *   merchantId: process.env.MERCHANT_ID!,
+ *   apiKey:     process.env.MERCHANT_API_KEY!,
+ *   vaultKey:   process.env.VAULT_API_KEY!,
+ * });
+ *
+ * export const POST = createMintWaxHandler(ozura);
+ */
+function createMintWaxHandler(ozura) {
+    return async (req) => {
+        var _a, _b;
+        if (req.method !== 'POST') {
+            return Response.json({ error: 'Method Not Allowed' }, { status: 405 });
+        }
+        // Reject non-JSON bodies — blocks simple-form CSRF requests which send
+        // application/x-www-form-urlencoded and cannot set Content-Type to
+        // application/json without triggering a CORS preflight.
+        const contentType = (_a = req.headers.get('content-type')) !== null && _a !== void 0 ? _a : '';
+        if (!contentType.includes('application/json')) {
+            return Response.json({ error: 'Content-Type must be application/json' }, { status: 415 });
+        }
+        let sessionId;
+        const body = await req.json().catch(() => ({}));
+        const raw = (_b = body.sessionId) !== null && _b !== void 0 ? _b : body.tokenizationSessionId;
+        if (typeof raw === 'string' && raw)
+            sessionId = raw;
+        try {
+            const { waxKey } = await ozura.mintWaxKey({ tokenizationSessionId: sessionId });
+            return Response.json({ waxKey });
+        }
+        catch (err) {
+            const status = err instanceof OzuraError && err.statusCode >= 400 ? err.statusCode : 502;
+            const message = err instanceof Error ? err.message : 'Failed to mint wax key';
+            return Response.json({ error: message }, { status });
+        }
+    };
+}
+/**
+ * Creates a ready-to-use Express / Connect middleware for minting wax keys.
+ *
+ * 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 }`.
+ * On error it sends `{ error }` with an appropriate HTTP status.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createMintWaxMiddleware } 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 app = express();
+ * app.use(express.json());
+ * app.post('/api/mint-wax', createMintWaxMiddleware(ozura));
+ */
+function createMintWaxMiddleware(ozura) {
+    return async (req, res) => {
+        var _a, _b, _c;
+        const method = req.method;
+        if (method && method !== 'POST') {
+            res.status(405).json({ error: 'Method Not Allowed' });
+            return;
+        }
+        // Reject non-JSON content types — blocks simple-form CSRF requests.
+        // Express sets req.headers as a plain object; check it directly.
+        const headers = req.headers;
+        const ct = (_a = (typeof (headers === null || headers === void 0 ? void 0 : headers['content-type']) === 'string' ? headers['content-type'] : '')) !== null && _a !== void 0 ? _a : '';
+        if (!ct.includes('application/json')) {
+            res.status(415).json({ error: 'Content-Type must be application/json' });
+            return;
+        }
+        const body = ((_b = req.body) !== null && _b !== void 0 ? _b : {});
+        const raw = (_c = body.sessionId) !== null && _c !== void 0 ? _c : body.tokenizationSessionId;
+        const sessionId = typeof raw === 'string' && raw ? raw : undefined;
+        try {
+            const { waxKey } = await ozura.mintWaxKey({ tokenizationSessionId: sessionId });
+            res.json({ waxKey });
+        }
+        catch (err) {
+            const status = err instanceof OzuraError && err.statusCode >= 400 ? err.statusCode : 502;
+            const message = err instanceof Error ? err.message : 'Failed to mint wax key';
+            res.status(status).json({ error: message });
+        }
+    };
+}
 // ─── Utilities ────────────────────────────────────────────────────────────────
 /**
  * Extract the client IP address from a server request object.
@@ -233,8 +735,27 @@ class Ozura {
  * (Cloudflare) → `x-forwarded-for` (reverse proxy) → `x-real-ip` →
  * `socket.remoteAddress` → `"0.0.0.0"`.
  *
+ * **Proxy trust requirements — read before deploying:**
+ *
+ * - **`x-forwarded-for` / `x-real-ip`** are HTTP headers that any client can
+ *   set arbitrarily. They are only trustworthy when your server sits behind a
+ *   reverse proxy (nginx, AWS ALB, Cloudflare, etc.) that strips and rewrites
+ *   those headers. If your Node.js process is directly internet-accessible,
+ *   an attacker can spoof any IP value and bypass payment-processor
+ *   IP-based fraud checks.
+ * - **Express `req.ip`** resolves through `X-Forwarded-For` only when
+ *   `app.set('trust proxy', true)` (or a specific proxy count/subnet) is
+ *   configured. Without `trust proxy`, `req.ip` returns the direct socket
+ *   address (your load-balancer's IP, not the client's).
+ * - **`cf-connecting-ip`** is only trustworthy when Cloudflare is genuinely
+ *   in front of your server. Without Cloudflare, any client can send this
+ *   header with a fabricated value.
+ *
+ * In all cases, ensure your infrastructure strips untrusted forwarding headers
+ * before they reach your application.
+ *
  * @example
- * // Express / Fastify
+ * // Express — requires app.set('trust proxy', true) behind a proxy
  * clientIpAddress: getClientIp(req)
  *
  * // Next.js App Router
@@ -252,8 +773,11 @@ function getClientIp(req) {
         if (cfIp)
             return cfIp;
         const xff = get('x-forwarded-for');
-        if (xff)
-            return xff.split(',')[0].trim();
+        if (xff) {
+            const candidate = xff.split(',')[0].trim();
+            if (candidate)
+                return candidate;
+        }
         const realIp = get('x-real-ip');
         if (realIp)
             return realIp;
@@ -265,10 +789,16 @@ function getClientIp(req) {
         if (typeof cfIp === 'string' && cfIp)
             return cfIp;
         const xff = h['x-forwarded-for'];
-        if (typeof xff === 'string' && xff)
-            return xff.split(',')[0].trim();
-        if (Array.isArray(xff) && xff[0])
-            return xff[0].split(',')[0].trim();
+        if (typeof xff === 'string' && xff) {
+            const candidate = xff.split(',')[0].trim();
+            if (candidate)
+                return candidate;
+        }
+        if (Array.isArray(xff) && xff[0]) {
+            const candidate = xff[0].split(',')[0].trim();
+            if (candidate)
+                return candidate;
+        }
         const realIp = h['x-real-ip'];
         if (typeof realIp === 'string' && realIp)
             return realIp;
@@ -279,8 +809,209 @@ function getClientIp(req) {
         return socket.remoteAddress;
     return '0.0.0.0';
 }
+/**
+ * Validates the token/cvcSession/billing fields from a parsed request body.
+ * Returns the normalized billing or a 400 error descriptor.
+ */
+function parseCardSaleBody(body) {
+    const { token, cvcSession, billing } = body;
+    if (typeof token !== 'string' || !token) {
+        return { ok: false, error: 'token is required' };
+    }
+    if (typeof cvcSession !== 'string' || !cvcSession) {
+        return { ok: false, error: 'cvcSession is required' };
+    }
+    if (!billing || typeof billing.firstName !== 'string' || typeof billing.lastName !== 'string') {
+        return { ok: false, error: 'billing with firstName and lastName is required' };
+    }
+    const billingValidation = validateBilling(billing);
+    if (!billingValidation.valid) {
+        return { ok: false, error: `Invalid billing details: ${billingValidation.errors.join('; ')}` };
+    }
+    return { ok: true, token, cvcSession, billing: billingValidation.normalized };
+}
+/**
+ * Runs the card sale after body validation: resolves amount + currency,
+ * calls ozura.cardSale(), and returns a typed outcome. Both handler and
+ * middleware factories delegate to this shared implementation.
+ */
+async function executeCardSale(ozura, options, token, cvcSession, billing, rawBody, clientIpAddress) {
+    let amount;
+    try {
+        amount = await options.getAmount(rawBody);
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'Failed to resolve amount', status: 500 };
+    }
+    if (typeof amount !== 'string' || !amount.trim()) {
+        return { ok: false, error: 'getAmount must return a non-empty decimal string', status: 500 };
+    }
+    if (!/^\d+(\.\d{1,2})?$/.test(amount.trim())) {
+        return {
+            ok: false,
+            error: `getAmount returned an invalid amount: "${amount}". Expected a positive decimal string, e.g. "49.00".`,
+            status: 500,
+        };
+    }
+    amount = amount.trim();
+    let currency = 'USD';
+    if (options.getCurrency) {
+        try {
+            currency = await options.getCurrency(rawBody);
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : 'Failed to resolve currency', status: 500 };
+        }
+    }
+    try {
+        const result = await ozura.cardSale({ token, cvcSession, amount, currency, billing, clientIpAddress });
+        return {
+            ok: true,
+            data: {
+                transactionId: result.transactionId,
+                amount: result.amount,
+                cardLastFour: result.cardLastFour,
+                cardBrand: result.cardBrand,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof OzuraError) {
+            if (err.statusCode === 429) {
+                return { ok: false, error: normalizeCardSaleError(err.message), status: 429, retryAfter: err.retryAfter };
+            }
+            const status = err.statusCode >= 400 && err.statusCode < 600 ? err.statusCode : 502;
+            return { ok: false, error: normalizeCardSaleError(err.message), status };
+        }
+        return { ok: false, error: 'Payment failed', status: 500 };
+    }
+}
+// ─── Public factories ─────────────────────────────────────────────────────────
+/**
+ * Creates a ready-to-use Fetch API route handler for charging a tokenized card.
+ *
+ * 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 `{ token, cvcSession, billing }` from the JSON request body,
+ * resolves the amount via `options.getAmount()`, calls `ozura.cardSale()`, and
+ * returns `{ transactionId, amount, cardLastFour, cardBrand }` on success.
+ * On error it returns `{ error }` with a normalized, user-facing message and
+ * an appropriate HTTP status.
+ *
+ * `clientIpAddress` is extracted automatically from the request headers.
+ *
+ * @example
+ * // app/api/charge/route.ts  (Next.js App Router)
+ * import { Ozura, createCardSaleHandler } from '@ozura/elements/server';
+ *
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * export const POST = createCardSaleHandler(ozura, {
+ *   getAmount: async (body) => {
+ *     const order = await db.orders.findById(body.orderId as string);
+ *     return order.total;
+ *   },
+ * });
+ */
+function createCardSaleHandler(ozura, options) {
+    return async (req) => {
+        var _a;
+        if (req.method !== 'POST') {
+            return Response.json({ error: 'Method Not Allowed' }, { status: 405 });
+        }
+        const contentType = (_a = req.headers.get('content-type')) !== null && _a !== void 0 ? _a : '';
+        if (!contentType.includes('application/json')) {
+            return Response.json({ error: 'Content-Type must be application/json' }, { status: 415 });
+        }
+        let body;
+        try {
+            body = await req.json();
+        }
+        catch (_b) {
+            return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+        }
+        const parsed = parseCardSaleBody(body);
+        if (!parsed.ok) {
+            return Response.json({ error: parsed.error }, { status: 400 });
+        }
+        const outcome = await executeCardSale(ozura, options, parsed.token, parsed.cvcSession, parsed.billing, body, getClientIp(req));
+        if (!outcome.ok) {
+            const headers = outcome.retryAfter
+                ? { 'Retry-After': String(outcome.retryAfter) }
+                : {};
+            return Response.json({ error: outcome.error }, Object.assign({ status: outcome.status }, (Object.keys(headers).length > 0 ? { headers } : {})));
+        }
+        return Response.json(outcome.data);
+    };
+}
+/**
+ * Creates a ready-to-use Express / Connect middleware for charging a tokenized card.
+ *
+ * Requires `express.json()` (or equivalent body-parser) to be registered before
+ * this middleware so `req.body` is available.
+ *
+ * The middleware reads `{ token, cvcSession, billing }` from `req.body`, resolves
+ * the amount via `options.getAmount()`, calls `ozura.cardSale()`, and sends
+ * `{ transactionId, amount, cardLastFour, cardBrand }` on success.
+ * On error it sends `{ error }` with a normalized, user-facing message and an
+ * appropriate HTTP status.
+ *
+ * `clientIpAddress` is extracted automatically from the request object.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createCardSaleMiddleware } from '@ozura/elements/server';
+ *
+ * const app = express();
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * app.use(express.json());
+ * app.post('/api/charge', createCardSaleMiddleware(ozura, {
+ *   getAmount: async (body) => {
+ *     const order = await db.orders.findById(body.orderId as string);
+ *     return order.total;
+ *   },
+ * }));
+ */
+function createCardSaleMiddleware(ozura, options) {
+    return async (req, res) => {
+        var _a, _b, _c;
+        const method = req.method;
+        if (method && method !== 'POST') {
+            res.status(405).json({ error: 'Method Not Allowed' });
+            return;
+        }
+        const headers = req.headers;
+        const ct = (_a = (typeof (headers === null || headers === void 0 ? void 0 : headers['content-type']) === 'string' ? headers['content-type'] : '')) !== null && _a !== void 0 ? _a : '';
+        if (!ct.includes('application/json')) {
+            res.status(415).json({ error: 'Content-Type must be application/json' });
+            return;
+        }
+        const body = ((_b = req.body) !== null && _b !== void 0 ? _b : {});
+        const parsed = parseCardSaleBody(body);
+        if (!parsed.ok) {
+            res.status(400).json({ error: parsed.error });
+            return;
+        }
+        const outcome = await executeCardSale(ozura, options, parsed.token, parsed.cvcSession, parsed.billing, body, getClientIp(req));
+        if (!outcome.ok) {
+            if (outcome.retryAfter)
+                (_c = res.setHeader) === null || _c === void 0 ? void 0 : _c.call(res, 'Retry-After', String(outcome.retryAfter));
+            res.status(outcome.status).json({ error: outcome.error });
+            return;
+        }
+        res.json(outcome.data);
+    };
+}
 
 exports.Ozura = Ozura;
 exports.OzuraError = OzuraError;
+exports.createCardSaleHandler = createCardSaleHandler;
+exports.createCardSaleMiddleware = createCardSaleMiddleware;
+exports.createMintWaxHandler = createMintWaxHandler;
+exports.createMintWaxMiddleware = createMintWaxMiddleware;
 exports.getClientIp = getClientIp;
+exports.normalizeCardSaleError = normalizeCardSaleError;
 //# sourceMappingURL=index.cjs.js.map