@lessonkit/xapi 1.5.0 → 1.7.0

package/README.md

@@ -55,7 +55,7 @@ const { batchSink, exitBatchSink } = createFetchBatchSink({ url: "/api/telemetry
 
 ## 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) · [LRS operations](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lrs-operations.html) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
+[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [LMS Go-Live](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lms-go-live.html) · [Backend proxy cookbook](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/backend-proxy-cookbook.html) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
 
 ## License
 

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 {
@@ -253,7 +259,14 @@ function createInMemoryXAPIQueue(opts) {
       buffer.length = 0;
       notifyDepth();
     },
-    getHeadInFlightId: () => headInFlightId
+    getHeadInFlightId: () => headInFlightId,
+    drainAll: () => {
+      if (!buffer.length) return [];
+      const drained = buffer.splice(0, buffer.length);
+      headFailureCount = 0;
+      notifyDepth();
+      return drained;
+    }
   };
 }
 
@@ -263,6 +276,19 @@ var import_core2 = require("@lessonkit/core");
 // src/deadLetter.ts
 var STORAGE_KEY = "lk-xapi-dead-letter";
 var MAX_DEAD_LETTER = 200;
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function reportPersistError(err, statement, opts) {
+  opts?.onPersistError?.(err, { statement });
+  if (!opts?.onPersistError && isDevEnvironment()) {
+    console.warn(
+      "[lessonkit] xAPI dead-letter persist failed:",
+      err instanceof Error ? err.message : err
+    );
+  }
+}
 function readStorage() {
   try {
     const storage = globalThis.sessionStorage;
@@ -286,15 +312,23 @@ function loadDeadLetterStatements() {
     return [];
   }
 }
-function persistDeadLetterStatement(statement) {
+function persistDeadLetterStatement(statement, opts) {
   const storage = readStorage();
-  if (!storage) return;
+  if (!storage) {
+    reportPersistError(new Error("sessionStorage is unavailable"), statement, opts);
+    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 {
+  } catch (err) {
+    reportPersistError(err, statement, opts);
   }
 }
 function removeDeadLetterStatement(id) {
@@ -426,6 +460,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 +588,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) {
@@ -577,17 +656,17 @@ function withStatementId2(statement) {
   statement.id = cryptoRandomId();
   return statement;
 }
-function isDevEnvironment() {
+function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function defaultQueueCapHandler() {
-  if (isDevEnvironment()) {
+  if (isDevEnvironment2()) {
     console.warn("[lessonkit] xAPI queue reached capacity; oldest statement(s) dropped.");
   }
 }
 function defaultHeadSkippedHandler(_statement, err) {
-  if (isDevEnvironment()) {
+  if (isDevEnvironment2()) {
     console.warn(
       "[lessonkit] xAPI queue skipped statement after repeated transport failures:",
       err instanceof Error ? err.message : err
@@ -598,16 +677,22 @@ function createXAPIClient(opts) {
   const transport = opts?.transport;
   const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
+  const persistDeadLetter = (statement) => {
+    persistDeadLetterStatement(statement, {
+      onTruncated: opts?.onDeadLetterTruncated,
+      onPersistError: opts?.onDeadLetterPersistError
+    });
+  };
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
     maxHeadFailures: opts?.maxHeadFailures,
     onDepth: opts?.onQueueDepth,
     onCap: opts?.onQueueCap ?? defaultQueueCapHandler,
     onOverflow: (statement) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -647,7 +732,7 @@ function createXAPIClient(opts) {
           () => markExitDelivered(statement),
           () => {
             exitHandoffIds.delete(statement.id);
-            persistDeadLetterStatement(statement);
+            persistDeadLetter(statement);
           }
         );
       } else {
@@ -655,17 +740,35 @@ function createXAPIClient(opts) {
       }
     } catch {
       exitHandoffIds.delete(statement.id);
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
     }
   };
   const pendingDuringFlush = [];
   let flushInProgress = false;
+  const requeuePendingDuringFlush = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      queue.enqueue(statement);
+    }
+  };
+  const persistPendingDuringFlush = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      persistDeadLetter(statement);
+    }
+  };
+  const dispatchPendingDuringFlushOnExit = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      dispatchExitStatement(statement);
+    }
+  };
   const sendOrQueueInternal = (statement) => {
     const normalized = withStatementId2(statement);
     if (exitDeliveredIds.has(normalized.id)) return;
     if (!deliveryTransport) {
       queue.enqueue(normalized);
-      if (isDevEnvironment() && !warnedNoTransport) {
+      if (isDevEnvironment2() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
           "[lessonkit] xAPI statements are queued but no transport is configured; pass config.xapi.transport or config.xapi.client"
@@ -700,6 +803,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 () => {
@@ -709,7 +813,7 @@ function createXAPIClient(opts) {
       if (exitDeliveredIds.has(normalized.id) || exitHandoffIds.has(normalized.id)) return;
       queue.enqueue(normalized);
       opts?.onTransportError?.(err);
-      if (isDevEnvironment() && !warnedTransportFailure) {
+      if (isDevEnvironment2() && !warnedTransportFailure) {
         warnedTransportFailure = true;
         console.warn(
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
@@ -741,7 +845,7 @@ function createXAPIClient(opts) {
       sendOrQueue(statement);
     } catch (err) {
       opts?.onMappingError?.(err);
-      if (isDevEnvironment()) {
+      if (isDevEnvironment2()) {
         console.warn(
           "[lessonkit] xAPI mapping skipped:",
           err instanceof Error ? err.message : err
@@ -765,6 +869,12 @@ function createXAPIClient(opts) {
       sendOrQueue(statement);
     },
     queueSize: () => queue.size(),
+    abandonUndelivered: () => {
+      persistPendingDuringFlush();
+      for (const statement of queue.drainAll()) {
+        persistDeadLetter(statement);
+      }
+    },
     flush: async () => {
       if (!deliveryTransport) return;
       for (; ; ) {
@@ -782,6 +892,9 @@ function createXAPIClient(opts) {
                 }
                 await runFlushLoop();
               }
+            } catch (err) {
+              requeuePendingDuringFlush();
+              throw err;
             } finally {
               flushInProgress = false;
             }
@@ -807,6 +920,7 @@ function createXAPIClient(opts) {
         opts.abortInFlight?.(statement.id);
         dispatchExitStatement(statement);
       }
+      dispatchPendingDuringFlushOnExit();
       queue.flushOnExit((statement) => {
         dispatchExitStatement(statement);
       });
@@ -913,6 +1027,9 @@ function containsPathTraversal(path) {
   return false;
 }
 function assertSafeLrsUrl(url, opts) {
+  if (url.startsWith("//")) {
+    throw new Error(`Unsafe LRS URL: protocol-relative URLs are not allowed "${url}"`);
+  }
   if (url.startsWith("/")) {
     if (containsPathTraversal(url)) {
       throw new Error(`Unsafe LRS URL: path traversal in "${url}"`);

package/dist/index.d.cts

@@ -39,6 +39,8 @@ type XAPIQueue = {
     size: () => number;
     /** Statement id currently being delivered via flush, if any. */
     getHeadInFlightId?: () => string | undefined;
+    /** Remove and return all queued statements (does not affect in-flight direct transport). */
+    drainAll: () => XAPIStatement[];
 };
 type XAPIExitTransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIClient = {
@@ -46,6 +48,11 @@ type XAPIClient = {
     flush: () => Promise<void>;
     /** Best-effort synchronous flush for pagehide using keepalive transport when configured. */
     flushOnExit?: () => void;
+    /**
+     * Persist any queued (undelivered) statements to sessionStorage dead-letter storage.
+     * Used when a client is discarded after a failed final flush (e.g. course switch).
+     */
+    abandonUndelivered?: () => void;
     queueSize: () => number;
     startedLesson: (opts: {
         lessonId: LessonId;
@@ -79,6 +86,24 @@ declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQ
 /**
  * Imperative xAPI client with in-memory queue, retry flush, and optional pagehide delivery.
  * Prefer wiring transport via `LessonkitProvider` config from `@lessonkit/react` in React apps.
+ *
+ * @example
+ * ```ts
+ * import { createXAPIClient, createFetchTransport } from "@lessonkit/xapi";
+ *
+ * const client = createXAPIClient({
+ *   courseId: "my-course",
+ *   transport: createFetchTransport({ url: "/api/xapi/statements" }),
+ *   onTransportError: (err) => console.error("LRS delivery failed", err),
+ * });
+ *
+ * await client.trackTelemetryEvent({
+ *   name: "quiz_answered",
+ *   courseId: "my-course",
+ *   lessonId: "lesson-1",
+ *   checkId: "q1",
+ * });
+ * ```
  */
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
@@ -94,6 +119,12 @@ 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;
+    /** Called when a statement cannot be persisted to sessionStorage dead-letter storage. */
+    onDeadLetterPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
     onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
     /** Called when transport fails after retries (statement is re-queued). */
     onTransportError?: (err: unknown) => void;
@@ -146,6 +177,18 @@ declare function isRetryableFetchError(err: unknown): boolean;
 /**
  * Creates an xAPI transport backed by fetch with timeout, retry backoff, and a
  * keepalive exit transport for pagehide delivery.
+ *
+ * @example
+ * ```ts
+ * import { createFetchTransport } from "@lessonkit/xapi";
+ *
+ * const { transport, exitTransport, abortInFlight } = createFetchTransport({
+ *   url: import.meta.env.VITE_XAPI_PROXY_URL,
+ *   headers: () => ({ Authorization: "Bearer …" }),
+ * });
+ * ```
+ *
+ * @throws When `url` points at a private/loopback host without `allowPrivateHosts: true`.
  */
 declare function createFetchTransport(opts: CreateFetchTransportOptions): FetchTransportBundle;
 type CreateFetchBatchSinkOptions = CreateFetchTransportOptions;
@@ -156,11 +199,29 @@ type FetchBatchSinkBundle = {
 };
 /**
  * Batch analytics sink with timeout, retry backoff, and keepalive exit delivery.
+ * Wire as `config.tracking.batchSink` and `config.tracking.exitBatchSink` in production.
+ *
+ * @example
+ * ```ts
+ * import { createFetchBatchSink } from "@lessonkit/xapi";
+ *
+ * const { batchSink, exitBatchSink } = createFetchBatchSink({
+ *   url: import.meta.env.VITE_ANALYTICS_URL,
+ * });
+ * ```
+ *
+ * @throws When `url` points at a private/loopback host without `allowPrivateHosts: true`.
  */
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
+type PersistDeadLetterOptions = {
+    onTruncated?: (droppedCount: number) => void;
+    onPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
+};
 declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: PersistDeadLetterOptions): void;
 
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.

package/dist/index.d.ts

@@ -39,6 +39,8 @@ type XAPIQueue = {
     size: () => number;
     /** Statement id currently being delivered via flush, if any. */
     getHeadInFlightId?: () => string | undefined;
+    /** Remove and return all queued statements (does not affect in-flight direct transport). */
+    drainAll: () => XAPIStatement[];
 };
 type XAPIExitTransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIClient = {
@@ -46,6 +48,11 @@ type XAPIClient = {
     flush: () => Promise<void>;
     /** Best-effort synchronous flush for pagehide using keepalive transport when configured. */
     flushOnExit?: () => void;
+    /**
+     * Persist any queued (undelivered) statements to sessionStorage dead-letter storage.
+     * Used when a client is discarded after a failed final flush (e.g. course switch).
+     */
+    abandonUndelivered?: () => void;
     queueSize: () => number;
     startedLesson: (opts: {
         lessonId: LessonId;
@@ -79,6 +86,24 @@ declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQ
 /**
  * Imperative xAPI client with in-memory queue, retry flush, and optional pagehide delivery.
  * Prefer wiring transport via `LessonkitProvider` config from `@lessonkit/react` in React apps.
+ *
+ * @example
+ * ```ts
+ * import { createXAPIClient, createFetchTransport } from "@lessonkit/xapi";
+ *
+ * const client = createXAPIClient({
+ *   courseId: "my-course",
+ *   transport: createFetchTransport({ url: "/api/xapi/statements" }),
+ *   onTransportError: (err) => console.error("LRS delivery failed", err),
+ * });
+ *
+ * await client.trackTelemetryEvent({
+ *   name: "quiz_answered",
+ *   courseId: "my-course",
+ *   lessonId: "lesson-1",
+ *   checkId: "q1",
+ * });
+ * ```
  */
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
@@ -94,6 +119,12 @@ 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;
+    /** Called when a statement cannot be persisted to sessionStorage dead-letter storage. */
+    onDeadLetterPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
     onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
     /** Called when transport fails after retries (statement is re-queued). */
     onTransportError?: (err: unknown) => void;
@@ -146,6 +177,18 @@ declare function isRetryableFetchError(err: unknown): boolean;
 /**
  * Creates an xAPI transport backed by fetch with timeout, retry backoff, and a
  * keepalive exit transport for pagehide delivery.
+ *
+ * @example
+ * ```ts
+ * import { createFetchTransport } from "@lessonkit/xapi";
+ *
+ * const { transport, exitTransport, abortInFlight } = createFetchTransport({
+ *   url: import.meta.env.VITE_XAPI_PROXY_URL,
+ *   headers: () => ({ Authorization: "Bearer …" }),
+ * });
+ * ```
+ *
+ * @throws When `url` points at a private/loopback host without `allowPrivateHosts: true`.
  */
 declare function createFetchTransport(opts: CreateFetchTransportOptions): FetchTransportBundle;
 type CreateFetchBatchSinkOptions = CreateFetchTransportOptions;
@@ -156,11 +199,29 @@ type FetchBatchSinkBundle = {
 };
 /**
  * Batch analytics sink with timeout, retry backoff, and keepalive exit delivery.
+ * Wire as `config.tracking.batchSink` and `config.tracking.exitBatchSink` in production.
+ *
+ * @example
+ * ```ts
+ * import { createFetchBatchSink } from "@lessonkit/xapi";
+ *
+ * const { batchSink, exitBatchSink } = createFetchBatchSink({
+ *   url: import.meta.env.VITE_ANALYTICS_URL,
+ * });
+ * ```
+ *
+ * @throws When `url` points at a private/loopback host without `allowPrivateHosts: true`.
  */
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
+type PersistDeadLetterOptions = {
+    onTruncated?: (droppedCount: number) => void;
+    onPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
+};
 declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: PersistDeadLetterOptions): 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 {
@@ -216,7 +222,14 @@ function createInMemoryXAPIQueue(opts) {
       buffer.length = 0;
       notifyDepth();
     },
-    getHeadInFlightId: () => headInFlightId
+    getHeadInFlightId: () => headInFlightId,
+    drainAll: () => {
+      if (!buffer.length) return [];
+      const drained = buffer.splice(0, buffer.length);
+      headFailureCount = 0;
+      notifyDepth();
+      return drained;
+    }
   };
 }
 
@@ -226,6 +239,19 @@ import { nowIso } from "@lessonkit/core";
 // src/deadLetter.ts
 var STORAGE_KEY = "lk-xapi-dead-letter";
 var MAX_DEAD_LETTER = 200;
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function reportPersistError(err, statement, opts) {
+  opts?.onPersistError?.(err, { statement });
+  if (!opts?.onPersistError && isDevEnvironment()) {
+    console.warn(
+      "[lessonkit] xAPI dead-letter persist failed:",
+      err instanceof Error ? err.message : err
+    );
+  }
+}
 function readStorage() {
   try {
     const storage = globalThis.sessionStorage;
@@ -249,15 +275,23 @@ function loadDeadLetterStatements() {
     return [];
   }
 }
-function persistDeadLetterStatement(statement) {
+function persistDeadLetterStatement(statement, opts) {
   const storage = readStorage();
-  if (!storage) return;
+  if (!storage) {
+    reportPersistError(new Error("sessionStorage is unavailable"), statement, opts);
+    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 {
+  } catch (err) {
+    reportPersistError(err, statement, opts);
   }
 }
 function removeDeadLetterStatement(id) {
@@ -389,6 +423,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 +551,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) {
@@ -540,17 +619,17 @@ function withStatementId2(statement) {
   statement.id = cryptoRandomId();
   return statement;
 }
-function isDevEnvironment() {
+function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function defaultQueueCapHandler() {
-  if (isDevEnvironment()) {
+  if (isDevEnvironment2()) {
     console.warn("[lessonkit] xAPI queue reached capacity; oldest statement(s) dropped.");
   }
 }
 function defaultHeadSkippedHandler(_statement, err) {
-  if (isDevEnvironment()) {
+  if (isDevEnvironment2()) {
     console.warn(
       "[lessonkit] xAPI queue skipped statement after repeated transport failures:",
       err instanceof Error ? err.message : err
@@ -561,16 +640,22 @@ function createXAPIClient(opts) {
   const transport = opts?.transport;
   const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
+  const persistDeadLetter = (statement) => {
+    persistDeadLetterStatement(statement, {
+      onTruncated: opts?.onDeadLetterTruncated,
+      onPersistError: opts?.onDeadLetterPersistError
+    });
+  };
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
     maxHeadFailures: opts?.maxHeadFailures,
     onDepth: opts?.onQueueDepth,
     onCap: opts?.onQueueCap ?? defaultQueueCapHandler,
     onOverflow: (statement) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -610,7 +695,7 @@ function createXAPIClient(opts) {
           () => markExitDelivered(statement),
           () => {
             exitHandoffIds.delete(statement.id);
-            persistDeadLetterStatement(statement);
+            persistDeadLetter(statement);
           }
         );
       } else {
@@ -618,17 +703,35 @@ function createXAPIClient(opts) {
       }
     } catch {
       exitHandoffIds.delete(statement.id);
-      persistDeadLetterStatement(statement);
+      persistDeadLetter(statement);
     }
   };
   const pendingDuringFlush = [];
   let flushInProgress = false;
+  const requeuePendingDuringFlush = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      queue.enqueue(statement);
+    }
+  };
+  const persistPendingDuringFlush = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      persistDeadLetter(statement);
+    }
+  };
+  const dispatchPendingDuringFlushOnExit = () => {
+    const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+    for (const statement of batch) {
+      dispatchExitStatement(statement);
+    }
+  };
   const sendOrQueueInternal = (statement) => {
     const normalized = withStatementId2(statement);
     if (exitDeliveredIds.has(normalized.id)) return;
     if (!deliveryTransport) {
       queue.enqueue(normalized);
-      if (isDevEnvironment() && !warnedNoTransport) {
+      if (isDevEnvironment2() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
           "[lessonkit] xAPI statements are queued but no transport is configured; pass config.xapi.transport or config.xapi.client"
@@ -663,6 +766,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 () => {
@@ -672,7 +776,7 @@ function createXAPIClient(opts) {
       if (exitDeliveredIds.has(normalized.id) || exitHandoffIds.has(normalized.id)) return;
       queue.enqueue(normalized);
       opts?.onTransportError?.(err);
-      if (isDevEnvironment() && !warnedTransportFailure) {
+      if (isDevEnvironment2() && !warnedTransportFailure) {
         warnedTransportFailure = true;
         console.warn(
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
@@ -704,7 +808,7 @@ function createXAPIClient(opts) {
       sendOrQueue(statement);
     } catch (err) {
       opts?.onMappingError?.(err);
-      if (isDevEnvironment()) {
+      if (isDevEnvironment2()) {
         console.warn(
           "[lessonkit] xAPI mapping skipped:",
           err instanceof Error ? err.message : err
@@ -728,6 +832,12 @@ function createXAPIClient(opts) {
       sendOrQueue(statement);
     },
     queueSize: () => queue.size(),
+    abandonUndelivered: () => {
+      persistPendingDuringFlush();
+      for (const statement of queue.drainAll()) {
+        persistDeadLetter(statement);
+      }
+    },
     flush: async () => {
       if (!deliveryTransport) return;
       for (; ; ) {
@@ -745,6 +855,9 @@ function createXAPIClient(opts) {
                 }
                 await runFlushLoop();
               }
+            } catch (err) {
+              requeuePendingDuringFlush();
+              throw err;
             } finally {
               flushInProgress = false;
             }
@@ -770,6 +883,7 @@ function createXAPIClient(opts) {
         opts.abortInFlight?.(statement.id);
         dispatchExitStatement(statement);
       }
+      dispatchPendingDuringFlushOnExit();
       queue.flushOnExit((statement) => {
         dispatchExitStatement(statement);
       });
@@ -875,6 +989,9 @@ function containsPathTraversal(path) {
   return false;
 }
 function assertSafeLrsUrl(url, opts) {
+  if (url.startsWith("//")) {
+    throw new Error(`Unsafe LRS URL: protocol-relative URLs are not allowed "${url}"`);
+  }
   if (url.startsWith("/")) {
     if (containsPathTraversal(url)) {
       throw new Error(`Unsafe LRS URL: path traversal in "${url}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -39,8 +39,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.build.json",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch --tsconfig tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
@@ -48,7 +48,7 @@
     "lint": "eslint --max-warnings 0 \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.5.0"
+    "@lessonkit/core": "1.7.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",