feat(audience): add core types, utils, config, storage, and cookie (#2812)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nattb8

packages/audience/core/src/config.test.ts

@@ -0,0 +1,15 @@
+import { getBaseUrl } from './config';
+
+describe('getBaseUrl', () => {
+  it('returns dev URL', () => {
+    expect(getBaseUrl('dev')).toBe('https://api.dev.immutable.com');
+  });
+
+  it('returns sandbox URL', () => {
+    expect(getBaseUrl('sandbox')).toBe('https://api.sandbox.immutable.com');
+  });
+
+  it('returns production URL', () => {
+    expect(getBaseUrl('production')).toBe('https://api.immutable.com');
+  });
+});

packages/audience/core/src/config.ts

@@ -0,0 +1,18 @@
+import type { Environment } from './types';
+
+const BASE_URLS: Record<Environment, string> = {
+  dev: 'https://api.dev.immutable.com',
+  sandbox: 'https://api.sandbox.immutable.com',
+  production: 'https://api.immutable.com',
+};
+
+export const INGEST_PATH = '/v1/audience/messages';
+export const CONSENT_PATH = '/v1/audience/tracking-consent';
+
+export const FLUSH_INTERVAL_MS = 5_000;
+export const FLUSH_SIZE = 20;
+
+export const COOKIE_NAME = 'imtbl_anon_id';
+export const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60 * 2; // 2 years
+
+export const getBaseUrl = (environment: Environment): string => BASE_URLS[environment];

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

@@ -0,0 +1,46 @@
+import { getOrCreateAnonymousId, getAnonymousId } from './cookie';
+import { COOKIE_NAME } from './config';
+
+function clearCookies() {
+  document.cookie.split(';').forEach((c) => {
+    const name = c.split('=')[0].trim();
+    document.cookie = `${name}=; max-age=0; path=/`;
+  });
+}
+
+beforeEach(clearCookies);
+
+describe('getOrCreateAnonymousId', () => {
+  it('generates a new ID when no cookie exists', () => {
+    const id = getOrCreateAnonymousId();
+    expect(id).toBeTruthy();
+    expect(typeof id).toBe('string');
+  });
+
+  it('persists the ID in a cookie', () => {
+    const id = getOrCreateAnonymousId();
+    expect(document.cookie).toContain(`${COOKIE_NAME}=${id}`);
+  });
+
+  it('returns the same ID on subsequent calls', () => {
+    const first = getOrCreateAnonymousId();
+    const second = getOrCreateAnonymousId();
+    expect(second).toBe(first);
+  });
+
+  it('returns an existing cookie value if already set', () => {
+    document.cookie = `${COOKIE_NAME}=existing-id; path=/`;
+    expect(getOrCreateAnonymousId()).toBe('existing-id');
+  });
+});
+
+describe('getAnonymousId', () => {
+  it('returns undefined when no cookie exists', () => {
+    expect(getAnonymousId()).toBeUndefined();
+  });
+
+  it('returns the cookie value when set', () => {
+    document.cookie = `${COOKIE_NAME}=test-id; path=/`;
+    expect(getAnonymousId()).toBe('test-id');
+  });
+});

packages/audience/core/src/cookie.ts

@@ -0,0 +1,32 @@
+import { COOKIE_NAME, COOKIE_MAX_AGE_SECONDS } from './config';
+import { isBrowser, generateId } from './utils';
+
+function getCookie(name: string): string | undefined {
+  if (!isBrowser()) return undefined;
+  const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]) : undefined;
+}
+
+function setCookie(name: string, value: string, maxAge: number): void {
+  if (!isBrowser()) return;
+  const secure = window.location.protocol === 'https:' ? '; Secure' : '';
+  document.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=${maxAge}; SameSite=Lax${secure}`;
+}
+
+/**
+ * Returns the anonymous ID from the shared cookie, creating one if it doesn't exist.
+ * Both the web SDK and pixel read/write the same cookie so identity stitching
+ * works across surfaces on the same domain.
+ */
+export function getOrCreateAnonymousId(): string {
+  const existing = getCookie(COOKIE_NAME);
+  if (existing) return existing;
+
+  const id = generateId();
+  setCookie(COOKIE_NAME, id, COOKIE_MAX_AGE_SECONDS);
+  return id;
+}
+
+export function getAnonymousId(): string | undefined {
+  return getCookie(COOKIE_NAME);
+}

packages/audience/core/src/index.ts

@@ -1,3 +1,28 @@
-// @imtbl/audience-core — shared foundation for the web SDK and pixel.
-// Source modules will be added in follow-up PRs (SDK-33, SDK-34).
-export {};
+export type {
+  Environment,
+  Surface,
+  MessageType,
+  EventContext,
+  UserTraits,
+  TrackMessage,
+  PageMessage,
+  ScreenMessage,
+  IdentifyMessage,
+  AliasMessage,
+  Message,
+  BatchPayload,
+} from './types';
+
+export { getOrCreateAnonymousId, getAnonymousId } from './cookie';
+export * as storage from './storage';
+
+export {
+  getBaseUrl,
+  INGEST_PATH,
+  CONSENT_PATH,
+  FLUSH_INTERVAL_MS,
+  FLUSH_SIZE,
+  COOKIE_NAME,
+} from './config';
+
+export { generateId, getTimestamp, isBrowser } from './utils';

packages/audience/core/src/storage.test.ts

@@ -0,0 +1,33 @@
+import * as storage from './storage';
+
+afterEach(() => {
+  localStorage.clear();
+});
+
+describe('storage', () => {
+  it('round-trips a string value', () => {
+    storage.setItem('key', 'hello');
+    expect(storage.getItem('key')).toBe('hello');
+  });
+
+  it('round-trips an object value', () => {
+    const obj = { a: 1, b: 'two' };
+    storage.setItem('key', obj);
+    expect(storage.getItem('key')).toEqual(obj);
+  });
+
+  it('returns undefined for missing keys', () => {
+    expect(storage.getItem('missing')).toBeUndefined();
+  });
+
+  it('removes items', () => {
+    storage.setItem('key', 'value');
+    storage.removeItem('key');
+    expect(storage.getItem('key')).toBeUndefined();
+  });
+
+  it('prefixes keys in localStorage', () => {
+    storage.setItem('test', 'val');
+    expect(localStorage.getItem('__imtbl_audience_test')).toBe('"val"');
+  });
+});

packages/audience/core/src/storage.ts

@@ -0,0 +1,39 @@
+import { isBrowser } from './utils';
+
+const PREFIX = '__imtbl_audience_';
+
+function hasLocalStorage(): boolean {
+  try {
+    return isBrowser() && typeof localStorage !== 'undefined';
+  } catch {
+    return false;
+  }
+}
+
+export function getItem(key: string): unknown | undefined {
+  if (!hasLocalStorage()) return undefined;
+  try {
+    const raw = localStorage.getItem(`${PREFIX}${key}`);
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function setItem(key: string, value: unknown): void {
+  if (!hasLocalStorage()) return;
+  try {
+    localStorage.setItem(`${PREFIX}${key}`, JSON.stringify(value));
+  } catch {
+    // Storage full or unavailable.
+  }
+}
+
+export function removeItem(key: string): void {
+  if (!hasLocalStorage()) return;
+  try {
+    localStorage.removeItem(`${PREFIX}${key}`);
+  } catch {
+    // Ignore.
+  }
+}

packages/audience/core/src/types.ts

@@ -0,0 +1,79 @@
+export type Environment = 'dev' | 'sandbox' | 'production';
+
+export type Surface = 'web' | 'pixel' | 'unity' | 'unreal';
+
+export type MessageType = 'track' | 'page' | 'screen' | 'identify' | 'alias';
+
+export interface EventContext {
+  library: string;
+  libraryVersion: string;
+  userAgent?: string;
+  locale?: string;
+  timezone?: string;
+  screen?: string;
+  pageUrl?: string;
+  pagePath?: string;
+  pageReferrer?: string;
+  pageTitle?: string;
+}
+
+export interface UserTraits {
+  email?: string;
+  name?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+interface BaseMessage {
+  type: MessageType;
+  messageId: string;
+  eventTimestamp: string;
+  anonymousId: string;
+  surface: Surface;
+  context: EventContext;
+}
+
+export interface TrackMessage extends BaseMessage {
+  type: 'track';
+  eventName: string;
+  properties?: Record<string, unknown>;
+  userId?: string;
+}
+
+export interface PageMessage extends BaseMessage {
+  type: 'page';
+  properties?: Record<string, unknown>;
+  userId?: string;
+}
+
+export interface ScreenMessage extends BaseMessage {
+  type: 'screen';
+  eventName?: string;
+  properties?: Record<string, unknown>;
+  userId?: string;
+}
+
+export interface IdentifyMessage extends BaseMessage {
+  type: 'identify';
+  userId?: string;
+  identityType?: string;
+  traits?: UserTraits;
+}
+
+export interface AliasMessage extends BaseMessage {
+  type: 'alias';
+  fromId: string;
+  fromType?: string;
+  toId: string;
+  toType?: string;
+}
+
+export type Message =
+  | TrackMessage
+  | PageMessage
+  | ScreenMessage
+  | IdentifyMessage
+  | AliasMessage;
+
+export interface BatchPayload {
+  messages: Message[];
+}

packages/audience/core/src/utils.test.ts

@@ -0,0 +1,27 @@
+import { isBrowser, generateId, getTimestamp } from './utils';
+
+describe('isBrowser', () => {
+  it('returns true in jsdom', () => {
+    expect(isBrowser()).toBe(true);
+  });
+});
+
+describe('generateId', () => {
+  it('returns a non-empty string', () => {
+    const id = generateId();
+    expect(typeof id).toBe('string');
+    expect(id.length).toBeGreaterThan(0);
+  });
+
+  it('returns unique values', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateId()));
+    expect(ids.size).toBe(100);
+  });
+});
+
+describe('getTimestamp', () => {
+  it('returns an ISO 8601 string', () => {
+    const ts = getTimestamp();
+    expect(new Date(ts).toISOString()).toBe(ts);
+  });
+});

packages/audience/core/src/utils.ts

@@ -0,0 +1,10 @@
+export const isBrowser = (): boolean => typeof window !== 'undefined' && typeof document !== 'undefined';
+
+export const generateId = (): string => {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+};
+
+export const getTimestamp = (): string => new Date().toISOString();