@lessonkit/core 1.0.1 → 1.1.0

package/dist/index.cjs

@@ -24,11 +24,13 @@ __export(index_exports, {
   ID_PATTERN: () => ID_PATTERN,
   SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
+  TELEMETRY_EVENT_CATALOG_V2: () => TELEMETRY_EVENT_CATALOG_V2,
   assertNever: () => assertNever,
   assertValidId: () => assertValidId,
   buildCourseStartedTelemetryEvent: () => buildCourseStartedTelemetryEvent,
   buildLessonkitUrn: () => buildLessonkitUrn,
   buildTelemetryCatalog: () => buildTelemetryCatalog,
+  buildTelemetryCatalogV2: () => buildTelemetryCatalogV2,
   buildTelemetryEvent: () => buildTelemetryEvent,
   completeCourseWithTelemetry: () => completeCourseWithTelemetry,
   completeLessonWithTelemetry: () => completeLessonWithTelemetry,
@@ -64,6 +66,7 @@ __export(index_exports, {
   resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
   resolveSessionId: () => resolveSessionId,
   slugifyId: () => slugifyId,
+  telemetryCatalogV2Version: () => telemetryCatalogV2Version,
   telemetryCatalogVersion: () => telemetryCatalogVersion,
   tryBuildTelemetryEvent: () => tryBuildTelemetryEvent,
   tryEmitCourseStarted: () => tryEmitCourseStarted,
@@ -247,6 +250,30 @@ function buildTelemetryCatalog() {
   return TELEMETRY_EVENT_CATALOG.map((entry) => ({ ...entry }));
 }
 
+// src/telemetryCatalogV2.ts
+var telemetryCatalogV2Version = 2;
+var TELEMETRY_EVENT_CATALOG_V2 = [
+  {
+    name: "assessment_answered",
+    description: "Learner submitted an assessment interaction answer",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "question", "response", "correct"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "assessment_completed",
+    description: "Assessment interaction completed (passing criteria met)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "score", "maxScore", "passingScore"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  }
+];
+function buildTelemetryCatalogV2() {
+  return TELEMETRY_EVENT_CATALOG_V2.map((entry) => ({ ...entry }));
+}
+
 // src/trackingClient.ts
 function isDevEnvironment() {
   const g = globalThis;
@@ -279,6 +306,11 @@ function invokeTrackingSink(sink, event) {
 function createTrackingClient(opts) {
   const sink = opts?.sink;
   const batchSink = opts?.batchSink;
+  if (batchSink != null && opts?.batch?.enabled === false) {
+    throw new Error(
+      "[lessonkit] tracking.batchSink cannot be used with batch.enabled: false; omit batch.enabled or set it to true"
+    );
+  }
   const batchEnabled = opts?.batch?.enabled ?? Boolean(batchSink);
   const flushIntervalMs = opts?.batch?.flushIntervalMs ?? 5e3;
   const maxBatchSize = opts?.batch?.maxBatchSize ?? 25;
@@ -350,7 +382,7 @@ function createTrackingClient(opts) {
       if (disposed || disposing) return;
       if (buffer.length >= maxBufferSize) {
         buffer.shift();
-        if (!warnedBufferCap && typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+        if (!warnedBufferCap && isDevEnvironment()) {
           warnedBufferCap = true;
           console.warn(
             `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; oldest events are dropped while the sink is unavailable.`
@@ -390,12 +422,14 @@ function nowIso() {
 
 // src/telemetryBuilder.ts
 var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
 function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function resetTelemetryBuilderWarningsForTests() {
   warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
 }
 function resolveLessonId(opts, eventName) {
   const lessonId = opts.lessonId ?? opts.data?.lessonId;
@@ -444,6 +478,16 @@ function buildTelemetryEvent(opts) {
       if (!lessonId) throw new Error("quiz_completed requires active lessonId");
       return { name: "quiz_completed", ...base, lessonId, data: opts.data };
     }
+    case "assessment_answered": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
+      return { name: "assessment_answered", ...base, lessonId, data: opts.data };
+    }
+    case "assessment_completed": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
+      return { name: "assessment_completed", ...base, lessonId, data: opts.data };
+    }
     case "interaction":
       return {
         name: "interaction",
@@ -456,13 +500,21 @@ function buildTelemetryEvent(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`
-      );
+  const needsLesson = opts.name === "quiz_answered" || opts.name === "quiz_completed" || opts.name === "assessment_answered" || opts.name === "assessment_completed";
+  if (needsLesson && !opts.lessonId) {
+    if (isDevEnvironment2()) {
+      if (opts.name.startsWith("quiz_") && !warnedMissingQuizLesson) {
+        warnedMissingQuizLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+        );
+      }
+      if (opts.name.startsWith("assessment_") && !warnedMissingAssessmentLesson) {
+        warnedMissingAssessmentLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
+        );
+      }
     }
     return null;
   }
@@ -539,7 +591,8 @@ function createMemoryBackedSessionStorage(session) {
   const warnPersistFailure = () => {
     if (warnedPersistFailure) return;
     warnedPersistFailure = true;
-    if (typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+    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)."
       );
@@ -580,23 +633,37 @@ function createMemoryBackedSessionStorage(session) {
 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);
+    },
+    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() {
-  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();
-      }
-    };
+  const session = resolveBrowserSessionStorage();
+  if (!session) {
+    return createInMemorySessionStoragePort();
   }
-  return createMemoryBackedSessionStorage(sessionStorage);
+  return createMemoryBackedSessionStorage(session);
 }
 function createGlobalTimer() {
   return {
@@ -954,11 +1021,13 @@ function defineLifecyclePlugin(plugin) {
   ID_PATTERN,
   SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  TELEMETRY_EVENT_CATALOG_V2,
   assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
   buildTelemetryCatalog,
+  buildTelemetryCatalogV2,
   buildTelemetryEvent,
   completeCourseWithTelemetry,
   completeLessonWithTelemetry,
@@ -994,6 +1063,7 @@ function defineLifecyclePlugin(plugin) {
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,
   slugifyId,
+  telemetryCatalogV2Version,
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,

package/dist/index.d.cts

@@ -54,7 +54,41 @@ type LessonkitUrnParts = {
  */
 declare function buildLessonkitUrn(parts: LessonkitUrnParts): LessonkitUrn;
 
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
+/** H5P-aligned interaction kinds for assessment telemetry and xAPI. */
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence";
+/** Behaviour flags aligned with H5P question types. */
+type AssessmentBehaviour = {
+    enableRetry?: boolean;
+    enableSolutionsButton?: boolean;
+    autoCheck?: boolean;
+};
+/** Payload for xAPI mapping from assessment components. */
+type AssessmentXAPIData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    response?: string | string[] | boolean | Record<string, unknown>;
+    correct?: boolean;
+    score?: number;
+    maxScore?: number;
+};
+/**
+ * Imperative handle for scored blocks (H5P question-type contract analogue).
+ * Parent containers (`AssessmentSequence`, future compounds) may call these methods.
+ */
+type AssessmentHandle = {
+    getScore: () => number;
+    getMaxScore: () => number;
+    getAnswerGiven: () => boolean;
+    resetTask: () => void;
+    showSolutions: () => void;
+    getXAPIData: () => AssessmentXAPIData;
+};
+type AssessmentBaseProps = AssessmentBehaviour & {
+    checkId: CheckId;
+    passingScore?: number;
+};
+
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -87,6 +121,20 @@ type QuizCompletedData = {
     maxScore?: number;
     passingScore?: number;
 };
+type AssessmentAnsweredData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    question?: string;
+    response?: string | string[] | boolean | Record<string, unknown>;
+    correct?: boolean;
+};
+type AssessmentCompletedData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    score?: number;
+    maxScore?: number;
+    passingScore?: number;
+};
 type InteractionData = {
     kind?: string;
     blockId?: BlockId;
@@ -121,6 +169,14 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "quiz_completed";
     lessonId: LessonId;
     data: QuizCompletedData;
+}) | (TelemetryEventBase & {
+    name: "assessment_answered";
+    lessonId: LessonId;
+    data: AssessmentAnsweredData;
+}) | (TelemetryEventBase & {
+    name: "assessment_completed";
+    lessonId: LessonId;
+    data: AssessmentCompletedData;
 }) | (TelemetryEventBase & {
     name: "interaction";
     lessonId?: LessonId;
@@ -152,6 +208,18 @@ type TelemetryCatalogEntry = {
 declare const TELEMETRY_EVENT_CATALOG: TelemetryCatalogEntry[];
 declare function buildTelemetryCatalog(): TelemetryCatalogEntry[];
 
+declare const telemetryCatalogV2Version: 2;
+type TelemetryCatalogV2Entry = {
+    name: Extract<TelemetryEventName, "assessment_answered" | "assessment_completed">;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
+declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
+
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -201,6 +269,14 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "quiz_completed";
     lessonId?: LessonId;
     data: QuizCompletedData;
+}) | (BuildTelemetryEventContext & {
+    name: "assessment_answered";
+    lessonId?: LessonId;
+    data: AssessmentAnsweredData;
+}) | (BuildTelemetryEventContext & {
+    name: "assessment_completed";
+    lessonId?: LessonId;
+    data: AssessmentCompletedData;
 }) | (BuildTelemetryEventContext & {
     name: "interaction";
     lessonId?: LessonId;
@@ -429,4 +505,4 @@ declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin
 declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
 declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, 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 };
+export { type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogV2Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };

package/dist/index.d.ts

@@ -54,7 +54,41 @@ type LessonkitUrnParts = {
  */
 declare function buildLessonkitUrn(parts: LessonkitUrnParts): LessonkitUrn;
 
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
+/** H5P-aligned interaction kinds for assessment telemetry and xAPI. */
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence";
+/** Behaviour flags aligned with H5P question types. */
+type AssessmentBehaviour = {
+    enableRetry?: boolean;
+    enableSolutionsButton?: boolean;
+    autoCheck?: boolean;
+};
+/** Payload for xAPI mapping from assessment components. */
+type AssessmentXAPIData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    response?: string | string[] | boolean | Record<string, unknown>;
+    correct?: boolean;
+    score?: number;
+    maxScore?: number;
+};
+/**
+ * Imperative handle for scored blocks (H5P question-type contract analogue).
+ * Parent containers (`AssessmentSequence`, future compounds) may call these methods.
+ */
+type AssessmentHandle = {
+    getScore: () => number;
+    getMaxScore: () => number;
+    getAnswerGiven: () => boolean;
+    resetTask: () => void;
+    showSolutions: () => void;
+    getXAPIData: () => AssessmentXAPIData;
+};
+type AssessmentBaseProps = AssessmentBehaviour & {
+    checkId: CheckId;
+    passingScore?: number;
+};
+
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -87,6 +121,20 @@ type QuizCompletedData = {
     maxScore?: number;
     passingScore?: number;
 };
+type AssessmentAnsweredData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    question?: string;
+    response?: string | string[] | boolean | Record<string, unknown>;
+    correct?: boolean;
+};
+type AssessmentCompletedData = {
+    checkId: CheckId;
+    interactionType: AssessmentInteractionType;
+    score?: number;
+    maxScore?: number;
+    passingScore?: number;
+};
 type InteractionData = {
     kind?: string;
     blockId?: BlockId;
@@ -121,6 +169,14 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "quiz_completed";
     lessonId: LessonId;
     data: QuizCompletedData;
+}) | (TelemetryEventBase & {
+    name: "assessment_answered";
+    lessonId: LessonId;
+    data: AssessmentAnsweredData;
+}) | (TelemetryEventBase & {
+    name: "assessment_completed";
+    lessonId: LessonId;
+    data: AssessmentCompletedData;
 }) | (TelemetryEventBase & {
     name: "interaction";
     lessonId?: LessonId;
@@ -152,6 +208,18 @@ type TelemetryCatalogEntry = {
 declare const TELEMETRY_EVENT_CATALOG: TelemetryCatalogEntry[];
 declare function buildTelemetryCatalog(): TelemetryCatalogEntry[];
 
+declare const telemetryCatalogV2Version: 2;
+type TelemetryCatalogV2Entry = {
+    name: Extract<TelemetryEventName, "assessment_answered" | "assessment_completed">;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
+declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
+
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -201,6 +269,14 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "quiz_completed";
     lessonId?: LessonId;
     data: QuizCompletedData;
+}) | (BuildTelemetryEventContext & {
+    name: "assessment_answered";
+    lessonId?: LessonId;
+    data: AssessmentAnsweredData;
+}) | (BuildTelemetryEventContext & {
+    name: "assessment_completed";
+    lessonId?: LessonId;
+    data: AssessmentCompletedData;
 }) | (BuildTelemetryEventContext & {
     name: "interaction";
     lessonId?: LessonId;
@@ -429,4 +505,4 @@ declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin
 declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
 declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, 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 };
+export { type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogV2Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };

package/dist/index.js

@@ -174,6 +174,30 @@ function buildTelemetryCatalog() {
   return TELEMETRY_EVENT_CATALOG.map((entry) => ({ ...entry }));
 }
 
+// src/telemetryCatalogV2.ts
+var telemetryCatalogV2Version = 2;
+var TELEMETRY_EVENT_CATALOG_V2 = [
+  {
+    name: "assessment_answered",
+    description: "Learner submitted an assessment interaction answer",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "question", "response", "correct"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "assessment_completed",
+    description: "Assessment interaction completed (passing criteria met)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "score", "maxScore", "passingScore"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  }
+];
+function buildTelemetryCatalogV2() {
+  return TELEMETRY_EVENT_CATALOG_V2.map((entry) => ({ ...entry }));
+}
+
 // src/trackingClient.ts
 function isDevEnvironment() {
   const g = globalThis;
@@ -206,6 +230,11 @@ function invokeTrackingSink(sink, event) {
 function createTrackingClient(opts) {
   const sink = opts?.sink;
   const batchSink = opts?.batchSink;
+  if (batchSink != null && opts?.batch?.enabled === false) {
+    throw new Error(
+      "[lessonkit] tracking.batchSink cannot be used with batch.enabled: false; omit batch.enabled or set it to true"
+    );
+  }
   const batchEnabled = opts?.batch?.enabled ?? Boolean(batchSink);
   const flushIntervalMs = opts?.batch?.flushIntervalMs ?? 5e3;
   const maxBatchSize = opts?.batch?.maxBatchSize ?? 25;
@@ -277,7 +306,7 @@ function createTrackingClient(opts) {
       if (disposed || disposing) return;
       if (buffer.length >= maxBufferSize) {
         buffer.shift();
-        if (!warnedBufferCap && typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+        if (!warnedBufferCap && isDevEnvironment()) {
           warnedBufferCap = true;
           console.warn(
             `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; oldest events are dropped while the sink is unavailable.`
@@ -317,12 +346,14 @@ function nowIso() {
 
 // src/telemetryBuilder.ts
 var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
 function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function resetTelemetryBuilderWarningsForTests() {
   warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
 }
 function resolveLessonId(opts, eventName) {
   const lessonId = opts.lessonId ?? opts.data?.lessonId;
@@ -371,6 +402,16 @@ function buildTelemetryEvent(opts) {
       if (!lessonId) throw new Error("quiz_completed requires active lessonId");
       return { name: "quiz_completed", ...base, lessonId, data: opts.data };
     }
+    case "assessment_answered": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
+      return { name: "assessment_answered", ...base, lessonId, data: opts.data };
+    }
+    case "assessment_completed": {
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
+      return { name: "assessment_completed", ...base, lessonId, data: opts.data };
+    }
     case "interaction":
       return {
         name: "interaction",
@@ -383,13 +424,21 @@ function buildTelemetryEvent(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`
-      );
+  const needsLesson = opts.name === "quiz_answered" || opts.name === "quiz_completed" || opts.name === "assessment_answered" || opts.name === "assessment_completed";
+  if (needsLesson && !opts.lessonId) {
+    if (isDevEnvironment2()) {
+      if (opts.name.startsWith("quiz_") && !warnedMissingQuizLesson) {
+        warnedMissingQuizLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+        );
+      }
+      if (opts.name.startsWith("assessment_") && !warnedMissingAssessmentLesson) {
+        warnedMissingAssessmentLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
+        );
+      }
     }
     return null;
   }
@@ -466,7 +515,8 @@ function createMemoryBackedSessionStorage(session) {
   const warnPersistFailure = () => {
     if (warnedPersistFailure) return;
     warnedPersistFailure = true;
-    if (typeof process !== "undefined" && process.env?.NODE_ENV === "development") {
+    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)."
       );
@@ -507,23 +557,37 @@ function createMemoryBackedSessionStorage(session) {
 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);
+    },
+    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() {
-  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();
-      }
-    };
+  const session = resolveBrowserSessionStorage();
+  if (!session) {
+    return createInMemorySessionStoragePort();
   }
-  return createMemoryBackedSessionStorage(sessionStorage);
+  return createMemoryBackedSessionStorage(session);
 }
 function createGlobalTimer() {
   return {
@@ -880,11 +944,13 @@ export {
   ID_PATTERN,
   SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  TELEMETRY_EVENT_CATALOG_V2,
   assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
   buildTelemetryCatalog,
+  buildTelemetryCatalogV2,
   buildTelemetryEvent,
   completeCourseWithTelemetry,
   completeLessonWithTelemetry,
@@ -920,6 +986,7 @@ export {
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,
   slugifyId,
+  telemetryCatalogV2Version,
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -48,8 +48,9 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "devDependencies": {
+    "@types/node": "^22.13.10",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }