@lessonkit/xapi 0.9.2 → 1.0.0

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,21 +29,31 @@ 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;
     }
   };
 }
@@ -118,10 +128,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 }),
         XAPIVerbs.answered,
-        event.timestamp
+        event.timestamp,
+        { result: Object.keys(result).length ? result : void 0 }
       );
     }
     case "quiz_completed": {
@@ -182,6 +197,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 +209,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 +219,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);

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;
     }
   };
 }
@@ -90,10 +100,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": {
@@ -154,6 +169,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 +181,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 +191,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "0.9.2",
+  "version": "1.0.0",
   "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.2"
+    "@lessonkit/core": "1.0.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",