@lessonkit/core 0.3.1 → 0.5.0

package/README.md

@@ -12,9 +12,12 @@ Core types and runtime primitives shared across LessonKit packages.
 npm install @lessonkit/core
 ```
 
-## What’s inside (0.3.0)
+## What’s inside (0.5.0)
 
-- Telemetry event types (`TelemetryEvent`)
-- A minimal tracking client (`createTrackingClient`) with optional batching
+- Identity helpers: `validateId`, `slugifyId`, `deriveId`, `buildLessonkitUrn`
+- Typed telemetry events (`TelemetryEvent`) and `telemetry-catalog.v1.json`
+- Tracking client (`createTrackingClient`) with optional batching
 - Session id helper (`createSessionId`)
 
+See [`docs/IDENTITY.md`](../../docs/IDENTITY.md) and [`docs/TELEMETRY.md`](../../docs/TELEMETRY.md).
+

package/dist/index.cjs

@@ -20,12 +20,177 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ID_MAX_LENGTH: () => ID_MAX_LENGTH,
+  ID_PATTERN: () => ID_PATTERN,
+  TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
+  assertValidId: () => assertValidId,
+  buildLessonkitUrn: () => buildLessonkitUrn,
+  buildTelemetryCatalog: () => buildTelemetryCatalog,
   createSessionId: () => createSessionId,
   createTrackingClient: () => createTrackingClient,
-  nowIso: () => nowIso
+  deriveId: () => deriveId,
+  nowIso: () => nowIso,
+  slugifyId: () => slugifyId,
+  telemetryCatalogVersion: () => telemetryCatalogVersion,
+  validateId: () => validateId
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/identityTypes.ts
+var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+var ID_MAX_LENGTH = 64;
+
+// src/validateId.ts
+function validateId(input, path = "id") {
+  if (typeof input !== "string") {
+    return { ok: false, issues: [{ path, message: "id must be a string" }] };
+  }
+  const id = input.trim();
+  if (!id.length) {
+    return { ok: false, issues: [{ path, message: "id must not be empty" }] };
+  }
+  if (id.length > ID_MAX_LENGTH) {
+    return {
+      ok: false,
+      issues: [{ path, message: `id must be at most ${ID_MAX_LENGTH} characters` }]
+    };
+  }
+  if (!ID_PATTERN.test(id)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path,
+          message: "id must start with a letter and contain only letters, digits, underscores, and hyphens"
+        }
+      ]
+    };
+  }
+  return { ok: true, id };
+}
+function assertValidId(input, path = "id") {
+  const result = validateId(input, path);
+  if (!result.ok) {
+    throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+  }
+  return result.id;
+}
+
+// src/slugify.ts
+function slugifyId(input) {
+  const slug = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").slice(0, 64);
+  if (!slug.length) return "id";
+  const candidate = /^[a-z]/.test(slug) ? slug : `id-${slug}`;
+  const validated = validateId(candidate);
+  return validated.ok ? validated.id : "id";
+}
+function deriveId(title, usedIds = /* @__PURE__ */ new Set()) {
+  const base = slugifyId(title);
+  if (!usedIds.has(base)) return base;
+  for (let n = 2; n < 1e3; n++) {
+    const candidate = `${base}-${n}`;
+    if (!usedIds.has(candidate)) return candidate;
+  }
+  return `${base}-${Date.now()}`;
+}
+
+// src/urn.ts
+function buildLessonkitUrn(parts) {
+  const courseId = assertValidId(parts.courseId, "courseId");
+  let urn = `urn:lessonkit:course:${courseId}`;
+  if (parts.lessonId !== void 0) {
+    const lessonId = assertValidId(parts.lessonId, "lessonId");
+    urn += `:lesson:${lessonId}`;
+  }
+  if (parts.checkId !== void 0) {
+    const checkId = assertValidId(parts.checkId, "checkId");
+    if (parts.lessonId === void 0) {
+      throw new Error("buildLessonkitUrn: checkId requires lessonId");
+    }
+    urn += `:check:${checkId}`;
+  }
+  if (parts.blockId !== void 0) {
+    const blockId = assertValidId(parts.blockId, "blockId");
+    if (parts.lessonId === void 0) {
+      throw new Error("buildLessonkitUrn: blockId requires lessonId");
+    }
+    urn += `:block:${blockId}`;
+  }
+  return urn;
+}
+
+// src/telemetryCatalog.ts
+var telemetryCatalogVersion = 1;
+var TELEMETRY_EVENT_CATALOG = [
+  {
+    name: "course_started",
+    description: "Learner session began for a course",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: [],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/initialized",
+    urnPattern: "urn:lessonkit:course:{courseId}"
+  },
+  {
+    name: "course_completed",
+    description: "Course completion criteria met",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: [],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}"
+  },
+  {
+    name: "lesson_started",
+    description: "Lesson became active",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/initialized",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "lesson_completed",
+    description: "Lesson marked complete",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId", "durationMs"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "lesson_time_on_task",
+    description: "Time on task for a lesson (companion to lesson_completed)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId", "durationMs"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "quiz_answered",
+    description: "Learner submitted a quiz/check answer",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "question", "choice", "correct"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "quiz_completed",
+    description: "Quiz/check completed (e.g. first correct answer)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "score", "maxScore"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "interaction",
+    description: "Custom interaction (branching, UI actions, blocks)",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["kind", "blockId", "payload"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  }
+];
+function buildTelemetryCatalog() {
+  return TELEMETRY_EVENT_CATALOG.map((entry) => ({ ...entry }));
+}
+
 // src/trackingClient.ts
 function createTrackingClient(opts) {
   const sink = opts?.sink;
@@ -110,7 +275,17 @@ function nowIso() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ID_MAX_LENGTH,
+  ID_PATTERN,
+  TELEMETRY_EVENT_CATALOG,
+  assertValidId,
+  buildLessonkitUrn,
+  buildTelemetryCatalog,
   createSessionId,
   createTrackingClient,
-  nowIso
+  deriveId,
+  nowIso,
+  slugifyId,
+  telemetryCatalogVersion,
+  validateId
 });

package/dist/index.d.cts

@@ -1,5 +1,42 @@
 type CourseId = string;
 type LessonId = string;
+type CheckId = string;
+type BlockId = string;
+type IdentityValidationIssue = {
+    path: string;
+    message: string;
+};
+type IdentityValidationResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    issues: IdentityValidationIssue[];
+};
+/** 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;
+
+/** Convert human-readable text to a candidate LessonKit id (may still need collision handling via deriveId). */
+declare function slugifyId(input: string): string;
+/** Pick a unique id from a title, suffixing -2, -3, … on collision. */
+declare function deriveId(title: string, usedIds?: ReadonlySet<string>): string;
+
+type LessonkitUrnParts = {
+    courseId: CourseId;
+    lessonId?: LessonId;
+    checkId?: CheckId;
+    blockId?: BlockId;
+};
+/**
+ * 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;
+
 type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
 type TelemetryUser = {
     id?: string;
@@ -7,16 +44,70 @@ type TelemetryUser = {
     name?: string;
     [key: string]: unknown;
 };
-type TelemetryEvent = {
-    name: TelemetryEventName;
+type TelemetryEventBase = {
     timestamp: string;
-    courseId?: CourseId;
-    lessonId?: LessonId;
+    courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
-    data?: Record<string, unknown>;
 };
+type LessonLifecycleData = {
+    lessonId: LessonId;
+    durationMs?: number;
+    success?: boolean;
+    score?: number;
+    maxScore?: number;
+};
+type QuizAnsweredData = {
+    checkId: CheckId;
+    question: string;
+    choice: string;
+    correct: boolean;
+};
+type QuizCompletedData = {
+    checkId: CheckId;
+    score?: number;
+    maxScore?: number;
+};
+type InteractionData = {
+    kind?: string;
+    blockId?: BlockId;
+    payload?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type TelemetryEvent = (TelemetryEventBase & {
+    name: "course_started";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (TelemetryEventBase & {
+    name: "course_completed";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (TelemetryEventBase & {
+    name: "lesson_started";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "lesson_completed";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "lesson_time_on_task";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "quiz_answered";
+    lessonId: LessonId;
+    data: QuizAnsweredData;
+}) | (TelemetryEventBase & {
+    name: "quiz_completed";
+    lessonId: LessonId;
+    data: QuizCompletedData;
+}) | (TelemetryEventBase & {
+    name: "interaction";
+    lessonId?: LessonId;
+    data?: InteractionData;
+});
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
@@ -25,6 +116,18 @@ type TrackingClient = {
     dispose?: () => void;
 };
 
+declare const telemetryCatalogVersion: 1;
+type TelemetryCatalogEntry = {
+    name: TelemetryEventName;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG: TelemetryCatalogEntry[];
+declare function buildTelemetryCatalog(): TelemetryCatalogEntry[];
+
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -39,4 +142,4 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-export { type CourseId, type LessonId, type TelemetryBatchSink, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, createSessionId, createTrackingClient, nowIso };
+export { type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitUrnParts, 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, createSessionId, createTrackingClient, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };

package/dist/index.d.ts

@@ -1,5 +1,42 @@
 type CourseId = string;
 type LessonId = string;
+type CheckId = string;
+type BlockId = string;
+type IdentityValidationIssue = {
+    path: string;
+    message: string;
+};
+type IdentityValidationResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    issues: IdentityValidationIssue[];
+};
+/** 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;
+
+/** Convert human-readable text to a candidate LessonKit id (may still need collision handling via deriveId). */
+declare function slugifyId(input: string): string;
+/** Pick a unique id from a title, suffixing -2, -3, … on collision. */
+declare function deriveId(title: string, usedIds?: ReadonlySet<string>): string;
+
+type LessonkitUrnParts = {
+    courseId: CourseId;
+    lessonId?: LessonId;
+    checkId?: CheckId;
+    blockId?: BlockId;
+};
+/**
+ * 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;
+
 type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
 type TelemetryUser = {
     id?: string;
@@ -7,16 +44,70 @@ type TelemetryUser = {
     name?: string;
     [key: string]: unknown;
 };
-type TelemetryEvent = {
-    name: TelemetryEventName;
+type TelemetryEventBase = {
     timestamp: string;
-    courseId?: CourseId;
-    lessonId?: LessonId;
+    courseId: CourseId;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
-    data?: Record<string, unknown>;
 };
+type LessonLifecycleData = {
+    lessonId: LessonId;
+    durationMs?: number;
+    success?: boolean;
+    score?: number;
+    maxScore?: number;
+};
+type QuizAnsweredData = {
+    checkId: CheckId;
+    question: string;
+    choice: string;
+    correct: boolean;
+};
+type QuizCompletedData = {
+    checkId: CheckId;
+    score?: number;
+    maxScore?: number;
+};
+type InteractionData = {
+    kind?: string;
+    blockId?: BlockId;
+    payload?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type TelemetryEvent = (TelemetryEventBase & {
+    name: "course_started";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (TelemetryEventBase & {
+    name: "course_completed";
+    lessonId?: LessonId;
+    data?: undefined;
+}) | (TelemetryEventBase & {
+    name: "lesson_started";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "lesson_completed";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "lesson_time_on_task";
+    lessonId: LessonId;
+    data: LessonLifecycleData;
+}) | (TelemetryEventBase & {
+    name: "quiz_answered";
+    lessonId: LessonId;
+    data: QuizAnsweredData;
+}) | (TelemetryEventBase & {
+    name: "quiz_completed";
+    lessonId: LessonId;
+    data: QuizCompletedData;
+}) | (TelemetryEventBase & {
+    name: "interaction";
+    lessonId?: LessonId;
+    data?: InteractionData;
+});
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
@@ -25,6 +116,18 @@ type TrackingClient = {
     dispose?: () => void;
 };
 
+declare const telemetryCatalogVersion: 1;
+type TelemetryCatalogEntry = {
+    name: TelemetryEventName;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG: TelemetryCatalogEntry[];
+declare function buildTelemetryCatalog(): TelemetryCatalogEntry[];
+
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -39,4 +142,4 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-export { type CourseId, type LessonId, type TelemetryBatchSink, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, createSessionId, createTrackingClient, nowIso };
+export { type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitUrnParts, 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, createSessionId, createTrackingClient, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };

package/dist/index.js

@@ -1,3 +1,158 @@
+// src/identityTypes.ts
+var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+var ID_MAX_LENGTH = 64;
+
+// src/validateId.ts
+function validateId(input, path = "id") {
+  if (typeof input !== "string") {
+    return { ok: false, issues: [{ path, message: "id must be a string" }] };
+  }
+  const id = input.trim();
+  if (!id.length) {
+    return { ok: false, issues: [{ path, message: "id must not be empty" }] };
+  }
+  if (id.length > ID_MAX_LENGTH) {
+    return {
+      ok: false,
+      issues: [{ path, message: `id must be at most ${ID_MAX_LENGTH} characters` }]
+    };
+  }
+  if (!ID_PATTERN.test(id)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path,
+          message: "id must start with a letter and contain only letters, digits, underscores, and hyphens"
+        }
+      ]
+    };
+  }
+  return { ok: true, id };
+}
+function assertValidId(input, path = "id") {
+  const result = validateId(input, path);
+  if (!result.ok) {
+    throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+  }
+  return result.id;
+}
+
+// src/slugify.ts
+function slugifyId(input) {
+  const slug = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").slice(0, 64);
+  if (!slug.length) return "id";
+  const candidate = /^[a-z]/.test(slug) ? slug : `id-${slug}`;
+  const validated = validateId(candidate);
+  return validated.ok ? validated.id : "id";
+}
+function deriveId(title, usedIds = /* @__PURE__ */ new Set()) {
+  const base = slugifyId(title);
+  if (!usedIds.has(base)) return base;
+  for (let n = 2; n < 1e3; n++) {
+    const candidate = `${base}-${n}`;
+    if (!usedIds.has(candidate)) return candidate;
+  }
+  return `${base}-${Date.now()}`;
+}
+
+// src/urn.ts
+function buildLessonkitUrn(parts) {
+  const courseId = assertValidId(parts.courseId, "courseId");
+  let urn = `urn:lessonkit:course:${courseId}`;
+  if (parts.lessonId !== void 0) {
+    const lessonId = assertValidId(parts.lessonId, "lessonId");
+    urn += `:lesson:${lessonId}`;
+  }
+  if (parts.checkId !== void 0) {
+    const checkId = assertValidId(parts.checkId, "checkId");
+    if (parts.lessonId === void 0) {
+      throw new Error("buildLessonkitUrn: checkId requires lessonId");
+    }
+    urn += `:check:${checkId}`;
+  }
+  if (parts.blockId !== void 0) {
+    const blockId = assertValidId(parts.blockId, "blockId");
+    if (parts.lessonId === void 0) {
+      throw new Error("buildLessonkitUrn: blockId requires lessonId");
+    }
+    urn += `:block:${blockId}`;
+  }
+  return urn;
+}
+
+// src/telemetryCatalog.ts
+var telemetryCatalogVersion = 1;
+var TELEMETRY_EVENT_CATALOG = [
+  {
+    name: "course_started",
+    description: "Learner session began for a course",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: [],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/initialized",
+    urnPattern: "urn:lessonkit:course:{courseId}"
+  },
+  {
+    name: "course_completed",
+    description: "Course completion criteria met",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: [],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}"
+  },
+  {
+    name: "lesson_started",
+    description: "Lesson became active",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/initialized",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "lesson_completed",
+    description: "Lesson marked complete",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId", "durationMs"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "lesson_time_on_task",
+    description: "Time on task for a lesson (companion to lesson_completed)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["lessonId", "durationMs"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+  },
+  {
+    name: "quiz_answered",
+    description: "Learner submitted a quiz/check answer",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "question", "choice", "correct"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "quiz_completed",
+    description: "Quiz/check completed (e.g. first correct answer)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "score", "maxScore"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "interaction",
+    description: "Custom interaction (branching, UI actions, blocks)",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["kind", "blockId", "payload"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  }
+];
+function buildTelemetryCatalog() {
+  return TELEMETRY_EVENT_CATALOG.map((entry) => ({ ...entry }));
+}
+
 // src/trackingClient.ts
 function createTrackingClient(opts) {
   const sink = opts?.sink;
@@ -81,7 +236,17 @@ function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 export {
+  ID_MAX_LENGTH,
+  ID_PATTERN,
+  TELEMETRY_EVENT_CATALOG,
+  assertValidId,
+  buildLessonkitUrn,
+  buildTelemetryCatalog,
   createSessionId,
   createTrackingClient,
-  nowIso
+  deriveId,
+  nowIso,
+  slugifyId,
+  telemetryCatalogVersion,
+  validateId
 };

package/identity-contract.v1.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lessonkit.dev/schemas/identity-contract.v1.json",
+  "title": "LessonKit Identity Contract v1",
+  "description": "Stable id format and URN patterns for LessonKit courses, lessons, checks, and blocks.",
+  "schemaVersion": 1,
+  "idPattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+  "maxLength": 64,
+  "requiredComponentIds": {
+    "Course": ["courseId"],
+    "Lesson": ["lessonId"],
+    "Quiz": ["checkId"],
+    "KnowledgeCheck": ["checkId"]
+  },
+  "optionalComponentIds": {
+    "Scenario": ["blockId"],
+    "Reflection": ["blockId"]
+  },
+  "urnPatterns": {
+    "course": "urn:lessonkit:course:{courseId}",
+    "lesson": "urn:lessonkit:course:{courseId}:lesson:{lessonId}",
+    "check": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}",
+    "block": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -29,10 +29,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./telemetry-catalog.v1.json": "./telemetry-catalog.v1.json",
+    "./identity-contract.v1.json": "./identity-contract.v1.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "telemetry-catalog.v1.json",
+    "identity-contract.v1.json"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",

package/telemetry-catalog.v1.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "name": "course_started",
+      "description": "Learner session began for a course",
+      "requiredFields": ["courseId", "sessionId", "timestamp"],
+      "dataFields": [],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/initialized",
+      "urnPattern": "urn:lessonkit:course:{courseId}"
+    },
+    {
+      "name": "course_completed",
+      "description": "Course completion criteria met",
+      "requiredFields": ["courseId", "sessionId", "timestamp"],
+      "dataFields": [],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/completed",
+      "urnPattern": "urn:lessonkit:course:{courseId}"
+    },
+    {
+      "name": "lesson_started",
+      "description": "Lesson became active",
+      "requiredFields": ["courseId", "lessonId", "sessionId", "timestamp"],
+      "dataFields": ["lessonId"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/initialized",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+    },
+    {
+      "name": "lesson_completed",
+      "description": "Lesson marked complete",
+      "requiredFields": ["courseId", "lessonId", "sessionId", "timestamp"],
+      "dataFields": ["lessonId", "durationMs"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/completed",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+    },
+    {
+      "name": "lesson_time_on_task",
+      "description": "Time on task for a lesson (companion to lesson_completed)",
+      "requiredFields": ["courseId", "lessonId", "sessionId", "timestamp"],
+      "dataFields": ["lessonId", "durationMs"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/completed",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}"
+    },
+    {
+      "name": "quiz_answered",
+      "description": "Learner submitted a quiz/check answer",
+      "requiredFields": ["courseId", "lessonId", "sessionId", "timestamp"],
+      "dataFields": ["checkId", "question", "choice", "correct"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/answered",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+    },
+    {
+      "name": "quiz_completed",
+      "description": "Quiz/check completed (e.g. first correct answer)",
+      "requiredFields": ["courseId", "lessonId", "sessionId", "timestamp"],
+      "dataFields": ["checkId", "score", "maxScore"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/completed",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+    },
+    {
+      "name": "interaction",
+      "description": "Custom interaction (branching, UI actions, blocks)",
+      "requiredFields": ["courseId", "sessionId", "timestamp"],
+      "dataFields": ["kind", "blockId", "payload"],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/experienced",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    }
+  ]
+}