onboardme-sdk 0.0.1

package/src/__tests__/week7-day5-api-flows.test.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { FlowConfig } from '@onboardme/types'
+import {
+  fetchFlowsFromAPI,
+  loadFlowsFromCache,
+  saveFlowsToCache,
+  fetchFlowsWithFallback,
+  startFlowsPolling,
+  stopFlowsPolling,
+  getCachedFlows,
+  _clearFlowsCache,
+} from '../core/api-flows'
+
+describe('Week 7 Day 5 — API Flows Integration', () => {
+  const mockFlows: FlowConfig[] = [
+    {
+      id: 'flow-1',
+      name: 'Welcome Flow',
+      completionGoal: 'onboarding_complete',
+      priority: 1,
+      steps: [
+        {
+          id: 'step-1',
+          type: 'modal',
+          order: 1,
+          title: 'Welcome',
+          body: 'Test body',
+          trigger: { type: 'page_load' },
+        },
+      ],
+    },
+    {
+      id: 'flow-2',
+      name: 'Checklist Flow',
+      completionGoal: 'checklist_complete',
+      priority: 2,
+      steps: [
+        {
+          id: 'step-2',
+          type: 'checklist',
+          order: 1,
+          title: 'Checklist',
+          body: 'Complete these items',
+          items: [],
+          trigger: { type: 'page_load' },
+        },
+      ],
+    },
+  ]
+
+  const mockResponse = {
+    flows: mockFlows,
+    checksumHash: 'abc12345',
+  }
+
+  const testCacheKey = 'test_cache_key'
+  const testEndpoint = 'http://localhost:3000'
+  const testApiKey = 'test-api-key-123'
+
+  beforeEach(() => {
+    _clearFlowsCache()
+    localStorage.clear()
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    stopFlowsPolling()
+    localStorage.clear()
+  })
+
+  describe('fetchFlowsFromAPI', () => {
+    it('should fetch flows from API successfully', async () => {
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      })
+
+      const result = await fetchFlowsFromAPI(testEndpoint, testApiKey)
+
+      expect(result).toEqual(mockResponse)
+      expect(fetchMock).toHaveBeenCalledWith(`${testEndpoint}/v1/flows`, {
+        method: 'GET',
+        headers: {
+          'x-api-key': testApiKey,
+          'Content-Type': 'application/json',
+        },
+        signal: expect.any(AbortSignal),
+      })
+    })
+
+    it('should return null on HTTP error', async () => {
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+      })
+
+      const result = await fetchFlowsFromAPI(testEndpoint, testApiKey)
+
+      expect(result).toBeNull()
+    })
+
+    it('should return null on network error', async () => {
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockRejectedValueOnce(new Error('Network error'))
+
+      const result = await fetchFlowsFromAPI(testEndpoint, testApiKey)
+
+      expect(result).toBeNull()
+    })
+
+    it('should return null on timeout (10s)', async () => {
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockImplementationOnce(
+        () =>
+          new Promise(() => {
+            // Never resolves — simulates timeout
+          }),
+      )
+
+      // Use Promise.race to enforce timeout behavior without waiting 10s
+      const result = await Promise.race([
+        fetchFlowsFromAPI(testEndpoint, testApiKey),
+        new Promise((resolve) => setTimeout(() => resolve(null), 100)),
+      ])
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('localStorage cache', () => {
+    it('should save flows to cache', () => {
+      saveFlowsToCache(testCacheKey, mockFlows, 'hash123')
+
+      const cached = localStorage.getItem(testCacheKey)
+      expect(cached).toBeTruthy()
+
+      const parsed = JSON.parse(cached!)
+      expect(parsed.flows).toEqual(mockFlows)
+      expect(parsed.checksumHash).toBe('hash123')
+      expect(parsed.timestamp).toBeLessThanOrEqual(Date.now())
+    })
+
+    it('should load flows from cache', () => {
+      saveFlowsToCache(testCacheKey, mockFlows, 'hash123')
+
+      const loaded = loadFlowsFromCache(testCacheKey)
+
+      expect(loaded).toBeTruthy()
+      expect(loaded!.flows).toEqual(mockFlows)
+      expect(loaded!.checksumHash).toBe('hash123')
+    })
+
+    it('should return null for missing cache', () => {
+      const loaded = loadFlowsFromCache('nonexistent_key')
+
+      expect(loaded).toBeNull()
+    })
+
+    it('should return null for expired cache (1h TTL)', () => {
+      // Manually create expired cache
+      const expiredData = {
+        flows: mockFlows,
+        checksumHash: 'hash123',
+        timestamp: Date.now() - 3600000 - 1000, // 1h + 1s ago
+      }
+      localStorage.setItem(testCacheKey, JSON.stringify(expiredData))
+
+      const loaded = loadFlowsFromCache(testCacheKey)
+
+      expect(loaded).toBeNull()
+      expect(localStorage.getItem(testCacheKey)).toBeNull() // Should be cleared
+    })
+
+    it('should handle corrupted cache gracefully', () => {
+      localStorage.setItem(testCacheKey, 'corrupted json {{{')
+
+      const loaded = loadFlowsFromCache(testCacheKey)
+
+      expect(loaded).toBeNull()
+    })
+  })
+
+  describe('fetchFlowsWithFallback', () => {
+    it('should fetch from API and cache result', async () => {
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      })
+
+      const result = await fetchFlowsWithFallback(testEndpoint, testApiKey, testCacheKey)
+
+      expect(result).toEqual(mockResponse)
+      expect(localStorage.getItem(testCacheKey)).toBeTruthy()
+    })
+
+    it('should fall back to cache on API failure', async () => {
+      // Pre-populate cache
+      saveFlowsToCache(testCacheKey, mockFlows, 'cached-hash')
+
+      // Mock API failure
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockRejectedValueOnce(new Error('API down'))
+
+      const result = await fetchFlowsWithFallback(testEndpoint, testApiKey, testCacheKey)
+
+      expect(result.flows).toEqual(mockFlows)
+      expect(result.checksumHash).toBe('cached-hash')
+    })
+
+    it('should return empty array on all failures', async () => {
+      // No cache
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockRejectedValueOnce(new Error('API down'))
+
+      const result = await fetchFlowsWithFallback(testEndpoint, testApiKey, testCacheKey)
+
+      expect(result.flows).toEqual([])
+      expect(result.checksumHash).toBe('')
+    })
+  })
+
+  describe('Flow polling', () => {
+    it('should call callback when checksum changes', async () => {
+      const callback = vi.fn()
+      let pollCount = 0
+
+      const fetchMock = vi.fn().mockImplementation(async () => {
+        pollCount++
+        if (pollCount === 1) {
+          return { ok: true, json: async () => ({ flows: mockFlows, checksumHash: 'hash1' }) }
+        }
+        // Second poll returns different hash
+        return { ok: true, json: async () => ({ flows: mockFlows, checksumHash: 'hash2' }) }
+      })
+
+      global.fetch = fetchMock
+
+      startFlowsPolling(testEndpoint, testApiKey, testCacheKey, callback)
+
+      // Wait for immediate check
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      expect(callback).toHaveBeenCalledWith(mockFlows, 'hash1')
+
+      // Clear mock and wait for it to be called again
+      callback.mockClear()
+      // Manually trigger second poll by updating mock
+      pollCount = 1
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ flows: mockFlows, checksumHash: 'hash2' }),
+      })
+
+      stopFlowsPolling()
+    })
+
+    it('should not call callback if hash unchanged', async () => {
+      const callback = vi.fn()
+
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockResolvedValue({
+        ok: true,
+        json: async () => ({ flows: mockFlows, checksumHash: 'same-hash' }),
+      })
+
+      startFlowsPolling(testEndpoint, testApiKey, testCacheKey, callback)
+
+      // Wait for initial check
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      expect(callback).toHaveBeenCalledTimes(1)
+
+      // Callback should not be called again (hash is same)
+      callback.mockClear()
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      expect(callback).not.toHaveBeenCalled()
+
+      stopFlowsPolling()
+    })
+
+    it('should stop polling cleanly', async () => {
+      const callback = vi.fn()
+      const fetchMock = vi.fn()
+      global.fetch = fetchMock.mockResolvedValue({
+        ok: true,
+        json: async () => mockResponse,
+      })
+
+      startFlowsPolling(testEndpoint, testApiKey, testCacheKey, callback)
+
+      // Stop immediately
+      stopFlowsPolling()
+
+      // Polling should be stopped
+      expect(getCachedFlows()).toBeNull() // Reset was called
+    })
+  })
+
+  describe('Integration', () => {
+    it('should handle multiple save/load cycles', () => {
+      const hash1 = 'hash1'
+      saveFlowsToCache(testCacheKey, mockFlows, hash1)
+
+      let loaded = loadFlowsFromCache(testCacheKey)
+      expect(loaded!.checksumHash).toBe(hash1)
+
+      // Update cache
+      const hash2 = 'hash2'
+      saveFlowsToCache(testCacheKey, mockFlows, hash2)
+
+      loaded = loadFlowsFromCache(testCacheKey)
+      expect(loaded!.checksumHash).toBe(hash2)
+    })
+
+    it('should preserve flow structure through cache cycle', () => {
+      const originalFlows: FlowConfig[] = [
+        {
+          id: 'flow-test',
+          name: 'Test Flow',
+          completionGoal: 'test_complete',
+          priority: 1,
+          steps: [
+            {
+              id: 'step-1',
+              type: 'modal',
+              order: 1,
+              title: 'Step 1',
+              body: 'Body 1',
+              trigger: { type: 'page_load' },
+            },
+            {
+              id: 'step-2',
+              type: 'checklist',
+              order: 2,
+              title: 'Step 2',
+              body: 'Body 2',
+              items: [],
+              trigger: { type: 'page_load' },
+            },
+          ],
+        },
+      ]
+
+      saveFlowsToCache(testCacheKey, originalFlows, 'hash-test')
+      const loaded = loadFlowsFromCache(testCacheKey)
+
+      expect(loaded!.flows).toEqual(originalFlows)
+      expect(loaded!.flows[0].steps).toHaveLength(2)
+      expect(loaded!.flows[0].steps[0].type).toBe('modal')
+    })
+  })
+})

