@lessonkit/core 1.3.0 → 1.3.1

package/dist/index.cjs

@@ -620,12 +620,14 @@ function createTrackingClient(opts) {
   }
   const buffer = [];
   let flushInFlight = null;
+  let inflightExitBatch = null;
   let disposed = false;
   let disposing = false;
   let intervalId;
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
+    inflightExitBatch = events;
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -650,6 +652,8 @@ function createTrackingClient(opts) {
         return runFlush();
       }
       return succeeded;
+    }).finally(() => {
+      inflightExitBatch = null;
     });
   };
   const flush = () => {
@@ -697,6 +701,22 @@ function createTrackingClient(opts) {
       if (buffer.length >= maxBatchSize) void flush();
     },
     flush,
+    flushOnExit: opts?.exitBatchSink ? () => {
+      const fromBuffer = buffer.splice(0, buffer.length);
+      const fromInflight = inflightExitBatch ? [...inflightExitBatch] : [];
+      const events = [...fromInflight, ...fromBuffer];
+      if (!events.length) return;
+      try {
+        const result = opts.exitBatchSink(events);
+        if (result != null && typeof result.catch === "function") {
+          void result.catch(() => {
+            buffer.unshift(...events);
+          });
+        }
+      } catch {
+        buffer.unshift(...events);
+      }
+    } : void 0,
     dispose: () => {
       if (disposed || disposing) return Promise.resolve();
       disposing = true;
@@ -1207,16 +1227,16 @@ function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
   return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
 function resetSharedVolatileSessionIdForTests() {
   sharedVolatileSessionId = null;
@@ -1238,19 +1258,29 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 }
 
 // src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Set();
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
   if (alreadyEmittedToSink) {
     return { emitted: true, marked };
   }
-  const emitted = deps.emitCourseStartedEvent(ctx);
-  if (emitted && !marked) {
-    markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmitFlights.has(flightKey)) {
+    return { emitted: false, marked };
+  }
+  courseStartedEmitFlights.add(flightKey);
+  try {
+    const emitted = deps.emitCourseStartedEvent(ctx);
+    if (emitted && !marked) {
+      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    }
+    return {
+      emitted,
+      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    };
+  } finally {
+    courseStartedEmitFlights.delete(flightKey);
   }
-  return {
-    emitted,
-    marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
-  };
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({

package/dist/index.d.cts

@@ -259,6 +259,8 @@ type TrackingClient = {
     track: (event: TelemetryEvent) => void;
     /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
     flush?: () => void | Promise<boolean>;
+    /** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
+    flushOnExit?: () => void;
     dispose?: () => void | Promise<void>;
 };
 
@@ -385,6 +387,8 @@ declare function createTrackingClient(opts?: {
     batchSink?: TelemetryBatchSink;
     /** Called when an event is dropped because the batch buffer is at cap (including in production). */
     onBufferDrop?: () => void;
+    /** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
+    exitBatchSink?: TelemetryBatchSink;
 }): TrackingClient;
 
 declare function createSessionId(): string;
@@ -523,9 +527,9 @@ declare function resolveSessionId(storage: StoragePort, provided?: string): stri
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 /** @internal Reset shared volatile session id between tests. */
 declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;

package/dist/index.d.ts

@@ -259,6 +259,8 @@ type TrackingClient = {
     track: (event: TelemetryEvent) => void;
     /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
     flush?: () => void | Promise<boolean>;
+    /** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
+    flushOnExit?: () => void;
     dispose?: () => void | Promise<void>;
 };
 
@@ -385,6 +387,8 @@ declare function createTrackingClient(opts?: {
     batchSink?: TelemetryBatchSink;
     /** Called when an event is dropped because the batch buffer is at cap (including in production). */
     onBufferDrop?: () => void;
+    /** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
+    exitBatchSink?: TelemetryBatchSink;
 }): TrackingClient;
 
 declare function createSessionId(): string;
@@ -523,9 +527,9 @@ declare function resolveSessionId(storage: StoragePort, provided?: string): stri
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 /** @internal Reset shared volatile session id between tests. */
 declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;

package/dist/index.js

@@ -522,12 +522,14 @@ function createTrackingClient(opts) {
   }
   const buffer = [];
   let flushInFlight = null;
+  let inflightExitBatch = null;
   let disposed = false;
   let disposing = false;
   let intervalId;
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
+    inflightExitBatch = events;
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -552,6 +554,8 @@ function createTrackingClient(opts) {
         return runFlush();
       }
       return succeeded;
+    }).finally(() => {
+      inflightExitBatch = null;
     });
   };
   const flush = () => {
@@ -599,6 +603,22 @@ function createTrackingClient(opts) {
       if (buffer.length >= maxBatchSize) void flush();
     },
     flush,
+    flushOnExit: opts?.exitBatchSink ? () => {
+      const fromBuffer = buffer.splice(0, buffer.length);
+      const fromInflight = inflightExitBatch ? [...inflightExitBatch] : [];
+      const events = [...fromInflight, ...fromBuffer];
+      if (!events.length) return;
+      try {
+        const result = opts.exitBatchSink(events);
+        if (result != null && typeof result.catch === "function") {
+          void result.catch(() => {
+            buffer.unshift(...events);
+          });
+        }
+      } catch {
+        buffer.unshift(...events);
+      }
+    } : void 0,
     dispose: () => {
       if (disposed || disposing) return Promise.resolve();
       disposing = true;
@@ -1109,16 +1129,16 @@ function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
   return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
 function resetSharedVolatileSessionIdForTests() {
   sharedVolatileSessionId = null;
@@ -1140,19 +1160,29 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 }
 
 // src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Set();
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
   if (alreadyEmittedToSink) {
     return { emitted: true, marked };
   }
-  const emitted = deps.emitCourseStartedEvent(ctx);
-  if (emitted && !marked) {
-    markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmitFlights.has(flightKey)) {
+    return { emitted: false, marked };
+  }
+  courseStartedEmitFlights.add(flightKey);
+  try {
+    const emitted = deps.emitCourseStartedEvent(ctx);
+    if (emitted && !marked) {
+      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    }
+    return {
+      emitted,
+      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    };
+  } finally {
+    courseStartedEmitFlights.delete(flightKey);
   }
-  return {
-    emitted,
-    marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
-  };
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",