@lessonkit/core 1.4.0 → 1.6.0

package/README.md

@@ -6,12 +6,22 @@
 
 Headless types, identity helpers, telemetry pipeline, and runtime primitives shared across LessonKit.
 
+## When to install
+
+- Custom headless runtime (no React UI)
+- Telemetry plugins, batch pipelines, or custom tracking clients
+- Validating IDs, URNs, and manifest fields in your own tooling
+
+Most course authors only need `@lessonkit/react`, which re-exports common APIs.
+
 ## Install
 
 ```bash
 npm install @lessonkit/core
 ```
 
+Requires Node.js **18+** minimum.
+
 ## Usage
 
 ```typescript
@@ -21,7 +31,16 @@ import {
   createTelemetryPipeline,
   createPluginRegistry,
   buildLessonkitUrn,
+  validateId,
 } from "@lessonkit/core";
+
+const event = buildTelemetryEvent({
+  name: "quiz_answered",
+  courseId: "my-course",
+  lessonId: "lesson-1",
+  checkId: "check-1",
+  data: { correct: true, score: 1 },
+});
 ```
 
 ## Exports
@@ -33,11 +52,18 @@ import {
 | Runtime | `createLessonkitRuntime`, progress and session helpers |
 | Plugins | `createPluginRegistry`, `defineTelemetryPlugin`, `defineAssessmentPlugin` |
 
-Machine-readable: `@lessonkit/core/telemetry-catalog.v1.json`, `identity-contract.v1.json`
+Machine-readable: `@lessonkit/core/telemetry-catalog.v3.json` (current; v1–v3 retained), `identity-contract.v1.json`
+
+## Common issues
+
+| Symptom | Fix |
+| --- | --- |
+| `buildTelemetryEvent` validation error | Ensure `courseId`, `lessonId`, and event-specific IDs match [identity rules](https://lessonkit.readthedocs.io/en/latest/reference/identity.html) |
+| Plugin not firing | Register with `createPluginRegistry` and pass plugins in `LessonkitProvider` config |
 
 ## Docs
 
-[Core reference](https://lessonkit.readthedocs.io/en/latest/reference/core.html) · [Identity](https://lessonkit.readthedocs.io/en/latest/reference/identity.html) · [Telemetry](https://lessonkit.readthedocs.io/en/latest/reference/telemetry.html) · [Plugins](https://lessonkit.readthedocs.io/en/latest/reference/plugins.html)
+[Core reference](https://lessonkit.readthedocs.io/en/latest/reference/core.html) · [Identity](https://lessonkit.readthedocs.io/en/latest/reference/identity.html) · [Telemetry](https://lessonkit.readthedocs.io/en/latest/reference/telemetry.html) · [Plugins](https://lessonkit.readthedocs.io/en/latest/reference/plugins.html) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
 
 ## License
 

package/dist/{chunk-PEWFPVQ6.js → chunk-NGCHHJSM.js}

@@ -1,8 +1,78 @@
+// src/identityTypes.ts
+var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+var ID_MAX_LENGTH = 64;
+
+// src/validateId.ts
+function validateId(input, path = "id") {
+  if (typeof input !== "string") {
+    return { ok: false, issues: [{ path, message: "id must be a string" }] };
+  }
+  const id = input.trim();
+  if (!id.length) {
+    return { ok: false, issues: [{ path, message: "id must not be empty" }] };
+  }
+  if (id.length > ID_MAX_LENGTH) {
+    return {
+      ok: false,
+      issues: [{ path, message: `id must be at most ${ID_MAX_LENGTH} characters` }]
+    };
+  }
+  if (!ID_PATTERN.test(id)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path,
+          message: "id must start with a letter and contain only letters, digits, underscores, and hyphens"
+        }
+      ]
+    };
+  }
+  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) {
+    throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+  }
+  return result.id;
+}
+
 // src/ids.ts
