@umituz/web-dashboard 6.0.0 → 6.1.0

package/src/domains/onboarding/utils/local-storage-bridge.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  buildOnboardingResult,
+  clearOnboardingProgress,
+  loadOnboardingProgress,
+  saveOnboardingProgress,
+} from './local-storage-bridge';
+import { defaultStorageKey } from './default-storage-key';
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+describe('local-storage-bridge round-trip', () => {
+  it('saves and loads progress under the default key', () => {
+    const startedAt = new Date('2026-01-01T10:00:00.000Z');
+    const ok = saveOnboardingProgress(undefined, {
+      currentStep: 2,
+      completedSteps: ['a', 'b'],
+      collected: { a: { selected: ['x'] } },
+      startedAt,
+      lastUpdated: new Date('2026-01-01T10:01:00.000Z'),
+    });
+    expect(ok).toBe(true);
+    expect(localStorage.getItem(defaultStorageKey)).toContain('"version":1');
+
+    const restored = loadOnboardingProgress(undefined);
+    expect(restored).not.toBeNull();
+    expect(restored?.currentStep).toBe(2);
+    expect(restored?.completedSteps).toEqual(['a', 'b']);
+    expect(restored?.collected).toEqual({ a: { selected: ['x'] } });
+    expect(restored?.startedAt.toISOString()).toBe('2026-01-01T10:00:00.000Z');
+  });
+
+  it('honors a custom storage key without touching the default one', () => {
+    saveOnboardingProgress('my-app:onboarding', {
+      currentStep: 1,
+      completedSteps: ['a'],
+      collected: {},
+      startedAt: new Date(),
+      lastUpdated: new Date(),
+    });
+    expect(localStorage.getItem('my-app:onboarding')).not.toBeNull();
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+  });
+
+  it('returns null and discards corrupt payloads so future saves start clean', () => {
+    localStorage.setItem(defaultStorageKey, '{corrupt');
+    expect(loadOnboardingProgress(undefined)).toBeNull();
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+  });
+
+  it('returns null when nothing is stored', () => {
+    expect(loadOnboardingProgress(undefined)).toBeNull();
+  });
+
+  it('clears the stored payload safely', () => {
+    saveOnboardingProgress(undefined, {
+      currentStep: 0,
+      completedSteps: [],
+      collected: {},
+      startedAt: new Date(),
+      lastUpdated: new Date(),
+    });
+    clearOnboardingProgress(undefined);
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+    expect(() => clearOnboardingProgress(undefined)).not.toThrow();
+  });
+});
+
+describe('buildOnboardingResult', () => {
+  it('computes the duration from start to finish', () => {
+    const result = buildOnboardingResult({
+      completedSteps: ['a', 'b'],
+      collected: { a: 1 },
+      startedAt: new Date('2026-01-01T10:00:00.000Z'),
+      finishedAt: new Date('2026-01-01T10:02:30.000Z'),
+    });
+    expect(result.durationMs).toBe(150_000);
+    expect(result.completedSteps).toEqual(['a', 'b']);
+    expect(result.collected).toEqual({ a: 1 });
+  });
+
+  it('clamps negative durations to zero', () => {
+    const result = buildOnboardingResult({
+      completedSteps: [],
+      collected: {},
+      startedAt: new Date('2026-01-01T10:02:30.000Z'),
+      finishedAt: new Date('2026-01-01T10:00:00.000Z'),
+    });
+    expect(result.durationMs).toBe(0);
+  });
+});

package/src/domains/onboarding/utils/local-storage-bridge.ts

