@lessonkit/xapi 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -26,35 +26,64 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/id.ts
+function cryptoRandomId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
 // src/queue.ts
+function withStatementId(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 function createInMemoryXAPIQueue(opts) {
   const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  let headInFlight = false;
   const notifyDepth = () => {
     opts?.onDepth?.(buffer.length);
   };
   const runFlush = async (transport) => {
     while (buffer.length) {
       const statement = buffer[0];
+      headInFlight = true;
       try {
         await transport(statement);
         buffer.shift();
         notifyDepth();
       } catch {
         return;
+      } finally {
+        headInFlight = false;
       }
     }
   };
   return {
     enqueue: (statement) => {
-      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      const normalized = withStatementId(statement);
+      if (buffer.some((s) => s.id === normalized.id)) return;
       if (buffer.length >= maxSize) {
-        buffer.shift();
+        if (headInFlight && buffer.length <= 1) {
+          opts?.onCap?.();
+          return;
+        }
+        if (headInFlight) {
+          buffer.splice(1, 1);
+        } else {
+          buffer.shift();
+        }
         opts?.onCap?.();
       }
-      buffer.push(statement);
+      buffer.push(normalized);
       notifyDepth();
     },
     size: () => buffer.length,
@@ -75,16 +104,10 @@ var import_core2 = require("@lessonkit/core");
 // src/telemetryMap.ts
 var import_core = require("@lessonkit/core");
 
-// src/id.ts
-function cryptoRandomId() {
-  const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
-}
-
 // src/duration.ts
 function formatDurationMs(ms) {
-  const safe = Math.max(0, ms);
+  if (!Number.isFinite(ms) || ms < 0) return void 0;
+  const safe = ms;
   const seconds = safe / 1e3;
   const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
   return `PT${fixed}S`;
@@ -101,12 +124,18 @@ function buildXapiScoreResult(opts) {
   const max = typeof opts.maxScore === "number" ? opts.maxScore : void 0;
   const raw = typeof opts.score === "number" ? opts.score : void 0;
   if (typeof raw !== "number" && typeof max !== "number") return void 0;
-  return {
-    raw,
-    max,
-    min: 0,
-    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-  };
+  if (typeof raw === "number" && !Number.isFinite(raw) || typeof max === "number" && !Number.isFinite(max)) {
+    return void 0;
+  }
+  if (typeof max === "number" && max <= 0) return void 0;
+  if (typeof raw === "number" && raw < 0) return void 0;
+  const result = { min: 0 };
+  if (typeof raw === "number") result.raw = raw;
+  if (typeof max === "number") result.max = max;
+  if (typeof raw === "number" && typeof max === "number" && max > 0 && raw <= max) {
+    result.scaled = raw / max;
+  }
+  return result;
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -129,7 +158,7 @@ var experiencedBlockMapper = (event, ctx) => {
   if (event.name === "interaction") {
     const lessonId2 = event.lessonId;
     const blockId2 = event.data?.blockId;
-    if (!lessonId2 || !blockId2) return null;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
     return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
   }
   const lessonId = event.lessonId;
@@ -155,7 +184,8 @@ var TELEMETRY_XAPI_MAPPERS = {
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
-      result.duration = formatDurationMs(data.durationMs);
+      const duration = formatDurationMs(data.durationMs);
+      if (duration !== void 0) result.duration = duration;
     }
     if (typeof data?.success === "boolean") result.success = data.success;
     const score = buildXapiScoreResult({ score: data?.score, maxScore: data?.maxScore });
@@ -209,6 +239,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   },
   interaction: experiencedBlockMapper,
   book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
   compound_page_viewed: experiencedBlockMapper,
   hotspot_opened: experiencedBlockMapper,
   accordion_section_toggled: experiencedBlockMapper,
@@ -227,6 +258,15 @@ function telemetryEventToXAPIStatement(event) {
 }
 
 // src/client.ts
+function withStatementId2(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
@@ -243,8 +283,9 @@ function createXAPIClient(opts) {
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
+    const normalized = withStatementId2(statement);
     if (!transport) {
-      queue.enqueue(statement);
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
@@ -253,35 +294,45 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    const existing = inflightById.get(statement.id);
+    const existing = inflightById.get(normalized.id);
     if (existing) {
       void existing.then(
         () => void 0,
         () => {
-          sendOrQueue(statement);
+          sendOrQueue(normalized);
         }
       );
       return;
     }
-    const transportFlight = Promise.resolve().then(() => transport(statement));
-    const flight = transportFlight.catch(() => {
-      queue.enqueue(statement);
+    const flight = Promise.resolve().then(() => transport(normalized)).catch(() => {
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedTransportFailure) {
         warnedTransportFailure = true;
         console.warn(
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
         );
       }
+      throw new Error("xAPI transport failed");
     }).finally(() => {
-      inflightById.delete(statement.id);
+      inflightById.delete(normalized.id);
+    });
+    inflightById.set(normalized.id, flight);
+    void flight.catch(() => {
     });
-    inflightById.set(statement.id, transportFlight);
-    void flight;
   };
   const emit = (event) => {
-    const statement = telemetryEventToXAPIStatement(event);
-    if (!statement) return;
-    sendOrQueue(statement);
+    try {
+      const statement = telemetryEventToXAPIStatement(event);
+      if (!statement) return;
+      sendOrQueue(statement);
+    } catch (err) {
+      if (isDevEnvironment()) {
+        console.warn(
+          "[lessonkit] xAPI mapping skipped:",
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
   };
   return {
     send: (statement) => {

package/dist/index.js

@@ -1,32 +1,61 @@
+// src/id.ts
+function cryptoRandomId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
 // src/queue.ts
+function withStatementId(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 function createInMemoryXAPIQueue(opts) {
   const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  let headInFlight = false;
   const notifyDepth = () => {
     opts?.onDepth?.(buffer.length);
   };
   const runFlush = async (transport) => {
     while (buffer.length) {
       const statement = buffer[0];
+      headInFlight = true;
       try {
         await transport(statement);
         buffer.shift();
         notifyDepth();
       } catch {
         return;
+      } finally {
+        headInFlight = false;
       }
     }
   };
   return {
     enqueue: (statement) => {
-      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      const normalized = withStatementId(statement);
+      if (buffer.some((s) => s.id === normalized.id)) return;
       if (buffer.length >= maxSize) {
-        buffer.shift();
+        if (headInFlight && buffer.length <= 1) {
+          opts?.onCap?.();
+          return;
+        }
+        if (headInFlight) {
+          buffer.splice(1, 1);
+        } else {
+          buffer.shift();
+        }
         opts?.onCap?.();
       }
-      buffer.push(statement);
+      buffer.push(normalized);
       notifyDepth();
     },
     size: () => buffer.length,
@@ -47,16 +76,10 @@ import { nowIso } from "@lessonkit/core";
 // src/telemetryMap.ts
 import { buildLessonkitUrn } from "@lessonkit/core";
 
-// src/id.ts
-function cryptoRandomId() {
-  const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
-}
-
 // src/duration.ts
 function formatDurationMs(ms) {
-  const safe = Math.max(0, ms);
+  if (!Number.isFinite(ms) || ms < 0) return void 0;
+  const safe = ms;
   const seconds = safe / 1e3;
   const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
   return `PT${fixed}S`;
@@ -73,12 +96,18 @@ function buildXapiScoreResult(opts) {
   const max = typeof opts.maxScore === "number" ? opts.maxScore : void 0;
   const raw = typeof opts.score === "number" ? opts.score : void 0;
   if (typeof raw !== "number" && typeof max !== "number") return void 0;
-  return {
-    raw,
-    max,
-    min: 0,
-    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-  };
+  if (typeof raw === "number" && !Number.isFinite(raw) || typeof max === "number" && !Number.isFinite(max)) {
+    return void 0;
+  }
+  if (typeof max === "number" && max <= 0) return void 0;
+  if (typeof raw === "number" && raw < 0) return void 0;
+  const result = { min: 0 };
+  if (typeof raw === "number") result.raw = raw;
+  if (typeof max === "number") result.max = max;
+  if (typeof raw === "number" && typeof max === "number" && max > 0 && raw <= max) {
+    result.scaled = raw / max;
+  }
+  return result;
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -101,7 +130,7 @@ var experiencedBlockMapper = (event, ctx) => {
   if (event.name === "interaction") {
     const lessonId2 = event.lessonId;
     const blockId2 = event.data?.blockId;
-    if (!lessonId2 || !blockId2) return null;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
     return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
   }
   const lessonId = event.lessonId;
@@ -127,7 +156,8 @@ var TELEMETRY_XAPI_MAPPERS = {
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
-      result.duration = formatDurationMs(data.durationMs);
+      const duration = formatDurationMs(data.durationMs);
+      if (duration !== void 0) result.duration = duration;
     }
     if (typeof data?.success === "boolean") result.success = data.success;
     const score = buildXapiScoreResult({ score: data?.score, maxScore: data?.maxScore });
@@ -181,6 +211,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   },
   interaction: experiencedBlockMapper,
   book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
   compound_page_viewed: experiencedBlockMapper,
   hotspot_opened: experiencedBlockMapper,
   accordion_section_toggled: experiencedBlockMapper,
@@ -199,6 +230,15 @@ function telemetryEventToXAPIStatement(event) {
 }
 
 // src/client.ts
+function withStatementId2(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
@@ -215,8 +255,9 @@ function createXAPIClient(opts) {
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
+    const normalized = withStatementId2(statement);
     if (!transport) {
-      queue.enqueue(statement);
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
@@ -225,35 +266,45 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    const existing = inflightById.get(statement.id);
+    const existing = inflightById.get(normalized.id);
     if (existing) {
       void existing.then(
         () => void 0,
         () => {
-          sendOrQueue(statement);
+          sendOrQueue(normalized);
         }
       );
       return;
     }
-    const transportFlight = Promise.resolve().then(() => transport(statement));
-    const flight = transportFlight.catch(() => {
-      queue.enqueue(statement);
+    const flight = Promise.resolve().then(() => transport(normalized)).catch(() => {
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedTransportFailure) {
         warnedTransportFailure = true;
         console.warn(
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
         );
       }
+      throw new Error("xAPI transport failed");
     }).finally(() => {
-      inflightById.delete(statement.id);
+      inflightById.delete(normalized.id);
+    });
+    inflightById.set(normalized.id, flight);
+    void flight.catch(() => {
     });
-    inflightById.set(statement.id, transportFlight);
-    void flight;
   };
   const emit = (event) => {
-    const statement = telemetryEventToXAPIStatement(event);
-    if (!statement) return;
-    sendOrQueue(statement);
+    try {
+      const statement = telemetryEventToXAPIStatement(event);
+      if (!statement) return;
+      sendOrQueue(statement);
+    } catch (err) {
+      if (isDevEnvironment()) {
+        console.warn(
+          "[lessonkit] xAPI mapping skipped:",
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
   };
   return {
     send: (statement) => {

package/package.json

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