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

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,76 @@
+import { ConsentManager } 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',
+        }),
+      }),
+    );
+  });
+
+  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,105 @@
+import type {
+  ConsentLevel,
+  ConsentStatus,
+  Environment,
+} from '@imtbl/audience-core';
+import {
+  CONSENT_PATH,
+  COOKIE_NAME,
+  SESSION_COOKIE,
+  getBaseUrl,
+  deleteCookie,
+  truncateSource,
+} from '@imtbl/audience-core';
+
+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;
+    this.level = initialConsent;
+  }
+
+  getLevel(): ConsentLevel {
+    return this.level;
+  }
+
+  setLevel(
+    level: ConsentLevel,
+    anonymousId: string,
+    callbacks?: ConsentCallbacks,
+  ): void {
+    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);
+}

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

@@ -0,0 +1,51 @@
+import {
+  getOrCreateSessionId,
+  getSessionId,
+  touchSession,
+} from './cookie';
+
+beforeEach(() => {
+  document.cookie.split(';').forEach((c) => {
+    document.cookie = `${c.trim().split('=')[0]}=; max-age=0; path=/`;
+  });
+});
+
+describe('getOrCreateSessionId', () => {
+  it('creates a new session ID and reports isNew', () => {
+    const result = getOrCreateSessionId();
+    expect(result.sessionId).toBeDefined();
+    expect(typeof result.sessionId).toBe('string');
+    expect(result.isNew).toBe(true);
+  });
+
+  it('returns existing session and isNew=false', () => {
+    const first = getOrCreateSessionId();
+    const second = getOrCreateSessionId();
+    expect(second.sessionId).toBe(first.sessionId);
+    expect(second.isNew).toBe(false);
+  });
+});
+
+describe('getSessionId', () => {
+  it('returns undefined when no session exists', () => {
+    expect(getSessionId()).toBeUndefined();
+  });
+
+  it('returns session ID after creation', () => {
+    const { sessionId } = getOrCreateSessionId();
+    expect(getSessionId()).toBe(sessionId);
+  });
+});
+
+describe('touchSession', () => {
+  it('does nothing if no session exists', () => {
+    touchSession();
+    expect(getSessionId()).toBeUndefined();
+  });
+
+  it('preserves existing session cookie', () => {
+    const { sessionId } = getOrCreateSessionId();
+    touchSession();
+    expect(getOrCreateSessionId().sessionId).toBe(sessionId);
+  });
+});

packages/audience/web/src/cookie.ts

@@ -0,0 +1,34 @@
+import {
+  SESSION_COOKIE,
+  getCookie,
+  setCookie,
+  generateId,
+} from '@imtbl/audience-core';
+
+const SESSION_MAX_AGE = 30 * 60; // 30 minutes (rolling)
+
+// --- Session ID (_imtbl_sid cookie, 30min rolling) ---
+
+export interface SessionResult {
+  sessionId: string;
+  isNew: boolean;
+}
+
+export function getOrCreateSessionId(domain?: string): SessionResult {
+  const existing = getCookie(SESSION_COOKIE);
+  const isNew = !existing;
+  const sid = existing ?? generateId();
+  setCookie(SESSION_COOKIE, sid, SESSION_MAX_AGE, domain);
+  return { sessionId: sid, isNew };
+}
+
+export function getSessionId(): string | undefined {
+  return getCookie(SESSION_COOKIE);
+}
+
+export function touchSession(domain?: string): void {
+  const sid = getCookie(SESSION_COOKIE);
+  if (sid) {
+    setCookie(SESSION_COOKIE, sid, SESSION_MAX_AGE, domain);
+  }
+}

packages/audience/web/src/debug.ts

@@ -0,0 +1,24 @@
+/* eslint-disable no-console, class-methods-use-this */
+import type { Message, ConsentLevel } from '@imtbl/audience-core';
+
+const PREFIX = '[Immutable Audience]';
+
+export class DebugLogger {
+  logEvent(method: string, message: Message): void {
+    console.log(`${PREFIX} ${method}()`, message);
+  }
+
+  logFlush(ok: boolean, count: number): void {
+    console.log(
+      `${PREFIX} flush: ${ok ? 'success' : 'failed'}, ${count} message${count !== 1 ? 's' : ''}`,
+    );
+  }
+
+  logConsent(from: ConsentLevel, to: ConsentLevel): void {
+    console.log(`${PREFIX} consent: ${from} \u2192 ${to}`);
+  }
+
+  logWarning(msg: string): void {
+    console.warn(`${PREFIX} ${msg}`);
+  }
+}