onboardme-sdk 0.0.1

package/src/core/sdk.ts

@@ -0,0 +1,301 @@
+import type { OnboardMeConfig, FlowConfig, FlowStep } from '@onboardme/types';
+import { logger } from '../utils/logger.js';
+import { validateConfig } from './config.js';
+import { detectUser } from '../detection/user-detection.js';
+import { getAnonymousId } from '../utils/fingerprint.js';
+import { getShadowRoot } from '../components/shadow-host.js';
+import { showModal } from '../components/modal.js';
+import { renderChecklist } from '../components/checklist.js';
+import { showCelebration } from '../components/celebration.js';
+import { loadProgress } from '../storage/progress-tracker.js';
+import { configureBatcher, attachFlushListeners, pushEvent } from './event-batcher.js';
+import { collectContext } from '../auto-generate/context-collector.js';
+import { fetchGeneratedFlows, mergeFlows } from '../auto-generate/flow-generator-client.js';
+import { fetchFlowsWithFallback, startFlowsPolling, stopFlowsPolling } from './api-flows.js';
+import { collectAndSendSnapshot } from '../snapshot/sender.js';
+import { isV2FlowConfig } from '../v2/types.js';
+import { renderV2Flow, type V2RenderHandle } from '../v2/renderer.js';
+
+export interface SDKState {
+  config: OnboardMeConfig;
+  anonymousId: string;
+  showOnboarding: boolean;
+}
+
+// Module-level initialised guard — prevents duplicate modals if the host app
+// calls init() more than once (belt-and-suspenders alongside index.ts guard).
+let _initialised = false;
+let _config: OnboardMeConfig | null = null;
+
+// Architecture v2 — Phase F. Active v2 render handles, keyed by flow id.
+// Tracked at module scope so polling refreshes can tear down stale renders
+// before mounting the new ones.
+const _v2Handles = new Map<string, V2RenderHandle>();
+
+function _teardownV2Renders(): void {
+  for (const handle of _v2Handles.values()) handle.destroy();
+  _v2Handles.clear();
+}
+
+/**
+ * Core orchestrator — runs once on init().
+ * Returns the initialised SDK state, or null if config is invalid.
+ *
+ * Sequence:
+ * 1. Guard against double-init (warn, return null)
+ * 2. Validate config (warn, never throw)
+ * 3. Generate / retrieve anonymousId
+ * 4. Run user detection
+ * 5. Set showOnboarding flag
+ * 6. If apiFlows is configured: fetch flows from API + start polling
+ * 7. If new user: schedule showModal via setTimeout(fn, 0) — defers until
+ *    after init() returns so initialisation stays synchronous
+ * 8. Warn if no flows are defined
+ */
+export function runSDK(raw: unknown): SDKState | null {
+  if (_initialised) {
+    logger.warn('OnboardMe already initialised — ignoring duplicate init() call.');
+    return null;
+  }
+
+  const config = validateConfig(raw);
+  if (!config) return null;
+
+  _initialised = true;
+  _config = config;
+
+  logger.log(`initialised for product: ${config.productId}`);
+
+  const anonymousId = getAnonymousId(config.productId);
+  logger.log(`anonymous ID: ${anonymousId}`);
+
+  // Wire event batcher — must happen before any component emits events
+  configureBatcher(config.eventsEndpoint ?? 'http://localhost:3001/events', anonymousId);
+  attachFlushListeners();
+
+  const detection = detectUser(config);
+  const showOnboarding = detection.isNew;
+
+  if (detection.isNew) {
+    logger.log(`new user detected (reason: ${detection.reason})`);
+  } else {
+    logger.log(`returning user, skipping onboarding`);
+  }
+
+  // Fetch flows from API if configured
+  if (config.apiFlows) {
+    void _bootstrapApiFlows(config, showOnboarding);
+    // Architecture v2 / Phase B — opportunistic DOM snapshot.
+    // Sends one snapshot per session per page so OnboardMe can build flows
+    // grounded in the host app's actual UI. Fire-and-forget; never blocks.
+    void _bootstrapSnapshot(config);
+  } else if (config.flows.length === 0) {
+    logger.warn('no flows defined in config — nothing to show');
+  } else {
+    _renderFlows(config.flows, config, showOnboarding);
+  }
+
+  if (config.autoGenerate) {
+    void _bootstrapAutoGenerate(config, showOnboarding);
+  }
+
+  return { config, anonymousId, showOnboarding };
+}
+
+/**
+ * Sends a single DOM snapshot for the current page if apiFlows is configured.
+ * Debounced server-side AND client-side (sessionStorage). Never throws.
+ * Defers to setTimeout(0) so init() returns synchronously and the host
+ * page's first paint isn't delayed by snapshot collection.
+ */
+async function _bootstrapSnapshot(config: OnboardMeConfig): Promise<void> {
+  if (!config.apiFlows) return;
+  // Defer one tick so the SDK doesn't compete with first paint.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await collectAndSendSnapshot(
+    config.productId,
+    config.apiFlows.endpoint,
+    config.apiFlows.apiKey,
+  );
+}
+
+/**
+ * Renders the first modal step (for new users) and the first checklist flow
+ * from the given flows array. Shared by the sync init path and the async
+ * auto-generate path so both use identical rendering logic.
+ */
+export function _renderFlows(
+  flows: FlowConfig[],
+  config: OnboardMeConfig,
+  showOnboarding: boolean,
+): void {
+  if (flows.length === 0) return;
+
+  // Architecture v2 — Phase F. Partition flows by schema. v2 flows go through
+  // the new renderer (tooltip / modal / highlight matching the v2 API schema);
+  // legacy flows continue down the original modal/checklist path below.
+  const legacyFlows: FlowConfig[] = [];
+  for (const flow of flows) {
+    if (isV2FlowConfig(flow.config ?? flow)) {
+      // Tear down any previous render of this same flow (e.g. on a polling
+      // refresh) before mounting the new version.
+      _v2Handles.get(flow.id)?.destroy();
+      _v2Handles.delete(flow.id);
+
+      // The v2 API stores steps under flow.config.steps; some legacy code
+      // paths nest them at flow.steps. Normalise here so the renderer
+      // accepts both shapes.
+      const v2Config = isV2FlowConfig(flow.config) ? flow.config : (flow as unknown as { steps: unknown }).steps
+        ? { steps: (flow as unknown as { steps: unknown[] }).steps }
+        : null;
+      if (!v2Config) continue;
+
+      // Defer to a microtask so init() stays synchronous and host first paint
+      // isn't delayed by querying the DOM for tooltip targets.
+      setTimeout(() => {
+        const handle = renderV2Flow(v2Config as { steps: never[] }, getShadowRoot());
+        if (handle) _v2Handles.set(flow.id, handle);
+      }, 0);
+    } else {
+      legacyFlows.push(flow);
+    }
+  }
+
+  if (legacyFlows.length === 0) return;
+  flows = legacyFlows;
+
+  if (showOnboarding) {
+    interface ModalCandidate { step: FlowStep; flowId: string }
+    const candidates: ModalCandidate[] = flows
+      .flatMap((f) => f.steps.filter((s) => s.type === 'modal').map((s) => ({ step: s, flowId: f.id })))
+      .sort((a, b) => a.step.order - b.step.order);
+    const first = candidates[0];
+    if (first) {
+      setTimeout(() => {
+        showModal(first.step, getShadowRoot(), config.productId, first.flowId);
+      }, 0);
+    } else {
+      logger.log('no modal step found — skipping welcome modal');
+    }
+  }
+
+  for (const flow of flows) {
+    if (!flow.steps.some((s) => s.type === 'checklist')) continue;
+    const progress = loadProgress(config.productId, flow.id);
+    setTimeout(() => {
+      renderChecklist(flow, progress, getShadowRoot(), config.debug ?? false, config.productId, flow.id);
+    }, 0);
+    break; // only the first checklist flow
+  }
+}
+
+/**
+ * Async bootstrap for fetching flows from the OnboardMe API. Runs
+ * fire-and-forget after the synchronous init path. Only active when
+ * config.apiFlows is set. Fetches initial flows and starts polling
+ * for updates every 60 seconds.
+ */
+export async function _bootstrapApiFlows(
+  config: OnboardMeConfig,
+  showOnboarding: boolean,
+): Promise<void> {
+  if (!config.apiFlows) return;
+
+  const cacheKey = `onboardme_flows_${config.productId}`;
+  const response = await fetchFlowsWithFallback(
+    config.apiFlows.endpoint,
+    config.apiFlows.apiKey,
+    cacheKey,
+  );
+
+  if (response.flows.length === 0) {
+    logger.warn('no flows from API and no cache available');
+    return;
+  }
+
+  // Update module config with API flows
+  if (_config) {
+    _config = { ..._config, flows: response.flows };
+  }
+
+  _renderFlows(response.flows, config, showOnboarding);
+
+  // Start polling for updates — uses checksumHash to avoid unnecessary re-renders
+  startFlowsPolling(
+    config.apiFlows.endpoint,
+    config.apiFlows.apiKey,
+    cacheKey,
+    (flows: FlowConfig[]) => {
+      // Update config with new flows
+      if (_config) {
+        _config = { ..._config, flows };
+      }
+      // Re-render new flows
+      _renderFlows(flows, config, showOnboarding);
+    },
+  );
+}
+
+/**
+ * Async bootstrap for AI-generated flows. Runs fire-and-forget after the
+ * synchronous init path. Only active when config.autoGenerate is set.
+ * Collects DOM context, fetches generated flows, merges with manual flows,
+ * and renders any novel flows that are not already in the manual config.
+ */
+export async function _bootstrapAutoGenerate(
+  config: OnboardMeConfig,
+  showOnboarding: boolean,
+): Promise<void> {
+  if (!config.autoGenerate) return;
+
+  const context = collectContext();
+  const generated = await fetchGeneratedFlows(
+    config.autoGenerate.endpoint,
+    config.productId,
+    context,
+    config.autoGenerate.cacheTtlMs,
+  );
+
+  if (generated.length === 0) return;
+
+  const existingIds = new Set(config.flows.map((f) => f.id));
+  const novel = generated.filter((f) => !existingIds.has(f.id));
+
+  if (novel.length === 0) return;
+
+  // Update module config so checkCompletionGoal sees generated flows
+  if (_config) {
+    _config = { ..._config, flows: mergeFlows(_config.flows, generated) };
+  }
+
+  _renderFlows(novel, config, showOnboarding);
+}
+
+/**
+ * Checks whether a tracked event name matches any active flow's completionGoal.
+ * If it does and the goal has not already fired, enqueues flow_completed +
+ * goal_reached events and shows the celebration banner.
+ * Called by index.ts track() on every OnboardMe.track() invocation.
+ */
+export function checkCompletionGoal(eventName: string): void {
+  if (!_config) return;
+
+  for (const flow of _config.flows) {
+    if (eventName !== flow.completionGoal) continue;
+
+    const key = `onboardme_flow_done_${_config.productId}_${flow.id}`;
+    if (localStorage.getItem(key)) continue; // already fired — prevent duplicate
+
+    localStorage.setItem(key, '1');
+    pushEvent('flow_completed', { flowId: flow.id });
+    pushEvent('goal_reached', { flowId: flow.id });
+    showCelebration(getShadowRoot());
+  }
+}
+
+/** Resets the initialised flag — only used in tests. */
+export function _resetSDK(): void {
+  _initialised = false;
+  _config = null;
+  stopFlowsPolling();
+}

