@lessonkit/xapi 1.3.1 → 1.5.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
@@ -16,11 +124,15 @@ function withStatementId(statement) {
   return statement;
 }
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+var DEFAULT_MAX_HEAD_FAILURES = 10;
 function createInMemoryXAPIQueue(opts) {
   const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
+  const maxHeadFailures = opts?.maxHeadFailures ?? DEFAULT_MAX_HEAD_FAILURES;
   const buffer = [];
   let flushInFlight = null;
   let headInFlight = false;
+  let headInFlightId;
+  let headFailureCount = 0;
   const notifyDepth = () => {
     opts?.onDepth?.(buffer.length);
   };
@@ -35,32 +147,51 @@ function createInMemoryXAPIQueue(opts) {
     while (buffer.length) {
       const statement = buffer[0];
       headInFlight = true;
+      headInFlightId = statement.id;
       try {
         await transport(statement);
         buffer.shift();
+        headFailureCount = 0;
         notifyDepth();
-      } catch {
-        return;
+      } catch (err) {
+        headFailureCount += 1;
+        if (headFailureCount >= maxHeadFailures) {
+          buffer.shift();
+          headFailureCount = 0;
+          notifyDepth();
+          opts?.onHeadSkipped?.(statement, err);
+          continue;
+        }
+        throw err;
       } finally {
         headInFlight = false;
+        headInFlightId = void 0;
       }
     }
   };
   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 && buffer.length <= 1) {
-          opts?.onCap?.();
-          return;
-        }
         if (headInFlight) {
-          buffer.splice(1, 1);
+          if (buffer.length > 1) {
+            buffer.splice(1, 1);
+            opts?.onCap?.();
+          } else {
+            opts?.onCap?.();
+            opts?.onOverflow?.(normalized);
+            return;
+          }
         } else {
           buffer.shift();
+          opts?.onCap?.();
         }
-        opts?.onCap?.();
       }
       buffer.push(normalized);
       notifyDepth();
@@ -76,27 +207,76 @@ function createInMemoryXAPIQueue(opts) {
       return flushInFlight;
     },
     flushOnExit: (exitTransport) => {
-      const startIdx = headInFlight && buffer.length > 0 ? 1 : 0;
-      for (let i = startIdx; i < buffer.length; i++) {
-        const statement = buffer[i];
+      for (const statement of buffer) {
         try {
           exitTransport(statement);
         } catch {
         }
       }
-      if (startIdx === 0) {
-        buffer.length = 0;
-      } else if (buffer.length > 1) {
-        buffer.splice(1);
-      }
+      buffer.length = 0;
       notifyDepth();
-    }
+    },
+    getHeadInFlightId: () => headInFlightId
   };
 }
 
 // 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) {
+  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);
+    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";
 
@@ -133,9 +313,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 },
@@ -143,8 +323,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
@@ -155,20 +348,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
@@ -186,9 +398,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) => {
@@ -196,6 +414,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,
@@ -206,6 +425,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,
@@ -217,6 +437,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,
@@ -227,6 +448,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,
@@ -240,16 +462,71 @@ var TELEMETRY_XAPI_MAPPERS = {
   hotspot_opened: experiencedBlockMapper,
   accordion_section_toggled: experiencedBlockMapper,
   flashcard_flipped: experiencedBlockMapper,
-  image_slider_changed: experiencedBlockMapper
+  image_slider_changed: experiencedBlockMapper,
+  video_cue_reached: experiencedBlockMapper,
+  video_segment_completed: (event, ctx) => {
+    if (event.name !== "video_segment_completed") return null;
+    const lessonId = event.lessonId;
+    const blockId = event.data.blockId;
+    if (!lessonId || !blockId) return null;
+    return statementFor(
+      event,
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  },
+  memory_card_flipped: experiencedBlockMapper,
+  information_wall_search: experiencedBlockMapper,
+  parallax_slide_viewed: experiencedBlockMapper,
+  questionnaire_submitted: (event, ctx) => {
+    if (event.name !== "questionnaire_submitted") return null;
+    const lessonId = event.lessonId;
+    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
+    );
+  }
 };
 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
   });
 }
 
