@lessonkit/core 1.0.0 → 1.0.1

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   ID_PATTERN: () => ID_PATTERN,
   SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
+  assertNever: () => assertNever,
   assertValidId: () => assertValidId,
   buildCourseStartedTelemetryEvent: () => buildCourseStartedTelemetryEvent,
   buildLessonkitUrn: () => buildLessonkitUrn,
@@ -49,10 +50,16 @@ __export(index_exports, {
   getTabSessionId: () => getTabSessionId,
   hasCourseStarted: () => hasCourseStarted,
   hasCourseStartedEmittedToTracking: () => hasCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered: () => hasCourseStartedPipelineDelivered,
   markCourseStarted: () => markCourseStarted,
   markCourseStartedEmittedToTracking: () => markCourseStartedEmittedToTracking,
+  markCourseStartedPipelineDelivered: () => markCourseStartedPipelineDelivered,
   migrateCourseStartedMark: () => migrateCourseStartedMark,
   nowIso: () => nowIso,
+  parseBlockId: () => parseBlockId,
+  parseCheckId: () => parseCheckId,
+  parseCourseId: () => parseCourseId,
+  parseLessonId: () => parseLessonId,
   resetStoragePortForTests: () => resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
   resolveSessionId: () => resolveSessionId,
@@ -68,6 +75,11 @@ module.exports = __toCommonJS(index_exports);
 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") {
@@ -96,6 +108,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) {
@@ -369,6 +397,11 @@ function isDevEnvironment2() {
 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(),
@@ -383,39 +416,33 @@ function buildTelemetryEvent(opts) {
     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");
+      const lessonId = resolveLessonId(opts, "lesson_started");
       return {
         name: "lesson_started",
         ...base,
         lessonId,
-        data: { ...data, lessonId }
+        data: { ...opts.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`);
+      const lessonId = resolveLessonId(opts, opts.name);
       return {
         name: opts.name,
         ...base,
         lessonId,
-        data: { ...data, lessonId }
+        data: { ...opts.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 };
+      return { name: "quiz_answered", ...base, lessonId, data: opts.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 };
+      return { name: "quiz_completed", ...base, lessonId, data: opts.data };
     }
     case "interaction":
       return {
@@ -425,7 +452,7 @@ function buildTelemetryEvent(opts) {
         data: opts.data
       };
     default:
-      return { name: opts.name, ...base };
+      return assertNever(opts);
   }
 }
 function tryBuildTelemetryEvent(opts) {
@@ -622,6 +649,7 @@ 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:";
 function resolveSessionId(storage, provided) {
   if (provided) return provided;
   const existing = storage.getItem(SESSION_STORAGE_KEY);
@@ -636,6 +664,9 @@ function courseStartedStorageKey(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";
@@ -652,6 +683,14 @@ 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)) {
@@ -662,6 +701,10 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, 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
@@ -911,6 +954,7 @@ function defineLifecyclePlugin(plugin) {
   ID_PATTERN,
   SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
@@ -936,10 +980,16 @@ function defineLifecyclePlugin(plugin) {
   getTabSessionId,
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
+  markCourseStartedPipelineDelivered,
   migrateCourseStartedMark,
   nowIso,
+  parseBlockId,
+  parseCheckId,
+  parseCourseId,
+  parseLessonId,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,

package/dist/index.d.cts

@@ -2,6 +2,8 @@ type CourseId = string;
 type LessonId = string;
 type CheckId = string;
 type BlockId = string;
+/** Stable URN string returned by {@link buildLessonkitUrn}. */
+type LessonkitUrn = string;
 type IdentityValidationIssue = {
     path: string;
     message: string;
@@ -13,12 +15,27 @@ type IdentityValidationResult = {
     ok: false;
     issues: IdentityValidationIssue[];
 };
+type IdentityIdPath = "courseId" | "lessonId" | "checkId" | "blockId" | "id";
 /** LessonKit id format: letter first, then alphanumeric, `_`, `-`; length 1–64. */
 declare const ID_PATTERN: RegExp;
 declare const ID_MAX_LENGTH = 64;
 
-declare function validateId(input: unknown, path?: string): IdentityValidationResult;
-declare function assertValidId(input: unknown, path?: string): string;
+/**
+ * Exhaustiveness helper for switch/default branches.
+ * @throws when called at runtime with an unexpected value.
+ */
+declare function assertNever(value: never, message?: string): never;
+
+declare function validateId(input: unknown, path?: IdentityIdPath | string): IdentityValidationResult;
+declare function parseCourseId(input: unknown): CourseId | null;
+declare function parseLessonId(input: unknown): LessonId | null;
+declare function parseCheckId(input: unknown): CheckId | null;
+declare function parseBlockId(input: unknown): BlockId | null;
+declare function assertValidId(input: unknown, path: "courseId"): CourseId;
+declare function assertValidId(input: unknown, path: "lessonId"): LessonId;
+declare function assertValidId(input: unknown, path: "checkId"): CheckId;
+declare function assertValidId(input: unknown, path: "blockId"): BlockId;
+declare function assertValidId(input: unknown, path?: IdentityIdPath | string): string;
 
 /** Convert human-readable text to a candidate LessonKit id (may still need collision handling via deriveId). */
 declare function slugifyId(input: string): string;
@@ -35,7 +52,7 @@ type LessonkitUrnParts = {
  * Build a stable LessonKit URN for courses, lessons, checks, and blocks.
  * Segments are validated and encoded in path order.
  */
-declare function buildLessonkitUrn(parts: LessonkitUrnParts): string;
+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";
 type TelemetryUser = {
@@ -109,6 +126,12 @@ type TelemetryEvent = (TelemetryEventBase & {
     lessonId?: LessonId;
     data?: InteractionData;
 });
+/** Payload shape for a telemetry event name. */
+type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
+    name: N;
+}> extends {
+    data?: infer D;
+} ? D : never;
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
@@ -143,16 +166,46 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-type BuildTelemetryEventInput = {
-    name: TelemetryEventName;
+type BuildTelemetryEventContext = {
     courseId: CourseId;
-    lessonId?: LessonId;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
-    data?: unknown;
     timestamp?: string;
 };
+type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
+    name: "course_started";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (BuildTelemetryEventContext & {
+    name: "course_completed";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_started";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_completed";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_time_on_task";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "quiz_answered";
+    lessonId?: LessonId;
+    data: QuizAnsweredData;
+}) | (BuildTelemetryEventContext & {
+    name: "quiz_completed";
+    lessonId?: LessonId;
+    data: QuizCompletedData;
+}) | (BuildTelemetryEventContext & {
+    name: "interaction";
+    lessonId?: LessonId;
+    data?: InteractionData;
+});
 /** Reset dev-warning state (tests only). */
 declare function resetTelemetryBuilderWarningsForTests(): void;
 /**
@@ -166,7 +219,7 @@ declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryE
 declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
 
 type EmitContext = {
-    courseId: string;
+    courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
 };
@@ -230,6 +283,8 @@ declare function hasCourseStarted(storage: StoragePort, sessionId: string, cours
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
 /** Plugin category — aligns with roadmap extension areas. */
@@ -241,8 +296,8 @@ type LessonkitPluginContext = {
     user?: TelemetryUser;
 };
 type AssessmentScoreInput = {
-    checkId: string;
-    lessonId?: string;
+    checkId: CheckId;
+    lessonId?: LessonId;
     response: unknown;
 };
 type AssessmentScoreResult = {
@@ -347,6 +402,9 @@ type HeadlessRuntimePorts = {
     storage?: StoragePort;
     clock?: ClockPort;
 };
+type TelemetryEmitFn = {
+    <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, lessonId?: LessonId): void;
+};
 type HeadlessLessonkitRuntime = {
     readonly config: HeadlessLessonkitConfig;
     readonly progress: ProgressController;
@@ -357,10 +415,10 @@ type HeadlessLessonkitRuntime = {
         user?: TelemetryUser;
     };
     updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
-    setActiveLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    completeLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    completeCourse: (emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    track: (name: TelemetryEventName, data: unknown | undefined, emit: (event: ReturnType<typeof tryBuildTelemetryEvent>) => void, lessonId?: LessonId) => void;
+    setActiveLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
+    completeLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
+    completeCourse: (emit: TelemetryEmitFn) => void;
+    track: <N extends TelemetryEventName>(name: N, data: TelemetryDataFor<N> | undefined, emit: (event: TelemetryEvent) => void, lessonId?: LessonId) => void;
     resetForCourseChange: (courseId: CourseId) => void;
 };
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
@@ -371,4 +429,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 IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, 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, markCourseStarted, markCourseStartedEmittedToTracking, migrateCourseStartedMark, nowIso, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+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 };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ type CourseId = string;
 type LessonId = string;
 type CheckId = string;
 type BlockId = string;
+/** Stable URN string returned by {@link buildLessonkitUrn}. */
+type LessonkitUrn = string;
 type IdentityValidationIssue = {
     path: string;
     message: string;
@@ -13,12 +15,27 @@ type IdentityValidationResult = {
     ok: false;
     issues: IdentityValidationIssue[];
 };
+type IdentityIdPath = "courseId" | "lessonId" | "checkId" | "blockId" | "id";
 /** LessonKit id format: letter first, then alphanumeric, `_`, `-`; length 1–64. */
 declare const ID_PATTERN: RegExp;
 declare const ID_MAX_LENGTH = 64;
 
-declare function validateId(input: unknown, path?: string): IdentityValidationResult;
-declare function assertValidId(input: unknown, path?: string): string;
+/**
+ * Exhaustiveness helper for switch/default branches.
+ * @throws when called at runtime with an unexpected value.
+ */
+declare function assertNever(value: never, message?: string): never;
+
+declare function validateId(input: unknown, path?: IdentityIdPath | string): IdentityValidationResult;
+declare function parseCourseId(input: unknown): CourseId | null;
+declare function parseLessonId(input: unknown): LessonId | null;
+declare function parseCheckId(input: unknown): CheckId | null;
+declare function parseBlockId(input: unknown): BlockId | null;
+declare function assertValidId(input: unknown, path: "courseId"): CourseId;
+declare function assertValidId(input: unknown, path: "lessonId"): LessonId;
+declare function assertValidId(input: unknown, path: "checkId"): CheckId;
+declare function assertValidId(input: unknown, path: "blockId"): BlockId;
+declare function assertValidId(input: unknown, path?: IdentityIdPath | string): string;
 
 /** Convert human-readable text to a candidate LessonKit id (may still need collision handling via deriveId). */
 declare function slugifyId(input: string): string;
@@ -35,7 +52,7 @@ type LessonkitUrnParts = {
  * Build a stable LessonKit URN for courses, lessons, checks, and blocks.
  * Segments are validated and encoded in path order.
  */
-declare function buildLessonkitUrn(parts: LessonkitUrnParts): string;
+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";
 type TelemetryUser = {
@@ -109,6 +126,12 @@ type TelemetryEvent = (TelemetryEventBase & {
     lessonId?: LessonId;
     data?: InteractionData;
 });
+/** Payload shape for a telemetry event name. */
+type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
+    name: N;
+}> extends {
+    data?: infer D;
+} ? D : never;
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
@@ -143,16 +166,46 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-type BuildTelemetryEventInput = {
-    name: TelemetryEventName;
+type BuildTelemetryEventContext = {
     courseId: CourseId;
-    lessonId?: LessonId;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
-    data?: unknown;
     timestamp?: string;
 };
+type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
+    name: "course_started";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (BuildTelemetryEventContext & {
+    name: "course_completed";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_started";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_completed";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "lesson_time_on_task";
+    lessonId?: LessonId;
+    data?: LessonLifecycleData;
+}) | (BuildTelemetryEventContext & {
+    name: "quiz_answered";
+    lessonId?: LessonId;
+    data: QuizAnsweredData;
+}) | (BuildTelemetryEventContext & {
+    name: "quiz_completed";
+    lessonId?: LessonId;
+    data: QuizCompletedData;
+}) | (BuildTelemetryEventContext & {
+    name: "interaction";
+    lessonId?: LessonId;
+    data?: InteractionData;
+});
 /** Reset dev-warning state (tests only). */
 declare function resetTelemetryBuilderWarningsForTests(): void;
 /**
@@ -166,7 +219,7 @@ declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryE
 declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
 
 type EmitContext = {
-    courseId: string;
+    courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
 };
@@ -230,6 +283,8 @@ declare function hasCourseStarted(storage: StoragePort, sessionId: string, cours
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
 /** Plugin category — aligns with roadmap extension areas. */
@@ -241,8 +296,8 @@ type LessonkitPluginContext = {
     user?: TelemetryUser;
 };
 type AssessmentScoreInput = {
-    checkId: string;
-    lessonId?: string;
+    checkId: CheckId;
+    lessonId?: LessonId;
     response: unknown;
 };
 type AssessmentScoreResult = {
@@ -347,6 +402,9 @@ type HeadlessRuntimePorts = {
     storage?: StoragePort;
     clock?: ClockPort;
 };
+type TelemetryEmitFn = {
+    <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, lessonId?: LessonId): void;
+};
 type HeadlessLessonkitRuntime = {
     readonly config: HeadlessLessonkitConfig;
     readonly progress: ProgressController;
@@ -357,10 +415,10 @@ type HeadlessLessonkitRuntime = {
         user?: TelemetryUser;
     };
     updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
-    setActiveLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    completeLesson: (lessonId: LessonId, emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    completeCourse: (emit: (name: TelemetryEventName, data?: unknown, lessonId?: LessonId) => void) => void;
-    track: (name: TelemetryEventName, data: unknown | undefined, emit: (event: ReturnType<typeof tryBuildTelemetryEvent>) => void, lessonId?: LessonId) => void;
+    setActiveLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
+    completeLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
+    completeCourse: (emit: TelemetryEmitFn) => void;
+    track: <N extends TelemetryEventName>(name: N, data: TelemetryDataFor<N> | undefined, emit: (event: TelemetryEvent) => void, lessonId?: LessonId) => void;
     resetForCourseChange: (courseId: CourseId) => void;
 };
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
@@ -371,4 +429,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 IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrnParts, type LifecyclePlugin, type PluginHost, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, 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, markCourseStarted, markCourseStartedEmittedToTracking, migrateCourseStartedMark, nowIso, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+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 };

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) {
@@ -303,6 +324,11 @@ function isDevEnvironment2() {
 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(),
@@ -317,39 +343,33 @@ function buildTelemetryEvent(opts) {
     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");
+      const lessonId = resolveLessonId(opts, "lesson_started");
       return {
         name: "lesson_started",
         ...base,
         lessonId,
-        data: { ...data, lessonId }
+        data: { ...opts.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`);
+      const lessonId = resolveLessonId(opts, opts.name);
       return {
         name: opts.name,
         ...base,
         lessonId,
-        data: { ...data, lessonId }
+        data: { ...opts.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 };
+      return { name: "quiz_answered", ...base, lessonId, data: opts.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 };
+      return { name: "quiz_completed", ...base, lessonId, data: opts.data };
     }
     case "interaction":
       return {
@@ -359,7 +379,7 @@ function buildTelemetryEvent(opts) {
         data: opts.data
       };
     default:
-      return { name: opts.name, ...base };
+      return assertNever(opts);
   }
 }
 function tryBuildTelemetryEvent(opts) {
@@ -556,6 +576,7 @@ 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:";
 function resolveSessionId(storage, provided) {
   if (provided) return provided;
   const existing = storage.getItem(SESSION_STORAGE_KEY);
@@ -570,6 +591,9 @@ function courseStartedStorageKey(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";
@@ -586,6 +610,14 @@ 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)) {
@@ -596,6 +628,10 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, 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
@@ -844,6 +880,7 @@ export {
   ID_PATTERN,
   SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
@@ -869,10 +906,16 @@ export {
   getTabSessionId,
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
+  markCourseStartedPipelineDelivered,
   migrateCourseStartedMark,
   nowIso,
+  parseBlockId,
+  parseCheckId,
+  parseCourseId,
+  parseLessonId,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,

package/package.json

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