elysium-attribution 1.0.0 → 1.0.2

package/src/gateways/StripeGateway.js

@@ -0,0 +1,89 @@
+import { PaymentGateway } from './PaymentGateway.js';
+import { logger } from '../utils/logger.js';
+
+export class StripeGateway extends PaymentGateway {
+  constructor(config = {}) {
+    super('stripe', config);
+    this.checkRedirectReturn();
+  }
+
+  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('stripe') || id.includes('stripe') || cls.includes('stripe')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Automatically detect and attribute Stripe 3DS/redirect returns
+   */
+  checkRedirectReturn() {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const params = new URLSearchParams(window.location.search);
+      const paymentIntentId = params.get('payment_intent');
+      const redirectStatus = params.get('redirect_status');
+
+      if (paymentIntentId && redirectStatus) {
+        logger.info(`Detected Stripe return redirect: status=${redirectStatus}, id=${paymentIntentId}`);
+
+        if (redirectStatus === 'succeeded') {
+          this.recordPaymentSuccess({
+            transactionId: paymentIntentId,
+            status: redirectStatus,
+            source: 'stripe_redirect',
+          });
+        } else if (redirectStatus === 'failed') {
+          this.recordPaymentFailure({
+            code: 'stripe_redirect_failed',
+            message: `Stripe redirect finished with status: ${redirectStatus}`,
+            transactionId: paymentIntentId,
+          });
+        }
+      }
+    } catch (err) {
+      logger.debug('Error checking Stripe redirect return:', err);
+    }
+  }
+
+  /**
+   * Instrument a Stripe instance to automatically intercept confirmPayment / confirmCardPayment
+   */
+  wrapStripe(stripeInstance) {
+    if (!stripeInstance) return stripeInstance;
+
+    const originalConfirmPayment = stripeInstance.confirmPayment?.bind(stripeInstance);
+    if (originalConfirmPayment) {
+      stripeInstance.confirmPayment = async (options) => {
+        this.recordPaymentAttempt({ method: 'confirmPayment', options });
+        try {
+          const result = await originalConfirmPayment(options);
+          if (result.error) {
+            this.recordPaymentFailure(result.error);
+          } else if (result.paymentIntent?.status === 'succeeded') {
+            this.recordPaymentSuccess({
+              transactionId: result.paymentIntent.id,
+              amount: result.paymentIntent.amount / 100,
+              currency: result.paymentIntent.currency,
+              paymentIntent: result.paymentIntent,
+            });
+          }
+          return result;
+        } catch (err) {
+          this.recordPaymentFailure(err);
+          throw err;
+        }
+      };
+    }
+
+    return stripeInstance;
+  }
+}

package/src/gateways/index.js

@@ -0,0 +1,6 @@
+export { PaymentGateway } from './PaymentGateway.js';
+export { StripeGateway } from './StripeGateway.js';
+export { RazorpayGateway } from './RazorpayGateway.js';
+export { PayPalGateway } from './PayPalGateway.js';
+export { GenericGateway } from './GenericGateway.js';
+export { GatewayRegistry, gatewayRegistry } from './GatewayRegistry.js';

package/src/index.js