@@ -267,22 +544,89 @@ 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);
+    },
+    onHeadSkipped: (statement, err) => {
+      persistDeadLetterStatement(statement);
+      (opts?.onHeadSkipped ?? defaultHeadSkippedHandler)(statement, err);
+    }
   });
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const inflightStatements = /* @__PURE__ */ new Map();
-  const sendOrQueue = (statement) => {
+  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 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 (!transport) {
+    if (exitDeliveredIds.has(normalized.id)) return;
+    if (!deliveryTransport) {
       queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
@@ -294,41 +638,72 @@ 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;
     }
     inflightStatements.set(normalized.id, normalized);
+    inflightPayload.set(normalized.id, normalized);
     const flight = Promise.resolve().then(async () => {
-      await transport(normalized);
+      await deliveryTransport(normalized);
       queue.removeById(normalized.id);
-    }).catch(() => {
+    }).catch((err) => {
+      if (exitDeliveredIds.has(normalized.id) || exitHandoffIds.has(normalized.id)) return;
       queue.enqueue(normalized);
+      opts?.onTransportError?.(err);
       if (isDevEnvironment() && !warnedTransportFailure) {
         warnedTransportFailure = true;
         console.warn(
           "[lessonkit] xAPI transport failed; statement re-queued. Check your LRS endpoint or transport implementation."
         );
       }
-      throw new Error("xAPI transport failed");
+      throw err instanceof Error ? err : new Error("xAPI transport failed", { cause: err });
     }).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:",
@@ -337,33 +712,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 (!transport) return;
-      await queue.flush(transport);
-      const flights = [...inflightById.values()];
-      if (flights.length > 0) {
-        await Promise.allSettled(flights);
+      if (!deliveryTransport) return;
+      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 exitSentIds = /* @__PURE__ */ new Set();
-      for (const statement of inflightStatements.values()) {
-        if (exitSentIds.has(statement.id)) continue;
-        try {
-          exitTransport(statement);
-          exitSentIds.add(statement.id);
-        } catch {
+      const headId = queue.getHeadInFlightId?.();
+      if (headId) {
+        opts.abortInFlight?.(headId);
+        const headStatement = inflightStatements.get(headId);
+        if (headStatement) {
+          dispatchExitStatement(headStatement);
         }
       }
+      for (const statement of inflightStatements.values()) {
+        if (statement.id === headId) continue;
+        opts.abortInFlight?.(statement.id);
+        dispatchExitStatement(statement);
+      }
       queue.flushOnExit((statement) => {
-        if (exitSentIds.has(statement.id)) return;
-        exitTransport(statement);
-        exitSentIds.add(statement.id);
+        dispatchExitStatement(statement);
       });
     } : void 0,
     startedLesson: ({ lessonId }) => {
@@ -401,124 +809,262 @@ 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
+var FetchHttpError = class extends Error {
+  status;
+  constructor(status, statusText, kind = "xapi") {
+    super(
+      kind === "xapi" ? `xAPI fetch failed: ${status} ${statusText}` : `telemetry batch fetch failed: ${status} ${statusText}`
+    );
+    this.name = "FetchHttpError";
+    this.status = status;
+  }
+};
+function isRetryableFetchHttpStatus(status) {
+  return status === 429 || status >= 500;
+}
+function isRetryableFetchError(err) {
+  if (err instanceof FetchHttpError) return isRetryableFetchHttpStatus(err.status);
+  return true;
+}
 function resolveHeaders(headers) {
   if (!headers) return { "Content-Type": "application/json" };
   const resolved = typeof headers === "function" ? headers() : headers;
   return { "Content-Type": "application/json", ...resolved };
 }
 function createAbortSignal(timeoutMs) {
-  if (timeoutMs <= 0) return void 0;
-  const timeout = AbortSignal;
-  if (typeof timeout.timeout === "function") {
-    return timeout.timeout(timeoutMs);
-  }
+  if (timeoutMs <= 0) return { signal: void 0, abort: () => {
+  } };
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   timer.unref?.();
-  return controller.signal;
+  return {
+    signal: controller.signal,
+    abort: () => {
+      clearTimeout(timer);
+      controller.abort();
+    }
+  };
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function postStatement(url, statement, init) {
   return fetch(url, {
+    ...init,
     method: "POST",
-    body: JSON.stringify(statement),
-    ...init
+    body: JSON.stringify(statement)
   }).then((res) => {
     if (!res.ok) {
-      throw new Error(`xAPI fetch failed: ${res.status} ${res.statusText}`);
+      throw new FetchHttpError(res.status, res.statusText, "xapi");
     }
   });
 }
+async function postWithRetry(post, retries, initialBackoffMs, maxBackoffMs) {
+  let attempt = 0;
+  let backoff = initialBackoffMs;
+  for (; ; ) {
+    try {
+      await post();
+      return;
+    } catch (err) {
+      if (!isRetryableFetchError(err) || attempt >= retries) throw err;
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, maxBackoffMs);
+      attempt += 1;
+    }
+  }
+}
 function createFetchTransport(opts) {
+  assertSafeLrsUrl(opts.url, { allowPrivateHosts: opts.allowPrivateHosts });
   const timeoutMs = opts.timeoutMs ?? 3e4;
-  const retries = opts.retries ?? 2;
+  const rawRetries = opts.retries ?? 2;
+  const retries = Number.isFinite(rawRetries) ? Math.max(0, Math.floor(rawRetries)) : 2;
   const initialBackoffMs = opts.backoffMs ?? 250;
   const maxBackoffMs = opts.maxBackoffMs ?? 5e3;
+  const activeControllers = /* @__PURE__ */ new Map();
   const transport = async (statement) => {
-    let attempt = 0;
-    let backoff = initialBackoffMs;
-    for (; ; ) {
-      try {
-        await postStatement(opts.url, statement, {
-          ...opts.init,
-          headers: resolveHeaders(opts.headers),
-          signal: createAbortSignal(timeoutMs)
-        });
-        return;
-      } catch (err) {
-        if (attempt >= retries) throw err;
-        await sleep(backoff);
-        backoff = Math.min(backoff * 2, maxBackoffMs);
-        attempt += 1;
-      }
+    let abortCleanup;
+    activeControllers.set(statement.id, {
+      abort: () => abortCleanup?.()
+    });
+    try {
+      await postWithRetry(
+        () => {
+          const { signal, abort } = createAbortSignal(timeoutMs);
+          abortCleanup = abort;
+          return postStatement(opts.url, statement, {
+            ...opts.init,
+            headers: resolveHeaders(opts.headers),
+            signal
+          });
+        },
+        retries,
+        initialBackoffMs,
+        maxBackoffMs
+      );
+    } finally {
+      activeControllers.delete(statement.id);
     }
   };
   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");
+    });
   };
-  return { transport, exitTransport };
+  const abortInFlight = (statementId) => {
+    activeControllers.get(statementId)?.abort();
+    activeControllers.delete(statementId);
+  };
+  return { transport, exitTransport, abortInFlight };
 }
 function createFetchBatchSink(opts) {
+  assertSafeLrsUrl(opts.url, { allowPrivateHosts: opts.allowPrivateHosts });
   const timeoutMs = opts.timeoutMs ?? 3e4;
-  const retries = opts.retries ?? 2;
+  const rawRetries = opts.retries ?? 2;
+  const retries = Number.isFinite(rawRetries) ? Math.max(0, Math.floor(rawRetries)) : 2;
   const initialBackoffMs = opts.backoffMs ?? 250;
   const maxBackoffMs = opts.maxBackoffMs ?? 5e3;
   const postBatch = async (events, init) => {
-    let attempt = 0;
-    let backoff = initialBackoffMs;
-    for (; ; ) {
-      try {
-        const res = await fetch(opts.url, {
-          method: "POST",
-          body: JSON.stringify(events),
-          ...init,
-          headers: resolveHeaders(opts.headers),
-          signal: createAbortSignal(timeoutMs)
-        });
-        if (!res.ok) {
-          throw new Error(`telemetry batch fetch failed: ${res.status} ${res.statusText}`);
-        }
-        return;
-      } catch (err) {
-        if (attempt >= retries) throw err;
-        await sleep(backoff);
-        backoff = Math.min(backoff * 2, maxBackoffMs);
-        attempt += 1;
+    await postWithRetry(async () => {
+      const { signal } = createAbortSignal(timeoutMs);
+      const res = await fetch(opts.url, {
+        ...init,
+        method: "POST",
+        body: JSON.stringify(events),
+        headers: resolveHeaders(opts.headers),
+        signal
+      });
+      if (!res.ok) {
+        throw new FetchHttpError(res.status, res.statusText, "batch");
       }
-    }
+    }, retries, initialBackoffMs, maxBackoffMs);
   };
   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
 };