@lessonkit/core 0.9.3 → 1.0.1

package/dist/index.js

@@ -2,6 +2,11 @@
 var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
 var ID_MAX_LENGTH = 64;
 
+// src/assertNever.ts
+function assertNever(value, message = "Unexpected value") {
+  throw new Error(`${message}: ${String(value)}`);
+}
+
 // src/validateId.ts
 function validateId(input, path = "id") {
   if (typeof input !== "string") {
@@ -30,6 +35,22 @@ function validateId(input, path = "id") {
   }
   return { ok: true, id };
 }
+function parseCourseId(input) {
+  const result = validateId(input, "courseId");
+  return result.ok ? result.id : null;
+}
+function parseLessonId(input) {
+  const result = validateId(input, "lessonId");
+  return result.ok ? result.id : null;
+}
+function parseCheckId(input) {
+  const result = validateId(input, "checkId");
+  return result.ok ? result.id : null;
+}
+function parseBlockId(input) {
+  const result = validateId(input, "blockId");
+  return result.ok ? result.id : null;
+}
 function assertValidId(input, path = "id") {
   const result = validateId(input, path);
   if (!result.ok) {
@@ -154,18 +175,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;
@@ -224,6 +275,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();
     },
@@ -255,16 +315,476 @@ 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 resolveLessonId(opts, eventName) {
+  const lessonId = opts.lessonId ?? opts.data?.lessonId;
+  if (!lessonId) throw new Error(`${eventName} requires lessonId`);
+  return lessonId;
+}
+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 lessonId = resolveLessonId(opts, "lesson_started");
+      return {
+        name: "lesson_started",
+        ...base,
+        lessonId,
+        data: { ...opts.data, lessonId }
+      };
+    }
+    case "lesson_completed":
+    case "lesson_time_on_task": {
+      const lessonId = resolveLessonId(opts, opts.name);
+      return {
+        name: opts.name,
+        ...base,
+        lessonId,
+        data: { ...opts.data, lessonId }
+      };
+    }
+    case "quiz_answered": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
+      return { name: "quiz_answered", ...base, lessonId, data: opts.data };
+    }
+    case "quiz_completed": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
+      return { name: "quiz_completed", ...base, lessonId, data: opts.data };
+    }
+    case "interaction":
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    default:
+      return assertNever(opts);
+  }
+}
+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:";
+var COURSE_STARTED_PIPELINE_PREFIX = "lessonkit:course_started_pipeline:";
+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 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;
+  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 hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
+  if (!courseId) return;
+  storage.setItem(courseStartedPipelineStorageKey(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));
+  }
+  if (hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)) {
+    markCourseStartedPipelineDelivered(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedPipelineStorageKey(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);
@@ -344,20 +864,64 @@ function createPluginHost(plugins = []) {
     scoreAssessment
   };
 }
+
+// src/plugins/define.ts
+function defineTelemetryPlugin(plugin) {
+  return plugin;
+}
+function defineAssessmentPlugin(plugin) {
+  return plugin;
+}
+function defineLifecyclePlugin(plugin) {
+  return plugin;
+}
 export {
   ID_MAX_LENGTH,
   ID_PATTERN,
+  SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  assertNever,
   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,
+  hasCourseStartedPipelineDelivered,
+  markCourseStarted,
+  markCourseStartedEmittedToTracking,
+  markCourseStartedPipelineDelivered,
+  migrateCourseStartedMark,
   nowIso,
+  parseBlockId,
+  parseCheckId,
+  parseCourseId,
+  parseLessonId,
+  resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests,
+  resolveSessionId,
   slugifyId,
   telemetryCatalogVersion,
+  tryBuildTelemetryEvent,
+  tryEmitCourseStarted,
   validateId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",