onboardme-sdk 0.0.1

package/src/__tests__/day2.test.ts

@@ -0,0 +1,447 @@
+/**
+ * Day 2 Tests — Shared Types
+ *
+ * These tests verify that every type defined in @onboardme/types has the right
+ * shape. They create example objects and check their fields at runtime so we
+ * know the types actually work — not just that TypeScript is happy at compile time.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+  FlowConfig,
+  FlowStep,
+  ChecklistItem,
+  Trigger,
+  Condition,
+  UserIdentity,
+  OnboardingEvent,
+  OnboardMeConfig,
+  EventType,
+  StepType,
+  TriggerType,
+  ConditionOperator,
+} from '@onboardme/types';
+
+// ---------------------------------------------------------------------------
+// Helpers — reusable minimal objects used across tests
+// ---------------------------------------------------------------------------
+
+const minimalTrigger: Trigger = { type: 'page_load' };
+
+const minimalStep: FlowStep = {
+  id: 'step-1',
+  type: 'modal',
+  order: 1,
+  title: 'Welcome!',
+  body: 'Let us show you around.',
+  trigger: minimalTrigger,
+};
+
+const minimalFlow: FlowConfig = {
+  id: 'flow-1',
+  name: 'Welcome Flow',
+  steps: [minimalStep],
+  completionGoal: 'first_project_created',
+  priority: 1,
+};
+
+// ---------------------------------------------------------------------------
+// FlowStep
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — FlowStep', () => {
+  it('a step has an id, type, order, title, body, and trigger', () => {
+    expect(minimalStep.id).toBe('step-1');
+    expect(minimalStep.type).toBe('modal');
+    expect(minimalStep.order).toBe(1);
+    expect(minimalStep.title).toBe('Welcome!');
+    expect(minimalStep.body).toBeDefined();
+    expect(minimalStep.trigger).toBeDefined();
+  });
+
+  it('order is a number you set yourself — two steps can have order 1 and 3, skipping 2', () => {
+    const stepA: FlowStep = { ...minimalStep, id: 'a', order: 1 };
+    const stepB: FlowStep = { ...minimalStep, id: 'b', order: 3 }; // gap is intentional
+    expect(stepA.order).toBe(1);
+    expect(stepB.order).toBe(3);
+    // The order values are independent — not derived from position in any array
+    expect(stepB.order - stepA.order).toBe(2);
+  });
+
+  it('a step can have optional media (image or video)', () => {
+    const stepWithImage: FlowStep = {
+      ...minimalStep,
+      media: { type: 'image', url: 'https://example.com/screenshot.png' },
+    };
+    expect(stepWithImage.media?.type).toBe('image');
+    expect(stepWithImage.media?.url).toContain('example.com');
+  });
+
+  it('a step can have custom CTA button labels — they are optional', () => {
+    const stepWithCtaLabels: FlowStep = {
+      ...minimalStep,
+      primaryCta: 'Get Started',
+      secondaryCta: 'Maybe Later',
+    };
+    expect(stepWithCtaLabels.primaryCta).toBe('Get Started');
+    expect(stepWithCtaLabels.secondaryCta).toBe('Maybe Later');
+    // A step without them is also valid
+    expect(minimalStep.primaryCta).toBeUndefined();
+  });
+
+  it('a checklist step can have a list of items', () => {
+    const item: ChecklistItem = {
+      id: 'item-1',
+      label: 'Connect your data source',
+      order: 1,
+    };
+    const checklistStep: FlowStep = {
+      ...minimalStep,
+      type: 'checklist',
+      items: [item],
+    };
+    expect(checklistStep.type).toBe('checklist');
+    expect(checklistStep.items).toHaveLength(1);
+    expect(checklistStep.items![0].label).toBe('Connect your data source');
+  });
+
+  it('a checklist item can auto-complete when a specific event fires', () => {
+    const item: ChecklistItem = {
+      id: 'item-2',
+      label: 'Invite a teammate',
+      order: 2,
+      completionEvent: 'teammate_invited',
+    };
+    expect(item.completionEvent).toBe('teammate_invited');
+  });
+
+  it('a step can have conditions — rules that decide whether to show the step', () => {
+    const condition: Condition = {
+      property: 'user.traits.plan',
+      operator: 'equals',
+      value: 'free',
+    };
+    const conditionalStep: FlowStep = {
+      ...minimalStep,
+      conditions: [condition],
+    };
+    expect(conditionalStep.conditions).toHaveLength(1);
+    expect(conditionalStep.conditions![0].operator).toBe('equals');
+    expect(conditionalStep.conditions![0].value).toBe('free');
+  });
+
+  it('a step can point to the next step by id', () => {
+    const step: FlowStep = { ...minimalStep, nextStep: 'step-2' };
+    expect(step.nextStep).toBe('step-2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Trigger
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — Trigger', () => {
+  it('a trigger can fire on page load (no extra value needed)', () => {
+    const t: Trigger = { type: 'page_load' };
+    expect(t.type).toBe('page_load');
+    expect(t.value).toBeUndefined();
+  });
+
+  it('a trigger can fire when the user clicks a specific element', () => {
+    const t: Trigger = { type: 'element_click', value: '#upgrade-button' };
+    expect(t.type).toBe('element_click');
+    expect(t.value).toBe('#upgrade-button');
+  });
+
+  it('a trigger can fire on a custom event sent by the host app', () => {
+    const t: Trigger = { type: 'custom_event', value: 'project_created' };
+    expect(t.type).toBe('custom_event');
+    expect(t.value).toBe('project_created');
+  });
+
+  it('a trigger can be manual — the step only shows when the app explicitly calls show()', () => {
+    const t: Trigger = { type: 'manual' };
+    expect(t.type).toBe('manual');
+  });
+
+  it('a trigger can have a delay in milliseconds before the step appears', () => {
+    const t: Trigger = { type: 'page_load', delay: 500 };
+    expect(t.delay).toBe(500);
+  });
+
+  it('all four trigger types are valid', () => {
+    const validTypes: TriggerType[] = ['page_load', 'element_click', 'custom_event', 'manual'];
+    validTypes.forEach((type) => {
+      const t: Trigger = { type };
+      expect(t.type).toBe(type);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FlowConfig
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — FlowConfig', () => {
+  it('a flow has an id, name, steps array, completionGoal, and priority', () => {
+    expect(minimalFlow.id).toBe('flow-1');
+    expect(minimalFlow.name).toBe('Welcome Flow');
+    expect(Array.isArray(minimalFlow.steps)).toBe(true);
+    expect(minimalFlow.completionGoal).toBe('first_project_created');
+    expect(typeof minimalFlow.priority).toBe('number');
+  });
+
+  it('a flow can have zero steps — the SDK must never crash on an empty flow', () => {
+    const emptyFlow: FlowConfig = {
+      id: 'empty',
+      name: 'Empty Flow',
+      steps: [],
+      completionGoal: 'anything',
+      priority: 0,
+    };
+    expect(emptyFlow.steps).toHaveLength(0);
+  });
+
+  it('steps are stored in an array but their display order is controlled by the order field, not array position', () => {
+    const stepFirst: FlowStep = { ...minimalStep, id: 's1', order: 1 };
+    const stepSecond: FlowStep = { ...minimalStep, id: 's2', order: 2 };
+    // Even if we put stepSecond before stepFirst in the array, order field wins
+    const flow: FlowConfig = {
+      ...minimalFlow,
+      steps: [stepSecond, stepFirst],
+    };
+    const sorted = [...flow.steps].sort((a, b) => a.order - b.order);
+    expect(sorted[0].id).toBe('s1');
+    expect(sorted[1].id).toBe('s2');
+  });
+
+  it('a flow can target a specific user segment', () => {
+    const segmentedFlow: FlowConfig = { ...minimalFlow, targetSegment: 'free-tier-users' };
+    expect(segmentedFlow.targetSegment).toBe('free-tier-users');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// UserIdentity
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — UserIdentity', () => {
+  it('a user always has an anonymousId — even before they log in', () => {
+    const user: UserIdentity = { anonymousId: 'anon-abc-123' };
+    expect(user.anonymousId).toBe('anon-abc-123');
+  });
+
+  it('userId is optional — new visitors do not have one yet', () => {
+    const anonymous: UserIdentity = { anonymousId: 'anon-xyz' };
+    expect(anonymous.userId).toBeUndefined();
+
+    const loggedIn: UserIdentity = { anonymousId: 'anon-xyz', userId: 'user-001' };
+    expect(loggedIn.userId).toBe('user-001');
+  });
+
+  it('createdAt is optional — it holds the ISO date string of when the account was made', () => {
+    const user: UserIdentity = {
+      anonymousId: 'anon-1',
+      createdAt: '2024-01-15T10:00:00.000Z',
+    };
+    expect(user.createdAt).toBe('2024-01-15T10:00:00.000Z');
+  });
+
+  it('traits is a flexible key-value store — any custom property goes here', () => {
+    const user: UserIdentity = {
+      anonymousId: 'anon-2',
+      traits: {
+        plan: 'pro',
+        company: 'Acme Corp',
+        teamSize: 42,
+        betaUser: true,
+      },
+    };
+    expect(user.traits?.plan).toBe('pro');
+    expect(user.traits?.teamSize).toBe(42);
+    expect(user.traits?.betaUser).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OnboardingEvent
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — OnboardingEvent', () => {
+  it('every event has an eventId, anonymousId, eventType, pageUrl, and timestamp', () => {
+    const event: OnboardingEvent = {
+      eventId: 'evt-001',
+      anonymousId: 'anon-abc',
+      eventType: 'flow_started',
+      pageUrl: 'https://app.example.com/dashboard',
+      timestamp: 1700000000000,
+    };
+    expect(event.eventId).toBe('evt-001');
+    expect(event.anonymousId).toBe('anon-abc');
+    expect(event.eventType).toBe('flow_started');
+    expect(event.pageUrl).toContain('dashboard');
+    expect(typeof event.timestamp).toBe('number');
+  });
+
+  it('timestamp is stored as a number (Unix milliseconds) — not a date string', () => {
+    const now = Date.now();
+    const event: OnboardingEvent = {
+      eventId: 'evt-002',
+      anonymousId: 'anon-abc',
+      eventType: 'step_viewed',
+      pageUrl: 'https://app.example.com/',
+      timestamp: now,
+    };
+    expect(typeof event.timestamp).toBe('number');
+    expect(event.timestamp).toBeGreaterThan(0);
+  });
+
+  it('all 11 event types are valid and accounted for', () => {
+    const allEventTypes: EventType[] = [
+      'flow_started',
+      'step_viewed',
+      'step_completed',
+      'step_skipped',
+      'step_action_taken',
+      'flow_completed',
+      'flow_abandoned',
+      'survey_answered',
+      'goal_reached',
+      'checklist_item_done',
+      'celebration_shown',
+    ];
+    expect(allEventTypes).toHaveLength(11);
+    allEventTypes.forEach((type) => {
+      expect(typeof type).toBe('string');
+    });
+  });
+
+  it('an event can optionally record which flow and step it came from', () => {
+    const event: OnboardingEvent = {
+      eventId: 'evt-003',
+      anonymousId: 'anon-abc',
+      eventType: 'step_completed',
+      pageUrl: 'https://app.example.com/',
+      timestamp: Date.now(),
+      flowId: 'flow-1',
+      stepId: 'step-2',
+      stepIndex: 1,
+    };
+    expect(event.flowId).toBe('flow-1');
+    expect(event.stepId).toBe('step-2');
+    expect(event.stepIndex).toBe(1);
+  });
+
+  it('an event can carry extra custom properties in a flexible key-value bag', () => {
+    const event: OnboardingEvent = {
+      eventId: 'evt-004',
+      anonymousId: 'anon-abc',
+      eventType: 'survey_answered',
+      pageUrl: 'https://app.example.com/',
+      timestamp: Date.now(),
+      properties: { answer: 'option_b', questionId: 'q-1' },
+    };
+    expect(event.properties?.answer).toBe('option_b');
+  });
+
+  it('a goal_reached event links a user reaching their Aha! moment', () => {
+    const event: OnboardingEvent = {
+      eventId: 'evt-005',
+      anonymousId: 'anon-abc',
+      eventType: 'goal_reached',
+      pageUrl: 'https://app.example.com/projects/new',
+      timestamp: Date.now(),
+      flowId: 'flow-1',
+    };
+    expect(event.eventType).toBe('goal_reached');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OnboardMeConfig
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — OnboardMeConfig', () => {
+  it('config only requires a productId and a flows array — everything else is optional', () => {
+    const config: OnboardMeConfig = {
+      productId: 'my-saas',
+      flows: [],
+    };
+    expect(config.productId).toBe('my-saas');
+    expect(Array.isArray(config.flows)).toBe(true);
+    expect(config.user).toBeUndefined();
+    expect(config.debug).toBeUndefined();
+  });
+
+  it('flows can be an empty array — the SDK handles it gracefully', () => {
+    const config: OnboardMeConfig = { productId: 'p1', flows: [] };
+    expect(config.flows).toHaveLength(0);
+  });
+
+  it('a user can be passed in config with just an id', () => {
+    const config: OnboardMeConfig = {
+      productId: 'p1',
+      flows: [],
+      user: { id: 'user-42' },
+    };
+    expect(config.user?.id).toBe('user-42');
+  });
+
+  it('a user in config can also include a createdAt date and custom traits', () => {
+    const config: OnboardMeConfig = {
+      productId: 'p1',
+      flows: [],
+      user: {
+        id: 'user-99',
+        createdAt: '2024-06-01T00:00:00.000Z',
+        traits: { plan: 'enterprise', seats: 200 },
+      },
+    };
+    expect(config.user?.createdAt).toBe('2024-06-01T00:00:00.000Z');
+    expect(config.user?.traits?.plan).toBe('enterprise');
+  });
+
+  it('debug mode is an optional boolean — off by default', () => {
+    const defaultConfig: OnboardMeConfig = { productId: 'p1', flows: [] };
+    const debugConfig: OnboardMeConfig = { productId: 'p1', flows: [], debug: true };
+    expect(defaultConfig.debug).toBeUndefined();
+    expect(debugConfig.debug).toBe(true);
+  });
+
+  it('a config can hold multiple flows at once', () => {
+    const config: OnboardMeConfig = {
+      productId: 'p1',
+      flows: [minimalFlow, { ...minimalFlow, id: 'flow-2', name: 'Upgrade Flow' }],
+    };
+    expect(config.flows).toHaveLength(2);
+    expect(config.flows[1].name).toBe('Upgrade Flow');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// StepType and ConditionOperator — enum-like string unions
+// ---------------------------------------------------------------------------
+
+describe('Day 2 — StepType', () => {
+  it('all 6 step types are valid', () => {
+    const validTypes: StepType[] = ['modal', 'tooltip', 'checklist', 'hotspot', 'survey', 'spotlight'];
+    expect(validTypes).toHaveLength(6);
+  });
+});
+
+describe('Day 2 — ConditionOperator', () => {
+  it('all 5 condition operators are valid', () => {
+    const operators: ConditionOperator[] = ['equals', 'not_equals', 'contains', 'greater_than', 'less_than'];
+    expect(operators).toHaveLength(5);
+  });
+
+  it('conditions can compare a user property against any value type', () => {
+    const stringCondition: Condition = { property: 'user.traits.plan', operator: 'equals', value: 'free' };
+    const numberCondition: Condition = { property: 'user.traits.seats', operator: 'greater_than', value: 10 };
+    const boolCondition: Condition = { property: 'user.traits.betaUser', operator: 'equals', value: true };
+
+    expect(stringCondition.value).toBe('free');
+    expect(numberCondition.value).toBe(10);
+    expect(boolCondition.value).toBe(true);
+  });
+});

package/src/__tests__/day3.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Day 3 Tests — SDK Initialisation
+ *
+ * Tests for: logger, config validator, OnboardMe.init() behaviour.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+describe('Day 3 — logger', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('suppresses all output when debug is off', async () => {
+    const { setDebug, logger } = await import('../utils/logger.js');
+    setDebug(false);
+    logger.log('hello');
+    logger.warn('warning');
+    logger.error('oops');
+    expect(console.log).not.toHaveBeenCalled();
+    expect(console.warn).not.toHaveBeenCalled();
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('outputs when debug is on', async () => {
+    const { setDebug, logger } = await import('../utils/logger.js');
+    setDebug(true);
+    logger.log('hello');
+    expect(console.log).toHaveBeenCalledWith('[OnboardMe] hello');
+    setDebug(false); // reset
+  });
+
+  it('prefixes every message with [OnboardMe]', async () => {
+    const { setDebug, logger } = await import('../utils/logger.js');
+    setDebug(true);
+    logger.warn('something happened');
+    expect(console.warn).toHaveBeenCalledWith('[OnboardMe] something happened');
+    setDebug(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateConfig
+// ---------------------------------------------------------------------------
+
+describe('Day 3 — validateConfig', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => { vi.restoreAllMocks(); });
+
+  it('returns null if no config is passed', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    expect(validateConfig(null)).toBeNull();
+    expect(validateConfig(undefined)).toBeNull();
+  });
+
+  it('returns null if productId is missing', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    expect(validateConfig({ flows: [] })).toBeNull();
+  });
+
+  it('returns null if productId is not a string', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    expect(validateConfig({ productId: 123, flows: [] })).toBeNull();
+  });
+
+  it('returns a normalised config with defaults when valid', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    const result = validateConfig({ productId: 'my-app', flows: [] });
+    expect(result).not.toBeNull();
+    expect(result?.productId).toBe('my-app');
+    expect(result?.flows).toEqual([]);
+    expect(result?.debug).toBe(false);
+  });
+
+  it('defaults flows to [] if omitted', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    const result = validateConfig({ productId: 'my-app' });
+    expect(result?.flows).toEqual([]);
+  });
+
+  it('defaults debug to false if omitted', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    const result = validateConfig({ productId: 'my-app', flows: [] });
+    expect(result?.debug).toBe(false);
+  });
+
+  it('preserves debug: true when passed', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    const result = validateConfig({ productId: 'my-app', flows: [], debug: true });
+    expect(result?.debug).toBe(true);
+  });
+
+  it('resets flows to [] and warns if flows is not an array', async () => {
+    const { validateConfig } = await import('../core/config.js');
+    const result = validateConfig({ productId: 'my-app', flows: 'bad' });
+    expect(result?.flows).toEqual([]);
+  });
+});

package/src/__tests__/day4.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Day 4 Tests — First-Time User Detection + Anonymous ID
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { detectUser } from '../detection/user-detection.js';
+import { getAnonymousId } from '../utils/fingerprint.js';
+import type { OnboardMeConfig } from '@onboardme/types';
+
+const baseConfig: OnboardMeConfig = {
+  productId: 'test-app',
+  flows: [],
+};
+
+// Clear localStorage before each test so tests are independent
+beforeEach(() => {
+  localStorage.clear();
+});
+
+// ---------------------------------------------------------------------------
+// detectUser
+// ---------------------------------------------------------------------------
+
+describe('Day 4 — detectUser: Layer 1 (localStorage flag)', () => {
+  it('returns isNew: true with reason first_visit when no flag exists', () => {
+    const result = detectUser(baseConfig);
+    expect(result.isNew).toBe(true);
+    expect(result.reason).toBe('first_visit');
+  });
+
+  it('sets the seen flag in localStorage on first visit', () => {
+    detectUser(baseConfig);
+    expect(localStorage.getItem('onboardme_seen_test-app')).toBe('1');
+  });
+
+  it('returns isNew: false when the seen flag already exists', () => {
+    localStorage.setItem('onboardme_seen_test-app', '1');
+    const result = detectUser(baseConfig);
+    expect(result.isNew).toBe(false);
+    expect(result.reason).toBe('returning');
+  });
+});
+
+describe('Day 4 — detectUser: Layer 2 (account age)', () => {
+  it('returns isNew: true with reason new_account when account is less than 48h old', () => {
+    const config: OnboardMeConfig = {
+      ...baseConfig,
+      user: { createdAt: new Date().toISOString() },
+    };
+    const result = detectUser(config);
+    expect(result.isNew).toBe(true);
+    expect(result.reason).toBe('new_account');
+  });
+
+  it('returns isNew: false when account is older than 48 hours', () => {
+    const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString();
+    const config: OnboardMeConfig = {
+      ...baseConfig,
+      user: { createdAt: threeDaysAgo },
+    };
+    const result = detectUser(config);
+    expect(result.isNew).toBe(false);
+    expect(result.reason).toBe('returning');
+  });
+});
+
+describe('Day 4 — detectUser: productId isolation', () => {
+  it('seen flags are independent per productId', () => {
+    const configA: OnboardMeConfig = { ...baseConfig, productId: 'app-a' };
+    const configB: OnboardMeConfig = { ...baseConfig, productId: 'app-b' };
+
+    // Mark app-a as seen
+    detectUser(configA);
+    localStorage.setItem('onboardme_seen_app-a', '1');
+
+    // app-b should still be new
+    const resultB = detectUser(configB);
+    expect(resultB.isNew).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAnonymousId
+// ---------------------------------------------------------------------------
+
+describe('Day 4 — getAnonymousId', () => {
+  it('returns a non-empty string', () => {
+    const id = getAnonymousId('test-app');
+    expect(typeof id).toBe('string');
+    expect(id.length).toBeGreaterThan(0);
+  });
+
+  it('returns the same ID on repeated calls (stable across page loads)', () => {
+    const id1 = getAnonymousId('test-app');
+    const id2 = getAnonymousId('test-app');
+    expect(id1).toBe(id2);
+  });
+
+  it('stores the ID in localStorage', () => {
+    const id = getAnonymousId('test-app');
+    expect(localStorage.getItem('onboardme_anon_test-app')).toBe(id);
+  });
+
+  it('returns different IDs for different productIds', () => {
+    const idA = getAnonymousId('app-a');
+    const idB = getAnonymousId('app-b');
+    expect(idA).not.toBe(idB);
+  });
+
+  it('generates a valid UUID format', () => {
+    const id = getAnonymousId('test-app');
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    expect(id).toMatch(uuidRegex);
+  });
+});