@lessonkit/lxpack 1.4.0 → 1.6.0

package/dist/bridge.d.ts

@@ -1,9 +1,23 @@
 import { LmsBridgeMode, TelemetryEvent, CheckId, LessonId } from '@lessonkit/core';
 import { LxpackBridgeV1, LxpackBridgeSubmitAssessmentPayload } from '@lxpack/spa-bridge';
-export { DEFAULT_BRIDGE_PASSING_SCORE, LXPACK_BRIDGE_VERSIONS, LxpackBridgeSubmitAssessmentPayload, LxpackBridgeV1, createLxpackBridgeHost, getLxpackBridge, normalizePassingThreshold, normalizeScore, supportedBridgeVersions } from '@lxpack/spa-bridge';
+export { DEFAULT_BRIDGE_PASSING_SCORE, LXPACK_BRIDGE_VERSIONS, LxpackBridgeSubmitAssessmentPayload, LxpackBridgeV1, createLxpackBridgeHost, supportedBridgeVersions } from '@lxpack/spa-bridge';
 import { mapLessonkitTelemetryToBridgeAction } from '@lxpack/tracking-schema';
 export { LESSONKIT_TELEMETRY_EVENTS, LessonkitBridgeAction, LessonkitTelemetryEvent, LessonkitTelemetryEventName, TrackingSchemaEvent, mapLessonkitTelemetryToBridgeAction, mapLessonkitTelemetryToLxpack } from '@lxpack/tracking-schema';
-export { t as telemetryEventToLessonkit } from './telemetry-gCxlwc7I.js';
+export { B as BRANCH_TELEMETRY_EVENTS, b as branchTelemetryToBridgeTrackEvent, t as telemetryEventToLessonkit } from './telemetry-0fIWoomS.js';
+
+/**
+ * Scale a raw quiz score to 0–1 for the LXPack parent bridge.
+ * When `maxScore > 1`, always treats `score` as raw points (fixes partial-credit 1/N cases).
+ */
+declare function normalizeScore(raw: {
+    score?: number;
+    maxScore?: number;
+}): number | null;
+/** Scale a raw passing threshold to 0–1 for the LXPack parent bridge. */
+declare function normalizePassingThreshold(raw?: {
+    passingScore?: number;
+    maxScore?: number;
+}): number;
 
 /**
  * Scale a raw quiz score to 0–1 for the LXPack parent bridge.
@@ -15,26 +29,60 @@ declare function normalizeAssessmentScore(opts: {
 }): number | null;
 /**
  * Scale a raw passing threshold to 0–1 for the LXPack parent bridge.
- * Delegates to `@lxpack/spa-bridge` (default 0.7 when omitted).
+ * Default 1.0 (100%) when omitted — matches React SPA default.
  */
 declare function normalizeAssessmentPassingScore(opts?: {
     passingScore?: number;
     maxScore?: number;
 }): number;
+type BridgeAccessOptions = {
+    /** Allowed parent-frame origins (scheme + host + port). When set, bridge calls require a matching origin. */
+    allowedParentOrigins?: string[];
+    /** LMS bridge mode; `"auto"` in production requires `allowedParentOrigins`. */
+    mode?: LxpackBridgeMode;
+    onBridgeError?: (err: unknown) => void;
+};
+/** Resolve the parent frame origin when embedded (same-origin parent or document.referrer fallback). */
+declare function resolveParentOrigin(parentWindow?: Window): string | null;
+/** Returns true when no allowlist is configured or the resolved parent origin is listed. */
+declare function isParentOriginAllowed(allowedParentOrigins: string[] | undefined, parentWindow?: Window, mode?: LxpackBridgeMode): boolean;
+/** Resolve the LXPack parent bridge when the parent origin passes validation. */
+declare function getLxpackBridge(parentWindow?: Window, opts?: BridgeAccessOptions): LxpackBridgeV1 | null;
 /** @deprecated Use `LmsBridgeMode` from `@lessonkit/core`. */
 type LxpackBridgeMode = LmsBridgeMode;
 /** Apply a mapped bridge action to an LXPack bridge instance. */
-declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>): void;
-declare function forwardTelemetryToBridge(event: TelemetryEvent, mode?: LxpackBridgeMode, parentWindow?: Window): void;
-declare function createLxpackBridge(): LxpackBridgeV1 | null;
-declare function notifyLxpackLessonComplete(lessonId: LessonId): boolean;
-declare function notifyLxpackCourseComplete(): boolean;
+declare function dispatchBridgeAction(bridge: LxpackBridgeV1, action: ReturnType<typeof mapLessonkitTelemetryToBridgeAction>, opts?: {
+    onBridgeError?: (err: unknown) => void;
+}): void;
+type ForwardTelemetryToBridgeOptions = {
+    onBridgeError?: (err: unknown) => void;
+    /** Called when assessment_completed cannot be forwarded (e.g. missing/invalid score). */
+    onBridgeMiss?: (event: TelemetryEvent) => void;
+    allowedParentOrigins?: string[];
+};
+/**
+ * Map a LessonKit telemetry event to LMS bridge actions (`track`, `complete`, assessment score).
+ *
+ * @example
+ * ```ts
+ * import { forwardTelemetryToBridge } from "@lessonkit/lxpack/bridge";
+ *
+ * forwardTelemetryToBridge(event, "auto", window.parent, {
+ *   allowedParentOrigins: ["https://lms.example.com"],
+ *   onBridgeMiss: (e) => console.warn("bridge miss", e.name),
+ * });
+ * ```
+ */
+declare function forwardTelemetryToBridge(event: TelemetryEvent, mode?: LxpackBridgeMode, parentWindow?: Window, opts?: ForwardTelemetryToBridgeOptions): void;
+declare function createLxpackBridge(opts?: BridgeAccessOptions): LxpackBridgeV1 | null;
+declare function notifyLxpackLessonComplete(lessonId: LessonId, opts?: BridgeAccessOptions): boolean;
+declare function notifyLxpackCourseComplete(opts?: BridgeAccessOptions): boolean;
 /**
  * Submit assessment results to the parent LXPack bridge.
- * `score` must already be on a 0–1 scale (use `normalizeAssessmentScore` for raw points).
+ * Raw point scores are normalized to 0–1 before submission.
  */
 declare function notifyLxpackAssessment(payload: LxpackBridgeSubmitAssessmentPayload & {
     id: CheckId;
-}): boolean;
+}, opts?: BridgeAccessOptions): boolean;
 
-export { type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, normalizeAssessmentPassingScore, normalizeAssessmentScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete };
+export { type BridgeAccessOptions, type ForwardTelemetryToBridgeOptions, type LxpackBridgeMode, createLxpackBridge, dispatchBridgeAction, forwardTelemetryToBridge, getLxpackBridge, isParentOriginAllowed, normalizeAssessmentPassingScore, normalizeAssessmentScore, normalizePassingThreshold, normalizeScore, notifyLxpackAssessment, notifyLxpackCourseComplete, notifyLxpackLessonComplete, resolveParentOrigin };

package/dist/bridge.js

