elysium-attribution 1.0.0 → 1.0.2

package/src/tracking/touchTracker.js

@@ -0,0 +1,202 @@
+import { getVisitorId, setVisitorId } from './visitor.js';
+import { extractMarketingParams } from './params.js';
+import { parseReferrer } from './referrer.js';
+import { shouldSendTouch, saveSuccessfulTouch, readTouchHistory } from './session.js';
+import { request } from './transport.js';
+import { getConfig } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Construct full touch payload with parameters, referrer, and visitor ID
+ */
+export function buildPayload(customData = {}) {
+  const config = getConfig();
+  const visitorId = getVisitorId();
+  const { utm, clickIds, cookies, custom } = extractMarketingParams();
+  const referrerInfo = parseReferrer();
+
+  // If UTM source/medium missing, infer from organic/social referrer
+  const source = utm.source || referrerInfo.detectedSource || null;
+  const medium = utm.medium || referrerInfo.detectedMedium || null;
+
+  const currentHref = typeof window !== 'undefined' ? window.location.href : '';
+  const currentTitle = typeof document !== 'undefined' ? document.title : '';
+
+  return {
+    visitorId,
+    touchedAt: new Date().toISOString(),
+    source,
+    medium,
+    campaign: utm.campaign,
+    term: utm.term,
+    content: utm.content,
+    referrer: referrerInfo.referrer,
+    landingPage: currentHref,
+    pageTitle: currentTitle,
+    channel: referrerInfo.channel,
+    ...clickIds,
+    ...cookies,
+    custom: { ...custom, ...customData },
+  };
+}
+
+/**
+ * Record a marketing touchpoint
+ */
+export async function recordTouch(options = {}) {
+  const config = getConfig();
+
+  if (!config.apiKey) {
+    logger.warn('Tracking disabled: apiKey is not configured.');
+    return { ok: false, error: 'apiKey missing' };
+  }
+
+  // Path regex check if configured (e.g. for product pages only)
+  if (config.productPathRegex && typeof window !== 'undefined') {
+    const regex =
+      config.productPathRegex instanceof RegExp
+        ? config.productPathRegex
+        : new RegExp(config.productPathRegex);
+    if (!regex.test(window.location.pathname)) {
+      logger.debug('Skipping touch: Path did not match productPathRegex.');
+      return { ok: false, skipped: true, reason: 'path_mismatch' };
+    }
+  }
+
+  const payload = buildPayload(options.customData);
+  const history = readTouchHistory();
+
+  if (!options.force && !shouldSendTouch(payload, history)) {
+    logger.debug('Touch not sent: Duplicate or redundant in active session.');
+    return { ok: false, skipped: true, reason: 'deduplicated' };
+  }
+
+  logger.info('Sending touch payload:', payload);
+
+  const res = await request('/v1/touches', {
+    method: 'POST',
+    body: payload,
+  });
+
+  if (!res.ok) {
+    logger.error('Failed to record touch:', res.error);
+    return res;
+  }
+
+  const responseData = res.data || {
+    id: `local_${Date.now()}`,
+    visitorId: payload.visitorId,
+    channel: payload.channel || 'direct',
+    touchedAt: payload.touchedAt,
+  };
+
+  saveSuccessfulTouch({
+    payload,
+    response: responseData,
+    recordedAt: Date.now(),
+  });
+
+  logger.info('Touch recorded successfully:', responseData);
+
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(
+      new CustomEvent('elysium:touch_recorded', {
+        detail: { payload, response: responseData },
+      })
+    );
+  }
+
+  return { ok: true, data: responseData };
+}
+
+/**
+ * Backward-compatible product touch tracker from existing touch-tracking.ts
+ */
+export async function recordProductTouch() {
+  const config = getConfig();
+  // By default, if productPathRegex is not configured, preserve existing /product/ check
+  const pathRegex = config.productPathRegex || /^\/product\/[^/]+\/?$/;
+  if (typeof window !== 'undefined' && !pathRegex.test(window.location.pathname)) {
+    return;
+  }
+  return recordTouch();
+}
+
+/**
+ * Identify a visitor with their email and optional user traits
+ */
+export async function identifyVisitor(email, traits = {}) {
+  const config = getConfig();
+
+  if (!config.apiKey) {
+    logger.warn('Visitor identification failed: apiKey is not configured.');
+    return false;
+  }
+
+  if (!email || typeof email !== 'string') {
+    logger.error('identifyVisitor requires a valid email string.');
+    return false;
+  }
+
+  const visitorId = getVisitorId();
+  const payload = {
+    visitorId,
+    email,
+    traits,
+    identifiedAt: new Date().toISOString(),
+  };
+
+  const res = await request('/v1/identify', {
+    method: 'POST',
+    body: payload,
+  });
+
+  if (!res.ok) {
+    logger.error('Identify request failed:', res.error);
+    return false;
+  }
+
+  // Update canonical visitorId if returned by backend customer profile
+  if (res.data && res.data.canonicalVisitorId) {
+    setVisitorId(res.data.canonicalVisitorId);
+  }
+
+  logger.info('Visitor identified successfully:', res.data);
+  return true;
+}
+
+/**
+ * Request checkout attribution session token
+ */
+export async function createCheckoutSession() {
+  const config = getConfig();
+
+  if (!config.apiKey) {
+    throw new Error('Checkout session was not created: apiKey is not configured.');
+  }
+
+  const visitorId = getVisitorId();
+  const res = await request('/v1/checkout-sessions', {
+    method: 'POST',
+    body: { visitorId },
+  });
+
+  if (!res.ok) {
+    throw new Error(res.error || 'Failed to create checkout session');
+  }
+
+  const result = res.data;
+  if (!result || typeof result !== 'object' || !result.checkoutSessionId || !result.token) {
+    throw new Error('The checkout session endpoint returned an invalid response structure.');
+  }
+
+  return {
+    checkoutSessionId: result.checkoutSessionId,
+    token: result.token,
+    visitorId: result.visitorId || visitorId,
+    visitorRecordId: result.visitorRecordId || '',
+    touchIds: Array.isArray(result.touchIds) ? result.touchIds : [],
+    touchCount: typeof result.touchCount === 'number' ? result.touchCount : 0,
+    expiresAt: result.expiresAt || new Date(Date.now() + 3600000).toISOString(),
+  };
+}

