onboardme-sdk 0.0.1

package/src/__tests__/week4-day1.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Week 4 Day 1 — Event Queue + API Client
+ *
+ * Tests for:
+ *   - src/core/event-batcher.ts (pushEvent, flushEvents, configureBatcher, queue limits)
+ *   - src/core/api-client.ts (postEvents: success, HTTP error, network error, timeout)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  configureBatcher,
+  pushEvent,
+  flushEvents,
+  _resetBatcher,
+  _getQueue,
+} from '../core/event-batcher.js';
+import { postEvents } from '../core/api-client.js';
+import { setDebug } from '../utils/logger.js';
+
+// ---------------------------------------------------------------------------
+// Shared setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  _resetBatcher();
+  vi.useFakeTimers();
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// configureBatcher
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 1 — configureBatcher', () => {
+  it('sets the endpoint used during flush', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-123');
+    pushEvent('flow_started');
+    await flushEvents();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:3001/events',
+      expect.objectContaining({ method: 'POST' }),
+    );
+  });
+
+  it('warns and does not send if flush is called before configureBatcher', async () => {
+    setDebug(true);
+    pushEvent('flow_started');
+    await flushEvents();
+    expect(console.warn).toHaveBeenCalled();
+    setDebug(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// pushEvent
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 1 — pushEvent', () => {
+  it('adds an event to the queue', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    expect(_getQueue()).toHaveLength(1);
+  });
+
+  it('auto-fills eventId as a UUID', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('step_viewed');
+    const [event] = _getQueue();
+    expect(event.eventId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+
+  it('auto-fills anonymousId from configureBatcher', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-xyz');
+    pushEvent('step_viewed');
+    expect(_getQueue()[0].anonymousId).toBe('anon-xyz');
+  });
+
+  it('auto-fills timestamp as a non-zero number', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('step_viewed');
+    expect(_getQueue()[0].timestamp).toBeGreaterThan(0);
+  });
+
+  it('sets the provided eventType', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('checklist_item_done', { flowId: 'f1', stepId: 's1' });
+    expect(_getQueue()[0].eventType).toBe('checklist_item_done');
+  });
+
+  it('preserves optional fields passed in partial', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('step_completed', { flowId: 'flow-1', stepId: 'step-1' });
+    const event = _getQueue()[0];
+    expect(event.flowId).toBe('flow-1');
+    expect(event.stepId).toBe('step-1');
+  });
+
+  it('accumulates multiple events', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    pushEvent('step_viewed');
+    pushEvent('step_completed');
+    expect(_getQueue()).toHaveLength(3);
+  });
+
+  it('drops the oldest event when queue exceeds 100 entries', () => {
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    for (let i = 0; i < 100; i++) pushEvent('step_viewed', { properties: { i } });
+    const firstId = _getQueue()[0].eventId;
+    pushEvent('flow_started'); // triggers drop
+    expect(_getQueue()).toHaveLength(100);
+    expect(_getQueue()[0].eventId).not.toBe(firstId); // oldest was dropped
+    expect(_getQueue()[99].eventType).toBe('flow_started');
+  });
+
+  it('warns when queue is full and an event is dropped', () => {
+    setDebug(true);
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    for (let i = 0; i < 101; i++) pushEvent('step_viewed');
+    expect(console.warn).toHaveBeenCalled();
+    setDebug(false);
+  });
+
+  it('starts the 5s auto-flush timer on the first event', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(fetchMock).toHaveBeenCalled();
+  });
+
+  it('does not start a second timer when more events are pushed', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    pushEvent('step_viewed');
+    pushEvent('step_completed');
+
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(fetchMock).toHaveBeenCalledTimes(1); // only one flush
+  });
+});
+
+// ---------------------------------------------------------------------------
+// flushEvents
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 1 — flushEvents', () => {
+  it('does nothing when the queue is empty', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    await flushEvents();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('sends all queued events in a single POST', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    pushEvent('step_viewed');
+    await flushEvents();
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.events).toHaveLength(2);
+  });
+
+  it('clears the queue on success', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }));
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    await flushEvents();
+    expect(_getQueue()).toHaveLength(0);
+  });
+
+  it('retains the queue on server error (non-2xx)', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500 }));
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    await flushEvents();
+    expect(_getQueue()).toHaveLength(1); // retained for retry
+  });
+
+  it('retains the queue on network error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network error')));
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    await flushEvents();
+    expect(_getQueue()).toHaveLength(1);
+  });
+
+  it('cancels the auto-flush timer when called manually', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    pushEvent('flow_started');
+    await flushEvents(); // manual flush
+    fetchMock.mockClear();
+
+    await vi.advanceTimersByTimeAsync(5_000); // timer should be cancelled
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// postEvents (api-client)
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 1 — postEvents (api-client)', () => {
+  it('returns true on a 2xx response', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }));
+    const result = await postEvents('http://localhost:3001/events', []);
+    expect(result).toBe(true);
+  });
+
+  it('returns false on a non-2xx response', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500 }));
+    const result = await postEvents('http://localhost:3001/events', []);
+    expect(result).toBe(false);
+  });
+
+  it('returns false on a network error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('Failed to fetch')));
+    const result = await postEvents('http://localhost:3001/events', []);
+    expect(result).toBe(false);
+  });
+
+  it('never throws — resolves even on network failure', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('timeout')));
+    await expect(postEvents('http://localhost:3001/events', [])).resolves.toBeDefined();
+  });
+
+  it('sends events as JSON body under the "events" key', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const mockEvent = {
+      eventId: 'e1',
+      anonymousId: 'a1',
+      eventType: 'flow_started' as const,
+      pageUrl: 'http://localhost',
+      timestamp: 1000,
+    };
+    await postEvents('http://localhost:3001/events', [mockEvent]);
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.events[0].eventId).toBe('e1');
+  });
+
+  it('uses POST method', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+    await postEvents('http://localhost:3001/events', []);
+    expect(fetchMock.mock.calls[0][1].method).toBe('POST');
+  });
+});