@@ -0,0 +1,104 @@
+/**
+ * localStorage bridge for onboarding progress.
+ * Owns the I/O — validation, parsing, and the schema version are delegated
+ * to the validation module so this file is a thin persistence layer.
+ */
+
+import { elapsedMillis } from '../calc/elapsed-millis';
+import { isLocalStorageAvailable } from '../predicates/storage-available';
+import { checkStoredProgress } from '../validation/stored-progress-check';
+import { defaultStorageKey } from './default-storage-key';
+import type { OnboardingResult } from '../types/config';
+
+export interface RehydratedProgress {
+  currentStep: number;
+  completedSteps: string[];
+  collected: Record<string, unknown>;
+  startedAt: Date;
+  lastUpdated: Date;
+}
+
+function buildKey(customKey: string | undefined): string {
+  return customKey ?? defaultStorageKey;
+}
+
+/**
+ * Save the current progress to localStorage. Returns true on success.
+ * Surfaces persistence failures to the console; never silently masks them.
+ */
+export function saveOnboardingProgress(
+  key: string | undefined,
+  payload: {
+    currentStep: number;
+    completedSteps: ReadonlyArray<string>;
+    collected: Record<string, unknown>;
+    startedAt: Date;
+    lastUpdated: Date;
+  },
+): boolean {
+  if (!isLocalStorageAvailable()) return false;
+  try {
+    const serialized = JSON.stringify({
+      version: 1,
+      currentStep: payload.currentStep,
+      completedSteps: [...payload.completedSteps],
+      collected: { ...payload.collected },
+      startedAt: payload.startedAt.toISOString(),
+      lastUpdated: payload.lastUpdated.toISOString(),
+    });
+    window.localStorage.setItem(buildKey(key), serialized);
+    return true;
+  } catch (error) {
+     
+    console.error('[web-onboarding] failed to persist progress', error);
+    return false;
+  }
+}
+
+/**
+ * Load and validate a previously saved progress payload.
+ * Returns null if storage is unavailable, nothing is stored, or the payload is corrupt.
+ */
+export function loadOnboardingProgress(key: string | undefined): RehydratedProgress | null {
+  if (!isLocalStorageAvailable()) return null;
+  const raw = window.localStorage.getItem(buildKey(key));
+  const checked = checkStoredProgress(raw);
+  if (!checked.ok) {
+    if (raw !== null) {
+      // Corrupt payload — discard so future saves start clean.
+      window.localStorage.removeItem(buildKey(key));
+    }
+    return null;
+  }
+  return {
+    currentStep: checked.data.currentStep,
+    completedSteps: checked.data.completedSteps,
+    collected: checked.data.collected,
+    startedAt: new Date(checked.data.startedAt),
+    lastUpdated: new Date(checked.data.lastUpdated),
+  };
+}
+
+/** Remove the stored payload. Safe to call when nothing is stored. */
+export function clearOnboardingProgress(key: string | undefined): void {
+  if (!isLocalStorageAvailable()) return;
+  window.localStorage.removeItem(buildKey(key));
+}
+
+/**
+ * Build the final `OnboardingResult` value the consumer receives via
+ * `onComplete`. Owns the duration calculation; no magic numbers here.
+ */
+export function buildOnboardingResult(input: {
+  completedSteps: ReadonlyArray<string>;
+  collected: Record<string, unknown>;
+  startedAt: Date;
+  finishedAt: Date;
+}): OnboardingResult {
+  return {
+    completedSteps: input.completedSteps,
+    collected: input.collected,
+    durationMs: elapsedMillis(input.startedAt, input.finishedAt),
+    finishedAt: input.finishedAt,
+  };
+}

package/src/domains/onboarding/utils/permission-bridge.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { queryPermissionStatus, requestPermission } from './permission-bridge';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe('queryPermissionStatus', () => {
+  it('maps photos to prompt and contacts to unsupported (no web-standard API)', async () => {
+    await expect(queryPermissionStatus('photos')).resolves.toBe('prompt');
+    await expect(queryPermissionStatus('contacts')).resolves.toBe('unsupported');
+  });
+
+  it('reads Notification.permission for notifications', async () => {
+    vi.stubGlobal('Notification', { permission: 'granted' });
+    await expect(queryPermissionStatus('notifications')).resolves.toBe('granted');
+  });
+
+  it('normalizes the browser "default" state to prompt', async () => {
+    vi.stubGlobal('Notification', { permission: 'default' });
+    await expect(queryPermissionStatus('notifications')).resolves.toBe('prompt');
+  });
+
+  it('returns unsupported when Notification is missing', async () => {
+    const original = (globalThis as { Notification?: unknown }).Notification;
+    vi.stubGlobal('Notification', undefined);
+    try {
+      await expect(queryPermissionStatus('notifications')).resolves.toBe('unsupported');
+    } finally {
+      if (original !== undefined) vi.stubGlobal('Notification', original);
+    }
+  });
+});
+
+describe('requestPermission — never throws', () => {
+  it('resolves granted when the user accepts notifications', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.resolve('granted'),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('granted');
+  });
+
+  it('resolves denied when the user rejects notifications', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.resolve('denied'),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('denied');
+  });
+
+  it('maps a throwing requestPermission to denied, not a rejection', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.reject(new Error('blocked')),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('denied');
+  });
+
+  it('returns unsupported for permission types without a web API', async () => {
+    await expect(requestPermission('contacts')).resolves.toBe('unsupported');
+  });
+});