package/src/tracking/transport.js

@@ -0,0 +1,60 @@
+import { getConfig } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+
+export async function request(path, options = {}) {
+  const config = getConfig();
+  const url = `${config.apiBaseUrl}${path}`;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(config.apiKey ? { 'X-Api-Key': config.apiKey, 'Authorization': `Bearer ${config.apiKey}` } : {}),
+    ...options.headers,
+  };
+
+  const timeoutMs = options.timeout ?? 8000;
+  let controller = null;
+  let timeoutId = null;
+
+  if (typeof AbortController !== 'undefined') {
+    controller = new AbortController();
+    timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  }
+
+  try {
+    const response = await fetch(url, {
+      method: options.method || 'POST',
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+      keepalive: options.keepalive ?? true,
+      signal: controller ? controller.signal : undefined,
+    });
+
+    if (timeoutId) clearTimeout(timeoutId);
+
+    const contentType = response.headers.get('content-type') || '';
+    let data = null;
+    if (contentType.includes('application/json')) {
+      data = await response.json().catch(() => null);
+    } else {
+      data = await response.text().catch(() => null);
+    }
+
+    if (!response.ok) {
+      const errorMsg =
+        (data && typeof data === 'object' && (data.message || data.error)) ||
+        `Request to ${path} failed with HTTP status ${response.status}`;
+      return { ok: false, status: response.status, error: errorMsg, data };
+    }
+
+    return { ok: true, status: response.status, data };
+  } catch (error) {
+    if (timeoutId) clearTimeout(timeoutId);
+    const isAbort = error.name === 'AbortError';
+    const message = isAbort
+      ? `Request to ${path} timed out after ${timeoutMs}ms`
+      : `Network error connecting to ${url}: ${error.message}`;
+
+    logger.error(message);
+    return { ok: false, status: 0, error: message, data: null };
+  }
+}

package/src/tracking/visitor.js

