@lessonkit/xapi 1.6.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

@@ -259,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;
+    }
   };
 }
 
@@ -269,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;
@@ -294,7 +314,10 @@ function loadDeadLetterStatements() {
 }
 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;
@@ -304,7 +327,8 @@ function persistDeadLetterStatement(statement, opts) {
     }
     const next = combined.slice(-MAX_DEAD_LETTER);
     storage.setItem(STORAGE_KEY, JSON.stringify(next));
-  } catch {
+  } catch (err) {
+    reportPersistError(err, statement, opts);
   }
 }
 function removeDeadLetterStatement(id) {
@@ -632,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
@@ -653,20 +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, {
-        onTruncated: opts?.onDeadLetterTruncated
-      });
+      persistDeadLetter(statement);
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement, {
-        onTruncated: opts?.onDeadLetterTruncated
-      });
+      persistDeadLetter(statement);
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -706,7 +732,7 @@ function createXAPIClient(opts) {
           () => markExitDelivered(statement),
           () => {
             exitHandoffIds.delete(statement.id);
-            persistDeadLetterStatement(statement);
+            persistDeadLetter(statement);
           }
         );
       } else {
@@ -714,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"
@@ -769,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."
@@ -801,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
@@ -825,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 (; ; ) {
@@ -842,6 +892,9 @@ function createXAPIClient(opts) {
                 }
                 await runFlushLoop();
               }
+            } catch (err) {
+              requeuePendingDuringFlush();
+              throw err;
             } finally {
               flushInProgress = false;
             }
@@ -867,6 +920,7 @@ function createXAPIClient(opts) {
         opts.abortInFlight?.(statement.id);
         dispatchExitStatement(statement);
       }
+      dispatchPendingDuringFlushOnExit();
       queue.flushOnExit((statement) => {
         dispatchExitStatement(statement);
       });
@@ -973,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;
@@ -96,6 +121,10 @@ declare function createXAPIClient(opts?: {
     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;
@@ -148,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;
@@ -158,13 +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;
 
-declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: {
+type PersistDeadLetterOptions = {
     onTruncated?: (droppedCount: number) => void;
-}): void;
+    onPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
+};
+declare function loadDeadLetterStatements(): XAPIStatement[];
+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;
@@ -96,6 +121,10 @@ declare function createXAPIClient(opts?: {
     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;
@@ -148,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;
@@ -158,13 +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;
 
-declare function loadDeadLetterStatements(): XAPIStatement[];
-declare function persistDeadLetterStatement(statement: XAPIStatement, opts?: {
+type PersistDeadLetterOptions = {
     onTruncated?: (droppedCount: number) => void;
-}): void;
+    onPersistError?: (err: unknown, ctx: {
+        statement: XAPIStatement;
+    }) => void;
+};
+declare function loadDeadLetterStatements(): XAPIStatement[];
+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

@@ -222,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;
+    }
   };
 }
 
@@ -232,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;
@@ -257,7 +277,10 @@ function loadDeadLetterStatements() {
 }
 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;
@@ -267,7 +290,8 @@ function persistDeadLetterStatement(statement, opts) {
     }
     const next = combined.slice(-MAX_DEAD_LETTER);
     storage.setItem(STORAGE_KEY, JSON.stringify(next));
-  } catch {
+  } catch (err) {
+    reportPersistError(err, statement, opts);
   }
 }
 function removeDeadLetterStatement(id) {
@@ -595,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
@@ -616,20 +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, {
-        onTruncated: opts?.onDeadLetterTruncated
-      });
+      persistDeadLetter(statement);
     },
     onHeadSkipped: (statement, err) => {
-      persistDeadLetterStatement(statement, {
-        onTruncated: opts?.onDeadLetterTruncated
-      });
+      persistDeadLetter(statement);
       (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
     }
   });
@@ -669,7 +695,7 @@ function createXAPIClient(opts) {
           () => markExitDelivered(statement),
           () => {
             exitHandoffIds.delete(statement.id);
-            persistDeadLetterStatement(statement);
+            persistDeadLetter(statement);
           }
         );
       } else {
@@ -677,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"
@@ -732,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."
@@ -764,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
@@ -788,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 (; ; ) {
@@ -805,6 +855,9 @@ function createXAPIClient(opts) {
                 }
                 await runFlushLoop();
               }
+            } catch (err) {
+              requeuePendingDuringFlush();
+              throw err;
             } finally {
               flushInProgress = false;
             }
@@ -830,6 +883,7 @@ function createXAPIClient(opts) {
         opts.abortInFlight?.(statement.id);
         dispatchExitStatement(statement);
       }
+      dispatchPendingDuringFlushOnExit();
       queue.flushOnExit((statement) => {
         dispatchExitStatement(statement);
       });
@@ -935,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.6.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.6.0"
+    "@lessonkit/core": "1.7.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",