elysium-attribution 1.0.0 → 1.0.2

package/test/gateways.test.js

@@ -0,0 +1,112 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  GatewayRegistry,
+  PaymentGateway,
+  StripeGateway,
+  RazorpayGateway,
+  PayPalGateway,
+  GenericGateway,
+} from '../src/gateways/index.js';
+
+describe('Payment Gateways Architecture', () => {
+  it('manages default and custom gateways in GatewayRegistry', () => {
+    const registry = new GatewayRegistry();
+
+    assert.ok(registry.get('stripe') instanceof StripeGateway);
+    assert.ok(registry.get('razorpay') instanceof RazorpayGateway);
+    assert.ok(registry.get('paypal') instanceof PayPalGateway);
+
+    // Register custom crypto gateway
+    class CryptoGateway extends PaymentGateway {
+      constructor() {
+        super('crypto');
+      }
+    }
+    registry.register('crypto', new CryptoGateway());
+    assert.ok(registry.get('crypto') instanceof CryptoGateway);
+  });
+
+  it('PaymentGateway emits lifecycle events on attempt, success, and failure', async () => {
+    const gateway = new GenericGateway('testgw');
+    const events = [];
+
+    gateway.on('attempt', (e) => events.push({ type: 'attempt', ...e }));
+    gateway.on('success', (e) => events.push({ type: 'success', ...e }));
+    gateway.on('failure', (e) => events.push({ type: 'failure', ...e }));
+
+    await gateway.recordPaymentAttempt({ stage: 'init' });
+    await gateway.recordPaymentSuccess({ transactionId: 'tx_999', amount: 150 });
+    await gateway.recordPaymentFailure({ code: 'card_declined', message: 'Insufficient funds' });
+
+    assert.equal(events.length, 3);
+    assert.equal(events[0].type, 'attempt');
+    assert.equal(events[1].type, 'success');
+    assert.equal(events[1].transactionId, 'tx_999');
+    assert.equal(events[2].type, 'failure');
+    assert.equal(events[2].errorCode, 'card_declined');
+  });
+
+  it('RazorpayGateway wraps options and intercepts success handler', async () => {
+    const rzpGateway = new RazorpayGateway();
+    let originalHandlerCalled = false;
+    let recordedSuccess = null;
+
+    rzpGateway.on('success', (data) => {
+      recordedSuccess = data;
+    });
+
+    const originalOptions = {
+      key: 'rzp_test_123',
+      amount: 50000,
+      currency: 'INR',
+      handler: (res) => {
+        originalHandlerCalled = true;
+      },
+    };
+
+    const wrapped = rzpGateway.wrapOptions(originalOptions);
+    assert.notEqual(wrapped.handler, originalOptions.handler);
+
+    // Simulate Razorpay calling the handler upon customer completing payment
+    wrapped.handler({
+      razorpay_payment_id: 'pay_ABC123',
+      razorpay_order_id: 'order_XYZ456',
+      razorpay_signature: 'sig_789',
+    });
+
+    assert.equal(originalHandlerCalled, true);
+    assert.ok(recordedSuccess);
+    assert.equal(recordedSuccess.transactionId, 'pay_ABC123');
+    assert.equal(recordedSuccess.orderId, 'order_XYZ456');
+    assert.equal(recordedSuccess.amount, 500); // 50000 paise -> 500 INR
+  });
+
+  it('PayPalGateway wraps buttons and intercepts onApprove', async () => {
+    const ppGateway = new PayPalGateway();
+    let originalApproveCalled = false;
+    let recordedSuccess = null;
+
+    ppGateway.on('success', (data) => {
+      recordedSuccess = data;
+    });
+
+    const originalButtonOpts = {
+      createOrder: () => 'order_pp_1',
+      onApprove: (data) => {
+        originalApproveCalled = true;
+      },
+    };
+
+    const wrapped = ppGateway.wrapButtons(originalButtonOpts);
+    await wrapped.onApprove({
+      orderID: 'PP_ORDER_999',
+      payerID: 'PAYER_555',
+    });
+
+    assert.equal(originalApproveCalled, true);
+    assert.ok(recordedSuccess);
+    assert.equal(recordedSuccess.orderId, 'PP_ORDER_999');
+    assert.equal(recordedSuccess.payerId, 'PAYER_555');
+  });
+});

package/test/params.test.js

