feat(audience): add pixel core class, consent state machine, and session cookie

Wire the pixel to audience-core now that PR #2824 has merged:

- Consent state machine: three-level (none/anonymous/full), DNT/GPC detection,
  queue purge on downgrade to none, userId strip on downgrade to anonymous,
  fire-and-forget PUT to /v1/audience/tracking-consent
- Session cookie: _imtbl_sid with 30-min rolling expiry
- Pixel class: init creates MessageQueue with storagePrefix isolation,
  auto-fires PageMessage with attribution context, supports identify at
  full consent, setConsent, and destroy
- Build config: resolves audience-core from source via tsup alias for
  tree-shaken self-contained IIFE bundle (8.04 KB raw / 3.2 KB gzipped)
- Metrics stub: no-op stubs so the pixel bundle doesn't ship internal telemetry

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

Author: bkbooth

packages/audience/pixel/jest.config.ts

@@ -3,6 +3,7 @@ import type { Config } from 'jest';
 const config: Config = {
   roots: ['<rootDir>/src'],
   moduleDirectories: ['node_modules', 'src'],
+  moduleNameMapper: { '^@imtbl/(.*)$': '<rootDir>/../../../node_modules/@imtbl/$1/src' },
   testEnvironment: 'jsdom',
   transform: {
     '^.+\\.(t|j)sx?$': '@swc/jest',

packages/audience/pixel/package.json

@@ -5,7 +5,9 @@
   "author": "Immutable",
   "private": true,
   "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
-  "dependencies": {},
+  "dependencies": {
+    "@imtbl/audience-core": "workspace:*"
+  },
   "devDependencies": {
     "@swc/core": "^1.4.2",
     "@swc/jest": "^0.2.37",
@@ -33,10 +35,10 @@
   "scripts": {
     "build": "pnpm transpile && pnpm typegen",
     "transpile": "tsup",
-    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "typegen": "tsc --customConditions development --emitDeclarationOnly --outDir dist/types",
     "lint": "eslint ./src --ext .ts --max-warnings=0",
     "test": "jest --passWithNoTests",
-    "typecheck": "tsc --customConditions default --noEmit"
+    "typecheck": "tsc --customConditions development --noEmit"
   },
   "type": "module",
   "types": "./dist/types/index.d.ts"

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

@@ -0,0 +1,122 @@
+import { createConsentManager } from './consent';
+
+// Mock audience-core
+jest.mock('@imtbl/audience-core', () => ({
+  httpSend: jest.fn().mockResolvedValue(true),
+  CONSENT_PATH: '/v1/audience/tracking-consent',
+  getBaseUrl: jest.fn().mockReturnValue('https://api.dev.immutable.com'),
+}));
+
+// Mock fetch globally
+const mockFetch = jest.fn().mockResolvedValue({ ok: true });
+global.fetch = mockFetch;
+
+function createMockQueue() {
+  return {
+    purge: jest.fn(),
+    transform: jest.fn(),
+    enqueue: jest.fn(),
+    flush: jest.fn(),
+    flushUnload: jest.fn(),
+    start: jest.fn(),
+    stop: jest.fn(),
+    destroy: jest.fn(),
+    clear: jest.fn(),
+    get length() { return 0; },
+  } as any;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('createConsentManager', () => {
+  it('defaults to none when no initial level provided', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev');
+    expect(manager.level).toBe('none');
+  });
+
+  it('uses the initial level when provided', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'anonymous');
+    expect(manager.level).toBe('anonymous');
+  });
+
+  it('upgrades consent without modifying queue', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'none');
+
+    manager.setLevel('anonymous');
+    expect(manager.level).toBe('anonymous');
+    expect(queue.purge).not.toHaveBeenCalled();
+    expect(queue.transform).not.toHaveBeenCalled();
+  });
+
+  it('purges queue on downgrade to none', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'full');
+
+    manager.setLevel('none');
+    expect(manager.level).toBe('none');
+    expect(queue.purge).toHaveBeenCalledWith(expect.any(Function));
+
+    // Verify the purge predicate matches all messages
+    const purgeFn = queue.purge.mock.calls[0][0];
+    expect(purgeFn({ type: 'page' })).toBe(true);
+  });
+
+  it('strips userId on downgrade from full to anonymous', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'full');
+
+    manager.setLevel('anonymous');
+    expect(manager.level).toBe('anonymous');
+    expect(queue.transform).toHaveBeenCalledWith(expect.any(Function));
+
+    // Verify the transform strips userId
+    const transformFn = queue.transform.mock.calls[0][0];
+    const withUserId = { type: 'page', userId: 'u-1', anonymousId: 'a-1' };
+    const result = transformFn(withUserId);
+    expect(result.userId).toBeUndefined();
+    expect(result.anonymousId).toBe('a-1');
+  });
+
+  it('fires PUT to consent endpoint on level change', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'none');
+
+    manager.setLevel('anonymous');
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.dev.immutable.com/v1/audience/tracking-consent',
+      expect.objectContaining({
+        method: 'PUT',
+        headers: expect.objectContaining({
+          'Content-Type': 'application/json',
+          'x-immutable-publishable-key': 'pk_test',
+        }),
+      }),
+    );
+  });
+
+  it('does nothing when setting the same level', () => {
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev', 'anonymous');
+
+    manager.setLevel('anonymous');
+    expect(queue.purge).not.toHaveBeenCalled();
+    expect(queue.transform).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('respects DNT by defaulting to none', () => {
+    Object.defineProperty(navigator, 'doNotTrack', { value: '1', configurable: true });
+
+    const queue = createMockQueue();
+    const manager = createConsentManager(queue, 'pk_test', 'anon-1', 'dev');
+    expect(manager.level).toBe('none');
+
+    Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
+  });
+});

