feat(audience): add session_start/end events and fix test isolation

Add session lifecycle tracking to the Pixel class:
- Fire session_start track event on new session creation
- Fire session_end track event on pagehide/visibilitychange with duration
- Refactor session module to return SessionResult with isNew flag
- Fix test listener leaking by cleaning up pixel instances in afterEach

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bkbooth

packages/audience/pixel/src/index.ts

@@ -4,7 +4,8 @@ export type { PixelInitOptions } from './pixel';
 export { createConsentManager } from './consent';
 export type { ConsentManager } from './consent';
 
-export { getOrCreateSessionId, getSessionId } from './session';
+export { getOrCreateSession, getOrCreateSessionId, getSessionId } from './session';
+export type { SessionResult } from './session';
 
 export { collectAttribution, clearAttribution } from './attribution';
 export type { Attribution } from './attribution';

packages/audience/pixel/src/pixel.test.ts

@@ -35,6 +35,7 @@ jest.mock('@imtbl/audience-core', () => ({
   }),
   generateId: jest.fn().mockReturnValue('msg-uuid'),
   getTimestamp: jest.fn().mockReturnValue('2026-04-07T00:00:00.000Z'),
+  isBrowser: jest.fn().mockReturnValue(true),
   getCookie: jest.fn(),
   setCookie: jest.fn(),
 }));
@@ -48,60 +49,99 @@ jest.mock('./attribution', () => ({
 }));
 
 jest.mock('./session', () => ({
+  getOrCreateSession: jest.fn().mockReturnValue({ sessionId: 'session-abc', isNew: true }),
   getOrCreateSessionId: jest.fn().mockReturnValue('session-abc'),
 }));
 
 // Mock fetch globally
 global.fetch = jest.fn().mockResolvedValue({ ok: true });
 