+function randomSessionIdFallback() {
+  const g = globalThis;
+  if (g.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `s-${hex}`;
+  }
+  throw new Error(
+    "[lessonkit] createSessionId requires crypto.randomUUID or crypto.getRandomValues"
+  );
+}
 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)}`;
+  if (g.crypto?.randomUUID) {
+    return `s-${g.crypto.randomUUID().replace(/-/g, "")}`;
+  }
+  return randomSessionIdFallback();
 }
 
 // src/time.ts
@@ -291,6 +361,118 @@ var TELEMETRY_EVENT_REGISTRY = {
         data: opts.data
       };
     }
+  },
+  branch_node_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_node_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_node_viewed requires active lessonId");
+      return {
+        name: "branch_node_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  branch_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_selected requires active lessonId");
+      return {
+        name: "branch_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  image_juxtaposition_changed: {
+    build: (opts, base) => ({
+      name: "image_juxtaposition_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  timeline_event_viewed: {
+    build: (opts, base) => ({
+      name: "timeline_event_viewed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  image_sequence_changed: {
+    build: (opts, base) => ({
+      name: "image_sequence_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_started: {
+    build: (opts, base) => ({
+      name: "audio_recording_started",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_completed: {
+    build: (opts, base) => ({
+      name: "audio_recording_completed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  qr_content_revealed: {
+    build: (opts, base) => ({
+      name: "qr_content_revealed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  advent_door_opened: {
+    build: (opts, base) => ({
+      name: "advent_door_opened",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  map_stage_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_stage_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_stage_viewed requires active lessonId");
+      return {
+        name: "map_stage_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  map_exit_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_exit_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_exit_selected requires active lessonId");
+      return {
+        name: "map_exit_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
   }
 };
 function buildTelemetryEventFromRegistry(opts) {
@@ -323,8 +505,8 @@ function buildTelemetryEvent(opts) {
 }
 function tryBuildTelemetryEvent(opts) {
   const entry = getTelemetryEventRegistryEntry(opts.name);
-  if (entry.requiresLessonId && !opts.lessonId && entry.tryBuildMissingLessonWarning) {
-    if (isDevEnvironment()) {
+  if (entry.requiresLessonId && !opts.lessonId) {
+    if (isDevEnvironment() && entry.tryBuildMissingLessonWarning) {
       if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
         warnedMissingQuizLesson = true;
         console.warn(
@@ -351,14 +533,44 @@ function createDefaultClock() {
   };
 }
 function createNoopStorage() {
+  const memory = /* @__PURE__ */ new Map();
   return {
-    getItem: () => null,
-    setItem: () => true
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+      return true;
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
   };
 }
 function createMemoryBackedSessionStorage(session) {
   const memory = /* @__PURE__ */ new Map();
+  const tombstones = /* @__PURE__ */ new Set();
   let warnedPersistFailure = false;
+  const syncFromStorageEvent = (key, newValue) => {
+    if (key === null) {
+      memory.clear();
+      tombstones.clear();
+      return;
+    }
+    tombstones.delete(key);
+    if (newValue === null) {
+      memory.delete(key);
+    } else {
+      memory.set(key, newValue);
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("storage", (event) => {
+      if (event.storageArea !== sessionStorage) return;
+      syncFromStorageEvent(event.key, event.newValue);
+    });
+  }
   const warnPersistFailure = () => {
     if (warnedPersistFailure) return;
     warnedPersistFailure = true;
@@ -369,24 +581,31 @@ function createMemoryBackedSessionStorage(session) {
       );
     }
   };
+  const bypassCacheForKey = (key) => key === "lessonkit:sessionId" || key.startsWith("lessonkit:course_started");
   return {
     getItem: (key) => {
-      if (memory.has(key)) return memory.get(key);
+      if (tombstones.has(key)) return null;
+      if (!bypassCacheForKey(key) && memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
         if (value !== null) memory.set(key, value);
+        else if (bypassCacheForKey(key)) memory.delete(key);
         return value;
       } catch {
         return memory.get(key) ?? null;
       }
     },
     setItem: (key, value) => {
-      memory.set(key, value);
+      tombstones.delete(key);
       try {
         session.setItem(key, value);
+        memory.set(key, value);
         return true;
       } catch {
         warnPersistFailure();
+        if (!bypassCacheForKey(key)) {
+          memory.set(key, value);
+        }
         return false;
       }
     },
@@ -394,12 +613,15 @@ function createMemoryBackedSessionStorage(session) {
       memory.delete(key);
       try {
         session.removeItem(key);
+        tombstones.delete(key);
       } catch {
         warnPersistFailure();
+        tombstones.add(key);
       }
     },
     resetForTests: () => {
       memory.clear();
+      tombstones.clear();
     }
   };
 }
@@ -449,7 +671,6 @@ function createGlobalTimer() {
 // 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";
@@ -460,39 +681,62 @@ function getTabSessionId(storage) {
 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:";
+var COURSE_STARTED_XAPI_PREFIX = "lessonkit:course_started_xapi:";
+function sessionKeySegment(sessionId) {
+  const validated = validateId(sessionId);
+  return validated.ok ? validated.id : encodeURIComponent(sessionId);
+}
 function resolveSessionId(storage, provided) {
   if (provided !== void 0) {
     const trimmed = provided.trim();
-    if (trimmed.length > 0) return trimmed;
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+    }
   }
   const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
+  if (existing) {
+    const trimmedExisting = existing.trim();
+    const validatedExisting = validateId(trimmedExisting);
+    if (validatedExisting.ok) return validatedExisting.id;
+    storage.removeItem?.(SESSION_STORAGE_KEY);
+    if (isDevEnvironment2()) {
+      console.warn(
+        `[lessonkit] Invalid stored sessionId "${existing}"; generating a new id.`
+      );
+    }
+  }
   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);
+    volatileSessionIds.set(storage, id);
     if (isDevEnvironment2()) {
       console.warn(
-        "[lessonkit] session id could not be persisted; reusing in-memory id for this tab."
+        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
       );
     }
-    return sharedVolatileSessionId;
+    return id;
   }
   return id;
 }
 function courseStartedStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function courseStartedTrackingStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function courseStartedPipelineStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function courseStartedXapiStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_XAPI_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
@@ -518,27 +762,52 @@ function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
   return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
+function hasCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+}
 function resetSharedVolatileSessionIdForTests() {
-  sharedVolatileSessionId = null;
+}
+function migrateStorageMark(storage, fromKey, toKey, hasMark) {
+  if (!hasMark) return;
+  if (storage.setItem(toKey, "1")) {
+    storage.removeItem?.(fromKey);
+  }
 }
 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));
-  }
+  migrateStorageMark(
+    storage,
+    courseStartedStorageKey(fromSessionId, courseId),
+    courseStartedStorageKey(toSessionId, courseId),
+    hasCourseStarted(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedTrackingStorageKey(fromSessionId, courseId),
+    courseStartedTrackingStorageKey(toSessionId, courseId),
+    hasCourseStartedEmittedToTracking(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedPipelineStorageKey(fromSessionId, courseId),
+    courseStartedPipelineStorageKey(toSessionId, courseId),
+    hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedXapiStorageKey(fromSessionId, courseId),
+    courseStartedXapiStorageKey(toSessionId, courseId),
+    hasCourseStartedXapiSent(storage, fromSessionId, courseId)
+  );
 }
 
 // src/runtime/courseLifecycle.ts
-var courseStartedEmitFlights = /* @__PURE__ */ new Set();
+var courseStartedEmitFlights = /* @__PURE__ */ new Map();
 function resetCourseStartedEmitFlightForTests() {
   courseStartedEmitFlights.clear();
 }
@@ -546,24 +815,43 @@ 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 };
+    const markPersisted = marked ? true : markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    return Promise.resolve({
+      emitted: true,
+      marked: markPersisted
+    });
   }
-  if (courseStartedEmitFlights.has(flightKey)) {
-    return { emitted: false, marked };
+  if (marked && hasCourseStartedEmittedToTracking(ctx.storage, ctx.sessionId, ctx.courseId)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: true
+    });
   }
-  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);
+  const existing = courseStartedEmitFlights.get(flightKey);
+  if (existing) {
+    return existing;
   }
+  const flight = Promise.resolve().then(() => {
+    try {
+      const emitted = deps.emitCourseStartedEvent(ctx);
+      const markPersisted = emitted && !marked ? markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId) : marked;
+      return {
+        emitted,
+        marked: markPersisted
+      };
+    } catch {
+      return {
+        emitted: false,
+        marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+      };
+    } finally {
+      if (courseStartedEmitFlights.get(flightKey) === flight) {
+        courseStartedEmitFlights.delete(flightKey);
+      }
+    }
+  });
+  courseStartedEmitFlights.set(flightKey, flight);
+  return flight;
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({
@@ -591,12 +879,29 @@ function completeCourseWithTelemetry(opts) {
     });
   }
   const result = opts.progress.completeCourse();
-  if (!result.didComplete) return false;
+  if (!result.didComplete) {
+    const after = opts.progress.getState();
+    if (after.activeLessonId) {
+      const lessonResult = opts.progress.completeLesson(after.activeLessonId, opts.nowMs);
+      if (lessonResult.didComplete) {
+        opts.emitLessonCompleted(after.activeLessonId, lessonResult.durationMs);
+      }
+    }
+    return false;
+  }
   opts.emitCourseCompleted();
   return true;
 }
 
 export {
+  ID_PATTERN,
+  ID_MAX_LENGTH,
+  validateId,
+  parseCourseId,
+  parseLessonId,
+  parseCheckId,
+  parseBlockId,
+  assertValidId,
   isDevEnvironment,
   warnDev,
   createSessionId,
@@ -618,6 +923,8 @@ export {
   markCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
   markCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
+  markCourseStartedXapiSent,
   resetSharedVolatileSessionIdForTests,
   migrateCourseStartedMark,
   resetCourseStartedEmitFlightForTests,