@playcademy/vite-plugin 0.3.2 → 0.3.3-beta.2

package/dist/index.js

@@ -23746,7 +23746,7 @@ import path from "node:path";
 // package.json
 var package_default = {
   name: "@playcademy/vite-plugin",
-  version: "0.3.2",
+  version: "0.3.3-beta.2",
   type: "module",
   exports: {
     ".": {
@@ -24339,10 +24339,13 @@ var TIMEBACK_COURSE_DEFAULTS;
 var TIMEBACK_RESOURCE_DEFAULTS;
 var TIMEBACK_COMPONENT_DEFAULTS;
 var TIMEBACK_COMPONENT_RESOURCE_DEFAULTS;
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES;
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE;
 var init_timeback2 = __esm(() => {
   TIMEBACK_ROUTES = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
+    GET_MASTERY: "/integrations/timeback/mastery",
     HEARTBEAT: "/integrations/timeback/heartbeat",
     ADVANCE_COURSE: "/integrations/timeback/advance-course"
   };
@@ -24382,6 +24385,17 @@ var init_timeback2 = __esm(() => {
     sortOrder: 1,
     lessonType: "quiz"
   };
+  TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+    xp: 1,
+    mastery: 0,
+    score: 2
+  };
+  TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+    xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+    mastery: 0,
+    time: 60,
+    score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+  };
 });
 var WORKER_NAMING;
 var SECRETS_PREFIX = "secrets_";
@@ -25176,7 +25190,7 @@ var package_default2;
 var init_package = __esm(() => {
   package_default2 = {
     name: "@playcademy/sandbox",
-    version: "0.4.0",
+    version: "0.4.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -52124,6 +52138,7 @@ var init_constants3 = __esm(() => {
     TIMEBACK: {
       END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
       GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
+      GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
       HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
       ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`
     }
@@ -53871,7 +53886,7 @@ var CourseGoalsSchema;
 var UpdateGameTimebackIntegrationRequestSchema;
 var TimebackActivityDataSchema;
 var EndActivityRequestSchema;
-var GameActivityMetricsSchema;
+var GameRunMetricsSchema;
 var GameCourseMetricsSchema;
 var GameMetricsResponseSchema;
 var AdvanceCourseRequestSchema;
@@ -53964,24 +53979,28 @@ var init_schemas4 = __esm(() => {
     }).optional(),
     xpEarned: exports_external.number().optional(),
     masteredUnits: exports_external.number().optional(),
+    masteredUnitsAbsolute: exports_external.number().int().nonnegative().optional(),
     extensions: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  }).refine((data) => !(data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined), {
+    message: "Cannot provide both masteredUnits and masteredUnitsAbsolute",
+    path: ["masteredUnitsAbsolute"]
   });
-  GameActivityMetricsSchema = exports_external.object({
+  GameRunMetricsSchema = exports_external.object({
+    runId: exports_external.string().uuid(),
     activityId: exports_external.string().min(1),
     activityName: exports_external.string().optional(),
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    completionCount: exports_external.number().int().nonnegative(),
-    lastCompletedAt: exports_external.string().datetime().optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    score: exports_external.number().min(0).max(100).optional()
   });
   GameCourseMetricsSchema = exports_external.object({
     grade: TimebackGradeSchema,
     subject: TimebackSubjectSchema,
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    activities: exports_external.array(GameActivityMetricsSchema).optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    activities: exports_external.array(GameRunMetricsSchema).optional()
   });
   GameMetricsResponseSchema = exports_external.object({
     studentId: exports_external.string().min(1),
@@ -54251,6 +54270,122 @@ function compareEnrollmentsByRecency(a, b) {
 var init_timeback_admin_util = __esm(() => {
   init_errors();
 });
+function createMetricRow(definition) {
+  const { gameValue, kind, metric, timebackValue, tolerance } = definition;
+  if (timebackValue === undefined && gameValue === undefined) {
+    return null;
+  }
+  if (gameValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_reported_by_game",
+      ...timebackValue !== undefined ? { timebackValue } : {}
+    };
+  }
+  if (timebackValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_recorded_by_timeback",
+      gameValue
+    };
+  }
+  const delta = gameValue - timebackValue;
+  const isDiscrepant = tolerance === 0 ? delta !== 0 : Math.abs(delta) >= tolerance;
+  return {
+    metric,
+    kind,
+    status: isDiscrepant ? "discrepant" : "matched",
+    timebackValue,
+    gameValue,
+    delta
+  };
+}
+function createRunComparison(activity, gameRun) {
+  const runId = activity.runId ?? "";
+  if (!gameRun) {
+    return {
+      runId,
+      status: "not_reported",
+      discrepancyCount: 0,
+      rows: []
+    };
+  }
+  const rows = [
+    createMetricRow({
+      metric: "xp",
+      kind: "number",
+      timebackValue: activity.xpDelta,
+      gameValue: gameRun.totalXp,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.xp
+    }),
+    createMetricRow({
+      metric: "mastery",
+      kind: "number",
+      timebackValue: activity.masteredUnitsDelta,
+      gameValue: gameRun.masteredUnits,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.mastery
+    }),
+    createMetricRow({
+      metric: "time",
+      kind: "time",
+      timebackValue: activity.timeDeltaSeconds,
+      gameValue: gameRun.activeTimeSeconds,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.time
+    }),
+    createMetricRow({
+      metric: "score",
+      kind: "percent",
+      timebackValue: activity.score,
+      gameValue: gameRun.score,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.score
+    })
+  ].filter((row) => row !== null);
+  const discrepancyCount = rows.filter((row) => row.status === "discrepant").length;
+  return {
+    runId,
+    status: discrepancyCount > 0 ? "discrepant" : "matched",
+    discrepancyCount,
+    rows
+  };
+}
+function summarizeGameRunMetricsComparison(comparison) {
+  return {
+    runId: comparison.runId,
+    status: comparison.status,
+    discrepancyCount: comparison.discrepancyCount,
+    ...comparison.reason ? { reason: comparison.reason } : {}
+  };
+}
+function buildGameRunMetricComparisons(activities, course, response) {
+  const activitiesWithRunIds = activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0);
+  const comparisons = new Map;
+  if (activitiesWithRunIds.length === 0) {
+    return comparisons;
+  }
+  if (!response.supported) {
+    for (const activity of activitiesWithRunIds) {
+      comparisons.set(activity.runId, {
+        runId: activity.runId,
+        status: "unavailable",
+        discrepancyCount: 0,
+        reason: response.reason,
+        rows: []
+      });
+    }
+    return comparisons;
+  }
+  const gameCourseMetrics = response.metrics.courses.find((gameCourse) => gameCourse.grade === course.grade && gameCourse.subject === course.subject);
+  const gameRunsById = new Map(gameCourseMetrics?.activities?.map((gameRun) => [gameRun.runId.toLowerCase(), gameRun]));
+  for (const activity of activitiesWithRunIds) {
+    comparisons.set(activity.runId, createRunComparison(activity, gameRunsById.get(activity.runId.toLowerCase())));
+  }
+  return comparisons;
+}
+var init_timeback_game_metrics_comparison_util = __esm(() => {
+  init_src();
+});
 async function upsertMasteryCompletionEntry(params) {
   const { client, courseId, studentId, appName, action } = params;
   const ids = deriveSourcedIds(courseId);
@@ -54325,7 +54460,7 @@ function mapEnrollmentsToUserEnrollments(enrollments, integrations) {
       subject: integration.subject,
       courseId: integration.courseId,
       orgId: courseToSchool.get(integration.courseId),
-      ...enrollment ? { enrollmentIds: { active: enrollment.sourcedId } } : {}
+      ...enrollment ? { id: enrollment.sourcedId } : {}
     };
   });
 }
@@ -54637,6 +54772,8 @@ class TimebackAdminService {
   static ANALYTICS_CONCURRENCY = 8;
   static MASTERABLE_UNITS_CONCURRENCY = 4;
   static GAME_METRICS_FETCH_TIMEOUT_MS = 1e4;
+  static GAME_METRICS_LIST_FETCH_TIMEOUT_MS = 3000;
+  static GAME_METRICS_RUN_IDS_PER_REQUEST = 50;
   constructor(deps) {
     this.deps = deps;
   }
@@ -54646,13 +54783,42 @@ class TimebackAdminService {
     }
     return this.deps.config.localGameUrls[slug2] ?? deployedUrl;
   }
-  static resolveGameMetricsUrl(baseUrl) {
+  static resolveGameMetricsUrl(baseUrl, runIds) {
     try {
-      return new URL("/__playcademy/metrics", baseUrl);
+      const url2 = new URL("/__playcademy/metrics", baseUrl);
+      for (const runId of runIds ?? []) {
+        url2.searchParams.append("runId", runId);
+      }
+      return url2;
     } catch {
       return null;
     }
   }
+  static normalizeRunIds(runIds, limit = Number.POSITIVE_INFINITY) {
+    const normalized = [];
+    const seen = new Set;
+    for (const runId of runIds ?? []) {
+      const value = runId.trim().toLowerCase();
+      if (isValidUUID(value) && !seen.has(value)) {
+        seen.add(value);
+        normalized.push(value);
+        if (normalized.length >= limit) {
+          break;
+        }
+      }
+    }
+    return normalized;
+  }
+  static chunkRunIds(runIds) {
+    const chunks = [];
+    for (let index2 = 0;index2 < runIds.length; index2 += this.GAME_METRICS_RUN_IDS_PER_REQUEST) {
+      chunks.push(runIds.slice(index2, index2 + this.GAME_METRICS_RUN_IDS_PER_REQUEST));
+    }
+    return chunks;
+  }
+  static isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+  }
   static roundXpToTenths(value) {
     const rounded = Math.round(value * TimebackAdminService.XP_PRECISION_FACTOR) / TimebackAdminService.XP_PRECISION_FACTOR;
     return Object.is(rounded, -0) ? 0 : rounded;
@@ -54813,6 +54979,56 @@ class TimebackAdminService {
     const remediationItems = events.map((event) => mapCaliperEventToRemediationActivity(event, relevantCourseIds)).filter((item) => Boolean(item));
     return [...groupedGameplayItems, ...remediationItems].toSorted((a, b) => b.occurredAt.localeCompare(a.occurredAt));
   }
+  async getGameMetricComparisonsForActivities(user, options) {
+    const runIds = TimebackAdminService.normalizeRunIds(options.activities.map((activity) => activity.runId).filter((runId) => Boolean(runId)));
+    if (runIds.length === 0) {
+      return new Map;
+    }
+    const activitiesByRunId = new Map(options.activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0).map((activity) => [activity.runId.toLowerCase(), activity]));
+    const comparisons = new Map;
+    await Promise.all(TimebackAdminService.chunkRunIds(runIds).map(async (chunk) => {
+      const activities = [];
+      for (const runId of chunk) {
+        const activity = activitiesByRunId.get(runId);
+        if (activity) {
+          activities.push(activity);
+        }
+      }
+      if (activities.length === 0) {
+        return;
+      }
+      let response;
+      try {
+        response = await this.getGameMetrics(options.gameId, options.studentId, user, {
+          runIds: chunk,
+          timeoutMs: options.timeoutMs
+        });
+      } catch (error) {
+        response = {
+          supported: false,
+          reason: "fetch_failed",
+          details: error instanceof Error ? error.message : String(error)
+        };
+      }
+      for (const [runId, comparison] of buildGameRunMetricComparisons(activities, options.course, response)) {
+        comparisons.set(runId, comparison);
+      }
+    }));
+    return comparisons;
+  }
+  async attachGameMetricSummariesToActivities(user, options) {
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, options);
+    if (comparisons.size === 0) {
+      return [...options.activities];
+    }
+    return options.activities.map((activity) => {
+      const comparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+      return comparison ? {
+        ...activity,
+        gameMetricsComparison: summarizeGameRunMetricsComparison(comparison)
+      } : activity;
+    });
+  }
   async getStudentEnrollmentsByCourseId(client, studentId, courseIds, options) {
     const enrollments = new Map;
     const allEnrollments = new Map;
@@ -54972,7 +55188,7 @@ class TimebackAdminService {
     });
     return { gameId, courseId, students: deduped };
   }
-  async getGameMetrics(gameId, timebackId, user) {
+  async getGameMetrics(gameId, timebackId, user, options) {
     const client = this.requireClient();
     await this.deps.validateGameManagementAccess(user, gameId);
     const [targetUser, integrations, game2, deployment] = await Promise.all([
@@ -55007,7 +55223,8 @@ class TimebackAdminService {
     if (!metricsBaseUrl) {
       return { supported: false, reason: "no_active_deployment" };
     }
-    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl);
+    const runIds = TimebackAdminService.normalizeRunIds(options?.runIds, TimebackAdminService.GAME_METRICS_RUN_IDS_PER_REQUEST);
+    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl, runIds);
     if (!metricsUrl) {
       return {
         supported: false,
@@ -55017,7 +55234,7 @@ class TimebackAdminService {
     }
     const token = await this.deps.mintPlatformServiceToken(gameId, targetUser.id);
     const controller = new AbortController;
-    const timeout = setTimeout(() => controller.abort(), TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
+    const timeout = setTimeout(() => controller.abort(), options?.timeoutMs ?? TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
     let response;
     try {
       response = await fetch(metricsUrl, {
@@ -55029,10 +55246,19 @@ class TimebackAdminService {
         signal: controller.signal
       });
     } catch (error) {
+      const timedOut = TimebackAdminService.isAbortError(error);
+      let details;
+      if (timedOut) {
+        details = "Game metrics request timed out";
+      } else if (error instanceof Error) {
+        details = error.message;
+      } else {
+        details = String(error);
+      }
       return {
         supported: false,
-        reason: "fetch_failed",
-        details: error instanceof Error ? error.message : String(error)
+        reason: timedOut ? "timeout" : "fetch_failed",
+        details
       };
     } finally {
       clearTimeout(timeout);
@@ -55136,7 +55362,14 @@ class TimebackAdminService {
     const allActivities = await this.listRecentActivityForStudent(client, studentId, gameSource, relevantCourseIds, fetchLimit);
     const activities = allActivities.slice(safeOffset, safeOffset + safeLimit);
     const hasMore = allActivities.length > safeOffset + safeLimit;
-    return { activities, hasMore };
+    const activitiesWithGameMetrics = await this.attachGameMetricSummariesToActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities,
+      timeoutMs: TimebackAdminService.GAME_METRICS_LIST_FETCH_TIMEOUT_MS
+    });
+    return { activities: activitiesWithGameMetrics, hasMore };
   }
   async getActivityDetail(user, options) {
     const { gameId, studentId, courseId, activityId, runId } = options;
@@ -55172,7 +55405,22 @@ class TimebackAdminService {
     if (!activity) {
       throw new NotFoundError("Activity", activityId);
     }
-    return { activity, rawEvents: matchedEvents };
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities: [activity]
+    });
+    const gameMetricsComparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+    const activityWithGameMetrics = gameMetricsComparison ? {
+      ...activity,
+      gameMetricsComparison: summarizeGameRunMetricsComparison(gameMetricsComparison)
+    } : activity;
+    return {
+      activity: activityWithGameMetrics,
+      rawEvents: matchedEvents,
+      ...gameMetricsComparison ? { gameMetricsComparison } : {}
+    };
   }
   async grantManualXp(data, user) {
     const { client, sensorUrl, appName, actor } = await this.resolveAdminMutationContext(data.gameId, data.courseId, user, data.studentId);
@@ -55460,6 +55708,7 @@ var init_timeback_admin_service = __esm(() => {
   init_errors();
   init_timeback_admin_metrics_util();
   init_timeback_admin_util();
+  init_timeback_game_metrics_comparison_util();
   init_timeback_mastery_completion_util();
   init_timeback_util();
   logger17 = log.scope("TimebackAdminService");
@@ -56904,6 +57153,7 @@ var init_timeback_service = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user
     }) {
@@ -56927,6 +57177,7 @@ var init_timeback_service = __esm(() => {
         durationSeconds: timingData.durationSeconds,
         xpEarned,
         masteredUnits,
+        masteredUnitsAbsolute,
         extensions: extensionsWithResumeId,
         activityId: activityData.activityId,
         activityName: activityData.activityName,
@@ -57175,6 +57426,46 @@ var init_timeback_service = __esm(() => {
       });
       return result;
     }
+    async getStudentMastery(timebackId, user, options) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, options.gameId);
+      const conditions2 = [eq(gameTimebackIntegrations.gameId, options.gameId)];
+      if (options.grade !== undefined && options.subject) {
+        conditions2.push(eq(gameTimebackIntegrations.grade, options.grade));
+        conditions2.push(eq(gameTimebackIntegrations.subject, options.subject));
+      }
+      const integrations = await db2.query.gameTimebackIntegrations.findMany({
+        where: and(...conditions2)
+      });
+      const courseIds = integrations.map((i2) => i2.courseId);
+      if (courseIds.length === 0) {
+        logger20.debug("No integrations found for game, returning empty mastery", {
+          timebackId,
+          gameId: options.gameId,
+          grade: options.grade,
+          subject: options.subject
+        });
+        return {
+          totalMasteredUnits: 0,
+          totalMasterableUnits: 0,
+          ...options.include?.perCourse && { courses: [] }
+        };
+      }
+      const result = await client.getStudentMastery(timebackId, {
+        courseIds,
+        include: options.include
+      });
+      logger20.debug("Retrieved student mastery", {
+        timebackId,
+        gameId: options.gameId,
+        grade: options.grade,
+        subject: options.subject,
+        totalMasteredUnits: result.totalMasteredUnits,
+        courseCount: result.courses?.length
+      });
+      return result;
+    }
   };
 });
 
@@ -59481,15 +59772,18 @@ class MasteryTracker {
     this.edubridgeNamespace = edubridgeNamespace;
   }
   async checkProgress(input) {
-    const { studentId, courseId, resourceId, masteredUnits } = input;
-    if (typeof masteredUnits !== "number" || masteredUnits === 0) {
+    const { studentId, courseId, resourceId, masteredUnits, masteredUnitsAbsolute } = input;
+    const hasIncremental = typeof masteredUnits === "number" && masteredUnits !== 0;
+    const hasAbsolute = typeof masteredUnitsAbsolute === "number";
+    if (!hasIncremental && !hasAbsolute) {
       return;
     }
     const status = await this.calculateStatus({
       studentId,
       courseId,
       resourceId,
-      additionalMasteredUnits: masteredUnits
+      additionalMasteredUnits: hasAbsolute ? 0 : masteredUnits,
+      absoluteMasteredUnits: hasAbsolute ? masteredUnitsAbsolute : undefined
     });
     if (!status) {
       return;
@@ -59498,7 +59792,8 @@ class MasteryTracker {
     return {
       pctCompleteApp: status.pctCompleteApp,
       masteryAchieved: !wasComplete && status.isComplete,
-      masteryRevoked: wasComplete && !status.isComplete
+      masteryRevoked: wasComplete && !status.isComplete,
+      effectiveDelta: status.effectiveDelta
     };
   }
   async getStatus(input) {
@@ -59520,7 +59815,8 @@ class MasteryTracker {
     studentId,
     courseId,
     resourceId,
-    additionalMasteredUnits
+    additionalMasteredUnits,
+    absoluteMasteredUnits
   }) {
     const masterableUnits = await this.resolveMasterableUnits(resourceId);
     if (!masterableUnits || masterableUnits <= 0) {
@@ -59539,7 +59835,15 @@ class MasteryTracker {
       return;
     }
     const historicalMasteredUnits = this.sumAnalyticsMetric(facts, "masteredUnits");
-    const totalMastered = Math.max(0, historicalMasteredUnits + additionalMasteredUnits);
+    let totalMastered;
+    let effectiveDelta;
+    if (absoluteMasteredUnits !== undefined) {
+      totalMastered = Math.max(0, absoluteMasteredUnits);
+      effectiveDelta = totalMastered - historicalMasteredUnits;
+    } else {
+      effectiveDelta = additionalMasteredUnits;
+      totalMastered = Math.max(0, historicalMasteredUnits + effectiveDelta);
+    }
     const rawPct = totalMastered / masterableUnits * 100;
     const pctCompleteApp = Math.min(100, Math.max(0, Math.round(rawPct)));
     return {
@@ -59547,7 +59851,8 @@ class MasteryTracker {
       masterableUnits,
       pctCompleteApp,
       isComplete: totalMastered >= masterableUnits,
-      historicalMasteredUnits
+      historicalMasteredUnits,
+      effectiveDelta
     };
   }
   async createCompletionEntry(studentId, courseId, classId, appName) {
@@ -59776,7 +60081,7 @@ class ProgressRecorder {
     validateProgressData(progressData);
     const { ids, activityId, activityName, courseName, student } = await this.resolveContext(courseId, studentIdentifier, progressData);
     const { id: studentId, email: studentEmail } = student;
-    const { score, totalQuestions, correctQuestions, xpEarned, masteredUnits, attemptNumber } = progressData;
+    const { score, totalQuestions, correctQuestions, xpEarned, attemptNumber } = progressData;
     const actualLineItemId = await this.resolveAssessmentLineItem(activityId, activityName, progressData.classId, ids);
     const currentAttemptNumber = await this.resolveAttemptNumber(attemptNumber, score, studentId, actualLineItemId);
     const calculatedXp = this.calculateXpForProgress(progressData, totalQuestions, correctQuestions, xpEarned, currentAttemptNumber);
@@ -59785,8 +60090,10 @@ class ProgressRecorder {
       studentId,
       courseId,
       resourceId: ids.resource,
-      masteredUnits: progressData.masteredUnits ?? 0
+      masteredUnits: progressData.masteredUnits ?? 0,
+      masteredUnitsAbsolute: progressData.masteredUnitsAbsolute
     });
+    const effectiveMasteredUnits = masteryProgress ? masteryProgress.effectiveDelta : progressData.masteredUnits ?? 0;
     let pctCompleteApp;
     let masteryAchieved = false;
     let scoreStatus = SCORE_STATUS5.fullyGraded;
@@ -59814,7 +60121,7 @@ class ProgressRecorder {
         appName: progressData.appName,
         totalQuestions,
         correctQuestions,
-        masteredUnits,
+        masteredUnits: effectiveMasteredUnits || undefined,
         pctCompleteApp
       });
     } else {
@@ -59852,7 +60159,7 @@ class ProgressRecorder {
       totalQuestions,
       correctQuestions,
       xpEarned: calculatedXp,
-      masteredUnits,
+      masteredUnits: effectiveMasteredUnits || undefined,
       attemptNumber: currentAttemptNumber,
       progressData,
       extensions,
@@ -59861,7 +60168,7 @@ class ProgressRecorder {
     return {
       xpAwarded: calculatedXp,
       attemptNumber: currentAttemptNumber,
-      masteredUnitsApplied: progressData.masteredUnits ?? 0,
+      masteredUnitsApplied: effectiveMasteredUnits,
       pctCompleteApp,
       scoreStatus,
       inProgress
@@ -60396,6 +60703,65 @@ class TimebackClient {
       resourceId: ids.resource
     });
   }
+  async getStudentMastery(studentId, options) {
+    await this._ensureAuthenticated();
+    const enrollments = await this.edubridge.enrollments.listByUser(studentId);
+    const filteredEnrollments = options?.courseIds?.length ? enrollments.filter((e) => options.courseIds.includes(e.course.id)) : enrollments;
+    if (filteredEnrollments.length === 0) {
+      return {
+        totalMasteredUnits: 0,
+        totalMasterableUnits: 0,
+        ...options?.include?.perCourse && { courses: [] }
+      };
+    }
+    const masteryResults = await Promise.all(filteredEnrollments.map(async (enrollment) => {
+      try {
+        const ids = deriveSourcedIds2(enrollment.course.id);
+        const status = await this.masteryTracker.getStatus({
+          studentId,
+          courseId: enrollment.course.id,
+          resourceId: ids.resource
+        });
+        return { enrollment, status };
+      } catch (error) {
+        log.warn("[TimebackClient] Failed to fetch mastery for enrollment", {
+          enrollmentId: enrollment.id,
+          error
+        });
+        return { enrollment, status: undefined };
+      }
+    }));
+    let totalMasteredUnits = 0;
+    let totalMasterableUnits = 0;
+    const courses = [];
+    for (const { enrollment, status } of masteryResults) {
+      const masteredUnits = status?.masteredUnits ?? 0;
+      const masterableUnits = status?.masterableUnits ?? 0;
+      totalMasteredUnits += masteredUnits;
+      totalMasterableUnits += masterableUnits;
+      if (options?.include?.perCourse) {
+        const gradeStr = enrollment.course.grades?.[0];
+        const parsedGrade = gradeStr ? parseInt(gradeStr, 10) : 0;
+        const grade = isTimebackGrade3(parsedGrade) ? parsedGrade : 0;
+        const subjectStr = enrollment.course.subjects?.[0];
+        const subject = subjectStr && isTimebackSubject3(subjectStr) ? subjectStr : "None";
+        courses.push({
+          grade,
+          subject,
+          title: enrollment.course.title,
+          masteredUnits,
+          masterableUnits,
+          pctComplete: status?.pctCompleteApp ?? 0,
+          isComplete: status?.isComplete ?? false
+        });
+      }
+    }
+    return {
+      totalMasteredUnits,
+      totalMasterableUnits,
+      ...options?.include?.perCourse && { courses }
+    };
+  }
   async getStudentXp(studentId, options) {
     await this._ensureAuthenticated();
     const enrollments = await this.edubridge.enrollments.listByUser(studentId);
@@ -120401,6 +120767,7 @@ var endActivity;
 var heartbeat;
 var advanceCourse;
 var getStudentXp;
+var getStudentMastery;
 var getRoster;
 var getStudentOverview;
 var getGameMetrics;
@@ -120585,6 +120952,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions
     } = body2;
     logger45.debug("Ending activity", { userId: ctx.user.id, gameId });
@@ -120599,6 +120967,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user: ctx.user
     });
@@ -120708,6 +121077,53 @@ var init_timeback_controller = __esm(() => {
       include
     });
   });
+  getStudentMastery = requireDeveloper(async (ctx) => {
+    const timebackId = ctx.params.timebackId;
+    if (!timebackId) {
+      throw ApiError.badRequest("Missing timebackId parameter");
+    }
+    const gameId = ctx.url.searchParams.get("gameId");
+    if (!gameId) {
+      throw ApiError.badRequest("Missing required gameId query parameter");
+    }
+    const gradeParam = ctx.url.searchParams.get("grade");
+    const subjectParam = ctx.url.searchParams.get("subject");
+    if (gradeParam !== null !== (subjectParam !== null)) {
+      throw ApiError.badRequest("Both grade and subject must be provided together");
+    }
+    let grade;
+    let subject;
+    if (gradeParam !== null && subjectParam !== null) {
+      const parsedGrade = parseInt(gradeParam, 10);
+      if (!isTimebackGrade2(parsedGrade)) {
+        throw ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+      }
+      if (!isTimebackSubject2(subjectParam)) {
+        throw ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+      }
+      grade = parsedGrade;
+      subject = subjectParam;
+    }
+    const includeParam = ctx.url.searchParams.get("include");
+    const includeOptions = includeParam ? includeParam.split(",").map((opt) => opt.trim().toLowerCase()) : [];
+    const include = {
+      perCourse: includeOptions.includes("percourse")
+    };
+    logger45.debug("Getting student mastery", {
+      requesterId: ctx.user.id,
+      timebackId,
+      gameId,
+      grade,
+      subject,
+      include
+    });
+    return ctx.services.timeback.getStudentMastery(timebackId, ctx.user, {
+      gameId,
+      grade,
+      subject,
+      include
+    });
+  });
   getRoster = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const courseId = ctx.params.courseId;
@@ -120743,15 +121159,19 @@ var init_timeback_controller = __esm(() => {
   getGameMetrics = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const timebackId = ctx.params.timebackId;
+    const runIds = [
+      ...new Set(ctx.url.searchParams.getAll("runId").map((runId) => runId.trim().toLowerCase()).filter(isValidUUID))
+    ];
     if (!gameId || !timebackId) {
       throw ApiError.badRequest("Missing gameId or timebackId path parameter");
     }
     logger45.debug("Getting game metrics", {
       requesterId: ctx.user.id,
       gameId,
-      timebackId
+      timebackId,
+      runIds
     });
-    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user);
+    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user, { runIds });
   });
   getStudentActivity = requireGameManagementAccess(async (ctx) => {
     const timebackId = ctx.params.timebackId;
@@ -121040,6 +121460,7 @@ var init_timeback_controller = __esm(() => {
     heartbeat,
     advanceCourse,
     getStudentXp,
+    getStudentMastery,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -121890,6 +122311,7 @@ var init_timeback6 = __esm(() => {
   init_controllers();
   init_errors();
   init_utils11();
+  init_schemas_index();
   init_api();
   init_error_handler();
   init_timeback5();
@@ -121969,6 +122391,14 @@ var init_timeback6 = __esm(() => {
       }
       if (gradeParam !== null && subjectParam !== null) {
         const grade = parseInt(gradeParam, 10);
+        if (!Number.isFinite(grade) || !isTimebackGrade2(grade)) {
+          const error2 = ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        if (!isTimebackSubject2(subjectParam)) {
+          const error2 = ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
         enrollments = enrollments.filter((e) => e.grade === grade && e.subject === subjectParam);
       }
       const mockCourses = enrollments.map((e) => {
@@ -121993,6 +122423,62 @@ var init_timeback6 = __esm(() => {
     }
     return handle2(timeback2.getStudentXp)(c2);
   });
+  timebackRouter.get("/student-mastery/:timebackId", async (c2) => {
+    const user = c2.get("user");
+    if (!user) {
+      const error2 = ApiError.unauthorized("Must be logged in to get student mastery");
+      return c2.json(createErrorResponse(error2), error2.status);
+    }
+    if (shouldMockTimeback()) {
+      const url2 = new URL(c2.req.url);
+      const gradeParam = url2.searchParams.get("grade");
+      const subjectParam = url2.searchParams.get("subject");
+      const includeParam = url2.searchParams.get("include") || "";
+      const includeOptions = includeParam.split(",").map((opt) => opt.trim().toLowerCase());
+      const includePerCourse = includeOptions.includes("percourse");
+      const db2 = c2.get("db");
+      let enrollments = await getMockEnrollments(db2);
+      if (gradeParam !== null !== (subjectParam !== null)) {
+        const error2 = ApiError.badRequest("Both grade and subject must be provided together");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (gradeParam !== null && subjectParam !== null) {
+        const grade = parseInt(gradeParam, 10);
+        if (!Number.isFinite(grade) || !isTimebackGrade2(grade)) {
+          const error2 = ApiError.badRequest(`Invalid grade: ${gradeParam}. Valid grades: ${TIMEBACK_GRADES.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        if (!isTimebackSubject2(subjectParam)) {
+          const error2 = ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+          return c2.json(createErrorResponse(error2), error2.status);
+        }
+        enrollments = enrollments.filter((e) => e.grade === grade && e.subject === subjectParam);
+      }
+      const mockCourses = enrollments.map((e) => {
+        const seed3 = hashCode(`${e.grade}-${e.subject}`);
+        const masterableUnits = 5 + seed3 % 16;
+        const masteredUnits = seed3 % (masterableUnits + 1);
+        const pctComplete = masterableUnits > 0 ? Math.round(masteredUnits / masterableUnits * 1e4) / 100 : 0;
+        return {
+          grade: e.grade,
+          subject: e.subject,
+          title: `${e.subject} ${formatGradeLabel(e.grade)}`,
+          masteredUnits,
+          masterableUnits,
+          pctComplete,
+          isComplete: masteredUnits >= masterableUnits
+        };
+      });
+      const totalMasteredUnits = mockCourses.reduce((sum2, course) => sum2 + course.masteredUnits, 0);
+      const totalMasterableUnits = mockCourses.reduce((sum2, course) => sum2 + course.masterableUnits, 0);
+      return c2.json({
+        totalMasteredUnits,
+        totalMasterableUnits,
+        ...includePerCourse && { courses: mockCourses }
+      });
+    }
+    return handle2(timeback2.getStudentMastery)(c2);
+  });
 });
 function verifyMockToken(idToken) {
   if (!idToken.startsWith("mock:")) {
@@ -122528,6 +123014,17 @@ var POSTHOG_CONFIG = {
 var TIMEBACK_ORG_SOURCED_ID2 = "PLAYCADEMY";
 var TIMEBACK_ORG_NAME2 = "Playcademy Studios";
 var TIMEBACK_ORG_TYPE2 = "department";
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES2 = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE2 = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES2.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES2.score
+};
 // src/lib/sandbox/timeback.ts
 function detectTimebackOptions() {
   if (process.env.TIMEBACK_LOCAL === "true") {
@@ -122744,10 +123241,13 @@ var TIMEBACK_COURSE_DEFAULTS2;
 var TIMEBACK_RESOURCE_DEFAULTS2;
 var TIMEBACK_COMPONENT_DEFAULTS2;
 var TIMEBACK_COMPONENT_RESOURCE_DEFAULTS2;
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES3;
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE3;
 var init_timeback7 = __esm8(() => {
   TIMEBACK_ROUTES2 = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
+    GET_MASTERY: "/integrations/timeback/mastery",
     HEARTBEAT: "/integrations/timeback/heartbeat",
     ADVANCE_COURSE: "/integrations/timeback/advance-course"
   };
@@ -122787,6 +123287,17 @@ var init_timeback7 = __esm8(() => {
     sortOrder: 1,
     lessonType: "quiz"
   };
+  TIMEBACK_GAME_METRIC_DECIMAL_PLACES3 = {
+    xp: 1,
+    mastery: 0,
+    score: 2
+  };
+  TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE3 = {
+    xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES3.xp,
+    mastery: 0,
+    time: 60,
+    score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES3.score
+  };
 });
 var WORKER_NAMING2;
 var init_cloudflare2 = __esm8(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "0.3.2",
+    "version": "0.3.3-beta.2",
     "type": "module",
     "exports": {
         ".": {