@lessonkit/core 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,9 @@
 # `@lessonkit/core`
 
+[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml)
+[![npm](https://img.shields.io/npm/v/@lessonkit/core.svg)](https://www.npmjs.com/package/@lessonkit/core)
+[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](../../LICENSE)
+
 Core types and runtime primitives shared across LessonKit packages.
 
 ## Install
@@ -8,8 +12,9 @@ Core types and runtime primitives shared across LessonKit packages.
 npm install @lessonkit/core
 ```
 
-## What’s inside (0.1.x)
+## What’s inside (0.2.1)
 
 - Telemetry event types (`TelemetryEvent`)
-- A minimal tracking client (`createTrackingClient`)
+- A minimal tracking client (`createTrackingClient`) with optional batching
+- Session id helper (`createSessionId`)
 

package/dist/index.cjs

@@ -20,23 +20,90 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createSessionId: () => createSessionId,
   createTrackingClient: () => createTrackingClient,
   nowIso: () => nowIso
 });
 module.exports = __toCommonJS(index_exports);
 function createTrackingClient(opts) {
   const sink = opts?.sink;
+  const batchSink = opts?.batchSink;
+  const batchEnabled = opts?.batch?.enabled ?? Boolean(batchSink);
+  const flushIntervalMs = opts?.batch?.flushIntervalMs ?? 5e3;
+  const maxBatchSize = opts?.batch?.maxBatchSize ?? 25;
+  if (!batchEnabled) {
+    let disposed2 = false;
+    return {
+      track: (event) => {
+        if (disposed2) return;
+        void sink?.(event);
+      },
+      dispose: () => {
+        disposed2 = true;
+      }
+    };
+  }
+  if (!sink && !batchSink) {
+    return { track: () => {
+    } };
+  }
+  const buffer = [];
+  let flushInFlight = null;
+  let disposed = false;
+  let intervalId;
+  const flush = () => {
+    if (disposed || flushInFlight) return;
+    if (!buffer.length) return;
+    const events = buffer.splice(0, buffer.length);
+    let sent = 0;
+    let succeeded = false;
+    flushInFlight = Promise.resolve().then(async () => {
+      if (batchSink) {
+        await batchSink(events);
+      } else {
+        for (const e of events) {
+          await sink?.(e);
+          sent += 1;
+        }
+      }
+      succeeded = true;
+    }).catch(() => {
+      buffer.unshift(...events.slice(sent));
+    }).finally(() => {
+      flushInFlight = null;
+      if (succeeded && !disposed && buffer.length > 0) flush();
+    });
+  };
+  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(flush, flushIntervalMs) : void 0;
   return {
     track: (event) => {
-      void sink?.(event);
+      if (disposed) return;
+      buffer.push(event);
+      if (buffer.length >= maxBatchSize) flush();
+    },
+    flush,
+    dispose: () => {
+      if (disposed) return;
+      if (intervalId !== void 0) {
+        globalThis.clearInterval(intervalId);
+        intervalId = void 0;
+      }
+      flush();
+      disposed = true;
     }
   };
 }
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function createSessionId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createSessionId,
   createTrackingClient,
   nowIso
 });

package/dist/index.d.cts

@@ -1,20 +1,39 @@
 type CourseId = string;
 type LessonId = string;
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "quiz_answered" | "quiz_completed" | "interaction";
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
+type TelemetryUser = {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+};
 type TelemetryEvent = {
     name: TelemetryEventName;
     timestamp: string;
     courseId?: CourseId;
     lessonId?: LessonId;
+    sessionId?: string;
+    attemptId?: string;
+    user?: TelemetryUser;
     data?: Record<string, unknown>;
 };
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
+type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
+    flush?: () => void;
+    dispose?: () => void;
 };
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
+    batch?: {
+        enabled?: boolean;
+        flushIntervalMs?: number;
+        maxBatchSize?: number;
+    };
+    batchSink?: TelemetryBatchSink;
 }): TrackingClient;
 declare function nowIso(): string;
+declare function createSessionId(): string;
 
-export { type CourseId, type LessonId, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TrackingClient, createTrackingClient, nowIso };
+export { type CourseId, type LessonId, type TelemetryBatchSink, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, createSessionId, createTrackingClient, nowIso };

package/dist/index.d.ts

@@ -1,20 +1,39 @@
 type CourseId = string;
 type LessonId = string;
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "quiz_answered" | "quiz_completed" | "interaction";
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
+type TelemetryUser = {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+};
 type TelemetryEvent = {
     name: TelemetryEventName;
     timestamp: string;
     courseId?: CourseId;
     lessonId?: LessonId;
+    sessionId?: string;
+    attemptId?: string;
+    user?: TelemetryUser;
     data?: Record<string, unknown>;
 };
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
+type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
+    flush?: () => void;
+    dispose?: () => void;
 };
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
+    batch?: {
+        enabled?: boolean;
+        flushIntervalMs?: number;
+        maxBatchSize?: number;
+    };
+    batchSink?: TelemetryBatchSink;
 }): TrackingClient;
 declare function nowIso(): string;
+declare function createSessionId(): string;
 
-export { type CourseId, type LessonId, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TrackingClient, createTrackingClient, nowIso };
+export { type CourseId, type LessonId, type TelemetryBatchSink, type TelemetryEvent, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, createSessionId, createTrackingClient, nowIso };

package/dist/index.js

@@ -1,16 +1,82 @@
 // src/index.ts
 function createTrackingClient(opts) {
   const sink = opts?.sink;
+  const batchSink = opts?.batchSink;
+  const batchEnabled = opts?.batch?.enabled ?? Boolean(batchSink);
+  const flushIntervalMs = opts?.batch?.flushIntervalMs ?? 5e3;
+  const maxBatchSize = opts?.batch?.maxBatchSize ?? 25;
+  if (!batchEnabled) {
+    let disposed2 = false;
+    return {
+      track: (event) => {
+        if (disposed2) return;
+        void sink?.(event);
+      },
+      dispose: () => {
+        disposed2 = true;
+      }
+    };
+  }
+  if (!sink && !batchSink) {
+    return { track: () => {
+    } };
+  }
+  const buffer = [];
+  let flushInFlight = null;
+  let disposed = false;
+  let intervalId;
+  const flush = () => {
+    if (disposed || flushInFlight) return;
+    if (!buffer.length) return;
+    const events = buffer.splice(0, buffer.length);
+    let sent = 0;
+    let succeeded = false;
+    flushInFlight = Promise.resolve().then(async () => {
+      if (batchSink) {
+        await batchSink(events);
+      } else {
+        for (const e of events) {
+          await sink?.(e);
+          sent += 1;
+        }
+      }
+      succeeded = true;
+    }).catch(() => {
+      buffer.unshift(...events.slice(sent));
+    }).finally(() => {
+      flushInFlight = null;
+      if (succeeded && !disposed && buffer.length > 0) flush();
+    });
+  };
+  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(flush, flushIntervalMs) : void 0;
   return {
     track: (event) => {
-      void sink?.(event);
+      if (disposed) return;
+      buffer.push(event);
+      if (buffer.length >= maxBatchSize) flush();
+    },
+    flush,
+    dispose: () => {
+      if (disposed) return;
+      if (intervalId !== void 0) {
+        globalThis.clearInterval(intervalId);
+        intervalId = void 0;
+      }
+      flush();
+      disposed = true;
     }
   };
 }
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function createSessionId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
 export {
+  createSessionId,
   createTrackingClient,
   nowIso
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -40,6 +40,7 @@
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests=false",
     "lint": "echo \"(no lint configured yet)\""
   },
   "devDependencies": {