package/src/domains/onboarding/utils/permission-bridge.ts

@@ -0,0 +1,95 @@
+/**
+ * Browser permission API bridge.
+ * Owns the I/O — the predicates and the validation module decide whether
+ * the runtime supports the call, and how to normalize the raw status.
+ */
+
+import {
+  doesBrowserSupportMediaCapture,
+  doesBrowserSupportGeolocation,
+  doesBrowserSupportNotifications,
+} from '../predicates/permission-supports';
+import { normalizePermissionStatus } from '../validation/permission-status-check';
+import type { PermissionStatus, PermissionType } from '../types/screens';
+
+const GEOLOCATION_TIMEOUT_MS = 5000;
+
+/** Read the current permission status without prompting the user. */
+export async function queryPermissionStatus(permission: PermissionType): Promise<PermissionStatus> {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
+
+  try {
+    switch (permission) {
+      case 'notifications': {
+        if (!doesBrowserSupportNotifications()) return 'unsupported';
+        return normalizePermissionStatus(window.Notification.permission);
+      }
+      case 'camera':
+      case 'microphone': {
+        if (!doesBrowserSupportMediaCapture()) return 'unsupported';
+        if (!navigator.permissions?.query) return 'unsupported';
+        const status = await navigator.permissions.query({
+          name: permission === 'camera' ? 'camera' : 'microphone',
+        });
+        return normalizePermissionStatus(status.state);
+      }
+      case 'location': {
+        if (!doesBrowserSupportGeolocation()) return 'unsupported';
+        if (!navigator.permissions?.query) return 'unsupported';
+        const status = await navigator.permissions.query({ name: 'geolocation' });
+        return normalizePermissionStatus(status.state);
+      }
+      case 'photos':
+        return 'prompt';
+      case 'contacts':
+        return 'unsupported';
+      default:
+        return 'unsupported';
+    }
+  } catch {
+    return 'unsupported';
+  }
+}
+
+/** Prompt the user for the given permission. Never throws — failures map to a status. */
+export async function requestPermission(permission: PermissionType): Promise<PermissionStatus> {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
+
+  try {
+    switch (permission) {
+      case 'notifications': {
+        if (!doesBrowserSupportNotifications()) return 'unsupported';
+        const result = await window.Notification.requestPermission();
+        return normalizePermissionStatus(result);
+      }
+      case 'camera':
+      case 'microphone': {
+        if (!doesBrowserSupportMediaCapture()) return 'unsupported';
+        const constraints: MediaStreamConstraints =
+          permission === 'camera' ? { video: true } : { audio: true };
+        const stream = await navigator.mediaDevices.getUserMedia(constraints);
+        stream.getTracks().forEach((track) => track.stop());
+        return 'granted';
+      }
+      case 'location': {
+        if (!doesBrowserSupportGeolocation()) return 'unsupported';
+        return new Promise<PermissionStatus>((resolve) => {
+          navigator.geolocation.getCurrentPosition(
+            () => resolve('granted'),
+            (err) =>
+              resolve(err.code === err.PERMISSION_DENIED ? 'denied' : 'unsupported'),
+            { timeout: GEOLOCATION_TIMEOUT_MS },
+          );
+        });
+      }
+      case 'photos':
+        return 'prompt';
+      case 'contacts':
+        return 'unsupported';
+      default:
+        return 'unsupported';
+    }
+  } catch {
+    return 'denied';
+  }
+}

package/src/domains/onboarding/validation/flow-structure-check.ts

