feat(audience): scaffold @imtbl/pixel package with attribution, loader, and snippet

Add the pixel package scaffold and three self-contained modules that have
no dependency on PR #2824. The package builds to a single IIFE bundle
(dist/imtbl.js) targeting <10KB gzipped (currently 823 bytes).

Modules:
- attribution: UTM params, ad click IDs, referrer, landing page (session-cached)
- loader: command-queue pattern (window.__imtbl) with pre-load replay
- snippet: embeddable <script> tag generator for studio integration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bkbooth

packages/audience/pixel/.eslintrc.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  extends: ['../../../.eslintrc'],
+  parserOptions: {
+    project: './tsconfig.eslint.json',
+    tsconfigRootDir: __dirname,
+  },
+  rules: {
+    'no-underscore-dangle': ['error', { allow: ['__imtbl', '_loaded'] }],
+  },
+};

packages/audience/pixel/jest.config.ts

@@ -0,0 +1,13 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  roots: ['<rootDir>/src'],
+  moduleDirectories: ['node_modules', 'src'],
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;

packages/audience/pixel/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@imtbl/pixel",
+  "description": "Immutable Tracking Pixel — drop-in JavaScript snippet for device fingerprint, page view, and attribution data",
+  "version": "0.0.0",
+  "author": "Immutable",
+  "private": true,
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "dependencies": {},
+  "devDependencies": {
+    "@swc/core": "^1.4.2",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.12",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.4.3",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "exports": {
+    "development": {
+      "types": "./src/index.ts",
+      "default": "./dist/imtbl.js"
+    },
+    "default": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/imtbl.js"
+    }
+  },
+  "files": ["dist"],
+  "main": "dist/imtbl.js",
+  "homepage": "https://github.com/immutable/ts-immutable-sdk#readme",
+  "repository": "immutable/ts-immutable-sdk.git",
+  "scripts": {
+    "build": "pnpm transpile && pnpm typegen",
+    "transpile": "tsup",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "lint": "eslint ./src --ext .ts --max-warnings=0",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --customConditions default --noEmit"
+  },
+  "type": "module",
+  "types": "./dist/types/index.d.ts"
+}

packages/audience/pixel/src/attribution.test.ts

@@ -0,0 +1,101 @@
+import { collectAttribution, clearAttribution } from './attribution';
+
+const STORAGE_KEY = '__imtbl_attribution';
+
+beforeEach(() => {
+  sessionStorage.clear();
+  jest.restoreAllMocks();
+});
+
+function setLocation(url: string) {
+  Object.defineProperty(window, 'location', {
+    value: new URL(url),
+    writable: true,
+    configurable: true,
+  });
+}
+
+describe('collectAttribution', () => {
+  it('parses UTM parameters from the URL', () => {
+    setLocation(
+      'https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring&utm_content=banner&utm_term=nft',
+    );
+
+    const result = collectAttribution();
+    expect(result.utm_source).toBe('google');
+    expect(result.utm_medium).toBe('cpc');
+    expect(result.utm_campaign).toBe('spring');
+    expect(result.utm_content).toBe('banner');
+    expect(result.utm_term).toBe('nft');
+  });
+
+  it('parses ad network click IDs', () => {
+    setLocation(
+      'https://example.com/?gclid=abc123&fbclid=fb456&ttclid=tt789&msclkid=ms000',
+    );
+
+    const result = collectAttribution();
+    expect(result.gclid).toBe('abc123');
+    expect(result.fbclid).toBe('fb456');
+    expect(result.ttclid).toBe('tt789');
+    expect(result.msclkid).toBe('ms000');
+  });
+
+  it('captures referrer and landing page', () => {
+    setLocation('https://game.example.com/landing');
+    Object.defineProperty(document, 'referrer', {
+      value: 'https://google.com/search?q=nft',
+      configurable: true,
+    });
+
+    const result = collectAttribution();
+    expect(result.referrer).toBe('https://google.com/search?q=nft');
+    expect(result.landing_page).toBe('https://game.example.com/landing');
+  });
+
+  it('caches in sessionStorage and returns cached on second call', () => {
+    setLocation('https://example.com/?utm_source=google');
+
+    const first = collectAttribution();
+    expect(first.utm_source).toBe('google');
+
+    // Change URL — should still return cached value
+    setLocation('https://example.com/?utm_source=facebook');
+    const second = collectAttribution();
+    expect(second.utm_source).toBe('google');
+  });
+
+  it('returns empty attribution when no params are present', () => {
+    setLocation('https://example.com/');
+    Object.defineProperty(document, 'referrer', { value: '', configurable: true });
+
+    const result = collectAttribution();
+    expect(result.utm_source).toBeUndefined();
+    expect(result.gclid).toBeUndefined();
+    expect(result.referrer).toBeUndefined();
+  });
+
+  it('handles sessionStorage being unavailable', () => {
+    setLocation('https://example.com/?utm_source=twitter');
+    jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('storage disabled');
+    });
+    jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new Error('storage disabled');
+    });
+
+    const result = collectAttribution();
+    expect(result.utm_source).toBe('twitter');
+  });
+});
+
+describe('clearAttribution', () => {
+  it('removes cached attribution from sessionStorage', () => {
+    setLocation('https://example.com/?utm_source=google');
+    collectAttribution();
+    expect(sessionStorage.getItem(STORAGE_KEY)).not.toBeNull();
+
+    clearAttribution();
+    expect(sessionStorage.getItem(STORAGE_KEY)).toBeNull();
+  });
+});

packages/audience/pixel/src/attribution.ts

