feat(audience): add @imtbl/audience-sdk package

Scaffold the Audience SDK built on top of core's createConsentManager
and MessageQueue. The SDK provides ImmutableAudienceSDK as the main
entry point with page/track/identify/alias methods, consent management,
session tracking, attribution collection, and debug logging.

No core changes — SDK consumes core's consent state machine, session
module, and attribution from the pixel-core-consent branch.

Also fixes pre-existing CI flaky tests:
- x-client: mock getStarkPublicKeyFromImx and IMX API calls
- checkout: stop replacing entire window object in connect tests

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

Author: ImmutableJeffrey

packages/audience/sdk/.eslintrc.cjs

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

packages/audience/sdk/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/sdk/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@imtbl/audience-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/sdk/src/config.ts

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

packages/audience/sdk/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/sdk/src/debug.ts

@@ -0,0 +1,35 @@
+import type { ConsentLevel, Message } from '@imtbl/audience-core';
+
+const PREFIX = '[Immutable Audience]';
+
+export class DebugLogger {
+  private enabled: boolean;
+
+  constructor(enabled = false) {
+    this.enabled = enabled;
+  }
+
+  logEvent(method: string, message: Message): void {
+    if (!this.enabled) return;
+    // eslint-disable-next-line no-console
+    console.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)`);
+  }
+
+  logConsent(from: ConsentLevel, to: ConsentLevel): void {
+    if (!this.enabled) return;
+    // eslint-disable-next-line no-console
+    console.log(`${PREFIX} consent ${from} → ${to}`);
+  }
+
+  logWarning(msg: string): void {
+    if (!this.enabled) return;
+    // eslint-disable-next-line no-console
+    console.warn(`${PREFIX} ${msg}`);
+  }
+}

packages/audience/sdk/src/index.ts

@@ -0,0 +1,4 @@
+export { ImmutableAudienceSDK } from './sdk';
+export type { AudienceSDKConfig } from './types';
+export { DebugLogger } from './debug';
+export { collectContext } from './context';

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

@@ -0,0 +1,174 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {
+  MessageQueue,
+  createConsentManager,
+  deleteCookie,
+} from '@imtbl/audience-core';
+import { ImmutableAudienceSDK } from './sdk';
+
+// Mock core modules
+jest.mock('@imtbl/audience-core', () => {
+  const actual = jest.requireActual('@imtbl/audience-core');
+
+  const mockQueue = {
+    start: jest.fn(),
+    stop: jest.fn(),
+    destroy: jest.fn(),
+    enqueue: jest.fn(),
+    flush: jest.fn(),
+    flushUnload: jest.fn(),
+    purge: jest.fn(),
+    transform: jest.fn(),
+    clear: jest.fn(),
+    get length() { return 0; },
+  };
+
+  let consentLevel = 'none';
+  const mockConsent = {
+    get level() { return consentLevel as 'none' | 'anonymous' | 'full'; },
+    setLevel: jest.fn((next: string) => { consentLevel = next; }),
+  };
+
+  return {
+    ...actual,
+    MessageQueue: jest.fn(() => mockQueue),
+    createConsentManager: jest.fn(() => {
+      consentLevel = 'none';
+      return mockConsent;
+    }),
+    getOrCreateAnonymousId: jest.fn(() => 'anon-123'),
+    getOrCreateSession: jest.fn(() => ({ sessionId: 'sess-456', isNew: false })),
+    collectAttribution: jest.fn(() => ({})),
+    deleteCookie: jest.fn(),
+    httpTransport: { send: jest.fn() },
+    generateId: actual.generateId,
+    getTimestamp: actual.getTimestamp,
+    getBaseUrl: actual.getBaseUrl,
+  };
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+function createSDK(overrides: Record<string, any> = {}) {
+  return new ImmutableAudienceSDK({
+    publishableKey: 'pk_test',
+    environment: 'sandbox',
+    ...overrides,
+  });
+}
+
+describe('ImmutableAudienceSDK', () => {
+  it('initialises with default consent none', () => {
+    createSDK();
+    expect(createConsentManager).toHaveBeenCalledWith(
+      expect.anything(),
+      'pk_test',
+      'anon-123',
+      'sandbox',
+      'none',
+    );
+  });
+
+  it('initialises with provided consent level', () => {
+    createSDK({ consent: 'full' });
+    expect(createConsentManager).toHaveBeenCalledWith(
+      expect.anything(),
+      'pk_test',
+      'anon-123',
+      'sandbox',
+      'full',
+    );
+  });
+
+  it('starts the queue on construction', () => {
+    createSDK();
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+    expect(queue.start).toHaveBeenCalled();
+  });
+
+  it('does not enqueue when consent is none', () => {
+    const sdk = createSDK();
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+
+    sdk.page();
+    sdk.track('click');
+
+    expect(queue.enqueue).not.toHaveBeenCalled();
+  });
+
+  it('enqueues page event when consent allows', () => {
+    const sdk = createSDK({ consent: 'anonymous' });
+    const consent = (createConsentManager as jest.Mock).mock.results[0].value;
+    consent.setLevel('anonymous');
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+
+    sdk.page({ section: 'shop' });
+
+    expect(queue.enqueue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'page',
+        surface: 'web',
+        anonymousId: 'anon-123',
+      }),
+    );
+  });
+
+  it('enqueues track event with eventName', () => {
+    const sdk = createSDK({ consent: 'anonymous' });
+    const consent = (createConsentManager as jest.Mock).mock.results[0].value;
+    consent.setLevel('anonymous');
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+
+    sdk.track('purchase', { value: 9.99 });
+
+    expect(queue.enqueue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'track',
+        eventName: 'purchase',
+      }),
+    );
+  });
+
+  it('only allows identify at full consent', () => {
+    const sdk = createSDK();
+    const consent = (createConsentManager as jest.Mock).mock.results[0].value;
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+
+    consent.setLevel('anonymous');
+    sdk.identify('user-1', { name: 'Test' });
+    expect(queue.enqueue).not.toHaveBeenCalled();
+
+    consent.setLevel('full');
+    sdk.identify('user-1', { name: 'Test' });
+    expect(queue.enqueue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'identify',
+        userId: 'user-1',
+      }),
+    );
+  });
+
+  it('clears cookies when consent set to none', () => {
+    const sdk = createSDK();
+    const consent = (createConsentManager as jest.Mock).mock.results[0].value;
+    consent.setLevel('full');
+
+    sdk.setConsent('none');
+
+    expect(consent.setLevel).toHaveBeenCalledWith('none');
+    expect(deleteCookie).toHaveBeenCalledTimes(2);
+  });
+
+  it('destroys queue on destroy', () => {
+    const sdk = createSDK();
+    const queue = (MessageQueue as jest.Mock).mock.results[0].value;
+
+    sdk.destroy();
+    expect(queue.destroy).toHaveBeenCalled();
+
+    sdk.track('late-event');
+    expect(queue.enqueue).not.toHaveBeenCalled();
+  });
+});