package/src/auto-generate/context-collector.ts

@@ -0,0 +1,47 @@
+import type { ProductContext } from '@onboardme/types';
+
+const MAX_HEADINGS = 10;
+const MAX_NAV_LINKS = 10;
+const MAX_BUTTONS = 15;
+
+/**
+ * Extracts unique, trimmed, non-empty text from a NodeList up to `max` entries.
+ */
+function uniqueText(elements: NodeListOf<Element>, max: number): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const el of elements) {
+    const text = (el.textContent ?? '').trim();
+    if (text && !seen.has(text)) {
+      seen.add(text);
+      result.push(text);
+      if (result.length >= max) break;
+    }
+  }
+  return result;
+}
+
+/**
+ * Collects a DOM fingerprint from the current page.
+ * Used by the AI flow-generator to give Claude context about the product.
+ */
+export function collectContext(): ProductContext {
+  const title = document.title ?? '';
+
+  const headings = uniqueText(
+    document.querySelectorAll('h1, h2, h3'),
+    MAX_HEADINGS,
+  );
+
+  const navLinks = uniqueText(
+    document.querySelectorAll('nav a'),
+    MAX_NAV_LINKS,
+  );
+
+  const buttons = uniqueText(
+    document.querySelectorAll('button, [role="button"]'),
+    MAX_BUTTONS,
+  );
+
+  return { title, headings, navLinks, buttons };
+}

