@lessonkit/core 0.9.2 → 1.0.0

package/dist/index.cjs

@@ -22,18 +22,44 @@ var index_exports = {};
 __export(index_exports, {
   ID_MAX_LENGTH: () => ID_MAX_LENGTH,
   ID_PATTERN: () => ID_PATTERN,
+  SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
   assertValidId: () => assertValidId,
+  buildCourseStartedTelemetryEvent: () => buildCourseStartedTelemetryEvent,
   buildLessonkitUrn: () => buildLessonkitUrn,
   buildTelemetryCatalog: () => buildTelemetryCatalog,
-  createPluginHost: () => createPluginHost,
+  buildTelemetryEvent: () => buildTelemetryEvent,
+  completeCourseWithTelemetry: () => completeCourseWithTelemetry,
+  completeLessonWithTelemetry: () => completeLessonWithTelemetry,
+  createDefaultClock: () => createDefaultClock,
+  createGlobalTimer: () => createGlobalTimer,
+  createLessonkitRuntime: () => createLessonkitRuntime,
+  createNoopStorage: () => createNoopStorage,
+  createPluginRegistry: () => createPluginRegistry,
+  createProgressController: () => createProgressController,
   createSessionId: () => createSessionId,
+  createSessionStoragePort: () => createSessionStoragePort,
+  createTelemetryPipeline: () => createTelemetryPipeline,
   createTrackingClient: () => createTrackingClient,
-  defineLessonkitPlugin: () => defineLessonkitPlugin,
+  createTrackingPipelineSink: () => createTrackingPipelineSink,
+  defineAssessmentPlugin: () => defineAssessmentPlugin,
+  defineLifecyclePlugin: () => defineLifecyclePlugin,
+  defineTelemetryPlugin: () => defineTelemetryPlugin,
   deriveId: () => deriveId,
+  getTabSessionId: () => getTabSessionId,
+  hasCourseStarted: () => hasCourseStarted,
+  hasCourseStartedEmittedToTracking: () => hasCourseStartedEmittedToTracking,
+  markCourseStarted: () => markCourseStarted,
+  markCourseStartedEmittedToTracking: () => markCourseStartedEmittedToTracking,
+  migrateCourseStartedMark: () => migrateCourseStartedMark,
   nowIso: () => nowIso,
+  resetStoragePortForTests: () => resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
+  resolveSessionId: () => resolveSessionId,
   slugifyId: () => slugifyId,
   telemetryCatalogVersion: () => telemetryCatalogVersion,
+  tryBuildTelemetryEvent: () => tryBuildTelemetryEvent,
+  tryEmitCourseStarted: () => tryEmitCourseStarted,
   validateId: () => validateId
 });
 module.exports = __toCommonJS(index_exports);
@@ -194,18 +220,48 @@ function buildTelemetryCatalog() {
 }
 
 // src/trackingClient.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function invokeTrackingSink(sink, event) {
