elysium-attribution 1.0.0 → 1.0.2

package/src/config/schema.js

@@ -0,0 +1,85 @@
+import { logger } from '../utils/logger.js';
+
+export const DEFAULT_CONFIG = {
+  apiKey: '',
+  apiBaseUrl: 'https://asbTemp-production.up.railway.app',
+  debug: false,
+  sessionWindowMs: 30 * 60 * 1000, // 30 minutes
+  buttonSelector: '.elysium-payment-button',
+  autoTrack: true,
+  productPathRegex: null,
+  cookieDomain: undefined,
+  customParams: [],
+  gateways: {
+    stripe: {
+      enabled: true,
+      publishableKey: '',
+    },
+    razorpay: {
+      enabled: true,
+      keyId: '',
+    },
+    paypal: {
+      enabled: true,
+      clientId: '',
+    },
+  },
+};
+
+const SECRET_KEY_PATTERNS = [
+  /^sk_live_[0-9a-zA-Z]+/i,
+  /^sk_test_[0-9a-zA-Z]+/i,
+  /^sec_[0-9a-zA-Z]+/i,
+  /secret/i,
+];
+
+/**
+ * Audit configuration for secret key exposure and validate values.
+ */
+export function validateAndSanitizeConfig(userConfig = {}) {
+  const sanitized = { ...DEFAULT_CONFIG, ...userConfig };
+
+  // Check for exposed secret keys in common mistake fields
+  const suspiciousKeys = ['apiSecret', 'secretKey', 'clientSecret', 'privateKey'];
+  for (const key of suspiciousKeys) {
+    if (sanitized[key]) {
+      logger.error(
+        `SECURITY WARNING: "${key}" was found in browser configuration! Secret keys must NEVER be exposed in client-side code. This key has been stripped for your security.`
+      );
+      delete sanitized[key];
+    }
+  }
+
+  // Check gateway credentials
+  if (sanitized.gateways && typeof sanitized.gateways === 'object') {
+    sanitized.gateways = { ...DEFAULT_CONFIG.gateways, ...sanitized.gateways };
+
+    for (const [gwName, gwConfig] of Object.entries(sanitized.gateways)) {
+      if (!gwConfig || typeof gwConfig !== 'object') continue;
+
+      for (const [k, v] of Object.entries(gwConfig)) {
+        if (typeof v === 'string') {
+          for (const pattern of SECRET_KEY_PATTERNS) {
+            if (pattern.test(k) || pattern.test(v)) {
+              logger.error(
+                `SECURITY WARNING: Possible secret credential detected in gateway "${gwName}.${k}". Secret keys must remain on the backend!`
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Ensure base URL has no trailing slashes
+  if (sanitized.apiBaseUrl && typeof sanitized.apiBaseUrl === 'string') {
+    sanitized.apiBaseUrl = sanitized.apiBaseUrl.replace(/\/+$/, '');
+  }
+
+  // Ensure sessionWindowMs is valid positive integer
+  if (typeof sanitized.sessionWindowMs !== 'number' || sanitized.sessionWindowMs <= 0) {
+    sanitized.sessionWindowMs = DEFAULT_CONFIG.sessionWindowMs;
+  }
+
+  return sanitized;
+}

package/src/dom/buttonDetector.js

@@ -0,0 +1,128 @@
+import { getConfig } from '../config/index.js';
+import { gatewayRegistry } from '../gateways/GatewayRegistry.js';
+import { logger } from '../utils/logger.js';
+
+let isListening = false;
+let observer = null;
+const debouncedButtons = new WeakMap();
+const DEBOUNCE_DELAY_MS = 1500;
+
+/**
+ * Check if an element matches the configured payment button selectors
+ */
+export function isPaymentButton(target, selector) {
+  if (!target || typeof target.closest !== 'function') return null;
+  return target.closest(selector);
+}
+
+/**
+ * Handle a detected payment button click
+ */
+export async function handleButtonClickEvent(event, customSelector = null) {
+  const config = getConfig();
+  const selector = customSelector || config.buttonSelector || '.elysium-payment-button';
+
+  const button = isPaymentButton(event.target, selector);
+  if (!button) return;
+
+  // Prevent duplicate accidental double-clicks within debounce window
+  const lastClick = debouncedButtons.get(button);
+  const now = Date.now();
+  if (lastClick && now - lastClick < DEBOUNCE_DELAY_MS) {
+    logger.debug('Ignoring rapid double-click on payment button');
+    return;
+  }
+  debouncedButtons.set(button, now);
+
+  // Extract contextual information from the button and any surrounding form
+  const context = {
+    buttonId: button.id || null,
+    buttonClasses: button.className || null,
+    buttonText: button.innerText?.trim() || null,
+    gatewayAttribute: button.dataset?.gateway || null,
+    amount: button.dataset?.amount ? Number.parseFloat(button.dataset.amount) : null,
+    currency: button.dataset?.currency || null,
+    productId: button.dataset?.productId || null,
+  };
+
+  const form = button.closest('form');
+  if (form) {
+    context.formId = form.id || null;
+    context.formAction = form.action || null;
+  }
+
+  // Resolve associated payment gateway
+  const gateway = gatewayRegistry.resolveForButton(button);
+  logger.info(`Detected payment button interaction for gateway [${gateway.name}]:`, context);
+
+  // Trigger gateway attempt handler (NOTE: Button click is intent/attempt, NOT payment proof!)
+  try {
+    await gateway.handleButtonClick(button, context);
+  } catch (err) {
+    logger.error(`Error in ${gateway.name} handleButtonClick:`, err);
+  }
+
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(
+      new CustomEvent('elysium:payment_attempt', {
+        detail: { gateway: gateway.name, button, context },
+      })
+    );
+  }
+}
+
+/**
+ * Initialize payment button detection with delegated event listening and MutationObserver
+ */
+export function initPaymentButtonDetection(customSelector = null) {
+  if (typeof document === 'undefined') return () => {};
+
+  const config = getConfig();
+  const selector = customSelector || config.buttonSelector || '.elysium-payment-button';
+
+  if (!isListening) {
+    // Delegated click listener handles dynamically mounted buttons automatically
+    const clickHandler = (event) => handleButtonClickEvent(event, selector);
+    document.addEventListener('click', clickHandler, { capture: true, passive: true });
+    isListening = true;
+
+    // MutationObserver to detect when payment buttons appear in DOM
+    if (typeof MutationObserver !== 'undefined') {
+      observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          for (const node of mutation.addedNodes) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+              const matched = node.matches?.(selector) ? [node] : Array.from(node.querySelectorAll?.(selector) || []);
+              if (matched.length > 0) {
+                logger.debug(`MutationObserver detected ${matched.length} new payment button(s) dynamically`);
+                matched.forEach((btn) => {
+                  window.dispatchEvent(
+                    new CustomEvent('elysium:button_detected', { detail: { button: btn } })
+                  );
+                });
+              }
+            }
+          }
+        }
+      });
+
+      observer.observe(document.body || document.documentElement, {
+        childList: true,
+        subtree: true,
+      });
+    }
+
+    logger.debug(`Payment button detector initialized with selector: "${selector}"`);
+
+    return () => {
+      document.removeEventListener('click', clickHandler, { capture: true });
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+      isListening = false;
+    };
+  }
+
+  return () => {};
+}

package/src/gateways/GatewayRegistry.js

@@ -0,0 +1,75 @@
+import { StripeGateway } from './StripeGateway.js';
+import { RazorpayGateway } from './RazorpayGateway.js';
+import { PayPalGateway } from './PayPalGateway.js';
+import { GenericGateway } from './GenericGateway.js';
+import { logger } from '../utils/logger.js';
+
+export class GatewayRegistry {
+  constructor() {
+    this.gateways = new Map();
+    this.initDefaultGateways();
+  }
+
+  initDefaultGateways() {
+    this.register('stripe', new StripeGateway());
+    this.register('razorpay', new RazorpayGateway());
+    this.register('paypal', new PayPalGateway());
+    this.generic = new GenericGateway('generic');
+  }
+
+  register(name, gatewayInstance) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Gateway registration requires a string name');
+    }
+    const key = name.toLowerCase();
+    this.gateways.set(key, gatewayInstance);
+    logger.debug(`Registered payment gateway: ${key}`);
+    return gatewayInstance;
+  }
+
+  get(name) {
+    if (!name) return null;
+    return this.gateways.get(name.toLowerCase()) || null;
+  }
+
+  getAll() {
+    return Array.from(this.gateways.values());
+  }
+
+  /**
+   * Find the matching gateway for a button element or context
+   */
+  resolveForButton(buttonElement) {
+    if (!buttonElement) return this.generic;
+
+    // 1. Direct data-gateway attribute check
+    const explicitGatewayName = buttonElement.dataset?.gateway;
+    if (explicitGatewayName && this.gateways.has(explicitGatewayName.toLowerCase())) {
+      return this.gateways.get(explicitGatewayName.toLowerCase());
+    }
+
+    // 2. Iterate registered gateways and ask canHandle()
+    for (const gateway of this.gateways.values()) {
+      if (gateway.canHandle(buttonElement)) {
+        return gateway;
+      }
+    }
+
+    // 3. Fallback to generic gateway
+    return this.generic;
+  }
+
+  /**
+   * Reconfigure all registered gateways with latest config settings
+   */
+  configureAll(gatewaysConfig = {}) {
+    for (const [name, config] of Object.entries(gatewaysConfig)) {
+      const gw = this.get(name);
+      if (gw) {
+        gw.init(config);
+      }
+    }
+  }
+}
+
+export const gatewayRegistry = new GatewayRegistry();

