@lessonkit/xapi 0.9.3 → 1.0.1

package/README.md

@@ -1,41 +1,47 @@
-# `@lessonkit/xapi`
+# @lessonkit/xapi
 
-[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/ci.yml)
-[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/)
 [![npm](https://img.shields.io/npm/v/@lessonkit/xapi.svg)](https://www.npmjs.com/package/@lessonkit/xapi)
+[![Documentation](https://readthedocs.org/projects/lessonkit/badge/?version=latest)](https://lessonkit.readthedocs.io/en/latest/reference/xapi.html)
 [![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](https://github.com/eddiethedean/lessonkit/blob/main/LICENSE)
 
-xAPI statement generation primitives.
+xAPI statement generation, in-memory queueing, and telemetry-to-xAPI mapping.
 
-**Docs:** [xAPI reference](https://lessonkit.readthedocs.io/en/latest/reference/xapi.html) · [Telemetry reference](https://lessonkit.readthedocs.io/en/latest/reference/telemetry.html) · [Telemetry & xAPI guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/telemetry-and-xapi.html)
+Requires Node.js **18+**.
 
 ## Install
 
 ```bash
-npm install @lessonkit/xapi
+npm install @lessonkit/xapi @lessonkit/core
 ```
 
-## Quick example
+## Usage
 
-```ts
-import { createXAPIClient } from "@lessonkit/xapi";
+```typescript
+import { createXAPIClient, telemetryEventToXAPIStatement } from "@lessonkit/xapi";
 
 const xapi = createXAPIClient({
-  courseId: "cyber-basics",
-  transport: (statement) => {
-    console.log(statement);
+  courseId: "my-course",
+  transport: async (statement) => {
+    await fetch("/xapi/statements", { method: "POST", body: JSON.stringify(statement) });
   },
 });
 
-xapi.completeLesson({ lessonId: "phishing-101", durationMs: 1500, success: true, score: 7, maxScore: 10 });
+xapi.completeLesson({ lessonId: "lesson-1", durationMs: 1200, success: true });
+await xapi.flush();
 ```
 
-Prefer mapping from telemetry: `telemetryEventToXAPIStatement(event)` (canonical object URNs).
+Map from telemetry events: `telemetryEventToXAPIStatement(event)` — uses canonical LessonKit URNs.
 
-## Notes (0.6.0)
+## Behavior
 
-- `createXAPIClient` requires `courseId` for lifecycle helpers; React uses the mapper after each `track()`.
-- If the transport throws/rejects, statements are queued in-memory.
-- Call `await xapi.flush()` to retry queued statements.
+- No transport → statements queue in memory (dev warns once).
+- Transport failure → re-queue; call `flush()` to retry.
+- Concurrent `flush()` calls are coalesced.
 
-See the [telemetry reference](https://lessonkit.readthedocs.io/en/latest/reference/telemetry.html) and [identity reference](https://lessonkit.readthedocs.io/en/latest/reference/identity.html) for URNs and event mapping.
+## Docs
+
+[xAPI reference](https://lessonkit.readthedocs.io/en/latest/reference/xapi.html) · [Telemetry & xAPI guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/telemetry-and-xapi.html)
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -29,30 +29,41 @@ module.exports = __toCommonJS(index_exports);
 // src/queue.ts
 function createInMemoryXAPIQueue() {
   const buffer = [];
+  let flushInFlight = null;
+  const runFlush = async (transport) => {
+    while (buffer.length) {
+      const statement = buffer[0];
+      try {
+        await transport(statement);
+        buffer.shift();
+      } catch {
+        return;
+      }
+    }
+  };
   return {
     enqueue: (statement) => {
+      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
       buffer.push(statement);
     },
     size: () => buffer.length,
     flush: async (transport) => {
-      while (buffer.length) {
-        const statement = buffer[0];
-        try {
-          await transport(statement);
-          buffer.shift();
-        } catch {
-          return;
-        }
-      }
+      if (flushInFlight) return flushInFlight;
+      if (!buffer.length) return;
+      flushInFlight = runFlush(transport).finally(() => {
+        flushInFlight = null;
+      });
+      return flushInFlight;
     }
   };
 }
 
 // src/client.ts
-var import_core2 = require("@lessonkit/core");
+var import_core3 = require("@lessonkit/core");
 
 // src/telemetryMap.ts
 var import_core = require("@lessonkit/core");
+var import_core2 = require("@lessonkit/core");
 
 // src/id.ts
 function cryptoRandomId() {
@@ -80,13 +91,13 @@ function telemetryEventToXAPIStatement(event) {
   const { courseId } = event;
   switch (event.name) {
     case "course_started":
-      return statementFor((0, import_core.buildLessonkitUrn)({ courseId }), XAPIVerbs.initialized, event.timestamp);
+      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId }), XAPIVerbs.initialized, event.timestamp);
     case "course_completed":
-      return statementFor((0, import_core.buildLessonkitUrn)({ courseId }), XAPIVerbs.completed, event.timestamp);
+      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId }), XAPIVerbs.completed, event.timestamp);
     case "lesson_started": {
       const lessonId = event.lessonId;
       return statementFor(
-        (0, import_core.buildLessonkitUrn)({ courseId, lessonId }),
+        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId }),
         XAPIVerbs.initialized,
         event.timestamp
       );
@@ -109,7 +120,7 @@ function telemetryEventToXAPIStatement(event) {
           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, {
+      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId, lessonId }), XAPIVerbs.completed, event.timestamp, {
         result: Object.keys(result).length ? result : void 0
       });
     }
@@ -118,10 +129,15 @@ function telemetryEventToXAPIStatement(event) {
     case "quiz_answered": {
       const lessonId = event.lessonId;
       const checkId = event.data.checkId;
+      const result = {};
+      if (typeof event.data.correct === "boolean") {
+        result.success = event.data.correct;
+      }
       return statementFor(
-        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, checkId }),
+        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
         XAPIVerbs.answered,
-        event.timestamp
+        event.timestamp,
+        { result: Object.keys(result).length ? result : void 0 }
       );
     }
     case "quiz_completed": {
@@ -140,7 +156,7 @@ function telemetryEventToXAPIStatement(event) {
         };
       }
       return statementFor(
-        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, checkId }),
+        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
         XAPIVerbs.completed,
         event.timestamp,
         { result: Object.keys(result).length ? result : void 0 }
@@ -151,13 +167,13 @@ function telemetryEventToXAPIStatement(event) {
       const blockId = event.data?.blockId;
       if (!lessonId || !blockId) return null;
       return statementFor(
-        (0, import_core.buildLessonkitUrn)({ courseId, lessonId, blockId }),
+        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, blockId }),
         XAPIVerbs.experienced,
         event.timestamp
       );
     }
     default:
-      return null;
+      return (0, import_core.assertNever)(event, "Unhandled telemetry event");
   }
 }
 function statementFor(objectId, verb, timestamp, extra) {
@@ -182,6 +198,7 @@ function createXAPIClient(opts) {
   const queue = opts?.queue ?? createInMemoryXAPIQueue();
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
+  const inflightById = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
     if (!transport) {
       queue.enqueue(statement);
@@ -193,7 +210,9 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    void Promise.resolve().then(() => transport(statement)).catch(() => {
+    const existing = inflightById.get(statement.id);
+    if (existing) return;
+    const flight = Promise.resolve().then(() => transport(statement)).catch(() => {
       queue.enqueue(statement);
       if (isDevEnvironment() && !warnedTransportFailure) {
         warnedTransportFailure = true;
@@ -201,7 +220,11 @@ function createXAPIClient(opts) {
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
         );
       }
+    }).finally(() => {
+      inflightById.delete(statement.id);
     });
+    inflightById.set(statement.id, flight);
+    void flight;
   };
   const emit = (event) => {
     const statement = telemetryEventToXAPIStatement(event);
@@ -215,12 +238,16 @@ function createXAPIClient(opts) {
     flush: async () => {
       if (!transport) return;
       await queue.flush(transport);
+      const flights = [...inflightById.values()];
+      if (flights.length > 0) {
+        await Promise.allSettled(flights);
+      }
     },
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;
       emit({
         name: "lesson_started",
-        timestamp: (0, import_core2.nowIso)(),
+        timestamp: (0, import_core3.nowIso)(),
         courseId,
         lessonId,
         data: { lessonId }
@@ -236,7 +263,7 @@ function createXAPIClient(opts) {
       if (!courseId) return;
       emit({
         name: "lesson_completed",
-        timestamp: (0, import_core2.nowIso)(),
+        timestamp: (0, import_core3.nowIso)(),
         courseId,
         lessonId,
         data: { lessonId, durationMs, score, maxScore, success }
@@ -246,7 +273,7 @@ function createXAPIClient(opts) {
       if (!courseId) return;
       emit({
         name: "course_completed",
-        timestamp: (0, import_core2.nowIso)(),
+        timestamp: (0, import_core3.nowIso)(),
         courseId
       });
     }

package/dist/index.d.cts

@@ -1,14 +1,32 @@
 import { LessonId, CourseId, TelemetryEvent } from '@lessonkit/core';
 
+type XAPIVerbIri = "http://adlnet.gov/expapi/verbs/initialized" | "http://adlnet.gov/expapi/verbs/completed" | "http://adlnet.gov/expapi/verbs/answered" | "http://adlnet.gov/expapi/verbs/experienced";
+type XAPIScore = {
+    raw?: number;
+    max?: number;
+    min?: number;
+    scaled?: number;
+};
+type XAPIResult = {
+    duration?: string;
+    success?: boolean;
+    score?: XAPIScore;
+    completion?: boolean;
+};
+type XAPIObjectDefinition = {
+    name?: Record<string, string>;
+    description?: Record<string, string>;
+    type?: string;
+};
 type XAPIStatement = {
     id: string;
     timestamp: string;
-    verb: string;
+    verb: XAPIVerbIri;
     object: {
         id: string;
-        definition?: Record<string, unknown>;
+        definition?: XAPIObjectDefinition;
     };
-    result?: Record<string, unknown>;
+    result?: XAPIResult;
     context?: Record<string, unknown>;
 };
 type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
@@ -48,4 +66,4 @@ declare function createXAPIClient(opts?: {
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.d.ts

@@ -1,14 +1,32 @@
 import { LessonId, CourseId, TelemetryEvent } from '@lessonkit/core';
 
+type XAPIVerbIri = "http://adlnet.gov/expapi/verbs/initialized" | "http://adlnet.gov/expapi/verbs/completed" | "http://adlnet.gov/expapi/verbs/answered" | "http://adlnet.gov/expapi/verbs/experienced";
+type XAPIScore = {
+    raw?: number;
+    max?: number;
+    min?: number;
+    scaled?: number;
+};
+type XAPIResult = {
+    duration?: string;
+    success?: boolean;
+    score?: XAPIScore;
+    completion?: boolean;
+};
+type XAPIObjectDefinition = {
+    name?: Record<string, string>;
+    description?: Record<string, string>;
+    type?: string;
+};
 type XAPIStatement = {
     id: string;
     timestamp: string;
-    verb: string;
+    verb: XAPIVerbIri;
     object: {
         id: string;
-        definition?: Record<string, unknown>;
+        definition?: XAPIObjectDefinition;
     };
-    result?: Record<string, unknown>;
+    result?: XAPIResult;
     context?: Record<string, unknown>;
 };
 type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
@@ -48,4 +66,4 @@ declare function createXAPIClient(opts?: {
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.js

@@ -1,21 +1,31 @@
 // src/queue.ts
 function createInMemoryXAPIQueue() {
   const buffer = [];
+  let flushInFlight = null;
+  const runFlush = async (transport) => {
+    while (buffer.length) {
+      const statement = buffer[0];
+      try {
+        await transport(statement);
+        buffer.shift();
+      } catch {
+        return;
+      }
+    }
+  };
   return {
     enqueue: (statement) => {
+      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
       buffer.push(statement);
     },
     size: () => buffer.length,
     flush: async (transport) => {
-      while (buffer.length) {
-        const statement = buffer[0];
-        try {
-          await transport(statement);
-          buffer.shift();
-        } catch {
-          return;
-        }
-      }
+      if (flushInFlight) return flushInFlight;
+      if (!buffer.length) return;
+      flushInFlight = runFlush(transport).finally(() => {
+        flushInFlight = null;
+      });
+      return flushInFlight;
     }
   };
 }
@@ -24,6 +34,7 @@ function createInMemoryXAPIQueue() {
 import { nowIso } from "@lessonkit/core";
 
 // src/telemetryMap.ts
+import { assertNever } from "@lessonkit/core";
 import { buildLessonkitUrn } from "@lessonkit/core";
 
 // src/id.ts
@@ -90,10 +101,15 @@ function telemetryEventToXAPIStatement(event) {
     case "quiz_answered": {
       const lessonId = event.lessonId;
       const checkId = event.data.checkId;
+      const result = {};
+      if (typeof event.data.correct === "boolean") {
+        result.success = event.data.correct;
+      }
       return statementFor(
         buildLessonkitUrn({ courseId, lessonId, checkId }),
         XAPIVerbs.answered,
-        event.timestamp
+        event.timestamp,
+        { result: Object.keys(result).length ? result : void 0 }
       );
     }
     case "quiz_completed": {
@@ -129,7 +145,7 @@ function telemetryEventToXAPIStatement(event) {
       );
     }
     default:
-      return null;
+      return assertNever(event, "Unhandled telemetry event");
   }
 }
 function statementFor(objectId, verb, timestamp, extra) {
@@ -154,6 +170,7 @@ function createXAPIClient(opts) {
   const queue = opts?.queue ?? createInMemoryXAPIQueue();
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
+  const inflightById = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
     if (!transport) {
       queue.enqueue(statement);
@@ -165,7 +182,9 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    void Promise.resolve().then(() => transport(statement)).catch(() => {
+    const existing = inflightById.get(statement.id);
+    if (existing) return;
+    const flight = Promise.resolve().then(() => transport(statement)).catch(() => {
       queue.enqueue(statement);
       if (isDevEnvironment() && !warnedTransportFailure) {
         warnedTransportFailure = true;
@@ -173,7 +192,11 @@ function createXAPIClient(opts) {
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
         );
       }
+    }).finally(() => {
+      inflightById.delete(statement.id);
     });
+    inflightById.set(statement.id, flight);
+    void flight;
   };
   const emit = (event) => {
     const statement = telemetryEventToXAPIStatement(event);
@@ -187,6 +210,10 @@ function createXAPIClient(opts) {
     flush: async () => {
       if (!transport) return;
       await queue.flush(transport);
+      const flights = [...inflightById.values()];
+      if (flights.length > 0) {
+        await Promise.allSettled(flights);
+      }
     },
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "0.9.3",
+  "version": "1.0.1",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -21,6 +21,9 @@
     "training",
     "lrs"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -45,7 +48,7 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "0.9.3"
+    "@lessonkit/core": "1.0.1"
   },
   "devDependencies": {
     "tsup": "^8.5.0",