@lessonkit/xapi 1.5.0 → 1.6.0

package/dist/index.cjs

@@ -218,16 +218,20 @@ function createInMemoryXAPIQueue(opts) {
       if (buffer.length >= maxSize) {
         if (headInFlight) {
           if (buffer.length > 1) {
+            const evicted = buffer[1];
             buffer.splice(1, 1);
             opts?.onCap?.();
+            opts?.onOverflow?.(evicted);
           } else {
             opts?.onCap?.();
             opts?.onOverflow?.(normalized);
             return;
           }
         } else {
+          const evicted = buffer[0];
           buffer.shift();
           opts?.onCap?.();
+          opts?.onOverflow?.(evicted);
         }
       }
       buffer.push(normalized);
@@ -244,7 +248,9 @@ function createInMemoryXAPIQueue(opts) {
       return flushInFlight;
     },
     flushOnExit: (exitTransport) => {
+      const skipId = headInFlightId;
       for (const statement of buffer) {
+        if (statement.id === skipId) continue;
         try {
           exitTransport(statement);
         } catch {
@@ -286,13 +292,17 @@ function loadDeadLetterStatements() {
     return [];
   }
 }
-function persistDeadLetterStatement(statement) {
+function persistDeadLetterStatement(statement, opts) {
   const storage = readStorage();
   if (!storage) return;
   try {
     const existing = loadDeadLetterStatements();
     if (existing.some((s) => s.id === statement.id)) return;
-    const next = [...existing, statement].slice(-MAX_DEAD_LETTER);
+    const combined = [...existing, statement];
+    if (combined.length > MAX_DEAD_LETTER) {
+      opts?.onTruncated?.(combined.length - MAX_DEAD_LETTER);
+    }
+    const next = combined.slice(-MAX_DEAD_LETTER);
     storage.setItem(STORAGE_KEY, JSON.stringify(next));
   } catch {
   }
@@ -426,6 +436,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   lesson_completed: (event, ctx) => {
     if (event.name !== "lesson_completed") return null;
     const lessonId = event.lessonId;
+    if (!lessonId) return null;
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
@@ -553,6 +564,50 @@ var TELEMETRY_XAPI_MAPPERS = {
       XAPIVerbs.experienced,
       ctx.timestamp
     );
+  },
+  image_juxtaposition_changed: experiencedBlockMapper,
+  timeline_event_viewed: experiencedBlockMapper,
+  image_sequence_changed: experiencedBlockMapper,
+  audio_recording_started: experiencedBlockMapper,
+  audio_recording_completed: (event, ctx) => {
+    if (event.name !== "audio_recording_completed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    if (!blockId) return null;
+    return statementFor(
+      event,
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  },
+  qr_content_revealed: experiencedBlockMapper,
+  advent_door_opened: experiencedBlockMapper,
+  map_stage_viewed: (event, ctx) => {
+    if (event.name !== "map_stage_viewed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const stageId = event.data.stageId;
+    if (!lessonId || !blockId || !stageId) return null;
+    return statementFor(
+      event,
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId, blockId, nodeId: stageId }),
+      XAPIVerbs.experienced,
+      ctx.timestamp
+    );
+  },
+  map_exit_selected: (event, ctx) => {
+    if (event.name !== "map_exit_selected") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const toStageId = event.data.toStageId;
+    if (!lessonId || !blockId || !toStageId) return null;
+    return statementFor(
+      event,
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId, blockId, nodeId: toStageId }),
+      XAPIVerbs.experienced,
+      ctx.timestamp
+    );
   }
 };
 function telemetryEventToXAPIStatement(event) {
@@ -604,10 +659,14 @@ function createXAPIClient(opts) {
     onDepth: opts?.onQueueDepth,
     onCap: opts?.onQueueCap ?? defaultQueueCapHandler,
     onOverflow: (statement) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -700,6 +759,7 @@ function createXAPIClient(opts) {
       }
       return;
     }
+    queue.removeById(normalized.id);
     inflightStatements.set(normalized.id, normalized);
     inflightPayload.set(normalized.id, normalized);
     const flight = Promise.resolve().then(async () => {

package/dist/index.d.cts

@@ -94,6 +94,8 @@ declare function createXAPIClient(opts?: {
     maxHeadFailures?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    /** Called when dead-letter storage drops older entries beyond the cap (200). */
+    onDeadLetterTruncated?: (droppedCount: number) => void;
     onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
     /** Called when transport fails after retries (statement is re-queued). */
     onTransportError?: (err: unknown) => void;
@@ -160,7 +162,9 @@ type FetchBatchSinkBundle = {
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
 declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: {
+    onTruncated?: (droppedCount: number) => void;
+}): void;
 
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.

package/dist/index.d.ts

@@ -94,6 +94,8 @@ declare function createXAPIClient(opts?: {
     maxHeadFailures?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    /** Called when dead-letter storage drops older entries beyond the cap (200). */
+    onDeadLetterTruncated?: (droppedCount: number) => void;
     onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
     /** Called when transport fails after retries (statement is re-queued). */
     onTransportError?: (err: unknown) => void;
@@ -160,7 +162,9 @@ type FetchBatchSinkBundle = {
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
 declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: {
+    onTruncated?: (droppedCount: number) => void;
+}): void;
 
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.

package/dist/index.js

@@ -181,16 +181,20 @@ function createInMemoryXAPIQueue(opts) {
       if (buffer.length >= maxSize) {
         if (headInFlight) {
           if (buffer.length > 1) {
+            const evicted = buffer[1];
             buffer.splice(1, 1);
             opts?.onCap?.();
+            opts?.onOverflow?.(evicted);
           } else {
             opts?.onCap?.();
             opts?.onOverflow?.(normalized);
             return;
           }
         } else {
+          const evicted = buffer[0];
           buffer.shift();
           opts?.onCap?.();
+          opts?.onOverflow?.(evicted);
         }
       }
       buffer.push(normalized);
@@ -207,7 +211,9 @@ function createInMemoryXAPIQueue(opts) {
       return flushInFlight;
     },
     flushOnExit: (exitTransport) => {
+      const skipId = headInFlightId;
       for (const statement of buffer) {
+        if (statement.id === skipId) continue;
         try {
           exitTransport(statement);
         } catch {
@@ -249,13 +255,17 @@ function loadDeadLetterStatements() {
     return [];
   }
 }
-function persistDeadLetterStatement(statement) {
+function persistDeadLetterStatement(statement, opts) {
   const storage = readStorage();
   if (!storage) return;
   try {
     const existing = loadDeadLetterStatements();
     if (existing.some((s) => s.id === statement.id)) return;
-    const next = [...existing, statement].slice(-MAX_DEAD_LETTER);
+    const combined = [...existing, statement];
+    if (combined.length > MAX_DEAD_LETTER) {
+      opts?.onTruncated?.(combined.length - MAX_DEAD_LETTER);
+    }
+    const next = combined.slice(-MAX_DEAD_LETTER);
     storage.setItem(STORAGE_KEY, JSON.stringify(next));
   } catch {
   }
@@ -389,6 +399,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   lesson_completed: (event, ctx) => {
     if (event.name !== "lesson_completed") return null;
     const lessonId = event.lessonId;
+    if (!lessonId) return null;
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
@@ -516,6 +527,50 @@ var TELEMETRY_XAPI_MAPPERS = {
       XAPIVerbs.experienced,
       ctx.timestamp
     );
+  },
+  image_juxtaposition_changed: experiencedBlockMapper,
+  timeline_event_viewed: experiencedBlockMapper,
+  image_sequence_changed: experiencedBlockMapper,
+  audio_recording_started: experiencedBlockMapper,
+  audio_recording_completed: (event, ctx) => {
+    if (event.name !== "audio_recording_completed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    if (!blockId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  },
+  qr_content_revealed: experiencedBlockMapper,
+  advent_door_opened: experiencedBlockMapper,
+  map_stage_viewed: (event, ctx) => {
+    if (event.name !== "map_stage_viewed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const stageId = event.data.stageId;
+    if (!lessonId || !blockId || !stageId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId, nodeId: stageId }),
+      XAPIVerbs.experienced,
+      ctx.timestamp
+    );
+  },
+  map_exit_selected: (event, ctx) => {
+    if (event.name !== "map_exit_selected") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const toStageId = event.data.toStageId;
+    if (!lessonId || !blockId || !toStageId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId, nodeId: toStageId }),
+      XAPIVerbs.experienced,
+      ctx.timestamp
+    );
   }
 };
 function telemetryEventToXAPIStatement(event) {
@@ -567,10 +622,14 @@ function createXAPIClient(opts) {
     onDepth: opts?.onQueueDepth,
     onCap: opts?.onQueueCap ?? defaultQueueCapHandler,
     onOverflow: (statement) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -663,6 +722,7 @@ function createXAPIClient(opts) {
       }
       return;
     }
+    queue.removeById(normalized.id);
     inflightStatements.set(normalized.id, normalized);
     inflightPayload.set(normalized.id, normalized);
     const flight = Promise.resolve().then(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -48,7 +48,7 @@
     "lint": "eslint --max-warnings 0 \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.5.0"
+    "@lessonkit/core": "1.6.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",