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

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

Author: ImmutableJeffrey

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

@@ -0,0 +1,124 @@
+import { parseAttribution, attributionToProperties } from './attribution';
+
+beforeEach(() => {
+  sessionStorage.clear();
+});
+
+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,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.utmSource).toBe('youtube');
+    expect(ctx.utmMedium).toBe('influencer');
+    expect(ctx.utmCampaign).toBe('launch');
+    expect(ctx.landingPage).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,
+    });
+
+    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 referralCode', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '?ref=creator_handle',
+        href: 'https://studio.com/?ref=creator_handle',
+      },
+      writable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.referralCode).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,
+    });
+
+    const first = parseAttribution();
+    expect(first.utmSource).toBe('first');
+
+    // Change URL (simulating SPA navigation)
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '',
+        href: 'https://studio.com/shop',
+      },
+      writable: true,
+    });
+
+    const second = parseAttribution();
+    expect(second.utmSource).toBe('first'); // Still the original
+  });
+
+  it('returns empty context with no params', () => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        search: '',
+        href: 'https://studio.com/',
+      },
+      writable: true,
+    });
+
+    const ctx = parseAttribution();
+    expect(ctx.utmSource).toBeUndefined();
+    expect(ctx.gclid).toBeUndefined();
+    expect(ctx.landingPage).toBe('https://studio.com/');
+  });
+});
+
+describe('attributionToProperties', () => {
+  it('converts attribution context to flat properties', () => {
+    const props = attributionToProperties({
+      utmSource: 'youtube',
+      utmMedium: 'influencer',
+      gclid: 'abc',
+      dclid: 'mno',
+      li_fat_id: 'pqr',
+      referralCode: 'ref123',
+      landingPage: 'https://studio.com/',
+    });
+
+    expect(props).toEqual({
+      utm_source: 'youtube',
+      utm_medium: 'influencer',
+      gclid: 'abc',
+      dclid: 'mno',
+      li_fat_id: 'pqr',
+      referral_code: 'ref123',
+      landing_page: 'https://studio.com/',
+    });
+  });
+
+  it('omits undefined fields', () => {
+    const props = attributionToProperties({ utmSource: 'youtube' });
+    expect(props).toEqual({ utm_source: 'youtube' });
+    expect(props).not.toHaveProperty('utm_medium');
+  });
+});

packages/audience/web/src/attribution.ts

@@ -0,0 +1,92 @@
+import { isBrowser } from '@imtbl/audience-core';
+
+export interface AttributionContext {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmContent?: string;
+  utmTerm?: string;
+  gclid?: string;
+  fbclid?: string;
+  ttclid?: string;
+  msclkid?: string;
+  dclid?: string;
+  li_fat_id?: string;
+  referrer?: string;
+  referralCode?: string;
+  landingPage?: string;
+}
+
+const SESSION_KEY = '__imtbl_attribution';
+
+function getSessionAttribution(): AttributionContext | undefined {
+  try {
+    const raw = sessionStorage.getItem(SESSION_KEY);
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function persistSessionAttribution(ctx: AttributionContext): void {
+  try {
+    sessionStorage.setItem(SESSION_KEY, JSON.stringify(ctx));
+  } catch {
+    // sessionStorage unavailable — attribution won't persist across SPA navigations
+  }
+}
+
+/**
+ * Parse attribution signals from the current URL.
+ * Captured once per session and persisted in sessionStorage so SPA
+ * route changes don't lose the original UTM params.
+ */
+export function parseAttribution(): AttributionContext {
+  if (!isBrowser()) return {};
+
+  // Return cached attribution for this session if it exists
+  const cached = getSessionAttribution();
+  if (cached) return cached;
+
+  const params = new URLSearchParams(window.location.search);
+
+  const ctx: AttributionContext = {
+    utmSource: params.get('utm_source') ?? undefined,
+    utmMedium: params.get('utm_medium') ?? undefined,
+    utmCampaign: params.get('utm_campaign') ?? undefined,
+    utmContent: params.get('utm_content') ?? undefined,
+    utmTerm: params.get('utm_term') ?? undefined,
+    gclid: params.get('gclid') ?? undefined,
+    fbclid: params.get('fbclid') ?? undefined,
+    ttclid: params.get('ttclid') ?? undefined,
+    msclkid: params.get('msclkid') ?? undefined,
+    dclid: params.get('dclid') ?? undefined,
+    li_fat_id: params.get('li_fat_id') ?? undefined,
+    referrer: document.referrer || undefined,
+    referralCode: params.get('ref') ?? undefined,
+    landingPage: window.location.href,
+  };
+
+  persistSessionAttribution(ctx);
+  return ctx;
+}
+
+/** Convert attribution context to flat properties for the first PageMessage. */
+export function attributionToProperties(ctx: AttributionContext): Record<string, string> {
+  const props: Record<string, string> = {};
+  if (ctx.utmSource) props.utm_source = ctx.utmSource;
+  if (ctx.utmMedium) props.utm_medium = ctx.utmMedium;
+  if (ctx.utmCampaign) props.utm_campaign = ctx.utmCampaign;
+  if (ctx.utmContent) props.utm_content = ctx.utmContent;
+  if (ctx.utmTerm) props.utm_term = ctx.utmTerm;
+  if (ctx.gclid) props.gclid = ctx.gclid;
+  if (ctx.fbclid) props.fbclid = ctx.fbclid;
+  if (ctx.ttclid) props.ttclid = ctx.ttclid;
+  if (ctx.msclkid) props.msclkid = ctx.msclkid;
+  if (ctx.dclid) props.dclid = ctx.dclid;
+  if (ctx.li_fat_id) props.li_fat_id = ctx.li_fat_id;
+  if (ctx.referrer) props.referrer = ctx.referrer;
+  if (ctx.referralCode) props.referral_code = ctx.referralCode;
+  if (ctx.landingPage) props.landing_page = ctx.landingPage;
+  return props;
+}

packages/audience/web/src/index.ts

@@ -1,11 +1,3 @@
-export { ConsentManager } from './consent';
-export type { ConsentCallbacks } from './consent';
+export { ImmutableWebSDK } from './sdk';
 export type { WebSDKConfig } from './types';
-export type { SessionResult } from './cookie';
-export {
-  getOrCreateSessionId,
-  getSessionId,
-  touchSession,
-} from './cookie';
-export { collectContext } from './context';
-export { DebugLogger } from './debug';
+export type { Environment, ConsentLevel, UserTraits } from '@imtbl/audience-core';