@@ -0,0 +1,51 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractMarketingParams } from '../src/tracking/params.js';
+import { configManager } from '../src/config/index.js';
+
+describe('Marketing Parameters Extraction Module', () => {
+  it('extracts standard UTM parameters', () => {
+    const search = '?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale&utm_term=shoes&utm_content=banner_top';
+    const result = extractMarketingParams(search);
+
+    assert.equal(result.utm.source, 'google');
+    assert.equal(result.utm.medium, 'cpc');
+    assert.equal(result.utm.campaign, 'summer_sale');
+    assert.equal(result.utm.term, 'shoes');
+    assert.equal(result.utm.content, 'banner_top');
+  });
+
+  it('falls back to short query parameters if utm_ prefix is omitted', () => {
+    const search = '?source=newsletter&medium=email&campaign=welcome_flow';
+    const result = extractMarketingParams(search);
+
+    assert.equal(result.utm.source, 'newsletter');
+    assert.equal(result.utm.medium, 'email');
+    assert.equal(result.utm.campaign, 'welcome_flow');
+  });
+
+  it('extracts multi-platform ad click IDs', () => {
+    const search = '?gclid=test_gclid_123&fbclid=test_fbclid_456&ttclid=test_ttclid_789&msclkid=test_msclkid_101&wbraid=test_wbraid_202&li_fat_id=test_linkedin_303';
+    const result = extractMarketingParams(search);
+
+    assert.equal(result.clickIds.gclid, 'test_gclid_123');
+    assert.equal(result.clickIds.fbclid, 'test_fbclid_456');
+    assert.equal(result.clickIds.ttclid, 'test_ttclid_789');
+    assert.equal(result.clickIds.msclkid, 'test_msclkid_101');
+    assert.equal(result.clickIds.wbraid, 'test_wbraid_202');
+    assert.equal(result.clickIds.li_fat_id, 'test_linkedin_303');
+  });
+
+  it('extracts configured custom query parameters', () => {
+    configManager.init({
+      customParams: ['affiliate_id', 'promo_code'],
+    });
+
+    const search = '?affiliate_id=aff_9988&promo_code=SAVE20&other=ignored';
+    const result = extractMarketingParams(search);
+
+    assert.equal(result.custom.affiliate_id, 'aff_9988');
+    assert.equal(result.custom.promo_code, 'SAVE20');
+    assert.equal(result.custom.other, undefined);
+  });
+});

package/test/referrer.test.js

@@ -0,0 +1,41 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isInternalReferrer, parseReferrer } from '../src/tracking/referrer.js';
+
+describe('Referrer Parsing and Classification Module', () => {
+  it('identifies internal referrals correctly', () => {
+    assert.equal(isInternalReferrer('https://mystore.com/catalog', 'mystore.com'), true);
+    assert.equal(isInternalReferrer('https://shop.mystore.com/cart', 'mystore.com'), true);
+    assert.equal(isInternalReferrer('https://google.com', 'mystore.com'), false);
+    assert.equal(isInternalReferrer('', 'mystore.com'), false);
+  });
+
+  it('classifies organic search engines', () => {
+    const googleResult = parseReferrer('https://www.google.com/search?q=shoes', 'mystore.com');
+    assert.equal(googleResult.channel, 'organic_search');
+    assert.equal(googleResult.detectedSource, 'google');
+    assert.equal(googleResult.detectedMedium, 'organic');
+
+    const bingResult = parseReferrer('https://www.bing.com/', 'mystore.com');
+    assert.equal(bingResult.channel, 'organic_search');
+    assert.equal(bingResult.detectedSource, 'bing');
+  });
+
+  it('classifies social networks', () => {
+    const fbResult = parseReferrer('https://l.facebook.com/', 'mystore.com');
+    assert.equal(fbResult.channel, 'social');
+    assert.equal(fbResult.detectedSource, 'facebook');
+    assert.equal(fbResult.detectedMedium, 'social');
+
+    const redditResult = parseReferrer('https://www.reddit.com/r/deals', 'mystore.com');
+    assert.equal(redditResult.channel, 'social');
+    assert.equal(redditResult.detectedSource, 'reddit');
+  });
+
+  it('filters out internal referrers and marks channel as internal', () => {
+    const internalResult = parseReferrer('https://mystore.com/products', 'mystore.com');
+    assert.equal(internalResult.isInternal, true);
+    assert.equal(internalResult.referrer, null);
+    assert.equal(internalResult.channel, 'internal');
+  });
+});

package/test/session.test.js

