@lessonkit/xapi 1.1.0 → 1.2.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

@@ -27,15 +27,21 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/queue.ts
-function createInMemoryXAPIQueue() {
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+function createInMemoryXAPIQueue(opts) {
+  const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  const notifyDepth = () => {
+    opts?.onDepth?.(buffer.length);
+  };
   const runFlush = async (transport) => {
     while (buffer.length) {
       const statement = buffer[0];
       try {
         await transport(statement);
         buffer.shift();
+        notifyDepth();
       } catch {
         return;
       }
@@ -44,7 +50,12 @@ function createInMemoryXAPIQueue() {
   return {
     enqueue: (statement) => {
       if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      if (buffer.length >= maxSize) {
+        buffer.shift();
+        opts?.onCap?.();
+      }
       buffer.push(statement);
+      notifyDepth();
     },
     size: () => buffer.length,
     flush: async (transport) => {
@@ -59,11 +70,10 @@ 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() {
@@ -87,130 +97,16 @@ 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;
+  return {
+    raw,
+    max,
+    min: 0,
+    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+  };
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -222,6 +118,113 @@ 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) 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") {
+      result.duration = formatDurationMs(data.durationMs);
+    }
+    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,
+  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 isDevEnvironment() {
@@ -231,7 +234,11 @@ 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();
@@ -293,7 +300,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 +316,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 +326,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,13 +1,19 @@
 // src/queue.ts
-function createInMemoryXAPIQueue() {
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+function createInMemoryXAPIQueue(opts) {
+  const maxSize = opts?.maxSize ?? DEFAULT_MAX_QUEUE_SIZE;
   const buffer = [];
   let flushInFlight = null;
+  const notifyDepth = () => {
+    opts?.onDepth?.(buffer.length);
+  };
   const runFlush = async (transport) => {
     while (buffer.length) {
       const statement = buffer[0];
       try {
         await transport(statement);
         buffer.shift();
+        notifyDepth();
       } catch {
         return;
       }
@@ -16,7 +22,12 @@ function createInMemoryXAPIQueue() {
   return {
     enqueue: (statement) => {
       if (statement.id && buffer.some((s) => s.id === statement.id)) return;
+      if (buffer.length >= maxSize) {
+        buffer.shift();
+        opts?.onCap?.();
+      }
       buffer.push(statement);
+      notifyDepth();
     },
     size: () => buffer.length,
     flush: async (transport) => {
@@ -34,7 +45,6 @@ function createInMemoryXAPIQueue() {
 import { nowIso } from "@lessonkit/core";
 
 // src/telemetryMap.ts
-import { assertNever } from "@lessonkit/core";
 import { buildLessonkitUrn } from "@lessonkit/core";
 
 // src/id.ts
@@ -59,130 +69,16 @@ 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;
+  return {
+    raw,
+    max,
+    min: 0,
+    scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
+  };
 }
 function statementFor(objectId, verb, timestamp, extra) {
   return {
@@ -194,6 +90,113 @@ 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) 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") {
+      result.duration = formatDurationMs(data.durationMs);
+    }
+    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,
+  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 isDevEnvironment() {
@@ -203,7 +206,11 @@ 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();

package/package.json

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