onboardme-sdk 0.0.1

package/src/snapshot/sender.ts

@@ -0,0 +1,105 @@
+// Snapshot sender (Architecture v2 — Phase B).
+//
+// Sends a DOM snapshot to OnboardMe. Debounced at one snapshot per session
+// per page URL — once a page has reported, we don't keep nagging the API
+// for the same data. Server-side dedup is also in place; the client-side
+// guard saves a network round-trip on subsequent renders/navigations.
+//
+// Like the rest of the SDK, this never throws. On failure we log a debug
+// warning and move on — collecting code is best-effort, not load-bearing
+// for the host app.
+
+import { logger } from '../utils/logger.js'
+import { collectSnapshot } from './dom-collector.js'
+import type { SnapshotPayload } from './dom-collector.js'
+
+const TIMEOUT_MS = 10_000
+
+function sessionKey(productId: string, pageUrl: string): string {
+  return `onboardme_snapshot_${productId}_${pageUrl}`
+}
+
+export function hasSentForThisPage(productId: string, pageUrl: string): boolean {
+  try {
+    return sessionStorage.getItem(sessionKey(productId, pageUrl)) !== null
+  } catch {
+    // Private mode / disabled storage — re-send is harmless thanks to
+    // server-side dedup, so just say "not sent".
+    return false
+  }
+}
+
+export function markSentForThisPage(productId: string, pageUrl: string): void {
+  try {
+    sessionStorage.setItem(sessionKey(productId, pageUrl), String(Date.now()))
+  } catch {
+    // ignore
+  }
+}
+
+export interface SnapshotSendResult {
+  sent:         boolean
+  skipped?:     'already_sent' | 'no_elements' | 'error'
+  status?:      number
+}
+
+export async function postSnapshot(
+  endpoint: string,
+  apiKey:   string,
+  payload:  SnapshotPayload,
+): Promise<{ ok: boolean; status?: number }> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+
+  try {
+    const res = await fetch(`${endpoint}/v1/code-sources/snapshot`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key':    apiKey,
+      },
+      body:   JSON.stringify(payload),
+      signal: controller.signal,
+    })
+    return { ok: res.ok, status: res.status }
+  } catch (err) {
+    logger.warn(`snapshot send failed — ${(err as Error).message}`)
+    return { ok: false }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// Public entry point: collects a snapshot from the current document and
+// sends it. Returns information about what happened so callers (or tests)
+// can verify behaviour, but never throws.
+export async function collectAndSendSnapshot(
+  productId: string,
+  endpoint:  string,
+  apiKey:    string,
+): Promise<SnapshotSendResult> {
+  // sessionStorage / window.location are only available in a browser context.
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return { sent: false, skipped: 'error' }
+  }
+
+  const pageUrl = window.location.href
+  if (hasSentForThisPage(productId, pageUrl)) {
+    return { sent: false, skipped: 'already_sent' }
+  }
+
+  const payload = collectSnapshot(document, window)
+  if (payload.elements.length === 0) {
+    // Nothing useful to send — host page is probably empty or pre-render.
+    return { sent: false, skipped: 'no_elements' }
+  }
+
+  const { ok, status } = await postSnapshot(endpoint, apiKey, payload)
+  if (ok) {
+    markSentForThisPage(productId, pageUrl)
+    logger.log(`snapshot sent (${payload.elements.length} elements)`)
+    return { sent: true, status }
+  }
+
+  return { sent: false, skipped: 'error', status }
+}

package/src/storage/event-listener.ts

@@ -0,0 +1,59 @@
+/**
+ * event-listener.ts — Week 3 Day 4
+ *
+ * Watches OnboardMe.track calls and auto-checks checklist items whose
+ * `completionEvent` matches the fired event name.
+ *
+ * Patches OnboardMe.track so the completion check runs *after* every
+ * track call — including calls made before init() (where track is a no-op).
+ * Returns an unsubscribe function that restores the original track.
+ */
+
+import type { FlowConfig, ChecklistItem } from '@onboardme/types';
+import OnboardMe from '../index.js';
+
+/**
+ * Begins watching OnboardMe.track for events that match a checklist item's
+ * `completionEvent` field.
+ *
+ * @param flow           The active flow config (reads items from checklist step).
+ * @param onItemComplete Called with the item's id when a matching event fires
+ *                       and the item has not already been marked complete.
+ *                       The caller is responsible for de-duplication.
+ * @returns              An unsubscribe function. Call it to remove the patch
+ *                       (e.g. on flow completion or SDK teardown).
+ */
+export function watchCompletionEvents(
+  flow: FlowConfig,
+  onItemComplete: (itemId: string) => void,
+): () => void {
+  // Build a map: eventName → itemId for every item that has a completionEvent
+  const checklistStep = flow.steps.find((s) => s.type === 'checklist');
+  const items: ChecklistItem[] = checklistStep?.items ?? [];
+
+  const watchMap = new Map<string, string>();
+  for (const item of items) {
+    if (item.completionEvent) {
+      watchMap.set(item.completionEvent, item.id);
+    }
+  }
+
+  // Patch track
+  const originalTrack = OnboardMe.track;
+  OnboardMe.track = (eventName: string, properties?: Record<string, unknown>) => {
+    // Run original logic first (may be a no-op if SDK not initialised — that's fine)
+    originalTrack.call(OnboardMe, eventName, properties);
+
+    // Completion check always runs
+    const itemId = watchMap.get(eventName);
+    if (itemId !== undefined) {
+      onItemComplete(itemId);
+    }
+  };
+
+  // Unsubscribe — restores the original track and clears the watchMap
+  return () => {
+    OnboardMe.track = originalTrack;
+    watchMap.clear();
+  };
+}

