elysium-attribution 1.0.0 → 1.0.2

package/src/signals/touchEngine.js

@@ -0,0 +1,211 @@
+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) {
+    // If request blocked by adblocker, we still save local event so UI/visitor state remains intact
+    if (res.blocked) {
+      logger.debug('Touch request blocked by client extension; continuing in local offline mode.');
+    } else {
+      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,
+    offlineMode: res.blocked ?? false,
+  };
+
+  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();
+  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.debug('Identify request status:', res.error);
+    return false;
+  }
+
+  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) {
+    // Generate resilient offline session if network/adblocker blocks the API
+    return {
+      checkoutSessionId: `chk_local_${Date.now()}`,
+      token: `tok_local_${Date.now()}`,
+      visitorId,
+      visitorRecordId: 'local_record',
+      touchIds: [],
+      touchCount: 1,
+      expiresAt: new Date(Date.now() + 3600000).toISOString(),
+    };
+  }
+
+  const result = res.data;
+  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/signals/transport.js

@@ -0,0 +1,64 @@
+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 isBlocked = error.message?.includes('Failed to fetch') || error.name === 'TypeError';
+
+    const message = isAbort
+      ? `Request to ${path} timed out after ${timeoutMs}ms`
+      : isBlocked
+      ? `Network request to ${url} was blocked (likely by an ad blocker / privacy extension). Touch gracefully skipped.`
+      : `Network error connecting to ${url}: ${error.message}`;
+
+    logger.debug(message);
+    return { ok: false, status: 0, error: message, data: null, blocked: isBlocked };
+  }
+}

package/src/signals/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/tracking/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/tracking/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/tracking/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;
+}