@lessonkit/core 0.9.3 → 1.0.1

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,138 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
+type BuildTelemetryEventContext = {
+    courseId: CourseId;
+    sessionId?: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    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;
+/**
+ * Build a typed telemetry event from a catalog event name and context.
+ * Validates lesson-scoped events require `lessonId`.
+ */
+declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
+/**
+ * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
+ */
+declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
+
+type EmitContext = {
+    courseId: CourseId;
+    sessionId?: string;
+    attemptId?: string;
+};
+/** Pluggable telemetry output (OCP). Distinct from the legacy `TelemetrySink` function type. */
+type TelemetryPipelineSink = {
+    readonly id: string;
+    emit(event: TelemetryEvent, ctx: EmitContext): void | Promise<void>;
+};
+type TelemetryPipeline = {
+    readonly sinks: readonly TelemetryPipelineSink[];
+    emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
+};
+declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
+declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
+
+type StoragePort = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem?: (key: string) => void;
+    /** @internal Test helper to clear in-memory fallback state. */
+    resetForTests?: () => void;
+};
+type ClockPort = {
+    nowMs: () => number;
+    nowIso: () => string;
+};
+type TimerPort = {
+    setInterval: (fn: () => void, ms: number) => ReturnType<typeof globalThis.setInterval>;
+    clearInterval: (id: ReturnType<typeof globalThis.setInterval>) => void;
+};
+declare function createDefaultClock(): ClockPort;
+declare function createNoopStorage(): StoragePort;
+declare function resetStoragePortForTests(storage: StoragePort): void;
+declare function createSessionStoragePort(): StoragePort;
+declare function createGlobalTimer(): TimerPort;
+
+type ProgressState = {
+    activeLessonId?: LessonId;
+    completedLessonIds: ReadonlySet<LessonId>;
+    courseCompleted: boolean;
+};
+type ProgressController = {
+    getState: () => ProgressState;
+    setActiveLesson: (lessonId: LessonId, startedAtMs: number) => {
+        previousLessonId?: LessonId;
+    };
+    completeLesson: (lessonId: LessonId, completedAtMs: number) => {
+        durationMs?: number;
+        didComplete: boolean;
+    };
+    completeCourse: () => {
+        didComplete: boolean;
+    };
+};
+declare function createProgressController(): ProgressController;
+
+declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+declare function getTabSessionId(storage: StoragePort): string | null;
+declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+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. */
 type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
 type LessonkitPluginContext = {
     courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
+    user?: TelemetryUser;
 };
 type AssessmentScoreInput = {
-    checkId: string;
-    lessonId?: string;
+    checkId: CheckId;
+    lessonId?: LessonId;
     response: unknown;
 };
 type AssessmentScoreResult = {
@@ -167,43 +312,121 @@ type InteractionBlockRegistration = {
     catalogVersion?: string;
     description?: string;
 };
-/**
- * Framework plugin contract (v1). Plugins are plain objects registered on `LessonkitProvider`.
- * Marketplace / dynamic loading are out of scope until Studio post-1.0.
- */
-type LessonkitPlugin = {
+type PluginIdentity = {
     id: string;
     version: string;
     kind: LessonkitPluginKind;
     name?: string;
-    setup?: (ctx: LessonkitPluginContext) => void;
-    dispose?: () => void;
-    /**
-     * Observe or filter telemetry before tracking/xAPI. Return `null` to drop the event.
-     * Hooks run in registration order.
-     */
+};
+/** Narrow telemetry plugin contract (ISP). */
+type TelemetryPlugin = PluginIdentity & {
     onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
-    /** Optional batch observer (analytics); receives events after per-event hooks. */
     onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
-    /** Wrap the configured tracking sink (analytics plugins). First registered = innermost. */
     wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
-    /** Optional assessment scoring override (assessment plugins). */
+};
+/** Narrow lifecycle plugin contract (ISP). */
+type LifecyclePlugin = PluginIdentity & {
+    setup?: (ctx: LessonkitPluginContext) => void;
+    dispose?: () => void;
+};
+/** Narrow assessment plugin contract (ISP). */
+type AssessmentPlugin = PluginIdentity & {
+    kind: "assessment";
     scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
-    /** Declare custom interaction block types for generators/tooling. */
+};
+/** Narrow interaction metadata plugin (ISP). */
+type InteractionPlugin = PluginIdentity & {
     interactionBlocks?: InteractionBlockRegistration[];
 };
+/**
+ * Combined plugin contract (v1). Prefer segregated types for new plugins.
+ * @deprecated Prefer `TelemetryPlugin`, `AssessmentPlugin`, or `LifecyclePlugin` via `define*Plugin`.
+ */
+type LessonkitPlugin = PluginIdentity & Partial<Pick<TelemetryPlugin, "onTelemetry" | "onTelemetryBatch" | "wrapTrackingSink"> & Pick<LifecyclePlugin, "setup" | "dispose"> & Pick<AssessmentPlugin, "scoreAssessment"> & Pick<InteractionPlugin, "interactionBlocks">>;
 type PluginHost = {
     readonly plugins: readonly LessonkitPlugin[];
     setupAll: (ctx: LessonkitPluginContext) => void;
     disposeAll: () => void;
     runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
     runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    /** Invoke only `onTelemetryBatch` hooks; events were already filtered at emit time. */
     deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
     composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
     scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
-declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;
-declare function createPluginHost(plugins?: readonly LessonkitPlugin[]): PluginHost;
+/** Segregated plugin registry (ISP + SRP). */
+type PluginRegistry = PluginHost;
+
+type CourseLifecycleContext = {
+    courseId: CourseId;
+    sessionId: string;
+    attemptId?: string;
+    user?: TelemetryUser;
+    storage: StoragePort;
+    pluginHost: PluginRegistry | null;
+    lxpackBridge: "auto" | "off";
+};
+type CourseLifecycleDeps = {
+    emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
+};
+declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
+    emitted: boolean;
+    marked: boolean;
+};
+declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
+type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
+declare function completeLessonWithTelemetry(opts: {
+    progress: ProgressController;
+    lessonId: LessonId;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+}): boolean;
+declare function completeCourseWithTelemetry(opts: {
+    progress: ProgressController;
+    nowMs: number;
+    emitLessonCompleted: LessonCompletionEmitter;
+    emitCourseCompleted: () => void;
+}): boolean;
+
+type LessonkitRuntimeVersion = "v1" | "v2";
+type HeadlessLessonkitConfig = {
+    courseId: CourseId;
+    runtimeVersion?: LessonkitRuntimeVersion;
+    session?: {
+        sessionId?: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    plugins?: PluginRegistry | null;
+};
+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;
+    getProgressState: () => ProgressState;
+    getSession: () => {
+        sessionId: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
+    updateConfig: (next: Partial<HeadlessLessonkitConfig>) => 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;
+
+declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
+
+declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
+declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
+declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitUrnParts, type PluginHost, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createPluginHost, createSessionId, createTrackingClient, defineLessonkitPlugin, deriveId, nowIso, slugifyId, telemetryCatalogVersion, 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 };