@lessonkit/xapi 1.4.0 → 1.6.0

package/dist/index.js

@@ -1,8 +1,116 @@
 // src/id.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function randomIdFallback() {
+  const g = globalThis;
+  if (g.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    return formatUuid(bytes);
+  }
+  throw new Error(
+    "[lessonkit] cryptoRandomId requires crypto.randomUUID or crypto.getRandomValues"
+  );
+}
+function formatUuid(bytes) {
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function hashSeedToUuid(seed) {
+  const bytes = new Uint8Array(16);
+  let h0 = 2166136261;
+  let h1 = 2166136261 ^ 2654435769;
+  let h2 = 2166136261 ^ 2246822507;
+  let h3 = 2166136261 ^ 3266489909;
+  for (let i = 0; i < seed.length; i += 1) {
+    const c = seed.charCodeAt(i);
+    h0 = Math.imul(h0 ^ c, 16777619);
+    h1 = Math.imul(h1 ^ c + 1, 16777619);
+    h2 = Math.imul(h2 ^ c + 2, 16777619);
+    h3 = Math.imul(h3 ^ c + 3, 16777619);
+  }
+  bytes[0] = h0 >>> 24 & 255;
+  bytes[1] = h0 >>> 16 & 255;
+  bytes[2] = h0 >>> 8 & 255;
+  bytes[3] = h0 & 255;
+  bytes[4] = h1 >>> 24 & 255;
+  bytes[5] = h1 >>> 16 & 255;
+  bytes[6] = h1 >>> 8 & 15 | 80;
+  bytes[7] = h1 & 255;
+  bytes[8] = h2 >>> 24 & 63 | 128;
+  bytes[9] = h2 >>> 16 & 255;
+  bytes[10] = h2 >>> 8 & 255;
+  bytes[11] = h2 & 255;
+  bytes[12] = h3 >>> 24 & 255;
+  bytes[13] = h3 >>> 16 & 255;
+  bytes[14] = h3 >>> 8 & 255;
+  bytes[15] = h3 & 255;
+  return formatUuid(bytes);
+}
 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)}`;
+  return randomIdFallback();
+}
+var LIFECYCLE_EVENTS_FOR_STABLE_ID = /* @__PURE__ */ new Set([
+  "course_started",
+  "course_completed",
+  "lesson_started",
+  "lesson_completed"
+]);
+var ASSESSMENT_COMPLETION_EVENTS_FOR_STABLE_ID = /* @__PURE__ */ new Set([
+  "assessment_completed",
+  "quiz_completed"
+]);
+function stableTelemetryEventId(event) {
+  const seed = [
+    event.name,
+    event.courseId,
+    event.lessonId ?? "",
+    event.sessionId ?? "",
+    event.attemptId ?? ""
+  ].join("|");
+  return hashSeedToUuid(seed);
+}
+function stableAssessmentCompletionEventId(event) {
+  const checkId = event.data && typeof event.data === "object" && "checkId" in event.data ? String(event.data.checkId ?? "") : "";
+  const seed = [
+    event.name,
+    event.courseId,
+    event.lessonId ?? "",
+    event.sessionId ?? "",
+    event.attemptId ?? "",
+    checkId
+  ].join("|");
+  return hashSeedToUuid(seed);
+}
+function enrichTelemetryEventForXapi(event) {
+  if (event.id?.trim()) return event;
+  if (LIFECYCLE_EVENTS_FOR_STABLE_ID.has(event.name)) {
+    return { ...event, id: stableTelemetryEventId(event) };
+  }
+  if (ASSESSMENT_COMPLETION_EVENTS_FOR_STABLE_ID.has(event.name)) {
+    return {
+      ...event,
+      id: stableAssessmentCompletionEventId(
+        event
+      )
+    };
+  }
+  return event;
+}
+function deriveStatementId(event, objectId, verb) {
+  const eventId = event.id?.trim();
+  if (eventId && UUID_RE.test(eventId)) return eventId;
+  const seed = [
+    event.name,
+    event.courseId,
+    event.lessonId ?? "",
+    event.sessionId ?? "",
+    objectId,
+    verb,
+    event.timestamp
+  ].join("|");
+  return hashSeedToUuid(seed);
 }
 
 // src/queue.ts
@@ -64,16 +172,30 @@ function createInMemoryXAPIQueue(opts) {
   return {
     enqueue: (statement) => {
       const normalized = withStatementId(statement);
-      if (buffer.some((s) => s.id === normalized.id)) return;
+      const existingIdx = buffer.findIndex((s) => s.id === normalized.id);
+      if (existingIdx >= 0) {
+        buffer[existingIdx] = normalized;
+        notifyDepth();
+        return;
+      }
       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);
         }
-        opts?.onCap?.();
       }
       buffer.push(normalized);
       notifyDepth();
@@ -89,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 {
@@ -105,6 +229,64 @@ function createInMemoryXAPIQueue(opts) {
 // src/client.ts
 import { nowIso } from "@lessonkit/core";
 
+// src/deadLetter.ts
+var STORAGE_KEY = "lk-xapi-dead-letter";
+var MAX_DEAD_LETTER = 200;
+function readStorage() {
+  try {
+    const storage = globalThis.sessionStorage;
+    return storage ?? null;
+  } catch {
+    return null;
+  }
+}
+function loadDeadLetterStatements() {
+  const storage = readStorage();
+  if (!storage) return [];
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item) => typeof item === "object" && item !== null && typeof item.id === "string"
+    );
+  } catch {
+    return [];
+  }
+}
+function persistDeadLetterStatement(statement, opts) {
+  const storage = readStorage();
+  if (!storage) return;
+  try {
+    const existing = loadDeadLetterStatements();
+    if (existing.some((s) => s.id === statement.id)) return;
+    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 {
+  }
+}
+function removeDeadLetterStatement(id) {
+  const storage = readStorage();
+  if (!storage) return;
+  try {
+    const next = loadDeadLetterStatements().filter((s) => s.id !== id);
+    if (next.length === 0) {
+      storage.removeItem(STORAGE_KEY);
+    } else {
+      storage.setItem(STORAGE_KEY, JSON.stringify(next));
+    }
+  } catch {
+  }
+}
+function clearDeadLetterStorage() {
+  readStorage()?.removeItem(STORAGE_KEY);
+}
+
 // src/telemetryMap.ts
 import { buildLessonkitUrn } from "@lessonkit/core";
 
@@ -141,9 +323,9 @@ function buildXapiScoreResult(opts) {
   }
   return result;
 }
-function statementFor(objectId, verb, timestamp, extra) {
+function statementFor(event, objectId, verb, timestamp, extra) {
   return {
-    id: cryptoRandomId(),
+    id: deriveStatementId(event, objectId, verb),
     timestamp,
     verb,
     object: { id: objectId },
@@ -151,8 +333,21 @@ function statementFor(objectId, verb, timestamp, extra) {
     context: extra?.context
   };
 }
-function experiencedBlockStatement(courseId, lessonId, blockId, timestamp) {
+function sanitizeTelemetryEmbedSrc(src) {
+  try {
+    const url = new URL(src);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return src;
+  }
+}
+function experiencedBlockStatement(event, courseId, lessonId, blockId, timestamp) {
   return statementFor(
+    event,
     buildLessonkitUrn({ courseId, lessonId, blockId }),
     XAPIVerbs.experienced,
     timestamp
@@ -163,20 +358,39 @@ var experiencedBlockMapper = (event, ctx) => {
     const lessonId2 = event.lessonId;
     const blockId2 = event.data?.blockId;
     if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
-    return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
+    const kind = event.data?.kind;
+    const extensions = {};
+    if (kind === "embed_viewed" || kind === "chart_viewed") {
+      extensions["https://lessonkit.dev/xapi/interactionKind"] = kind;
+      const data = event.data;
+      if (kind === "embed_viewed" && data && typeof data.src === "string") {
+        extensions["https://lessonkit.dev/xapi/embedSrc"] = sanitizeTelemetryEmbedSrc(data.src);
+      }
+      if (kind === "chart_viewed" && data && typeof data.chartType === "string") {
+        extensions["https://lessonkit.dev/xapi/chartType"] = data.chartType;
+      }
+    }
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId: lessonId2, blockId: blockId2 }),
+      XAPIVerbs.experienced,
+      ctx.timestamp,
+      Object.keys(extensions).length > 0 ? { context: { extensions } } : void 0
+    );
   }
   const lessonId = event.lessonId;
   const blockId = "data" in event && event.data && "blockId" in event.data ? event.data.blockId : void 0;
   if (!lessonId || !blockId || typeof blockId !== "string") return null;
-  return experiencedBlockStatement(ctx.courseId, lessonId, blockId, ctx.timestamp);
+  return experiencedBlockStatement(event, ctx.courseId, lessonId, blockId, ctx.timestamp);
 };
 var TELEMETRY_XAPI_MAPPERS = {
-  course_started: (_event, ctx) => statementFor(buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.initialized, ctx.timestamp),
-  course_completed: (_event, ctx) => statementFor(buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.completed, ctx.timestamp),
+  course_started: (event, ctx) => statementFor(event, buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.initialized, ctx.timestamp),
+  course_completed: (event, ctx) => statementFor(event, buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.completed, ctx.timestamp),
   lesson_started: (event, ctx) => {
     const lessonId = event.name === "lesson_started" ? event.lessonId : void 0;
     if (!lessonId) return null;
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId }),
       XAPIVerbs.initialized,
       ctx.timestamp
@@ -185,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") {
@@ -194,9 +409,15 @@ var TELEMETRY_XAPI_MAPPERS = {
     if (typeof data?.success === "boolean") result.success = data.success;
     const score = buildXapiScoreResult({ score: data?.score, maxScore: data?.maxScore });
     if (score) result.score = score;
-    return statementFor(buildLessonkitUrn({ courseId: ctx.courseId, lessonId }), XAPIVerbs.completed, ctx.timestamp, {
-      result: Object.keys(result).length ? result : void 0
-    });
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId }),
+      XAPIVerbs.completed,
+      ctx.timestamp,
+      {
+        result: Object.keys(result).length ? result : void 0
+      }
+    );
   },
   lesson_time_on_task: () => null,
   quiz_answered: (event, ctx) => {
@@ -204,6 +425,7 @@ var TELEMETRY_XAPI_MAPPERS = {
     const result = {};
     if (typeof event.data.correct === "boolean") result.success = event.data.correct;
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
       XAPIVerbs.answered,
       ctx.timestamp,
@@ -214,6 +436,7 @@ var TELEMETRY_XAPI_MAPPERS = {
     if (event.name !== "quiz_completed") return null;
     const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
       XAPIVerbs.completed,
       ctx.timestamp,
@@ -225,6 +448,7 @@ var TELEMETRY_XAPI_MAPPERS = {
     const result = {};
     if (typeof event.data.correct === "boolean") result.success = event.data.correct;
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
       XAPIVerbs.answered,
       ctx.timestamp,
@@ -235,6 +459,7 @@ var TELEMETRY_XAPI_MAPPERS = {
     if (event.name !== "assessment_completed") return null;
     const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
       XAPIVerbs.completed,
       ctx.timestamp,
@@ -256,6 +481,7 @@ var TELEMETRY_XAPI_MAPPERS = {
     const blockId = event.data.blockId;
     if (!lessonId || !blockId) return null;
     return statementFor(
+      event,
       buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId }),
       XAPIVerbs.completed,
       ctx.timestamp
@@ -270,20 +496,92 @@ var TELEMETRY_XAPI_MAPPERS = {
     const blockId = event.data.blockId;
     if (!lessonId || !blockId) return null;
     return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  },
+  branch_node_viewed: (event, ctx) => {
+    if (event.name !== "branch_node_viewed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const nodeId = event.data.nodeId;
+    if (!lessonId || !blockId || !nodeId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId, nodeId }),
+      XAPIVerbs.experienced,
+      ctx.timestamp
+    );
+  },
+  branch_selected: (event, ctx) => {
+    if (event.name !== "branch_selected") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    const toNodeId = event.data.toNodeId;
+    if (!lessonId || !blockId || !toNodeId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId, nodeId: toNodeId }),
+      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) {
-  const mapper = TELEMETRY_XAPI_MAPPERS[event.name];
+  const enriched = enrichTelemetryEventForXapi(event);
+  const mapper = TELEMETRY_XAPI_MAPPERS[enriched.name];
   if (!mapper) {
-    throw new Error(`Unhandled telemetry event: ${event.name}`);
+    throw new Error(`Unhandled telemetry event: ${enriched.name}`);
   }
-  return mapper(event, {
-    courseId: event.courseId,
-    timestamp: event.timestamp
+  return mapper(enriched, {
+    courseId: enriched.courseId,
+    timestamp: enriched.timestamp
   });
 }
 
@@ -301,26 +599,90 @@ function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
+function defaultQueueCapHandler() {
+  if (isDevEnvironment()) {
+    console.warn("[lessonkit] xAPI queue reached capacity; oldest statement(s) dropped.");
+  }
+}
+function defaultHeadSkippedHandler(_statement, err) {
+  if (isDevEnvironment()) {
+    console.warn(
+      "[lessonkit] xAPI queue skipped statement after repeated transport failures:",
+      err instanceof Error ? err.message : err
+    );
+  }
+}
 function createXAPIClient(opts) {
   const transport = opts?.transport;
   const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
+    maxHeadFailures: opts?.maxHeadFailures,
     onDepth: opts?.onQueueDepth,
-    onCap: opts?.onQueueCap
+    onCap: opts?.onQueueCap ?? defaultQueueCapHandler,
+    onOverflow: (statement) => {
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
+    },
+    onHeadSkipped: (statement, err) => {
+      persistDeadLetterStatement(statement, {
+        onTruncated: opts?.onDeadLetterTruncated
+      });
+      (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
+    }
   });
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const inflightStatements = /* @__PURE__ */ new Map();
+  const pendingReplacement = /* @__PURE__ */ new Map();
+  const inflightPayload = /* @__PURE__ */ new Map();
+  const replacementWatcher = /* @__PURE__ */ new Set();
   const exitDeliveredIds = /* @__PURE__ */ new Set();
   const exitNetworkSentIds = /* @__PURE__ */ new Set();
+  const exitHandoffIds = /* @__PURE__ */ new Set();
+  let activeFlush = null;
+  for (const statement of loadDeadLetterStatements()) {
+    queue.enqueue(statement);
+  }
+  const hadDeadLetters = queue.size() > 0;
   const deliveryTransport = transport ? async (statement) => {
     if (exitNetworkSentIds.has(statement.id)) return;
     await transport(statement);
+    removeDeadLetterStatement(statement.id);
   } : void 0;
-  const sendOrQueue = (statement) => {
+  const markExitDelivered = (statement) => {
+    exitHandoffIds.delete(statement.id);
+    exitDeliveredIds.add(statement.id);
+    exitNetworkSentIds.add(statement.id);
+    removeDeadLetterStatement(statement.id);
+  };
+  const dispatchExitStatement = (statement) => {
+    if (exitDeliveredIds.has(statement.id)) return;
+    exitHandoffIds.add(statement.id);
+    try {
+      const result = exitTransport(statement);
+      if (result != null && typeof result.then === "function") {
+        void result.then(
+          () => markExitDelivered(statement),
+          () => {
+            exitHandoffIds.delete(statement.id);
+            persistDeadLetterStatement(statement);
+          }
+        );
+      } else {
+        markExitDelivered(statement);
+      }
+    } catch {
+      exitHandoffIds.delete(statement.id);
+      persistDeadLetterStatement(statement);
+    }
+  };
+  const pendingDuringFlush = [];
+  let flushInProgress = false;
+  const sendOrQueueInternal = (statement) => {
     const normalized = withStatementId2(statement);
     if (exitDeliveredIds.has(normalized.id)) return;
     if (!deliveryTransport) {
@@ -335,20 +697,39 @@ function createXAPIClient(opts) {
     }
     const existing = inflightById.get(normalized.id);
     if (existing) {
-      void existing.then(
-        () => void 0,
-        () => {
-          sendOrQueue(normalized);
-        }
-      );
+      pendingReplacement.set(normalized.id, normalized);
+      inflightStatements.set(normalized.id, normalized);
+      if (!replacementWatcher.has(normalized.id)) {
+        replacementWatcher.add(normalized.id);
+        void existing.then(
+          () => {
+            replacementWatcher.delete(normalized.id);
+            const replacement = pendingReplacement.get(normalized.id);
+            const transported = inflightPayload.get(normalized.id);
+            pendingReplacement.delete(normalized.id);
+            inflightPayload.delete(normalized.id);
+            if (replacement && replacement !== transported) {
+              sendOrQueueInternal(replacement);
+            }
+          },
+          () => {
+            replacementWatcher.delete(normalized.id);
+            const replacement = pendingReplacement.get(normalized.id) ?? normalized;
+            pendingReplacement.delete(normalized.id);
+            sendOrQueueInternal(replacement);
+          }
+        );
+      }
       return;
     }
+    queue.removeById(normalized.id);
     inflightStatements.set(normalized.id, normalized);
+    inflightPayload.set(normalized.id, normalized);
     const flight = Promise.resolve().then(async () => {
       await deliveryTransport(normalized);
       queue.removeById(normalized.id);
     }).catch((err) => {
-      if (exitDeliveredIds.has(normalized.id)) return;
+      if (exitDeliveredIds.has(normalized.id) || exitHandoffIds.has(normalized.id)) return;
       queue.enqueue(normalized);
       opts?.onTransportError?.(err);
       if (isDevEnvironment() && !warnedTransportFailure) {
@@ -361,17 +742,28 @@ function createXAPIClient(opts) {
     }).finally(() => {
       inflightById.delete(normalized.id);
       inflightStatements.delete(normalized.id);
+      if (!replacementWatcher.has(normalized.id)) {
+        inflightPayload.delete(normalized.id);
+      }
     });
     inflightById.set(normalized.id, flight);
     void flight.catch(() => {
     });
   };
+  const sendOrQueue = (statement) => {
+    if (flushInProgress) {
+      pendingDuringFlush.push(statement);
+      return;
+    }
+    sendOrQueueInternal(statement);
+  };
   const emit = (event) => {
     try {
       const statement = telemetryEventToXAPIStatement(event);
       if (!statement) return;
       sendOrQueue(statement);
     } catch (err) {
+      opts?.onMappingError?.(err);
       if (isDevEnvironment()) {
         console.warn(
           "[lessonkit] xAPI mapping skipped:",
@@ -380,42 +772,66 @@ function createXAPIClient(opts) {
       }
     }
   };
-  return {
+  const runFlushLoop = async () => {
+    if (!deliveryTransport) return;
+    for (; ; ) {
+      await queue.flush(deliveryTransport);
+      const flights = [...inflightById.values()];
+      if (flights.length > 0) {
+        await Promise.all(flights);
+      }
+      if (queue.size() === 0 && inflightById.size === 0) break;
+    }
+  };
+  const client = {
     send: (statement) => {
       sendOrQueue(statement);
     },
     queueSize: () => queue.size(),
     flush: async () => {
       if (!deliveryTransport) return;
-      await queue.flush(deliveryTransport);
-      const flights = [...inflightById.values()];
-      if (flights.length > 0) {
-        await Promise.all(flights);
-      }
-      if (queue.size() > 0) {
-        throw new Error("xAPI flush incomplete: statements remain queued after flush");
+      for (; ; ) {
+        if (activeFlush) {
+          await activeFlush;
+        } else {
+          flushInProgress = true;
+          activeFlush = (async () => {
+            try {
+              await runFlushLoop();
+              while (pendingDuringFlush.length > 0) {
+                const batch = pendingDuringFlush.splice(0, pendingDuringFlush.length);
+                for (const pending of batch) {
+                  sendOrQueueInternal(pending);
+                }
+                await runFlushLoop();
+              }
+            } finally {
+              flushInProgress = false;
+            }
+          })().finally(() => {
+            activeFlush = null;
+          });
+          await activeFlush;
+        }
+        if (queue.size() === 0 && inflightById.size === 0) break;
       }
     },
     flushOnExit: exitTransport ? () => {
       const headId = queue.getHeadInFlightId?.();
       if (headId) {
-        exitNetworkSentIds.add(headId);
-        exitDeliveredIds.add(headId);
         opts.abortInFlight?.(headId);
+        const headStatement = inflightStatements.get(headId);
+        if (headStatement) {
+          dispatchExitStatement(headStatement);
+        }
       }
       for (const statement of inflightStatements.values()) {
-        exitNetworkSentIds.add(statement.id);
-        exitDeliveredIds.add(statement.id);
+        if (statement.id === headId) continue;
         opts.abortInFlight?.(statement.id);
+        dispatchExitStatement(statement);
       }
       queue.flushOnExit((statement) => {
-        if (exitDeliveredIds.has(statement.id)) return;
-        exitNetworkSentIds.add(statement.id);
-        exitDeliveredIds.add(statement.id);
-        try {
-          exitTransport(statement);
-        } catch {
-        }
+        dispatchExitStatement(statement);
       });
     } : void 0,
     startedLesson: ({ lessonId }) => {
@@ -453,6 +869,97 @@ function createXAPIClient(opts) {
       });
     }
   };
+  if (hadDeadLetters && deliveryTransport) {
+    queueMicrotask(() => {
+      void client.flush().catch(() => void 0);
+    });
+  }
+  return client;
+}
+function resetXAPIDeadLetterForTests() {
+  clearDeadLetterStorage();
+}
+
+// src/safeLrsUrl.ts
+function isProductionRuntime() {
+  try {
+    if (import.meta.env?.PROD === true) return true;
+  } catch {
+  }
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
+}
+function parseHostname(url) {
+  return url.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+}
+function isIpv4MappedAddress(hostname) {
+  const match = hostname.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  return match?.[1] ?? null;
+}
+function isLoopbackHost(hostname) {
+  const ipv4Mapped = isIpv4MappedAddress(hostname);
+  if (ipv4Mapped) return isLoopbackHost(ipv4Mapped);
+  return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "::1" || hostname === "0.0.0.0";
+}
+function isLinkLocalOrMetadataHost(hostname) {
+  if (hostname === "169.254.169.254") return true;
+  if (/^169\.254\./.test(hostname)) return true;
+  if (/^fe80:/i.test(hostname)) return true;
+  return false;
+}
+function isRfc1918Host(hostname) {
+  const ipv4Mapped = isIpv4MappedAddress(hostname);
+  if (ipv4Mapped) return isRfc1918Host(ipv4Mapped);
+  if (/^10\./.test(hostname)) return true;
+  if (/^192\.168\./.test(hostname)) return true;
+  const parts = hostname.split(".").map(Number);
+  if (parts.length === 4 && parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+  return false;
+}
+function isPrivateOrMetadataHost(hostname) {
+  return isLoopbackHost(hostname) || isLinkLocalOrMetadataHost(hostname) || isRfc1918Host(hostname);
+}
+function containsPathTraversal(path) {
+  if (path.includes("..")) return true;
+  let decoded = path;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const next = decodeURIComponent(decoded.replace(/\+/g, " "));
+      if (next.includes("..")) return true;
+      if (next === decoded) break;
+      decoded = next;
+    } catch {
+      break;
+    }
+  }
+  return false;
+}
+function assertSafeLrsUrl(url, opts) {
+  if (url.startsWith("/")) {
+    if (containsPathTraversal(url)) {
+      throw new Error(`Unsafe LRS URL: path traversal in "${url}"`);
+    }
+    return;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Unsafe LRS URL: invalid URL "${url}"`);
+  }
+  if (containsPathTraversal(parsed.pathname)) {
+    throw new Error(`Unsafe LRS URL: path traversal in "${url}"`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`Unsafe LRS URL: unsupported scheme "${parsed.protocol}"`);
+  }
+  if (isProductionRuntime() && parsed.protocol !== "https:") {
+    throw new Error("Unsafe LRS URL: HTTPS is required in production builds");
+  }
+  const hostname = parseHostname(parsed);
+  if (!opts?.allowPrivateHosts && isPrivateOrMetadataHost(hostname)) {
+    throw new Error(`Unsafe LRS URL: private or metadata host "${hostname}" is not allowed`);
+  }
 }
 
 // src/fetchTransport.ts