@@ -0,0 +1,151 @@
+import { configManager, getConfig, setConfig } from './config/index.js';
+import { getVisitorId, setVisitorId } from './signals/visitor.js';
+import {
+  recordTouch,
+  recordProductTouch,
+  identifyVisitor,
+  createCheckoutSession,
+  buildPayload,
+} from './signals/touchEngine.js';
+import { readTouchHistory, getTouchSignature } from './signals/session.js';
+import { extractMarketingParams } from './signals/params.js';
+import { parseReferrer } from './signals/referrer.js';
+import {
+  gatewayRegistry,
+  PaymentGateway,
+  StripeGateway,
+  RazorpayGateway,
+  PayPalGateway,
+  GenericGateway,
+} from './gateways/index.js';
+import { initPaymentButtonDetection } from './dom/buttonDetector.js';
+import { logger } from './utils/logger.js';
+
+let buttonDetectorCleanup = null;
+
+/**
+ * Main SDK initialization method.
+ * Configures API keys, starts tracking, registers gateways, and activates button detector.
+ */
+export function init(userConfig = {}) {
+  const config = configManager.init(userConfig);
+
+  // Configure gateways with user settings
+  if (config.gateways) {
+    gatewayRegistry.configureAll(config.gateways);
+  }
+
+  // Initialize payment button listener
+  if (buttonDetectorCleanup) {
+    buttonDetectorCleanup();
+  }
+  buttonDetectorCleanup = initPaymentButtonDetection(config.buttonSelector);
+
+  // Auto-record touchpoint if autoTrack enabled (default true)
+  if (config.autoTrack && typeof window !== 'undefined') {
+    // Run after current event loop turn to allow page title & DOM to settle
+    setTimeout(() => {
+      recordTouch().catch((err) => {
+        logger.error('Auto touch tracking encountered an error:', err);
+      });
+    }, 0);
+  }
+
+  logger.info('ElysiumSDK initialized successfully');
+  return Elysium;
+}
+
+/**
+ * Update active configuration at runtime
+ */
+export function configure(updates = {}) {
+  const config = setConfig(updates);
+  if (updates.gateways) {
+    gatewayRegistry.configureAll(updates.gateways);
+  }
+  if (updates.buttonSelector && buttonDetectorCleanup) {
+    buttonDetectorCleanup();
+    buttonDetectorCleanup = initPaymentButtonDetection(config.buttonSelector);
+  }
+  return config;
+}
+
+/**
+ * Explicit helper to record payment success
+ */
+export async function recordPaymentSuccess(details = {}) {
+  const gatewayName = details.gateway || 'generic';
+  const gateway = gatewayRegistry.get(gatewayName) || gatewayRegistry.generic;
+  return gateway.recordPaymentSuccess(details);
+}
+
+/**
+ * Explicit helper to record payment failure
+ */
+export async function recordPaymentFailure(details = {}) {
+  const gatewayName = details.gateway || 'generic';
+  const gateway = gatewayRegistry.get(gatewayName) || gatewayRegistry.generic;
+  return gateway.recordPaymentFailure(details);
+}
+
+/**
+ * Explicit helper to record payment attempt
+ */
+export async function recordPaymentAttempt(details = {}) {
+  const gatewayName = details.gateway || 'generic';
+  const gateway = gatewayRegistry.get(gatewayName) || gatewayRegistry.generic;
+  return gateway.recordPaymentAttempt(details);
+}
+
+/**
+ * Register a custom payment gateway
+ */
+export function registerGateway(name, gatewayInstance) {
+  return gatewayRegistry.register(name, gatewayInstance);
+}
+
+/**
+ * Retrieve a registered payment gateway by name
+ */
+export function getGateway(name) {
+  return gatewayRegistry.get(name);
+}
+
+// Unified SDK namespace object
+export const Elysium = {
+  init,
+  configure,
+  getConfig,
+  getVisitorId,
+  setVisitorId,
+  recordTouch,
+  recordProductTouch,
+  identifyVisitor,
+  createCheckoutSession,
+  buildPayload,
+  readTouchHistory,
+  getTouchSignature,
+  extractMarketingParams,
+  parseReferrer,
+  initPaymentButtonDetection,
+  registerGateway,
+  getGateway,
+  recordPaymentAttempt,
+  recordPaymentSuccess,
+  recordPaymentFailure,
+  gateways: {
+    PaymentGateway,
+    StripeGateway,
+    RazorpayGateway,
+    PayPalGateway,
+    GenericGateway,
+    registry: gatewayRegistry,
+  },
+};
+
+// Expose on global window object if running in browser
+if (typeof window !== 'undefined') {
+  window.Elysium = Elysium;
+}
+
+export default Elysium;

package/src/signals/params.js

@@ -0,0 +1,68 @@
+import { getCookie } from '../utils/storage.js';
+import { getConfig } from '../config/index.js';
+
+function getParam(params, key) {
+  return params.get(key) || null;
+}
+
+function getQueryParameter(params, name) {
+  return params.get(`utm_${name}`) ?? params.get(name) ?? null;
+}
+
+/**
+ * Extracts marketing parameters, click IDs, ad cookies, and custom parameters.
+ */
+export function extractMarketingParams(locationSearch = '') {
+  const search = locationSearch || (typeof window !== 'undefined' ? window.location.search : '');
+  const params = new URLSearchParams(search);
+  const config = getConfig();
+
+  // Core UTM parameters
+  const utm = {
+    source: getQueryParameter(params, 'source'),
+    medium: getQueryParameter(params, 'medium'),
+    campaign: getQueryParameter(params, 'campaign'),
+    term: getQueryParameter(params, 'term'),
+    content: getQueryParameter(params, 'content'),
+  };
+
+  // Advertising click IDs
+  const clickIds = {
+    gclid: getParam(params, 'gclid'),
+    dclid: getParam(params, 'dclid'),
+    wbraid: getParam(params, 'wbraid'),
+    gbraid: getParam(params, 'gbraid'),
+    srsltid: getParam(params, 'srsltid'),
+    fbclid: getParam(params, 'fbclid'),
+    ttclid: getParam(params, 'ttclid'),
+    msclkid: getParam(params, 'msclkid'),
+    twclid: getParam(params, 'twclid'),
+    li_fat_id: getParam(params, 'li_fat_id'),
+    rdt_cid: getParam(params, 'rdt_cid'),
+    epik: getParam(params, 'epik'),
+  };
+
+  // Ad cookies
+  const cookies = {
+    fbc: getCookie('_fbc'),
+    fbp: getCookie('_fbp'),
+    ttp: getCookie('_ttp'),
+    ga: getCookie('_ga'),
+  };
+
+  // Custom parameters defined by developer in elysium.config.js
+  const custom = {};
+  if (Array.isArray(config.customParams)) {
+    for (const key of config.customParams) {
+      const val = getParam(params, key);
+      if (val !== null) custom[key] = val;
+    }
+  }
+
+  return {
+    utm,
+    clickIds,
+    cookies,
+    custom,
+  };
+}

