feat(audience): add ImmutableWebSDK with consent, attribution, and session lifecycle

Adds @imtbl/audience-web-sdk at packages/audience/web/ — the explicit,
typed tracking surface for game studios on web.

Architecture (core → sdk → web):
- ConsentManager + DebugLogger imported from @imtbl/audience-sdk
- WebSDKConfig extends AudienceSDKConfig (adds consentSource)
- Web provides fetch-based ConsentTransport and cookie-clearing callbacks
- Deleted sdk/context.ts wrapper — calls core collectContext directly

API: init, track, page, identify, alias, setConsent, reset, flush, shutdown

Design:
- Attribution stored in wire format (snake_case) from parse to send.
  TRACKED_PARAMS constant is the single source of truth.
- Message factory (baseMessage + enqueue) eliminates repeated boilerplate.
- Event names (SESSION_START, SESSION_END) are named constants.
- All public interfaces have JSDoc on every field.
- identify() type guard rejects null and arrays, truncates once.
- Helpers: isTrackingDisabled(), effectiveUserId(), startSession(),
  renewSession() — each method reads as intent, not mechanics.
- Multi-instance warning on double init without prior shutdown.

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

Author: ImmutableJeffrey

packages/audience/sdk/src/context.test.ts

@@ -1,5 +1,5 @@
 import type { Message } from '@imtbl/audience-core';
-import { DebugLogger } from './debug';
+import { DebugLogger, LOG_PREFIX } from './debug';
 
 describe('DebugLogger', () => {
   let logSpy: jest.SpyInstance;
@@ -22,7 +22,7 @@ describe('DebugLogger', () => {
     anonymousId: 'anon-1',
     surface: 'web',
     context: { library: 'test', libraryVersion: '0.0.0' },
-    event: 'click',
+    eventName: 'click',
     properties: {},
   };
 
@@ -42,7 +42,7 @@ describe('DebugLogger', () => {
     logger.logEvent('track', stubMessage);
 
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] track',
+      `${LOG_PREFIX} track`,
       stubMessage,
     );
   });
@@ -52,12 +52,12 @@ describe('DebugLogger', () => {
 
     logger.logFlush(true, 5);
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] flush ok (5 messages)',
+      `${LOG_PREFIX} flush ok (5 messages)`,
     );
 
     logger.logFlush(false, 3);
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] flush failed (3 messages)',
+      `${LOG_PREFIX} flush failed (3 messages)`,
     );
   });
 
@@ -66,7 +66,7 @@ describe('DebugLogger', () => {
     logger.logConsent('none', 'full');
 
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] consent none → full',
+      `${LOG_PREFIX} consent none \u2192 full`,
     );
   });
 
@@ -75,7 +75,7 @@ describe('DebugLogger', () => {
     logger.logWarning('something went wrong');
 
     expect(warnSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] something went wrong',
+      `${LOG_PREFIX} something went wrong`,
     );
   });
 });

packages/audience/sdk/src/context.ts

@@ -1,6 +1,6 @@
 import type { ConsentLevel, Message } from '@imtbl/audience-core';
 
-const PREFIX = '[Immutable Audience]';
+export const LOG_PREFIX = '[audience-sdk]';
 
 export class DebugLogger {
   private enabled: boolean;
@@ -12,24 +12,24 @@ export class DebugLogger {
   logEvent(method: string, message: Message): void {
     if (!this.enabled) return;
     // eslint-disable-next-line no-console
-    console.log(`${PREFIX} ${method}`, message);
+    console.log(`${LOG_PREFIX} ${method}`, message);
   }
 
   logFlush(ok: boolean, count: number): void {
     if (!this.enabled) return;
     // eslint-disable-next-line no-console
-    console.log(`${PREFIX} flush ${ok ? 'ok' : 'failed'} (${count} messages)`);
+    console.log(`${LOG_PREFIX} flush ${ok ? 'ok' : 'failed'} (${count} messages)`);
   }
 
   logConsent(from: ConsentLevel, to: ConsentLevel): void {
     if (!this.enabled) return;
     // eslint-disable-next-line no-console
-    console.log(`${PREFIX} consent ${from} → ${to}`);
+    console.log(`${LOG_PREFIX} consent ${from} → ${to}`);
   }
 
   logWarning(msg: string): void {
     if (!this.enabled) return;
     // eslint-disable-next-line no-console
-    console.warn(`${PREFIX} ${msg}`);
+    console.warn(`${LOG_PREFIX} ${msg}`);
   }
 }

packages/audience/sdk/src/debug.test.ts

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

packages/audience/sdk/src/debug.ts

@@ -0,0 +1,16 @@
+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',
+    '^@imtbl/audience-sdk$': '<rootDir>/../sdk/src/index.ts',
+  },
+};
+
+export default config;

packages/audience/web/.eslintrc.cjs

@@ -0,0 +1,62 @@
+{
+  "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:*",
+    "@imtbl/audience-sdk": "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/jest.config.ts

@@ -0,0 +1,132 @@
+import { parseAttribution } from './attribution';
+
+const originalLocation = window.location;
+
+beforeEach(() => {
+  sessionStorage.clear();
+});
+
+afterEach(() => {
+  Object.defineProperty(window, 'location', {
+    value: originalLocation,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(document, 'referrer', {
+    value: '',
+    configurable: true,
+  });
+});
+
+describe('parseAttribution', () => {
+  it('parses UTM params from the URL', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '?utm_source=youtube&utm_medium=influencer&utm_campaign=launch',
+        href: 'https://studio.com/shop?utm_source=youtube&utm_medium=influencer&utm_campaign=launch',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.utm_source).toBe('youtube');
+    expect(ctx.utm_medium).toBe('influencer');
+    expect(ctx.utm_campaign).toBe('launch');
+    expect(ctx.landing_page).toBe(window.location.href);
+  });
+
+  it('parses click IDs from the URL', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '?gclid=abc&fbclid=def&ttclid=ghi&msclkid=jkl&dclid=mno&li_fat_id=pqr',
+        href: 'https://studio.com/?gclid=abc&fbclid=def&ttclid=ghi&msclkid=jkl&dclid=mno&li_fat_id=pqr',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.gclid).toBe('abc');
+    expect(ctx.fbclid).toBe('def');
+    expect(ctx.ttclid).toBe('ghi');
+    expect(ctx.msclkid).toBe('jkl');
+    expect(ctx.dclid).toBe('mno');
+    expect(ctx.li_fat_id).toBe('pqr');
+  });
+
+  it('parses ref param as referral_code', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '?ref=creator_handle',
+        href: 'https://studio.com/?ref=creator_handle',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.referral_code).toBe('creator_handle');
+  });
+
+  it('returns cached attribution on subsequent calls within session', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '?utm_source=first',
+        href: 'https://studio.com/?utm_source=first',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const first = parseAttribution();
+    expect(first.utm_source).toBe('first');
+
+    // Change URL (simulating SPA navigation)
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '',
+        href: 'https://studio.com/shop',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const second = parseAttribution();
+    expect(second.utm_source).toBe('first'); // Still the original
+  });
+
+  it('captures document.referrer', () => {
+    Object.defineProperty(document, 'referrer', {
+      value: 'https://google.com/search?q=immutable',
+      configurable: true,
+    });
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '',
+        href: 'https://studio.com/',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.referrer).toBe('https://google.com/search?q=immutable');
+  });
+
+  it('only includes params that are present', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '',
+        href: 'https://studio.com/',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.utm_source).toBeUndefined();
+    expect(ctx.gclid).toBeUndefined();
+    expect(ctx.landing_page).toBe('https://studio.com/');
+  });
+});