package/src/storage/progress-tracker.ts

@@ -0,0 +1,78 @@
+/**
+ * progress-tracker.ts — Week 3 Day 1
+ *
+ * Owns all localStorage reads/writes for checklist progress.
+ * Pure, synchronous, never throws.
+ * Key format: onboardme_progress_{productId}_{flowId}
+ */
+
+export interface Progress {
+  completedSteps: string[];
+  lastUpdated: number;
+}
+
+const DEFAULT_PROGRESS: Progress = { completedSteps: [], lastUpdated: 0 };
+
+function storageKey(productId: string, flowId: string): string {
+  return `onboardme_progress_${productId}_${flowId}`;
+}
+
+/**
+ * Reads progress for a product+flow from localStorage.
+ * Returns the empty default if the key is absent or the value is unparseable.
+ */
+export function loadProgress(productId: string, flowId: string): Progress {
+  try {
+    const raw = localStorage.getItem(storageKey(productId, flowId));
+    if (!raw) return { ...DEFAULT_PROGRESS, completedSteps: [] };
+    return JSON.parse(raw) as Progress;
+  } catch {
+    return { ...DEFAULT_PROGRESS, completedSteps: [] };
+  }
+}
+
+/**
+ * Writes a fresh progress snapshot to localStorage.
+ * Stamps lastUpdated with the current time.
+ */
+export function saveProgress(
+  productId: string,
+  flowId: string,
+  completedSteps: string[],
+): void {
+  const data: Progress = { completedSteps, lastUpdated: Date.now() };
+  localStorage.setItem(storageKey(productId, flowId), JSON.stringify(data));
+}
+
+/**
+ * Marks a single step as complete.
+ * Idempotent — calling it twice for the same stepId has no effect.
+ */
+export function markStepComplete(
+  productId: string,
+  flowId: string,
+  stepId: string,
+): void {
+  const current = loadProgress(productId, flowId);
+  if (current.completedSteps.includes(stepId)) return;
+  saveProgress(productId, flowId, [...current.completedSteps, stepId]);
+}
+
+/**
+ * Returns true if the given step has been marked complete.
+ */
+export function isStepComplete(
+  productId: string,
+  flowId: string,
+  stepId: string,
+): boolean {
+  return loadProgress(productId, flowId).completedSteps.includes(stepId);
+}
+
+/**
+ * Removes all progress for a product+flow.
+ * Used for testing and explicit flow resets.
+ */
+export function clearProgress(productId: string, flowId: string): void {
+  localStorage.removeItem(storageKey(productId, flowId));
+}

package/src/styles/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;
+}
+`;

package/src/styles/checklist.css

@@ -0,0 +1,166 @@
+/* ============================================================
+   OnboardMe — Checklist panel
+   All selectors are scoped inside Shadow DOM, so there is no
+   risk of bleeding into the host application's styles.
+   ============================================================ */
+
+/* ---- Floating panel ---------------------------------------- */
+.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;
+}
+
+/* ---- Header ------------------------------------------------ */
+.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;
+}
+
+/* ---- Progress area ----------------------------------------- */
+.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;
+}
+
+/* ---- Items list -------------------------------------------- */
+.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;
+}
+
+/* ---- Done state -------------------------------------------- */
+.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;
+}
+
+/* ---- Optional badge ---------------------------------------- */
+.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;
+}
+
+/* ---- Collapsed pill state ---------------------------------- */
+.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;
+}

package/src/styles/modal-css.ts

@@ -0,0 +1,96 @@
+/**
+ * Modal CSS as an injectable string for the Shadow DOM.
+ * Source of truth: modal.css (kept alongside for readability/tooling).
+ */
+export const MODAL_CSS = `
+.om-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 2147483647;
+}
+
+.om-modal {
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
+  max-width: 480px;
+  width: calc(100% - 32px);
+  padding: 32px;
+  box-sizing: border-box;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  color: #111827;
+}
+
+.om-modal__title {
+  margin: 0 0 12px;
+  font-size: 20px;
+  font-weight: 700;
+  line-height: 1.3;
+  color: #111827;
+}
+
+.om-modal__body {
+  margin: 0 0 24px;
+  font-size: 15px;
+  line-height: 1.6;
+  color: #4b5563;
+}
+
+.om-modal__actions {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  align-items: stretch;
+}
+
+.om-btn-primary {
+  display: block;
+  width: 100%;
+  padding: 12px 20px;
+  background: #4f46e5;
+  color: #ffffff;
+  font-size: 15px;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  text-align: center;
+  transition: background 0.15s ease;
+}
+
+.om-btn-primary:hover {
+  background: #4338ca;
+}
+
+.om-btn-primary:focus-visible {
+  outline: 3px solid #818cf8;
+  outline-offset: 2px;
+}
+
+.om-btn-skip {
+  display: block;
+  background: none;
+  border: none;
+  padding: 6px 0;
+  color: #6b7280;
+  font-size: 14px;
+  cursor: pointer;
+  text-align: center;
+  text-decoration: underline;
+  transition: color 0.15s ease;
+}
+
+.om-btn-skip:hover {
+  color: #374151;
+}
+
+.om-btn-skip:focus-visible {
+  outline: 2px solid #818cf8;
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+`;