package/src/signals/referrer.js

@@ -0,0 +1,106 @@
+/**
+ * Referrer analysis module: distinguishes internal referrals from external,
+ * and classifies organic search and social traffic.
+ */
+
+const SEARCH_ENGINES = [
+  { name: 'google', pattern: /(?:^|\.)google\./i },
+  { name: 'bing', pattern: /(?:^|\.)bing\.com/i },
+  { name: 'yahoo', pattern: /(?:^|\.)yahoo\.com/i },
+  { name: 'duckduckgo', pattern: /(?:^|\.)duckduckgo\.com/i },
+  { name: 'baidu', pattern: /(?:^|\.)baidu\.com/i },
+  { name: 'yandex', pattern: /(?:^|\.)yandex\./i },
+  { name: 'ecosia', pattern: /(?:^|\.)ecosia\.org/i },
+];
+
+const SOCIAL_NETWORKS = [
+  { name: 'facebook', pattern: /(?:^|\.)(?:facebook\.com|fb\.com|l\.facebook\.com)/i },
+  { name: 'instagram', pattern: /(?:^|\.)instagram\.com/i },
+  { name: 'linkedin', pattern: /(?:^|\.)linkedin\.com/i },
+  { name: 'twitter', pattern: /(?:^|\.)(?:twitter\.com|t\.co|x\.com)/i },
+  { name: 'pinterest', pattern: /(?:^|\.)pinterest\./i },
+  { name: 'reddit', pattern: /(?:^|\.)reddit\.com/i },
+  { name: 'youtube', pattern: /(?:^|\.)youtube\.com/i },
+  { name: 'tiktok', pattern: /(?:^|\.)tiktok\.com/i },
+];
+
+/**
+ * Check if the referrer hostname belongs to the same domain
+ */
+export function isInternalReferrer(referrerUrl, currentHostname = '') {
+  if (!referrerUrl) return false;
+  try {
+    const refHost = new URL(referrerUrl).hostname.toLowerCase();
+    const currHost = (
+      currentHostname || (typeof window !== 'undefined' ? window.location.hostname : '')
+    ).toLowerCase();
+
+    if (!currHost || !refHost) return false;
+    if (refHost === currHost) return true;
+
+    // Check parent domain (e.g. shop.mystore.com and mystore.com)
+    const refParts = refHost.split('.');
+    const currParts = currHost.split('.');
+    if (refParts.length >= 2 && currParts.length >= 2) {
+      const refRoot = refParts.slice(-2).join('.');
+      const currRoot = currParts.slice(-2).join('.');
+      if (refRoot === currRoot) return true;
+    }
+  } catch {
+    // Malformed referrer
+  }
+  return false;
+}
+
+/**
+ * Parse referrer to identify organic search and social channels
+ */
+export function parseReferrer(rawReferrer = '', currentHostname = '') {
+  const referrer = rawReferrer || (typeof document !== 'undefined' ? document.referrer : '');
+  if (!referrer) {
+    return { referrer: null, isInternal: false, channel: 'direct', detectedSource: null, detectedMedium: null };
+  }
+
+  if (isInternalReferrer(referrer, currentHostname)) {
+    return { referrer: null, isInternal: true, channel: 'internal', detectedSource: null, detectedMedium: null };
+  }
+
+  try {
+    const refUrl = new URL(referrer);
+    const host = refUrl.hostname.toLowerCase();
+
+    for (const se of SEARCH_ENGINES) {
+      if (se.pattern.test(host)) {
+        return {
+          referrer,
+          isInternal: false,
+          channel: 'organic_search',
+          detectedSource: se.name,
+          detectedMedium: 'organic',
+        };
+      }
+    }
+
+    for (const sn of SOCIAL_NETWORKS) {
+      if (sn.pattern.test(host)) {
+        return {
+          referrer,
+          isInternal: false,
+          channel: 'social',
+          detectedSource: sn.name,
+          detectedMedium: 'social',
+        };
+      }
+    }
+
+    return {
+      referrer,
+      isInternal: false,
+      channel: 'referral',
+      detectedSource: host,
+      detectedMedium: 'referral',
+    };
+  } catch {
+    return { referrer, isInternal: false, channel: 'unknown', detectedSource: null, detectedMedium: null };
+  }
+}

