@playcademy/sandbox 0.4.0 → 0.4.1-beta.1

package/dist/cli.js

@@ -248,6 +248,7 @@ 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"
   };
@@ -1064,7 +1065,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.0",
+    version: "0.4.1-beta.1",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28234,6 +28235,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}`
     }
@@ -29958,7 +29960,11 @@ 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({
     activityId: exports_external.string().min(1),
@@ -30329,7 +30335,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 } : {}
     };
   });
 }
@@ -32886,6 +32892,7 @@ var init_timeback_service = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user
     }) {
@@ -32909,6 +32916,7 @@ var init_timeback_service = __esm(() => {
         durationSeconds: timingData.durationSeconds,
         xpEarned,
         masteredUnits,
+        masteredUnitsAbsolute,
         extensions: extensionsWithResumeId,
         activityId: activityData.activityId,
         activityName: activityData.activityName,
@@ -33157,6 +33165,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;
+    }
   };
 });
 
@@ -35482,15 +35530,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;
@@ -35499,7 +35550,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) {
@@ -35521,7 +35573,8 @@ class MasteryTracker {
     studentId,
     courseId,
     resourceId,
-    additionalMasteredUnits
+    additionalMasteredUnits,
+    absoluteMasteredUnits
   }) {
     const masterableUnits = await this.resolveMasterableUnits(resourceId);
     if (!masterableUnits || masterableUnits <= 0) {
@@ -35540,7 +35593,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 {
@@ -35548,7 +35609,8 @@ class MasteryTracker {
       masterableUnits,
       pctCompleteApp,
       isComplete: totalMastered >= masterableUnits,
-      historicalMasteredUnits
+      historicalMasteredUnits,
+      effectiveDelta
     };
   }
   async createCompletionEntry(studentId, courseId, classId, appName) {
@@ -35777,7 +35839,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);
@@ -35786,8 +35848,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;
@@ -35815,7 +35879,7 @@ class ProgressRecorder {
         appName: progressData.appName,
         totalQuestions,
         correctQuestions,
-        masteredUnits,
+        masteredUnits: effectiveMasteredUnits || undefined,
         pctCompleteApp
       });
     } else {
@@ -35853,7 +35917,7 @@ class ProgressRecorder {
       totalQuestions,
       correctQuestions,
       xpEarned: calculatedXp,
-      masteredUnits,
+      masteredUnits: effectiveMasteredUnits || undefined,
       attemptNumber: currentAttemptNumber,
       progressData,
       extensions,
@@ -35862,7 +35926,7 @@ class ProgressRecorder {
     return {
       xpAwarded: calculatedXp,
       attemptNumber: currentAttemptNumber,
-      masteredUnitsApplied: progressData.masteredUnits ?? 0,
+      masteredUnitsApplied: effectiveMasteredUnits,
       pctCompleteApp,
       scoreStatus,
       inProgress
@@ -36397,6 +36461,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);
@@ -93719,7 +93842,7 @@ var init_session_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
+var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getStudentMastery, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -93877,6 +94000,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions
     } = body2;
     logger45.debug("Ending activity", { userId: ctx.user.id, gameId });
@@ -93891,6 +94015,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user: ctx.user
     });
@@ -94000,6 +94125,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;
@@ -94332,6 +94504,7 @@ var init_timeback_controller = __esm(() => {
     heartbeat,
     advanceCourse,
     getStudentXp,
+    getStudentMastery,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -95218,6 +95391,7 @@ var init_timeback6 = __esm(() => {
   init_controllers();
   init_errors();
   init_utils11();
+  init_schemas_index();
   init_api();
   init_error_handler();
   init_timeback5();
@@ -95297,6 +95471,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) => {
@@ -95321,6 +95503,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);
+  });
 });
 
 // src/routes/integrations/lti.ts

package/dist/constants.js

@@ -83,6 +83,7 @@ var init_timeback = __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"
   };

package/dist/server.js

@@ -247,6 +247,7 @@ 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"
   };
@@ -1063,7 +1064,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.0",
+    version: "0.4.1-beta.1",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28233,6 +28234,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}`
     }
@@ -29957,7 +29959,11 @@ 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({
     activityId: exports_external.string().min(1),
@@ -30328,7 +30334,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 } : {}
     };
   });
 }