@@ -0,0 +1,82 @@
+import { safeLocalStorage, getCookie, setCookie } from '../utils/storage.js';
+import { getConfig } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+
+export const VISITOR_ID_KEY = 'aid_vid';
+let memoryVisitorId = null;
+
+/**
+ * Generate standard UUIDv4 with crypto fallback
+ */
+export function generateUUID() {
+  if (typeof crypto !== 'undefined') {
+    if (typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID();
+    }
+    if (typeof crypto.getRandomValues === 'function') {
+      const buffer = new Uint8Array(16);
+      crypto.getRandomValues(buffer);
+      buffer[6] = (buffer[6] & 0x0f) | 0x40;
+      buffer[8] = (buffer[8] & 0x3f) | 0x80;
+      const hex = Array.from(buffer, (b) => b.toString(16).padStart(2, '0')).join('');
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+  }
+
+  const randomHex = () => Math.floor(Math.random() * 16).toString(16);
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (character) => {
+    const value = Number.parseInt(randomHex(), 16);
+    return (character === 'x' ? value : (value & 0x3) | 0x8).toString(16);
+  });
+}
+
+/**
+ * Retrieve or create persistent visitor ID.
+ * Keeps cookie and localStorage synchronized to prevent identity loss across ITP/subdomains.
+ */
+export function getVisitorId() {
+  if (memoryVisitorId) {
+    return memoryVisitorId;
+  }
+
+  // 1. Try LocalStorage
+  let visitorId = safeLocalStorage.getItem(VISITOR_ID_KEY);
+
+  // 2. Try Cookie if not in LocalStorage
+  if (!visitorId) {
+    visitorId = getCookie(VISITOR_ID_KEY);
+  }
+
+  // 3. Generate new if missing
+  if (!visitorId) {
+    visitorId = generateUUID();
+    logger.debug('Generated new visitor ID:', visitorId);
+  }
+
+  // 4. Synchronize back to both storages
+  const config = getConfig();
+  safeLocalStorage.setItem(VISITOR_ID_KEY, visitorId);
+  setCookie(VISITOR_ID_KEY, visitorId, {
+    maxAge: 63072000, // 2 years
+    path: '/',
+    domain: config.cookieDomain,
+  });
+
+  memoryVisitorId = visitorId;
+  return visitorId;
+}
+
+/**
+ * Set custom or backend-canonicalized visitor ID
+ */
+export function setVisitorId(newId) {
+  if (!newId || typeof newId !== 'string') return;
+  memoryVisitorId = newId;
+  const config = getConfig();
+  safeLocalStorage.setItem(VISITOR_ID_KEY, newId);
+  setCookie(VISITOR_ID_KEY, newId, {
+    maxAge: 63072000,
+    path: '/',
+    domain: config.cookieDomain,
+  });
+}

package/src/utils/attributionInit.js

@@ -1,3 +1,56 @@
-export const initAttribution = () => {
-    
-}
+
+const API_BASE_URL =
+  "https://asbTemp-production.up.railway.app/".replace(/\/+$/, "");
+
+export function initAttribution(apikey) {
+  if (!apikey || typeof apikey !== "string") {
+    throw new Error("A valid API key is required.");
+  }
+
+  if (typeof window === "undefined") return;
+
+  const visitorKey = "aid_vid";
+
+  let visitorId = localStorage.getItem(visitorKey);
+
+  if (!visitorId) {
+    visitorId = crypto.randomUUID();
+    localStorage.setItem(visitorKey, visitorId);
+  }
+
+  const params = new URLSearchParams(location.search);
+
+  const hasMarketingParams = [
+    "utm_source", "utm_medium", "utm_campaign",
+    "gclid", "fbclid", "ttclid", "msclkid"
+  ].some(key => params.has(key));
+
+  if (!hasMarketingParams) return;
+
+  const payload = {
+    visitorId,
+    touchedAt: new Date().toISOString(),
+    source: params.get("utm_source"),
+    medium: params.get("utm_medium"),
+    campaign: params.get("utm_campaign"),
+    term: params.get("utm_term"),
+    content: params.get("utm_content"),
+    referrer: document.referrer || null,
+    landingPage: location.href,
+    pageTitle: document.title,
+    gclid: params.get("gclid"),
+    fbclid: params.get("fbclid"),
+    ttclid: params.get("ttclid"),
+    msclkid: params.get("msclkid")
+  };
+
+  return fetch(`${API_BASE_URL}/v1/touches`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "authorization": apikey
+    },
+    body: JSON.stringify(payload),
+    keepalive: true
+  });
+}

package/src/utils/cli.js

