@lessonkit/core 0.8.1 → 0.9.1

package/dist/index.cjs

@@ -26,8 +26,10 @@ __export(index_exports, {
   assertValidId: () => assertValidId,
   buildLessonkitUrn: () => buildLessonkitUrn,
   buildTelemetryCatalog: () => buildTelemetryCatalog,
+  createPluginHost: () => createPluginHost,
   createSessionId: () => createSessionId,
   createTrackingClient: () => createTrackingClient,
+  defineLessonkitPlugin: () => defineLessonkitPlugin,
   deriveId: () => deriveId,
   nowIso: () => nowIso,
   slugifyId: () => slugifyId,
@@ -273,6 +275,74 @@ function createSessionId() {
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+
+// src/plugins.ts
+function defineLessonkitPlugin(plugin) {
+  return plugin;
+}
+function warnDuplicatePlugin(id) {
+  const g = globalThis;
+  if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
+  console.warn(`[lessonkit] plugin id "${id}" was registered more than once; using the latest definition`);
+}
+function createPluginHost(plugins = []) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const plugin of plugins) {
+    if (registry.has(plugin.id)) warnDuplicatePlugin(plugin.id);
+    registry.set(plugin.id, plugin);
+  }
+  const list = [...registry.values()];
+  const setupAll = (ctx) => {
+    for (const plugin of list) {
+      plugin.setup?.(ctx);
+    }
+  };
+  const disposeAll = () => {
+    for (let i = list.length - 1; i >= 0; i -= 1) {
+      list[i]?.dispose?.();
+    }
+  };
+  const runTelemetry = (event, ctx) => {
+    let current = event;
+    for (const plugin of list) {
+      if (!plugin.onTelemetry || current === null) continue;
+      current = plugin.onTelemetry(current, ctx);
+    }
+    return current;
+  };
+  const runTelemetryBatch = (events, ctx) => {
+    const filtered = events.map((event) => runTelemetry(event, ctx)).filter((event) => event !== null);
+    for (const plugin of list) {
+      plugin.onTelemetryBatch?.(filtered, ctx);
+    }
+    return filtered;
+  };
+  const composeTrackingSink = (sink, ctx) => {
+    let composed = sink;
+    for (const plugin of list) {
+      if (!plugin.wrapTrackingSink || !composed) continue;
+      composed = plugin.wrapTrackingSink(composed, ctx);
+    }
+    return composed;
+  };
+  const scoreAssessment = (input, ctx) => {
+    for (const plugin of list) {
+      if (plugin.kind !== "assessment" || !plugin.scoreAssessment) continue;
+      const result = plugin.scoreAssessment(input, ctx);
+      if (result) return result;
+    }
+    return null;
+  };
+  return {
+    plugins: list,
+    setupAll,
+    disposeAll,
+    runTelemetry,
+    runTelemetryBatch,
+    composeTrackingSink,
+    scoreAssessment
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ID_MAX_LENGTH,
@@ -281,8 +351,10 @@ function nowIso() {
   assertValidId,
   buildLessonkitUrn,
   buildTelemetryCatalog,
+  createPluginHost,
   createSessionId,
   createTrackingClient,
+  defineLessonkitPlugin,
   deriveId,
   nowIso,
   slugifyId,

package/dist/index.d.cts

@@ -143,4 +143,65 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-export { type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitUrnParts, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createSessionId, createTrackingClient, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };
+/** Plugin category — aligns with roadmap extension areas. */
+type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
+type LessonkitPluginContext = {
+    courseId: CourseId;
+    sessionId?: string;
+    attemptId?: string;
+};
+type AssessmentScoreInput = {
+    checkId: string;
+    lessonId?: string;
+    response: unknown;
+};
+type AssessmentScoreResult = {
+    score: number;
+    maxScore?: number;
+    passed?: boolean;
+    feedback?: string;
+};
+/** Metadata for custom interaction blocks (renderer wiring stays in app code until 1.0). */
+type InteractionBlockRegistration = {
+    blockType: string;
+    catalogVersion?: string;
+    description?: string;
+};
+/**
+ * Framework plugin contract (v1). Plugins are plain objects registered on `LessonkitProvider`.
+ * Marketplace / dynamic loading are out of scope until Studio post-1.0.
+ */
+type LessonkitPlugin = {
+    id: string;
+    version: string;
+    kind: LessonkitPluginKind;
+    name?: string;
+    setup?: (ctx: LessonkitPluginContext) => void;
+    dispose?: () => void;
+    /**
+     * Observe or filter telemetry before tracking/xAPI. Return `null` to drop the event.
+     * Hooks run in registration order.
+     */
+    onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
+    /** Optional batch observer (analytics); receives events after per-event hooks. */
+    onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
+    /** Wrap the configured tracking sink (analytics plugins). First registered = innermost. */
+    wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
+    /** Optional assessment scoring override (assessment plugins). */
+    scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
+    /** Declare custom interaction block types for generators/tooling. */
+    interactionBlocks?: InteractionBlockRegistration[];
+};
+type PluginHost = {
+    readonly plugins: readonly LessonkitPlugin[];
+    setupAll: (ctx: LessonkitPluginContext) => void;
+    disposeAll: () => void;
+    runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
+    runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
+};
+declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;
+declare function createPluginHost(plugins?: readonly LessonkitPlugin[]): PluginHost;
+
+export { type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitUrnParts, type PluginHost, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createPluginHost, createSessionId, createTrackingClient, defineLessonkitPlugin, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };

package/dist/index.d.ts

@@ -143,4 +143,65 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-export { type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitUrnParts, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createSessionId, createTrackingClient, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };
+/** Plugin category — aligns with roadmap extension areas. */
+type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
+type LessonkitPluginContext = {
+    courseId: CourseId;
+    sessionId?: string;
+    attemptId?: string;
+};
+type AssessmentScoreInput = {
+    checkId: string;
+    lessonId?: string;
+    response: unknown;
+};
+type AssessmentScoreResult = {
+    score: number;
+    maxScore?: number;
+    passed?: boolean;
+    feedback?: string;
+};
+/** Metadata for custom interaction blocks (renderer wiring stays in app code until 1.0). */
+type InteractionBlockRegistration = {
+    blockType: string;
+    catalogVersion?: string;
+    description?: string;
+};
+/**
+ * Framework plugin contract (v1). Plugins are plain objects registered on `LessonkitProvider`.
+ * Marketplace / dynamic loading are out of scope until Studio post-1.0.
+ */
+type LessonkitPlugin = {
+    id: string;
+    version: string;
+    kind: LessonkitPluginKind;
+    name?: string;
+    setup?: (ctx: LessonkitPluginContext) => void;
+    dispose?: () => void;
+    /**
+     * Observe or filter telemetry before tracking/xAPI. Return `null` to drop the event.
+     * Hooks run in registration order.
+     */
+    onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
+    /** Optional batch observer (analytics); receives events after per-event hooks. */
+    onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
+    /** Wrap the configured tracking sink (analytics plugins). First registered = innermost. */
+    wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
+    /** Optional assessment scoring override (assessment plugins). */
+    scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
+    /** Declare custom interaction block types for generators/tooling. */
+    interactionBlocks?: InteractionBlockRegistration[];
+};
+type PluginHost = {
+    readonly plugins: readonly LessonkitPlugin[];
+    setupAll: (ctx: LessonkitPluginContext) => void;
+    disposeAll: () => void;
+    runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
+    runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
+};
+declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;
+declare function createPluginHost(plugins?: readonly LessonkitPlugin[]): PluginHost;
+
+export { type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type CheckId, type CourseId, ID_MAX_LENGTH, ID_PATTERN, type IdentityValidationIssue, type IdentityValidationResult, type InteractionBlockRegistration, type InteractionData, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitUrnParts, type PluginHost, type QuizAnsweredData, type QuizCompletedData, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetrySink, type TelemetryUser, type TrackingClient, assertValidId, buildLessonkitUrn, buildTelemetryCatalog, createPluginHost, createSessionId, createTrackingClient, defineLessonkitPlugin, deriveId, nowIso, slugifyId, telemetryCatalogVersion, validateId };

package/dist/index.js

@@ -235,6 +235,74 @@ function createSessionId() {
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+
+// src/plugins.ts
+function defineLessonkitPlugin(plugin) {
+  return plugin;
+}
+function warnDuplicatePlugin(id) {
+  const g = globalThis;
+  if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
+  console.warn(`[lessonkit] plugin id "${id}" was registered more than once; using the latest definition`);
+}
+function createPluginHost(plugins = []) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const plugin of plugins) {
+    if (registry.has(plugin.id)) warnDuplicatePlugin(plugin.id);
+    registry.set(plugin.id, plugin);
+  }
+  const list = [...registry.values()];
+  const setupAll = (ctx) => {
+    for (const plugin of list) {
+      plugin.setup?.(ctx);
+    }
+  };
+  const disposeAll = () => {
+    for (let i = list.length - 1; i >= 0; i -= 1) {
+      list[i]?.dispose?.();
+    }
+  };
+  const runTelemetry = (event, ctx) => {
+    let current = event;
+    for (const plugin of list) {
+      if (!plugin.onTelemetry || current === null) continue;
+      current = plugin.onTelemetry(current, ctx);
+    }
+    return current;
+  };
+  const runTelemetryBatch = (events, ctx) => {
+    const filtered = events.map((event) => runTelemetry(event, ctx)).filter((event) => event !== null);
+    for (const plugin of list) {
+      plugin.onTelemetryBatch?.(filtered, ctx);
+    }
+    return filtered;
+  };
+  const composeTrackingSink = (sink, ctx) => {
+    let composed = sink;
+    for (const plugin of list) {
+      if (!plugin.wrapTrackingSink || !composed) continue;
+      composed = plugin.wrapTrackingSink(composed, ctx);
+    }
+    return composed;
+  };
+  const scoreAssessment = (input, ctx) => {
+    for (const plugin of list) {
+      if (plugin.kind !== "assessment" || !plugin.scoreAssessment) continue;
+      const result = plugin.scoreAssessment(input, ctx);
+      if (result) return result;
+    }
+    return null;
+  };
+  return {
+    plugins: list,
+    setupAll,
+    disposeAll,
+    runTelemetry,
+    runTelemetryBatch,
+    composeTrackingSink,
+    scoreAssessment
+  };
+}
 export {
   ID_MAX_LENGTH,
   ID_PATTERN,
@@ -242,8 +310,10 @@ export {
   assertValidId,
   buildLessonkitUrn,
   buildTelemetryCatalog,
+  createPluginHost,
   createSessionId,
   createTrackingClient,
+  defineLessonkitPlugin,
   deriveId,
   nowIso,
   slugifyId,

package/package.json

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