@@ -0,0 +1,28 @@
+import type { OnboardingScreen } from '../types/screens';
+import { checkScreenConfig } from './screen-config-check';
+
+export type ValidationOutcome = { ok: true } | { ok: false; reason: string };
+
+const MIN_FLOW_LENGTH = 1;
+
+/**
+ * Validates the structure of an entire onboarding flow:
+ *  - At least one screen exists
+ *  - Every screen passes its own check
+ *  - Step IDs are unique
+ */
+export function checkFlowStructure(screens: ReadonlyArray<OnboardingScreen>): ValidationOutcome {
+  if (!Array.isArray(screens) || screens.length < MIN_FLOW_LENGTH) {
+    return { ok: false, reason: 'flow must contain at least one screen' };
+  }
+  const seen = new Set<string>();
+  for (const screen of screens) {
+    const result = checkScreenConfig(screen);
+    if (!result.ok) return result;
+    if (seen.has(screen.id)) {
+      return { ok: false, reason: `duplicate step id: "${screen.id}"` };
+    }
+    seen.add(screen.id);
+  }
+  return { ok: true };
+}

package/src/domains/onboarding/validation/index.ts

@@ -0,0 +1,9 @@
+export { checkFlowStructure } from './flow-structure-check';
+export type { ValidationOutcome } from './flow-structure-check';
+export { checkScreenConfig, getRecognizedScreenTypes } from './screen-config-check';
+export { checkStoredProgress } from './stored-progress-check';
+export type { StoredProgressShape, StoredProgressOutcome } from './stored-progress-check';
+export {
+  isRecognizedPermissionStatus,
+  normalizePermissionStatus,
+} from './permission-status-check';

package/src/domains/onboarding/validation/permission-status-check.ts

@@ -0,0 +1,23 @@
+import type { PermissionStatus } from '../types/screens';
+
+const RECOGNIZED_STATUSES: ReadonlySet<PermissionStatus> = new Set<PermissionStatus>([
+  'granted',
+  'denied',
+  'prompt',
+  'unsupported',
+]);
+
+/** Is the given string one of the recognized permission statuses? */
+export function isRecognizedPermissionStatus(value: unknown): value is PermissionStatus {
+  return typeof value === 'string' && RECOGNIZED_STATUSES.has(value as PermissionStatus);
+}
+
+/**
+ * Normalize a browser-level permission string (which may be "default")
+ * to our internal PermissionStatus enum.
+ */
+export function normalizePermissionStatus(rawValue: string | null | undefined): PermissionStatus {
+  if (rawValue === 'granted' || rawValue === 'denied') return rawValue;
+  if (rawValue === 'default' || rawValue === 'prompt') return 'prompt';
+  return 'unsupported';
+}

package/src/domains/onboarding/validation/screen-config-check.ts