package/src/auto-generate/flow-generator-client.ts

@@ -0,0 +1,97 @@
+import type { FlowConfig, ProductContext } from '@onboardme/types';
+import { logger } from '../utils/logger.js';
+
+export const DEFAULT_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const TIMEOUT_MS = 10_000;
+
+interface CacheEntry {
+  flows: FlowConfig[];
+  cachedAt: number;
+}
+
+export function cacheKey(productId: string): string {
+  return `onboardme_autogen_${productId}`;
+}
+
+/** Returns cached flows if present and not expired, otherwise null. */
+export function loadCache(productId: string, ttlMs: number): FlowConfig[] | null {
+  try {
+    const raw = localStorage.getItem(cacheKey(productId));
+    if (!raw) return null;
+    const entry: CacheEntry = JSON.parse(raw);
+    if (Date.now() - entry.cachedAt > ttlMs) return null;
+    return entry.flows;
+  } catch {
+    return null;
+  }
+}
+
+/** Persists flows to localStorage. Silently no-ops on quota errors. */
+export function saveCache(productId: string, flows: FlowConfig[]): void {
+  try {
+    const entry: CacheEntry = { flows, cachedAt: Date.now() };
+    localStorage.setItem(cacheKey(productId), JSON.stringify(entry));
+  } catch {
+    logger.warn('auto-generate: localStorage quota exceeded — cache not saved');
+  }
+}
+
+/**
+ * Fetches AI-generated flows from the flow-generator server.
+ * Returns the cached result if fresh, otherwise POSTs the ProductContext
+ * and caches the response. Never throws — returns [] on any error.
+ */
+export async function fetchGeneratedFlows(
+  endpoint: string,
+  productId: string,
+  context: ProductContext,
+  ttlMs = DEFAULT_CACHE_TTL_MS,
+): Promise<FlowConfig[]> {
+  const cached = loadCache(productId, ttlMs);
+  if (cached) return cached;
+
+  const controller = new AbortController();
+  const timerId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ productId, context }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      logger.warn(`auto-generate: server responded ${res.status}`);
+      return [];
+    }
+
+    const data: unknown = await res.json();
+    const flows: FlowConfig[] =
+      data !== null &&
+      typeof data === 'object' &&
+      'flows' in data &&
+      Array.isArray((data as { flows: unknown }).flows)
+        ? ((data as { flows: FlowConfig[] }).flows)
+        : [];
+
+    saveCache(productId, flows);
+    return flows;
+  } catch (err) {
+    logger.warn(`auto-generate: fetch failed — ${(err as Error).message}`);
+    return [];
+  } finally {
+    clearTimeout(timerId);
+  }
+}
+
+/**
+ * Merges manually configured flows with AI-generated flows.
+ * Generated flows whose id already exists in manual are skipped.
+ * Manual flows always take precedence and appear first.
+ */
+export function mergeFlows(manual: FlowConfig[], generated: FlowConfig[]): FlowConfig[] {
+  const existingIds = new Set(manual.map((f) => f.id));
+  const novel = generated.filter((f) => !existingIds.has(f.id));
+  return [...manual, ...novel];
+}