packages/audience/pixel/src/consent.ts

@@ -0,0 +1,87 @@
+import type {
+  ConsentLevel, Message, Environment, MessageQueue,
+} from '@imtbl/audience-core';
+import { CONSENT_PATH, getBaseUrl } from '@imtbl/audience-core';
+
+export interface ConsentManager {
+  level: ConsentLevel;
+  setLevel(next: ConsentLevel): void;
+}
+
+function detectDoNotTrack(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  // DNT header
+  if (navigator.doNotTrack === '1') return true;
+  // Global Privacy Control
+  if ((navigator as unknown as Record<string, unknown>).globalPrivacyControl === true) return true;
+  return false;
+}
+
+/**
+ * Create a consent state machine.
+ *
+ * - Default level is `'none'` (no collection).
+ * - If DNT or GPC is detected and no explicit consent is provided, stays `'none'`.
+ * - On downgrade (e.g. full → anonymous), strips `userId` from queued messages.
+ * - On downgrade to `'none'`, purges the queue entirely.
+ * - Fires PUT to `/v1/audience/tracking-consent` on every state change.
+ */
+export function createConsentManager(
+  queue: MessageQueue,
+  publishableKey: string,
+  anonymousId: string,
+  environment: Environment,
+  initialLevel?: ConsentLevel,
+): ConsentManager {
+  const dntDetected = detectDoNotTrack();
+  let current: ConsentLevel = initialLevel ?? (dntDetected ? 'none' : 'none');
+
+  const LEVELS: Record<ConsentLevel, number> = { none: 0, anonymous: 1, full: 2 };
+
+  function notifyBackend(level: ConsentLevel): void {
+    const url = `${getBaseUrl(environment)}${CONSENT_PATH}`;
+    const payload = { anonymousId, consentLevel: level };
+    fetch(url, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-immutable-publishable-key': publishableKey,
+      },
+      body: JSON.stringify(payload),
+      keepalive: true,
+    }).catch(() => {});
+  }
+
+  const manager: ConsentManager = {
+    get level() {
+      return current;
+    },
+
+    setLevel(next: ConsentLevel): void {
+      if (next === current) return;
+
+      const isDowngrade = LEVELS[next] < LEVELS[current];
+
+      if (isDowngrade) {
+        if (next === 'none') {
+          // Purge all queued messages
+          queue.purge(() => true);
+        } else if (next === 'anonymous') {
+          // Strip userId from queued messages
+          queue.transform((msg: Message) => {
+            if ('userId' in msg) {
+              const { userId, ...rest } = msg;
+              return rest as Message;
+            }
+            return msg;
+          });
+        }
+      }
+
+      current = next;
+      notifyBackend(next);
+    },
+  };
+
+  return manager;
+}

packages/audience/pixel/src/index.ts

@@ -1,3 +1,11 @@
+export { Pixel } from './pixel';
+export type { PixelInitOptions } from './pixel';
+
+export { createConsentManager } from './consent';
+export type { ConsentManager } from './consent';
+
+export { getOrCreateSessionId, getSessionId } from './session';
+
 export { collectAttribution, clearAttribution } from './attribution';
 export type { Attribution } from './attribution';