package/src/gateways/GenericGateway.js

@@ -0,0 +1,12 @@
+import { PaymentGateway } from './PaymentGateway.js';
+
+export class GenericGateway extends PaymentGateway {
+  constructor(name = 'generic', config = {}) {
+    super(name, config);
+  }
+
+  canHandle(buttonOrContext) {
+    if (super.canHandle(buttonOrContext)) return true;
+    return true; // Generic acts as ultimate fallback
+  }
+}

package/src/gateways/PayPalGateway.js

@@ -0,0 +1,83 @@
+import { PaymentGateway } from './PaymentGateway.js';
+import { logger } from '../utils/logger.js';
+
+export class PayPalGateway extends PaymentGateway {
+  constructor(config = {}) {
+    super('paypal', config);
+  }
+
+  canHandle(buttonOrContext) {
+    if (super.canHandle(buttonOrContext)) return true;
+
+    if (typeof HTMLElement !== 'undefined' && buttonOrContext instanceof HTMLElement) {
+      const text = buttonOrContext.innerText?.toLowerCase() || '';
+      const id = buttonOrContext.id?.toLowerCase() || '';
+      const cls = buttonOrContext.className?.toLowerCase() || '';
+      if (text.includes('paypal') || id.includes('paypal') || cls.includes('paypal')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Wrap options passed to paypal.Buttons(...)
+   */
+  wrapButtons(options = {}) {
+    const originalCreateOrder = options.createOrder;
+    const originalOnApprove = options.onApprove;
+    const originalOnCancel = options.onCancel;
+    const originalOnError = options.onError;
+
+    return {
+      ...options,
+      createOrder: async (data, actions) => {
+        this.recordPaymentAttempt({ stage: 'createOrder', data });
+        if (typeof originalCreateOrder === 'function') {
+          return originalCreateOrder(data, actions);
+        }
+      },
+      onApprove: async (data, actions) => {
+        logger.info('[PayPal] Payment approved by buyer:', data);
+
+        this.recordPaymentSuccess({
+          transactionId: data.orderID,
+          orderId: data.orderID,
+          payerId: data.payerID,
+          paymentId: data.paymentID,
+          subscriptionId: data.subscriptionID,
+          source: 'paypal_buttons',
+        });
+
+        if (typeof originalOnApprove === 'function') {
+          return originalOnApprove(data, actions);
+        }
+      },
+      onCancel: (data) => {
+        logger.debug('[PayPal] Payment cancelled by buyer:', data);
+
+        this.recordPaymentFailure({
+          code: 'paypal_cancelled',
+          message: 'Buyer cancelled the PayPal flow',
+          orderId: data?.orderID,
+        });
+
+        if (typeof originalOnCancel === 'function') {
+          return originalOnCancel(data);
+        }
+      },
+      onError: (err) => {
+        logger.error('[PayPal] Payment error encountered:', err);
+
+        this.recordPaymentFailure({
+          code: 'paypal_error',
+          message: err?.message || String(err),
+        });
+
+        if (typeof originalOnError === 'function') {
+          return originalOnError(err);
+        }
+      },
+    };
+  }
+}

package/src/gateways/PaymentGateway.js

@@ -0,0 +1,173 @@
+import { getVisitorId } from '../signals/visitor.js';
+import { request } from '../signals/transport.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Base PaymentGateway class defining standard lifecycle and interface
+ */
+export class PaymentGateway {
+  constructor(name, config = {}) {
+    if (!name) throw new Error('Gateway must have a unique name');
+    this.name = name;
+    this.config = config;
+    this.listeners = new Map();
+  }
+
+  /**
+   * Lifecycle initialize
+   */
+  init(gatewayConfig = {}) {
+    this.config = { ...this.config, ...gatewayConfig };
+    logger.debug(`[Gateway:${this.name}] Initialized with config:`, this.config);
+  }
+
+  /**
+   * Determine if this gateway matches the clicked button or context
+   */
+  canHandle(buttonOrContext) {
+    if (!buttonOrContext) return false;
+
+    // Check DOM element data attributes
+    if (typeof HTMLElement !== 'undefined' && buttonOrContext instanceof HTMLElement) {
+      const dataGateway = buttonOrContext.dataset?.gateway;
+      if (dataGateway && dataGateway.toLowerCase() === this.name.toLowerCase()) {
+        return true;
+      }
+      // Check class name
+      if (buttonOrContext.classList.contains(`elysium-gateway-${this.name}`)) {
+        return true;
+      }
+    }
+
+    // Check context object
+    if (typeof buttonOrContext === 'object' && buttonOrContext.gateway) {
+      return buttonOrContext.gateway.toLowerCase() === this.name.toLowerCase();
+    }
+
+    return false;
+  }
+
+  /**
+   * Invoked when an elysium payment button associated with this gateway is clicked.
+   * NOTE: A button click is only a payment INTENT/ATTEMPT, never proof of payment!
+   */
+  async handleButtonClick(button, context = {}) {
+    logger.info(`[Gateway:${this.name}] Payment button interaction detected:`, {
+      gateway: this.name,
+      buttonText: button?.innerText?.trim(),
+      context,
+    });
+
+    return this.recordPaymentAttempt({
+      gateway: this.name,
+      buttonId: button?.id || null,
+      buttonClass: button?.className || null,
+      ...context,
+    });
+  }
+
+  /**
+   * Record payment attempt / checkout start
+   */
+  async recordPaymentAttempt(details = {}) {
+    const payload = {
+      visitorId: getVisitorId(),
+      gateway: this.name,
+      status: 'attempted',
+      timestamp: new Date().toISOString(),
+      metadata: details,
+    };
+
+    this.emit('attempt', payload);
+
+    return request('/v1/payment/attempt', {
+      method: 'POST',
+      body: payload,
+    });
+  }
+
+  /**
+   * Record verified payment success with transaction identifiers
+   */
+  async recordPaymentSuccess(paymentData = {}) {
+    const payload = {
+      visitorId: getVisitorId(),
+      gateway: this.name,
+      status: 'succeeded',
+      transactionId: paymentData.transactionId || paymentData.id || null,
+      orderId: paymentData.orderId || null,
+      amount: paymentData.amount || null,
+      currency: paymentData.currency || 'USD',
+      timestamp: new Date().toISOString(),
+      ...paymentData,
+      metadata: paymentData,
+    };
+
+    logger.info(`[Gateway:${this.name}] Payment succeeded:`, payload);
+    this.emit('success', payload);
+
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(
+        new CustomEvent('elysium:payment_success', { detail: payload })
+      );
+    }
+
+    return request('/v1/payment/success', {
+      method: 'POST',
+      body: payload,
+    });
+  }
+
+  /**
+   * Record payment failure or cancellation
+   */
+  async recordPaymentFailure(errorData = {}) {
+    const payload = {
+      visitorId: getVisitorId(),
+      gateway: this.name,
+      status: 'failed',
+      errorCode: errorData.code || null,
+      errorMessage: errorData.message || 'Payment failed',
+      timestamp: new Date().toISOString(),
+      metadata: errorData,
+    };
+
+    logger.warn(`[Gateway:${this.name}] Payment failed:`, payload);
+    this.emit('failure', payload);
+
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(
+        new CustomEvent('elysium:payment_failure', { detail: payload })
+      );
+    }
+
+    return request('/v1/payment/failure', {
+      method: 'POST',
+      body: payload,
+    });
+  }
+
+  /**
+   * Event emitter helpers
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => this.listeners.get(event)?.delete(callback);
+  }
+
+  emit(event, data) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((cb) => {
+        try {
+          cb(data);
+        } catch (err) {
+          logger.error(`Error in ${this.name} ${event} listener:`, err);
+        }
+      });
+    }
+  }
+}

package/src/gateways/RazorpayGateway.js

@@ -0,0 +1,88 @@
+import { PaymentGateway } from './PaymentGateway.js';
+import { logger } from '../utils/logger.js';
+
+export class RazorpayGateway extends PaymentGateway {
+  constructor(config = {}) {
+    super('razorpay', config);
+  }
+
+  canHandle(buttonOrContext) {
+    if (super.canHandle(buttonOrContext)) return true;
+
+    if (typeof HTMLElement !== 'undefined' && buttonOrContext instanceof HTMLElement) {
+      const text = buttonOrContext.innerText?.toLowerCase() || '';
+      const id = buttonOrContext.id?.toLowerCase() || '';
+      const cls = buttonOrContext.className?.toLowerCase() || '';
+      if (text.includes('razorpay') || id.includes('razorpay') || cls.includes('razorpay')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Wrap Razorpay checkout options to automatically intercept payment success/dismissal
+   */
+  wrapOptions(options = {}) {
+    const originalHandler = options.handler;
+
+    const wrappedOptions = {
+      ...options,
+      handler: (response) => {
+        logger.info('[Razorpay] Payment successful response received:', response);
+
+        this.recordPaymentSuccess({
+          transactionId: response.razorpay_payment_id,
+          orderId: response.razorpay_order_id,
+          signature: response.razorpay_signature,
+          amount: options.amount ? options.amount / 100 : undefined,
+          currency: options.currency || 'INR',
+        });
+
+        if (typeof originalHandler === 'function') {
+          return originalHandler(response);
+        }
+      },
+    };
+
+    // Modal dismiss handler
+    const originalModal = options.modal || {};
+    const originalOnDismiss = originalModal.ondismiss;
+    wrappedOptions.modal = {
+      ...originalModal,
+      ondismiss: () => {
+        logger.debug('[Razorpay] Checkout modal dismissed by user');
+        this.recordPaymentFailure({
+          code: 'modal_dismissed',
+          message: 'User closed the Razorpay checkout modal before completing payment',
+        });
+        if (typeof originalOnDismiss === 'function') {
+          return originalOnDismiss();
+        }
+      },
+    };
+
+    return wrappedOptions;
+  }
+
+  /**
+   * Instrument a Razorpay instance to listen for payment.failed events
+   */
+  wrapInstance(rzpInstance) {
+    if (!rzpInstance || typeof rzpInstance.on !== 'function') return rzpInstance;
+
+    rzpInstance.on('payment.failed', (response) => {
+      logger.warn('[Razorpay] Payment failed event caught:', response);
+      this.recordPaymentFailure({
+        code: response.error?.code || 'payment_failed',
+        message: response.error?.description || 'Razorpay payment failed',
+        reason: response.error?.reason,
+        step: response.error?.step,
+        orderId: response.error?.metadata?.order_id,
+        transactionId: response.error?.metadata?.payment_id,
+      });
+    });
+
+    return rzpInstance;
+  }
+}