@@ -1,17 +1,69 @@
-#!/usr/bin/env node
-
-import fs from 'fs';
-
-const configPath = 'elysium.config.js';
-
-if(fs.existsSync(configPath)){
-    console.log("The config already exists");
-    process.exit(0);
-}
-fs.writeFileSync(
-  configPath,
-  `export default {
-  apiKey: "",
-  debug: true,
-};\n`
-);
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const configPath = 'elysium.config.js';
+
+if (fs.existsSync(configPath)) {
+  console.log(`[ElysiumSDK] Configuration file already exists at ${path.resolve(configPath)}`);
+  process.exit(0);
+}
+
+const template = `/**
+ * ElysiumSDK Configuration File
+ *
+ * IMPORTANT SECURITY NOTICE:
+ * This configuration is loaded on the client side (browser).
+ * ONLY include PUBLISHABLE keys here. NEVER expose secret keys
+ * (e.g., Stripe secret key "sk_live_...", Razorpay key secret, or private tokens).
+ * Secret keys must remain strictly on your backend server.
+ */
+export default {
+  // Public attribution API Key provided by Elysium
+  apiKey: "YOUR_ELYSIUM_PUBLIC_API_KEY",
+
+  // Attribution API Backend endpoint
+  apiBaseUrl: "https://asbTemp-production.up.railway.app",
+
+  // Enable verbose debugging logs in browser console
+  debug: false,
+
+  // Session inactivity timeout in milliseconds (default: 30 minutes)
+  sessionWindowMs: 30 * 60 * 1000,
+
+  // CSS selector or class for detecting checkout/payment buttons
+  buttonSelector: ".elysium-payment-button",
+
+  // Automatically record touch on page load
+  autoTrack: true,
+
+  // Optional: restrict touch tracking to specific path regex (e.g. product pages only)
+  // productPathRegex: null,
+
+  // Domain for cross-subdomain cookie tracking (e.g., ".yourstore.com")
+  cookieDomain: undefined,
+
+  // Additional custom query parameters to capture and attribute
+  customParams: [],
+
+  // Supported payment gateways configuration (PUBLIC keys only)
+  gateways: {
+    stripe: {
+      enabled: true,
+      publishableKey: "pk_test_...", // Stripe Publishable Key (NOT secret key)
+    },
+    razorpay: {
+      enabled: true,
+      keyId: "rzp_test_...",        // Razorpay Key ID (NOT key secret)
+    },
+    paypal: {
+      enabled: true,
+      clientId: "YOUR_PAYPAL_CLIENT_ID", // PayPal Client ID (NOT client secret)
+    },
+  },
+};
+`;
+
+fs.writeFileSync(configPath, template, 'utf8');
+console.log(`[ElysiumSDK] Created template configuration file at ${configPath}`);

package/src/utils/logger.js

@@ -0,0 +1,31 @@
+/**
+ * Safe logger for ElysiumSDK
+ */
+export class Logger {
+  constructor(getDebug = () => false) {
+    this.getDebug = getDebug;
+    this.prefix = '[ElysiumSDK]';
+  }
+
+  debug(...args) {
+    if (this.getDebug()) {
+      console.debug(this.prefix, ...args);
+    }
+  }
+
+  info(...args) {
+    if (this.getDebug()) {
+      console.info(this.prefix, ...args);
+    }
+  }
+
+  warn(...args) {
+    console.warn(this.prefix, ...args);
+  }
+
+  error(...args) {
+    console.error(this.prefix, ...args);
+  }
+}
+
+export const logger = new Logger();

package/src/utils/storage.js

