onboardme-sdk 0.0.1

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

@@ -0,0 +1,323 @@
+/**
+ * Week 4 Day 3 — Wire All SDK Actions into Event Stream
+ *
+ * Verifies that every user-facing SDK action enqueues the correct event:
+ *
+ * runSDK:
+ *   ✓ configureBatcher is called (events have the correct anonymousId after init)
+ *
+ * showModal:
+ *   ✓ Enqueues flow_started with correct flowId
+ *   ✓ Enqueues step_viewed with correct stepId + stepIndex: 0
+ *   ✓ CTA click → step_completed (stepId + flowId correct)
+ *   ✓ Skip click → step_skipped
+ *   ✓ Escape key → step_skipped
+ *   ✓ Session guard prevents duplicate flow_started on second call
+ *
+ * renderChecklist:
+ *   ✓ Enqueues step_viewed with checklist stepId + flowId
+ *   ✓ Item click → checklist_item_done with itemId as stepId
+ *   ✓ Already-done item click does NOT emit checklist_item_done
+ *   ✓ Auto-check via track() → checklist_item_done
+ *
+ * identify() + track():
+ *   ✓ Events before identify() have no userId
+ *   ✓ Events after identify() carry the userId
+ *   ✓ track() enqueues step_action_taken
+ *   ✓ step_action_taken carries eventName and extra properties
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  configureBatcher,
+  _resetBatcher,
+  _getQueue,
+  _detachFlushListeners,
+  setBatcherUserId,
+  pushEvent,
+} from '../core/event-batcher.js';
+import { showModal } from '../components/modal.js';
+import { renderChecklist } from '../components/checklist.js';
+import { getShadowRoot } from '../components/shadow-host.js';
+import OnboardMe, { _resetIndex } from '../index.js';
+import { _resetSDK } from '../core/sdk.js';
+import type { FlowStep, FlowConfig } from '@onboardme/types';
+import type { Progress } from '../storage/progress-tracker.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const FLOW_ID = 'flow-welcome';
+const MODAL_STEP_ID = 'step-modal-1';
+const CHECKLIST_STEP_ID = 'step-checklist-1';
+const ITEM_ID_1 = 'item-profile';
+const ITEM_ID_2 = 'item-invite';
+
+const modalStep: FlowStep = {
+  id: MODAL_STEP_ID,
+  type: 'modal',
+  order: 1,
+  title: 'Welcome',
+  body: 'Let us show you around.',
+  trigger: { type: 'page_load' },
+};
+
+const flow: FlowConfig = {
+  id: FLOW_ID,
+  name: 'Welcome Flow',
+  priority: 1,
+  completionGoal: 'setup_complete',
+  steps: [
+    modalStep,
+    {
+      id: CHECKLIST_STEP_ID,
+      type: 'checklist',
+      order: 2,
+      title: 'Get started',
+      body: '',
+      trigger: { type: 'page_load' },
+      items: [
+        { id: ITEM_ID_1, label: 'Complete profile', order: 1, completionEvent: 'profile_completed' },
+        { id: ITEM_ID_2, label: 'Invite a teammate', order: 2 },
+      ],
+    },
+  ],
+};
+
+const EMPTY_PROGRESS: Progress = { completedSteps: [], lastUpdated: 0 };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function freshShadow(): ShadowRoot {
+  document.body.innerHTML = '';
+  return getShadowRoot();
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+// Preserve the original track so tests that patch it can restore it
+const originalTrack = OnboardMe.track;
+
+beforeEach(() => {
+  _resetBatcher();
+  configureBatcher('http://localhost:3001/events', 'anon-test');
+  sessionStorage.clear();
+  localStorage.clear();
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  OnboardMe.track = originalTrack;
+  _detachFlushListeners();
+  vi.restoreAllMocks();
+  document.body.innerHTML = '';
+  sessionStorage.clear();
+  localStorage.clear();
+});
+
+// ---------------------------------------------------------------------------
+// runSDK wires batcher
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 3 — runSDK wires batcher', () => {
+  it('after init() events carry the anonymousId set by configureBatcher', () => {
+    _resetSDK();
+    _resetIndex();
+    _resetBatcher();
+
+    // Returning user — no modal/checklist side effects
+    localStorage.setItem('onboardme_seen_wire-test', '1');
+
+    vi.useFakeTimers();
+    OnboardMe.init({ productId: 'wire-test', flows: [] });
+    vi.runAllTimers();
+    vi.useRealTimers();
+
+    // Push an event after init — batcher should have been configured with the anon ID
+    pushEvent('flow_started');
+    const event = _getQueue().find((e) => e.eventType === 'flow_started');
+    expect(event?.anonymousId).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showModal events
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 3 — showModal events', () => {
+  it('enqueues flow_started when the modal is shown', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    expect(_getQueue().some((e) => e.eventType === 'flow_started')).toBe(true);
+  });
+
+  it('flow_started carries the correct flowId', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    const event = _getQueue().find((e) => e.eventType === 'flow_started');
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('enqueues step_viewed when the modal is shown', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    expect(_getQueue().some((e) => e.eventType === 'step_viewed')).toBe(true);
+  });
+
+  it('step_viewed carries correct stepId, flowId, and stepIndex 0', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    const event = _getQueue().find((e) => e.eventType === 'step_viewed');
+    expect(event?.stepId).toBe(MODAL_STEP_ID);
+    expect(event?.flowId).toBe(FLOW_ID);
+    expect(event?.stepIndex).toBe(0);
+  });
+
+  it('clicking the primary CTA enqueues step_completed', () => {
+    const sr = freshShadow();
+    showModal(modalStep, sr, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')?.click();
+    expect(_getQueue().some((e) => e.eventType === 'step_completed')).toBe(true);
+  });
+
+  it('step_completed carries correct stepId and flowId', () => {
+    const sr = freshShadow();
+    showModal(modalStep, sr, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')?.click();
+    const event = _getQueue().find((e) => e.eventType === 'step_completed');
+    expect(event?.stepId).toBe(MODAL_STEP_ID);
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('clicking the skip button enqueues step_skipped', () => {
+    const sr = freshShadow();
+    showModal(modalStep, sr, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLButtonElement>('[data-onboardme="skip-cta"]')?.click();
+    expect(_getQueue().some((e) => e.eventType === 'step_skipped')).toBe(true);
+  });
+
+  it('pressing Escape enqueues step_skipped', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(_getQueue().some((e) => e.eventType === 'step_skipped')).toBe(true);
+  });
+
+  it('session guard prevents a second flow_started on duplicate showModal call', () => {
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    // Second call blocked by sessionStorage guard
+    showModal(modalStep, freshShadow(), 'prod-1', FLOW_ID);
+    const flowStarted = _getQueue().filter((e) => e.eventType === 'flow_started');
+    expect(flowStarted).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderChecklist events
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 3 — renderChecklist events', () => {
+  it('enqueues step_viewed when the checklist is rendered', () => {
+    renderChecklist(flow, EMPTY_PROGRESS, freshShadow(), false, 'prod-1', FLOW_ID);
+    expect(_getQueue().some((e) => e.eventType === 'step_viewed')).toBe(true);
+  });
+
+  it('step_viewed carries the checklist stepId and flowId', () => {
+    renderChecklist(flow, EMPTY_PROGRESS, freshShadow(), false, 'prod-1', FLOW_ID);
+    const event = _getQueue().find((e) => e.eventType === 'step_viewed');
+    expect(event?.stepId).toBe(CHECKLIST_STEP_ID);
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('clicking an unchecked item enqueues checklist_item_done', () => {
+    const sr = freshShadow();
+    renderChecklist(flow, EMPTY_PROGRESS, sr, false, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLLIElement>(`[data-item-id="${ITEM_ID_1}"]`)?.click();
+    expect(_getQueue().some((e) => e.eventType === 'checklist_item_done')).toBe(true);
+  });
+
+  it('checklist_item_done carries the itemId as stepId and the flowId', () => {
+    const sr = freshShadow();
+    renderChecklist(flow, EMPTY_PROGRESS, sr, false, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLLIElement>(`[data-item-id="${ITEM_ID_1}"]`)?.click();
+    const event = _getQueue().find((e) => e.eventType === 'checklist_item_done');
+    expect(event?.stepId).toBe(ITEM_ID_1);
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('clicking an already-done item does NOT emit checklist_item_done', () => {
+    const sr = freshShadow();
+    const doneProgress: Progress = { completedSteps: [ITEM_ID_1], lastUpdated: Date.now() };
+    renderChecklist(flow, doneProgress, sr, false, 'prod-1', FLOW_ID);
+    sr.querySelector<HTMLLIElement>(`[data-item-id="${ITEM_ID_1}"]`)?.click();
+    const done = _getQueue().filter(
+      (e) => e.eventType === 'checklist_item_done' && e.stepId === ITEM_ID_1,
+    );
+    expect(done).toHaveLength(0);
+  });
+
+  it('auto-check via OnboardMe.track enqueues checklist_item_done', () => {
+    const sr = freshShadow();
+    renderChecklist(flow, EMPTY_PROGRESS, sr, false, 'prod-1', FLOW_ID);
+    // watchCompletionEvents patches OnboardMe.track; firing 'profile_completed' auto-checks ITEM_ID_1
+    OnboardMe.track('profile_completed');
+    expect(
+      _getQueue().some((e) => e.eventType === 'checklist_item_done' && e.stepId === ITEM_ID_1),
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// identify() + track() wiring
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 3 — identify() wiring', () => {
+  it('events pushed before identify() have no userId', () => {
+    pushEvent('flow_started');
+    expect(_getQueue().find((e) => e.eventType === 'flow_started')?.userId).toBeUndefined();
+  });
+
+  it('events pushed after setBatcherUserId (identify wiring) carry the userId', () => {
+    setBatcherUserId('user-abc');
+    pushEvent('step_viewed');
+    expect(_getQueue().find((e) => e.eventType === 'step_viewed')?.userId).toBe('user-abc');
+  });
+});
+
+describe('Week 4 Day 3 — track() wiring', () => {
+  const PRODUCT = 'track-wire-test';
+
+  beforeEach(() => {
+    localStorage.setItem(`onboardme_seen_${PRODUCT}`, '1'); // returning user
+    _resetSDK();
+    _resetIndex();
+    _resetBatcher();
+    vi.useFakeTimers();
+    OnboardMe.init({ productId: PRODUCT, flows: [] });
+    vi.runAllTimers();
+    vi.useRealTimers();
+  });
+
+  afterEach(() => {
+    localStorage.removeItem(`onboardme_seen_${PRODUCT}`);
+  });
+
+  it('track() enqueues a step_action_taken event', () => {
+    OnboardMe.track('button_clicked');
+    expect(_getQueue().some((e) => e.eventType === 'step_action_taken')).toBe(true);
+  });
+
+  it('step_action_taken properties contain the eventName', () => {
+    OnboardMe.track('button_clicked');
+    const event = _getQueue().find((e) => e.eventType === 'step_action_taken');
+    expect(event?.properties?.['eventName']).toBe('button_clicked');
+  });
+
+  it('step_action_taken properties include extra properties from the caller', () => {
+    OnboardMe.track('button_clicked', { color: 'blue', count: 3 });
+    const event = _getQueue().find((e) => e.eventType === 'step_action_taken');
+    expect(event?.properties?.['color']).toBe('blue');
+    expect(event?.properties?.['count']).toBe(3);
+  });
+});

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

@@ -0,0 +1,210 @@
+/**
+ * Week 4 Day 4 — Completion Goal + Celebration Banner
+ *
+ * Verifies that calling OnboardMe.track(completionGoal) triggers the full
+ * goal-completion sequence:
+ *
+ * goal detection:
+ *   ✓ track(completionGoal) enqueues flow_completed with correct flowId
+ *   ✓ track(completionGoal) enqueues goal_reached with correct flowId
+ *   ✓ track(otherEvent) does NOT enqueue flow_completed or goal_reached
+ *   ✓ track(completionGoal) called twice → goal_reached fires only once (localStorage guard)
+ *   ✓ flow_completed fires only once on repeated track(completionGoal) calls
+ *
+ * celebration banner:
+ *   ✓ track(completionGoal) renders .om-celebration inside the shadow root
+ *   ✓ banner text is "🎉 You're all set!"
+ *   ✓ banner auto-removes after 3 seconds
+ *   ✓ banner does NOT appear when track(otherEvent) is called
+ *   ✓ second track(completionGoal) after guard fires does NOT render another banner
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  configureBatcher,
+  _resetBatcher,
+  _getQueue,
+  _detachFlushListeners,
+} from '../core/event-batcher.js';
+import { getShadowRoot } from '../components/shadow-host.js';
+import OnboardMe, { _resetIndex } from '../index.js';
+import { _resetSDK } from '../core/sdk.js';
+import type { FlowConfig } from '@onboardme/types';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const PRODUCT = 'goal-test-product';
+const FLOW_ID = 'flow-onboarding';
+const COMPLETION_GOAL = 'created_first_project';
+
+const flow: FlowConfig = {
+  id: FLOW_ID,
+  name: 'Onboarding Flow',
+  priority: 1,
+  completionGoal: COMPLETION_GOAL,
+  steps: [],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function initSDK() {
+  _resetSDK();
+  _resetIndex();
+  _resetBatcher();
+  // returning user — no modal/checklist side-effects
+  localStorage.setItem(`onboardme_seen_${PRODUCT}`, '1');
+  vi.useFakeTimers();
+  OnboardMe.init({ productId: PRODUCT, flows: [flow] });
+  vi.runAllTimers();
+  vi.useRealTimers();
+}
+
+function shadowRoot(): ShadowRoot {
+  return getShadowRoot();
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  _resetBatcher();
+  configureBatcher('http://localhost:3001/events', 'anon-test');
+  localStorage.clear();
+  sessionStorage.clear();
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  _detachFlushListeners();
+  vi.restoreAllMocks();
+  document.body.innerHTML = '';
+  localStorage.clear();
+  sessionStorage.clear();
+});
+
+// ---------------------------------------------------------------------------
+// Goal detection
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 4 — goal detection', () => {
+  it('track(completionGoal) enqueues flow_completed', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(_getQueue().some((e) => e.eventType === 'flow_completed')).toBe(true);
+  });
+
+  it('flow_completed carries the correct flowId', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    const event = _getQueue().find((e) => e.eventType === 'flow_completed');
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('track(completionGoal) enqueues goal_reached', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(_getQueue().some((e) => e.eventType === 'goal_reached')).toBe(true);
+  });
+
+  it('goal_reached carries the correct flowId', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    const event = _getQueue().find((e) => e.eventType === 'goal_reached');
+    expect(event?.flowId).toBe(FLOW_ID);
+  });
+
+  it('track(otherEvent) does NOT enqueue flow_completed', () => {
+    initSDK();
+    OnboardMe.track('some_other_event');
+    expect(_getQueue().some((e) => e.eventType === 'flow_completed')).toBe(false);
+  });
+
+  it('track(otherEvent) does NOT enqueue goal_reached', () => {
+    initSDK();
+    OnboardMe.track('some_other_event');
+    expect(_getQueue().some((e) => e.eventType === 'goal_reached')).toBe(false);
+  });
+
+  it('track(completionGoal) twice → goal_reached fires only once (localStorage guard)', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    OnboardMe.track(COMPLETION_GOAL);
+    const goalReached = _getQueue().filter((e) => e.eventType === 'goal_reached');
+    expect(goalReached).toHaveLength(1);
+  });
+
+  it('track(completionGoal) twice → flow_completed fires only once', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    OnboardMe.track(COMPLETION_GOAL);
+    const flowCompleted = _getQueue().filter((e) => e.eventType === 'flow_completed');
+    expect(flowCompleted).toHaveLength(1);
+  });
+
+  it('localStorage guard key is set after first track(completionGoal)', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(localStorage.getItem(`onboardme_flow_done_${PRODUCT}_${FLOW_ID}`)).toBe('1');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Celebration banner
+// ---------------------------------------------------------------------------
+
+describe('Week 4 Day 4 — celebration banner', () => {
+  it('track(completionGoal) renders .om-celebration in the shadow root', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(shadowRoot().querySelector('.om-celebration')).not.toBeNull();
+  });
+
+  it('banner text is "🎉 You\'re all set!"', () => {
+    initSDK();
+    OnboardMe.track(COMPLETION_GOAL);
+    const banner = shadowRoot().querySelector('.om-celebration');
+    expect(banner?.textContent).toBe("🎉 You're all set!");
+  });
+
+  it('banner auto-removes after 3 seconds', () => {
+    initSDK();
+    vi.useFakeTimers();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(shadowRoot().querySelector('.om-celebration')).not.toBeNull();
+    vi.advanceTimersByTime(3000);
+    expect(shadowRoot().querySelector('.om-celebration')).toBeNull();
+    vi.useRealTimers();
+  });
+
+  it('banner is still present before 3 seconds have elapsed', () => {
+    initSDK();
+    vi.useFakeTimers();
+    OnboardMe.track(COMPLETION_GOAL);
+    vi.advanceTimersByTime(2999);
+    expect(shadowRoot().querySelector('.om-celebration')).not.toBeNull();
+    vi.useRealTimers();
+  });
+
+  it('track(otherEvent) does NOT render a celebration banner', () => {
+    initSDK();
+    OnboardMe.track('some_other_event');
+    expect(shadowRoot().querySelector('.om-celebration')).toBeNull();
+  });
+
+  it('second track(completionGoal) after guard does NOT render another banner', () => {
+    initSDK();
+    vi.useFakeTimers();
+    OnboardMe.track(COMPLETION_GOAL);
+    vi.advanceTimersByTime(3000); // first banner removed
+    OnboardMe.track(COMPLETION_GOAL); // guard prevents second banner
+    expect(shadowRoot().querySelector('.om-celebration')).toBeNull();
+    vi.useRealTimers();
+  });
+});