@lessonkit/xapi 1.3.1 → 1.4.0

package/dist/index.cjs

@@ -20,10 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FetchHttpError: () => FetchHttpError,
   createFetchBatchSink: () => createFetchBatchSink,
   createFetchTransport: () => createFetchTransport,
   createInMemoryXAPIQueue: () => createInMemoryXAPIQueue,
   createXAPIClient: () => createXAPIClient,
+  isRetryableFetchError: () => isRetryableFetchError,
+  isRetryableFetchHttpStatus: () => isRetryableFetchHttpStatus,
   telemetryEventToXAPIStatement: () => telemetryEventToXAPIStatement
 });
 module.exports = __toCommonJS(index_exports);
@@ -46,11 +49,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);
   };
@@ -65,14 +72,25 @@ 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;
       }
     }
   };
@@ -81,12 +99,10 @@ function createInMemoryXAPIQueue(opts) {
       const normalized = withStatementId(statement);
       if (buffer.some((s) => s.id === normalized.id)) 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);
+          }
         } else {
           buffer.shift();
         }
@@ -106,21 +122,16 @@ 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
   };
 }
 
@@ -270,7 +281,33 @@ 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(
+      (0, import_core.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(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  }
 };
 function telemetryEventToXAPIStatement(event) {
   const mapper = TELEMETRY_XAPI_MAPPERS[event.name];
@@ -310,9 +347,16 @@ function createXAPIClient(opts) {
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const inflightStatements = /* @__PURE__ */ new Map();
+  const exitDeliveredIds = /* @__PURE__ */ new Set();
+  const exitNetworkSentIds = /* @__PURE__ */ new Set();
+  const deliveryTransport = transport ? async (statement) => {
+    if (exitNetworkSentIds.has(statement.id)) return;
+    await transport(statement);
+  } : void 0;
   const sendOrQueue = (statement) => {
     const normalized = withStatementId2(statement);
-    if (!transport) {
+    if (exitDeliveredIds.has(normalized.id)) return;
+    if (!deliveryTransport) {
       queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
@@ -334,17 +378,19 @@ function createXAPIClient(opts) {
     }
     inflightStatements.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)) 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);
@@ -373,27 +419,36 @@ function createXAPIClient(opts) {
     },
     queueSize: () => queue.size(),
     flush: async () => {
-      if (!transport) return;
-      await queue.flush(transport);
+      if (!deliveryTransport) return;
+      await queue.flush(deliveryTransport);
       const flights = [...inflightById.values()];
       if (flights.length > 0) {
-        await Promise.allSettled(flights);
+        await Promise.all(flights);
+      }
+      if (queue.size() > 0) {
+        throw new Error("xAPI flush incomplete: statements remain queued after flush");
       }
     },
     flushOnExit: exitTransport ? () => {
-      const exitSentIds = /* @__PURE__ */ new Set();
+      const headId = queue.getHeadInFlightId?.();
+      if (headId) {
+        exitNetworkSentIds.add(headId);
+        exitDeliveredIds.add(headId);
+        opts.abortInFlight?.(headId);
+      }
       for (const statement of inflightStatements.values()) {
-        if (exitSentIds.has(statement.id)) continue;
+        exitNetworkSentIds.add(statement.id);
+        exitDeliveredIds.add(statement.id);
+        opts.abortInFlight?.(statement.id);
+      }
+      queue.flushOnExit((statement) => {
+        if (exitDeliveredIds.has(statement.id)) return;
+        exitNetworkSentIds.add(statement.id);
+        exitDeliveredIds.add(statement.id);
         try {
           exitTransport(statement);
-          exitSentIds.add(statement.id);
         } catch {
         }
-      }
-      queue.flushOnExit((statement) => {
-        if (exitSentIds.has(statement.id)) return;
-        exitTransport(statement);
-        exitSentIds.add(statement.id);
       });
     } : void 0,
     startedLesson: ({ lessonId }) => {
@@ -434,58 +489,100 @@ function createXAPIClient(opts) {
 }
 
 // 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) {
   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) => {
@@ -498,36 +595,32 @@ function createFetchTransport(opts) {
     } catch {
     }
   };
-  return { transport, exitTransport };
+  const abortInFlight = (statementId) => {
+    activeControllers.get(statementId)?.abort();
+    activeControllers.delete(statementId);
+  };
+  return { transport, exitTransport, abortInFlight };
 }
 function createFetchBatchSink(opts) {
   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 ?? {}),
@@ -547,9 +640,12 @@ function createFetchBatchSink(opts) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FetchHttpError,
   createFetchBatchSink,
   createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
+  isRetryableFetchError,
+  isRetryableFetchHttpStatus,
   telemetryEventToXAPIStatement
 });

package/dist/index.d.cts

@@ -37,6 +37,8 @@ type XAPIQueue = {
     flush: (transport: XAPITransport) => Promise<void>;
     flushOnExit: (exitTransport: XAPIExitTransport) => void;
     size: () => number;
+    /** Statement id currently being delivered via flush, if any. */
+    getHeadInFlightId?: () => string | undefined;
 };
 type XAPIExitTransport = (statement: XAPIStatement) => void;
 type XAPIClient = {
@@ -65,6 +67,10 @@ type InMemoryXAPIQueueOptions = {
     onDepth?: (size: number) => void;
     /** Called when an oldest statement is dropped because the queue is at maxSize. */
     onCap?: () => void;
+    /** Failures at queue head before skipping (default 10). */
+    maxHeadFailures?: number;
+    /** Called when the queue head is skipped after repeated transport failures. */
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
 };
 declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
@@ -72,12 +78,16 @@ declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
     exitTransport?: XAPIExitTransport;
+    /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
+    abortInFlight?: (statementId: string) => void;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
     maxQueueSize?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    /** Called when transport fails after retries (statement is re-queued). */
+    onTransportError?: (err: unknown) => void;
 }): XAPIClient;
 
 type CreateFetchTransportOptions = {
@@ -100,7 +110,17 @@ type FetchTransportBundle = {
     transport: XAPITransport;
     /** Best-effort synchronous delivery for pagehide (keepalive fetch). */
     exitTransport: (statement: XAPIStatement) => void;
+    /** Abort an in-flight transport request by statement id (used on pagehide). */
+    abortInFlight: (statementId: string) => void;
 };
+/** HTTP error from fetch transport with status for retry policy. */
+declare class FetchHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, kind?: "xapi" | "batch");
+}
+/** Retry 429 and 5xx; do not retry other 4xx (auth/config errors). */
+declare function isRetryableFetchHttpStatus(status: number): boolean;
+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.
@@ -123,4 +143,4 @@ declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchB
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, FetchHttpError, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, isRetryableFetchError, isRetryableFetchHttpStatus, telemetryEventToXAPIStatement };