package/src/__tests__/week4-day2.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Week 4 Day 2 — Flush Mechanisms
+ *
+ * Tests for attachFlushListeners() in src/core/event-batcher.ts:
+ *   - visibilitychange → flush via fetch when tab hidden
+ *   - beforeunload → flush via sendBeacon (fire-and-forget)
+ *   - duplicate registration guard (listeners attached only once)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  configureBatcher,
+  pushEvent,
+  flushEvents,
+  attachFlushListeners,
+  _resetBatcher,
+  _detachFlushListeners,
+  _getQueue,
+} from '../core/event-batcher.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fireVisibilityChange(state: 'hidden' | 'visible') {
+  Object.defineProperty(document, 'visibilityState', {
+    value: state,
+    configurable: true,
+  });
+  document.dispatchEvent(new Event('visibilitychange'));
+}
+
+function fireBeforeUnload() {
+  window.dispatchEvent(new Event('beforeunload'));
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  _resetBatcher();
+  vi.useFakeTimers();
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  _detachFlushListeners(); // remove jsdom listeners so they don't accumulate across tests
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  Object.defineProperty(document, 'visibilityState', {
+    value: 'visible',
+    configurable: true,
+  });
+});
+
+// ---------------------------------------------------------------------------
+// visibilitychange
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 2 — visibilitychange flush', () => {
+  it('flushes events when the tab becomes hidden', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+
+    fireVisibilityChange('hidden');
+    await vi.runAllTimersAsync();
+
+    expect(fetchMock).toHaveBeenCalled();
+  });
+
+  it('clears the queue after a successful visibility flush', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }));
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+    pushEvent('step_viewed');
+
+    fireVisibilityChange('hidden');
+    await vi.runAllTimersAsync();
+
+    expect(_getQueue()).toHaveLength(0);
+  });
+
+  it('does NOT flush when tab becomes visible (only on hidden)', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+
+    fireVisibilityChange('visible');
+    // Use Promise.resolve() to flush microtasks only — does NOT advance the 5s auto-flush timer
+    await Promise.resolve();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when the queue is empty on visibilitychange', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    // no events pushed
+
+    fireVisibilityChange('hidden');
+    await vi.runAllTimersAsync();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// beforeunload / sendBeacon
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 2 — beforeunload sendBeacon flush', () => {
+  it('calls sendBeacon on beforeunload when there are queued events', () => {
+    const beaconMock = vi.fn().mockReturnValue(true);
+    vi.stubGlobal('navigator', { sendBeacon: beaconMock });
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+
+    fireBeforeUnload();
+
+    expect(beaconMock).toHaveBeenCalledWith(
+      'http://localhost:3001/events',
+      expect.any(Blob),
+    );
+  });
+
+  it('sends events JSON inside the Blob payload', () => {
+    const beaconMock = vi.fn().mockReturnValue(true);
+    vi.stubGlobal('navigator', { sendBeacon: beaconMock });
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+
+    fireBeforeUnload();
+
+    const blob: Blob = beaconMock.mock.calls[0][1];
+    expect(blob.type).toBe('application/json');
+  });
+
+  it('clears the queue after sendBeacon returns true', () => {
+    vi.stubGlobal('navigator', { sendBeacon: vi.fn().mockReturnValue(true) });
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+    pushEvent('step_viewed');
+
+    fireBeforeUnload();
+
+    expect(_getQueue()).toHaveLength(0);
+  });
+
+  it('retains the queue if sendBeacon returns false', () => {
+    vi.stubGlobal('navigator', { sendBeacon: vi.fn().mockReturnValue(false) });
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    pushEvent('flow_started');
+
+    fireBeforeUnload();
+
+    expect(_getQueue()).toHaveLength(1);
+  });
+
+  it('does not call sendBeacon when queue is empty', () => {
+    const beaconMock = vi.fn();
+    vi.stubGlobal('navigator', { sendBeacon: beaconMock });
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    // no events pushed
+
+    fireBeforeUnload();
+
+    expect(beaconMock).not.toHaveBeenCalled();
+  });
+
+  it('does not call sendBeacon when endpoint is not configured', () => {
+    const beaconMock = vi.fn();
+    vi.stubGlobal('navigator', { sendBeacon: beaconMock });
+
+    attachFlushListeners(); // no configureBatcher
+    pushEvent('flow_started');
+
+    fireBeforeUnload();
+
+    expect(beaconMock).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Duplicate registration guard
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 2 — duplicate listener guard', () => {
+  it('calling attachFlushListeners twice only registers listeners once', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    configureBatcher('http://localhost:3001/events', 'anon-1');
+    attachFlushListeners();
+    attachFlushListeners(); // second call should be a no-op
+    pushEvent('flow_started');
+
+    fireVisibilityChange('hidden');
+    await vi.runAllTimersAsync();
+
+    // fetch called exactly once — not twice due to duplicate listener
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});