@funnelfox/billing 0.6.4-beta.0 → 0.6.4-beta.1

package/README.md

@@ -94,17 +94,24 @@ const checkout = await createCheckout({
   priceId: 'price_123',
   customer: {
     externalId: 'user_456',
-    email: 'user@example.com',
+    email: 'user@example.com', // Optional if you collect it in the card form
     countryCode: 'US', // Optional
   },
   container: '#checkout-container',
   clientMetadata: { source: 'web' },
+  card: {
+    emailAddress: {
+      visible: true,
+      template: '{{email}}',
+    },
+  },
   cardSelectors: {
     // Custom card input selectors (optional, defaults to auto-generated)
     cardNumber: '#cardNumberInput',
     expiryDate: '#expiryInput',
     cvv: '#cvvInput',
     cardholderName: '#cardHolderInput',
+    emailAddress: '#emailAddressInput',
     button: '#submitButton',
   },
   paypalButtonContainer: '#paypalButton', // Optional
@@ -130,9 +137,11 @@ const checkout = await createCheckout({
 - `options.priceId` (string, required) - Price identifier
 - `options.customer` (object, required)
   - `customer.externalId` (string, required) - Your user identifier
-  - `customer.email` (string, required) - Customer email
+  - `customer.email` (string, optional) - Customer email
   - `customer.countryCode` (string, optional) - ISO country code
 - `options.container` (string, required) - CSS selector for checkout container
+- `options.card.emailAddress.visible` (boolean, optional) - Shows an email field in the card form. Disabled by default.
+- `options.card.emailAddress.template` (string, optional) - Wraps the entered email before it is sent with payment, for example `{{email}}`.
 
 **Container Styling Requirements (Default Skin):**
 
@@ -176,7 +185,7 @@ import { createClientSession } from '@funnelfox/billing';
 const session = await createClientSession({
   priceId: 'price_123',
   externalId: 'user_456',
-  email: 'user@example.com',
+  email: 'user@example.com', // Optional
   orgId: 'your-org-id', // Optional if configured
 });
 
@@ -528,6 +537,7 @@ const checkout = await createCheckout({
     expiryDate: '#my-expiry',
     cvv: '#my-cvv',
     cardholderName: '#my-cardholder',
+    emailAddress: '#my-email',
     button: '#my-submit-button',
   },
 
@@ -657,7 +667,7 @@ await paymentMethod.destroy();
   - `orgId` (string, required) - Your organization identifier
   - `priceId` (string, required) - Price identifier
   - `externalId` (string, required) - Your user identifier
-  - `email` (string, required) - Customer email
+  - `email` (string, optional) - Customer email
   - `baseUrl` (string, optional) - Custom API URL
   - `meta` (object, optional) - Custom metadata
   - `style`, `card`, `applePay`, `paypal`, `googlePay` (optional) - Primer SDK configuration options

package/dist/chunk-index.cjs.js

@@ -150,64 +150,46 @@ class NetworkError extends FunnefoxSDKError {
 }
 
 /**
- * @fileoverview Generic script and stylesheet loader utility to reduce bundle size
+ * @fileoverview Dynamic loader for Primer SDK
+ * Loads Primer script and CSS from CDN independently of bundler
  */
+const PRIMER_CDN_BASE = 'https://sdk.primer.io/web';
+const DEFAULT_VERSION = '2.57.3';
+// Integrity hashes for specific versions (for SRI security)
+const INTEGRITY_HASHES = {
+    '2.57.3': {
+        js: 'sha384-xq2SWkYvTlKOMpuXQUXq1QI3eZN7JiqQ3Sc72U9wY1IE30MW3HkwQWg/1n6BTMz4',
+    },
+};
+let loadingPromise = null;
+let isLoaded = false;
 /**
- * Dynamically loads an external script into the document.
- * Checks if script already exists before loading to prevent duplicates.
- *
- * @param options - Script configuration options
- * @returns Promise that resolves when script is loaded or rejects on error
+ * Injects a script tag into the document head
  */
-function loadScript$1(options) {
-    const { id, src, async = true, type = 'text/javascript', attributes = {}, integrity, crossOrigin, appendTo = 'body', } = options;
+function injectScript$1(src, integrity) {
     return new Promise((resolve, reject) => {
-        // Check if script already exists (by ID or src)
-        let existingScript = null;
-        if (id) {
-            existingScript = document.getElementById(id);
-        }
-        if (!existingScript) {
-            existingScript = document.querySelector(`script[src="${src}"]`);
-        }
+        // Check if script already exists
+        const existingScript = document.querySelector(`script[src="${src}"]`);
         if (existingScript) {
             resolve(existingScript);
             return;
         }
         const script = document.createElement('script');
-        if (id) {
-            script.id = id;
-        }
-        script.type = type;
         script.src = src;
-        if (async) {
-            script.async = true;
-        }
+        script.async = true;
+        script.crossOrigin = 'anonymous';
         if (integrity) {
             script.integrity = integrity;
         }
-        if (crossOrigin) {
-            script.crossOrigin = crossOrigin;
-        }
-        // Set additional attributes
-        Object.entries(attributes).forEach(([key, value]) => {
-            script.setAttribute(key, value);
-        });
         script.onload = () => resolve(script);
-        script.onerror = () => reject(new Error(`Failed to load script: ${src}`));
-        const target = appendTo === 'head' ? document.head : document.body;
-        target.appendChild(script);
+        script.onerror = () => reject(new Error(`Failed to load Primer SDK script from ${src}`));
+        document.head.appendChild(script);
     });
 }
 /**
- * Dynamically loads an external stylesheet into the document head.
- * Checks if stylesheet already exists before loading to prevent duplicates.
- *
- * @param options - Stylesheet configuration options
- * @returns Promise that resolves when stylesheet is loaded or rejects on error
+ * Injects a CSS link tag into the document head
  */
-function loadStylesheet(options) {
-    const { href, integrity, crossOrigin } = options;
+function injectCSS(href, integrity) {
     return new Promise((resolve, reject) => {
         // Check if stylesheet already exists
         const existingLink = document.querySelector(`link[href="${href}"]`);
@@ -218,32 +200,15 @@ function loadStylesheet(options) {
         const link = document.createElement('link');
         link.rel = 'stylesheet';
         link.href = href;
+        link.crossOrigin = 'anonymous';
         if (integrity) {
             link.integrity = integrity;
         }
-        if (crossOrigin) {
-            link.crossOrigin = crossOrigin;
-        }
         link.onload = () => resolve(link);
-        link.onerror = () => reject(new Error(`Failed to load stylesheet: ${href}`));
+        link.onerror = () => reject(new Error(`Failed to load Primer SDK CSS from ${href}`));
         document.head.appendChild(link);
     });
 }
-
-/**
- * @fileoverview Dynamic loader for Primer SDK
- * Loads Primer script and CSS from CDN independently of bundler
- */
-const PRIMER_CDN_BASE = 'https://sdk.primer.io/web';
-const DEFAULT_VERSION = '2.57.3';
-// Integrity hashes for specific versions (for SRI security)
-const INTEGRITY_HASHES = {
-    '2.57.3': {
-        js: 'sha384-xq2SWkYvTlKOMpuXQUXq1QI3eZN7JiqQ3Sc72U9wY1IE30MW3HkwQWg/1n6BTMz4',
-    },
-};
-let loadingPromise = null;
-let isLoaded = false;
 /**
  * Waits for window.Primer to be available
  */
@@ -295,17 +260,8 @@ async function loadPrimerSDK(version) {
         try {
             // Load CSS and JS in parallel
             await Promise.all([
-                loadStylesheet({
-                    href: cssUrl,
-                    integrity: hashes?.css,
-                    crossOrigin: 'anonymous',
-                }),
-                loadScript$1({
-                    src: jsUrl,
-                    integrity: hashes?.js,
-                    crossOrigin: 'anonymous',
-                    appendTo: 'head',
-                }),
+                injectCSS(cssUrl, hashes?.css),
+                injectScript$1(jsUrl, hashes?.js),
             ]);
             // Wait for Primer to be available on window
             await waitForPrimer();
@@ -348,28 +304,6 @@ function generateId(prefix = '') {
     const random = Math.random().toString(36).substr(2, 5);
     return `${prefix}${timestamp}_${random}`;
 }
-/**
- * Generates a UUID v4 compliant string (RFC 4122).
- * Meets Airwallex requirements:
- * - Maximum 128 characters (UUID is 36 chars)
- * - Only contains: a-z, A-Z, 0-9, underscore, hyphen
- * - No prefix + timestamp pattern
- * - Not a short series of numbers
- *
- * @returns UUID v4 string (e.g., "a3bb189e-8bf9-3888-9912-ace4e6543002")
- */
-function generateUUID() {
-    // Use crypto.randomUUID if available (modern browsers)
-    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-        return crypto.randomUUID();
-    }
-    // Fallback: manual UUID v4 generation
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -488,7 +422,7 @@ exports.PaymentMethod = void 0;
 /**
  * @fileoverview Constants for Funnefox SDK
  */
-const SDK_VERSION = '0.6.4-beta.0';
+const SDK_VERSION = '0.6.4-beta.1';
 const DEFAULTS = {
     BASE_URL: 'https://billing.funnelfox.com',
     REGION: 'default',
@@ -602,6 +536,26 @@ const APPLE_PAY_COLLECTING_EMAIL_OPTIONS = {
     },
 };
 
+/**
+ * @fileoverview Input validation utilities for Funnefox SDK
+ */
+function isValidEmail(email) {
+    if (typeof email !== 'string')
+        return false;
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+}
+function sanitizeString(input) {
+    return input?.trim() || '';
+}
+function requireString(value, fieldName) {
+    const sanitized = sanitizeString(value);
+    if (sanitized.length === 0) {
+        throw new ValidationError(fieldName, 'must be a non-empty string', value);
+    }
+    return true;
+}
+
 /**
  * @fileoverview Primer SDK integration wrapper
  */
@@ -718,6 +672,7 @@ class PrimerWrapper {
                     onInputChange: options.onInputChange,
                     onMethodRenderError: options.onMethodRenderError,
                     onMethodRender: options.onMethodRender,
+                    onCardInputValueChange: options.onCardInputValueChange,
                 });
                 this.paymentMethodsInterfaces.push(cardInterface);
                 return cardInterface;
@@ -736,7 +691,7 @@ class PrimerWrapper {
             throw new PrimerError('Failed to initialize Primer checkout', error);
         }
     }
-    async renderCardCheckoutWithElements(elements, { onSubmit, onInputChange, onMethodRenderError, onMethodRender, }) {
+    async renderCardCheckoutWithElements(elements, { onSubmit, onInputChange, onCardInputValueChange, onMethodRenderError, onMethodRender, }) {
         try {
             if (!this.currentHeadless) {
                 throw new PrimerError('Headless checkout not found');
@@ -753,7 +708,12 @@ class PrimerWrapper {
                 const { valid, validationErrors } = await pmManager.validate();
                 const cardHolderError = validationErrors.find(v => v.name === 'cardholderName');
                 dispatchError('cardholderName', cardHolderError?.message || null);
-                return valid;
+                const emailAddress = elements.emailAddress?.value?.trim();
+                const emailError = emailAddress && !isValidEmail(emailAddress)
+                    ? 'Please enter a valid email address'
+                    : null;
+                dispatchError('emailAddress', emailError);
+                return valid && !emailError;
             };
             const dispatchError = (inputName, error) => {
                 onInputChange(inputName, error);
@@ -768,7 +728,16 @@ class PrimerWrapper {
                 pmManager.setCardholderName(e.target.value);
                 dispatchError('cardholderName', null);
             };
+            const emailAddressOnChange = (e) => {
+                const value = e.target.value;
+                const email = value.trim();
+                onCardInputValueChange?.('emailAddress', email);
+                dispatchError('emailAddress', email && !isValidEmail(email)
+                    ? 'Please enter a valid email address'
+                    : null);
+            };
             elements.cardholderName?.addEventListener('input', cardHolderOnChange);
+            elements.emailAddress?.addEventListener('input', emailAddressOnChange);
             cardNumberInput.addEventListener('change', onHostedInputChange('cardNumber'));
             expiryInput.addEventListener('change', onHostedInputChange('expiryDate'));
             cvvInput.addEventListener('change', onHostedInputChange('cvv'));
@@ -808,7 +777,8 @@ class PrimerWrapper {
             ]);
             const onDestroy = () => {
                 pmManager.removeHostedInputs();
-                elements.cardholderName?.removeEventListener('change', cardHolderOnChange);
+                elements.cardholderName?.removeEventListener('input', cardHolderOnChange);
+                elements.emailAddress?.removeEventListener('input', emailAddressOnChange);
                 elements.button?.removeEventListener('click', onSubmitHandler);
             };
             this.destroyCallbacks.push(onDestroy);
@@ -824,6 +794,9 @@ class PrimerWrapper {
                     if (elements.cardholderName) {
                         elements.cardholderName.disabled = disabled;
                     }
+                    if (elements.emailAddress) {
+                        elements.emailAddress.disabled = disabled;
+                    }
                 },
                 submit: () => onSubmitHandler(),
                 destroy: () => {
@@ -846,7 +819,7 @@ class PrimerWrapper {
         });
     }
     async renderCheckout(clientToken, checkoutOptions, checkoutRenderOptions) {
-        const { cardElements, paymentButtonElements, container, onSubmit, onInputChange, onMethodRender, onMethodRenderError, onMethodsAvailable, } = checkoutRenderOptions;
+        const { cardElements, paymentButtonElements, container, onSubmit, onInputChange, onMethodRender, onMethodRenderError, onMethodsAvailable, onCardInputValueChange, } = checkoutRenderOptions;
         await this.initializeHeadlessCheckout(clientToken, checkoutOptions);
         onMethodsAvailable?.(this.availableMethods);
         await Promise.all(this.availableMethods.map(method => {
@@ -858,6 +831,7 @@ class PrimerWrapper {
                     onInputChange,
                     onMethodRender,
                     onMethodRenderError,
+                    onCardInputValueChange,
                 });
             }
             else {
@@ -974,20 +948,6 @@ class PrimerWrapper {
 }
 PrimerWrapper.headlessManager = new HeadlessManager();
 
-/**
- * @fileoverview Input validation utilities for Funnefox SDK
- */
-function sanitizeString(input) {
-    return input?.trim() || '';
-}
-function requireString(value, fieldName) {
-    const sanitized = sanitizeString(value);
-    if (sanitized.length === 0) {
-        throw new ValidationError(fieldName, 'must be a non-empty string', value);
-    }
-    return true;
-}
-
 /**
  * @fileoverview API client for Funnefox backend integration
  */
@@ -1083,6 +1043,9 @@ class APIClient {
             payment_method_token: params.paymentMethodToken,
             client_metadata: params.clientMetadata || {},
         };
+        if (params.email !== undefined) {
+            payload.email_address = params.email;
+        }
         return (await this.request(API_ENDPOINTS.CREATE_PAYMENT, {
             method: 'POST',
             body: JSON.stringify(payload),
@@ -1387,34 +1350,6 @@ const renderError = (container, reqId) => {
     }
 };
 
-/**
- * @fileoverview Airwallex device fingerprinting script loader
- */
-/**
- * Loads Airwallex device fingerprinting script for fraud prevention.
- * The script collects browser, screen, device, and interaction data.
- *
- * @param sessionId - Unique order session ID (UUID v4 format, max 128 chars)
- * @param isDemoMode - If true, uses demo environment URL for testing
- * @returns Promise that resolves when script is loaded
- *
- * @see https://www.airwallex.com/docs/payments/online-payments/native-api/device-fingerprinting
- */
-async function loadAirwallexDeviceFingerprint(sessionId, isDemoMode = false) {
-    const scriptId = 'airwallex-fraud-api';
-    const src = isDemoMode
-        ? 'https://static-demo.airwallex.com/webapp/fraud/device-fingerprint/index.js'
-        : 'https://static.airwallex.com/webapp/fraud/device-fingerprint/index.js';
-    await loadScript$1({
-        id: scriptId,
-        src,
-        async: true,
-        attributes: {
-            'data-order-session-id': sessionId,
-        },
-    });
-}
-
 /**
  * @fileoverview Checkout instance manager for Funnefox SDK
  */
@@ -1423,10 +1358,14 @@ class CheckoutInstance extends EventEmitter {
         super();
         this.counter = 0;
         this.radarSessionId = null;
-        this.airwallexDeviceId = null;
         this.handleInputChange = (inputName, error) => {
             this.emit(EVENTS.INPUT_ERROR, { name: inputName, error });
         };
+        this.handleCardInputValueChange = (inputName, value) => {
+            if (inputName === 'emailAddress') {
+                this.cardEmailAddress = value?.trim() || undefined;
+            }
+        };
         this.handleMethodRender = (method) => {
             this.emit(EVENTS.METHOD_RENDER, method);
         };
@@ -1445,16 +1384,13 @@ class CheckoutInstance extends EventEmitter {
             try {
                 this.onLoaderChangeWithRace(true);
                 this._setState('processing');
-                const [radarSessionId, airwallexDeviceId] = await Promise.all([
-                    this.radarSessionId,
-                    this.airwallexDeviceId,
-                ]);
+                const radarSessionId = await this.radarSessionId;
                 const paymentResponse = await this.apiClient.createPayment({
                     orderId: this.orderId,
                     paymentMethodToken: paymentMethodTokenData.token,
+                    email: this.getPaymentEmailAddress(),
                     clientMetadata: {
                         radarSessionId,
-                        airwallexDeviceId,
                     },
                 });
                 const result = this.apiClient.processPaymentResponse(paymentResponse);
@@ -1524,6 +1460,7 @@ class CheckoutInstance extends EventEmitter {
         this.clientToken = null;
         this.primerWrapper = new PrimerWrapper();
         this.isDestroyed = false;
+        this.cardEmailAddress = this.checkoutConfig.customer.email;
         this._setupCallbackBridges();
     }
     _setupCallbackBridges() {
@@ -1602,16 +1539,6 @@ class CheckoutInstance extends EventEmitter {
                             .catch(() => '');
                     });
                 }
-                // Initialize Airwallex device fingerprinting if enabled by backend
-                if (response.data?.airwallex_risk_enabled) {
-                    const deviceId = generateUUID();
-                    this.airwallexDeviceId = loadAirwallexDeviceFingerprint(deviceId, true)
-                        .then(() => deviceId)
-                        .catch(() => {
-                        // Silently fail - return deviceId anyway
-                        return deviceId;
-                    });
-                }
                 this.isCollectingApplePayEmail =
                     !!response.data?.collect_apple_pay_email;
                 return response;
@@ -1624,11 +1551,61 @@ class CheckoutInstance extends EventEmitter {
         this.orderId = sessionData.orderId;
         this.clientToken = sessionData.clientToken;
     }
+    getPrimerCardConfig() {
+        const cardConfig = { ...(this.checkoutConfig.card || {}) };
+        delete cardConfig.emailAddress;
+        return Object.keys(cardConfig).length
+            ? cardConfig
+            : undefined;
+    }
+    getPaymentEmailAddress() {
+        const email = this.cardEmailAddress?.trim() || this.checkoutConfig.customer.email;
+        if (!email || !isValidEmail(email)) {
+            return undefined;
+        }
+        const template = this.checkoutConfig.card?.emailAddress?.template;
+        if (template?.includes('{{email}}')) {
+            return template.replace(/\{\{email\}\}/g, email);
+        }
+        return email;
+    }
+    mergeApplePayCollectingEmailOptions(checkoutOptions) {
+        if (!this.isCollectingApplePayEmail) {
+            return checkoutOptions;
+        }
+        const billingFields = Array.from(new Set([
+            ...(checkoutOptions.applePay?.billingOptions
+                ?.requiredBillingContactFields || []),
+            ...(APPLE_PAY_COLLECTING_EMAIL_OPTIONS.billingOptions
+                ?.requiredBillingContactFields || []),
+        ]));
+        const shippingFields = Array.from(new Set([
+            ...(checkoutOptions.applePay?.shippingOptions
+                ?.requiredShippingContactFields || []),
+            ...(APPLE_PAY_COLLECTING_EMAIL_OPTIONS.shippingOptions
+                ?.requiredShippingContactFields || []),
+        ]));
+        return merge(checkoutOptions, {
+            applePay: {
+                billingOptions: {
+                    requiredBillingContactFields: billingFields,
+                },
+                shippingOptions: {
+                    requiredShippingContactFields: shippingFields,
+                },
+            },
+        });
+    }
     convertCardSelectorsToElements(selectors, container) {
         const cardNumber = container.querySelector(selectors.cardNumber);
         const expiryDate = container.querySelector(selectors.expiryDate);
         const cvv = container.querySelector(selectors.cvv);
-        const cardholderName = container.querySelector(selectors.cardholderName);
+        const cardholderName = selectors.cardholderName
+            ? container.querySelector(selectors.cardholderName)
+            : undefined;
+        const emailAddress = selectors.emailAddress
+            ? container.querySelector(selectors.emailAddress)
+            : undefined;
         const button = container.querySelector(selectors.button);
         if (!cardNumber || !expiryDate || !cvv || !button) {
             throw new CheckoutError('Required card input elements not found in container');
@@ -1638,6 +1615,7 @@ class CheckoutInstance extends EventEmitter {
             expiryDate,
             cvv,
             cardholderName,
+            emailAddress,
             button,
         };
     }
@@ -1687,15 +1665,14 @@ class CheckoutInstance extends EventEmitter {
             paymentButtonElements = this.convertPaymentButtonSelectorsToElements(this.checkoutConfig.paymentButtonSelectors);
             checkoutOptions = this.getCheckoutOptions({});
         }
-        checkoutOptions = merge(checkoutOptions, this.isCollectingApplePayEmail
-            ? { applePay: APPLE_PAY_COLLECTING_EMAIL_OPTIONS }
-            : {});
+        checkoutOptions = this.mergeApplePayCollectingEmailOptions(checkoutOptions);
         await this.primerWrapper.renderCheckout(this.clientToken, checkoutOptions, {
             container: containerElement,
             cardElements,
             paymentButtonElements,
             onSubmit: this.handleSubmit,
             onInputChange: this.handleInputChange,
+            onCardInputValueChange: this.handleCardInputValueChange,
             onMethodRender: this.handleMethodRender,
             onMethodsAvailable: this.handleMethodsAvailable,
             onMethodRenderError: this.handleMethodRenderError,
@@ -1731,9 +1708,13 @@ class CheckoutInstance extends EventEmitter {
     }
     getCheckoutOptions(options) {
         let wasPaymentProcessedStarted = false;
+        const checkoutConfig = { ...this.checkoutConfig };
+        delete checkoutConfig.card;
         return {
-            ...this.checkoutConfig,
+            ...checkoutConfig,
             ...options,
+            card: merge(this.getPrimerCardConfig() || {}, options.card || {}),
+            applePay: merge(this.checkoutConfig.applePay || {}, options.applePay || {}),
             onTokenizeSuccess: this.handleTokenizeSuccess,
             onResumeSuccess: this.handleResumeSuccess,
             onResumeError: error => {
@@ -1917,9 +1898,7 @@ class CheckoutInstance extends EventEmitter {
         if (callbacks.onMethodsAvailable) {
             this.on(EVENTS.METHODS_AVAILABLE, callbacks.onMethodsAvailable);
         }
-        let checkoutOptions = this.getCheckoutOptions(this.isCollectingApplePayEmail
-            ? { applePay: APPLE_PAY_COLLECTING_EMAIL_OPTIONS }
-            : {});
+        let checkoutOptions = this.mergeApplePayCollectingEmailOptions(this.getCheckoutOptions({}));
         let methodOptions = {
             onMethodRender: this.handleMethodRender,
             onMethodRenderError: this.handleMethodRenderError,
@@ -1933,6 +1912,7 @@ class CheckoutInstance extends EventEmitter {
                 cardElements: cardDefaultOptions.cardElements,
                 onSubmit: this.handleSubmit,
                 onInputChange: this.handleInputChange,
+                onCardInputValueChange: this.handleCardInputValueChange,
                 onMethodRender: this.handleMethodRender,
                 onMethodRenderError: this.handleMethodRenderError,
             };