onboardme-sdk 0.0.1

package/src/__tests__/day5.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Day 5 Tests — SDK Orchestrator + Week 1 Edge Cases
+ *
+ * Tests for core/sdk.ts (runSDK) and the full init() flow.
+ * These are the integration-level checks from the Week 1 completion checklist.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { runSDK, _resetSDK } from '../core/sdk.js';
+import OnboardMe, { _resetIndex } from '../index.js';
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  document.body.innerHTML = '';
+  _resetSDK();
+  _resetIndex();
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// runSDK — orchestrator
+// ---------------------------------------------------------------------------
+
+describe('Day 5 — runSDK orchestrator', () => {
+  it('returns null and does not throw when config is missing productId', () => {
+    expect(() => runSDK({ flows: [] })).not.toThrow();
+    expect(runSDK({ flows: [] })).toBeNull();
+  });
+
+  it('returns null and does not throw when config is null', () => {
+    expect(() => runSDK(null)).not.toThrow();
+    expect(runSDK(null)).toBeNull();
+  });
+
+  it('returns a valid SDKState when config is correct', () => {
+    const state = runSDK({ productId: 'my-app', flows: [] });
+    expect(state).not.toBeNull();
+    expect(state?.config.productId).toBe('my-app');
+    expect(typeof state?.anonymousId).toBe('string');
+    expect(typeof state?.showOnboarding).toBe('boolean');
+  });
+
+  it('sets showOnboarding: true for a new user (no seen flag)', () => {
+    const state = runSDK({ productId: 'brand-new', flows: [] });
+    expect(state?.showOnboarding).toBe(true);
+  });
+
+  it('sets showOnboarding: false for a returning user (seen flag present)', () => {
+    localStorage.setItem('onboardme_seen_returning-app', '1');
+    const state = runSDK({ productId: 'returning-app', flows: [] });
+    expect(state?.showOnboarding).toBe(false);
+  });
+
+  it('empty flows does not throw — warns in debug mode instead', async () => {
+    const { setDebug } = await import('../utils/logger.js');
+    setDebug(true);
+    expect(() => runSDK({ productId: 'my-app', flows: [] })).not.toThrow();
+    expect(console.warn).toHaveBeenCalled();
+    setDebug(false);
+  });
+
+  it('returns a stable anonymousId — same value on repeated calls for same product', () => {
+    const state1 = runSDK({ productId: 'stable-app', flows: [] });
+    // Reset the init guard so a second runSDK call is allowed (simulates a new page load).
+    // localStorage is NOT cleared — verifies the stored anon ID is reused.
+    _resetSDK();
+    const state2 = runSDK({ productId: 'stable-app', flows: [] });
+    expect(state1?.anonymousId).toBe(state2?.anonymousId);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// init() — full public API integration
+// ---------------------------------------------------------------------------
+
+describe('Day 5 — init() integration (Week 1 checklist)', () => {
+  it('calling init() with missing productId does not throw', () => {
+    expect(() => {
+      // @ts-expect-error — intentionally bad input
+      OnboardMe.init({ flows: [] });
+    }).not.toThrow();
+  });
+
+  it('calling init() with empty flows does not throw', () => {
+    expect(() => {
+      OnboardMe.init({ productId: 'checklist-app', flows: [] });
+    }).not.toThrow();
+  });
+
+  it('calling init() twice does not throw', () => {
+    expect(() => {
+      OnboardMe.init({ productId: 'double-init', flows: [] });
+      OnboardMe.init({ productId: 'double-init', flows: [] });
+    }).not.toThrow();
+  });
+});

package/src/__tests__/snapshot-dom-collector.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { collectSnapshot, buildSelector } from '../snapshot/dom-collector'
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+  document.title = 'Test Page'
+})
+
+function setBody(html: string) {
+  document.body.innerHTML = html
+}
+
+describe('collectSnapshot — element extraction', () => {
+  it('captures headings, buttons, links, inputs, forms, navs, images', () => {
+    setBody(`
+      <h1>Welcome</h1>
+      <h2>Get started</h2>
+      <nav aria-label="primary">
+        <a href="/dash">Dashboard</a>
+      </nav>
+      <form action="/submit" method="post">
+        <input type="email" name="email" placeholder="Email" />
+        <button type="submit">Sign up</button>
+      </form>
+      <img src="/logo.png" alt="Logo" />
+    `)
+
+    const snap = collectSnapshot()
+
+    const roles = snap.elements.map((e) => e.role).sort()
+    expect(roles).toContain('heading')
+    expect(roles).toContain('button')
+    expect(roles).toContain('link')
+    expect(roles).toContain('input')
+    expect(roles).toContain('form')
+    expect(roles).toContain('nav')
+    expect(roles).toContain('image')
+  })
+
+  it('captures heading text correctly', () => {
+    setBody('<h1>Welcome to OnboardMe</h1><h2>Step 1</h2>')
+    const snap = collectSnapshot()
+    const headings = snap.elements.filter((e) => e.role === 'heading')
+    expect(headings.length).toBe(2)
+    expect(headings[0].text).toBe('Welcome to OnboardMe')
+    expect(headings[1].text).toBe('Step 1')
+  })
+
+  it('extracts button attributes (type, name, aria-label, data-testid)', () => {
+    setBody(`
+      <button type="submit" name="primary-cta" aria-label="Sign up" data-testid="signup-btn">Go</button>
+    `)
+    const snap = collectSnapshot()
+    const btn = snap.elements.find((e) => e.role === 'button')
+    expect(btn?.attributes?.type).toBe('submit')
+    expect(btn?.attributes?.name).toBe('primary-cta')
+    expect(btn?.attributes?.['aria-label']).toBe('Sign up')
+    expect(btn?.attributes?.['data-testid']).toBe('signup-btn')
+  })
+
+  it('extracts link href + image alt', () => {
+    setBody('<a href="/foo" aria-label="Foo">Foo</a><img src="/x.png" alt="x" />')
+    const snap = collectSnapshot()
+    const link = snap.elements.find((e) => e.role === 'link')
+    const img = snap.elements.find((e) => e.role === 'image')
+    expect(link?.attributes?.href).toBe('/foo')
+    expect(img?.attributes?.alt).toBe('x')
+  })
+
+  it('does NOT double-count an element that matches multiple selectors', () => {
+    setBody('<a href="/x" role="button">Click</a>')
+    const snap = collectSnapshot()
+    // The <a role="button"> should be classified as a button (earlier in
+    // the COLLECTORS list) and not also picked up as a link.
+    const matches = snap.elements.filter((e) => e.text === 'Click')
+    expect(matches.length).toBe(1)
+    expect(matches[0].role).toBe('button')
+  })
+
+  it('truncates very long text', () => {
+    const long = 'word '.repeat(100)
+    setBody(`<h1>${long}</h1>`)
+    const snap = collectSnapshot()
+    const h1 = snap.elements[0]
+    expect((h1.text ?? '').length).toBeLessThanOrEqual(200)
+    expect(h1.text?.endsWith('…')).toBe(true)
+  })
+
+  it('skips display:none and visibility:hidden elements', () => {
+    setBody(`
+      <h1 style="display:none">Hidden 1</h1>
+      <h2 style="visibility:hidden">Hidden 2</h2>
+      <h3>Visible</h3>
+    `)
+    const snap = collectSnapshot()
+    const headingTexts = snap.elements.filter((e) => e.role === 'heading').map((e) => e.text)
+    expect(headingTexts).toEqual(['Visible'])
+  })
+
+  it('caps the total at 500 elements', () => {
+    let html = ''
+    for (let i = 0; i < 600; i++) html += `<h6>H${i}</h6>`
+    setBody(html)
+    const snap = collectSnapshot()
+    expect(snap.elements.length).toBeLessThanOrEqual(500)
+  })
+
+  it('records pageUrl, pageTitle, collectedAt, viewport meta', () => {
+    setBody('<h1>x</h1>')
+    document.title = 'My Title'
+    const before = Date.now()
+    const snap = collectSnapshot()
+    expect(snap.pageTitle).toBe('My Title')
+    expect(snap.pageUrl).toContain('http')           // jsdom default URL has http
+    expect(snap.collectedAt).toBeGreaterThanOrEqual(before)
+    expect(snap.meta?.viewport?.width).toBeGreaterThanOrEqual(0)
+  })
+})
+
+describe('buildSelector', () => {
+  it('prefers data-testid', () => {
+    setBody('<button data-testid="primary-cta" id="some-id">x</button>')
+    const btn = document.querySelector('button')!
+    expect(buildSelector(btn)).toBe('[data-testid="primary-cta"]')
+  })
+
+  it('uses id when stable-looking', () => {
+    setBody('<button id="signup-btn">x</button>')
+    const btn = document.querySelector('button')!
+    expect(buildSelector(btn)).toBe('#signup-btn')
+  })
+
+  it('skips auto-generated-looking ids', () => {
+    setBody('<div><button id="__react_1234567">x</button></div>')
+    const btn = document.querySelector('button')!
+    // Falls back to tag (only one button child)
+    expect(buildSelector(btn)).toBe('button')
+  })
+
+  it('uses nth-of-type when multiple siblings of same tag exist', () => {
+    setBody(`
+      <div>
+        <button>A</button>
+        <button>B</button>
+        <button>C</button>
+      </div>
+    `)
+    const buttons = document.querySelectorAll('button')
+    expect(buildSelector(buttons[0])).toBe('button:nth-of-type(1)')
+    expect(buildSelector(buttons[1])).toBe('button:nth-of-type(2)')
+    expect(buildSelector(buttons[2])).toBe('button:nth-of-type(3)')
+  })
+})

package/src/__tests__/snapshot-sender.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  collectAndSendSnapshot,
+  hasSentForThisPage,
+  markSentForThisPage,
+  postSnapshot,
+} from '../snapshot/sender'
+
+function setBody(html: string) {
+  document.body.innerHTML = html
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+  sessionStorage.clear()
+  vi.restoreAllMocks()
+  // Default fetch returns 201
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 201 })),
+  )
+})
+
+describe('hasSentForThisPage / markSentForThisPage', () => {
+  it('round-trips through sessionStorage', () => {
+    expect(hasSentForThisPage('p1', '/page')).toBe(false)
+    markSentForThisPage('p1', '/page')
+    expect(hasSentForThisPage('p1', '/page')).toBe(true)
+  })
+
+  it('keys per (productId, pageUrl)', () => {
+    markSentForThisPage('p1', '/a')
+    expect(hasSentForThisPage('p1', '/a')).toBe(true)
+    expect(hasSentForThisPage('p1', '/b')).toBe(false)
+    expect(hasSentForThisPage('p2', '/a')).toBe(false)
+  })
+})
+
+describe('postSnapshot', () => {
+  it('sends to <endpoint>/v1/code-sources/snapshot with x-api-key header', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(new Response('{}', { status: 201 }))
+    vi.stubGlobal('fetch', fetchSpy)
+
+    const payload = {
+      pageUrl:     'https://x.com',
+      pageTitle:   'X',
+      collectedAt: 0,
+      elements:    [{ selector: 'h1', role: 'heading' as const }],
+    }
+    const result = await postSnapshot('https://api.test', 'KEY', payload)
+
+    expect(result.ok).toBe(true)
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('https://api.test/v1/code-sources/snapshot')
+    expect((init as RequestInit).method).toBe('POST')
+    const headers = (init as RequestInit).headers as Record<string, string>
+    expect(headers['x-api-key']).toBe('KEY')
+    expect(headers['Content-Type']).toBe('application/json')
+  })
+
+  it('returns ok:false on network error without throwing', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('boom')))
+
+    const result = await postSnapshot('https://api.test', 'KEY', {
+      pageUrl: 'x', pageTitle: 'x', collectedAt: 0, elements: [],
+    })
+    expect(result.ok).toBe(false)
+  })
+})
+
+describe('collectAndSendSnapshot', () => {
+  it('happy path: collects DOM, sends, marks session', async () => {
+    setBody('<h1>Welcome</h1><button>Go</button>')
+    const result = await collectAndSendSnapshot('prod-1', 'https://api.test', 'KEY')
+
+    expect(result.sent).toBe(true)
+    expect(hasSentForThisPage('prod-1', window.location.href)).toBe(true)
+  })
+
+  it('skips when already sent for this page in this session', async () => {
+    setBody('<h1>Welcome</h1>')
+    markSentForThisPage('prod-1', window.location.href)
+
+    const fetchSpy = vi.fn()
+    vi.stubGlobal('fetch', fetchSpy)
+
+    const result = await collectAndSendSnapshot('prod-1', 'https://api.test', 'KEY')
+    expect(result.sent).toBe(false)
+    expect(result.skipped).toBe('already_sent')
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('skips when DOM has no extractable elements', async () => {
+    setBody('')   // no headings/buttons/links/forms etc
+    const result = await collectAndSendSnapshot('prod-1', 'https://api.test', 'KEY')
+    expect(result.sent).toBe(false)
+    expect(result.skipped).toBe('no_elements')
+  })
+
+  it('does NOT mark sent when the request fails', async () => {
+    setBody('<h1>x</h1>')
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('fail', { status: 500 })))
+
+    const result = await collectAndSendSnapshot('prod-1', 'https://api.test', 'KEY')
+    expect(result.sent).toBe(false)
+    expect(result.skipped).toBe('error')
+    // Critical: a failed send must allow a retry on the next page load.
+    expect(hasSentForThisPage('prod-1', window.location.href)).toBe(false)
+  })
+})

