@lessonkit/xapi 1.3.0 → 1.4.0

package/README.md

@@ -17,27 +17,41 @@ npm install @lessonkit/xapi @lessonkit/core
 ## Usage
 
 ```typescript
-import { createXAPIClient, telemetryEventToXAPIStatement } from "@lessonkit/xapi";
+import { createFetchTransport, createXAPIClient, telemetryEventToXAPIStatement } from "@lessonkit/xapi";
+
+const { transport, exitTransport } = createFetchTransport({
+  url: "/api/xapi/statements",
+  timeoutMs: 30_000,
+});
 
 const xapi = createXAPIClient({
   courseId: "my-course",
-  transport: async (statement) => {
-    await fetch("/xapi/statements", { method: "POST", body: JSON.stringify(statement) });
-  },
+  transport,
+  exitTransport,
 });
 
 xapi.completeLesson({ lessonId: "lesson-1", durationMs: 1200, success: true });
 await xapi.flush();
+xapi.flushOnExit?.(); // pagehide keepalive delivery
 ```
 
 Map from telemetry events: `telemetryEventToXAPIStatement(event)` — uses canonical LessonKit URNs.
 
+Batch analytics sink:
+
+```typescript
+import { createFetchBatchSink } from "@lessonkit/xapi";
+
+const { batchSink, exitBatchSink } = createFetchBatchSink({ url: "/api/telemetry/batch" });
+```
+
 ## Behavior
 
 - No transport → statements queue in memory (dev warns once).
 - Transport failure → re-queue; call `flush()` to retry.
 - Queue capped at **1000** statements by default; oldest dropped when full (`onCap` / `createInMemoryXAPIQueue({ onCap })`).
 - Concurrent `flush()` calls are coalesced.
+- `createFetchTransport` retries with exponential backoff and uses `AbortSignal.timeout` when available.
 
 ## Docs
 

package/dist/index.cjs

@@ -20,8 +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);
@@ -44,26 +49,48 @@ 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);
   };
+  const removeById = (id) => {
+    const idx = buffer.findIndex((s) => s.id === id);
+    if (idx >= 0) {
+      buffer.splice(idx, 1);
+      notifyDepth();
+    }
+  };
   const runFlush = async (transport) => {
     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;
       }
     }
   };
@@ -72,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();
         }
@@ -86,6 +111,7 @@ function createInMemoryXAPIQueue(opts) {
       buffer.push(normalized);
       notifyDepth();
     },
+    removeById,
     size: () => buffer.length,
     flush: async (transport) => {
       if (flushInFlight) return flushInFlight;
@@ -94,7 +120,18 @@ function createInMemoryXAPIQueue(opts) {
         flushInFlight = null;
       });
       return flushInFlight;
-    }
+    },
+    flushOnExit: (exitTransport) => {
+      for (const statement of buffer) {
+        try {
+          exitTransport(statement);
+        } catch {
+        }
+      }
+      buffer.length = 0;
+      notifyDepth();
+    },
+    getHeadInFlightId: () => headInFlightId
   };
 }
 
@@ -244,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];
@@ -273,6 +336,7 @@ function isDevEnvironment() {
 }
 function createXAPIClient(opts) {
   const transport = opts?.transport;
+  const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
@@ -282,9 +346,17 @@ function createXAPIClient(opts) {
   let warnedNoTransport = false;
   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 +376,24 @@ function createXAPIClient(opts) {
       );
       return;
     }
-    const flight = Promise.resolve().then(() => transport(normalized)).catch(() => {
+    inflightStatements.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;
       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);
     });
     inflightById.set(normalized.id, flight);
     void flight.catch(() => {
@@ -340,13 +419,38 @@ 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 headId = queue.getHeadInFlightId?.();
+      if (headId) {
+        exitNetworkSentIds.add(headId);
+        exitDeliveredIds.add(headId);
+        opts.abortInFlight?.(headId);
+      }
+      for (const statement of inflightStatements.values()) {
+        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);
+        } catch {
+        }
+      });
+    } : void 0,
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;
       emit({
@@ -383,9 +487,165 @@ 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 { signal: void 0, abort: () => {
+  } };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  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)
+  }).then((res) => {
+    if (!res.ok) {
+      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 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 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 {
+    }
+  };
+  const abortInFlight = (statementId) => {
+    activeControllers.get(statementId)?.abort();
+    activeControllers.delete(statementId);
+  };
+  return { transport, exitTransport, abortInFlight };
+}
+function createFetchBatchSink(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  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) => {
+    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 {
+      }
+    }
+  };
+}
 // 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