+  let result;
+  try {
+    result = sink(event);
+  } catch (err) {
+    if (isDevEnvironment()) {
+      console.warn(
+        "[lessonkit] tracking sink failed:",
+        err instanceof Error ? err.message : err
+      );
+    }
+    throw err;
+  }
+  if (result != null && typeof result.catch === "function") {
+    void result.catch((err) => {
+      if (isDevEnvironment()) {
+        console.warn(
+          "[lessonkit] tracking sink failed:",
+          err instanceof Error ? err.message : err
+        );
+      }
+    });
+  }
+}
 function createTrackingClient(opts) {
   const sink = opts?.sink;
   const batchSink = opts?.batchSink;
   const batchEnabled = opts?.batch?.enabled ?? Boolean(batchSink);
   const flushIntervalMs = opts?.batch?.flushIntervalMs ?? 5e3;
   const maxBatchSize = opts?.batch?.maxBatchSize ?? 25;
+  const maxBufferSize = 1e3;
+  let warnedBufferCap = false;
   if (!batchEnabled) {
     let disposed2 = false;
     return {
       track: (event) => {
         if (disposed2) return;
-        void sink?.(event);
+        if (sink) invokeTrackingSink(sink, event);
       },
       dispose: () => {
         disposed2 = true;
@@ -264,6 +320,15 @@ function createTrackingClient(opts) {
   return {
     track: (event) => {
       if (disposed || disposing) return;
+      if (buffer.length >= maxBufferSize) {
+        buffer.shift();
+        if (!warnedBufferCap && typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+          warnedBufferCap = true;
+          console.warn(
+            `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; oldest events are dropped while the sink is unavailable.`
+          );
+        }
+      }
       buffer.push(event);
       if (buffer.length >= maxBatchSize) void flush();
     },
@@ -295,16 +360,461 @@ function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 
-// src/plugins.ts
-function defineLessonkitPlugin(plugin) {
-  return plugin;
+// src/telemetryBuilder.ts
+var warnedMissingQuizLesson = false;
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function resetTelemetryBuilderWarningsForTests() {
+  warnedMissingQuizLesson = false;
+}
+function buildTelemetryEvent(opts) {
+  const base = {
+    timestamp: opts.timestamp ?? nowIso(),
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  };
+  switch (opts.name) {
+    case "course_started":
+      return { name: "course_started", ...base };
+    case "course_completed":
+      return { name: "course_completed", ...base };
+    case "lesson_started": {
+      const data = opts.data;
+      const lessonId = opts.lessonId ?? data?.lessonId;
+      if (!lessonId) throw new Error("lesson_started requires lessonId");
+      return {
+        name: "lesson_started",
+        ...base,
+        lessonId,
+        data: { ...data, lessonId }
+      };
+    }
+    case "lesson_completed":
+    case "lesson_time_on_task": {
+      const data = opts.data;
+      const lessonId = opts.lessonId ?? data?.lessonId;
+      if (!lessonId) throw new Error(`${opts.name} requires lessonId`);
+      return {
+        name: opts.name,
+        ...base,
+        lessonId,
+        data: { ...data, lessonId }
+      };
+    }
+    case "quiz_answered": {
+      const data = opts.data;
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
+      return { name: "quiz_answered", ...base, lessonId, data };
+    }
+    case "quiz_completed": {
+      const data = opts.data;
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
+      return { name: "quiz_completed", ...base, lessonId, data };
+    }
+    case "interaction":
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    default:
+      return { name: opts.name, ...base };
+  }
+}
+function tryBuildTelemetryEvent(opts) {
+  const isQuiz = opts.name === "quiz_answered" || opts.name === "quiz_completed";
+  if (isQuiz && !opts.lessonId) {
+    if (isDevEnvironment2() && !warnedMissingQuizLesson) {
+      warnedMissingQuizLesson = true;
+      console.warn(
+        `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+      );
+    }
+    return null;
+  }
+  return buildTelemetryEvent(opts);
+}
+
+// src/telemetryPipeline.ts
+function isDevEnvironment3() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnSinkFailure(sinkId, err) {
+  if (isDevEnvironment3()) {
+    console.warn(
+      `[lessonkit] telemetry sink "${sinkId}" failed:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+function invokeSink(sink, event, emitCtx) {
+  let result;
+  try {
+    result = sink.emit(event, emitCtx);
+  } catch (err) {
+    warnSinkFailure(sink.id, err);
+    return;
+  }
+  if (result != null && typeof result.catch === "function") {
+    void result.catch((err) => warnSinkFailure(sink.id, err));
+  }
+}
+function createTelemetryPipeline(sinks) {
+  const list = [...sinks];
+  return {
+    sinks: list,
+    emit(event, ctx) {
+      const emitCtx = ctx ?? {
+        courseId: event.courseId,
+        sessionId: event.sessionId,
+        attemptId: event.attemptId
+      };
+      for (const sink of list) {
+        invokeSink(sink, event, emitCtx);
+      }
+    }
+  };
+}
+function createTrackingPipelineSink(id, track) {
+  return {
+    id,
+    emit(event) {
+      track(event);
+    }
+  };
+}
+
+// src/ports.ts
+function createDefaultClock() {
+  return {
+    nowMs: () => Date.now(),
+    nowIso: () => (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createNoopStorage() {
+  return {
+    getItem: () => null,
+    setItem: () => {
+    }
+  };
+}
+function createMemoryBackedSessionStorage(session) {
+  const memory = /* @__PURE__ */ new Map();
+  let warnedPersistFailure = false;
+  const warnPersistFailure = () => {
+    if (warnedPersistFailure) return;
+    warnedPersistFailure = true;
+    if (typeof process !== "undefined" && 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);
+      } catch {
+        warnPersistFailure();
+      }
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+      try {
+        session.removeItem(key);
+      } catch {
+        warnPersistFailure();
+      }
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
+  };
+}
+function resetStoragePortForTests(storage) {
+  storage.resetForTests?.();
+}
+function createSessionStoragePort() {
+  if (typeof sessionStorage === "undefined") {
+    const memory = /* @__PURE__ */ new Map();
+    return {
+      getItem: (key) => memory.get(key) ?? null,
+      setItem: (key, value) => {
+        memory.set(key, value);
+      },
+      removeItem: (key) => {
+        memory.delete(key);
+      },
+      resetForTests: () => {
+        memory.clear();
+      }
+    };
+  }
+  return createMemoryBackedSessionStorage(sessionStorage);
+}
+function createGlobalTimer() {
+  return {
+    setInterval: (fn, ms) => globalThis.setInterval(fn, ms),
+    clearInterval: (id) => globalThis.clearInterval(id)
+  };
+}
+
+// src/progress.ts
+function createProgressController() {
+  let activeLessonId;
+  let completedLessonIds = /* @__PURE__ */ new Set();
+  let courseCompleted = false;
+  const lessonStartTimes = /* @__PURE__ */ new Map();
+  return {
+    getState: () => ({
+      activeLessonId,
+      completedLessonIds: new Set(completedLessonIds),
+      courseCompleted
+    }),
+    setActiveLesson: (lessonId, startedAtMs) => {
+      const previousLessonId = activeLessonId;
+      activeLessonId = lessonId;
+      lessonStartTimes.set(lessonId, startedAtMs);
+      return { previousLessonId };
+    },
+    completeLesson: (lessonId, completedAtMs) => {
+      if (completedLessonIds.has(lessonId)) return { didComplete: false };
+      completedLessonIds = new Set(completedLessonIds).add(lessonId);
+      if (activeLessonId === lessonId) {
+        activeLessonId = void 0;
+      }
+      const startedAt = lessonStartTimes.get(lessonId);
+      lessonStartTimes.delete(lessonId);
+      const durationMs = typeof startedAt === "number" ? Math.max(0, completedAtMs - startedAt) : void 0;
+      return { durationMs, didComplete: true };
+    },
+    completeCourse: () => {
+      if (courseCompleted) return { didComplete: false };
+      courseCompleted = true;
+      return { didComplete: true };
+    }
+  };
+}
+
+// src/session.ts
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+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:";
+function resolveSessionId(storage, provided) {
+  if (provided) return provided;
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
+  if (existing) return existing;
+  const id = createSessionId();
+  storage.setItem(SESSION_STORAGE_KEY, id);
+  return id;
+}
+function courseStartedStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
 }
+function courseStartedTrackingStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_TRACKING_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;
+  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;
+  storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+}
+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));
+  }
+}
+
+// src/runtime/courseLifecycle.ts
+function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (alreadyEmittedToSink) {
+    return { emitted: true, marked };
+  }
+  if (marked) {
+    return { emitted: false, marked: true };
+  }
+  const emitted = deps.emitCourseStartedEvent(ctx);
+  if (emitted) {
+    markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  }
+  return { emitted, marked: emitted };
+}
+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;
+}
+
+// src/runtime/createLessonkitRuntime.ts
+function createLessonkitRuntime(config, ports = {}) {
+  const storage = ports.storage ?? createSessionStoragePort();
+  const clock = ports.clock ?? createDefaultClock();
+  const configSnapshot = { ...config };
+  let sessionId = resolveSessionId(storage, configSnapshot.session?.sessionId);
+  let attemptId = configSnapshot.session?.attemptId;
+  let user = configSnapshot.session?.user;
+  let courseId = configSnapshot.courseId;
+  let progress = createProgressController();
+  const getSession = () => ({ sessionId, attemptId, user });
+  const syncSessionFromConfig = (next) => {
+    sessionId = resolveSessionId(storage, next.session?.sessionId);
+    attemptId = next.session?.attemptId;
+    user = next.session?.user;
+    courseId = next.courseId;
+  };
+  syncSessionFromConfig(configSnapshot);
+  const track = (name, data, emit, lessonId) => {
+    const event = tryBuildTelemetryEvent({
+      name,
+      courseId,
+      lessonId: lessonId ?? progress.getState().activeLessonId,
+      sessionId,
+      attemptId,
+      user,
+      data
+    });
+    if (!event) return;
+    emit(event);
+  };
+  const emitLessonCompleted = (lessonId, durationMs, emitFn) => {
+    emitFn("lesson_completed", { lessonId, durationMs }, lessonId);
+    if (durationMs !== void 0) {
+      emitFn("lesson_time_on_task", { lessonId, durationMs }, lessonId);
+    }
+  };
+  return {
+    get config() {
+      return configSnapshot;
+    },
+    get progress() {
+      return progress;
+    },
+    getProgressState: () => progress.getState(),
+    getSession,
+    updateConfig(next) {
+      if (next.courseId !== void 0) configSnapshot.courseId = next.courseId;
+      if (next.runtimeVersion !== void 0) configSnapshot.runtimeVersion = next.runtimeVersion;
+      if (next.plugins !== void 0) configSnapshot.plugins = next.plugins;
+      if (next.session !== void 0) {
+        configSnapshot.session = { ...configSnapshot.session, ...next.session };
+      }
+      syncSessionFromConfig(configSnapshot);
+    },
+    setActiveLesson(lessonId, emitFn) {
+      const current = progress.getState();
+      if (current.activeLessonId === lessonId) return;
+      if (current.completedLessonIds.has(lessonId)) {
+        progress.setActiveLesson(lessonId, clock.nowMs());
+        return;
+      }
+      const previous = current.activeLessonId;
+      if (previous && previous !== lessonId) {
+        const completed = progress.completeLesson(previous, clock.nowMs());
+        if (completed.didComplete) {
+          emitLessonCompleted(previous, completed.durationMs, emitFn);
+        }
+      }
+      progress.setActiveLesson(lessonId, clock.nowMs());
+      emitFn("lesson_started", { lessonId }, lessonId);
+    },
+    completeLesson(lessonId, emitFn) {
+      const result = progress.completeLesson(lessonId, clock.nowMs());
+      if (!result.didComplete) return;
+      emitLessonCompleted(lessonId, result.durationMs, emitFn);
+    },
+    completeCourse(emitFn) {
+      const current = progress.getState();
+      if (current.activeLessonId) {
+        const lessonResult = progress.completeLesson(current.activeLessonId, clock.nowMs());
+        if (lessonResult.didComplete) {
+          emitLessonCompleted(current.activeLessonId, lessonResult.durationMs, emitFn);
+        }
+      }
+      const result = progress.completeCourse();
+      if (!result.didComplete) return;
+      emitFn("course_completed");
+    },
+    track,
+    resetForCourseChange(nextCourseId) {
+      configSnapshot.courseId = nextCourseId;
+      courseId = nextCourseId;
+      progress = createProgressController();
+    }
+  };
+}
+
+// src/plugins/registry.ts
 function warnDuplicatePlugin(id) {
   const g = globalThis;
   if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
   console.warn(`[lessonkit] plugin id "${id}" was registered more than once; using the latest definition`);
 }
-function createPluginHost(plugins = []) {
+function createPluginRegistry(plugins = []) {
   const registry = /* @__PURE__ */ new Map();
   for (const plugin of plugins) {
     if (registry.has(plugin.id)) warnDuplicatePlugin(plugin.id);
@@ -342,11 +852,26 @@ function createPluginHost(plugins = []) {
     }
     return events;
   };
-  const composeTrackingSink = (sink, ctx) => {
+  const composeTrackingSink = (sink, ctxSource) => {
+    if (!sink) return void 0;
+    const resolveCtx = () => typeof ctxSource === "function" ? ctxSource() : ctxSource;
+    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}`;
+    const layers = [];
     let composed = sink;
     for (const plugin of list) {
-      if (!plugin.wrapTrackingSink || !composed) continue;
-      composed = plugin.wrapTrackingSink(composed, ctx);
+      if (!plugin.wrapTrackingSink) continue;
+      const inner = composed;
+      const layer = { plugin, inner, wrapped: null, lastCtxKey: "" };
+      layers.push(layer);
+      composed = (event) => {
+        const ctx = resolveCtx();
+        const key = ctxKey(ctx);
+        if (!layer.wrapped || layer.lastCtxKey !== key) {
+          layer.wrapped = layer.plugin.wrapTrackingSink(layer.inner, ctx) ?? layer.inner;
+          layer.lastCtxKey = key;
+        }
+        return layer.wrapped(event);
+      };
     }
     return composed;
   };
@@ -369,21 +894,58 @@ function createPluginHost(plugins = []) {
     scoreAssessment
   };
 }
+
+// src/plugins/define.ts
+function defineTelemetryPlugin(plugin) {
+  return plugin;
+}
+function defineAssessmentPlugin(plugin) {
+  return plugin;
+}
+function defineLifecyclePlugin(plugin) {
+  return plugin;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ID_MAX_LENGTH,
   ID_PATTERN,
+  SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
   assertValidId,
+  buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
   buildTelemetryCatalog,
-  createPluginHost,
+  buildTelemetryEvent,
+  completeCourseWithTelemetry,
+  completeLessonWithTelemetry,
+  createDefaultClock,
+  createGlobalTimer,
+  createLessonkitRuntime,
+  createNoopStorage,
+  createPluginRegistry,
+  createProgressController,
   createSessionId,
+  createSessionStoragePort,
+  createTelemetryPipeline,
   createTrackingClient,
-  defineLessonkitPlugin,
+  createTrackingPipelineSink,
+  defineAssessmentPlugin,
+  defineLifecyclePlugin,
+  defineTelemetryPlugin,
   deriveId,
+  getTabSessionId,
+  hasCourseStarted,
+  hasCourseStartedEmittedToTracking,
+  markCourseStarted,
+  markCourseStartedEmittedToTracking,
+  migrateCourseStartedMark,
   nowIso,
+  resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests,
+  resolveSessionId,
   slugifyId,
   telemetryCatalogVersion,
+  tryBuildTelemetryEvent,
+  tryEmitCourseStarted,
   validateId
 });