package/src/detection/user-detection.ts

@@ -0,0 +1,55 @@
+import type { OnboardMeConfig } from '@onboardme/types';
+
+export type DetectionResult =
+  | { isNew: true;  reason: 'first_visit' | 'new_account' }
+  | { isNew: false; reason: 'returning' };
+
+const NEW_ACCOUNT_THRESHOLD_MS = 48 * 60 * 60 * 1000; // 48 hours
+
+/**
+ * Three-layer first-time user detection, checked in order:
+ *
+ * Layer 1 — localStorage flag: if onboardme_seen_{productId} exists → returning user.
+ * Layer 2 — Account age: if config.user.createdAt < 48h ago → new user.
+ * Layer 3 — Fallback: no info → treat as new (better to show once too many than miss a new user).
+ *
+ * On a positive new-user result, the seen flag is written to localStorage
+ * so the next visit is correctly identified as returning.
+ */
+export function detectUser(config: OnboardMeConfig): DetectionResult {
+  const seenKey = `onboardme_seen_${config.productId}`;
+
+  // Layer 1 — localStorage flag
+  try {
+    if (localStorage.getItem(seenKey) !== null) {
+      return { isNew: false, reason: 'returning' };
+    }
+  } catch {
+    // localStorage unavailable — fall through to next layer
+  }
+
+  // Layer 2 — Account age
+  const createdAt = config.user?.createdAt;
+  if (createdAt) {
+    const ageMs = Date.now() - new Date(createdAt).getTime();
+    if (ageMs >= NEW_ACCOUNT_THRESHOLD_MS) {
+      // Old account, probably cleared their cache — treat as returning
+      return { isNew: false, reason: 'returning' };
+    }
+    // Account is fresh — new user
+    _markSeen(seenKey);
+    return { isNew: true, reason: 'new_account' };
+  }
+
+  // Layer 3 — Fallback: no information, assume new
+  _markSeen(seenKey);
+  return { isNew: true, reason: 'first_visit' };
+}
+
+function _markSeen(key: string): void {
+  try {
+    localStorage.setItem(key, '1');
+  } catch {
+    // Silently ignore if localStorage is unavailable
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+import type { OnboardMeConfig } from '@onboardme/types';
+import { setDebug, logger } from './utils/logger.js';
+import { runSDK, checkCompletionGoal } from './core/sdk.js';
+import { setBatcherUserId, pushEvent } from './core/event-batcher.js';
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+let _initialised = false;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const OnboardMe = {
+  init(config: OnboardMeConfig): void {
+    if (_initialised) {
+      logger.warn('init() called more than once — ignoring duplicate call.');
+      return;
+    }
+
+    // Enable debug logging before any further output
+    if (config?.debug) setDebug(true);
+
+    const state = runSDK(config);
+    if (!state) return;
+
+    _initialised = true;
+
+    // Replay any calls that were queued before the script finished loading
+    _replayQueue();
+  },
+
+  identify(userId: string, traits?: Record<string, unknown>): void {
+    if (!_initialised) {
+      logger.warn('identify() called before init() — call will be ignored.');
+      return;
+    }
+    setBatcherUserId(userId);
+    logger.log(`identify: ${userId}`, traits);
+  },
+
+  track(eventName: string, properties?: Record<string, unknown>): void {
+    if (!_initialised) {
+      logger.warn('track() called before init() — call will be ignored.');
+      return;
+    }
+    pushEvent('step_action_taken', { properties: { eventName, ...(properties ?? {}) } });
+    checkCompletionGoal(eventName);
+    logger.log(`track: ${eventName}`, properties);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Async snippet queue replay
+// Product teams paste a stub into their HTML before the SDK loads.
+// The stub queues calls in window.OnboardMe._q.
+// When the real SDK loads, we replay everything that was buffered.
+// ---------------------------------------------------------------------------
+
+type QueueEntry = [string, IArguments | unknown[]];
+
+interface OnboardMeStub {
+  _q?: QueueEntry[];
+}
+
+function _replayQueue(): void {
+  const stub = (window as unknown as { OnboardMe?: OnboardMeStub }).OnboardMe;
+  const queue = stub?._q;
+  if (!Array.isArray(queue) || queue.length === 0) return;
+
+  logger.log(`replaying ${queue.length} queued call(s)`);
+
+  for (const [method, args] of queue) {
+    if (method === 'identify') {
+      OnboardMe.identify(args[0] as string, args[1] as Record<string, unknown>);
+    } else if (method === 'track') {
+      OnboardMe.track(args[0] as string, args[1] as Record<string, unknown>);
+    }
+  }
+
+  // Clear the queue so replayed calls are not re-run
+  if (stub) stub._q = [];
+}
+
+// Replace the stub on window with the real SDK
+(window as unknown as { OnboardMe: typeof OnboardMe }).OnboardMe = OnboardMe;
+
+export default OnboardMe;
+
+/** Resets the index-level initialised flag — only used in tests. */
+export function _resetIndex(): void {
+  _initialised = false;
+}

package/src/snapshot/dom-collector.ts

@@ -0,0 +1,193 @@
+// DOM collector (Architecture v2 — Phase B).
+//
+// Walks the host page's DOM and extracts a normalised, AI-readable summary
+// of the UI: headings, buttons, links, form inputs, navigation, images.
+// Output is the SnapshotPayload the API expects at POST /v1/code-sources/snapshot.
+//
+// Constraints:
+//   - Read-only — never mutates the host page DOM
+//   - Bounded — caps element count and text length per element
+//   - Resilient — wrapped in try/catch where a malformed DOM might throw
+
+export type SnapshotRole =
+  | 'heading'
+  | 'button'
+  | 'link'
+  | 'input'
+  | 'form'
+  | 'nav'
+  | 'image'
+  | 'other'
+
+export interface SnapshotElement {
+  selector:    string
+  role:        SnapshotRole
+  text?:       string
+  attributes?: Record<string, string>
+}
+
+export interface SnapshotPayload {
+  pageUrl:     string
+  pageTitle:   string
+  collectedAt: number
+  elements:    SnapshotElement[]
+  meta?: {
+    userAgent?: string
+    viewport?:  { width: number; height: number }
+  }
+}
+
+const MAX_ELEMENTS  = 500
+const MAX_TEXT_LEN  = 200
+
+// Roles in the order we collect them — earlier roles win when an element
+// could match multiple categories (e.g. <a role="button"> is a button).
+const COLLECTORS: Array<{ selector: string; role: SnapshotRole }> = [
+  { selector: 'h1, h2, h3, h4, h5, h6',                     role: 'heading' },
+  { selector: 'button, [role="button"]',                    role: 'button'  },
+  { selector: 'a[href]',                                    role: 'link'    },
+  { selector: 'input, textarea, select',                    role: 'input'   },
+  { selector: 'form',                                       role: 'form'    },
+  { selector: 'nav, [role="navigation"]',                   role: 'nav'     },
+  { selector: 'img[alt]',                                   role: 'image'   },
+]
+
+const ATTRIBUTES_BY_ROLE: Record<SnapshotRole, string[]> = {
+  heading: [],
+  button:  ['type', 'name', 'aria-label', 'data-testid'],
+  link:    ['href', 'aria-label', 'data-testid'],
+  input:   ['type', 'name', 'placeholder', 'aria-label', 'data-testid'],
+  form:    ['name', 'action', 'method'],
+  nav:     ['aria-label'],
+  image:   ['alt', 'src'],
+  other:   [],
+}
+
+export function collectSnapshot(doc: Document = document, win: Window = window): SnapshotPayload {
+  const seen = new Set<Element>()
+  const elements: SnapshotElement[] = []
+
+  for (const { selector, role } of COLLECTORS) {
+    const nodes = safeQueryAll(doc, selector)
+    for (const node of nodes) {
+      if (seen.has(node)) continue
+      if (!isVisible(node, win)) continue
+      seen.add(node)
+
+      const el: SnapshotElement = {
+        selector: buildSelector(node),
+        role,
+      }
+      const text = extractText(node)
+      if (text) el.text = text
+      const attrs = extractAttributes(node, role)
+      if (Object.keys(attrs).length > 0) el.attributes = attrs
+
+      elements.push(el)
+      if (elements.length >= MAX_ELEMENTS) break
+    }
+    if (elements.length >= MAX_ELEMENTS) break
+  }
+
+  return {
+    pageUrl:     win.location?.href ?? '',
+    pageTitle:   doc.title ?? '',
+    collectedAt: Date.now(),
+    elements,
+    meta: {
+      userAgent: win.navigator?.userAgent,
+      viewport:  {
+        width:  win.innerWidth ?? 0,
+        height: win.innerHeight ?? 0,
+      },
+    },
+  }
+}
+
+// ─── Selector synthesis ──────────────────────────────────────────────────────
+// Prefers stable identifiers in this order:
+//   1. data-testid attribute
+//   2. id attribute (if it doesn't look auto-generated)
+//   3. tag + nth-of-type fallback (always present)
+// Auto-generated id heuristic: contains digits beyond a small constant or
+// matches react/__-style prefixes — these change across renders.
+
+export function buildSelector(el: Element): string {
+  const testId = el.getAttribute('data-testid')
+  if (testId) return `[data-testid="${cssEscape(testId)}"]`
+
+  const id = el.getAttribute('id')
+  if (id && !looksAutoGenerated(id)) return `#${cssEscape(id)}`
+
+  const tag = el.tagName.toLowerCase()
+
+  // nth-of-type relative to siblings of same tag — gives a unique selector
+  // even when no IDs/classes are available.
+  const parent = el.parentElement
+  if (!parent) return tag
+
+  const siblings = Array.from(parent.children).filter((c) => c.tagName === el.tagName)
+  if (siblings.length === 1) return tag
+  const idx = siblings.indexOf(el) + 1
+  return `${tag}:nth-of-type(${idx})`
+}
+
+function looksAutoGenerated(id: string): boolean {
+  // React/Vue framework patterns: __, react-, _stable_, long digit runs
+  if (id.startsWith('__') || id.startsWith('_react')) return true
+  const digitRun = id.match(/\d{6,}/)
+  return digitRun !== null
+}
+
+// CSS.escape isn't available everywhere — a minimal-shim covers identifier chars.
+function cssEscape(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`)
+}
+
+// ─── Text extraction ─────────────────────────────────────────────────────────
+
+function extractText(el: Element): string {
+  const raw = (el as HTMLElement).innerText ?? el.textContent ?? ''
+  const trimmed = raw.replace(/\s+/g, ' ').trim()
+  if (trimmed.length === 0) return ''
+  if (trimmed.length <= MAX_TEXT_LEN) return trimmed
+  return trimmed.slice(0, MAX_TEXT_LEN - 1) + '…'
+}
+
+// ─── Attribute extraction ────────────────────────────────────────────────────
+
+function extractAttributes(el: Element, role: SnapshotRole): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const name of ATTRIBUTES_BY_ROLE[role]) {
+    const val = el.getAttribute(name)
+    if (val !== null && val.length > 0) out[name] = val.slice(0, 200)
+  }
+  return out
+}
+
+// ─── Visibility check ────────────────────────────────────────────────────────
+// Skip hidden elements — they're not part of the actual user-visible UI.
+
+function isVisible(el: Element, win: Window): boolean {
+  // jsdom's getComputedStyle returns sensible defaults; in production browsers
+  // it's authoritative. Either way, treat unknowns as visible (safer for
+  // capture; if we miss showing something, the user can always re-collect).
+  try {
+    const style = win.getComputedStyle?.(el as HTMLElement)
+    if (!style) return true
+    if (style.display === 'none') return false
+    if (style.visibility === 'hidden') return false
+    if (style.opacity === '0') return false
+  } catch {
+    return true
+  }
+  return true
+}
+
+function safeQueryAll(doc: Document, selector: string): Element[] {
+  try {
+    return Array.from(doc.querySelectorAll(selector))
+  } catch {
+    return []
+  }
+}