@@ -32,12 +32,20 @@ type XAPIStatement = {
 type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIQueue = {
     enqueue: (statement: XAPIStatement) => void;
+    /** Remove a queued statement by id (e.g. after successful direct transport). */
+    removeById: (id: string) => void;
     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 = {
     send: (statement: XAPIStatement) => void;
     flush: () => Promise<void>;
+    /** Best-effort synchronous flush for pagehide using keepalive transport when configured. */
+    flushOnExit?: () => void;
     queueSize: () => number;
     startedLesson: (opts: {
         lessonId: LessonId;
@@ -59,23 +67,80 @@ 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;
 
 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 = {
+    /** LRS or proxy endpoint (POST). */
+    url: string;
+    /** Per-request timeout (default 30_000 ms). Uses AbortSignal.timeout when available. */
+    timeoutMs?: number;
+    /** Static headers merged into each request (e.g. Authorization from a short-lived token). */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Retries after transport failure (default 2). */
+    retries?: number;
+    /** Initial backoff in ms (default 250). Doubles each retry up to maxBackoffMs. */
+    backoffMs?: number;
+    /** Maximum backoff in ms (default 5_000). */
+    maxBackoffMs?: number;
+    /** Extra fetch init merged into each request. */
+    init?: Omit<RequestInit, "method" | "body" | "signal" | "keepalive">;
+};
+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.
+ */
+declare function createFetchTransport(opts: CreateFetchTransportOptions): FetchTransportBundle;
+type CreateFetchBatchSinkOptions = CreateFetchTransportOptions;
+type FetchBatchSinkBundle = {
+    batchSink: (events: unknown[]) => Promise<void>;
+    /** Best-effort keepalive POST for pagehide (JSON array body). */
+    exitBatchSink: (events: unknown[]) => void;
+};
+/**
+ * Batch analytics sink with timeout, retry backoff, and keepalive exit delivery.
+ */
+declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
+
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
  * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, 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

@@ -32,12 +32,20 @@ type XAPIStatement = {
 type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIQueue = {
     enqueue: (statement: XAPIStatement) => void;
+    /** Remove a queued statement by id (e.g. after successful direct transport). */
+    removeById: (id: string) => void;
     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 = {
     send: (statement: XAPIStatement) => void;
     flush: () => Promise<void>;
+    /** Best-effort synchronous flush for pagehide using keepalive transport when configured. */
+    flushOnExit?: () => void;
     queueSize: () => number;
     startedLesson: (opts: {
         lessonId: LessonId;
@@ -59,23 +67,80 @@ 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;
 
 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 = {
+    /** LRS or proxy endpoint (POST). */
+    url: string;
+    /** Per-request timeout (default 30_000 ms). Uses AbortSignal.timeout when available. */
+    timeoutMs?: number;
+    /** Static headers merged into each request (e.g. Authorization from a short-lived token). */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Retries after transport failure (default 2). */
+    retries?: number;
+    /** Initial backoff in ms (default 250). Doubles each retry up to maxBackoffMs. */
+    backoffMs?: number;
+    /** Maximum backoff in ms (default 5_000). */
+    maxBackoffMs?: number;
+    /** Extra fetch init merged into each request. */
+    init?: Omit<RequestInit, "method" | "body" | "signal" | "keepalive">;
+};
+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.
+ */
+declare function createFetchTransport(opts: CreateFetchTransportOptions): FetchTransportBundle;
+type CreateFetchBatchSinkOptions = CreateFetchTransportOptions;
+type FetchBatchSinkBundle = {
+    batchSink: (events: unknown[]) => Promise<void>;
+    /** Best-effort keepalive POST for pagehide (JSON array body). */
+    exitBatchSink: (events: unknown[]) => void;
+};
+/**
+ * Batch analytics sink with timeout, retry backoff, and keepalive exit delivery.
+ */
+declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
+
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
  * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, 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,26 +16,48 @@ 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);
   };
+  const removeById = (id) => {
+    const idx = buffer.findIndex((s) => s.id === id);
+    if (idx >= 0) {
+      buffer.splice(idx, 1);
+      notifyDepth();
+    }
+  };
   const runFlush = async (transport) => {
     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;
       }
     }
   };
@@ -44,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();
         }
@@ -58,6 +78,7 @@ function createInMemoryXAPIQueue(opts) {
       buffer.push(normalized);
       notifyDepth();
     },
+    removeById,
     size: () => buffer.length,
     flush: async (transport) => {
       if (flushInFlight) return flushInFlight;
@@ -66,7 +87,18 @@ function createInMemoryXAPIQueue(opts) {
         flushInFlight = null;
       });
       return flushInFlight;
-    }
+    },
+    flushOnExit: (exitTransport) => {
+      for (const statement of buffer) {
+        try {
+          exitTransport(statement);
+        } catch {
+        }
+      }
+      buffer.length = 0;
+      notifyDepth();
+    },
+    getHeadInFlightId: () => headInFlightId
   };
 }
 
@@ -216,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];
@@ -245,6 +303,7 @@ function isDevEnvironment() {
 }
 function createXAPIClient(opts) {
   const transport = opts?.transport;
+  const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
@@ -254,9 +313,17 @@ function createXAPIClient(opts) {
   let warnedNoTransport = false;
   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;
@@ -276,17 +343,24 @@ function createXAPIClient(opts) {
       );
       return;
     }
-    const flight = Promise.resolve().then(() => transport(normalized)).catch(() => {
+    inflightStatements.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;
       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);
     });
     inflightById.set(normalized.id, flight);
     void flight.catch(() => {
@@ -312,13 +386,38 @@ 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 headId = queue.getHeadInFlightId?.();
+      if (headId) {
+        exitNetworkSentIds.add(headId);
+        exitDeliveredIds.add(headId);
+        opts.abortInFlight?.(headId);
+      }
+      for (const statement of inflightStatements.values()) {
+        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);
+        } catch {
+        }
+      });
+    } : void 0,
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;
       emit({
@@ -355,8 +454,164 @@ 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 { signal: void 0, abort: () => {
+  } };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  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)
+  }).then((res) => {
+    if (!res.ok) {
+      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 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 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 {
+    }
+  };
+  const abortInFlight = (statementId) => {
+    activeControllers.get(statementId)?.abort();
+    activeControllers.delete(statementId);
+  };
+  return { transport, exitTransport, abortInFlight };
+}
+function createFetchBatchSink(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  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) => {
+    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 {
+      }
+    }
+  };
+}
 export {
+  FetchHttpError,
+  createFetchBatchSink,
+  createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
+  isRetryableFetchError,
+  isRetryableFetchHttpStatus,
   telemetryEventToXAPIStatement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "1.3.0",
+  "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.0"
+    "@lessonkit/core": "1.4.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",