onboardme-sdk 0.0.1

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

@@ -0,0 +1,503 @@
+/**
+ * Week 4 Day 5 — Full Test Suite + Phase 1 Verification
+ *
+ * Master integration test that exercises every item on the Phase 1
+ * completion checklist end-to-end through the public SDK API.
+ *
+ * Phase 1 checklist:
+ *   ✓ New user       → welcome modal appears within 500ms of init()
+ *   ✓ Returning user → no modal rendered
+ *   ✓ Modal dismiss  → session flag set; modal does not reappear this session
+ *   ✓ Checklist persistence → checked items survive page reload
+ *   ✓ Auto-check     → track(completionEvent) checks matching item without click
+ *   ✓ Completion goal → track(completionGoal) fires flow_completed + goal_reached
+ *   ✓ Double goal    → track(completionGoal) called twice → goal_reached fires once
+ *   ✓ Celebration    → .om-celebration banner appears and auto-removes after 3s
+ *   ✓ Event shape    → events carry eventId, anonymousId, eventType, pageUrl, timestamp
+ *   ✓ userId         → absent before identify(); present after identify()
+ *   ✓ Event stream   → modal, checklist, goal events all land in the queue with correct types
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import OnboardMe, { _resetIndex } from '../index.js';
+import { _resetSDK } from '../core/sdk.js';
+import {
+  configureBatcher,
+  _resetBatcher,
+  _getQueue,
+  _detachFlushListeners,
+  setBatcherUserId,
+  pushEvent,
+} from '../core/event-batcher.js';
+import {
+  loadProgress,
+  markStepComplete,
+  isStepComplete,
+  clearProgress,
+} from '../storage/progress-tracker.js';
+import { getShadowRoot } from '../components/shadow-host.js';
+import { renderChecklist } from '../components/checklist.js';
+import type { FlowConfig, ChecklistItem } from '@onboardme/types';
+import type { Progress } from '../storage/progress-tracker.js';
+
+// ---------------------------------------------------------------------------
+// Reference fixtures — one flow config used across the whole test file
+// ---------------------------------------------------------------------------
+
+const PID = 'phase1-verify';
+const FLOW_MODAL_ID = 'flow-welcome';
+const FLOW_CHECKLIST_ID = 'flow-checklist';
+const COMPLETION_GOAL = 'onboarding_complete';
+
+const ITEMS: ChecklistItem[] = [
+  { id: 'profile',  label: 'Create your profile',  order: 1, required: true,  completionEvent: 'profile_created'   },
+  { id: 'teammate', label: 'Invite a teammate',     order: 2, required: true,  completionEvent: 'teammate_invited'  },
+  { id: 'project',  label: 'Create first project',  order: 3, required: true                                        },
+  { id: 'docs',     label: 'Explore the docs',      order: 4, required: false                                       },
+];
+
+const MODAL_FLOW: FlowConfig = {
+  id: FLOW_MODAL_ID,
+  name: 'Welcome flow',
+  completionGoal: 'modal_complete',
+  priority: 1,
+  steps: [
+    {
+      id: 'step-welcome',
+      type: 'modal',
+      order: 1,
+      title: 'Welcome!',
+      body: 'Quick tour.',
+      trigger: { type: 'page_load' },
+      dismissible: true,
+    },
+  ],
+};
+
+const CHECKLIST_FLOW: FlowConfig = {
+  id: FLOW_CHECKLIST_ID,
+  name: 'Getting started',
+  completionGoal: COMPLETION_GOAL,
+  priority: 2,
+  steps: [
+    {
+      id: 'cl-step',
+      type: 'checklist',
+      order: 1,
+      title: 'Getting started',
+      body: '',
+      trigger: { type: 'page_load' },
+      items: ITEMS,
+    },
+  ],
+};
+
+const EMPTY: Progress = { completedSteps: [], lastUpdated: 0 };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Full init for a new user (no returning flag in localStorage). */
+function initNew(flows: FlowConfig[] = [MODAL_FLOW, CHECKLIST_FLOW]) {
+  _resetSDK();
+  _resetIndex();
+  _resetBatcher();
+  localStorage.clear();
+  sessionStorage.clear();
+  document.body.innerHTML = '';
+  vi.useFakeTimers();
+  OnboardMe.init({ productId: PID, flows });
+  vi.runAllTimers();
+  vi.useRealTimers();
+}
+
+/** Full init for a returning user. */
+function initReturning(flows: FlowConfig[] = [MODAL_FLOW, CHECKLIST_FLOW]) {
+  _resetSDK();
+  _resetIndex();
+  _resetBatcher();
+  sessionStorage.clear();
+  document.body.innerHTML = '';
+  localStorage.setItem(`onboardme_seen_${PID}`, '1');
+  vi.useFakeTimers();
+  OnboardMe.init({ productId: PID, flows });
+  vi.runAllTimers();
+  vi.useRealTimers();
+}
+
+function shadow(): ShadowRoot {
+  return document.getElementById('onboardme-root')!.shadowRoot!;
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+const originalTrack = OnboardMe.track;
+
+beforeEach(() => {
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  OnboardMe.track = originalTrack;
+  _detachFlushListeners();
+  _resetBatcher();
+  _resetSDK();
+  _resetIndex();
+  vi.restoreAllMocks();
+  document.body.innerHTML = '';
+  localStorage.clear();
+  sessionStorage.clear();
+  clearProgress(PID, FLOW_CHECKLIST_ID);
+});
+
+// ---------------------------------------------------------------------------
+// 1. New user → welcome modal appears within 500ms
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — new user → modal appears', () => {
+  it('modal is absent immediately after init() (deferred render)', () => {
+    _resetSDK(); _resetIndex(); _resetBatcher();
+    localStorage.clear(); sessionStorage.clear(); document.body.innerHTML = '';
+    vi.useFakeTimers();
+    OnboardMe.init({ productId: PID, flows: [MODAL_FLOW] });
+    // Before timer flush — not yet shown
+    expect(document.getElementById('onboardme-root')?.shadowRoot?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+    vi.useRealTimers();
+  });
+
+  it('modal appears after timer flush — well within 500ms', () => {
+    initNew([MODAL_FLOW]);
+    expect(shadow().querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('modal shows correct title and body', () => {
+    initNew([MODAL_FLOW]);
+    expect(shadow().querySelector('.om-modal__title')?.textContent).toBe('Welcome!');
+    expect(shadow().querySelector('.om-modal__body')?.textContent).toBe('Quick tour.');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Returning user → no modal
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — returning user → no modal', () => {
+  it('no modal rendered when localStorage returning flag is set', () => {
+    initReturning([MODAL_FLOW]);
+    expect(document.getElementById('onboardme-root')?.shadowRoot?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Modal dismiss → session flag set; modal does not reappear this session
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — modal dismiss + session guard', () => {
+  it('clicking CTA removes the modal', () => {
+    initNew([MODAL_FLOW]);
+    shadow().querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(shadow().querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('clicking CTA sets the session flag', () => {
+    initNew([MODAL_FLOW]);
+    shadow().querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(sessionStorage.getItem(`onboardme_modal_shown_${PID}`)).not.toBeNull();
+  });
+
+  it('second init() in same session does not re-show modal (session guard)', () => {
+    initNew([MODAL_FLOW]);
+    shadow().querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    // Simulate second page-load in same session by running through init again
+    _resetSDK(); _resetIndex(); _resetBatcher();
+    document.body.innerHTML = '';
+    vi.useFakeTimers();
+    // Keep sessionStorage as-is (same session), but mark as returning
+    localStorage.setItem(`onboardme_seen_${PID}`, '1');
+    OnboardMe.init({ productId: PID, flows: [MODAL_FLOW] });
+    vi.runAllTimers();
+    vi.useRealTimers();
+    // Returning user → no modal attempted
+    expect(document.getElementById('onboardme-root')?.shadowRoot?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Checklist persistence — checked items survive page reload
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — checklist persistence across reload', () => {
+  it('items marked complete persist in localStorage', () => {
+    initReturning();
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'profile');
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'project');
+    expect(isStepComplete(PID, FLOW_CHECKLIST_ID, 'profile')).toBe(true);
+    expect(isStepComplete(PID, FLOW_CHECKLIST_ID, 'project')).toBe(true);
+  });
+
+  it('reload (re-render with saved progress) shows correct checked state', () => {
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'profile');
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'teammate');
+    const sr = getShadowRoot();
+    const saved = loadProgress(PID, FLOW_CHECKLIST_ID);
+    renderChecklist(CHECKLIST_FLOW, saved, sr, false, PID, FLOW_CHECKLIST_ID);
+
+    expect(sr.querySelector('[data-item-id="profile"]')?.classList.contains('om-checklist__item--done')).toBe(true);
+    expect(sr.querySelector('[data-item-id="teammate"]')?.classList.contains('om-checklist__item--done')).toBe(true);
+    expect(sr.querySelector('[data-item-id="project"]')?.classList.contains('om-checklist__item--done')).toBe(false);
+  });
+
+  it('progress bar reflects reloaded state correctly', () => {
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'profile');
+    markStepComplete(PID, FLOW_CHECKLIST_ID, 'project');
+    const sr = getShadowRoot();
+    const saved = loadProgress(PID, FLOW_CHECKLIST_ID);
+    renderChecklist(CHECKLIST_FLOW, saved, sr, false, PID, FLOW_CHECKLIST_ID);
+    // 2 of 3 required → 67%
+    const fill = sr.querySelector<HTMLElement>('.om-checklist__progress-bar-fill');
+    expect(fill?.style.width).toBe('67%');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Auto-check via track(completionEvent)
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — auto-check via track(completionEvent)', () => {
+  it('track(completionEvent) checks the matching item without a click', () => {
+    const sr = getShadowRoot();
+    renderChecklist(CHECKLIST_FLOW, EMPTY, sr, false, PID, FLOW_CHECKLIST_ID);
+    OnboardMe.track('profile_created');
+    expect(sr.querySelector('[data-item-id="profile"]')?.classList.contains('om-checklist__item--done')).toBe(true);
+  });
+
+  it('auto-check saves the completion to localStorage', () => {
+    const sr = getShadowRoot();
+    renderChecklist(CHECKLIST_FLOW, EMPTY, sr, false, PID, FLOW_CHECKLIST_ID);
+    OnboardMe.track('teammate_invited');
+    expect(isStepComplete(PID, FLOW_CHECKLIST_ID, 'teammate')).toBe(true);
+  });
+
+  it('unrelated track() call does not check any item', () => {
+    const sr = getShadowRoot();
+    renderChecklist(CHECKLIST_FLOW, EMPTY, sr, false, PID, FLOW_CHECKLIST_ID);
+    OnboardMe.track('some_random_event');
+    const doneCls = 'om-checklist__item--done';
+    const anyDone = Array.from(sr.querySelectorAll('[data-item-id]')).some(
+      (el) => el.classList.contains(doneCls),
+    );
+    expect(anyDone).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Completion goal → flow_completed + goal_reached + celebration
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — completion goal', () => {
+  it('track(completionGoal) enqueues flow_completed', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(_getQueue().some((e) => e.eventType === 'flow_completed')).toBe(true);
+  });
+
+  it('track(completionGoal) enqueues goal_reached', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(_getQueue().some((e) => e.eventType === 'goal_reached')).toBe(true);
+  });
+
+  it('goal_reached carries the correct flowId', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    const ev = _getQueue().find((e) => e.eventType === 'goal_reached');
+    expect(ev?.flowId).toBe(FLOW_CHECKLIST_ID);
+  });
+
+  it('track(completionGoal) renders the .om-celebration banner', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    const sr = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(sr.querySelector('.om-celebration')).not.toBeNull();
+  });
+
+  it('celebration banner text is correct', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    const banner = document.getElementById('onboardme-root')!.shadowRoot!.querySelector('.om-celebration');
+    expect(banner?.textContent).toBe("🎉 You're all set!");
+  });
+
+  it('celebration banner auto-removes after 3 seconds', () => {
+    initReturning();
+    vi.useFakeTimers();
+    OnboardMe.track(COMPLETION_GOAL);
+    vi.advanceTimersByTime(3000);
+    const sr = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(sr.querySelector('.om-celebration')).toBeNull();
+    vi.useRealTimers();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Double goal → goal_reached fires only once
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — double goal guard', () => {
+  it('goal_reached fires only once when track(completionGoal) is called twice', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    OnboardMe.track(COMPLETION_GOAL);
+    const goalReached = _getQueue().filter((e) => e.eventType === 'goal_reached');
+    expect(goalReached).toHaveLength(1);
+  });
+
+  it('flow_completed fires only once on repeated calls', () => {
+    initReturning();
+    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 and prevents second fire', () => {
+    initReturning();
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(localStorage.getItem(`onboardme_flow_done_${PID}_${FLOW_CHECKLIST_ID}`)).toBe('1');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. Event shape — correct fields on every event
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — event shape', () => {
+  beforeEach(() => {
+    _resetBatcher();
+    configureBatcher('http://localhost:3001/events', 'anon-shape-test');
+  });
+
+  it('every event has a non-empty eventId', () => {
+    pushEvent('flow_started', { flowId: 'f1' });
+    const ev = _getQueue()[0];
+    expect(ev.eventId).toBeTruthy();
+    expect(typeof ev.eventId).toBe('string');
+  });
+
+  it('every event has a non-empty anonymousId', () => {
+    pushEvent('flow_started', { flowId: 'f1' });
+    expect(_getQueue()[0].anonymousId).toBe('anon-shape-test');
+  });
+
+  it('every event has a timestamp (number)', () => {
+    pushEvent('step_viewed', { stepId: 's1' });
+    expect(typeof _getQueue()[0].timestamp).toBe('number');
+    expect(_getQueue()[0].timestamp).toBeGreaterThan(0);
+  });
+
+  it('every event has a pageUrl string', () => {
+    pushEvent('step_viewed', { stepId: 's1' });
+    expect(typeof _getQueue()[0].pageUrl).toBe('string');
+  });
+
+  it('every event carries the correct eventType', () => {
+    pushEvent('goal_reached', { flowId: 'f1' });
+    expect(_getQueue()[0].eventType).toBe('goal_reached');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. userId on events — absent before identify(), present after
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — userId on events', () => {
+  beforeEach(() => {
+    _resetBatcher();
+    configureBatcher('http://localhost:3001/events', 'anon-user-test');
+  });
+
+  it('userId is absent on events pushed before identify()', () => {
+    pushEvent('flow_started');
+    expect(_getQueue()[0].userId).toBeUndefined();
+  });
+
+  it('userId is present on events pushed after setBatcherUserId()', () => {
+    setBatcherUserId('user-xyz');
+    pushEvent('step_viewed');
+    expect(_getQueue()[0].userId).toBe('user-xyz');
+  });
+
+  it('identify() wires through to event queue via OnboardMe.identify()', () => {
+    initReturning();
+    OnboardMe.identify('real-user-123');
+    OnboardMe.track('something');
+    const ev = _getQueue().find((e) => e.eventType === 'step_action_taken');
+    expect(ev?.userId).toBe('real-user-123');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. Full Phase 1 end-to-end lifecycle
+// ---------------------------------------------------------------------------
+
+describe('Phase 1 — full end-to-end lifecycle', () => {
+  it('complete lifecycle: init → modal → dismiss → checklist → auto-check → goal → celebration', () => {
+    // 1. New user — init
+    _resetSDK(); _resetIndex(); _resetBatcher();
+    localStorage.clear(); sessionStorage.clear(); document.body.innerHTML = '';
+    vi.useFakeTimers();
+    OnboardMe.init({ productId: PID, flows: [MODAL_FLOW, CHECKLIST_FLOW] });
+    vi.runAllTimers();
+    vi.useRealTimers();
+
+    const sr = document.getElementById('onboardme-root')!.shadowRoot!;
+
+    // 2. Modal appeared
+    expect(sr.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+
+    // 3. Click CTA → modal closes, step_completed enqueued
+    sr.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(sr.querySelector('[data-onboardme="overlay"]')).toBeNull();
+    expect(_getQueue().some((e) => e.eventType === 'step_completed')).toBe(true);
+
+    // 4. Checklist is rendered (step_viewed enqueued)
+    expect(sr.querySelector('[data-onboardme="checklist"]')).not.toBeNull();
+    expect(_getQueue().some((e) => e.eventType === 'step_viewed')).toBe(true);
+
+    // 5. Manual check on item
+    sr.querySelector<HTMLLIElement>('[data-item-id="project"]')!.click();
+    expect(sr.querySelector('[data-item-id="project"]')?.classList.contains('om-checklist__item--done')).toBe(true);
+    expect(_getQueue().some((e) => e.eventType === 'checklist_item_done')).toBe(true);
+
+    // 6. Auto-check via track
+    OnboardMe.track('profile_created');
+    expect(sr.querySelector('[data-item-id="profile"]')?.classList.contains('om-checklist__item--done')).toBe(true);
+
+    // 7. Completion goal
+    OnboardMe.track(COMPLETION_GOAL);
+    expect(_getQueue().some((e) => e.eventType === 'flow_completed')).toBe(true);
+    expect(_getQueue().some((e) => e.eventType === 'goal_reached')).toBe(true);
+
+    // 8. Celebration banner visible
+    expect(sr.querySelector('.om-celebration')).not.toBeNull();
+
+    // 9. All progress persisted
+    expect(isStepComplete(PID, FLOW_CHECKLIST_ID, 'project')).toBe(true);
+    expect(isStepComplete(PID, FLOW_CHECKLIST_ID, 'profile')).toBe(true);
+
+    // 10. Event log has expected event types
+    const queue = _getQueue();
+    const types = queue.map((e) => e.eventType);
+    expect(types).toContain('flow_started');
+    expect(types).toContain('step_completed');
+    expect(types).toContain('step_viewed');
+    expect(types).toContain('checklist_item_done');
+    expect(types).toContain('step_action_taken');
+    expect(types).toContain('flow_completed');
+    expect(types).toContain('goal_reached');
+  });
+});

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

@@ -0,0 +1,152 @@
+/**
+ * Week 5 Day 1 — AutoGenerateConfig + ProductContext types
+ *
+ * Tests for:
+ *   - packages/types/src/config.ts (ProductContext, AutoGenerateConfig)
+ *   - OnboardMeConfig now accepts optional autoGenerate field
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+  ProductContext,
+  AutoGenerateConfig,
+  OnboardMeConfig,
+} from '@onboardme/types';
+
+// ---------------------------------------------------------------------------
+// ProductContext
+// ---------------------------------------------------------------------------
+
+describe('Week 5 Day 1 — ProductContext', () => {
+  it('accepts a fully populated object', () => {
+    const ctx: ProductContext = {
+      title: 'My App — Dashboard',
+      headings: ['Welcome to My App', 'Get Started'],
+      navLinks: ['Home', 'Settings', 'Help'],
+      buttons: ['Create project', 'Invite team', 'Upgrade'],
+    };
+    expect(ctx.title).toBe('My App — Dashboard');
+    expect(ctx.headings).toHaveLength(2);
+    expect(ctx.navLinks).toHaveLength(3);
+    expect(ctx.buttons).toHaveLength(3);
+  });
+
+  it('accepts empty arrays for headings, navLinks, and buttons', () => {
+    const ctx: ProductContext = {
+      title: 'Minimal App',
+      headings: [],
+      navLinks: [],
+      buttons: [],
+    };
+    expect(ctx.headings).toEqual([]);
+    expect(ctx.navLinks).toEqual([]);
+    expect(ctx.buttons).toEqual([]);
+  });
+
+  it('title is a string', () => {
+    const ctx: ProductContext = {
+      title: 'Acme SaaS',
+      headings: [],
+      navLinks: [],
+      buttons: [],
+    };
+    expect(typeof ctx.title).toBe('string');
+  });
+
+  it('headings is an array of strings', () => {
+    const ctx: ProductContext = {
+      title: '',
+      headings: ['h1 text', 'h2 text', 'h3 text'],
+      navLinks: [],
+      buttons: [],
+    };
+    ctx.headings.forEach((h) => expect(typeof h).toBe('string'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AutoGenerateConfig
+// ---------------------------------------------------------------------------
+
+describe('Week 5 Day 1 — AutoGenerateConfig', () => {
+  it('accepts endpoint-only (minimal config)', () => {
+    const cfg: AutoGenerateConfig = {
+      endpoint: 'http://localhost:3002/generate',
+    };
+    expect(cfg.endpoint).toBe('http://localhost:3002/generate');
+    expect(cfg.productDescription).toBeUndefined();
+    expect(cfg.cacheTtlMs).toBeUndefined();
+  });
+
+  it('accepts all optional fields', () => {
+    const cfg: AutoGenerateConfig = {
+      endpoint: 'https://flows.example.com/generate',
+      productDescription: 'A project management tool for remote teams',
+      cacheTtlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+    };
+    expect(cfg.productDescription).toBe('A project management tool for remote teams');
+    expect(cfg.cacheTtlMs).toBe(604_800_000);
+  });
+
+  it('endpoint is a string', () => {
+    const cfg: AutoGenerateConfig = { endpoint: 'http://localhost:3002/generate' };
+    expect(typeof cfg.endpoint).toBe('string');
+  });
+
+  it('cacheTtlMs is a number when provided', () => {
+    const cfg: AutoGenerateConfig = {
+      endpoint: 'http://localhost:3002/generate',
+      cacheTtlMs: 3600_000,
+    };
+    expect(typeof cfg.cacheTtlMs).toBe('number');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OnboardMeConfig.autoGenerate
+// ---------------------------------------------------------------------------
+
+describe('Week 5 Day 1 — OnboardMeConfig accepts autoGenerate', () => {
+  const baseConfig: OnboardMeConfig = {
+    productId: 'test-product',
+    flows: [],
+  };
+
+  it('works without autoGenerate (backwards compatible)', () => {
+    expect(baseConfig.autoGenerate).toBeUndefined();
+  });
+
+  it('accepts autoGenerate with endpoint only', () => {
+    const cfg: OnboardMeConfig = {
+      ...baseConfig,
+      autoGenerate: { endpoint: 'http://localhost:3002/generate' },
+    };
+    expect(cfg.autoGenerate?.endpoint).toBe('http://localhost:3002/generate');
+  });
+
+  it('accepts autoGenerate with all fields', () => {
+    const cfg: OnboardMeConfig = {
+      ...baseConfig,
+      autoGenerate: {
+        endpoint: 'http://localhost:3002/generate',
+        productDescription: 'Analytics dashboard',
+        cacheTtlMs: 86_400_000,
+      },
+    };
+    expect(cfg.autoGenerate?.productDescription).toBe('Analytics dashboard');
+    expect(cfg.autoGenerate?.cacheTtlMs).toBe(86_400_000);
+  });
+
+  it('autoGenerate can coexist with flows, debug, and eventsEndpoint', () => {
+    const cfg: OnboardMeConfig = {
+      productId: 'prod-1',
+      eventsEndpoint: 'http://localhost:3001/events',
+      autoGenerate: { endpoint: 'http://localhost:3002/generate' },
+      flows: [],
+      debug: true,
+    };
+    expect(cfg.debug).toBe(true);
+    expect(cfg.eventsEndpoint).toBe('http://localhost:3001/events');
+    expect(cfg.autoGenerate?.endpoint).toBe('http://localhost:3002/generate');
+  });
+});