@lessonkit/core 1.3.1 → 1.5.0

package/dist/chunk-KFXFQ6B2.js

@@ -0,0 +1,813 @@
+// src/identityTypes.ts
+var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+var ID_MAX_LENGTH = 64;
+
+// src/validateId.ts
+function validateId(input, path = "id") {
+  if (typeof input !== "string") {
+    return { ok: false, issues: [{ path, message: "id must be a string" }] };
+  }
+  const id = input.trim();
+  if (!id.length) {
+    return { ok: false, issues: [{ path, message: "id must not be empty" }] };
+  }
+  if (id.length > ID_MAX_LENGTH) {
+    return {
+      ok: false,
+      issues: [{ path, message: `id must be at most ${ID_MAX_LENGTH} characters` }]
+    };
+  }
+  if (!ID_PATTERN.test(id)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path,
+          message: "id must start with a letter and contain only letters, digits, underscores, and hyphens"
+        }
+      ]
+    };
+  }
+  return { ok: true, id };
+}
+function parseCourseId(input) {
+  const result = validateId(input, "courseId");
+  return result.ok ? result.id : null;
+}
+function parseLessonId(input) {
+  const result = validateId(input, "lessonId");
+  return result.ok ? result.id : null;
+}
+function parseCheckId(input) {
+  const result = validateId(input, "checkId");
+  return result.ok ? result.id : null;
+}
+function parseBlockId(input) {
+  const result = validateId(input, "blockId");
+  return result.ok ? result.id : null;
+}
+function assertValidId(input, path = "id") {
+  const result = validateId(input, path);
+  if (!result.ok) {
+    throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+  }
+  return result.id;
+}
+
+// src/ids.ts
+function randomSessionIdFallback() {
+  const g = globalThis;
+  if (g.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  throw new Error(
+    "[lessonkit] createSessionId requires crypto.randomUUID or crypto.getRandomValues"
+  );
+}
+function createSessionId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return randomSessionIdFallback();
+}
+
+// src/time.ts
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/internal/env.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnDev(message, err) {
+  if (!isDevEnvironment()) return;
+  console.warn(message, err instanceof Error ? err.message : err);
+}
+
+// src/telemetry/eventRegistry.ts
+function resolveLessonId(opts, eventName) {
+  const lessonId = opts.lessonId ?? opts.data?.lessonId;
+  if (!lessonId) throw new Error(`${eventName} requires lessonId`);
+  return lessonId;
+}
+function withLessonScopedData(name, base, lessonId, data) {
+  return { name, ...base, lessonId, data: { ...data, lessonId } };
+}
+var TELEMETRY_EVENT_REGISTRY = {
+  course_started: {
+    build: (_opts, base) => ({ name: "course_started", ...base })
+  },
+  course_completed: {
+    build: (_opts, base) => ({ name: "course_completed", ...base })
+  },
+  lesson_started: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_started") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, "lesson_started");
+      return withLessonScopedData("lesson_started", base, lessonId, opts.data);
+    }
+  },
+  lesson_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_completed") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  lesson_time_on_task: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_time_on_task") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  quiz_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_answered") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
+      return {
+        name: "quiz_answered",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  quiz_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
+      return {
+        name: "quiz_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  assessment_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_answered") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
+      return {
+        name: "assessment_answered",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  assessment_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
+      return {
+        name: "assessment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  interaction: {
+    build: (opts, base) => {
+      if (opts.name !== "interaction") throw new Error("unexpected event");
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  book_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "book_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("book_page_viewed requires active lessonId");
+      return {
+        name: "book_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  slide_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "slide_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("slide_viewed requires active lessonId");
+      return {
+        name: "slide_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  compound_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "compound_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("compound_page_viewed requires active lessonId");
+      return {
+        name: "compound_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  hotspot_opened: {
+    build: (opts, base) => {
+      if (opts.name !== "hotspot_opened") throw new Error("unexpected event");
+      return {
+        name: "hotspot_opened",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  accordion_section_toggled: {
+    build: (opts, base) => {
+      if (opts.name !== "accordion_section_toggled") throw new Error("unexpected event");
+      return {
+        name: "accordion_section_toggled",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  flashcard_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "flashcard_flipped") throw new Error("unexpected event");
+      return {
+        name: "flashcard_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  image_slider_changed: {
+    build: (opts, base) => {
+      if (opts.name !== "image_slider_changed") throw new Error("unexpected event");
+      return {
+        name: "image_slider_changed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  video_cue_reached: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_cue_reached") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_cue_reached requires active lessonId");
+      return {
+        name: "video_cue_reached",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  video_segment_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_segment_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_segment_completed requires active lessonId");
+      return {
+        name: "video_segment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  memory_card_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "memory_card_flipped") throw new Error("unexpected event");
+      return {
+        name: "memory_card_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  information_wall_search: {
+    build: (opts, base) => {
+      if (opts.name !== "information_wall_search") throw new Error("unexpected event");
+      return {
+        name: "information_wall_search",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  parallax_slide_viewed: {
+    build: (opts, base) => {
+      if (opts.name !== "parallax_slide_viewed") throw new Error("unexpected event");
+      return {
+        name: "parallax_slide_viewed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  questionnaire_submitted: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "questionnaire_submitted") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("questionnaire_submitted requires active lessonId");
+      return {
+        name: "questionnaire_submitted",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  branch_node_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_node_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_node_viewed requires active lessonId");
+      return {
+        name: "branch_node_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  branch_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_selected requires active lessonId");
+      return {
+        name: "branch_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  }
+};
+function buildTelemetryEventFromRegistry(opts) {
+  const entry = TELEMETRY_EVENT_REGISTRY[opts.name];
+  if (!entry) {
+    throw new Error("Unexpected value");
+  }
+  const base = {
+    timestamp: opts.timestamp ?? nowIso(),
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  };
+  return entry.build(opts, base);
+}
+function getTelemetryEventRegistryEntry(name) {
+  return TELEMETRY_EVENT_REGISTRY[name];
+}
+
+// src/telemetryBuilder.ts
+var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
+function resetTelemetryBuilderWarningsForTests() {
+  warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
+}
+function buildTelemetryEvent(opts) {
+  return buildTelemetryEventFromRegistry(opts);
+}
+function tryBuildTelemetryEvent(opts) {
+  const entry = getTelemetryEventRegistryEntry(opts.name);
+  if (entry.requiresLessonId && !opts.lessonId) {
+    if (isDevEnvironment() && entry.tryBuildMissingLessonWarning) {
+      if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
+        warnedMissingQuizLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+        );
+      }
+      if (entry.tryBuildMissingLessonWarning === "assessment" && !warnedMissingAssessmentLesson) {
+        warnedMissingAssessmentLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
+        );
+      }
+    }
+    return null;
+  }
+  return buildTelemetryEvent(opts);
+}
+
+// src/ports.ts
+function createDefaultClock() {
+  return {
+    nowMs: () => Date.now(),
+    nowIso: () => (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createNoopStorage() {
+  const memory = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+      return true;
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
+  };
+}
+function createMemoryBackedSessionStorage(session) {
+  const memory = /* @__PURE__ */ new Map();
+  const tombstones = /* @__PURE__ */ new Set();
+  let warnedPersistFailure = false;
+  const syncFromStorageEvent = (key, newValue) => {
+    if (key === null) {
+      memory.clear();
+      tombstones.clear();
+      return;
+    }
+    tombstones.delete(key);
+    if (newValue === null) {
+      memory.delete(key);
+    } else {
+      memory.set(key, newValue);
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("storage", (event) => {
+      if (event.storageArea !== sessionStorage) return;
+      syncFromStorageEvent(event.key, event.newValue);
+    });
+  }
+  const warnPersistFailure = () => {
+    if (warnedPersistFailure) return;
+    warnedPersistFailure = true;
+    const g = globalThis;
+    if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "development") {
+      console.warn(
+        "[lessonkit] sessionStorage is unavailable or failed; using in-memory session dedupe for this tab (may reset on full reload)."
+      );
+    }
+  };
+  return {
+    getItem: (key) => {
+      if (tombstones.has(key)) return null;
+      if (memory.has(key)) return memory.get(key);
+      try {
+        const value = session.getItem(key);
+        if (value !== null) memory.set(key, value);
+        return value;
+      } catch {
+        return memory.get(key) ?? null;
+      }
+    },
+    setItem: (key, value) => {
+      tombstones.delete(key);
+      memory.set(key, value);
+      try {
+        session.setItem(key, value);
+        return true;
+      } catch {
+        warnPersistFailure();
+        return false;
+      }
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+      try {
+        session.removeItem(key);
+        tombstones.delete(key);
+      } catch {
+        warnPersistFailure();
+        tombstones.add(key);
+      }
+    },
+    resetForTests: () => {
+      memory.clear();
+      tombstones.clear();
+    }
+  };
+}
+function resetStoragePortForTests(storage) {
+  storage.resetForTests?.();
+}
+function createInMemorySessionStoragePort() {
+  const memory = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+      return true;
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
+  };
+}
+function resolveBrowserSessionStorage() {
+  try {
+    if (typeof sessionStorage === "undefined" || sessionStorage == null) {
+      return null;
+    }
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function createSessionStoragePort() {
+  const session = resolveBrowserSessionStorage();
+  if (!session) {
+    return createInMemorySessionStoragePort();
+  }
+  return createMemoryBackedSessionStorage(session);
+}
+function createGlobalTimer() {
+  return {
+    setInterval: (fn, ms) => globalThis.setInterval(fn, ms),
+    clearInterval: (id) => globalThis.clearInterval(id)
+  };
+}
+
+// src/session.ts
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function getTabSessionId(storage) {
+  return storage.getItem(SESSION_STORAGE_KEY);
+}
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+var COURSE_STARTED_TRACKING_PREFIX = "lessonkit:course_started_tracking:";
+var COURSE_STARTED_PIPELINE_PREFIX = "lessonkit:course_started_pipeline:";
+var COURSE_STARTED_XAPI_PREFIX = "lessonkit:course_started_xapi:";
+function sessionKeySegment(sessionId) {
+  const validated = validateId(sessionId);
+  return validated.ok ? validated.id : encodeURIComponent(sessionId);
+}
+function resolveSessionId(storage, provided) {
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+    }
+  }
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
+  if (existing) return existing;
+  const volatile = volatileSessionIds.get(storage);
+  if (volatile) return volatile;
+  const id = createSessionId();
+  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
+  if (!persisted) {
+    volatileSessionIds.set(storage, id);
+    if (isDevEnvironment2()) {
+      console.warn(
+        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
+      );
+    }
+    return id;
+  }
+  return id;
+}
+function courseStartedStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function courseStartedTrackingStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function courseStartedPipelineStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function courseStartedXapiStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_XAPI_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function hasCourseStarted(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStarted(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+}
+function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
+  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 false;
+  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+}
+function hasCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+}
+function resetSharedVolatileSessionIdForTests() {
+}
+function migrateStorageMark(storage, fromKey, toKey, hasMark) {
+  if (!hasMark) return;
+  if (storage.setItem(toKey, "1")) {
+    storage.removeItem?.(fromKey);
+  }
+}
+function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
+  if (!courseId || fromSessionId === toSessionId) return;
+  migrateStorageMark(
+    storage,
+    courseStartedStorageKey(fromSessionId, courseId),
+    courseStartedStorageKey(toSessionId, courseId),
+    hasCourseStarted(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedTrackingStorageKey(fromSessionId, courseId),
+    courseStartedTrackingStorageKey(toSessionId, courseId),
+    hasCourseStartedEmittedToTracking(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedPipelineStorageKey(fromSessionId, courseId),
+    courseStartedPipelineStorageKey(toSessionId, courseId),
+    hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedXapiStorageKey(fromSessionId, courseId),
+    courseStartedXapiStorageKey(toSessionId, courseId),
+    hasCourseStartedXapiSent(storage, fromSessionId, courseId)
+  );
+}
+
+// src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+function resetCourseStartedEmitFlightForTests() {
+  courseStartedEmitFlights.clear();
+}
+function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
+  const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (alreadyEmittedToSink) {
+    return Promise.resolve({ emitted: true, marked });
+  }
+  const existing = courseStartedEmitFlights.get(flightKey);
+  if (existing) {
+    return existing;
+  }
+  const flight = Promise.resolve().then(() => {
+    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)
+      };
+    } catch {
+      return { emitted: false, marked };
+    } finally {
+      if (courseStartedEmitFlights.get(flightKey) === flight) {
+        courseStartedEmitFlights.delete(flightKey);
+      }
+    }
+  });
+  courseStartedEmitFlights.set(flightKey, flight);
+  return flight;
+}
+function buildCourseStartedTelemetryEvent(ctx) {
+  return buildTelemetryEvent({
+    name: "course_started",
+    courseId: ctx.courseId,
+    sessionId: ctx.sessionId,
+    attemptId: ctx.attemptId,
+    user: ctx.user
+  });
+}
+function completeLessonWithTelemetry(opts) {
+  const result = opts.progress.completeLesson(opts.lessonId, opts.nowMs);
+  if (!result.didComplete) return false;
+  opts.emitLessonCompleted(opts.lessonId, result.durationMs);
+  return true;
+}
+function completeCourseWithTelemetry(opts) {
+  const current = opts.progress.getState();
+  if (current.activeLessonId) {
+    completeLessonWithTelemetry({
+      progress: opts.progress,
+      lessonId: current.activeLessonId,
+      nowMs: opts.nowMs,
+      emitLessonCompleted: opts.emitLessonCompleted
+    });
+  }
+  const result = opts.progress.completeCourse();
+  if (!result.didComplete) return false;
+  opts.emitCourseCompleted();
+  return true;
+}
+
+export {
+  ID_PATTERN,
+  ID_MAX_LENGTH,
+  validateId,
+  parseCourseId,
+  parseLessonId,
+  parseCheckId,
+  parseBlockId,
+  assertValidId,
+  isDevEnvironment,
+  warnDev,
+  createSessionId,
+  nowIso,
+  resetTelemetryBuilderWarningsForTests,
+  buildTelemetryEvent,
+  tryBuildTelemetryEvent,
+  createDefaultClock,
+  createNoopStorage,
+  resetStoragePortForTests,
+  createSessionStoragePort,
+  createGlobalTimer,
+  SESSION_STORAGE_KEY,
+  getTabSessionId,
+  resolveSessionId,
+  hasCourseStarted,
+  markCourseStarted,
+  hasCourseStartedEmittedToTracking,
+  markCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
+  markCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
+  markCourseStartedXapiSent,
+  resetSharedVolatileSessionIdForTests,
+  migrateCourseStartedMark,
+  resetCourseStartedEmitFlightForTests,
+  tryEmitCourseStarted,
+  buildCourseStartedTelemetryEvent,
+  completeLessonWithTelemetry,
+  completeCourseWithTelemetry
+};