feat(audience): scaffold @imtbl/audience-web-sdk with consent and cookies

- Package scaffold: package.json, tsconfig, eslint, jest config
- Add packages/audience/sdk and packages/audience/web to pnpm workspace
- Cookie helpers: session ID (30min rolling)
- ConsentManager: 3-tier consent, DNT/GPC detection, server sync
- Debug logger for dev mode

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

packages/audience/web/.eslintrc.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['../../../.eslintrc'],
+  parserOptions: {
+    project: './tsconfig.eslint.json',
+    tsconfigRootDir: __dirname,
+  },
+};

packages/audience/web/jest.config.ts

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

packages/audience/web/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@imtbl/audience-web-sdk",
+  "description": "Immutable Audience Web SDK — consent-aware event tracking and identity management",
+  "version": "0.0.0",
+  "author": "Immutable",
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "dependencies": {
+    "@imtbl/audience-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.4.2",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.7",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.4.3",
+    "ts-jest": "^29.1.0",
+    "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",
+  "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",
+    "transpile:cdn": "tsup --config tsup.cdn.js",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "lint": "eslint ./src --ext .ts,.jsx,.tsx --max-warnings=0",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "demo": "pnpm build && npx serve -l 3456 --cors ..",
+    "typecheck": "tsc --customConditions development --noEmit --jsx preserve"
+  },
+  "type": "module",
+  "types": "./dist/types/index.d.ts"
+}

packages/audience/web/src/config.ts

@@ -0,0 +1,6 @@
+// Web SDK-specific constants.
+// Backend endpoints and base URLs come from @imtbl/audience-core.
+
+export const LIBRARY_NAME = '@imtbl/audience-web-sdk';
+// Replaced at build time by esbuild replace plugin
+export const LIBRARY_VERSION = '__SDK_VERSION__';

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

@@ -0,0 +1,118 @@
+import { ConsentManager, detectPrivacySignal } from './consent';
+
+// Mock fetch for server sync
+const mockFetch = jest.fn().mockResolvedValue({ ok: true, json: async () => ({}) });
+global.fetch = mockFetch;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('ConsentManager', () => {
+  it('initialises with the provided consent level', () => {
+    const manager = new ConsentManager('sandbox', 'pk_test', 'anonymous', 'TestSDK');
+    expect(manager.getLevel()).toBe('anonymous');
+  });
+
+  it('calls onPurgeQueue when downgrading to none', () => {
+    const manager = new ConsentManager('sandbox', 'pk_test', 'full', 'TestSDK');
+    const onPurge = jest.fn();
+    const onClear = jest.fn();
+
+    manager.setLevel('none', 'anon-123', {
+      onPurgeQueue: onPurge,
+      onClearCookies: onClear,
+    });
+
+    expect(onPurge).toHaveBeenCalled();
+    expect(onClear).toHaveBeenCalled();
+    expect(manager.getLevel()).toBe('none');
+  });
+
+  it('calls onStripIdentity when downgrading from full to anonymous', () => {
+    const manager = new ConsentManager('sandbox', 'pk_test', 'full', 'TestSDK');
+    const onStrip = jest.fn();
+
+    manager.setLevel('anonymous', 'anon-123', { onStripIdentity: onStrip });
+
+    expect(onStrip).toHaveBeenCalled();
+    expect(manager.getLevel()).toBe('anonymous');
+  });
+
+  it('syncs consent to server via PUT on setLevel', () => {
+    const manager = new ConsentManager('sandbox', 'pk_test', 'none', 'TestSDK');
+    manager.setLevel('full', 'anon-123');
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.sandbox.immutable.com/v1/audience/tracking-consent',
+      expect.objectContaining({
+        method: 'PUT',
+        body: JSON.stringify({
+          anonymousId: 'anon-123',
+          status: 'full',
+          source: 'TestSDK',
+        }),
+      }),
+    );
+  });
+
+  describe('DNT / GPC', () => {
+    it('forces consent to none when DNT is set', () => {
+      Object.defineProperty(navigator, 'doNotTrack', { value: '1', configurable: true });
+      const manager = new ConsentManager('sandbox', 'pk_test', 'full', 'TestSDK');
+      expect(manager.getLevel()).toBe('none');
+      Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
+    });
+
+    it('forces consent to none when GPC is set', () => {
+      Object.defineProperty(navigator, 'globalPrivacyControl', { value: true, configurable: true });
+      const manager = new ConsentManager('sandbox', 'pk_test', 'anonymous', 'TestSDK');
+      expect(manager.getLevel()).toBe('none');
+      Object.defineProperty(navigator, 'globalPrivacyControl', { value: false, configurable: true });
+    });
+
+    it('blocks setLevel upgrade when DNT is active', () => {
+      Object.defineProperty(navigator, 'doNotTrack', { value: '1', configurable: true });
+      const manager = new ConsentManager('sandbox', 'pk_test', 'none', 'TestSDK');
+      manager.setLevel('full', 'anon-123');
+      expect(manager.getLevel()).toBe('none');
+      Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
+    });
+
+    it('still allows downgrade to none when DNT is active', () => {
+      const manager = new ConsentManager('sandbox', 'pk_test', 'full', 'TestSDK');
+      expect(manager.getLevel()).toBe('full');
+
+      Object.defineProperty(navigator, 'doNotTrack', { value: '1', configurable: true });
+      const onPurge = jest.fn();
+      manager.setLevel('none', 'anon-123', { onPurgeQueue: onPurge });
+      expect(manager.getLevel()).toBe('none');
+      expect(onPurge).toHaveBeenCalled();
+      Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
+    });
+
+    it('detectPrivacySignal returns false when no signals set', () => {
+      Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
+      Object.defineProperty(navigator, 'globalPrivacyControl', { value: false, configurable: true });
+      expect(detectPrivacySignal()).toBe(false);
+    });
+  });
+
+  it('fetches server consent status', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ status: 'anonymous' }),
+    });
+
+    const manager = new ConsentManager('sandbox', 'pk_test', 'none', 'TestSDK');
+    const status = await manager.fetchServerConsent('anon-123');
+
+    expect(status).toBe('anonymous');
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.sandbox.immutable.com/v1/audience/tracking-consent?anonymousId=anon-123',
+      expect.objectContaining({
+        headers: { 'x-immutable-publishable-key': 'pk_test' },
+      }),
+    );
+  });
+});