@@ -0,0 +1,98 @@
+const UTM_PARAMS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_content',
+  'utm_term',
+] as const;
+
+const CLICK_ID_PARAMS = [
+  'gclid',
+  'fbclid',
+  'ttclid',
+  'msclkid',
+] as const;
+
+const STORAGE_KEY = '__imtbl_attribution';
+
+export interface Attribution {
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  gclid?: string;
+  fbclid?: string;
+  ttclid?: string;
+  msclkid?: string;
+  referrer?: string;
+  landing_page?: string;
+}
+
+type AttributionKey = keyof Attribution;
+
+function parseParams(url: string): Attribution {
+  let params: URLSearchParams;
+  try {
+    params = new URL(url).searchParams;
+  } catch {
+    return {};
+  }
+
+  const result: Attribution = {};
+  for (const key of [...UTM_PARAMS, ...CLICK_ID_PARAMS]) {
+    const value = params.get(key);
+    if (value) {
+      result[key as AttributionKey] = value;
+    }
+  }
+  return result;
+}
+
+function loadFromStorage(): Attribution | null {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as Attribution) : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveToStorage(attribution: Attribution): void {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(attribution));
+  } catch {
+    // sessionStorage may be unavailable (private browsing, storage full)
+  }
+}
+
+export function collectAttribution(): Attribution {
+  const cached = loadFromStorage();
+  if (cached) return cached;
+
+  const urlParams = typeof window !== 'undefined' && window.location
+    ? parseParams(window.location.href)
+    : {};
+
+  const referrer = typeof document !== 'undefined' ? document.referrer || undefined : undefined;
+  const landingPage = typeof window !== 'undefined' && window.location
+    ? window.location.href
+    : undefined;
+
+  const attribution: Attribution = {
+    ...urlParams,
+    referrer,
+    landing_page: landingPage,
+  };
+
+  saveToStorage(attribution);
+  return attribution;
+}
+
+export function clearAttribution(): void {
+  try {
+    sessionStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // noop
+  }
+}

packages/audience/pixel/src/index.ts

@@ -0,0 +1,8 @@
+export { collectAttribution, clearAttribution } from './attribution';
+export type { Attribution } from './attribution';
+
+export { createLoader } from './loader';
+export type { Command, ImtblGlobal } from './loader';
+
+export { generateSnippet } from './snippet';
+export type { SnippetOptions } from './snippet';

packages/audience/pixel/src/loader.test.ts

@@ -0,0 +1,79 @@
+import { createLoader, Command } from './loader';
+
+beforeEach(() => {
+  delete (window as Record<string, unknown>).__imtbl;
+});
+
+describe('createLoader', () => {
+  it('installs on window.__imtbl', () => {
+    const handler = jest.fn();
+    const loader = createLoader(handler);
+
+    expect((window as Record<string, unknown>).__imtbl).toBe(loader);
+    expect(loader._loaded).toBe(true);
+  });
+
+  it('forwards push() calls to the handler', () => {
+    const handler = jest.fn();
+    const loader = createLoader(handler);
+
+    loader.push(['init', { key: 'pk_123' }]);
+    loader.push(['identify', 'user-1']);
+
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenCalledWith(['init', { key: 'pk_123' }]);
+    expect(handler).toHaveBeenCalledWith(['identify', 'user-1']);
+  });
+
+  it('replays queued commands from the stub array', () => {
+    // Simulate the snippet having pushed commands before the script loaded
+    const stub: Command[] = [
+      ['init', { key: 'pk_abc' }],
+      ['consent', 'anonymous'],
+    ];
+    (window as Record<string, unknown>).__imtbl = stub;
+
+    const handler = jest.fn();
+    createLoader(handler);
+
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenNthCalledWith(1, ['init', { key: 'pk_abc' }]);
+    expect(handler).toHaveBeenNthCalledWith(2, ['consent', 'anonymous']);
+  });
+
+  it('replays queued commands then handles new pushes', () => {
+    (window as Record<string, unknown>).__imtbl = [['init', { key: 'pk_1' }]];
+
+    const handler = jest.fn();
+    const loader = createLoader(handler);
+
+    // Queued command replayed
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // New command via push
+    loader.push(['identify', 'user-2']);
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenLastCalledWith(['identify', 'user-2']);
+  });
+
+  it('handles empty window.__imtbl gracefully', () => {
+    (window as Record<string, unknown>).__imtbl = [];
+    const handler = jest.fn();
+    createLoader(handler);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('handles undefined window.__imtbl gracefully', () => {
+    const handler = jest.fn();
+    createLoader(handler);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('supports multiple commands in a single push call', () => {
+    const handler = jest.fn();
+    const loader = createLoader(handler);
+
+    loader.push(['init', { key: 'pk_1' }], ['consent', 'full']);
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+});

packages/audience/pixel/src/loader.ts

@@ -0,0 +1,37 @@
+export type Command = [string, ...unknown[]];
+
+export interface ImtblGlobal {
+  push: (...commands: Command[]) => void;
+  _loaded: boolean;
+}
+
+type CommandHandler = (command: Command) => void;
+
+export function createLoader(handler: CommandHandler): ImtblGlobal {
+  const win = typeof window !== 'undefined' ? window : undefined;
+  const existing = win ? (win as unknown as Record<string, unknown>).__imtbl : undefined;
+
+  // Replay any commands that were queued before the script loaded
+  const queued: Command[] = Array.isArray(existing) ? (existing as Command[]) : [];
+
+  const loader: ImtblGlobal = {
+    push: (...commands: Command[]) => {
+      for (const cmd of commands) {
+        handler(cmd);
+      }
+    },
+    _loaded: true,
+  };
+
+  // Install on window
+  if (win) {
+    (win as unknown as Record<string, unknown>).__imtbl = loader;
+  }
+
+  // Replay queued commands in order
+  for (const cmd of queued) {
+    handler(cmd);
+  }
+
+  return loader;
+}