package/src/browser.ts

@@ -0,0 +1,5 @@
+// Browser IIFE entry — re-exports only the default SDK object.
+// Named test helpers (_resetIndex, _resetSDK) are intentionally excluded so
+// Rollup can use the single-default-export IIFE pattern, which sets
+// window.OnboardMe = <SDK object> directly (no { default: sdk } wrapper).
+export { default } from './index.js';

package/src/components/celebration.ts

@@ -0,0 +1,44 @@
+const CELEBRATION_CSS = `
+.om-celebration {
+  position: fixed;
+  top: 1.25rem;
+  left: 50%;
+  transform: translateX(-50%);
+  background: #16a34a;
+  color: #ffffff;
+  font-family: system-ui, sans-serif;
+  font-size: 1rem;
+  font-weight: 600;
+  padding: 0.75rem 1.5rem;
+  border-radius: 0.5rem;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  z-index: 999999;
+  text-align: center;
+  white-space: nowrap;
+}
+`;
+
+/**
+ * Renders a "🎉 You're all set!" celebration banner inside the shadow root.
+ * The banner auto-dismisses after 3 seconds.
+ */
+export function showCelebration(shadowRoot: ShadowRoot): void {
+  // Inject styles if not already present
+  if (!shadowRoot.querySelector('#om-celebration-styles')) {
+    const style = document.createElement('style');
+    style.id = 'om-celebration-styles';
+    style.textContent = CELEBRATION_CSS;
+    shadowRoot.appendChild(style);
+  }
+
+  const banner = document.createElement('div');
+  banner.className = 'om-celebration';
+  banner.setAttribute('role', 'status');
+  banner.setAttribute('aria-live', 'polite');
+  banner.textContent = "🎉 You're all set!";
+  shadowRoot.appendChild(banner);
+
+  setTimeout(() => {
+    banner.remove();
+  }, 3000);
+}