@@ -0,0 +1,105 @@
+import type {
+  OnboardingScreen,
+  OnboardingScreenType,
+} from '../types/screens';
+import type { ValidationOutcome } from './flow-structure-check';
+
+const RECOGNIZED_SCREEN_TYPES: ReadonlySet<OnboardingScreenType> = new Set<OnboardingScreenType>([
+  'welcome',
+  'goal-question',
+  'pain-points',
+  'social-proof',
+  'tinder-cards',
+  'personalized-solution',
+  'comparison',
+  'preferences',
+  'permission-priming',
+  'processing',
+  'app-demo',
+  'value-delivery',
+  'account-gate',
+  'paywall',
+]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function checkGoalQuestion(screen: OnboardingScreen): ValidationOutcome {
+  const options = (screen as { options?: unknown }).options;
+  if (!Array.isArray(options) || options.length === 0) {
+    return { ok: false, reason: 'goal-question screen requires non-empty options' };
+  }
+  return { ok: true };
+}
+
+function checkPainPoints(screen: OnboardingScreen): ValidationOutcome {
+  const points = (screen as { painPoints?: unknown }).painPoints;
+  if (!Array.isArray(points) || points.length === 0) {
+    return { ok: false, reason: 'pain-points screen requires non-empty painPoints' };
+  }
+  return { ok: true };
+}
+
+function checkTinderCards(screen: OnboardingScreen): ValidationOutcome {
+  const statements = (screen as { statements?: unknown }).statements;
+  if (!Array.isArray(statements) || statements.length === 0) {
+    return { ok: false, reason: 'tinder-cards screen requires non-empty statements' };
+  }
+  return { ok: true };
+}
+
+function checkPermissionPriming(screen: OnboardingScreen): ValidationOutcome {
+  const permission = (screen as { permission?: unknown }).permission;
+  if (typeof permission !== 'string') {
+    return { ok: false, reason: 'permission-priming screen requires a permission identifier' };
+  }
+  return { ok: true };
+}
+
+function checkPaywall(screen: OnboardingScreen): ValidationOutcome {
+  const price = (screen as { price?: unknown }).price;
+  const trialDays = (screen as { trialDays?: unknown }).trialDays;
+  if (typeof price !== 'string' || typeof trialDays !== 'number') {
+    return { ok: false, reason: 'paywall screen requires price and trialDays' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Validates a single screen config. Per-screen rules live here so the file
+ * is the single place to look when a new screen type is added.
+ */
+export function checkScreenConfig(screen: OnboardingScreen): ValidationOutcome {
+  if (!isPlainObject(screen)) {
+    return { ok: false, reason: 'screen must be an object' };
+  }
+  const id = (screen as { id?: unknown }).id;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, reason: 'screen.id must be a non-empty string' };
+  }
+  const type = (screen as { type?: unknown }).type;
+  if (typeof type !== 'string' || !RECOGNIZED_SCREEN_TYPES.has(type as OnboardingScreenType)) {
+    return { ok: false, reason: `screen.type "${String(type)}" is not a recognized screen type` };
+  }
+
+  switch (type) {
+    case 'goal-question':
+      return checkGoalQuestion(screen);
+    case 'pain-points':
+      return checkPainPoints(screen);
+    case 'tinder-cards':
+      return checkTinderCards(screen);
+    case 'permission-priming':
+      return checkPermissionPriming(screen);
+    case 'paywall':
+      return checkPaywall(screen);
+    default:
+      return { ok: true };
+  }
+}
+
+/** The set of screen types the orchestrator knows how to render. */
+export function getRecognizedScreenTypes(): ReadonlySet<OnboardingScreenType> {
+  return RECOGNIZED_SCREEN_TYPES;
+}

package/src/domains/onboarding/validation/stored-progress-check.ts

@@ -0,0 +1,68 @@
+/**
+ * Storage payload integrity check.
+ * Decides whether a localStorage string is something we can safely rehydrate
+ * from. The shape is versioned so future migrations stay clean.
+ */
+
+export interface StoredProgressShape {
+  version: 1;
+  currentStep: number;
+  completedSteps: string[];
+  collected: Record<string, unknown>;
+  startedAt: string; // ISO
+  lastUpdated: string; // ISO
+}
+
+export type StoredProgressOutcome =
+  | { ok: true; data: StoredProgressShape }
+  | { ok: false; reason: string };
+
+const STORAGE_VERSION = 1;
+const MIN_STEP_INDEX = 0;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+
+function isIsoDateString(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms);
+}
+
+/** Is the raw string a valid, current-version stored progress payload? */
+export function checkStoredProgress(raw: string | null): StoredProgressOutcome {
+  if (raw === null) return { ok: false, reason: 'no stored progress' };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      ok: false,
+      reason: e instanceof Error ? e.message : 'invalid JSON',
+    };
+  }
+  if (!isObject(parsed)) {
+    return { ok: false, reason: 'stored payload must be an object' };
+  }
+  if (parsed.version !== STORAGE_VERSION) {
+    return { ok: false, reason: `unsupported storage version: ${String(parsed.version)}` };
+  }
+  if (typeof parsed.currentStep !== 'number' || parsed.currentStep < MIN_STEP_INDEX) {
+    return { ok: false, reason: 'currentStep must be a non-negative number' };
+  }
+  if (!isStringArray(parsed.completedSteps)) {
+    return { ok: false, reason: 'completedSteps must be a string array' };
+  }
+  if (!isObject(parsed.collected)) {
+    return { ok: false, reason: 'collected must be an object' };
+  }
+  if (!isIsoDateString(parsed.startedAt) || !isIsoDateString(parsed.lastUpdated)) {
+    return { ok: false, reason: 'startedAt and lastUpdated must be ISO date strings' };
+  }
+  return { ok: true, data: parsed as unknown as StoredProgressShape };
+}