@funnelfox/billing 0.1.0

package/dist/funnelfox-billing.js

@@ -0,0 +1,1519 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+  typeof define === 'function' && define.amd ? define(['exports'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.FunnelfoxSDK = {}));
+})(this, (function (exports) { 'use strict';
+
+  /**
+   * @fileoverview Custom error classes for Funnefox SDK
+   */
+
+  /**
+   * Base error class for all Funnefox SDK errors
+   */
+  class FunnefoxSDKError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {string} [code='SDK_ERROR'] - Error code
+     * @param {*} [details=null] - Additional error details
+     */
+    constructor(message, code = 'SDK_ERROR', details = null) {
+      super(message);
+      this.name = 'FunnefoxSDKError';
+      this.code = code;
+      this.details = details;
+      if (Error.captureStackTrace) {
+        Error.captureStackTrace(this, FunnefoxSDKError);
+      }
+    }
+  }
+
+  /**
+   * Error thrown when input validation fails
+   */
+  class ValidationError extends FunnefoxSDKError {
+    /**
+     * @param {string} field - Field that failed validation
+     * @param {string} message - Validation error message
+     * @param {*} [value] - Invalid value that caused the error
+     */
+    constructor(field, message, value = null) {
+      super(`Invalid ${field}: ${message}`, 'VALIDATION_ERROR');
+      this.name = 'ValidationError';
+      this.field = field;
+      this.value = value;
+    }
+  }
+
+  /**
+   * Error thrown when API calls fail
+   */
+  class APIError extends FunnefoxSDKError {
+    /**
+     * @param {string} message - API error message
+     * @param {number} [statusCode] - HTTP status code
+     * @param {Object} [options] - Additional error details
+     * @param {string} [options.errorCode] - API error code (e.g., 'double_purchase')
+     * @param {string} [options.errorType] - API error type (e.g., 'api_exception')
+     * @param {string} [options.requestId] - Request ID for tracking
+     * @param {*} [options.response] - Full API response data
+     */
+    constructor(message, statusCode = null, options = {}) {
+      super(message, options.errorCode || 'API_ERROR');
+      this.name = 'APIError';
+      this.statusCode = statusCode;
+      this.errorCode = options.errorCode || null;
+      this.errorType = options.errorType || null;
+      this.requestId = options.requestId || null;
+      this.response = options.response || null;
+    }
+  }
+
+  /**
+   * Error thrown when Primer SDK integration fails
+   */
+  class PrimerError extends FunnefoxSDKError {
+    /**
+     * @param {string} message - Primer error message
+     * @param {*} [primerError] - Original Primer error object
+     */
+    constructor(message, primerError = null) {
+      super(message, 'PRIMER_ERROR');
+      this.name = 'PrimerError';
+      this.primerError = primerError;
+    }
+  }
+
+  /**
+   * Error thrown when checkout operations fail
+   */
+  class CheckoutError extends FunnefoxSDKError {
+    /**
+     * @param {string} message - Checkout error message
+     * @param {string} [phase] - Checkout phase where error occurred
+     */
+    constructor(message, phase = null) {
+      super(message, 'CHECKOUT_ERROR');
+      this.name = 'CheckoutError';
+      this.phase = phase;
+    }
+  }
+
+  /**
+   * Error thrown when SDK configuration is invalid
+   */
+  class ConfigurationError extends FunnefoxSDKError {
+    /**
+     * @param {string} message - Configuration error message
+     */
+    constructor(message) {
+      super(message, 'CONFIGURATION_ERROR');
+      this.name = 'ConfigurationError';
+    }
+  }
+
+  /**
+   * Error thrown when network requests fail
+   */
+  class NetworkError extends FunnefoxSDKError {
+    /**
+     * @param {string} message - Network error message
+     * @param {*} [originalError] - Original network error
+     */
+    constructor(message, originalError = null) {
+      super(message, 'NETWORK_ERROR');
+      this.name = 'NetworkError';
+      this.originalError = originalError;
+    }
+  }
+
+  /**
+   * @fileoverview Constants for Funnefox SDK
+   */
+
+  /**
+   * SDK version
+   */
+  const SDK_VERSION = '0.1.0';
+
+  /**
+   * Default configuration values
+   */
+  const DEFAULTS = {
+    BASE_URL: 'https://billing.funnelfox.com',
+    REGION: 'default',
+    SANDBOX: false,
+    REQUEST_TIMEOUT: 30000,
+    RETRY_ATTEMPTS: 3,
+    RETRY_BASE_DELAY: 1000
+  };
+
+  /**
+   * Checkout states
+   */
+  const CHECKOUT_STATES = {
+    INITIALIZING: 'initializing',
+    READY: 'ready',
+    PROCESSING: 'processing',
+    ACTION_REQUIRED: 'action_required',
+    UPDATING: 'updating',
+    COMPLETED: 'completed',
+    ERROR: 'error',
+    DESTROYED: 'destroyed'
+  };
+
+  /**
+   * Event names
+   */
+  const EVENTS = {
+    SUCCESS: 'success',
+    ERROR: 'error',
+    STATUS_CHANGE: 'status-change',
+    DESTROY: 'destroy'
+  };
+
+  /**
+   * Error codes
+   */
+  const ERROR_CODES = {
+    SDK_ERROR: 'SDK_ERROR',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    API_ERROR: 'API_ERROR',
+    PRIMER_ERROR: 'PRIMER_ERROR',
+    CHECKOUT_ERROR: 'CHECKOUT_ERROR',
+    CONFIGURATION_ERROR: 'CONFIGURATION_ERROR',
+    NETWORK_ERROR: 'NETWORK_ERROR'
+  };
+
+  /**
+   * @fileoverview Lightweight event emitter for Funnefox SDK
+   */
+
+  /**
+   * Simple event emitter for checkout instances
+   */
+  class EventEmitter {
+    constructor() {
+      this._events = new Map();
+    }
+
+    /**
+     * Add an event listener
+     * @param {string} eventName - Name of the event
+     * @param {function} handler - Event handler function
+     * @returns {EventEmitter} Returns this for chaining
+     */
+    on(eventName, handler) {
+      if (typeof handler !== 'function') {
+        throw new Error('Event handler must be a function');
+      }
+      if (!this._events.has(eventName)) {
+        this._events.set(eventName, []);
+      }
+      this._events.get(eventName).push(handler);
+      return this;
+    }
+
+    /**
+     * Add a one-time event listener
+     * @param {string} eventName - Name of the event
+     * @param {function} handler - Event handler function
+     * @returns {EventEmitter} Returns this for chaining
+     */
+    once(eventName, handler) {
+      if (typeof handler !== 'function') {
+        throw new Error('Event handler must be a function');
+      }
+      const onceWrapper = (...args) => {
+        this.off(eventName, onceWrapper);
+        handler.apply(this, args);
+      };
+      return this.on(eventName, onceWrapper);
+    }
+
+    /**
+     * Remove an event listener
+     * @param {string} eventName - Name of the event
+     * @param {function} [handler] - Specific handler to remove. If not provided, removes all handlers for the event
+     * @returns {EventEmitter} Returns this for chaining
+     */
+    off(eventName, handler = null) {
+      if (!this._events.has(eventName)) {
+        return this;
+      }
+      if (handler === null) {
+        this._events.delete(eventName);
+        return this;
+      }
+      const handlers = this._events.get(eventName);
+      const index = handlers.indexOf(handler);
+      if (index !== -1) {
+        handlers.splice(index, 1);
+        if (handlers.length === 0) {
+          this._events.delete(eventName);
+        }
+      }
+      return this;
+    }
+
+    /**
+     * Emit an event to all registered handlers
+     * @param {string} eventName - Name of the event to emit
+     * @param {...*} args - Arguments to pass to event handlers
+     * @returns {boolean} Returns true if event had listeners, false otherwise
+     */
+    emit(eventName, ...args) {
+      if (!this._events.has(eventName)) {
+        return false;
+      }
+      const handlers = this._events.get(eventName).slice();
+      for (const handler of handlers) {
+        try {
+          handler.apply(this, args);
+        } catch (error) {
+          // Don't let handler errors break the emission chain
+          // eslint-disable-next-line no-console
+          console.warn(`Error in event handler for "${eventName}":`, error);
+        }
+      }
+      return true;
+    }
+
+    /**
+     * Get the number of listeners for an event
+     * @param {string} eventName - Name of the event
+     * @returns {number} Number of listeners
+     */
+    listenerCount(eventName) {
+      return this._events.has(eventName) ? this._events.get(eventName).length : 0;
+    }
+
+    /**
+     * Get all event names that have listeners
+     * @returns {string[]} Array of event names
+     */
+    eventNames() {
+      return Array.from(this._events.keys());
+    }
+
+    /**
+     * Remove all listeners for all events
+     * @returns {EventEmitter} Returns this for chaining
+     */
+    removeAllListeners() {
+      this._events.clear();
+      return this;
+    }
+
+    /**
+     * Get all listeners for an event
+     * @param {string} eventName - Name of the event
+     * @returns {function[]} Array of handler functions
+     */
+    listeners(eventName) {
+      return this._events.has(eventName) ? this._events.get(eventName).slice() : [];
+    }
+  }
+
+  /**
+   * @fileoverview Helper utilities for Funnefox SDK
+   */
+
+
+  /**
+   * Merges multiple objects into a new object
+   * @param {...Object} objects - Objects to merge
+   * @returns {Object} Merged object
+   */
+  function merge(...objects) {
+    const result = {};
+    for (const obj of objects) {
+      if (obj && typeof obj === 'object') {
+        for (const key in obj) {
+          if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            if (typeof obj[key] === 'object' && !Array.isArray(obj[key]) && obj[key] !== null) {
+              result[key] = merge(result[key] || {}, obj[key]);
+            } else {
+              result[key] = obj[key];
+            }
+          }
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Generates a unique identifier
+   * @param {string} [prefix=''] - Optional prefix for the ID
+   * @returns {string} Unique identifier
+   */
+  function generateId(prefix = '') {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substr(2, 5);
+    return `${prefix}${timestamp}_${random}`;
+  }
+
+  /**
+   * Waits for a specified amount of time
+   * @param {number} ms - Milliseconds to wait
+   * @returns {Promise} Promise that resolves after the specified time
+   */
+  function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Retries a function with exponential backoff
+   * @param {function} fn - Function to retry
+   * @param {number} [maxAttempts=3] - Maximum number of attempts
+   * @param {number} [baseDelay=1000] - Base delay in milliseconds
+   * @returns {Promise} Promise that resolves with the function result
+   */
+  async function retry(fn, maxAttempts = 3, baseDelay = 1000) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (attempt === maxAttempts) {
+          throw lastError;
+        }
+        const delay = baseDelay * Math.pow(2, attempt - 1);
+        await sleep(delay);
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Creates a promise that rejects after a timeout
+   * @param {Promise} promise - Promise to wrap
+   * @param {number} timeoutMs - Timeout in milliseconds
+   * @param {string} [message='Operation timed out'] - Timeout error message
+   * @returns {Promise} Promise that rejects if timeout is reached
+   */
+  function withTimeout(promise, timeoutMs, message = 'Operation timed out') {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(message)), timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]);
+  }
+
+  /**
+   * @fileoverview Primer SDK integration wrapper
+   *
+   * @typedef {import('@primer-io/checkout-web').IPrimerHeadlessUniversalCheckout} PrimerCheckout
+   * @typedef {import('@primer-io/checkout-web').ITokenizationHandler} PrimerTokenizationHandler
+   * @typedef {import('@primer-io/checkout-web').IResumeHandler} PrimerResumeHandler
+   * @typedef {import('@primer-io/checkout-web').PaymentMethodTokenData} PaymentMethodTokenData
+   * @typedef {import('@primer-io/checkout-web').ResumeTokenData} ResumeTokenData
+   * @typedef {import('@primer-io/checkout-web').UniversalCheckoutOptions} UniversalCheckoutOptions
+   */
+
+
+  /**
+   * Wrapper class for Primer SDK integration
+   */
+  class PrimerWrapper {
+    constructor() {
+      this.currentCheckout = null;
+      this.isInitialized = false;
+    }
+
+    /**
+     * Checks if Primer SDK is available
+     * @returns {boolean} True if Primer is available
+     */
+    isPrimerAvailable() {
+      return typeof window !== 'undefined' && window.Primer && typeof window.Primer.showUniversalCheckout === 'function';
+    }
+
+    /**
+     * Ensures Primer SDK is available
+     * @throws {PrimerError} If Primer SDK is not available
+     */
+    ensurePrimerAvailable() {
+      if (!this.isPrimerAvailable()) {
+        throw new PrimerError('Primer SDK not found. Please include the Primer SDK script before initializing FunnefoxSDK.');
+      }
+    }
+
+    /**
+     * Creates a universal checkout instance
+     * @param {string} clientToken - Client token from your backend
+     * @param {Partial<UniversalCheckoutOptions> & {onTokenizeSuccess: function, onResumeSuccess: function}} options - Checkout options
+     * @returns {Promise<PrimerCheckout>} Primer checkout instance
+     */
+    async showUniversalCheckout(clientToken, options) {
+      this.ensurePrimerAvailable();
+
+      // Extract SDK-managed handlers
+      const {
+        onTokenizeSuccess,
+        onResumeSuccess,
+        container,
+        ...userPrimerOptions
+      } = options;
+
+      // Merge defaults with user's Primer options
+      /** @type {UniversalCheckoutOptions} */
+      const primerOptions = merge({
+        clientToken,
+        container,
+        paymentHandling: 'MANUAL',
+        apiVersion: '2.4',
+        paypal: {
+          buttonColor: 'blue',
+          paymentFlow: 'PREFER_VAULT'
+        }
+      }, userPrimerOptions);
+
+      // Add the required event handlers (must override any user-provided ones)
+      primerOptions.onTokenizeSuccess = this._wrapTokenizeHandler(onTokenizeSuccess);
+      primerOptions.onResumeSuccess = this._wrapResumeHandler(onResumeSuccess);
+      try {
+        const checkout = await window.Primer.showUniversalCheckout(clientToken, primerOptions);
+        this.currentCheckout = checkout;
+        this.isInitialized = true;
+        return checkout;
+      } catch (error) {
+        throw new PrimerError('Failed to initialize Primer checkout', error);
+      }
+    }
+
+    /**
+     * Wraps the tokenize success handler with error handling
+     * @private
+     * @param {function(PaymentMethodTokenData, PrimerTokenizationHandler): Promise<void>} handler
+     * @returns {function(PaymentMethodTokenData, PrimerTokenizationHandler): Promise<void>}
+     */
+    _wrapTokenizeHandler(handler) {
+      return async (paymentMethodTokenData, primerHandler) => {
+        try {
+          await handler(paymentMethodTokenData, primerHandler);
+        } catch (error) {
+          console.error('Error in tokenize handler:', error);
+          primerHandler.handleFailure('Payment processing failed. Please try again.');
+        }
+      };
+    }
+
+    /**
+     * Wraps the resume success handler with error handling
+     * @private
+     * @param {function(ResumeTokenData, PrimerResumeHandler): Promise<void>} handler
+     * @returns {function(ResumeTokenData, PrimerResumeHandler): Promise<void>}
+     */
+    _wrapResumeHandler(handler) {
+      return async (resumeTokenData, primerHandler) => {
+        try {
+          await handler(resumeTokenData, primerHandler);
+        } catch (error) {
+          console.error('Error in resume handler:', error);
+          primerHandler.handleFailure('Payment processing failed. Please try again.');
+        }
+      };
+    }
+
+    /**
+     * Updates the client token for an existing checkout
+     * @param {string} newClientToken - New client token
+     * @returns {Promise<void>}
+     */
+    async updateClientToken(newClientToken) {
+      if (!this.currentCheckout) {
+        throw new PrimerError('No active checkout to update');
+      }
+      try {
+        // Primer SDK doesn't have a direct update method, so we need to destroy and recreate
+        // This is handled at the checkout level
+        throw new PrimerError('Client token updates require checkout recreation');
+      } catch (error) {
+        throw new PrimerError('Failed to update client token', error);
+      }
+    }
+
+    /**
+     * Destroys the current checkout instance
+     * @returns {Promise<void>}
+     */
+    async destroy() {
+      if (this.currentCheckout) {
+        try {
+          // Primer checkout cleanup - this depends on Primer SDK version
+          if (typeof this.currentCheckout.destroy === 'function') {
+            await this.currentCheckout.destroy();
+          } else {
+            // Fallback - clear the container
+            const container = document.querySelector(this.currentCheckout.container);
+            if (container) {
+              container.innerHTML = '';
+            }
+          }
+        } catch (error) {
+          console.warn('Error destroying Primer checkout:', error);
+        } finally {
+          this.currentCheckout = null;
+          this.isInitialized = false;
+        }
+      }
+    }
+
+    /**
+     * Creates standardized Primer handler helpers
+     * @param {Object} handlers - Handler functions
+     * @param {function} handlers.onSuccess - Success callback
+     * @param {function} handlers.onError - Error callback
+     * @param {function} handlers.onActionRequired - Action required callback
+     * @returns {Object} Primer-compatible handler functions
+     */
+    createHandlers(handlers) {
+      return {
+        /**
+         * Handle successful tokenization
+         */
+        handleSuccess: () => {
+          if (handlers.onSuccess) {
+            handlers.onSuccess();
+          }
+        },
+        /**
+         * Handle payment failure
+         */
+        handleFailure: message => {
+          if (handlers.onError) {
+            handlers.onError(new Error(message));
+          }
+        },
+        /**
+         * Continue with new client token (for 3DS flows)
+         */
+        continueWithNewClientToken: newClientToken => {
+          if (handlers.onActionRequired) {
+            handlers.onActionRequired(newClientToken);
+          }
+        }
+      };
+    }
+
+    /**
+     * Gets the current checkout state
+     * @returns {PrimerCheckout|null} Current checkout instance or null
+     */
+    getCurrentCheckout() {
+      return this.currentCheckout;
+    }
+
+    /**
+     * Checks if checkout is currently active
+     * @returns {boolean} True if checkout is active
+     */
+    isActive() {
+      return this.isInitialized && this.currentCheckout !== null;
+    }
+
+    /**
+     * Validates that a container element exists and is suitable for Primer
+     * @param {string} selector - DOM selector
+     * @returns {Element} The container element
+     * @throws {PrimerError} If container is invalid
+     */
+    validateContainer(selector) {
+      const element = document.querySelector(selector);
+      if (!element) {
+        throw new PrimerError(`Checkout container not found: ${selector}`);
+      }
+
+      // Check if container is suitable (visible, not already in use, etc.)
+      const computedStyle = window.getComputedStyle(element);
+      if (computedStyle.display === 'none') {
+        console.warn('Checkout container is hidden, this may cause display issues');
+      }
+      return element;
+    }
+  }
+
+  var primerWrapper = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    default: PrimerWrapper
+  });
+
+  /**
+   * @fileoverview Input validation utilities for Funnefox SDK
+   */
+
+
+  /**
+   * Sanitizes a string input
+   * @param {*} input - Input to sanitize
+   * @returns {string} Sanitized string
+   */
+  function sanitizeString(input) {
+    if (input === null || input === undefined) {
+      return '';
+    }
+    return String(input).trim();
+  }
+
+  /**
+   * Validates that a value is a non-empty string
+   * @param {*} value - Value to validate
+   * @param {string} fieldName - Name of the field for error reporting
+   * @returns {boolean} True if valid
+   * @throws {ValidationError} If validation fails
+   */
+  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;
+  }
+
+  /**
+   * Validates that a container element exists in the DOM
+   * @param {string} selector - DOM selector
+   * @returns {Element} The found element
+   * @throws {ValidationError} If element not found
+   */
+  function validateContainer(selector) {
+    requireString(selector, 'container');
+    const element = document.querySelector(selector);
+    if (!element) {
+      throw new ValidationError('container', `element not found: ${selector}`, selector);
+    }
+    return element;
+  }
+
+  /**
+   * @fileoverview API client for Funnefox backend integration
+   */
+
+
+  /**
+   * HTTP client for Funnefox API requests
+   */
+  class APIClient {
+    /**
+     * @param {Object} config - API client configuration
+     * @param {string} config.baseUrl - Base URL for API calls
+     * @param {string} config.orgId - Organization identifier
+     * @param {number} [config.timeout=30000] - Request timeout in milliseconds
+     * @param {number} [config.retryAttempts=3] - Number of retry attempts
+     */
+    constructor(config) {
+      this.baseUrl = config.baseUrl.replace(/\/$/, '');
+      this.orgId = config.orgId;
+      this.timeout = config.timeout || 30000;
+      this.retryAttempts = config.retryAttempts || 3;
+    }
+
+    /**
+     * Makes an HTTP request with error handling and retries
+     * @param {string} endpoint - API endpoint
+     * @param {Object} [options={}] - Request options
+     * @returns {Promise<Object>} API response data
+     * @throws {APIError|NetworkError} If request fails
+     */
+    async request(endpoint, options = {}) {
+      const url = `${this.baseUrl}/${this.orgId}${endpoint}`;
+      const requestOptions = {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          ...options.headers
+        },
+        ...options
+      };
+      try {
+        return await retry(async () => {
+          return await withTimeout(this._makeRequest(url, requestOptions), this.timeout, 'Request timed out');
+        }, this.retryAttempts);
+      } catch (error) {
+        if (error.name === 'APIError') {
+          throw error;
+        }
+        throw new NetworkError('Network request failed', error);
+      }
+    }
+
+    /**
+     * Internal method to make the actual HTTP request
+     * @private
+     */
+    async _makeRequest(url, options) {
+      let response;
+      try {
+        response = await fetch(url, options);
+      } catch (error) {
+        throw new NetworkError('Network request failed', error);
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch (error) {
+        throw new APIError('Invalid JSON response', response.status, {});
+      }
+      if (!response.ok) {
+        const message = data.message || data.error || `HTTP ${response.status}`;
+        throw new APIError(message, response.status, {
+          response: data
+        });
+      }
+      return data;
+    }
+
+    /**
+     * Creates a client session for checkout
+     * @param {Object} params - Session parameters
+     * @param {string} params.priceId - Price point identifier
+     * @param {string} params.externalId - External user identifier
+     * @param {string} params.email - Customer email
+     * @param {Object} [params.clientMetadata] - Additional metadata
+     * @param {string} [params.region='default'] - Checkout region
+     * @param {string} [params.countryCode] - Optional ISO country code
+     * @returns {Promise<Object>} Client session response
+     */
+    async createClientSession(params) {
+      const payload = {
+        region: params.region || 'default',
+        integration_type: 'primer',
+        pp_ident: params.priceId,
+        external_id: params.externalId,
+        email_address: params.email,
+        client_metadata: params.clientMetadata || {}
+      };
+
+      // Add country_code if provided (nullable field per Swagger spec)
+      if (params.countryCode !== undefined) {
+        payload.country_code = params.countryCode;
+      }
+      return await this.request('/v1/checkout/create_client_session', {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+    }
+
+    /**
+     * Updates an existing client session
+     * @param {Object} params - Update parameters
+     * @param {string} params.orderId - Order identifier
+     * @param {string} params.clientToken - Current client token
+     * @param {string} params.priceId - New price identifier
+     * @returns {Promise<Object>} Update response
+     */
+    async updateClientSession(params) {
+      const payload = {
+        order_id: params.orderId,
+        client_token: params.clientToken,
+        pp_ident: params.priceId
+      };
+      return await this.request('/v1/checkout/update_client_session', {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+    }
+
+    /**
+     * Creates a payment with tokenized payment method
+     * @param {Object} params - Payment parameters
+     * @param {string} params.orderId - Order identifier
+     * @param {string} params.paymentMethodToken - Payment method token from Primer
+     * @returns {Promise<Object>} Payment response
+     */
+    async createPayment(params) {
+      const payload = {
+        order_id: params.orderId,
+        payment_method_token: params.paymentMethodToken
+      };
+      return await this.request('/v1/checkout/create_payment', {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+    }
+
+    /**
+     * Resumes a payment with 3DS or similar flows
+     * @param {Object} params - Resume parameters
+     * @param {string} params.orderId - Order identifier
+     * @param {string} params.resumeToken - Resume token from Primer
+     * @returns {Promise<Object>} Resume response
+     */
+    async resumePayment(params) {
+      const payload = {
+        order_id: params.orderId,
+        resume_token: params.resumeToken
+      };
+      return await this.request('/v1/checkout/resume_payment', {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+    }
+
+    /**
+     * One-click payment for returning customers with saved payment methods
+     * @param {Object} params - One-click payment parameters
+     * @param {string} params.externalId - External user identifier
+     * @param {string} params.priceId - Price point identifier
+     * @param {Object} [params.clientMetadata] - Additional metadata
+     * @returns {Promise<Object>} Payment response
+     */
+    async oneClickPayment(params) {
+      const payload = {
+        external_id: params.externalId,
+        pp_ident: params.priceId,
+        client_metadata: params.clientMetadata || {}
+      };
+      return await this.request('/v1/checkout/one_click', {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+    }
+
+    /**
+     * Processes session creation response (create_client_session)
+     * @param {Object} response - Raw API response
+     * @returns {Object} Processed session data
+     * @throws {APIError} If response indicates an error
+     */
+    processSessionResponse(response) {
+      if (response.status === 'error') {
+        // Extract error details from error array format
+        const firstError = response.error?.[0];
+        const message = firstError?.msg || 'Session creation failed';
+        throw new APIError(message, null, {
+          errorCode: firstError?.code,
+          errorType: firstError?.type,
+          requestId: response.req_id,
+          response
+        });
+      }
+      const data = response.data || response;
+      return {
+        type: 'session_created',
+        orderId: data.order_id,
+        clientToken: data.client_token
+      };
+    }
+
+    /**
+     * Processes payment/resume response (create_payment, resume_payment, one_click)
+     * @param {Object} response - Raw API response
+     * @returns {Object} Processed payment data
+     * @throws {APIError} If response indicates an error
+     */
+    processPaymentResponse(response) {
+      if (response.status === 'error') {
+        // Extract error details from error array format
+        const firstError = response.error?.[0];
+        const message = firstError?.msg || 'Payment request failed';
+        throw new APIError(message, null, {
+          errorCode: firstError?.code,
+          errorType: firstError?.type,
+          requestId: response.req_id,
+          response
+        });
+      }
+      const data = response.data || response;
+
+      // Check for action required (3DS, etc.)
+      if (data.action_required_token) {
+        return {
+          type: 'action_required',
+          orderId: data.order_id,
+          clientToken: data.action_required_token
+        };
+      }
+
+      // Handle checkout status
+      if (data.checkout_status) {
+        switch (data.checkout_status) {
+          case 'succeeded':
+            return {
+              type: 'success',
+              orderId: data.order_id,
+              status: 'succeeded',
+              transactionId: data.transaction_id
+            };
+          case 'failed':
+            throw new APIError(data.failed_message_for_user || 'Payment failed', null, data);
+          case 'cancelled':
+            throw new APIError('Payment was cancelled by user', null, data);
+          case 'processing':
+            return {
+              type: 'processing',
+              orderId: data.order_id,
+              status: 'processing'
+            };
+          default:
+            throw new APIError(`Unhandled checkout status: ${data.checkout_status}`, null, data);
+        }
+      }
+      throw new APIError('Invalid payment response format', null, data);
+    }
+
+    /**
+     * Processes API response and extracts relevant data
+     * @deprecated Use processSessionResponse() or processPaymentResponse() instead
+     * @param {Object} response - Raw API response
+     * @returns {Object} Processed response data
+     * @throws {APIError} If response indicates an error
+     */
+    processResponse(response) {
+      // Try to detect response type and delegate to specialized methods
+      const data = response.data || response;
+      if (data.client_token && data.order_id && !data.checkout_status) {
+        return this.processSessionResponse(response);
+      }
+      if (data.checkout_status || data.action_required_token) {
+        return this.processPaymentResponse(response);
+      }
+
+      // Fallback for unknown response types
+      throw new APIError('Unknown response format', null, response);
+    }
+  }
+
+  /**
+   * @fileoverview Checkout instance manager for Funnefox SDK
+   */
+
+
+  /**
+   * Checkout instance that manages the complete checkout lifecycle
+   * @typedef {import('./types').CheckoutInstance} CheckoutInstance
+   * @typedef {import('./types').CheckoutConfig} CheckoutConfig
+   * @typedef {import('./types').CheckoutConfigWithCallbacks} CheckoutConfigWithCallbacks
+   * @typedef {import('./types').PaymentResult} PaymentResult
+   * @typedef {import('./types').CheckoutState} CheckoutState
+   * @typedef {import('@primer-io/checkout-web').PaymentMethodTokenData} PaymentMethodTokenData
+   * @typedef {import('@primer-io/checkout-web').ResumeTokenData} ResumeTokenData
+   * @typedef {import('@primer-io/checkout-web').ITokenizationHandler} PrimerHandler
+   * @typedef {import('@primer-io/checkout-web').UniversalCheckoutOptions} UniversalCheckoutOptions
+   */
+  class CheckoutInstance extends EventEmitter {
+    /**
+     * @param {Object} config - Checkout configuration
+     * @param {string} config.orgId - Organization ID
+     * @param {string} [config.baseUrl] - API base URL
+     * @param {string} [config.region] - Region
+     * @param {CheckoutConfig | CheckoutConfigWithCallbacks} config.checkoutConfig - Checkout configuration
+     */
+    constructor(config) {
+      super();
+      this.id = generateId('checkout_');
+      this.orgId = config.orgId;
+      this.baseUrl = config.baseUrl;
+      this.region = config.region;
+      this.checkoutConfig = {
+        ...config.checkoutConfig
+      };
+
+      // Extract callbacks from config
+      this.callbacks = {
+        onSuccess: this.checkoutConfig.onSuccess,
+        onError: this.checkoutConfig.onError,
+        onStatusChange: this.checkoutConfig.onStatusChange,
+        onDestroy: this.checkoutConfig.onDestroy
+      };
+
+      // Clean callbacks from config to avoid sending to API
+      delete this.checkoutConfig.onSuccess;
+      delete this.checkoutConfig.onError;
+      delete this.checkoutConfig.onStatusChange;
+      delete this.checkoutConfig.onDestroy;
+
+      // Internal state
+      this.state = 'initializing';
+      this.orderId = null;
+      this.clientToken = null;
+      this.primerWrapper = new PrimerWrapper();
+      this.isDestroyed = false;
+
+      // Set up callback bridges if provided
+      this._setupCallbackBridges();
+
+      // Bind methods to preserve context
+      this._handleTokenizeSuccess = this._handleTokenizeSuccess.bind(this);
+      this._handleResumeSuccess = this._handleResumeSuccess.bind(this);
+    }
+
+    /**
+     * Set up bridges between events and callbacks
+     * @private
+     */
+    _setupCallbackBridges() {
+      if (this.callbacks.onSuccess) {
+        this.on('success', this.callbacks.onSuccess);
+      }
+      if (this.callbacks.onError) {
+        this.on('error', this.callbacks.onError);
+      }
+      if (this.callbacks.onStatusChange) {
+        this.on('status-change', this.callbacks.onStatusChange);
+      }
+      if (this.callbacks.onDestroy) {
+        this.on('destroy', this.callbacks.onDestroy);
+      }
+    }
+
+    /**
+     * Initialize the checkout instance
+     * @returns {Promise<CheckoutInstance>} Returns this instance for chaining
+     */
+    async initialize() {
+      try {
+        this._setState('initializing');
+
+        // Validate container exists
+        validateContainer(this.checkoutConfig.container);
+
+        // Create API client and session
+        this.apiClient = new APIClient({
+          baseUrl: this.baseUrl || DEFAULTS.BASE_URL,
+          orgId: this.orgId,
+          timeout: DEFAULTS.REQUEST_TIMEOUT,
+          retryAttempts: DEFAULTS.RETRY_ATTEMPTS
+        });
+        const sessionResponse = await this.apiClient.createClientSession({
+          priceId: this.checkoutConfig.priceId,
+          externalId: this.checkoutConfig.customer.externalId,
+          email: this.checkoutConfig.customer.email,
+          region: this.region || DEFAULTS.REGION,
+          clientMetadata: this.checkoutConfig.clientMetadata,
+          countryCode: this.checkoutConfig.customer.countryCode
+        });
+        const sessionData = this.apiClient.processSessionResponse(sessionResponse);
+        this.orderId = sessionData.orderId;
+        this.clientToken = sessionData.clientToken;
+
+        // Initialize Primer checkout
+        await this._initializePrimerCheckout();
+        this._setState('ready');
+        return this;
+      } catch (error) {
+        this._setState('error');
+        this.emit('error', error);
+        throw error;
+      }
+    }
+
+    /**
+     * Initialize Primer checkout with current client token
+     * @private
+     */
+    async _initializePrimerCheckout() {
+      /** @type {Partial<UniversalCheckoutOptions> & {onTokenizeSuccess: function, onResumeSuccess: function}} */
+      const checkoutOptions = {
+        container: this.checkoutConfig.container,
+        onTokenizeSuccess: this._handleTokenizeSuccess,
+        onResumeSuccess: this._handleResumeSuccess,
+        ...(this.checkoutConfig.universalCheckoutOptions || {})
+      };
+      await this.primerWrapper.showUniversalCheckout(this.clientToken, checkoutOptions);
+    }
+
+    /**
+     * Handle successful payment method tokenization
+     * @private
+     * @param {PaymentMethodTokenData} paymentMethodTokenData - Payment method token from Primer
+     * @param {PrimerHandler} primerHandler - Primer handler for success/failure
+     */
+    async _handleTokenizeSuccess(paymentMethodTokenData, primerHandler) {
+      try {
+        this._setState('processing');
+        const paymentResponse = await this.apiClient.createPayment({
+          orderId: this.orderId,
+          paymentMethodToken: paymentMethodTokenData.token
+        });
+        const result = this.apiClient.processPaymentResponse(paymentResponse);
+        await this._processPaymentResult(result, primerHandler);
+      } catch (error) {
+        this._setState('error');
+        this.emit('error', error);
+        primerHandler.handleFailure(error.message || 'Payment processing failed');
+      }
+    }
+
+    /**
+     * Handle successful payment resume (3DS flows)
+     * @private
+     * @param {ResumeTokenData} resumeTokenData - Resume token from Primer
+     * @param {PrimerHandler} primerHandler - Primer handler for success/failure
+     */
+    async _handleResumeSuccess(resumeTokenData, primerHandler) {
+      try {
+        this._setState('processing');
+        const resumeResponse = await this.apiClient.resumePayment({
+          orderId: this.orderId,
+          resumeToken: resumeTokenData.resumeToken
+        });
+        const result = this.apiClient.processPaymentResponse(resumeResponse);
+        await this._processPaymentResult(result, primerHandler);
+      } catch (error) {
+        this._setState('error');
+        this.emit('error', error);
+        primerHandler.handleFailure(error.message || 'Payment processing failed');
+      }
+    }
+
+    /**
+     * Process payment result and handle different scenarios
+     * @private
+     */
+    async _processPaymentResult(result, primerHandler) {
+      switch (result.type) {
+        case 'success':
+          this._setState('completed');
+          this.emit('success', {
+            orderId: result.orderId,
+            status: result.status,
+            transactionId: result.transactionId,
+            metadata: result.metadata
+          });
+          primerHandler.handleSuccess();
+          break;
+        case 'action_required':
+          this._setState('action_required');
+          // Update client token and continue
+          this.clientToken = result.clientToken;
+          primerHandler.continueWithNewClientToken(result.clientToken);
+          break;
+        case 'processing':
+          this._setState('processing');
+          // Let the payment process - usually requires polling or webhook
+          setTimeout(() => {
+            primerHandler.handleFailure('Payment is still processing. Please check back later.');
+          }, 30000);
+          break;
+        default:
+          throw new CheckoutError(`Unknown payment result type: ${result.type}`);
+      }
+    }
+
+    /**
+     * Update the checkout to use a different price
+     * @param {string} newPriceId - New price identifier
+     * @returns {Promise<void>}
+     */
+    async updatePrice(newPriceId) {
+      this._ensureNotDestroyed();
+      requireString(newPriceId, 'priceId');
+      if (this.state === 'processing') {
+        throw new CheckoutError('Cannot update price while payment is processing');
+      }
+      try {
+        this._setState('updating');
+
+        // Update client session with new price
+        await this.apiClient.updateClientSession({
+          orderId: this.orderId,
+          clientToken: this.clientToken,
+          priceId: newPriceId
+        });
+        this.checkoutConfig.priceId = newPriceId;
+        this._setState('ready');
+        this.emit('status-change', 'price-updated');
+      } catch (error) {
+        this._setState('error');
+        this.emit('error', error);
+        throw error;
+      }
+    }
+
+    /**
+     * Get current checkout status
+     * @returns {Object} Status information
+     */
+    getStatus() {
+      return {
+        id: this.id,
+        state: this.state,
+        orderId: this.orderId,
+        priceId: this.checkoutConfig.priceId,
+        isDestroyed: this.isDestroyed
+      };
+    }
+
+    /**
+     * Destroy the checkout instance and clean up resources
+     * @returns {Promise<void>}
+     */
+    async destroy() {
+      if (this.isDestroyed) {
+        return;
+      }
+      try {
+        // Clean up Primer checkout
+        await this.primerWrapper.destroy();
+
+        // Clear state
+        this._setState('destroyed');
+        this.orderId = null;
+        this.clientToken = null;
+        this.isDestroyed = true;
+
+        // Emit destroy event
+        this.emit('destroy');
+
+        // Remove all listeners
+        this.removeAllListeners();
+      } catch (error) {
+        console.warn('Error during checkout cleanup:', error);
+      }
+    }
+
+    /**
+     * Set internal state and emit change events
+     * @private
+     */
+    _setState(newState) {
+      if (this.state !== newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.emit('status-change', newState, oldState);
+      }
+    }
+
+    /**
+     * Ensure checkout is not destroyed
+     * @private
+     */
+    _ensureNotDestroyed() {
+      if (this.isDestroyed) {
+        throw new CheckoutError('Checkout instance has been destroyed');
+      }
+    }
+
+    /**
+     * Get the container element
+     * @returns {Element} Container element
+     */
+    getContainer() {
+      return document.querySelector(this.checkoutConfig.container);
+    }
+
+    /**
+     * Check if checkout is in a given state
+     * @param {string} state - State to check
+     * @returns {boolean} True if in the specified state
+     */
+    isInState(state) {
+      return this.state === state;
+    }
+
+    /**
+     * Check if checkout is ready for user interaction
+     * @returns {boolean} True if ready
+     */
+    isReady() {
+      return this.state === 'ready' && !this.isDestroyed;
+    }
+
+    /**
+     * Check if checkout is currently processing a payment
+     * @returns {boolean} True if processing
+     */
+    isProcessing() {
+      return ['processing', 'action_required'].includes(this.state);
+    }
+  }
+
+  /**
+   * @fileoverview Public API with configuration and orchestration logic
+   */
+
+  let defaultConfig = null;
+
+  /**
+   * Configure global SDK settings
+   * @param {import('./types').SDKConfig} config - SDK configuration
+   */
+  function configure(config) {
+    defaultConfig = config;
+  }
+
+  /**
+   * Resolve configuration with fallback chain
+   * @private
+   * @param {Object} options - Options with optional orgId and apiConfig
+   * @param {string} functionName - Name of calling function for error messages
+   * @returns {{orgId: string, baseUrl: string, region: string}} Resolved configuration
+   */
+  function resolveConfig(options, functionName) {
+    const {
+      orgId,
+      apiConfig
+    } = options;
+
+    // Fallback chain: params > configure() > error
+    const finalOrgId = orgId || defaultConfig?.orgId;
+    if (!finalOrgId) {
+      throw new Error(`orgId is required. Pass it to ${functionName}() or call configure() first.`);
+    }
+    const finalBaseUrl = apiConfig?.baseUrl || defaultConfig?.baseUrl || DEFAULTS.BASE_URL;
+    const finalRegion = apiConfig?.region || defaultConfig?.region || DEFAULTS.REGION;
+    return {
+      orgId: finalOrgId,
+      baseUrl: finalBaseUrl,
+      region: finalRegion
+    };
+  }
+
+  /**
+   * Create a checkout instance - supports both events and callbacks
+   * @param {import('./types').CreateCheckoutOptions} options - Checkout options with optional SDK config
+   * @returns {Promise<import('./types').CheckoutInstance>} Checkout instance
+   */
+  async function createCheckout(options) {
+    const {
+      ...checkoutConfig
+    } = options;
+
+    // Verify Primer SDK is available
+    const primerWrapper = new PrimerWrapper();
+    primerWrapper.ensurePrimerAvailable();
+
+    // Resolve configuration with fallback chain
+    const config = resolveConfig(options, 'createCheckout');
+    const checkout = new CheckoutInstance({
+      ...config,
+      checkoutConfig
+    });
+    await checkout.initialize();
+    return checkout;
+  }
+
+  /**
+   * Direct checkout creation with Primer (legacy compatible)
+   * @param {string} clientToken - Pre-created client token
+   * @param {Object} options - Primer options
+   * @returns {Promise<Object>} Primer checkout instance
+   */
+  async function showUniversalCheckout(clientToken, options) {
+    // Import dynamically to avoid circular dependencies
+    const {
+      default: PrimerWrapper
+    } = await Promise.resolve().then(function () { return primerWrapper; });
+    const primerWrapper$1 = new PrimerWrapper();
+    return await primerWrapper$1.showUniversalCheckout(clientToken, options);
+  }
+
+  /**
+   * Create client session for manual checkout integration
+   * @param {Object} params - Session creation parameters
+   * @param {string} params.priceId - Price identifier
+   * @param {string} params.externalId - Customer external ID
+   * @param {string} params.email - Customer email
+   * @param {string} [params.orgId] - Organization ID (optional if configured)
+   * @param {import('./types').APIConfig} [params.apiConfig] - Optional API config override
+   * @param {Object} [params.clientMetadata] - Optional client metadata
+   * @param {string} [params.countryCode] - Optional country code
+   * @returns {Promise<{clientToken: string, orderId: string, type: string}>} Session data
+   */
+  async function createClientSession(params) {
+    const {
+      priceId,
+      externalId,
+      email,
+      clientMetadata,
+      countryCode
+    } = params;
+
+    // Resolve configuration with fallback chain
+    const config = resolveConfig(params, 'createClientSession');
+
+    // Create API client and session
+    const apiClient = new APIClient({
+      baseUrl: config.baseUrl,
+      orgId: config.orgId,
+      timeout: DEFAULTS.REQUEST_TIMEOUT,
+      retryAttempts: DEFAULTS.RETRY_ATTEMPTS
+    });
+    const sessionResponse = await apiClient.createClientSession({
+      priceId,
+      externalId,
+      email,
+      region: config.region,
+      clientMetadata,
+      countryCode
+    });
+    return apiClient.processSessionResponse(sessionResponse);
+  }
+
+  /**
+   * @fileoverview Main entry point for @funnelfox/billing
+   *
+   * Modern functional SDK for subscription payments with Primer integration
+   *
+   * @example
+   * // Functional style (simple)
+   * import { configure, createCheckout } from '@funnelfox/billing';
+   *
+   * configure({
+   *   orgId: 'your-org-id'
+   * });
+   *
+   * const checkout = await createCheckout({
+   *   priceId: 'price_123',
+   *   customer: {
+   *     externalId: 'user_456',
+   *     email: 'user@example.com'
+   *   },
+   *   container: '#checkout-container'
+   * });
+   *
+   * @example
+   * // Namespace style
+   * import { Billing } from '@funnelfox/billing';
+   *
+   * Billing.configure({ orgId: 'your-org-id' });
+   * const checkout = await Billing.createCheckout({ ... });
+   *
+   * // Handle events
+   * checkout.on('success', (result) => {
+   *   console.log('Payment completed:', result.orderId);
+   * });
+   */
+
+  const Billing = {
+    configure: configure,
+    createCheckout: createCheckout,
+    showUniversalCheckout: showUniversalCheckout,
+    createClientSession: createClientSession
+  };
+  if (typeof window !== 'undefined') {
+    window.Billing = Billing;
+  }
+
+  exports.APIError = APIError;
+  exports.Billing = Billing;
+  exports.CHECKOUT_STATES = CHECKOUT_STATES;
+  exports.CheckoutError = CheckoutError;
+  exports.ConfigurationError = ConfigurationError;
+  exports.DEFAULTS = DEFAULTS;
+  exports.ERROR_CODES = ERROR_CODES;
+  exports.EVENTS = EVENTS;
+  exports.FunnefoxSDKError = FunnefoxSDKError;
+  exports.NetworkError = NetworkError;
+  exports.PrimerError = PrimerError;
+  exports.SDK_VERSION = SDK_VERSION;
+  exports.ValidationError = ValidationError;
+  exports.configure = configure;
+  exports.createCheckout = createCheckout;
+  exports.createClientSession = createClientSession;
+  exports.default = Billing;
+  exports.showUniversalCheckout = showUniversalCheckout;
+
+  Object.defineProperty(exports, '__esModule', { value: true });
+
+}));