Test: Attribution prototype

pkg/attribution/jest.config.ts

@@ -0,0 +1,25 @@
+import type { Config } from 'jest';
+import { execSync } from 'child_process';
+import { name } from './package.json';
+
+const rootDirs = execSync(`pnpm --filter ${name}... exec pwd`)
+  .toString()
+  .split('\n')
+  .filter(Boolean)
+  .map((dir) => `${dir}/dist`);
+
+const config: Config = {
+  clearMocks: true,
+  roots: ['<rootDir>/src', ...rootDirs],
+  coverageProvider: 'v8',
+  moduleDirectories: ['node_modules', 'src'],
+  moduleNameMapper: { '^@imtbl/(.*)$': '<rootDir>/../../node_modules/@imtbl/$1/src' },
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;
+

pkg/attribution/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@imtbl/attribution",
+  "description": "Minimal marketing attribution package for web - replacement for AppsFlyer/Adjust",
+  "version": "0.0.0",
+  "author": "Immutable",
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "dependencies": {},
+  "devDependencies": {
+    "@swc/core": "^1.3.36",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.4.3",
+    "@types/node": "^18.14.2",
+    "@typescript-eslint/eslint-plugin": "^5.57.1",
+    "@typescript-eslint/parser": "^5.57.1",
+    "eslint": "^8.40.0",
+    "jest": "^29.4.3",
+    "jest-environment-jsdom": "^29.4.3",
+    "prettier": "^2.8.7",
+    "ts-node": "^10.9.1",
+    "tsup": "8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "exports": {
+    "development": {
+      "types": "./src/index.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    },
+    "default": {
+      "types": "./dist/types/index.d.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/immutable/ts-immutable-sdk#readme",
+  "license": "Apache-2.0",
+  "main": "dist/node/index.cjs",
+  "module": "dist/node/index.js",
+  "browser": "dist/browser/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "immutable/ts-immutable-sdk.git",
+  "scripts": {
+    "build": "pnpm transpile && pnpm typegen",
+    "transpile": "tsup src/index.ts --config ../../tsup.config.js",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "pack:root": "pnpm pack --pack-destination $(dirname $(pnpm root -w))",
+    "lint": "eslint ./src --ext .ts,.jsx,.tsx --max-warnings=0",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --customConditions default --noEmit --jsx preserve"
+  },
+  "type": "module",
+  "types": "./dist/types/index.d.ts"
+}
+

pkg/attribution/src/attribution.ts

@@ -0,0 +1,147 @@
+/**
+ * Attribution data extracted from URL parameters and referrer
+ */
+export interface AttributionData {
+  /** Campaign source (e.g., 'google', 'facebook') */
+  source?: string;
+  /** Campaign medium (e.g., 'cpc', 'email') */
+  medium?: string;
+  /** Campaign name */
+  campaign?: string;
+  /** Campaign term (keywords) */
+  term?: string;
+  /** Campaign content (A/B testing) */
+  content?: string;
+  /** Referrer URL */
+  referrer?: string;
+  /** Landing page URL */
+  landingPage?: string;
+  /** First touch timestamp */
+  firstTouchTime?: number;
+  /** Last touch timestamp */
+  lastTouchTime?: number;
+  /** Custom attribution parameters */
+  custom?: Record<string, string>;
+}
+
+/**
+ * Parse URL parameters for attribution data
+ */
+export function parseAttributionFromUrl(url?: string): AttributionData {
+  const urlObj = typeof window !== 'undefined' && !url
+    ? new URL(window.location.href)
+    : url
+      ? new URL(url, typeof window !== 'undefined' ? window.location.origin : 'https://example.com')
+      : null;
+
+  if (!urlObj) {
+    return {};
+  }
+
+  const params = urlObj.searchParams;
+  const attribution: AttributionData = {
+    landingPage: urlObj.href,
+    firstTouchTime: Date.now(),
+    lastTouchTime: Date.now(),
+    custom: {},
+  };
+
+  // Standard UTM parameters
+  const utmSource = params.get('utm_source');
+  const utmMedium = params.get('utm_medium');
+  const utmCampaign = params.get('utm_campaign');
+  const utmTerm = params.get('utm_term');
+  const utmContent = params.get('utm_content');
+
+  if (utmSource) attribution.source = utmSource;
+  if (utmMedium) attribution.medium = utmMedium;
+  if (utmCampaign) attribution.campaign = utmCampaign;
+  if (utmTerm) attribution.term = utmTerm;
+  if (utmContent) attribution.content = utmContent;
+
+  // AppsFlyer parameters (af_*)
+  const afSource = params.get('af_source') || params.get('pid');
+  const afMedium = params.get('af_medium') || params.get('c');
+  const afCampaign = params.get('af_campaign') || params.get('af_c');
+  const afAdset = params.get('af_adset') || params.get('af_adset_id');
+  const afAd = params.get('af_ad') || params.get('af_ad_id');
+
+  if (afSource && !attribution.source) attribution.source = afSource;
+  if (afMedium && !attribution.medium) attribution.medium = afMedium;
+  if (afCampaign && !attribution.campaign) attribution.campaign = afCampaign;
+  if (afAdset) attribution.custom = { ...attribution.custom, af_adset: afAdset };
+  if (afAd) attribution.custom = { ...attribution.custom, af_ad: afAd };
+
+  // Adjust parameters (adjust_*)
+  const adjustSource = params.get('adjust_source') || params.get('network');
+  const adjustCampaign = params.get('adjust_campaign') || params.get('campaign');
+  const adjustAdgroup = params.get('adjust_adgroup') || params.get('adgroup');
+  const adjustCreative = params.get('adjust_creative') || params.get('creative');
+
+  if (adjustSource && !attribution.source) attribution.source = adjustSource;
+  if (adjustCampaign && !attribution.campaign) attribution.campaign = adjustCampaign;
+  if (adjustAdgroup) attribution.custom = { ...attribution.custom, adjust_adgroup: adjustAdgroup };
+  if (adjustCreative) attribution.custom = { ...attribution.custom, adjust_creative: adjustCreative };
+
+  // Referrer
+  if (typeof document !== 'undefined' && document.referrer) {
+    try {
+      const referrerUrl = new URL(document.referrer);
+      attribution.referrer = referrerUrl.hostname;
+    } catch {
+      attribution.referrer = document.referrer;
+    }
+  }
+
+  // Collect any remaining custom parameters
+  for (const [key, value] of params.entries()) {
+    if (
+      !key.startsWith('utm_') &&
+      !key.startsWith('af_') &&
+      !key.startsWith('adjust_') &&
+      key !== 'pid' &&
+      key !== 'c' &&
+      key !== 'network' &&
+      key !== 'campaign' &&
+      key !== 'adgroup' &&
+      key !== 'creative'
+    ) {
+      attribution.custom = attribution.custom || {};
+      attribution.custom[key] = value;
+    }
+  }
+
+  return attribution;
+}
+
+/**
+ * Merge new attribution data with existing data
+ */
+export function mergeAttributionData(
+  existing: AttributionData | null,
+  incoming: AttributionData,
+): AttributionData {
+  if (!existing) {
+    return incoming;
+  }
+
+  return {
+    ...existing,
+    // Keep first touch time from existing
+    firstTouchTime: existing.firstTouchTime || incoming.firstTouchTime,
+    // Update last touch time
+    lastTouchTime: incoming.lastTouchTime || Date.now(),
+    // Merge custom parameters
+    custom: {
+      ...existing.custom,
+      ...incoming.custom,
+    },
+    // Prefer existing source/medium/campaign unless incoming has values
+    source: incoming.source || existing.source,
+    medium: incoming.medium || existing.medium,
+    campaign: incoming.campaign || existing.campaign,
+    term: incoming.term || existing.term,
+    content: incoming.content || existing.content,
+  };
+}
+

pkg/attribution/src/deeplink.ts

@@ -0,0 +1,87 @@
+import type { AttributionData } from './attribution';
+
+/**
+ * Deep link data extracted from URL parameters
+ */
+export interface DeepLinkData {
+  /** Deep link path (e.g., '/product/123') */
+  path?: string;
+  /** Deep link value (alternative to path) */
+  value?: string;
+  /** All deep link parameters */
+  params?: Record<string, string>;
+  /** Full deep link URL */
+  url?: string;
+}
+
+/**
+ * Common deep link parameter names used by AppsFlyer/Adjust
+ */
+const DEEP_LINK_PARAM_NAMES = [
+  'deep_link',
+  'deep_link_value',
+  'deep_link_path',
+  'af_dp', // AppsFlyer deep link path
+  'af_dl', // AppsFlyer deep link value
+  'af_web_dp', // AppsFlyer web deep link path
+  'adjust_deeplink', // Adjust deep link
+  'deeplink',
+  'deeplink_path',
+  'deeplink_value',
+];
+
+/**
+ * Extract deep link data from attribution data
+ */
+export function extractDeepLinkData(attribution: AttributionData | null): DeepLinkData | null {
+  if (!attribution || !attribution.custom) {
+    return null;
+  }
+
+  const deepLink: DeepLinkData = {
+    params: {},
+  };
+
+  // Check for common deep link parameter names
+  for (const paramName of DEEP_LINK_PARAM_NAMES) {
+    const value = attribution.custom[paramName];
+    if (value) {
+      if (paramName.includes('path') || paramName === 'af_dp' || paramName === 'af_web_dp') {
+        deepLink.path = value;
+      } else if (paramName.includes('value') || paramName === 'af_dl') {
+        deepLink.value = value;
+      } else {
+        // Generic deep link parameter
+        deepLink.path = deepLink.path || value;
+        deepLink.value = deepLink.value || value;
+      }
+    }
+  }
+
+  // If no standard deep link params found, check for any custom params
+  // that might be deep link related
+  if (!deepLink.path && !deepLink.value && Object.keys(attribution.custom).length > 0) {
+    // Use first custom param as potential deep link
+    const firstParam = Object.entries(attribution.custom)[0];
+    if (firstParam) {
+      deepLink.value = firstParam[1];
+      deepLink.params = { [firstParam[0]]: firstParam[1] };
+    }
+  } else {
+    // Include all custom params as deep link params
+    deepLink.params = { ...attribution.custom };
+  }
+
+  // Include landing page URL if available
+  if (attribution.landingPage) {
+    deepLink.url = attribution.landingPage;
+  }
+
+  // Return null if no deep link data found
+  if (!deepLink.path && !deepLink.value && Object.keys(deepLink.params || {}).length === 0) {
+    return null;
+  }
+
+  return deepLink;
+}
+