package/dist/index.d.ts

@@ -37,6 +37,8 @@ type XAPIQueue = {
     flush: (transport: XAPITransport) => Promise<void>;
     flushOnExit: (exitTransport: XAPIExitTransport) => void;
     size: () => number;
+    /** Statement id currently being delivered via flush, if any. */
+    getHeadInFlightId?: () => string | undefined;
 };
 type XAPIExitTransport = (statement: XAPIStatement) => void;
 type XAPIClient = {
@@ -65,6 +67,10 @@ type InMemoryXAPIQueueOptions = {
     onDepth?: (size: number) => void;
     /** Called when an oldest statement is dropped because the queue is at maxSize. */
     onCap?: () => void;
+    /** Failures at queue head before skipping (default 10). */
+    maxHeadFailures?: number;
+    /** Called when the queue head is skipped after repeated transport failures. */
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
 };
 declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
@@ -72,12 +78,16 @@ declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
     exitTransport?: XAPIExitTransport;
+    /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
+    abortInFlight?: (statementId: string) => void;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
     maxQueueSize?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    /** Called when transport fails after retries (statement is re-queued). */
+    onTransportError?: (err: unknown) => void;
 }): XAPIClient;
 
 type CreateFetchTransportOptions = {
@@ -100,7 +110,17 @@ type FetchTransportBundle = {
     transport: XAPITransport;
     /** Best-effort synchronous delivery for pagehide (keepalive fetch). */
     exitTransport: (statement: XAPIStatement) => void;
+    /** Abort an in-flight transport request by statement id (used on pagehide). */
+    abortInFlight: (statementId: string) => void;
 };
+/** HTTP error from fetch transport with status for retry policy. */
+declare class FetchHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, kind?: "xapi" | "batch");
+}
+/** Retry 429 and 5xx; do not retry other 4xx (auth/config errors). */
+declare function isRetryableFetchHttpStatus(status: number): boolean;
+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.
@@ -123,4 +143,4 @@ declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchB
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, FetchHttpError, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, isRetryableFetchError, isRetryableFetchHttpStatus, telemetryEventToXAPIStatement };

