onboardme-sdk 0.0.1

package/src/core/api-flows.ts

@@ -0,0 +1,204 @@
+import type { FlowConfig } from '@onboardme/types'
+import { logger } from '../utils/logger.js'
+
+export interface FlowsResponse {
+  flows: FlowConfig[]
+  checksumHash: string
+}
+
+interface CachedFlows {
+  flows: FlowConfig[]
+  checksumHash: string
+  timestamp: number
+}
+
+// In-memory cache for flows and their checksum
+let _cachedFlows: CachedFlows | null = null
+let _pollInterval: ReturnType<typeof setInterval> | null = null
+let _lastChecksumHash: string = ''
+
+const POLL_INTERVAL_MS = 60000 // 60 seconds
+const CACHE_TIMEOUT_MS = 3600000 // 1 hour
+
+/**
+ * Fetches flows from the API endpoint with a 10s timeout.
+ * Returns null if fetch fails (network error, timeout, parse error).
+ * Never throws.
+ */
+export async function fetchFlowsFromAPI(endpoint: string, apiKey: string): Promise<FlowsResponse | null> {
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 10000)
+
+    const response = await fetch(`${endpoint}/v1/flows`, {
+      method: 'GET',
+      headers: {
+        'x-api-key': apiKey,
+        'Content-Type': 'application/json',
+      },
+      signal: controller.signal,
+    })
+
+    clearTimeout(timeoutId)
+
+    if (!response.ok) {
+      logger.warn(`Failed to fetch flows: HTTP ${response.status}`)
+      return null
+    }
+
+    const data = await response.json() as FlowsResponse
+    return data
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        logger.warn('Fetch flows timeout (10s)')
+      } else {
+        logger.warn(`Fetch flows error: ${error.message}`)
+      }
+    }
+    return null
+  }
+}
+
+/**
+ * Loads flows from localStorage cache.
+ * Returns null if cache is missing or expired.
+ */
+export function loadFlowsFromCache(cacheKey: string): CachedFlows | null {
+  try {
+    const cached = localStorage.getItem(cacheKey)
+    if (!cached) return null
+
+    const data = JSON.parse(cached) as CachedFlows
+    const age = Date.now() - data.timestamp
+    if (age > CACHE_TIMEOUT_MS) {
+      logger.log('Flows cache expired (1h)')
+      localStorage.removeItem(cacheKey)
+      return null
+    }
+
+    return data
+  } catch (error) {
+    logger.warn('Failed to parse flows cache')
+    return null
+  }
+}
+
+/**
+ * Saves flows to localStorage cache with timestamp.
+ */
+export function saveFlowsToCache(cacheKey: string, flows: FlowConfig[], checksumHash: string): void {
+  try {
+    const data: CachedFlows = {
+      flows,
+      checksumHash,
+      timestamp: Date.now(),
+    }
+    localStorage.setItem(cacheKey, JSON.stringify(data))
+  } catch (error) {
+    logger.warn('Failed to save flows to cache')
+  }
+}
+
+/**
+ * Fetches flows from API or returns cached flows.
+ * On success, caches the flows and returns them.
+ * On API failure, returns cached flows if available.
+ * On all failure, returns empty array (silent fallback).
+ */
+export async function fetchFlowsWithFallback(
+  endpoint: string,
+  apiKey: string,
+  cacheKey: string,
+): Promise<{ flows: FlowConfig[]; checksumHash: string }> {
+  // Try API first
+  const apiResponse = await fetchFlowsFromAPI(endpoint, apiKey)
+  if (apiResponse) {
+    saveFlowsToCache(cacheKey, apiResponse.flows, apiResponse.checksumHash)
+    _cachedFlows = {
+      flows: apiResponse.flows,
+      checksumHash: apiResponse.checksumHash,
+      timestamp: Date.now(),
+    }
+    return apiResponse
+  }
+
+  // Fall back to cache
+  const cached = loadFlowsFromCache(cacheKey)
+  if (cached) {
+    logger.log('Using cached flows from localStorage')
+    _cachedFlows = cached
+    return {
+      flows: cached.flows,
+      checksumHash: cached.checksumHash,
+    }
+  }
+
+  // No cache and API failed — return empty
+  logger.warn('No flows available (API down, cache empty)')
+  return { flows: [], checksumHash: '' }
+}
+
+/**
+ * Starts polling the API for flow updates every 60s.
+ * Only re-renders if checksumHash changes (intelligent caching).
+ * Polling stops and restarts on demand — see startFlowsPolling().
+ */
+export function startFlowsPolling(
+  endpoint: string,
+  apiKey: string,
+  cacheKey: string,
+  onFlowsUpdated: (flows: FlowConfig[], checksumHash: string) => void,
+): void {
+  if (_pollInterval) return; // Already polling
+
+  logger.log('Starting flows polling (60s interval)')
+
+  // First check immediately
+  void (async () => {
+    const response = await fetchFlowsFromAPI(endpoint, apiKey)
+    if (response && response.checksumHash !== _lastChecksumHash) {
+      _lastChecksumHash = response.checksumHash
+      saveFlowsToCache(cacheKey, response.flows, response.checksumHash)
+      onFlowsUpdated(response.flows, response.checksumHash)
+    }
+  })()
+
+  // Then poll every 60s
+  _pollInterval = setInterval(async () => {
+    const response = await fetchFlowsFromAPI(endpoint, apiKey)
+    if (response && response.checksumHash !== _lastChecksumHash) {
+      logger.log('Flows updated (new checksum detected)')
+      _lastChecksumHash = response.checksumHash
+      saveFlowsToCache(cacheKey, response.flows, response.checksumHash)
+      onFlowsUpdated(response.flows, response.checksumHash)
+    }
+  }, POLL_INTERVAL_MS)
+}
+
+/**
+ * Stops the flows polling interval.
+ */
+export function stopFlowsPolling(): void {
+  if (_pollInterval) {
+    clearInterval(_pollInterval)
+    _pollInterval = null
+    logger.log('Flows polling stopped')
+  }
+}
+
+/**
+ * Gets the currently cached flows. Used by tests or debugging.
+ */
+export function getCachedFlows(): CachedFlows | null {
+  return _cachedFlows
+}
+
+/**
+ * Clears all cached flows and stops polling. Used in tests.
+ */
+export function _clearFlowsCache(): void {
+  _cachedFlows = null
+  _lastChecksumHash = ''
+  stopFlowsPolling()
+}