@@ -1,20 +1,18 @@
 import {
+  BRANCH_TELEMETRY_EVENTS,
+  answeredTelemetryToBridgeTrackEvent,
+  branchTelemetryToBridgeTrackEvent,
   telemetryEventToLessonkit
-} from "./chunk-DYQI222N.js";
+} from "./chunk-HTZR4CF3.js";
 
 // src/bridge.ts
 import {
-  getLxpackBridge as getLxpackBridgeFromParent,
-  normalizePassingThreshold,
-  normalizeScore
+  getLxpackBridge as getLxpackBridgeFromParent
 } from "@lxpack/spa-bridge";
 import {
   createLxpackBridgeHost,
   DEFAULT_BRIDGE_PASSING_SCORE,
-  getLxpackBridge,
   LXPACK_BRIDGE_VERSIONS,
-  normalizePassingThreshold as normalizePassingThreshold2,
-  normalizeScore as normalizeScore2,
   supportedBridgeVersions
 } from "@lxpack/spa-bridge";
 import {
@@ -23,6 +21,37 @@ import {
   mapLessonkitTelemetryToLxpack
 } from "@lxpack/tracking-schema";
 import { mapLessonkitTelemetryToBridgeAction as mapLessonkitTelemetryToBridgeAction2 } from "@lxpack/tracking-schema";
+var DEFAULT_BRIDGE_PASSING_SCORE2 = 1;
+function clamp01(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function normalizeScore(raw) {
+  const { score, maxScore } = raw;
+  if (typeof score !== "number" || !Number.isFinite(score)) return null;
+  if (typeof maxScore === "number" && maxScore > 0) {
+    return clamp01(score / maxScore);
+  }
+  if (score > 1 && score <= 100) {
+    return clamp01(score / 100);
+  }
+  return clamp01(score);
+}
+function normalizePassingThreshold(raw) {
+  const { passingScore, maxScore } = raw ?? {};
+  if (typeof passingScore !== "number" || !Number.isFinite(passingScore)) {
+    return DEFAULT_BRIDGE_PASSING_SCORE2;
+  }
+  if (typeof maxScore === "number" && maxScore > 1) {
+    return clamp01(passingScore / maxScore);
+  }
+  if (typeof maxScore === "number" && maxScore <= 1) {
+    return clamp01(passingScore);
+  }
+  if (passingScore > 1 && passingScore <= 100) {
+    return clamp01(passingScore / 100);
+  }
+  return clamp01(passingScore);
+}
 function normalizeAssessmentScore(opts) {
   if (typeof opts.score !== "number" || !Number.isFinite(opts.score)) {
     return null;
@@ -35,7 +64,35 @@ function normalizeAssessmentPassingScore(opts) {
     maxScore: opts?.maxScore
   });
 }
-function getBridge(parentWindow) {
+function resolveParentOrigin(parentWindow) {
+  if (typeof window === "undefined") return null;
+  const parent = parentWindow ?? window.parent;
+  if (!parent || parent === window) return null;
+  try {
+    return parent.location.origin;
+  } catch {
+    return null;
+  }
+}
+function isProductionRuntime() {
+  try {
+    if (import.meta.env?.PROD === true) return true;
+  } catch {
+  }
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
+}
+function isParentOriginAllowed(allowedParentOrigins, parentWindow, mode) {
+  if (mode === "off") return false;
+  if (isProductionRuntime() && !allowedParentOrigins?.length) return false;
+  if (!allowedParentOrigins?.length) return true;
+  const origin = resolveParentOrigin(parentWindow);
+  if (!origin) return false;
+  return allowedParentOrigins.includes(origin);
+}
+function getBridge(parentWindow, opts) {
+  const mode = opts?.mode ?? "auto";
+  if (!isParentOriginAllowed(opts?.allowedParentOrigins, parentWindow, mode)) return null;
   const fromSdk = getLxpackBridgeFromParent(parentWindow);
   if (fromSdk) return fromSdk;
   if (typeof window === "undefined") return null;
@@ -43,21 +100,33 @@ function getBridge(parentWindow) {
   if (!parent || parent === window) return null;
   return parent.lxpackBridge?.v1 ?? parent.lxpack ?? null;
 }
+function getLxpackBridge(parentWindow, opts) {
+  return getBridge(parentWindow, opts);
+}
 function isDevEnvironment() {
+  try {
+    if (import.meta.env?.DEV === true) return true;
+    if (import.meta.env?.PROD === true) return false;
+  } catch {
+  }
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
-function dispatchBridgeAction(bridge, action) {
+function handleBridgeError(err, onBridgeError) {
+  onBridgeError?.(err);
+  if (isDevEnvironment()) {
+    console.warn(
+      "[lessonkit/lxpack] lxpack bridge action failed:",
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+function dispatchBridgeAction(bridge, action, opts) {
   if (!action) return;
   try {
     dispatchBridgeActionInner(bridge, action);
   } catch (err) {
-    if (isDevEnvironment()) {
-      console.warn(
-        "[lessonkit/lxpack] lxpack bridge action failed:",
-        err instanceof Error ? err.message : err
-      );
-    }
+    handleBridgeError(err, opts?.onBridgeError);
   }
 }
 function dispatchBridgeActionInner(bridge, action) {
@@ -93,13 +162,16 @@ function dispatchBridgeActionInner(bridge, action) {
       return;
   }
 }
-function forwardAssessmentCompletedToBridge(bridge, event) {
+function forwardAssessmentCompletedToBridge(bridge, event, onBridgeMiss) {
   const data = event.data;
   const scaled = normalizeAssessmentScore({
     score: data.score,
     maxScore: data.maxScore
   });
-  if (scaled === null) return;
+  if (scaled === null) {
+    onBridgeMiss?.(event);
+    return;
+  }
   bridge.submitAssessment?.({
     id: data.checkId,
     score: scaled,
@@ -110,58 +182,106 @@ function forwardAssessmentCompletedToBridge(bridge, event) {
     maxScore: data.maxScore
   });
 }
-function forwardTelemetryToBridge(event, mode = "auto", parentWindow) {
+function forwardTelemetryToBridge(event, mode = "auto", parentWindow, opts) {
   if (mode === "off") return;
-  const bridge = getBridge(parentWindow);
+  const bridge = getBridge(parentWindow, {
+    allowedParentOrigins: opts?.allowedParentOrigins,
+    mode
+  });
   if (!bridge) return;
-  if (event.name === "assessment_completed") {
-    forwardAssessmentCompletedToBridge(bridge, event);
-    return;
+  try {
+    if (event.name === "assessment_completed") {
+      forwardAssessmentCompletedToBridge(bridge, event, opts?.onBridgeMiss);
+      return;
+    }
+    const answeredTrack = answeredTelemetryToBridgeTrackEvent(event);
+    if (answeredTrack) {
+      bridge.track?.(answeredTrack);
+      return;
+    }
+    const branchTrack = branchTelemetryToBridgeTrackEvent(event);
+    if (branchTrack) {
+      bridge.track?.(branchTrack);
+      return;
+    }
+    const lessonkitEvent = telemetryEventToLessonkit(event);
+    if (!lessonkitEvent) return;
+    const action = mapLessonkitTelemetryToBridgeAction2(lessonkitEvent);
+    dispatchBridgeActionInner(bridge, action);
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
   }
-  const lessonkitEvent = telemetryEventToLessonkit(event);
-  if (!lessonkitEvent) return;
-  const action = mapLessonkitTelemetryToBridgeAction2(lessonkitEvent);
-  dispatchBridgeAction(bridge, action);
 }
-function createLxpackBridge() {
-  return getBridge();
+function createLxpackBridge(opts) {
+  return getBridge(void 0, opts);
 }
-function notifyLxpackLessonComplete(lessonId) {
-  const bridge = getBridge();
+function notifyLxpackLessonComplete(lessonId, opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.completeLesson) return false;
-  bridge.completeLesson(lessonId);
-  return true;
+  try {
+    bridge.completeLesson(lessonId);
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
-function notifyLxpackCourseComplete() {
-  const bridge = getBridge();
+function notifyLxpackCourseComplete(opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.completeCourse) return false;
-  bridge.completeCourse();
-  return true;
+  try {
+    bridge.completeCourse();
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
-function notifyLxpackAssessment(payload) {
-  const bridge = getBridge();
+function notifyLxpackAssessment(payload, opts) {
+  const bridge = getBridge(void 0, opts);
   if (!bridge?.submitAssessment) return false;
-  bridge.submitAssessment(payload);
-  return true;
+  const scaled = normalizeAssessmentScore({
+    score: payload.score,
+    maxScore: payload.maxScore
+  });
+  if (scaled === null) return false;
+  try {
+    bridge.submitAssessment({
+      ...payload,
+      score: scaled,
+      passingScore: normalizeAssessmentPassingScore({
+        passingScore: payload.passingScore,
+        maxScore: payload.maxScore
+      })
+    });
+    return true;
+  } catch (err) {
+    handleBridgeError(err, opts?.onBridgeError);
+    return false;
+  }
 }
 export {
+  BRANCH_TELEMETRY_EVENTS,
   DEFAULT_BRIDGE_PASSING_SCORE,
   LESSONKIT_TELEMETRY_EVENTS,
   LXPACK_BRIDGE_VERSIONS,
+  branchTelemetryToBridgeTrackEvent,
   createLxpackBridge,
   createLxpackBridgeHost,
   dispatchBridgeAction,
   forwardTelemetryToBridge,
   getLxpackBridge,
+  isParentOriginAllowed,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,
   normalizeAssessmentPassingScore,
   normalizeAssessmentScore,
-  normalizePassingThreshold2 as normalizePassingThreshold,
-  normalizeScore2 as normalizeScore,
+  normalizePassingThreshold,
+  normalizeScore,
   notifyLxpackAssessment,
   notifyLxpackCourseComplete,
   notifyLxpackLessonComplete,
+  resolveParentOrigin,
   supportedBridgeVersions,
   telemetryEventToLessonkit
 };

package/dist/chunk-HTZR4CF3.js

@@ -0,0 +1,94 @@
+// src/telemetry.ts
+import {
+  LESSONKIT_TELEMETRY_EVENTS,
+  mapLessonkitTelemetryToLxpack
+} from "@lxpack/tracking-schema";
+var BRANCH_TELEMETRY_EVENTS = ["branch_node_viewed", "branch_selected"];
+var ASSESSMENT_TELEMETRY_EVENTS = ["assessment_answered"];
+var SUPPORTED = /* @__PURE__ */ new Set([
+  ...LESSONKIT_TELEMETRY_EVENTS,
+  ...BRANCH_TELEMETRY_EVENTS,
+  ...ASSESSMENT_TELEMETRY_EVENTS
+]);
+function isQuizAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isQuizCompletedData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isAssessmentAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isInteractionData(data) {
+  return typeof data === "object" && data !== null;
+}
+function isBranchNodeViewedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.nodeId === "string";
+}
+function isBranchSelectedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.fromNodeId === "string" && typeof data.toNodeId === "string";
+}
+function telemetryEventToLessonkit(event) {
+  if (!SUPPORTED.has(event.name)) {
+    return null;
+  }
+  const mapped = {
+    name: event.name,
+    lessonId: event.lessonId
+  };
+  if (event.name === "quiz_completed" || event.name === "quiz_answered" || event.name === "assessment_answered") {
+    const data = event.data;
+    if (!isQuizAnsweredData(data) && !isQuizCompletedData(data) && !isAssessmentAnsweredData(data)) {
+      return null;
+    }
+    mapped.assessmentId = data.checkId;
+    if ("score" in data) {
+      mapped.score = data.score;
+      mapped.maxScore = data.maxScore;
+      mapped.passingScore = data.passingScore;
+    }
+    mapped.data = data;
+  } else if (mapped.name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
+    mapped.data = event.data;
+  }
+  return mapped;
+}
+function answeredTelemetryToBridgeTrackEvent(event) {
+  if (event.name !== "quiz_answered" && event.name !== "assessment_answered") {
+    return null;
+  }
+  const lessonkitEvent = telemetryEventToLessonkit(event);
+  if (!lessonkitEvent?.assessmentId) return null;
+  return mapLessonkitTelemetryToLxpack({
+    ...lessonkitEvent,
+    name: "quiz_answered"
+  });
+}
+function branchTelemetryToBridgeTrackEvent(event) {
+  if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    return {
+      type: "interaction",
+      id: "branch_node_viewed",
+      data: { ...event.data, lessonkitEvent: event.name }
+    };
+  }
+  if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
+    return {
+      type: "interaction",
+      id: "branch_selected",
+      data: { ...event.data, lessonkitEvent: event.name }
+    };
+  }
+  return null;
+}
+
+export {
+  BRANCH_TELEMETRY_EVENTS,
+  telemetryEventToLessonkit,
+  answeredTelemetryToBridgeTrackEvent,
+  branchTelemetryToBridgeTrackEvent
+};