@funnelfox/billing 0.1.0

package/dist/funnelfox-billing.cjs.js

@@ -0,0 +1,1513 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * @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;