Core reference¶

`@lessonkit/core` reference (1.0)¶

Headless runtime, telemetry pipeline, plugins, identity, and session helpers shared across LessonKit packages.

Identity¶

validateId, assertValidId, slugifyId, deriveId, buildLessonkitUrn
Machine-readable contract: @lessonkit/core/identity-contract.v1.json

Telemetry¶

Event builder¶

import { buildTelemetryEvent, tryBuildTelemetryEvent } from "@lessonkit/core";

const event = buildTelemetryEvent({
  name: "lesson_completed",
  courseId: "my-course",
  lessonId: "intro",
  sessionId: "…",
  data: { lessonId: "intro", durationMs: 1200 },
});

tryBuildTelemetryEvent returns null for quiz events when no lessonId is available (instead of throwing).

Pipeline¶

import {
  createTelemetryPipeline,
  createTrackingPipelineSink,
  type TelemetryPipelineSink,
} from "@lessonkit/core";

const pipeline = createTelemetryPipeline([
  createTrackingPipelineSink("analytics", (event) => sink(event)),
  {
    id: "custom",
    emit(event) {
      /* … */
    },
  },
]);

pipeline.emit(event);

@lessonkit/react routes provider telemetry through an internal pipeline (tracking, xAPI, LXPack bridge) and accepts extra sinks via config.sinks.

Tracking client¶

import { createTrackingClient } from "@lessonkit/core";

const client = createTrackingClient({
  sink: (event) => console.log(event),
  batch: { enabled: true, flushIntervalMs: 5000, maxBatchSize: 50 },
  batchSink: (events) => sendBatch(events),
});

Catalog¶

TELEMETRY_EVENT_CATALOG, buildTelemetryCatalog(), telemetryCatalogVersion
JSON: @lessonkit/core/telemetry-catalog.v1.json

See Telemetry reference.

Headless runtime¶

createLessonkitRuntime powers @lessonkit/react when runtimeVersion is "v2" (the default in 1.0):

import { createLessonkitRuntime } from "@lessonkit/core";

const runtime = createLessonkitRuntime({
  courseId: "my-course",
  runtimeVersion: "v2",
  session: { sessionId: "…", attemptId: "…" },
  plugins: [defineTelemetryPlugin({ id: "…", version: "1", kind: "analytics", onTelemetry: (e) => e })],
});

runtime.setActiveLesson("intro", emitLifecycle);
runtime.completeLesson("intro", emitLifecycle);
runtime.completeCourse(emitLifecycle);

Exports: createProgressController, buildPluginContext, session helpers (resolveSessionId, hasCourseStarted, …), and course lifecycle helpers in runtime/courseLifecycle. Plugin hooks run on runtime.track and lifecycle emits; call runtime.dispose() when tearing down a headless instance.

Plugins¶

Segregated plugin types and registry:

import {
  createPluginRegistry,
  defineTelemetryPlugin,
  defineAssessmentPlugin,
  defineLifecyclePlugin,
} from "@lessonkit/core";

const registry = createPluginRegistry([
  defineTelemetryPlugin({
    id: "com.example.analytics",
    version: "1.0.0",
    kind: "analytics",
    onTelemetry: (event) => event,
  }),
]);

See Plugins reference and LXPack bridge reference.

Ports¶

Testable abstractions: createSessionStoragePort, createDefaultClock, createGlobalTimer, createNoopStorage.