@lessonkit/xapi 1.2.0 → 1.3.1

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,43 +20,82 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createFetchBatchSink: () => createFetchBatchSink,
+  createFetchTransport: () => createFetchTransport,
   createInMemoryXAPIQueue: () => createInMemoryXAPIQueue,
   createXAPIClient: () => createXAPIClient,
   telemetryEventToXAPIStatement: () => telemetryEventToXAPIStatement
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/id.ts
+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)}`;
+}
+
 // src/queue.ts
+function withStatementId(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 function createInMemoryXAPIQueue(opts) {
   const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  let headInFlight = false;
   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;
       try {
         await transport(statement);
         buffer.shift();
         notifyDepth();
       } catch {
         return;
+      } finally {
+        headInFlight = false;
       }
     }
   };
   return {
     enqueue: (statement) => {
-      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      const normalized = withStatementId(statement);
+      if (buffer.some((s) => s.id === normalized.id)) return;
       if (buffer.length >= maxSize) {
-        buffer.shift();
+        if (headInFlight && buffer.length <= 1) {
+          opts?.onCap?.();
+          return;
+        }
+        if (headInFlight) {
+          buffer.splice(1, 1);
+        } else {
+          buffer.shift();
+        }
         opts?.onCap?.();
       }
-      buffer.push(statement);
+      buffer.push(normalized);
       notifyDepth();
     },
+    removeById,
     size: () => buffer.length,
     flush: async (transport) => {
       if (flushInFlight) return flushInFlight;
@@ -65,6 +104,22 @@ function createInMemoryXAPIQueue(opts) {
         flushInFlight = null;
       });
       return flushInFlight;
+    },
+    flushOnExit: (exitTransport) => {
+      const startIdx = headInFlight && buffer.length > 0 ? 1 : 0;
+      for (let i = startIdx; i < buffer.length; i++) {
+        const statement = buffer[i];
+        try {
+          exitTransport(statement);
+        } catch {
+        }
+      }
+      if (startIdx === 0) {
+        buffer.length = 0;
+      } else if (buffer.length > 1) {
+        buffer.splice(1);
+      }
+      notifyDepth();
     }
   };
 }
@@ -75,16 +130,10 @@ var import_core2 = require("@lessonkit/core");
 // src/telemetryMap.ts
 var import_core = require("@lessonkit/core");
 
-// src/id.ts
-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)}`;
-}
-
 // src/duration.ts
 function formatDurationMs(ms) {
-  const safe = Math.max(0, ms);
+  if (!Number.isFinite(ms) || ms < 0) return void 0;
+  const safe = ms;
   const seconds = safe / 1e3;
   const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
   return `PT${fixed}S`;
@@ -101,12 +150,18 @@ function buildXapiScoreResult(opts) {
   const max = typeof opts.maxScore === "number" ? opts.maxScore : void 0;
   const raw = typeof opts.score === "number" ? opts.score : void 0;
   if (typeof raw !== "number" && typeof max !== "number") return void 0;
-  return {
-    raw,
-    max,
-    min: 0,
-    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-  };
+  if (typeof raw === "number" && !Number.isFinite(raw) || typeof max === "number" && !Number.isFinite(max)) {
+    return void 0;
+  }
+  if (typeof max === "number" && max <= 0) return void 0;
+  if (typeof raw === "number" && raw < 0) return void 0;
+  const result = { min: 0 };
+  if (typeof raw === "number") result.raw = raw;
+  if (typeof max === "number") result.max = max;
+  if (typeof raw === "number" && typeof max === "number" && max > 0 && raw <= max) {
+    result.scaled = raw / max;
+  }
+  return result;
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -129,7 +184,7 @@ var experiencedBlockMapper = (event, ctx) => {
   if (event.name === "interaction") {
     const lessonId2 = event.lessonId;
     const blockId2 = event.data?.blockId;
-    if (!lessonId2 || !blockId2) return null;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
     return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
   }
   const lessonId = event.lessonId;
@@ -155,7 +210,8 @@ var TELEMETRY_XAPI_MAPPERS = {
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
-      result.duration = formatDurationMs(data.durationMs);
+      const duration = formatDurationMs(data.durationMs);
+      if (duration !== void 0) result.duration = duration;
     }
     if (typeof data?.success === "boolean") result.success = data.success;
     const score = buildXapiScoreResult({ score: data?.score, maxScore: data?.maxScore });
@@ -209,6 +265,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   },
   interaction: experiencedBlockMapper,
   book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
   compound_page_viewed: experiencedBlockMapper,
   hotspot_opened: experiencedBlockMapper,
   accordion_section_toggled: experiencedBlockMapper,
@@ -227,12 +284,22 @@ function telemetryEventToXAPIStatement(event) {
 }
 
 // src/client.ts
+function withStatementId2(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function createXAPIClient(opts) {
   const transport = opts?.transport;
+  const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
@@ -242,9 +309,11 @@ function createXAPIClient(opts) {
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
+  const inflightStatements = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
+    const normalized = withStatementId2(statement);
     if (!transport) {
-      queue.enqueue(statement);
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
@@ -253,35 +322,50 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    const existing = inflightById.get(statement.id);
+    const existing = inflightById.get(normalized.id);
     if (existing) {
       void existing.then(
         () => void 0,
         () => {
-          sendOrQueue(statement);
+          sendOrQueue(normalized);
         }
       );
       return;
     }
-    const transportFlight = Promise.resolve().then(() => transport(statement));
-    const flight = transportFlight.catch(() => {
-      queue.enqueue(statement);
+    inflightStatements.set(normalized.id, normalized);
+    const flight = Promise.resolve().then(async () => {
+      await transport(normalized);
+      queue.removeById(normalized.id);
+    }).catch(() => {
+      queue.enqueue(normalized);
       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");
     }).finally(() => {
-      inflightById.delete(statement.id);
+      inflightById.delete(normalized.id);
+      inflightStatements.delete(normalized.id);
+    });
+    inflightById.set(normalized.id, flight);
+    void flight.catch(() => {
     });
-    inflightById.set(statement.id, transportFlight);
-    void flight;
   };
   const emit = (event) => {
-    const statement = telemetryEventToXAPIStatement(event);
-    if (!statement) return;
-    sendOrQueue(statement);
+    try {
+      const statement = telemetryEventToXAPIStatement(event);
+      if (!statement) return;
+      sendOrQueue(statement);
+    } catch (err) {
+      if (isDevEnvironment()) {
+        console.warn(
+          "[lessonkit] xAPI mapping skipped:",
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
   };
   return {
     send: (statement) => {
@@ -296,6 +380,22 @@ function createXAPIClient(opts) {
         await Promise.allSettled(flights);
       }
     },
+    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 {
+        }
+      }
+      queue.flushOnExit((statement) => {
+        if (exitSentIds.has(statement.id)) return;
+        exitTransport(statement);
+        exitSentIds.add(statement.id);
+      });
+    } : void 0,
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;
       emit({
@@ -332,8 +432,123 @@ function createXAPIClient(opts) {
     }
   };
 }
+
+// src/fetchTransport.ts
+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);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  return controller.signal;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function postStatement(url, statement, init) {
+  return fetch(url, {
+    method: "POST",
+    body: JSON.stringify(statement),
+    ...init
+  }).then((res) => {
+    if (!res.ok) {
+      throw new Error(`xAPI fetch failed: ${res.status} ${res.statusText}`);
+    }
+  });
+}
+function createFetchTransport(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const retries = opts.retries ?? 2;
+  const initialBackoffMs = opts.backoffMs ?? 250;
+  const maxBackoffMs = opts.maxBackoffMs ?? 5e3;
+  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;
+      }
+    }
+  };
+  const exitTransport = (statement) => {
+    try {
+      void postStatement(opts.url, statement, {
+        ...opts.init,
+        headers: resolveHeaders(opts.headers),
+        keepalive: true
+      }).catch(() => void 0);
+    } catch {
+    }
+  };
+  return { transport, exitTransport };
+}
+function createFetchBatchSink(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const retries = opts.retries ?? 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;
+      }
+    }
+  };
+  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 = {
+  createFetchBatchSink,
+  createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
   telemetryEventToXAPIStatement

package/dist/index.d.cts

@@ -32,12 +32,18 @@ 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;
 };
+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;
@@ -64,6 +70,8 @@ declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQ
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
+    /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
+    exitTransport?: XAPIExitTransport;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
@@ -72,10 +80,47 @@ declare function createXAPIClient(opts?: {
     onQueueCap?: () => 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;
+};
+/**
+ * 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, 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 };

package/dist/index.d.ts

@@ -32,12 +32,18 @@ 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;
 };
+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;
@@ -64,6 +70,8 @@ declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQ
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
+    /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
+    exitTransport?: XAPIExitTransport;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
@@ -72,10 +80,47 @@ declare function createXAPIClient(opts?: {
     onQueueCap?: () => 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;
+};
+/**
+ * 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, 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 };

package/dist/index.js

@@ -1,34 +1,71 @@
+// src/id.ts
+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)}`;
+}
+
 // src/queue.ts
+function withStatementId(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 function createInMemoryXAPIQueue(opts) {
   const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  let headInFlight = false;
   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;
       try {
         await transport(statement);
         buffer.shift();
         notifyDepth();
       } catch {
         return;
+      } finally {
+        headInFlight = false;
       }
     }
   };
   return {
     enqueue: (statement) => {
-      if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      const normalized = withStatementId(statement);
+      if (buffer.some((s) => s.id === normalized.id)) return;
       if (buffer.length >= maxSize) {
-        buffer.shift();
+        if (headInFlight && buffer.length <= 1) {
+          opts?.onCap?.();
+          return;
+        }
+        if (headInFlight) {
+          buffer.splice(1, 1);
+        } else {
+          buffer.shift();
+        }
         opts?.onCap?.();
       }
-      buffer.push(statement);
+      buffer.push(normalized);
       notifyDepth();
     },
+    removeById,
     size: () => buffer.length,
     flush: async (transport) => {
       if (flushInFlight) return flushInFlight;
@@ -37,6 +74,22 @@ function createInMemoryXAPIQueue(opts) {
         flushInFlight = null;
       });
       return flushInFlight;
+    },
+    flushOnExit: (exitTransport) => {
+      const startIdx = headInFlight && buffer.length > 0 ? 1 : 0;
+      for (let i = startIdx; i < buffer.length; i++) {
+        const statement = buffer[i];
+        try {
+          exitTransport(statement);
+        } catch {
+        }
+      }
+      if (startIdx === 0) {
+        buffer.length = 0;
+      } else if (buffer.length > 1) {
+        buffer.splice(1);
+      }
+      notifyDepth();
     }
   };
 }
@@ -47,16 +100,10 @@ import { nowIso } from "@lessonkit/core";
 // src/telemetryMap.ts
 import { buildLessonkitUrn } from "@lessonkit/core";
 
-// src/id.ts
-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)}`;
-}
-
 // src/duration.ts
 function formatDurationMs(ms) {
-  const safe = Math.max(0, ms);
+  if (!Number.isFinite(ms) || ms < 0) return void 0;
+  const safe = ms;
   const seconds = safe / 1e3;
   const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
   return `PT${fixed}S`;
@@ -73,12 +120,18 @@ function buildXapiScoreResult(opts) {
   const max = typeof opts.maxScore === "number" ? opts.maxScore : void 0;
   const raw = typeof opts.score === "number" ? opts.score : void 0;
   if (typeof raw !== "number" && typeof max !== "number") return void 0;
-  return {
-    raw,
-    max,
-    min: 0,
-    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-  };
+  if (typeof raw === "number" && !Number.isFinite(raw) || typeof max === "number" && !Number.isFinite(max)) {
+    return void 0;
+  }
+  if (typeof max === "number" && max <= 0) return void 0;
+  if (typeof raw === "number" && raw < 0) return void 0;
+  const result = { min: 0 };
+  if (typeof raw === "number") result.raw = raw;
+  if (typeof max === "number") result.max = max;
+  if (typeof raw === "number" && typeof max === "number" && max > 0 && raw <= max) {
+    result.scaled = raw / max;
+  }
+  return result;
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -101,7 +154,7 @@ var experiencedBlockMapper = (event, ctx) => {
   if (event.name === "interaction") {
     const lessonId2 = event.lessonId;
     const blockId2 = event.data?.blockId;
-    if (!lessonId2 || !blockId2) return null;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
     return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
   }
   const lessonId = event.lessonId;
@@ -127,7 +180,8 @@ var TELEMETRY_XAPI_MAPPERS = {
     const data = event.data;
     const result = {};
     if (typeof data?.durationMs === "number") {
-      result.duration = formatDurationMs(data.durationMs);
+      const duration = formatDurationMs(data.durationMs);
+      if (duration !== void 0) result.duration = duration;
     }
     if (typeof data?.success === "boolean") result.success = data.success;
     const score = buildXapiScoreResult({ score: data?.score, maxScore: data?.maxScore });
@@ -181,6 +235,7 @@ var TELEMETRY_XAPI_MAPPERS = {
   },
   interaction: experiencedBlockMapper,
   book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
   compound_page_viewed: experiencedBlockMapper,
   hotspot_opened: experiencedBlockMapper,
   accordion_section_toggled: experiencedBlockMapper,
@@ -199,12 +254,22 @@ function telemetryEventToXAPIStatement(event) {
 }
 
 // src/client.ts
+function withStatementId2(statement) {
+  const trimmed = statement.id?.trim();
+  if (trimmed) {
+    if (trimmed !== statement.id) statement.id = trimmed;
+    return statement;
+  }
+  statement.id = cryptoRandomId();
+  return statement;
+}
 function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function createXAPIClient(opts) {
   const transport = opts?.transport;
+  const exitTransport = opts?.exitTransport;
   const courseId = opts?.courseId;
   const queue = opts?.queue ?? createInMemoryXAPIQueue({
     maxSize: opts?.maxQueueSize,
@@ -214,9 +279,11 @@ function createXAPIClient(opts) {
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__PURE__ */ new Map();
+  const inflightStatements = /* @__PURE__ */ new Map();
   const sendOrQueue = (statement) => {
+    const normalized = withStatementId2(statement);
     if (!transport) {
-      queue.enqueue(statement);
+      queue.enqueue(normalized);
       if (isDevEnvironment() && !warnedNoTransport) {
         warnedNoTransport = true;
         console.warn(
@@ -225,35 +292,50 @@ function createXAPIClient(opts) {
       }
       return;
     }
-    const existing = inflightById.get(statement.id);
+    const existing = inflightById.get(normalized.id);
     if (existing) {
       void existing.then(
         () => void 0,
         () => {
-          sendOrQueue(statement);
+          sendOrQueue(normalized);
         }
       );
       return;
     }
-    const transportFlight = Promise.resolve().then(() => transport(statement));
-    const flight = transportFlight.catch(() => {
-      queue.enqueue(statement);
+    inflightStatements.set(normalized.id, normalized);
+    const flight = Promise.resolve().then(async () => {
+      await transport(normalized);
+      queue.removeById(normalized.id);
+    }).catch(() => {
+      queue.enqueue(normalized);
       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");
     }).finally(() => {
-      inflightById.delete(statement.id);
+      inflightById.delete(normalized.id);
+      inflightStatements.delete(normalized.id);
+    });
+    inflightById.set(normalized.id, flight);
+    void flight.catch(() => {
     });
-    inflightById.set(statement.id, transportFlight);
-    void flight;
   };
   const emit = (event) => {
-    const statement = telemetryEventToXAPIStatement(event);
-    if (!statement) return;
-    sendOrQueue(statement);
+    try {
+      const statement = telemetryEventToXAPIStatement(event);
+      if (!statement) return;
+      sendOrQueue(statement);
+    } catch (err) {
+      if (isDevEnvironment()) {
+        console.warn(
+          "[lessonkit] xAPI mapping skipped:",
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
   };
   return {
     send: (statement) => {
@@ -268,6 +350,22 @@ function createXAPIClient(opts) {
         await Promise.allSettled(flights);
       }
     },
+    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 {
+        }
+      }
+      queue.flushOnExit((statement) => {
+        if (exitSentIds.has(statement.id)) return;
+        exitTransport(statement);
+        exitSentIds.add(statement.id);
+      });
+    } : void 0,
     startedLesson: ({ lessonId }) => {
       if (!courseId) return;
       emit({
@@ -304,7 +402,122 @@ function createXAPIClient(opts) {
     }
   };
 }
+
+// src/fetchTransport.ts
+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);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  return controller.signal;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function postStatement(url, statement, init) {
+  return fetch(url, {
+    method: "POST",
+    body: JSON.stringify(statement),
+    ...init
+  }).then((res) => {
+    if (!res.ok) {
+      throw new Error(`xAPI fetch failed: ${res.status} ${res.statusText}`);
+    }
+  });
+}
+function createFetchTransport(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const retries = opts.retries ?? 2;
+  const initialBackoffMs = opts.backoffMs ?? 250;
+  const maxBackoffMs = opts.maxBackoffMs ?? 5e3;
+  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;
+      }
+    }
+  };
+  const exitTransport = (statement) => {
+    try {
+      void postStatement(opts.url, statement, {
+        ...opts.init,
+        headers: resolveHeaders(opts.headers),
+        keepalive: true
+      }).catch(() => void 0);
+    } catch {
+    }
+  };
+  return { transport, exitTransport };
+}
+function createFetchBatchSink(opts) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const retries = opts.retries ?? 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;
+      }
+    }
+  };
+  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 {
+  createFetchBatchSink,
+  createFetchTransport,
   createInMemoryXAPIQueue,
   createXAPIClient,
   telemetryEventToXAPIStatement

package/package.json

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