@lessonkit/xapi 1.1.0 → 1.3.0

package/README.md

@@ -36,6 +36,7 @@ Map from telemetry events: `telemetryEventToXAPIStatement(event)` — uses canon
 
 - 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.
 
 ## Docs

package/dist/index.cjs

@@ -26,25 +26,65 @@ __export(index_exports, {
 });
 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 createInMemoryXAPIQueue() {
+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 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;
-      buffer.push(statement);
+      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);
+        } else {
+          buffer.shift();
+        }
+        opts?.onCap?.();
+      }
+      buffer.push(normalized);
+      notifyDepth();
     },
     size: () => buffer.length,
     flush: async (transport) => {
@@ -59,22 +99,15 @@ function createInMemoryXAPIQueue() {
 }
 
 // src/client.ts
-var import_core3 = require("@lessonkit/core");
+var import_core2 = require("@lessonkit/core");
 
 // src/telemetryMap.ts
 var import_core = require("@lessonkit/core");
-var import_core2 = 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`;
@@ -87,130 +120,22 @@ var XAPIVerbs = {
   answered: "http://adlnet.gov/expapi/verbs/answered",
   experienced: "http://adlnet.gov/expapi/verbs/experienced"
 };
-function telemetryEventToXAPIStatement(event) {
-  const { courseId } = event;
-  switch (event.name) {
-    case "course_started":
-      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId }), XAPIVerbs.initialized, event.timestamp);
-    case "course_completed":
-      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId }), XAPIVerbs.completed, event.timestamp);
-    case "lesson_started": {
-      const lessonId = event.lessonId;
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId }),
-        XAPIVerbs.initialized,
-        event.timestamp
-      );
-    }
-    case "lesson_completed": {
-      const lessonId = event.lessonId;
-      const data = event.data;
-      const result = {};
-      if (typeof data?.durationMs === "number") {
-        result.duration = formatDurationMs(data.durationMs);
-      }
-      if (typeof data?.success === "boolean") result.success = data.success;
-      if (typeof data?.score === "number" || typeof data?.maxScore === "number") {
-        const max = typeof data.maxScore === "number" ? data.maxScore : void 0;
-        const raw = typeof data.score === "number" ? data.score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor((0, import_core2.buildLessonkitUrn)({ courseId, lessonId }), XAPIVerbs.completed, event.timestamp, {
-        result: Object.keys(result).length ? result : void 0
-      });
-    }
-    case "lesson_time_on_task":
-      return null;
-    case "quiz_answered": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const result = {};
-      if (typeof event.data.correct === "boolean") {
-        result.success = event.data.correct;
-      }
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
-        XAPIVerbs.answered,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "quiz_completed": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const { score, maxScore } = event.data;
-      const result = {};
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
-        XAPIVerbs.completed,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "assessment_answered": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const result = {};
-      if (typeof event.data.correct === "boolean") {
-        result.success = event.data.correct;
-      }
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
-        XAPIVerbs.answered,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "assessment_completed": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const { score, maxScore } = event.data;
-      const result = {};
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, checkId }),
-        XAPIVerbs.completed,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "interaction": {
-      const lessonId = event.lessonId;
-      const blockId = event.data?.blockId;
-      if (!lessonId || !blockId) return null;
-      return statementFor(
-        (0, import_core2.buildLessonkitUrn)({ courseId, lessonId, blockId }),
-        XAPIVerbs.experienced,
-        event.timestamp
-      );
-    }
-    default:
-      return (0, import_core.assertNever)(event, "Unhandled telemetry event");
+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;
+  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 {
@@ -222,8 +147,126 @@ function statementFor(objectId, verb, timestamp, extra) {
     context: extra?.context
   };
 }
+function experiencedBlockStatement(courseId, lessonId, blockId, timestamp) {
+  return statementFor(
+    (0, import_core.buildLessonkitUrn)({ courseId, lessonId, blockId }),
+    XAPIVerbs.experienced,
+    timestamp
+  );
+}
+var experiencedBlockMapper = (event, ctx) => {
+  if (event.name === "interaction") {
+    const lessonId2 = event.lessonId;
+    const blockId2 = event.data?.blockId;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
+    return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
+  }
+  const lessonId = event.lessonId;
+  const blockId = "data" in event && event.data && "blockId" in event.data ? event.data.blockId : void 0;
+  if (!lessonId || !blockId || typeof blockId !== "string") return null;
+  return experiencedBlockStatement(ctx.courseId, lessonId, blockId, ctx.timestamp);
+};
+var TELEMETRY_XAPI_MAPPERS = {
+  course_started: (_event, ctx) => statementFor((0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId }), XAPIVerbs.initialized, ctx.timestamp),
+  course_completed: (_event, ctx) => statementFor((0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId }), XAPIVerbs.completed, ctx.timestamp),
+  lesson_started: (event, ctx) => {
+    const lessonId = event.name === "lesson_started" ? event.lessonId : void 0;
+    if (!lessonId) return null;
+    return statementFor(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId }),
+      XAPIVerbs.initialized,
+      ctx.timestamp
+    );
+  },
+  lesson_completed: (event, ctx) => {
+    if (event.name !== "lesson_completed") return null;
+    const lessonId = event.lessonId;
+    const data = event.data;
+    const result = {};
+    if (typeof data?.durationMs === "number") {
+      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 });
+    if (score) result.score = score;
+    return statementFor((0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId }), XAPIVerbs.completed, ctx.timestamp, {
+      result: Object.keys(result).length ? result : void 0
+    });
+  },
+  lesson_time_on_task: () => null,
+  quiz_answered: (event, ctx) => {
+    if (event.name !== "quiz_answered") return null;
+    const result = {};
+    if (typeof event.data.correct === "boolean") result.success = event.data.correct;
+    return statementFor(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.answered,
+      ctx.timestamp,
+      { result: Object.keys(result).length ? result : void 0 }
+    );
+  },
+  quiz_completed: (event, ctx) => {
+    if (event.name !== "quiz_completed") return null;
+    const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
+    return statementFor(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.completed,
+      ctx.timestamp,
+      { result: score ? { score } : void 0 }
+    );
+  },
+  assessment_answered: (event, ctx) => {
+    if (event.name !== "assessment_answered") return null;
+    const result = {};
+    if (typeof event.data.correct === "boolean") result.success = event.data.correct;
+    return statementFor(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.answered,
+      ctx.timestamp,
+      { result: Object.keys(result).length ? result : void 0 }
+    );
+  },
+  assessment_completed: (event, ctx) => {
+    if (event.name !== "assessment_completed") return null;
+    const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
+    return statementFor(
+      (0, import_core.buildLessonkitUrn)({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.completed,
+      ctx.timestamp,
+      { result: score ? { score } : void 0 }
+    );
+  },
+  interaction: experiencedBlockMapper,
+  book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
+  compound_page_viewed: experiencedBlockMapper,
+  hotspot_opened: experiencedBlockMapper,
+  accordion_section_toggled: experiencedBlockMapper,
+  flashcard_flipped: experiencedBlockMapper,
+  image_slider_changed: experiencedBlockMapper
+};
+function telemetryEventToXAPIStatement(event) {
+  const mapper = TELEMETRY_XAPI_MAPPERS[event.name];
+  if (!mapper) {
+    throw new Error(`Unhandled telemetry event: ${event.name}`);
+  }
+  return mapper(event, {
+    courseId: event.courseId,
+    timestamp: event.timestamp
+  });
+}
 
 // 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";
@@ -231,13 +274,18 @@ function isDevEnvironment() {
 function createXAPIClient(opts) {
   const transport = opts?.transport;
   const courseId = opts?.courseId;
-  const queue = opts?.queue ?? createInMemoryXAPIQueue();
+  const queue = opts?.queue ?? createInMemoryXAPIQueue({
+    maxSize: opts?.maxQueueSize,
+    onDepth: opts?.onQueueDepth,
+    onCap: opts?.onQueueCap
+  });
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__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(
@@ -246,35 +294,45 @@ 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);
+    const flight = Promise.resolve().then(() => transport(normalized)).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);
+    });
+    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) => {
@@ -293,7 +351,7 @@ function createXAPIClient(opts) {
       if (!courseId) return;
       emit({
         name: "lesson_started",
-        timestamp: (0, import_core3.nowIso)(),
+        timestamp: (0, import_core2.nowIso)(),
         courseId,
         lessonId,
         data: { lessonId }
@@ -309,7 +367,7 @@ function createXAPIClient(opts) {
       if (!courseId) return;
       emit({
         name: "lesson_completed",
-        timestamp: (0, import_core3.nowIso)(),
+        timestamp: (0, import_core2.nowIso)(),
         courseId,
         lessonId,
         data: { lessonId, durationMs, score, maxScore, success }
@@ -319,7 +377,7 @@ function createXAPIClient(opts) {
       if (!courseId) return;
       emit({
         name: "course_completed",
-        timestamp: (0, import_core3.nowIso)(),
+        timestamp: (0, import_core2.nowIso)(),
         courseId
       });
     }

package/dist/index.d.cts

@@ -52,12 +52,24 @@ type XAPIClient = {
     completeCourse: () => void;
 };
 
-declare function createInMemoryXAPIQueue(): XAPIQueue;
+type InMemoryXAPIQueueOptions = {
+    /** Maximum queued statements (default 1000). Oldest entries are dropped when full. */
+    maxSize?: number;
+    /** Called after enqueue with the current queue size. */
+    onDepth?: (size: number) => void;
+    /** Called when an oldest statement is dropped because the queue is at maxSize. */
+    onCap?: () => void;
+};
+declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     courseId?: CourseId;
     queue?: XAPIQueue;
+    /** When creating the default in-memory queue (max size 1000 unless overridden). */
+    maxQueueSize?: number;
+    onQueueDepth?: (size: number) => void;
+    onQueueCap?: () => void;
 }): XAPIClient;
 
 /**
@@ -66,4 +78,4 @@ declare function createXAPIClient(opts?: {
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.d.ts

@@ -52,12 +52,24 @@ type XAPIClient = {
     completeCourse: () => void;
 };
 
-declare function createInMemoryXAPIQueue(): XAPIQueue;
+type InMemoryXAPIQueueOptions = {
+    /** Maximum queued statements (default 1000). Oldest entries are dropped when full. */
+    maxSize?: number;
+    /** Called after enqueue with the current queue size. */
+    onDepth?: (size: number) => void;
+    /** Called when an oldest statement is dropped because the queue is at maxSize. */
+    onCap?: () => void;
+};
+declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     courseId?: CourseId;
     queue?: XAPIQueue;
+    /** When creating the default in-memory queue (max size 1000 unless overridden). */
+    maxQueueSize?: number;
+    onQueueDepth?: (size: number) => void;
+    onQueueCap?: () => void;
 }): XAPIClient;
 
 /**
@@ -66,4 +78,4 @@ declare function createXAPIClient(opts?: {
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };

package/dist/index.js

@@ -1,22 +1,62 @@
+// 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 createInMemoryXAPIQueue() {
+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 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;
-      buffer.push(statement);
+      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);
+        } else {
+          buffer.shift();
+        }
+        opts?.onCap?.();
+      }
+      buffer.push(normalized);
+      notifyDepth();
     },
     size: () => buffer.length,
     flush: async (transport) => {
@@ -34,19 +74,12 @@ function createInMemoryXAPIQueue() {
 import { nowIso } from "@lessonkit/core";
 
 // src/telemetryMap.ts
-import { assertNever } from "@lessonkit/core";
 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`;
@@ -59,130 +92,22 @@ var XAPIVerbs = {
   answered: "http://adlnet.gov/expapi/verbs/answered",
   experienced: "http://adlnet.gov/expapi/verbs/experienced"
 };
-function telemetryEventToXAPIStatement(event) {
-  const { courseId } = event;
-  switch (event.name) {
-    case "course_started":
-      return statementFor(buildLessonkitUrn({ courseId }), XAPIVerbs.initialized, event.timestamp);
-    case "course_completed":
-      return statementFor(buildLessonkitUrn({ courseId }), XAPIVerbs.completed, event.timestamp);
-    case "lesson_started": {
-      const lessonId = event.lessonId;
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId }),
-        XAPIVerbs.initialized,
-        event.timestamp
-      );
-    }
-    case "lesson_completed": {
-      const lessonId = event.lessonId;
-      const data = event.data;
-      const result = {};
-      if (typeof data?.durationMs === "number") {
-        result.duration = formatDurationMs(data.durationMs);
-      }
-      if (typeof data?.success === "boolean") result.success = data.success;
-      if (typeof data?.score === "number" || typeof data?.maxScore === "number") {
-        const max = typeof data.maxScore === "number" ? data.maxScore : void 0;
-        const raw = typeof data.score === "number" ? data.score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor(buildLessonkitUrn({ courseId, lessonId }), XAPIVerbs.completed, event.timestamp, {
-        result: Object.keys(result).length ? result : void 0
-      });
-    }
-    case "lesson_time_on_task":
-      return null;
-    case "quiz_answered": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const result = {};
-      if (typeof event.data.correct === "boolean") {
-        result.success = event.data.correct;
-      }
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId, checkId }),
-        XAPIVerbs.answered,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "quiz_completed": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const { score, maxScore } = event.data;
-      const result = {};
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId, checkId }),
-        XAPIVerbs.completed,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "assessment_answered": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const result = {};
-      if (typeof event.data.correct === "boolean") {
-        result.success = event.data.correct;
-      }
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId, checkId }),
-        XAPIVerbs.answered,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "assessment_completed": {
-      const lessonId = event.lessonId;
-      const checkId = event.data.checkId;
-      const { score, maxScore } = event.data;
-      const result = {};
-      if (typeof score === "number" || typeof maxScore === "number") {
-        const max = typeof maxScore === "number" ? maxScore : void 0;
-        const raw = typeof score === "number" ? score : void 0;
-        result.score = {
-          raw,
-          max,
-          min: 0,
-          scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
-        };
-      }
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId, checkId }),
-        XAPIVerbs.completed,
-        event.timestamp,
-        { result: Object.keys(result).length ? result : void 0 }
-      );
-    }
-    case "interaction": {
-      const lessonId = event.lessonId;
-      const blockId = event.data?.blockId;
-      if (!lessonId || !blockId) return null;
-      return statementFor(
-        buildLessonkitUrn({ courseId, lessonId, blockId }),
-        XAPIVerbs.experienced,
-        event.timestamp
-      );
-    }
-    default:
-      return assertNever(event, "Unhandled telemetry event");
+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;
+  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 {
@@ -194,8 +119,126 @@ function statementFor(objectId, verb, timestamp, extra) {
     context: extra?.context
   };
 }