package/src/core/config.ts

@@ -0,0 +1,37 @@
+import type { OnboardMeConfig } from '@onboardme/types';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Validates and normalises the raw config passed to OnboardMe.init().
+ * All failures are logger.warn — never throw.
+ * Returns a normalised config with defaults applied.
+ */
+export function validateConfig(raw: unknown): OnboardMeConfig | null {
+  if (!raw || typeof raw !== 'object') {
+    logger.warn('init() called with no config — OnboardMe will not run.');
+    return null;
+  }
+
+  const config = raw as Record<string, unknown>;
+
+  if (!config['productId'] || typeof config['productId'] !== 'string') {
+    logger.warn('config.productId is required and must be a string — OnboardMe will not run.');
+    return null;
+  }
+
+  if (config['flows'] !== undefined && !Array.isArray(config['flows'])) {
+    logger.warn('config.flows must be an array — defaulting to [].');
+    config['flows'] = [];
+  }
+
+  // Apply defaults
+  return {
+    productId:      config['productId'] as string,
+    eventsEndpoint: config['eventsEndpoint'] as string | undefined,
+    autoGenerate:   config['autoGenerate'] as OnboardMeConfig['autoGenerate'] ?? undefined,
+    apiFlows:       config['apiFlows'] as OnboardMeConfig['apiFlows'] ?? undefined,
+    flows:          (config['flows'] as OnboardMeConfig['flows']) ?? [],
+    user:           config['user'] as OnboardMeConfig['user'] ?? undefined,
+    debug:          typeof config['debug'] === 'boolean' ? config['debug'] : false,
+  };
+}

package/src/core/event-batcher.ts

