@lessonkit/core 1.3.1 → 1.4.0

package/dist/chunk-PEWFPVQ6.js

@@ -0,0 +1,628 @@
+// src/ids.ts
+function createSessionId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+// src/time.ts
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/internal/env.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnDev(message, err) {
+  if (!isDevEnvironment()) return;
+  console.warn(message, err instanceof Error ? err.message : err);
+}
+
+// src/telemetry/eventRegistry.ts
+function resolveLessonId(opts, eventName) {
+  const lessonId = opts.lessonId ?? opts.data?.lessonId;
+  if (!lessonId) throw new Error(`${eventName} requires lessonId`);
+  return lessonId;
+}
+function withLessonScopedData(name, base, lessonId, data) {
+  return { name, ...base, lessonId, data: { ...data, lessonId } };
+}
+var TELEMETRY_EVENT_REGISTRY = {
+  course_started: {
+    build: (_opts, base) => ({ name: "course_started", ...base })
+  },
+  course_completed: {
+    build: (_opts, base) => ({ name: "course_completed", ...base })
+  },
+  lesson_started: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_started") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, "lesson_started");
+      return withLessonScopedData("lesson_started", base, lessonId, opts.data);
+    }
+  },
+  lesson_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_completed") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  lesson_time_on_task: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_time_on_task") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  quiz_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_answered") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
+      return {
+        name: "quiz_answered",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  quiz_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
+      return {
+        name: "quiz_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  assessment_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_answered") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
+      return {
+        name: "assessment_answered",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  assessment_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
+      return {
+        name: "assessment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  interaction: {
+    build: (opts, base) => {
+      if (opts.name !== "interaction") throw new Error("unexpected event");
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  book_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "book_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("book_page_viewed requires active lessonId");
+      return {
+        name: "book_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  slide_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "slide_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("slide_viewed requires active lessonId");
+      return {
+        name: "slide_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  compound_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "compound_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("compound_page_viewed requires active lessonId");
+      return {
+        name: "compound_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  hotspot_opened: {
+    build: (opts, base) => {
+      if (opts.name !== "hotspot_opened") throw new Error("unexpected event");
+      return {
+        name: "hotspot_opened",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  accordion_section_toggled: {
+    build: (opts, base) => {
+      if (opts.name !== "accordion_section_toggled") throw new Error("unexpected event");
+      return {
+        name: "accordion_section_toggled",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  flashcard_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "flashcard_flipped") throw new Error("unexpected event");
+      return {
+        name: "flashcard_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  image_slider_changed: {
+    build: (opts, base) => {
+      if (opts.name !== "image_slider_changed") throw new Error("unexpected event");
+      return {
+        name: "image_slider_changed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  video_cue_reached: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_cue_reached") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_cue_reached requires active lessonId");
+      return {
+        name: "video_cue_reached",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  video_segment_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_segment_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_segment_completed requires active lessonId");
+      return {
+        name: "video_segment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  memory_card_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "memory_card_flipped") throw new Error("unexpected event");
+      return {
+        name: "memory_card_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  information_wall_search: {
+    build: (opts, base) => {
+      if (opts.name !== "information_wall_search") throw new Error("unexpected event");
+      return {
+        name: "information_wall_search",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  parallax_slide_viewed: {
+    build: (opts, base) => {
+      if (opts.name !== "parallax_slide_viewed") throw new Error("unexpected event");
+      return {
+        name: "parallax_slide_viewed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  questionnaire_submitted: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "questionnaire_submitted") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("questionnaire_submitted requires active lessonId");
+      return {
+        name: "questionnaire_submitted",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  }
+};
+function buildTelemetryEventFromRegistry(opts) {
+  const entry = TELEMETRY_EVENT_REGISTRY[opts.name];
+  if (!entry) {
+    throw new Error("Unexpected value");
+  }
+  const base = {
+    timestamp: opts.timestamp ?? nowIso(),
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  };
+  return entry.build(opts, base);
+}
+function getTelemetryEventRegistryEntry(name) {
+  return TELEMETRY_EVENT_REGISTRY[name];
+}
+
+// src/telemetryBuilder.ts
+var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
+function resetTelemetryBuilderWarningsForTests() {
+  warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
+}
+function buildTelemetryEvent(opts) {
+  return buildTelemetryEventFromRegistry(opts);
+}
+function tryBuildTelemetryEvent(opts) {
+  const entry = getTelemetryEventRegistryEntry(opts.name);
+  if (entry.requiresLessonId && !opts.lessonId && entry.tryBuildMissingLessonWarning) {
+    if (isDevEnvironment()) {
+      if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
+        warnedMissingQuizLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+        );
+      }
+      if (entry.tryBuildMissingLessonWarning === "assessment" && !warnedMissingAssessmentLesson) {
+        warnedMissingAssessmentLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
+        );
+      }
+    }
+    return null;
+  }
+  return buildTelemetryEvent(opts);
+}
+
+// src/ports.ts
+function createDefaultClock() {
+  return {
+    nowMs: () => Date.now(),
+    nowIso: () => (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createNoopStorage() {
+  return {
+    getItem: () => null,
+    setItem: () => true
+  };
+}
+function createMemoryBackedSessionStorage(session) {
+  const memory = /* @__PURE__ */ new Map();
+  let warnedPersistFailure = false;
+  const warnPersistFailure = () => {
+    if (warnedPersistFailure) return;
+    warnedPersistFailure = true;
+    const g = globalThis;
+    if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "development") {
+      console.warn(
+        "[lessonkit] sessionStorage is unavailable or failed; using in-memory session dedupe for this tab (may reset on full reload)."
+      );
+    }
+  };
+  return {
+    getItem: (key) => {
+      if (memory.has(key)) return memory.get(key);
+      try {
+        const value = session.getItem(key);
+        if (value !== null) memory.set(key, value);
+        return value;
+      } catch {
+        return memory.get(key) ?? null;
+      }
+    },
+    setItem: (key, value) => {
+      memory.set(key, value);
+      try {
+        session.setItem(key, value);
+        return true;
+      } catch {
+        warnPersistFailure();
+        return false;
+      }
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+      try {
+        session.removeItem(key);
+      } catch {
+        warnPersistFailure();
+      }
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
+  };
+}
+function resetStoragePortForTests(storage) {
+  storage.resetForTests?.();
+}
+function createInMemorySessionStoragePort() {
+  const memory = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+      return true;
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
+  };
+}
+function resolveBrowserSessionStorage() {
+  try {
+    if (typeof sessionStorage === "undefined" || sessionStorage == null) {
+      return null;
+    }
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function createSessionStoragePort() {
+  const session = resolveBrowserSessionStorage();
+  if (!session) {
+    return createInMemorySessionStoragePort();
+  }
+  return createMemoryBackedSessionStorage(session);
+}
+function createGlobalTimer() {
+  return {
+    setInterval: (fn, ms) => globalThis.setInterval(fn, ms),
+    clearInterval: (id) => globalThis.clearInterval(id)
+  };
+}
+
+// src/session.ts
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+var sharedVolatileSessionId = null;
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function getTabSessionId(storage) {
+  return storage.getItem(SESSION_STORAGE_KEY);
+}
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+var COURSE_STARTED_TRACKING_PREFIX = "lessonkit:course_started_tracking:";
+var COURSE_STARTED_PIPELINE_PREFIX = "lessonkit:course_started_pipeline:";
+function resolveSessionId(storage, provided) {
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
+  if (existing) return existing;
+  const volatile = volatileSessionIds.get(storage);
+  if (volatile) return volatile;
+  const id = createSessionId();
+  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
+  if (!persisted) {
+    if (!sharedVolatileSessionId) {
+      sharedVolatileSessionId = id;
+    }
+    volatileSessionIds.set(storage, sharedVolatileSessionId);
+    if (isDevEnvironment2()) {
+      console.warn(
+        "[lessonkit] session id could not be persisted; reusing in-memory id for this tab."
+      );
+    }
+    return sharedVolatileSessionId;
+  }
+  return id;
+}
+function courseStartedStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
+}
+function courseStartedTrackingStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionId}:${courseId ?? ""}`;
+}
+function courseStartedPipelineStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionId}:${courseId ?? ""}`;
+}
+function hasCourseStarted(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStarted(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+}
+function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+}
+function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+}
+function resetSharedVolatileSessionIdForTests() {
+  sharedVolatileSessionId = null;
+}
+function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
+  if (!courseId || fromSessionId === toSessionId) return;
+  if (hasCourseStarted(storage, fromSessionId, courseId)) {
+    markCourseStarted(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedStorageKey(fromSessionId, courseId));
+  }
+  if (hasCourseStartedEmittedToTracking(storage, fromSessionId, courseId)) {
+    markCourseStartedEmittedToTracking(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedTrackingStorageKey(fromSessionId, courseId));
+  }
+  if (hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)) {
+    markCourseStartedPipelineDelivered(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedPipelineStorageKey(fromSessionId, courseId));
+  }
+}
+
+// src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Set();
+function resetCourseStartedEmitFlightForTests() {
+  courseStartedEmitFlights.clear();
+}
+function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
+  const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (alreadyEmittedToSink) {
+    return { emitted: true, marked };
+  }
+  if (courseStartedEmitFlights.has(flightKey)) {
+    return { emitted: false, marked };
+  }
+  courseStartedEmitFlights.add(flightKey);
+  try {
+    const emitted = deps.emitCourseStartedEvent(ctx);
+    if (emitted && !marked) {
+      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    }
+    return {
+      emitted,
+      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    };
+  } finally {
+    courseStartedEmitFlights.delete(flightKey);
+  }
+}
+function buildCourseStartedTelemetryEvent(ctx) {
+  return buildTelemetryEvent({
+    name: "course_started",
+    courseId: ctx.courseId,
+    sessionId: ctx.sessionId,
+    attemptId: ctx.attemptId,
+    user: ctx.user
+  });
+}
+function completeLessonWithTelemetry(opts) {
+  const result = opts.progress.completeLesson(opts.lessonId, opts.nowMs);
+  if (!result.didComplete) return false;
+  opts.emitLessonCompleted(opts.lessonId, result.durationMs);
+  return true;
+}
+function completeCourseWithTelemetry(opts) {
+  const current = opts.progress.getState();
+  if (current.activeLessonId) {
+    completeLessonWithTelemetry({
+      progress: opts.progress,
+      lessonId: current.activeLessonId,
+      nowMs: opts.nowMs,
+      emitLessonCompleted: opts.emitLessonCompleted
+    });
+  }
+  const result = opts.progress.completeCourse();
+  if (!result.didComplete) return false;
+  opts.emitCourseCompleted();
+  return true;
+}
+
+export {
+  isDevEnvironment,
+  warnDev,
+  createSessionId,
+  nowIso,
+  resetTelemetryBuilderWarningsForTests,
+  buildTelemetryEvent,
+  tryBuildTelemetryEvent,
+  createDefaultClock,
+  createNoopStorage,
+  resetStoragePortForTests,
+  createSessionStoragePort,
+  createGlobalTimer,
+  SESSION_STORAGE_KEY,
+  getTabSessionId,
+  resolveSessionId,
+  hasCourseStarted,
+  markCourseStarted,
+  hasCourseStartedEmittedToTracking,
+  markCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
+  markCourseStartedPipelineDelivered,
+  resetSharedVolatileSessionIdForTests,
+  migrateCourseStartedMark,
+  resetCourseStartedEmitFlightForTests,
+  tryEmitCourseStarted,
+  buildCourseStartedTelemetryEvent,
+  completeLessonWithTelemetry,
+  completeCourseWithTelemetry
+};