+function experiencedBlockStatement(courseId, lessonId, blockId, timestamp) {
+  return statementFor(
+    buildLessonkitUrn({ courseId, lessonId, blockId }),
+    XAPIVerbs.experienced,
+    timestamp
+  );
+}
+var experiencedBlockMapper = (event, ctx) => {
+  if (event.name === "interaction") {
+    const lessonId2 = event.lessonId;
+    const blockId2 = event.data?.blockId;
+    if (!lessonId2 || !blockId2 || typeof blockId2 !== "string") return null;
+    return experiencedBlockStatement(ctx.courseId, lessonId2, blockId2, ctx.timestamp);
+  }
+  const lessonId = event.lessonId;
+  const blockId = "data" in event && event.data && "blockId" in event.data ? event.data.blockId : void 0;
+  if (!lessonId || !blockId || typeof blockId !== "string") return null;
+  return experiencedBlockStatement(ctx.courseId, lessonId, blockId, ctx.timestamp);
+};
+var TELEMETRY_XAPI_MAPPERS = {
+  course_started: (_event, ctx) => statementFor(buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.initialized, ctx.timestamp),
+  course_completed: (_event, ctx) => statementFor(buildLessonkitUrn({ courseId: ctx.courseId }), XAPIVerbs.completed, ctx.timestamp),
+  lesson_started: (event, ctx) => {
+    const lessonId = event.name === "lesson_started" ? event.lessonId : void 0;
+    if (!lessonId) return null;
+    return statementFor(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId }),
+      XAPIVerbs.initialized,
+      ctx.timestamp
+    );
+  },
+  lesson_completed: (event, ctx) => {
+    if (event.name !== "lesson_completed") return null;
+    const lessonId = event.lessonId;
+    const data = event.data;
+    const result = {};
+    if (typeof data?.durationMs === "number") {
+      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 });
+    if (score) result.score = score;
+    return statementFor(buildLessonkitUrn({ courseId: ctx.courseId, lessonId }), XAPIVerbs.completed, ctx.timestamp, {
+      result: Object.keys(result).length ? result : void 0
+    });
+  },
+  lesson_time_on_task: () => null,
+  quiz_answered: (event, ctx) => {
+    if (event.name !== "quiz_answered") return null;
+    const result = {};
+    if (typeof event.data.correct === "boolean") result.success = event.data.correct;
+    return statementFor(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.answered,
+      ctx.timestamp,
+      { result: Object.keys(result).length ? result : void 0 }
+    );
+  },
+  quiz_completed: (event, ctx) => {
+    if (event.name !== "quiz_completed") return null;
+    const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
+    return statementFor(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.completed,
+      ctx.timestamp,
+      { result: score ? { score } : void 0 }
+    );
+  },
+  assessment_answered: (event, ctx) => {
+    if (event.name !== "assessment_answered") return null;
+    const result = {};
+    if (typeof event.data.correct === "boolean") result.success = event.data.correct;
+    return statementFor(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.answered,
+      ctx.timestamp,
+      { result: Object.keys(result).length ? result : void 0 }
+    );
+  },
+  assessment_completed: (event, ctx) => {
+    if (event.name !== "assessment_completed") return null;
+    const score = buildXapiScoreResult({ score: event.data.score, maxScore: event.data.maxScore });
+    return statementFor(
+      buildLessonkitUrn({ courseId: ctx.courseId, lessonId: event.lessonId, checkId: event.data.checkId }),
+      XAPIVerbs.completed,
+      ctx.timestamp,
+      { result: score ? { score } : void 0 }
+    );
+  },
+  interaction: experiencedBlockMapper,
+  book_page_viewed: experiencedBlockMapper,
+  slide_viewed: experiencedBlockMapper,
+  compound_page_viewed: experiencedBlockMapper,
+  hotspot_opened: experiencedBlockMapper,
+  accordion_section_toggled: experiencedBlockMapper,
+  flashcard_flipped: experiencedBlockMapper,
+  image_slider_changed: experiencedBlockMapper
+};
+function telemetryEventToXAPIStatement(event) {
+  const mapper = TELEMETRY_XAPI_MAPPERS[event.name];
+  if (!mapper) {
+    throw new Error(`Unhandled telemetry event: ${event.name}`);
+  }
+  return mapper(event, {
+    courseId: event.courseId,
+    timestamp: event.timestamp
+  });
+}
 
 // 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";
@@ -203,13 +246,18 @@ function isDevEnvironment() {
 function createXAPIClient(opts) {
   const transport = opts?.transport;
   const courseId = opts?.courseId;
-  const queue = opts?.queue ?? createInMemoryXAPIQueue();
+  const queue = opts?.queue ?? createInMemoryXAPIQueue({
+    maxSize: opts?.maxQueueSize,
+    onDepth: opts?.onQueueDepth,
+    onCap: opts?.onQueueCap
+  });
   let warnedNoTransport = false;
   let warnedTransportFailure = false;
   const inflightById = /* @__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(
@@ -218,35 +266,45 @@ 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);
+    const flight = Promise.resolve().then(() => transport(normalized)).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);
+    });
+    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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/xapi",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "description": "xAPI statement generation primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/eddiethedean/lessonkit.git",
     "directory": "packages/xapi"
   },
-  "homepage": "https://github.com/eddiethedean/lessonkit",
+  "homepage": "https://lessonkit.readthedocs.io/en/latest/reference/xapi.html",
   "bugs": {
     "url": "https://github.com/eddiethedean/lessonkit/issues"
   },
@@ -48,7 +48,7 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.1.0"
+    "@lessonkit/core": "1.3.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",