feat(audience): add debug logger and WebSDKConfig

- DebugLogger: opt-in console logging for events, flushes, consent
  changes, and warnings
- WebSDKConfig: publishable key, environment, consent, debug, cookie
  domain, flush interval/size
- Config constants: library name/version, log prefix, consent source,
  session event names

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

Author: ImmutableJeffrey

packages/audience/sdk/src/config.ts

@@ -2,5 +2,19 @@
 // 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
+/** Replaced at build time by esbuild replace plugin. */
 export const LIBRARY_VERSION = '__SDK_VERSION__';
+
+/** Log prefix for console messages from this package. */
+export const LOG_PREFIX = '[audience-sdk]';
+
+/** Default consent source when consentSource is not provided in config. */
+export const DEFAULT_CONSENT_SOURCE = 'WebSDK';
+
+// --- Auto-tracked event names ---
+// These are fired by the SDK lifecycle, not by studio code.
+
+/** Fired on init (or consent upgrade from none) when no active session cookie exists. */
+export const SESSION_START = 'session_start';
+/** Fired on explicit shutdown(). Not fired on tab close or consent revocation. */
+export const SESSION_END = 'session_end';

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

@@ -1,5 +1,6 @@
 import type { Message } from '@imtbl/audience-core';
 import { DebugLogger } from './debug';
+import { LOG_PREFIX } from './config';
 
 describe('DebugLogger', () => {
   let logSpy: jest.SpyInstance;
@@ -22,7 +23,7 @@ describe('DebugLogger', () => {
     anonymousId: 'anon-1',
     surface: 'web',
     context: { library: 'test', libraryVersion: '0.0.0' },
-    event: 'click',
+    eventName: 'click',
     properties: {},
   };
 
@@ -42,7 +43,7 @@ describe('DebugLogger', () => {
     logger.logEvent('track', stubMessage);
 
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] track',
+      `${LOG_PREFIX} track`,
       stubMessage,
     );
   });
@@ -52,12 +53,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 +67,7 @@ describe('DebugLogger', () => {
     logger.logConsent('none', 'full');
 
     expect(logSpy).toHaveBeenCalledWith(
-      '[Immutable Audience] consent none → full',
+      `${LOG_PREFIX} consent none \u2192 full`,
     );
   });
 
@@ -75,7 +76,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,5 @@
 import type { ConsentLevel, Message } from '@imtbl/audience-core';
-
-const PREFIX = '[Immutable Audience]';
+import { LOG_PREFIX } from './config';
 
 export class DebugLogger {
   private enabled: boolean;
@@ -12,24 +11,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

@@ -1,13 +1,19 @@
 import type { Environment, ConsentLevel } from '@imtbl/audience-core';
 
-/** Configuration for the Immutable Audience SDK. */
-export interface AudienceSDKConfig {
+/** Configuration for the Immutable Web SDK. */
+export interface WebSDKConfig {
+  /** Publishable API key from Immutable Hub (pk_imtbl_...). */
   publishableKey: string;
+  /** Target environment — controls which backend receives events. */
   environment: Environment;
-  /** Defaults to 'none' — no tracking until explicitly opted in. */
+  /** Initial consent level. Defaults to 'none' (no tracking until opted in). */
   consent?: ConsentLevel;
+  /** Enable console logging of all events, flushes, and consent changes. */
   debug?: boolean;
+  /** Cookie domain for cross-subdomain sharing (e.g. '.studio.com'). */
   cookieDomain?: string;
+  /** Queue flush interval in milliseconds. Defaults to 5000. */
   flushInterval?: number;
+  /** Number of queued messages that triggers an automatic flush. Defaults to 20. */
   flushSize?: number;
 }