@@ -522,6 +1029,7 @@ async function postWithRetry(post, retries, initialBackoffMs, maxBackoffMs) {
   }
 }
 function createFetchTransport(opts) {
+  assertSafeLrsUrl(opts.url, { allowPrivateHosts: opts.allowPrivateHosts });
   const timeoutMs = opts.timeoutMs ?? 3e4;
   const rawRetries = opts.retries ?? 2;
   const retries = Number.isFinite(rawRetries) ? Math.max(0, Math.floor(rawRetries)) : 2;
@@ -553,14 +1061,13 @@ function createFetchTransport(opts) {
     }
   };
   const exitTransport = (statement) => {
-    try {
-      void postStatement(opts.url, statement, {
-        ...opts.init,
-        headers: resolveHeaders(opts.headers),
-        keepalive: true
-      }).catch(() => void 0);
-    } catch {
-    }
+    return postStatement(opts.url, statement, {
+      ...opts.init,
+      headers: resolveHeaders(opts.headers),
+      keepalive: true
+    }).catch(() => {
+      throw new Error("xAPI keepalive delivery failed");
+    });
   };
   const abortInFlight = (statementId) => {
     activeControllers.get(statementId)?.abort();
@@ -569,6 +1076,7 @@ function createFetchTransport(opts) {
   return { transport, exitTransport, abortInFlight };
 }
 function createFetchBatchSink(opts) {
+  assertSafeLrsUrl(opts.url, { allowPrivateHosts: opts.allowPrivateHosts });
   const timeoutMs = opts.timeoutMs ?? 3e4;
   const rawRetries = opts.retries ?? 2;
   const retries = Number.isFinite(rawRetries) ? Math.max(0, Math.floor(rawRetries)) : 2;
@@ -592,26 +1100,31 @@ function createFetchBatchSink(opts) {
   return {
     batchSink: (events) => postBatch(events, opts.init ?? {}),
     exitBatchSink: (events) => {
-      try {
-        void fetch(opts.url, {
-          method: "POST",
-          body: JSON.stringify(events),
-          ...opts.init,
-          headers: resolveHeaders(opts.headers),
-          keepalive: true
-        }).catch(() => void 0);
-      } catch {
-      }
+      return fetch(opts.url, {
+        method: "POST",
+        body: JSON.stringify(events),
+        ...opts.init,
+        headers: resolveHeaders(opts.headers),
+        keepalive: true
+      }).then((res) => {
+        if (!res.ok) {
+          throw new FetchHttpError(res.status, res.statusText, "batch");
+        }
+      });
     }
   };
 }
 export {
   FetchHttpError,
+  assertSafeLrsUrl,
   createFetchBatchSink,
   createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
   isRetryableFetchError,
   isRetryableFetchHttpStatus,
+  loadDeadLetterStatements,
+  persistDeadLetterStatement,
+  resetXAPIDeadLetterForTests,
   telemetryEventToXAPIStatement
 };