package/dist/index.js

@@ -16,11 +16,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,14 +39,25 @@ 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;
       }
     }
   };
@@ -51,12 +66,10 @@ function createInMemoryXAPIQueue(opts) {
       const normalized = withStatementId(statement);
       if (buffer.some((s) => s.id === normalized.id)) 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);
+          }
         } else {
           buffer.shift();
         }
@@ -76,21 +89,16 @@ 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
   };
 }
 
@@ -240,7 +248,33 @@ 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(
+      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(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId, blockId }),
+      XAPIVerbs.completed,
+      ctx.timestamp
+    );
+  }
 };
 function telemetryEventToXAPIStatement(event) {
   const mapper = TELEMETRY_XAPI_MAPPERS[event.name];
@@ -280,9 +314,16 @@ function createXAPIClient(opts) {
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
   const inflightStatements = /* @__PURE__ */ new Map();
+  const exitDeliveredIds = /* @__PURE__ */ new Set();
+  const exitNetworkSentIds = /* @__PURE__ */ new Set();
+  const deliveryTransport = transport ? async (statement) => {
+    if (exitNetworkSentIds.has(statement.id)) return;
+    await transport(statement);
+  } : void 0;
   const sendOrQueue = (statement) => {
     const normalized = withStatementId2(statement);
-    if (!transport) {
+    if (exitDeliveredIds.has(normalized.id)) return;
+    if (!deliveryTransport) {
       queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
@@ -304,17 +345,19 @@ function createXAPIClient(opts) {
     }
     inflightStatements.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)) 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);
@@ -343,27 +386,36 @@ function createXAPIClient(opts) {
     },
     queueSize: () => queue.size(),
     flush: async () => {
-      if (!transport) return;
-      await queue.flush(transport);
+      if (!deliveryTransport) return;
+      await queue.flush(deliveryTransport);
       const flights = [...inflightById.values()];
       if (flights.length > 0) {
-        await Promise.allSettled(flights);
+        await Promise.all(flights);
+      }
+      if (queue.size() > 0) {
+        throw new Error("xAPI flush incomplete: statements remain queued after flush");
       }
     },
     flushOnExit: exitTransport ? () => {
-      const exitSentIds = /* @__PURE__ */ new Set();
+      const headId = queue.getHeadInFlightId?.();
+      if (headId) {
+        exitNetworkSentIds.add(headId);
+        exitDeliveredIds.add(headId);
+        opts.abortInFlight?.(headId);
+      }
       for (const statement of inflightStatements.values()) {
-        if (exitSentIds.has(statement.id)) continue;
+        exitNetworkSentIds.add(statement.id);
+        exitDeliveredIds.add(statement.id);
+        opts.abortInFlight?.(statement.id);
+      }
+      queue.flushOnExit((statement) => {
+        if (exitDeliveredIds.has(statement.id)) return;
+        exitNetworkSentIds.add(statement.id);
+        exitDeliveredIds.add(statement.id);
         try {
           exitTransport(statement);
-          exitSentIds.add(statement.id);
         } catch {
         }
-      }
-      queue.flushOnExit((statement) => {
-        if (exitSentIds.has(statement.id)) return;
-        exitTransport(statement);
-        exitSentIds.add(statement.id);
       });
     } : void 0,
     startedLesson: ({ lessonId }) => {
@@ -404,58 +456,100 @@ function createXAPIClient(opts) {
 }
 
 // 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) {
   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) => {
@@ -468,36 +562,32 @@ function createFetchTransport(opts) {
     } catch {
     }
   };
-  return { transport, exitTransport };
+  const abortInFlight = (statementId) => {
+    activeControllers.get(statementId)?.abort();
+    activeControllers.delete(statementId);
+  };
+  return { transport, exitTransport, abortInFlight };
 }
 function createFetchBatchSink(opts) {
   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 ?? {}),
@@ -516,9 +606,12 @@ function createFetchBatchSink(opts) {
   };
 }
 export {
+  FetchHttpError,
   createFetchBatchSink,
   createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
+  isRetryableFetchError,
+  isRetryableFetchHttpStatus,
   telemetryEventToXAPIStatement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -48,7 +48,7 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.3.1"
+    "@lessonkit/core": "1.4.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",