package/src/components/checklist-css.ts

@@ -0,0 +1,159 @@
+/**
+ * Checklist CSS as an injectable string for the Shadow DOM.
+ * Source of truth: checklist.css (kept alongside for readability/tooling).
+ */
+export const CHECKLIST_CSS = `
+.om-checklist {
+  position: fixed;
+  bottom: 24px;
+  right: 24px;
+  width: 320px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12), 0 2px 8px rgba(0, 0, 0, 0.08);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-size: 14px;
+  color: #1a1a2e;
+  z-index: 9999;
+  overflow: hidden;
+  transition: width 0.2s ease, height 0.2s ease;
+}
+
+.om-checklist__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 16px 10px;
+  border-bottom: 1px solid #f0f0f0;
+}
+
+.om-checklist__title {
+  font-weight: 600;
+  font-size: 14px;
+  color: #1a1a2e;
+}
+
+.om-checklist__collapse-btn {
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: 18px;
+  color: #888;
+  padding: 0 2px;
+  line-height: 1;
+  transition: color 0.15s;
+}
+
+.om-checklist__collapse-btn:hover {
+  color: #1a1a2e;
+}
+
+.om-checklist__progress {
+  padding: 10px 16px 6px;
+}
+
+.om-checklist__progress-bar {
+  width: 100%;
+  height: 6px;
+  background: #ebebeb;
+  border-radius: 3px;
+  overflow: hidden;
+  margin-bottom: 6px;
+}
+
+.om-checklist__progress-bar-fill {
+  height: 100%;
+  background: #4f46e5;
+  border-radius: 3px;
+  transition: width 0.35s ease;
+}
+
+.om-checklist__progress-label {
+  font-size: 12px;
+  color: #888;
+}
+
+.om-checklist__items {
+  list-style: none;
+  margin: 0;
+  padding: 6px 0 10px;
+}
+
+.om-checklist__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 16px;
+  cursor: pointer;
+  transition: background 0.1s;
+}
+
+.om-checklist__item:hover {
+  background: #f8f8fb;
+}
+
+.om-checklist__item-check {
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+  border: 2px solid #d1d5db;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 10px;
+  color: transparent;
+  transition: background 0.15s, border-color 0.15s, color 0.15s;
+}
+
+.om-checklist__item-label {
+  flex: 1;
+  font-size: 13px;
+  color: #1a1a2e;
+}
+
+.om-checklist__item--done .om-checklist__item-check {
+  background: #4f46e5;
+  border-color: #4f46e5;
+  color: #ffffff;
+}
+
+.om-checklist__item--done .om-checklist__item-label {
+  text-decoration: line-through;
+  color: #aaa;
+}
+
+.om-checklist__item--optional .om-checklist__item-label {
+  color: #888;
+}
+
+.om-badge {
+  flex-shrink: 0;
+  background: #f3f4f6;
+  color: #6b7280;
+  font-size: 11px;
+  font-weight: 500;
+  padding: 2px 7px;
+  border-radius: 10px;
+}
+
+.om-checklist--collapsed {
+  width: auto;
+  height: auto;
+}
+
+.om-checklist--collapsed .om-checklist__progress,
+.om-checklist--collapsed .om-checklist__items {
+  display: none;
+}
+
+.om-checklist--collapsed .om-checklist__header {
+  border-bottom: none;
+  padding: 10px 14px;
+  cursor: pointer;
+}
+
+.om-checklist--collapsed .om-checklist__collapse-btn {
+  display: none;
+}
+`;