package/src/__tests__/v2-integration.test.ts

@@ -0,0 +1,305 @@
+/**
+ * v2-integration.test.ts — Phase F
+ *
+ * End-to-end test verifying the complete v2 flow:
+ * Flow creation → API fetch → SDK rendering → step transitions → completion
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type { V2FlowConfig } from '../v2/types'
+import { renderV2Flow } from '../v2/renderer'
+import { getShadowRoot } from '../components/shadow-host'
+
+describe('v2 Integration — End-to-End Flow Rendering', () => {
+  let shadowRoot: ShadowRoot
+
+  beforeEach(() => {
+    shadowRoot = getShadowRoot()
+    // Clear any existing content
+    shadowRoot.innerHTML = '<style data-onboardme="styles"></style>'
+  })
+
+  it('should render a complete v2 flow with multiple step types', () => {
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-1',
+          type: 'modal',
+          title: 'Welcome',
+          description: 'Let\'s get started!',
+          action: { type: 'next' },
+        },
+        {
+          id: 'step-2',
+          type: 'tooltip',
+          title: 'Find the button',
+          description: 'Click here to proceed',
+          position: { selector: 'button[data-test="proceed"]', placement: 'bottom' },
+          action: { type: 'next' },
+        },
+        {
+          id: 'step-3',
+          type: 'highlight',
+          description: 'You\'ve completed the flow',
+          position: { selector: 'button[data-test="proceed"]', placement: 'bottom' },
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Step 1: Modal should be rendered
+    expect(handle).not.toBeNull()
+    const modalTitle = shadowRoot.querySelector('.om2-modal-card h3')
+    expect(modalTitle?.textContent).toContain('Welcome')
+
+    // Modal should have action button
+    const actionBtn = shadowRoot.querySelector('.om2-btn-primary')
+    expect(actionBtn).not.toBeNull()
+    expect(actionBtn?.textContent).toMatch(/next|done/i)
+
+    // Cleanup
+    handle?.destroy()
+    expect(shadowRoot.querySelector('.om2-modal-card')).toBeNull()
+  })
+
+  it('should handle step transitions via action buttons', () => {
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-a',
+          type: 'modal',
+          title: 'Step A',
+          description: 'First step',
+          action: { type: 'next' },
+        },
+        {
+          id: 'step-b',
+          type: 'modal',
+          title: 'Step B',
+          description: 'Second step',
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Initial state: Step A rendered
+    let title = shadowRoot.querySelector('.om2-modal-card h3')
+    expect(title?.textContent).toContain('Step A')
+
+    // Simulate clicking "Next" button
+    const actionBtn = shadowRoot.querySelector<HTMLButtonElement>(
+      '.om2-btn-primary'
+    )
+    expect(actionBtn).not.toBeNull()
+    actionBtn?.click()
+
+    // After click: Step B should be rendered
+    title = shadowRoot.querySelector('.om2-modal-card h3')
+    expect(title?.textContent).toContain('Step B')
+
+    // Click again to complete
+    const finalBtn = shadowRoot.querySelector<HTMLButtonElement>(
+      '.om2-btn-primary'
+    )
+    finalBtn?.click()
+
+    // After complete: flow should be torn down
+    expect(shadowRoot.querySelector('.om2-modal-card')).toBeNull()
+
+    // Cleanup
+    handle?.destroy()
+  })
+
+  it('should correctly render tooltip with target selector', () => {
+    // Create a test target element
+    const testDiv = document.createElement('div')
+    testDiv.setAttribute('data-test', 'target')
+    testDiv.textContent = 'Target Element'
+    document.body.appendChild(testDiv)
+
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'tooltip-step',
+          type: 'tooltip',
+          title: 'Tip',
+          description: 'This is a tooltip',
+          position: { selector: '[data-test="target"]', placement: 'right' },
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Tooltip should be rendered
+    const tooltip = shadowRoot.querySelector('.om2-tooltip')
+    expect(tooltip).not.toBeNull()
+    expect(tooltip?.textContent).toContain('Tip')
+
+    // Cleanup
+    handle?.destroy()
+    testDiv.remove()
+  })
+
+  it('should render highlight with ring', () => {
+    // Create a test target element
+    const testDiv = document.createElement('div')
+    testDiv.setAttribute('data-test', 'highlight-target')
+    testDiv.textContent = 'Highlighted Element'
+    document.body.appendChild(testDiv)
+
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'highlight-step',
+          type: 'highlight',
+          description: 'This element is highlighted',
+          position: { selector: '[data-test="highlight-target"]', placement: 'bottom' },
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Highlight should render (outline ring)
+    const highlight = shadowRoot.querySelector('.om2-highlight')
+    expect(highlight).not.toBeNull()
+
+    // Cleanup
+    handle?.destroy()
+    testDiv.remove()
+  })
+
+  it('should skip flow when action is skip', () => {
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-1',
+          type: 'modal',
+          title: 'Skippable Step',
+          description: 'You can skip this',
+          action: { type: 'skip' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Modal should be rendered
+    expect(shadowRoot.querySelector('.om2-modal-card')).not.toBeNull()
+
+    // Click the action button (which has action: skip)
+    const actionBtn = shadowRoot.querySelector<HTMLButtonElement>(
+      '.om2-btn-primary'
+    )
+    actionBtn?.click()
+
+    // Flow should be completely torn down
+    expect(shadowRoot.querySelector('.om2-modal-card')).toBeNull()
+
+    // Cleanup
+    handle?.destroy()
+  })
+
+  it('should handle re-rendering when flow is updated', () => {
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-1',
+          type: 'modal',
+          title: 'Original Title',
+          description: 'Original content',
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle1 = renderV2Flow(v2Flow, shadowRoot)
+    expect(shadowRoot.querySelector('.om2-modal-card h3')?.textContent)
+      .toContain('Original Title')
+
+    // Destroy old render
+    handle1?.destroy()
+
+    // Render new flow with different content
+    const v2Flow2: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-1-updated',
+          type: 'modal',
+          title: 'Updated Title',
+          description: 'Updated content',
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle2 = renderV2Flow(v2Flow2, shadowRoot)
+    expect(shadowRoot.querySelector('.om2-modal-card h3')?.textContent)
+      .toContain('Updated Title')
+
+    // Cleanup
+    handle2?.destroy()
+  })
+
+  it('should clean up all DOM on destroy', () => {
+    const v2Flow: V2FlowConfig = {
+      steps: [
+        {
+          id: 'step-1',
+          type: 'modal',
+          title: 'Will be destroyed',
+          description: 'All DOM will be removed',
+          action: { type: 'complete' },
+        },
+      ],
+    }
+
+    const handle = renderV2Flow(v2Flow, shadowRoot)
+
+    // Verify content is rendered
+    expect(shadowRoot.querySelector('.om2-modal-card')).not.toBeNull()
+
+    // Destroy
+    handle?.destroy()
+
+    // Verify all v2 content is removed (modal, tooltip, highlight should be gone)
+    expect(shadowRoot.querySelector('.om2-modal-card')).toBeNull()
+    expect(shadowRoot.querySelector('.om2-tooltip')).toBeNull()
+    expect(shadowRoot.querySelector('.om2-highlight')).toBeNull()
+
+    // Style tag should still exist
+    expect(shadowRoot.querySelector('style')).not.toBeNull()
+  })
+
+  it('should handle empty flow gracefully', () => {
+    const emptyFlow: V2FlowConfig = {
+      steps: [],
+    }
+
+    const handle = renderV2Flow(emptyFlow, shadowRoot)
+
+    // Should return null for empty flow
+    expect(handle).toBeNull()
+
+    // Shadow root should be unchanged (no modal, tooltip, or highlight)
+    expect(shadowRoot.querySelector('.om2-modal-card')).toBeNull()
+    expect(shadowRoot.querySelector('.om2-tooltip')).toBeNull()
+    expect(shadowRoot.querySelector('.om2-highlight')).toBeNull()
+  })
+
+  it('should handle flow with no steps gracefully', () => {
+    const flowNoSteps = {} as V2FlowConfig
+
+    const handle = renderV2Flow(flowNoSteps, shadowRoot)
+
+    // Should return null for flow with no steps
+    expect(handle).toBeNull()
+  })
+})