@@ -0,0 +1,112 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  shouldSendTouch,
+  saveSuccessfulTouch,
+  readTouchHistory,
+  TOUCH_HISTORY_KEY,
+  getTouchSignature,
+} from '../src/tracking/session.js';
+import { safeLocalStorage } from '../src/utils/storage.js';
+import { configManager } from '../src/config/index.js';
+
+describe('Session Tracking and Deduplication Module', () => {
+  beforeEach(() => {
+    safeLocalStorage.removeItem(TOUCH_HISTORY_KEY);
+    configManager.init({
+      sessionWindowMs: 30 * 60 * 1000,
+    });
+  });
+
+  it('allows the initial touch when history is empty', () => {
+    const payload = {
+      visitorId: 'vis-1',
+      source: 'google',
+      medium: 'cpc',
+      campaign: 'shoes',
+    };
+    assert.equal(shouldSendTouch(payload, []), true);
+  });
+
+  it('rejects duplicate touch with the same signature within the session window', () => {
+    const payload = {
+      visitorId: 'vis-1',
+      source: 'google',
+      medium: 'cpc',
+      campaign: 'shoes',
+      landingPage: 'https://mystore.com/shoes',
+    };
+
+    const history = [
+      {
+        payload,
+        response: { id: 't-1', visitorId: 'vis-1', channel: 'cpc', touchedAt: '' },
+        recordedAt: Date.now() - 5000, // 5 seconds ago
+      },
+    ];
+
+    assert.equal(shouldSendTouch(payload, history), false);
+  });
+
+  it('protects paid marketing attribution from being overwritten by a direct navigation in the same session', () => {
+    const adPayload = {
+      visitorId: 'vis-1',
+      source: 'facebook',
+      medium: 'cpc',
+      campaign: 'retargeting',
+      fbclid: 'fb_123',
+    };
+
+    const directPayload = {
+      visitorId: 'vis-1',
+      source: null,
+      medium: null,
+      campaign: null,
+    };
+
+    const history = [
+      {
+        payload: adPayload,
+        response: { id: 't-1', visitorId: 'vis-1', channel: 'cpc', touchedAt: '' },
+        recordedAt: Date.now() - 60000, // 1 min ago
+      },
+    ];
+
+    // Direct navigation should not overwrite the active paid touch
+    assert.equal(shouldSendTouch(directPayload, history), false);
+  });
+
+  it('allows a new touch when session window has expired', () => {
+    const payload = {
+      visitorId: 'vis-1',
+      source: 'google',
+      medium: 'cpc',
+    };
+
+    const history = [
+      {
+        payload,
+        response: { id: 't-1', visitorId: 'vis-1', channel: 'cpc', touchedAt: '' },
+        recordedAt: Date.now() - (35 * 60 * 1000), // 35 minutes ago (> 30 min window)
+      },
+    ];
+
+    assert.equal(shouldSendTouch(payload, history), true);
+  });
+
+  it('limits saved history to 50 items and purges older records (FIFO)', () => {
+    for (let i = 0; i < 60; i++) {
+      saveSuccessfulTouch({
+        payload: { visitorId: 'vis-1', index: i },
+        response: { id: `touch-${i}`, visitorId: 'vis-1', channel: 'direct', touchedAt: '' },
+        recordedAt: Date.now() + i,
+      });
+    }
+
+    const history = readTouchHistory();
+    assert.equal(history.length, 50);
+    // Oldest 10 items (0..9) should be dropped, item 10 should be the first
+    assert.equal(history[0].payload.index, 10);
+    assert.equal(history[49].payload.index, 59);
+  });
+});

package/test/visitor.test.js

@@ -0,0 +1,35 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { generateUUID, getVisitorId, setVisitorId, VISITOR_ID_KEY } from '../src/tracking/visitor.js';
+import { safeLocalStorage } from '../src/utils/storage.js';
+
+describe('Visitor Tracking Module', () => {
+  beforeEach(() => {
+    safeLocalStorage.removeItem(VISITOR_ID_KEY);
+    // Reset memory cache if any
+    setVisitorId('');
+  });
+
+  it('generates a valid UUIDv4 string', () => {
+    const uuid = generateUUID();
+    assert.equal(typeof uuid, 'string');
+    assert.match(uuid, /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+  });
+
+  it('generates and persists visitorId', () => {
+    const id1 = getVisitorId();
+    assert.ok(id1);
+    assert.equal(typeof id1, 'string');
+
+    // Calling again returns the exact same visitorId
+    const id2 = getVisitorId();
+    assert.equal(id1, id2);
+  });
+
+  it('allows explicit override with setVisitorId', () => {
+    const customId = 'custom-visitor-12345';
+    setVisitorId(customId);
+    assert.equal(getVisitorId(), customId);
+    assert.equal(safeLocalStorage.getItem(VISITOR_ID_KEY), customId);
+  });
+});