@lessonkit/xapi 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # `@lessonkit/xapi`
 
-[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml)
+[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@lessonkit/xapi.svg)](https://www.npmjs.com/package/@lessonkit/xapi)
 [![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](../../LICENSE)
 
@@ -18,8 +18,8 @@ npm install @lessonkit/xapi
 import { createXAPIClient } from "@lessonkit/xapi";
 
 const xapi = createXAPIClient({
+  courseId: "cyber-basics",
   transport: (statement) => {
-    // Send to your LRS (or queue offline).
     console.log(statement);
   },
 });
@@ -27,8 +27,13 @@ const xapi = createXAPIClient({
 xapi.completeLesson({ lessonId: "phishing-101", durationMs: 1500, success: true, score: 7, maxScore: 10 });
 ```
 
-## Notes (0.4.0)
+Prefer mapping from telemetry: `telemetryEventToXAPIStatement(event)` (canonical object URNs).
 
+## Notes (0.6.0)
+
+- `createXAPIClient` requires `courseId` for lifecycle helpers; React uses the mapper after each `track()`.
 - If the transport throws/rejects, statements are queued in-memory.
-- You can call `await xapi.flush()` to retry queued statements.
+- Call `await xapi.flush()` to retry queued statements.
+
+See [`docs/TELEMETRY.md`](../../docs/TELEMETRY.md).
 

package/dist/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createInMemoryXAPIQueue: () => createInMemoryXAPIQueue,
-  createXAPIClient: () => createXAPIClient
+  createXAPIClient: () => createXAPIClient,
+  telemetryEventToXAPIStatement: () => telemetryEventToXAPIStatement
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -48,6 +49,9 @@ function createInMemoryXAPIQueue() {
 }
 
 // src/client.ts
+var import_core2 = require("@lessonkit/core");
+
+// src/telemetryMap.ts
 var import_core = require("@lessonkit/core");
 
 // src/id.ts
@@ -65,24 +69,144 @@ function formatDurationMs(ms) {
   return `PT${fixed}S`;
 }
 
-// src/client.ts
+// src/telemetryMap.ts
 var XAPIVerbs = {
-  started: "http://adlnet.gov/expapi/verbs/initialized",
-  completed: "http://adlnet.gov/expapi/verbs/completed"
+  initialized: "http://adlnet.gov/expapi/verbs/initialized",
+  completed: "http://adlnet.gov/expapi/verbs/completed",
+  answered: "http://adlnet.gov/expapi/verbs/answered",
+  experienced: "http://adlnet.gov/expapi/verbs/experienced"
 };
+function telemetryEventToXAPIStatement(event) {
+  const { courseId } = event;
+  switch (event.name) {
+    case "course_started":
+      return statementFor((0, import_core.buildLessonkitUrn)({ courseId }), XAPIVerbs.initialized, event.timestamp);
+    case "course_completed":
+      return statementFor((0, import_core.buildLessonkitUrn)({ courseId }), XAPIVerbs.completed, event.timestamp);
+    case "lesson_started": {
+      const lessonId = event.lessonId;
+      return statementFor(
+        (0, import_core.buildLessonkitUrn)({ courseId, lessonId }),
+        XAPIVerbs.initialized,
+        event.timestamp
+      );
+    }
+    case "lesson_completed": {
+      const lessonId = event.lessonId;
+      const data = event.data;
+      const result = {};
+      if (typeof data?.durationMs === "number") {
+        result.duration = formatDurationMs(data.durationMs);
+      }
+      if (typeof data?.success === "boolean") result.success = data.success;
+      if (typeof data?.score === "number" || typeof data?.maxScore === "number") {
+        const max = typeof data.maxScore === "number" ? data.maxScore : void 0;
+        const raw = typeof data.score === "number" ? data.score : void 0;
+        result.score = {
+          raw,
+          max,
+          min: 0,
+          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+        };
+      }
+      return statementFor((0, import_core.buildLessonkitUrn)({ courseId, lessonId }), XAPIVerbs.completed, event.timestamp, {
+        result: Object.keys(result).length ? result : void 0
+      });
+    }
+    case "lesson_time_on_task":
+      return null;
+    case "quiz_answered": {
+      const lessonId = event.lessonId;
+      const checkId = event.data.checkId;
+      return statementFor(
+        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, checkId }),
+        XAPIVerbs.answered,
+        event.timestamp
+      );
+    }
+    case "quiz_completed": {
+      const lessonId = event.lessonId;
+      const checkId = event.data.checkId;
+      const { score, maxScore } = event.data;
+      const result = {};
+      if (typeof score === "number" || typeof maxScore === "number") {
+        const max = typeof maxScore === "number" ? maxScore : void 0;
+        const raw = typeof score === "number" ? score : void 0;
+        result.score = {
+          raw,
+          max,
+          min: 0,
+          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+        };
+      }
+      return statementFor(
+        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, checkId }),
+        XAPIVerbs.completed,
+        event.timestamp,
+        { result: Object.keys(result).length ? result : void 0 }
+      );
+    }
+    case "interaction": {
+      const lessonId = event.lessonId;
+      const blockId = event.data?.blockId;
+      if (!lessonId || !blockId) return null;
+      return statementFor(
+        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, blockId }),
+        XAPIVerbs.experienced,
+        event.timestamp
+      );
+    }
+    default:
+      return null;
+  }
+}
+function statementFor(objectId, verb, timestamp, extra) {
+  return {
+    id: cryptoRandomId(),
+    timestamp,
+    verb,
+    object: { id: objectId },
+    result: extra?.result,
+    context: extra?.context
+  };
+}
+
+// src/client.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
 function createXAPIClient(opts) {
   const transport = opts?.transport;
-  const baseId = opts?.baseId ?? "urn:lessonkit";
+  const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue();
+  let warnedNoTransport = false;
+  let warnedTransportFailure = false;
   const sendOrQueue = (statement) => {
     if (!transport) {
       queue.enqueue(statement);
+      if (isDevEnvironment() && !warnedNoTransport) {
+        warnedNoTransport = true;
+        console.warn(
+          "[lessonkit] xAPI statements are queued but no transport is configured; pass config.xapi.transport or config.xapi.client"
+        );
+      }
       return;
     }
     void Promise.resolve().then(() => transport(statement)).catch(() => {
       queue.enqueue(statement);
+      if (isDevEnvironment() && !warnedTransportFailure) {
+        warnedTransportFailure = true;
+        console.warn(
+          "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
+        );
+      }
     });
   };
+  const emit = (event) => {
+    const statement = telemetryEventToXAPIStatement(event);
+    if (statement) sendOrQueue(statement);
+  };
   return {
     send: (statement) => {
       sendOrQueue(statement);
@@ -93,46 +217,44 @@ function createXAPIClient(opts) {
       await queue.flush(transport);
     },
     startedLesson: ({ lessonId }) => {
-      const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.started);
-      sendOrQueue(statement);
+      if (!courseId) return;
+      emit({
+        name: "lesson_started",
+        timestamp: (0, import_core2.nowIso)(),
+        courseId,
+        lessonId,
+        data: { lessonId }
+      });
     },
-    completeLesson: ({ lessonId, durationMs, score, maxScore, success }) => {
-      const result = {};
-      if (typeof durationMs === "number") result.duration = formatDurationMs(durationMs);
-      if (typeof success === "boolean") result.success = success;
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.completed, {
-        result: Object.keys(result).length ? result : void 0
+    completeLesson: ({
+      lessonId,
+      durationMs,
+      score,
+      maxScore,
+      success
+    }) => {
+      if (!courseId) return;
+      emit({
+        name: "lesson_completed",
+        timestamp: (0, import_core2.nowIso)(),
+        courseId,
+        lessonId,
+        data: { lessonId, durationMs, score, maxScore, success }
       });
-      sendOrQueue(statement);
     },
     completeCourse: () => {
-      const statement = statementFor(`${baseId}:course`, XAPIVerbs.completed);
-      sendOrQueue(statement);
+      if (!courseId) return;
+      emit({
+        name: "course_completed",
+        timestamp: (0, import_core2.nowIso)(),
+        courseId
+      });
     }
   };
 }
-function statementFor(objectId, verb, extra) {
-  return {
-    id: cryptoRandomId(),
-    timestamp: (0, import_core.nowIso)(),
-    verb,
-    object: { id: objectId },
-    result: extra?.result,
-    context: extra?.context
-  };
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createInMemoryXAPIQueue,
-  createXAPIClient
+  createXAPIClient,
+  telemetryEventToXAPIStatement
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { LessonId } from '@lessonkit/core';
+import { LessonId, CourseId, TelemetryEvent } from '@lessonkit/core';
 
 type XAPIStatement = {
     id: string;
@@ -38,8 +38,14 @@ declare function createInMemoryXAPIQueue(): XAPIQueue;
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
-    baseId?: string;
+    courseId?: CourseId;
     queue?: XAPIQueue;
 }): XAPIClient;
 
-export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient };
+/**
+ * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
+ * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
+ */
+declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
+
+export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LessonId } from '@lessonkit/core';
+import { LessonId, CourseId, TelemetryEvent } from '@lessonkit/core';
 
 type XAPIStatement = {
     id: string;
@@ -38,8 +38,14 @@ declare function createInMemoryXAPIQueue(): XAPIQueue;
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
-    baseId?: string;
+    courseId?: CourseId;
     queue?: XAPIQueue;
 }): XAPIClient;
 
-export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient };
+/**
+ * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
+ * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
+ */
+declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
+
+export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.js

@@ -23,6 +23,9 @@ function createInMemoryXAPIQueue() {
 // src/client.ts
 import { nowIso } from "@lessonkit/core";
 
+// src/telemetryMap.ts
+import { buildLessonkitUrn } from "@lessonkit/core";
+
 // src/id.ts
 function cryptoRandomId() {
   const g = globalThis;
@@ -38,24 +41,144 @@ function formatDurationMs(ms) {
   return `PT${fixed}S`;
 }
 
-// src/client.ts
+// src/telemetryMap.ts
 var XAPIVerbs = {
-  started: "http://adlnet.gov/expapi/verbs/initialized",
-  completed: "http://adlnet.gov/expapi/verbs/completed"
+  initialized: "http://adlnet.gov/expapi/verbs/initialized",
+  completed: "http://adlnet.gov/expapi/verbs/completed",
+  answered: "http://adlnet.gov/expapi/verbs/answered",
+  experienced: "http://adlnet.gov/expapi/verbs/experienced"
 };
+function telemetryEventToXAPIStatement(event) {
+  const { courseId } = event;
+  switch (event.name) {
+    case "course_started":
+      return statementFor(buildLessonkitUrn({ courseId }), XAPIVerbs.initialized, event.timestamp);
+    case "course_completed":
+      return statementFor(buildLessonkitUrn({ courseId }), XAPIVerbs.completed, event.timestamp);
+    case "lesson_started": {
+      const lessonId = event.lessonId;
+      return statementFor(
+        buildLessonkitUrn({ courseId, lessonId }),
+        XAPIVerbs.initialized,
+        event.timestamp
+      );
+    }
+    case "lesson_completed": {
+      const lessonId = event.lessonId;
+      const data = event.data;
+      const result = {};
+      if (typeof data?.durationMs === "number") {
+        result.duration = formatDurationMs(data.durationMs);
+      }
+      if (typeof data?.success === "boolean") result.success = data.success;
+      if (typeof data?.score === "number" || typeof data?.maxScore === "number") {
+        const max = typeof data.maxScore === "number" ? data.maxScore : void 0;
+        const raw = typeof data.score === "number" ? data.score : void 0;
+        result.score = {
+          raw,
+          max,
+          min: 0,
+          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+        };
+      }
+      return statementFor(buildLessonkitUrn({ courseId, lessonId }), XAPIVerbs.completed, event.timestamp, {
+        result: Object.keys(result).length ? result : void 0
+      });
+    }
+    case "lesson_time_on_task":
+      return null;
+    case "quiz_answered": {
+      const lessonId = event.lessonId;
+      const checkId = event.data.checkId;
+      return statementFor(
+        buildLessonkitUrn({ courseId, lessonId, checkId }),
+        XAPIVerbs.answered,
+        event.timestamp
+      );
+    }
+    case "quiz_completed": {
+      const lessonId = event.lessonId;
+      const checkId = event.data.checkId;
+      const { score, maxScore } = event.data;
+      const result = {};
+      if (typeof score === "number" || typeof maxScore === "number") {
+        const max = typeof maxScore === "number" ? maxScore : void 0;
+        const raw = typeof score === "number" ? score : void 0;
+        result.score = {
+          raw,
+          max,
+          min: 0,
+          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+        };
+      }
+      return statementFor(
+        buildLessonkitUrn({ courseId, lessonId, checkId }),
+        XAPIVerbs.completed,
+        event.timestamp,
+        { result: Object.keys(result).length ? result : void 0 }
+      );
+    }
+    case "interaction": {
+      const lessonId = event.lessonId;
+      const blockId = event.data?.blockId;
+      if (!lessonId || !blockId) return null;
+      return statementFor(
+        buildLessonkitUrn({ courseId, lessonId, blockId }),
+        XAPIVerbs.experienced,
+        event.timestamp
+      );
+    }
+    default:
+      return null;
+  }
+}
+function statementFor(objectId, verb, timestamp, extra) {
+  return {
+    id: cryptoRandomId(),
+    timestamp,
+    verb,
+    object: { id: objectId },
+    result: extra?.result,
+    context: extra?.context
+  };
+}
+
+// src/client.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
 function createXAPIClient(opts) {
   const transport = opts?.transport;
-  const baseId = opts?.baseId ?? "urn:lessonkit";
+  const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue();
+  let warnedNoTransport = false;
+  let warnedTransportFailure = false;
   const sendOrQueue = (statement) => {
     if (!transport) {
       queue.enqueue(statement);
+      if (isDevEnvironment() && !warnedNoTransport) {
+        warnedNoTransport = true;
+        console.warn(
+          "[lessonkit] xAPI statements are queued but no transport is configured; pass config.xapi.transport or config.xapi.client"
+        );
+      }
       return;
     }
     void Promise.resolve().then(() => transport(statement)).catch(() => {
       queue.enqueue(statement);
+      if (isDevEnvironment() && !warnedTransportFailure) {
+        warnedTransportFailure = true;
+        console.warn(
+          "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
+        );
+      }
     });
   };
+  const emit = (event) => {
+    const statement = telemetryEventToXAPIStatement(event);
+    if (statement) sendOrQueue(statement);
+  };
   return {
     send: (statement) => {
       sendOrQueue(statement);
@@ -66,45 +189,43 @@ function createXAPIClient(opts) {
       await queue.flush(transport);
     },
     startedLesson: ({ lessonId }) => {
-      const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.started);
-      sendOrQueue(statement);
+      if (!courseId) return;
+      emit({
+        name: "lesson_started",
+        timestamp: nowIso(),
+        courseId,
+        lessonId,
+        data: { lessonId }
+      });
     },
-    completeLesson: ({ lessonId, durationMs, score, maxScore, success }) => {
-      const result = {};
-      if (typeof durationMs === "number") result.duration = formatDurationMs(durationMs);
-      if (typeof success === "boolean") result.success = success;
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.completed, {
-        result: Object.keys(result).length ? result : void 0
+    completeLesson: ({
+      lessonId,
+      durationMs,
+      score,
+      maxScore,
+      success
+    }) => {
+      if (!courseId) return;
+      emit({
+        name: "lesson_completed",
+        timestamp: nowIso(),
+        courseId,
+        lessonId,
+        data: { lessonId, durationMs, score, maxScore, success }
       });
-      sendOrQueue(statement);
     },
     completeCourse: () => {
-      const statement = statementFor(`${baseId}:course`, XAPIVerbs.completed);
-      sendOrQueue(statement);
+      if (!courseId) return;
+      emit({
+        name: "course_completed",
+        timestamp: nowIso(),
+        courseId
+      });
     }
   };
 }
-function statementFor(objectId, verb, extra) {
-  return {
-    id: cryptoRandomId(),
-    timestamp: nowIso(),
-    verb,
-    object: { id: objectId },
-    result: extra?.result,
-    context: extra?.context
-  };
-}
 export {
   createInMemoryXAPIQueue,
-  createXAPIClient
+  createXAPIClient,
+  telemetryEventToXAPIStatement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -45,7 +45,7 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "0.4.0"
+    "@lessonkit/core": "0.6.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",