@@ -32885,6 +32891,7 @@ var init_timeback_service = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user
     }) {
@@ -32908,6 +32915,7 @@ var init_timeback_service = __esm(() => {
         durationSeconds: timingData.durationSeconds,
         xpEarned,
         masteredUnits,
+        masteredUnitsAbsolute,
         extensions: extensionsWithResumeId,
         activityId: activityData.activityId,
         activityName: activityData.activityName,
@@ -33156,6 +33164,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;
+    }
   };
 });
 
@@ -35481,15 +35529,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;
@@ -35498,7 +35549,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) {
@@ -35520,7 +35572,8 @@ class MasteryTracker {
     studentId,
     courseId,
     resourceId,
-    additionalMasteredUnits
+    additionalMasteredUnits,
+    absoluteMasteredUnits
   }) {
     const masterableUnits = await this.resolveMasterableUnits(resourceId);
     if (!masterableUnits || masterableUnits <= 0) {
@@ -35539,7 +35592,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 {
@@ -35547,7 +35608,8 @@ class MasteryTracker {
       masterableUnits,
       pctCompleteApp,
       isComplete: totalMastered >= masterableUnits,
-      historicalMasteredUnits
+      historicalMasteredUnits,
+      effectiveDelta
     };
   }
   async createCompletionEntry(studentId, courseId, classId, appName) {
@@ -35776,7 +35838,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);
@@ -35785,8 +35847,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;
@@ -35814,7 +35878,7 @@ class ProgressRecorder {
         appName: progressData.appName,
         totalQuestions,
         correctQuestions,
-        masteredUnits,
+        masteredUnits: effectiveMasteredUnits || undefined,
         pctCompleteApp
       });
     } else {
@@ -35852,7 +35916,7 @@ class ProgressRecorder {
       totalQuestions,
       correctQuestions,
       xpEarned: calculatedXp,
-      masteredUnits,
+      masteredUnits: effectiveMasteredUnits || undefined,
       attemptNumber: currentAttemptNumber,
       progressData,
       extensions,
@@ -35861,7 +35925,7 @@ class ProgressRecorder {
     return {
       xpAwarded: calculatedXp,
       attemptNumber: currentAttemptNumber,
-      masteredUnitsApplied: progressData.masteredUnits ?? 0,
+      masteredUnitsApplied: effectiveMasteredUnits,
       pctCompleteApp,
       scoreStatus,
       inProgress
@@ -36396,6 +36460,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);
@@ -93718,7 +93841,7 @@ var init_session_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
+var logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getStudentMastery, getRoster, getStudentOverview, getGameMetrics, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, reconcileMasteryForConfigChange, searchStudents, enrollStudent, unenrollStudent, reactivateEnrollment, listAssessments, createAssessment, deleteAssessment, reorderAssessments, reorderQuestions, activateAssessment, deactivateAssessment, listQuestions, createQuestion, updateQuestion, deleteQuestion, getAssessmentBankStatus, destroyAssessmentBank, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -93876,6 +93999,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions
     } = body2;
     logger45.debug("Ending activity", { userId: ctx.user.id, gameId });
@@ -93890,6 +94014,7 @@ var init_timeback_controller = __esm(() => {
       sessionTimingData,
       xpEarned,
       masteredUnits,
+      masteredUnitsAbsolute,
       extensions,
       user: ctx.user
     });
@@ -93999,6 +94124,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;
@@ -94331,6 +94503,7 @@ var init_timeback_controller = __esm(() => {
     heartbeat,
     advanceCourse,
     getStudentXp,
+    getStudentMastery,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -95217,6 +95390,7 @@ var init_timeback6 = __esm(() => {
   init_controllers();
   init_errors();
   init_utils11();
+  init_schemas_index();
   init_api();
   init_error_handler();
   init_timeback5();
@@ -95296,6 +95470,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) => {
@@ -95320,6 +95502,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);
+  });
 });
 
 // src/routes/integrations/lti.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sandbox",
-    "version": "0.4.0",
+    "version": "0.4.1-beta.1",
     "description": "Local development server for Playcademy game development",
     "type": "module",
     "exports": {