+// Access the mock to change return values per test
+const mockGetOrCreateSession = jest.requireMock('./session').getOrCreateSession;
+
+let activePixel: Pixel | null = null;
+
 beforeEach(() => {
   jest.clearAllMocks();
+  mockGetOrCreateSession.mockReturnValue({ sessionId: 'session-abc', isNew: true });
+});
+
+afterEach(() => {
+  // Clean up any active pixel to remove event listeners
+  if (activePixel) {
+    activePixel.destroy();
+    activePixel = null;
+  }
 });
 
 describe('Pixel', () => {
   describe('init', () => {
-    it('creates queue, starts it, and fires a page view when consent is anonymous', () => {
+    it('creates queue, starts it, and fires page view + session_start when consent is anonymous', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
 
       expect(mockStart).toHaveBeenCalled();
-      expect(mockEnqueue).toHaveBeenCalledWith(
-        expect.objectContaining({
-          type: 'page',
-          surface: 'pixel',
-          anonymousId: 'anon-123',
-          properties: expect.objectContaining({
-            utm_source: 'google',
-            sessionId: 'session-abc',
-          }),
-        }),
+
+      // Should fire session_start (new session) then page view
+      const calls = mockEnqueue.mock.calls.map((c: unknown[]) => (c[0] as Record<string, unknown>));
+      const pageCall = calls.find((c) => c.type === 'page');
+      const sessionStartCall = calls.find(
+        (c) => c.type === 'track' && c.eventName === 'session_start',
       );
+
+      expect(pageCall).toBeDefined();
+      expect(pageCall!.surface).toBe('pixel');
+      expect(pageCall!.anonymousId).toBe('anon-123');
+      expect((pageCall!.properties as Record<string, unknown>).utm_source).toBe('google');
+
+      expect(sessionStartCall).toBeDefined();
+      expect((sessionStartCall!.properties as Record<string, unknown>).sessionId).toBe('session-abc');
     });
 
-    it('does not fire page view when consent is none', () => {
+    it('does not fire page view or session_start when consent is none', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'none' });
 
       expect(mockStart).toHaveBeenCalled();
       expect(mockEnqueue).not.toHaveBeenCalled();
     });
 
+    it('does not fire session_start for existing sessions', () => {
+      mockGetOrCreateSession.mockReturnValue({ sessionId: 'session-abc', isNew: false });
+
+      const pixel = new Pixel();
+      activePixel = pixel;
+      pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
+
+      const calls = mockEnqueue.mock.calls.map((c: unknown[]) => (c[0] as Record<string, unknown>));
+      const sessionStartCall = calls.find(
+        (c) => c.type === 'track' && c.eventName === 'session_start',
+      );
+
+      expect(sessionStartCall).toBeUndefined();
+      // Page view should still fire
+      expect(calls.find((c) => c.type === 'page')).toBeDefined();
+    });
+
     it('only initializes once', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
       pixel.init({ key: 'pk_other', environment: 'dev', consent: 'anonymous' });
 
-      // Start called only once
       expect(mockStart).toHaveBeenCalledTimes(1);
     });
   });
 
   describe('page', () => {
     it('enqueues a page message with attribution and session', () => {
+      mockGetOrCreateSession.mockReturnValue({ sessionId: 'session-abc', isNew: false });
+
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
-
-      // Clear the auto-fired page view
       mockEnqueue.mockClear();
 
       pixel.page({ custom: 'prop' });
@@ -121,6 +161,7 @@ describe('Pixel', () => {
 
     it('does not enqueue when consent is none', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'none' });
 
       pixel.page();
@@ -130,7 +171,10 @@ describe('Pixel', () => {
 
   describe('identify', () => {
     it('enqueues identify message at full consent', () => {
+      mockGetOrCreateSession.mockReturnValue({ sessionId: 'session-abc', isNew: false });
+
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'full' });
       mockEnqueue.mockClear();
 
@@ -151,23 +195,79 @@ describe('Pixel', () => {
 
     it('does not enqueue identify at anonymous consent', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
 
       pixel.identify('user-1');
-      // Only the auto page view, no identify
-      expect(mockEnqueue).toHaveBeenCalledTimes(1);
-      expect(mockEnqueue).toHaveBeenCalledWith(expect.objectContaining({ type: 'page' }));
+      // Only the auto page view + session_start, no identify
+      const calls = mockEnqueue.mock.calls.map((c: unknown[]) => (c[0] as Record<string, unknown>));
+      expect(calls.find((c) => c.type === 'identify')).toBeUndefined();
+    });
+  });
+
+  describe('session_end', () => {
+    it('fires session_end on pagehide when session is active', () => {
+      const pixel = new Pixel();
+      activePixel = pixel;
+      pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
+      mockEnqueue.mockClear();
+
+      // Simulate pagehide
+      window.dispatchEvent(new Event('pagehide'));
+
+      expect(mockEnqueue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'track',
+          eventName: 'session_end',
+          properties: expect.objectContaining({
+            sessionId: 'session-abc',
+          }),
+        }),
+      );
+    });
+
+    it('includes duration in session_end', () => {
+      const dateNowSpy = jest.spyOn(Date, 'now').mockReturnValue(1000000);
+
+      const pixel = new Pixel();
+      activePixel = pixel;
+      pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
+      mockEnqueue.mockClear();
+
+      // Advance time by 15 seconds before triggering pagehide
+      dateNowSpy.mockReturnValue(1015000);
+      window.dispatchEvent(new Event('pagehide'));
+
+      const sessionEndCall = mockEnqueue.mock.calls.find(
+        (c: unknown[]) => (c[0] as Record<string, unknown>).eventName === 'session_end',
+      );
+      expect(sessionEndCall).toBeDefined();
+      expect((sessionEndCall![0] as Record<string, unknown>).properties).toEqual(
+        expect.objectContaining({ duration: 15 }),
+      );
+
+      dateNowSpy.mockRestore();
+    });
+
+    it('does not fire session_end when consent is none', () => {
+      const pixel = new Pixel();
+      activePixel = pixel;
+      pixel.init({ key: 'pk_test', environment: 'dev', consent: 'none' });
+
+      window.dispatchEvent(new Event('pagehide'));
+      expect(mockEnqueue).not.toHaveBeenCalled();
     });
   });
 
   describe('setConsent', () => {
     it('updates consent level', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'none' });
 
       pixel.setConsent('anonymous');
 
-      // After upgrading consent, page() should work
+      mockGetOrCreateSession.mockReturnValue({ sessionId: 'session-xyz', isNew: false });
       pixel.page();
       expect(mockEnqueue).toHaveBeenCalledWith(expect.objectContaining({ type: 'page' }));
     });
@@ -176,6 +276,7 @@ describe('Pixel', () => {
   describe('destroy', () => {
     it('destroys the queue and resets state', () => {
       const pixel = new Pixel();
+      activePixel = pixel;
       pixel.init({ key: 'pk_test', environment: 'dev', consent: 'anonymous' });
 
       pixel.destroy();