@@ -0,0 +1,110 @@
+/**
+ * Resilient cross-browser storage utilities with in-memory fallbacks
+ * and Safari ITP-aware cookie handling.
+ */
+
+class MemoryStorage {
+  constructor() {
+    this.store = new Map();
+  }
+  getItem(key) {
+    return this.store.has(key) ? this.store.get(key) : null;
+  }
+  setItem(key, value) {
+    this.store.set(key, String(value));
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+}
+
+const memoryFallback = new MemoryStorage();
+
+export function isLocalStorageAvailable() {
+  try {
+    if (typeof window === 'undefined' || !window.localStorage) return false;
+    const testKey = '__elysium_storage_test__';
+    window.localStorage.setItem(testKey, '1');
+    window.localStorage.removeItem(testKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const safeLocalStorage = {
+  getItem(key) {
+    try {
+      if (isLocalStorageAvailable()) {
+        return window.localStorage.getItem(key);
+      }
+    } catch {
+      // Fallback below
+    }
+    return memoryFallback.getItem(key);
+  },
+
+  setItem(key, value) {
+    try {
+      if (isLocalStorageAvailable()) {
+        window.localStorage.setItem(key, value);
+        return;
+      }
+    } catch {
+      // Storage quota exceeded or disabled
+    }
+    memoryFallback.setItem(key, value);
+  },
+
+  removeItem(key) {
+    try {
+      if (isLocalStorageAvailable()) {
+        window.localStorage.removeItem(key);
+      }
+    } catch {
+      // Fallback
+    }
+    memoryFallback.removeItem(key);
+  }
+};
+
+/**
+ * Safely parse cookie string regardless of spacing
+ */
+export function getCookie(name) {
+  if (typeof document === 'undefined') return null;
+  try {
+    const escapedName = name.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+    const regex = new RegExp(`(?:^|;)\\s*${escapedName}=([^;]*)`);
+    const match = document.cookie.match(regex);
+    if (!match) return null;
+    return decodeURIComponent(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Set a cookie safely with max-age, path, sameSite, and optional domain
+ */
+export function setCookie(name, value, options = {}) {
+  if (typeof document === 'undefined') return;
+  try {
+    const maxAge = options.maxAge ?? 63072000; // 2 years default
+    const path = options.path ?? '/';
+    const sameSite = options.sameSite ?? 'Lax';
+    const isHttps = typeof window !== 'undefined' && window.location.protocol === 'https:';
+    const secure = options.secure ?? isHttps;
+
+    let cookieStr = `${encodeURIComponent(name)}=${encodeURIComponent(value)}; max-age=${maxAge}; path=${path}; SameSite=${sameSite}`;
+    if (secure) cookieStr += '; Secure';
+    if (options.domain) cookieStr += `; domain=${options.domain}`;
+
+    document.cookie = cookieStr;
+  } catch {
+    // In restricted iframe or sandbox
+  }
+}

package/test/buttonDetector.test.js

@@ -0,0 +1,26 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isPaymentButton } from '../src/dom/buttonDetector.js';
+
+describe('Payment Button Detector Module', () => {
+  it('detects button matching configured selector via closest()', () => {
+    const mockButton = {
+      tagName: 'BUTTON',
+      className: 'elysium-payment-button custom-style',
+      closest: (sel) => {
+        if (sel.includes('.elysium-payment-button')) return mockButton;
+        return null;
+      },
+    };
+
+    const mockChildSpan = {
+      tagName: 'SPAN',
+      innerText: 'Pay Now',
+      closest: (sel) => mockButton.closest(sel),
+    };
+
+    assert.equal(isPaymentButton(mockButton, '.elysium-payment-button'), mockButton);
+    assert.equal(isPaymentButton(mockChildSpan, '.elysium-payment-button'), mockButton);
+    assert.equal(isPaymentButton(mockButton, '.non-existent-button'), null);
+  });
+});

package/test/config.test.js

@@ -0,0 +1,35 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateAndSanitizeConfig } from '../src/config/schema.js';
+import { configManager } from '../src/config/index.js';
+
+describe('Configuration & Security Sanitization Module', () => {
+  it('loads default configuration', () => {
+    const config = validateAndSanitizeConfig({});
+    assert.equal(config.apiBaseUrl, 'https://asbTemp-production.up.railway.app');
+    assert.equal(config.buttonSelector, '.elysium-payment-button');
+    assert.equal(config.sessionWindowMs, 1800000);
+  });
+
+  it('removes trailing slashes from apiBaseUrl', () => {
+    const config = validateAndSanitizeConfig({
+      apiBaseUrl: 'https://api.elysium.dev///',
+    });
+    assert.equal(config.apiBaseUrl, 'https://api.elysium.dev');
+  });
+
+  it('strips client-exposed secret keys to prevent security leaks', () => {
+    const unsafeConfig = {
+      apiKey: 'pk_live_safe_123',
+      secretKey: 'sk_live_DANGEROUS_SECRET_NEVER_EXPOSE',
+      apiSecret: 'SUPER_SECRET',
+      clientSecret: 'ANOTHER_SECRET',
+    };
+
+    const sanitized = validateAndSanitizeConfig(unsafeConfig);
+    assert.equal(sanitized.apiKey, 'pk_live_safe_123');
+    assert.equal(sanitized.secretKey, undefined);
+    assert.equal(sanitized.apiSecret, undefined);
+    assert.equal(sanitized.clientSecret, undefined);
+  });
+});