packages/audience/web/src/consent.ts

@@ -0,0 +1,128 @@
+import type {
+  ConsentLevel,
+  ConsentStatus,
+  Environment,
+} from '@imtbl/audience-core';
+import {
+  CONSENT_PATH,
+  COOKIE_NAME,
+  SESSION_COOKIE,
+  getBaseUrl,
+  isBrowser,
+  deleteCookie,
+  truncateSource,
+} from '@imtbl/audience-core';
+
+/**
+ * Check if the browser signals a Do Not Track or Global Privacy Control
+ * preference. When either is active, consent should be capped at 'none'.
+ */
+export function detectPrivacySignal(): boolean {
+  if (!isBrowser()) return false;
+  const nav = navigator as any;
+  if (nav.doNotTrack === '1' || (window as any).doNotTrack === '1') return true;
+  if (nav.globalPrivacyControl === true) return true;
+  return false;
+}
+
+export interface ConsentCallbacks {
+  onPurgeQueue?: () => void;
+  onStripIdentity?: () => void;
+  onClearCookies?: () => void;
+}
+
+export class ConsentManager {
+  private level: ConsentLevel;
+
+  private readonly baseUrl: string;
+
+  private readonly publishableKey: string;
+
+  private readonly source: string;
+
+  private readonly cookieDomain?: string;
+
+  constructor(
+    environment: Environment,
+    publishableKey: string,
+    initialConsent: ConsentLevel,
+    rawSource: string,
+    cookieDomain?: string,
+  ) {
+    this.baseUrl = getBaseUrl(environment);
+    this.publishableKey = publishableKey;
+    this.source = truncateSource(rawSource);
+    this.cookieDomain = cookieDomain;
+
+    // DNT / GPC: auto-downgrade to 'none' if browser signals tracking opt-out
+    if (detectPrivacySignal()) {
+      this.level = 'none';
+      return;
+    }
+
+    this.level = initialConsent;
+  }
+
+  getLevel(): ConsentLevel {
+    return this.level;
+  }
+
+  setLevel(
+    level: ConsentLevel,
+    anonymousId: string,
+    callbacks?: ConsentCallbacks,
+  ): void {
+    // DNT / GPC active: refuse to upgrade consent
+    if (level !== 'none' && detectPrivacySignal()) return;
+
+    const { level: previous } = this;
+    this.level = level;
+
+    // Downgrade: full/anonymous -> none — purge everything
+    if (level === 'none') {
+      callbacks?.onPurgeQueue?.();
+      callbacks?.onClearCookies?.();
+    } else if (level === 'anonymous' && previous === 'full') {
+      // Downgrade: full -> anonymous — strip PII, keep anonymous events
+      callbacks?.onStripIdentity?.();
+    }
+
+    // Sync to server (fire-and-forget)
+    this.syncToServer(anonymousId, level);
+  }
+
+  /** Fetch server-side consent status for reconciliation. */
+  async fetchServerConsent(anonymousId: string): Promise<ConsentStatus | undefined> {
+    try {
+      const url = `${this.baseUrl}${CONSENT_PATH}?anonymousId=${encodeURIComponent(anonymousId)}`;
+      const res = await fetch(url, {
+        headers: { 'x-immutable-publishable-key': this.publishableKey },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as { status: ConsentStatus };
+      return body.status;
+    } catch {
+      return undefined;
+    }
+  }
+
+  clearCookies(): void {
+    deleteCookie(COOKIE_NAME, this.cookieDomain);
+    deleteCookie(SESSION_COOKIE, this.cookieDomain);
+  }
+
+  private async syncToServer(anonymousId: string, status: ConsentLevel): Promise<void> {
+    try {
+      await fetch(`${this.baseUrl}${CONSENT_PATH}`, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-immutable-publishable-key': this.publishableKey,
+        },
+        body: JSON.stringify({ anonymousId, status, source: this.source }),
+      });
+    } catch {
+      // Fire-and-forget — consent sync failure shouldn't break the SDK
+    }
+  }
+}

packages/audience/web/src/context.ts

@@ -0,0 +1,7 @@
+import type { EventContext } from '@imtbl/audience-core';
+import { collectContext as coreCollectContext } from '@imtbl/audience-core';
+import { LIBRARY_NAME, LIBRARY_VERSION } from './config';
+
+export function collectContext(): EventContext {
+  return coreCollectContext(LIBRARY_NAME, LIBRARY_VERSION);
+}