package/src/signals/session.js

@@ -0,0 +1,134 @@
+import { safeLocalStorage } from '../utils/storage.js';
+import { getConfig } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+
+export const TOUCH_HISTORY_KEY = 'aid_touches';
+const MAX_HISTORY_LENGTH = 50;
+
+/**
+ * Validate shape of a stored touch record
+ */
+export function isStoredTouch(value) {
+  if (typeof value !== 'object' || value === null) return false;
+  return (
+    typeof value.recordedAt === 'number' &&
+    typeof value.payload === 'object' &&
+    value.payload !== null &&
+    typeof value.response === 'object' &&
+    value.response !== null
+  );
+}
+
+/**
+ * Read and validate touch history from storage
+ */
+export function readTouchHistory() {
+  try {
+    const raw = safeLocalStorage.getItem(TOUCH_HISTORY_KEY);
+    if (!raw) return [];
+
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+
+    return parsed.filter(isStoredTouch);
+  } catch (error) {
+    logger.debug('Could not read touch history:', error);
+    return [];
+  }
+}
+
+/**
+ * Save accepted touch with FIFO truncation to prevent storage exhaustion
+ */
+export function saveSuccessfulTouch(touch) {
+  try {
+    const history = readTouchHistory();
+    history.push(touch);
+
+    // Keep history bounded to avoid QuotaExceededError
+    while (history.length > MAX_HISTORY_LENGTH) {
+      history.shift();
+    }
+
+    safeLocalStorage.setItem(TOUCH_HISTORY_KEY, JSON.stringify(history));
+  } catch (error) {
+    logger.error('Failed to save touch to storage:', error);
+  }
+}
+
+/**
+ * Check if the payload contains an active marketing signal (paid or explicit campaign)
+ */
+export function hasMarketingSignal(payload) {
+  if (!payload) return false;
+  return Boolean(
+    payload.source ||
+    payload.medium ||
+    payload.campaign ||
+    payload.gclid ||
+    payload.fbclid ||
+    payload.ttclid ||
+    payload.msclkid ||
+    payload.dclid ||
+    payload.wbraid ||
+    payload.gbraid ||
+    payload.twclid ||
+    payload.li_fat_id ||
+    payload.rdt_cid
+  );
+}
+
+/**
+ * Generate a signature for deduplication
+ */
+export function getTouchSignature(payload) {
+  return [
+    payload.visitorId || '',
+    payload.source || '',
+    payload.medium || '',
+    payload.campaign || '',
+    payload.gclid || '',
+    payload.fbclid || '',
+    payload.ttclid || '',
+    payload.msclkid || '',
+    payload.dclid || '',
+    payload.wbraid || '',
+    payload.gbraid || '',
+    payload.landingPage || '',
+  ].join('|');
+}
+
+/**
+ * Determine whether a new touch should be transmitted to the backend.
+ * Prevents duplicates while ensuring multi-touch and session restarts are respected.
+ */
+export function shouldSendTouch(payload, history = null) {
+  const touchHistory = history || readTouchHistory();
+  const config = getConfig();
+  const sessionWindow = config.sessionWindowMs || 30 * 60 * 1000;
+
+  const previous = touchHistory[touchHistory.length - 1];
+
+  // If no previous touch recorded, always send
+  if (!previous) return true;
+
+  // If previous touch is older than the session window, this is a new session
+  if (Date.now() - previous.recordedAt > sessionWindow) return true;
+
+  const previousWasAttributed = hasMarketingSignal(previous.payload);
+  const currentIsAttributed = hasMarketingSignal(payload);
+
+  // Guard against overwriting an active paid ad attribution with an internal/direct navigation
+  if (previousWasAttributed && !currentIsAttributed) {
+    logger.debug('Skipping touch: Recent paid attribution protected from direct browse navigation.');
+    return false;
+  }
+
+  // Exact duplicate signature within the same session window
+  if (getTouchSignature(previous.payload) === getTouchSignature(payload)) {
+    logger.debug('Skipping touch: Duplicate touch signature within active session window.');
+    return false;
+  }
+
+  return true;
+}