@@ -0,0 +1,169 @@
+import type { OnboardingEvent, EventType } from '@onboardme/types';
+import { logger } from '../utils/logger.js';
+import { postEvents } from './api-client.js';
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+const MAX_QUEUE_SIZE = 100;
+const AUTO_FLUSH_DELAY_MS = 5_000;
+
+let _endpoint = '';
+let _anonymousId = '';
+let _userId: string | undefined;
+let _queue: OnboardingEvent[] = [];
+let _flushTimer: ReturnType<typeof setTimeout> | null = null;
+let _listenersAttached = false;
+let _visibilityHandler: (() => void) | null = null;
+let _beforeUnloadHandler: (() => void) | null = null;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Configures the batcher with the endpoint and anonymousId to use for all events.
+ * Must be called once during init() before any pushEvent calls.
+ */
+export function configureBatcher(endpoint: string, anonymousId: string): void {
+  _endpoint = endpoint;
+  _anonymousId = anonymousId;
+}
+
+/** Sets the authenticated userId to include on future events after identify(). */
+export function setBatcherUserId(userId: string): void {
+  _userId = userId;
+}
+
+/**
+ * Adds an event to the in-memory queue.
+ * Auto-fills: eventId, anonymousId, userId, pageUrl, timestamp.
+ * Starts the 5s auto-flush timer on the first event.
+ * Drops the oldest event if the queue exceeds MAX_QUEUE_SIZE.
+ */
+export function pushEvent(
+  eventType: EventType,
+  partial: Omit<OnboardingEvent, 'eventId' | 'anonymousId' | 'eventType' | 'pageUrl' | 'timestamp'> = {},
+): void {
+  const event: OnboardingEvent = {
+    eventId: crypto.randomUUID(),
+    anonymousId: _anonymousId,
+    ...((_userId !== undefined) ? { userId: _userId } : {}),
+    eventType,
+    pageUrl: typeof window !== 'undefined' ? window.location.href : '',
+    timestamp: Date.now(),
+    ...partial,
+  };
+
+  if (_queue.length >= MAX_QUEUE_SIZE) {
+    _queue.shift(); // drop oldest to prevent unbounded growth
+    logger.warn('event queue full — oldest event dropped');
+  }
+
+  _queue.push(event);
+  logger.log(`event queued: ${eventType} (queue size: ${_queue.length})`);
+
+  // Start auto-flush timer only on the first event
+  if (_queue.length === 1 && _flushTimer === null) {
+    _flushTimer = setTimeout(() => {
+      _flushTimer = null;
+      flushEvents().catch(() => {});
+    }, AUTO_FLUSH_DELAY_MS);
+  }
+}
+
+/**
+ * Flushes all queued events to the configured endpoint.
+ * Clears the queue and cancels the timer on success.
+ * On failure: logs a warn, leaves the queue intact for retry.
+ * Never throws.
+ */
+export async function flushEvents(): Promise<void> {
+  if (_queue.length === 0) return;
+  if (!_endpoint) {
+    logger.warn('flushEvents called before configureBatcher — events not sent');
+    return;
+  }
+
+  // Cancel any pending auto-flush timer
+  if (_flushTimer !== null) {
+    clearTimeout(_flushTimer);
+    _flushTimer = null;
+  }
+
+  const batch = [..._queue];
+  const ok = await postEvents(_endpoint, batch);
+
+  if (ok) {
+    _queue = [];
+    logger.log(`flushed ${batch.length} event(s)`);
+  }
+  // On failure: queue retained so next flush can retry
+}
+
+/**
+ * Attaches visibilitychange and beforeunload flush listeners.
+ * Safe to call multiple times — listeners are only registered once.
+ *
+ * - visibilitychange: flushes via fetch when the tab is hidden (user switches tabs).
+ * - beforeunload: flushes via sendBeacon — fire-and-forget POST that survives page unload.
+ *   Regular fetch is unreliable during beforeunload; sendBeacon is the correct API for this.
+ */
+export function attachFlushListeners(): void {
+  if (_listenersAttached) return;
+  _listenersAttached = true;
+
+  _visibilityHandler = () => {
+    if (document.visibilityState === 'hidden') {
+      flushEvents().catch(() => {});
+    }
+  };
+
+  _beforeUnloadHandler = () => {
+    if (_queue.length === 0 || !_endpoint) return;
+    const payload = JSON.stringify({ events: _queue });
+    const sent = navigator.sendBeacon(_endpoint, new Blob([payload], { type: 'application/json' }));
+    if (sent) {
+      _queue = [];
+      if (_flushTimer !== null) {
+        clearTimeout(_flushTimer);
+        _flushTimer = null;
+      }
+    }
+  };
+
+  document.addEventListener('visibilitychange', _visibilityHandler);
+  window.addEventListener('beforeunload', _beforeUnloadHandler);
+}
+
+/** Removes flush listeners — only used in tests to prevent jsdom listener accumulation. */
+export function _detachFlushListeners(): void {
+  if (_visibilityHandler) {
+    document.removeEventListener('visibilitychange', _visibilityHandler);
+    _visibilityHandler = null;
+  }
+  if (_beforeUnloadHandler) {
+    window.removeEventListener('beforeunload', _beforeUnloadHandler);
+    _beforeUnloadHandler = null;
+  }
+  _listenersAttached = false;
+}
+
+/** Resets all batcher state — only used in tests. */
+export function _resetBatcher(): void {
+  _detachFlushListeners();
+  if (_flushTimer !== null) {
+    clearTimeout(_flushTimer);
+    _flushTimer = null;
+  }
+  _endpoint = '';
+  _anonymousId = '';
+  _userId = undefined;
+  _queue = [];
+}
+
+/** Returns a copy of the current queue — only used in tests. */
+export function _getQueue(): OnboardingEvent[] {
+  return [..._queue];
+}