@playcademy/sandbox 0.4.1 → 0.4.2-beta.2

package/dist/cli.js

@@ -249,8 +249,10 @@ var init_timeback2 = __esm(() => {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
     GET_MASTERY: "/integrations/timeback/mastery",
+    GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
     HEARTBEAT: "/integrations/timeback/heartbeat",
-    ADVANCE_COURSE: "/integrations/timeback/advance-course"
+    ADVANCE_COURSE: "/integrations/timeback/advance-course",
+    UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
   };
   TIMEBACK_COURSE_DEFAULTS = {
     gradingScheme: "STANDARD",
@@ -1076,7 +1078,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.1",
+    version: "0.4.2-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28247,8 +28249,10 @@ var init_constants3 = __esm(() => {
       END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
       GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
       GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
+      GET_HIGHEST_GRADE_MASTERED: `/api${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}`,
       HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
-      ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`
+      ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`,
+      UNENROLL_COURSE: `/api${TIMEBACK_ROUTES.UNENROLL_COURSE}`
     }
   };
 });
@@ -29126,6 +29130,7 @@ var init_utils6 = __esm(() => {
     };
   });
   init_constants7();
+  init_constants7();
   if (process.env.DEBUG === "true") {
     process.env.TERM = "dumb";
   }
@@ -29902,7 +29907,7 @@ function isValidAdminAttributionDate(value) {
   const date3 = new Date(Date.UTC(year, month - 1, day, 12, 0, 0));
   return date3.getUTCFullYear() === year && date3.getUTCMonth() + 1 === month && date3.getUTCDate() === day;
 }
-var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
+var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
 var init_schemas4 = __esm(() => {
   init_drizzle_zod();
   init_esm();
@@ -30004,6 +30009,12 @@ var init_schemas4 = __esm(() => {
     studentId: exports_external.string().min(1),
     subject: TimebackSubjectSchema.optional()
   });
+  UnenrollCourseRequestSchema = exports_external.object({
+    gameId: exports_external.string().uuid(),
+    studentId: exports_external.string().min(1),
+    subject: TimebackSubjectSchema.optional(),
+    force: exports_external.boolean().optional()
+  });
   HeartbeatRequestSchema = exports_external.object({
     gameId: exports_external.string().uuid(),
     studentId: exports_external.string().min(1),
@@ -33208,15 +33219,14 @@ var init_timeback_service = __esm(() => {
         inProgress: result.inProgress
       };
     }
-    async advanceCourse({
+    async resolveActiveGameCourse({
       gameId,
       studentId,
       subject,
-      user
+      action
     }) {
       const client = this.requireClient();
       const db2 = this.deps.db;
-      await this.deps.validateDeveloperAccess(user, gameId);
       const integrations = await db2.query.gameTimebackIntegrations.findMany({
         where: subject ? and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.subject, subject)) : eq(gameTimebackIntegrations.gameId, gameId)
       });
@@ -33231,12 +33241,30 @@ var init_timeback_service = __esm(() => {
       }
       const subjectsInPlay = new Set(enrolledIntegrations.map((i2) => i2.subject));
       if (subjectsInPlay.size > 1) {
-        throw new ValidationError(`Ambiguous Timeback advance: student is enrolled in ${subjectsInPlay.size} parallel ladders (${[...subjectsInPlay].join(", ")}); pass { subject } to disambiguate`);
+        throw new ValidationError(`Ambiguous Timeback ${action}: student is enrolled in ${subjectsInPlay.size} parallel ladders (${[...subjectsInPlay].join(", ")}); pass { subject } to disambiguate`);
       }
       const currentIntegration = enrolledIntegrations.toSorted((left, right) => left.grade - right.grade)[0];
+      const currentEnrollment = enrollments.find((enrollment) => enrollment.course.id === currentIntegration.courseId);
+      return { currentIntegration, currentEnrollment, enrollments };
+    }
+    async advanceCourse({
+      gameId,
+      studentId,
+      subject,
+      user
+    }) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const { currentIntegration, enrollments } = await this.resolveActiveGameCourse({
+        gameId,
+        studentId,
+        subject,
+        action: "advance"
+      });
       const masteryStatus = await client.getMasteryStatus(currentIntegration.courseId, studentId);
       if (!masteryStatus) {
-        throw new ValidationError(`Cannot advance course: mastery status is unavailable for course ${currentIntegration.courseId}. Ensure the course has mastery configuration and the student has enrollment analytics before calling client.timeback.advanceCourse().`);
+        throw new ValidationError(`Cannot advance course: mastery status is unavailable for course ${currentIntegration.courseId}. Ensure the course has mastery configuration and the student has enrollment analytics before calling client.timeback.course.advance().`);
       }
       if (!masteryStatus.isComplete) {
         const promotion2 = {
@@ -33274,6 +33302,93 @@ var init_timeback_service = __esm(() => {
       });
       return { status: "ok", promotion };
     }
+    async unenrollCourse({
+      gameId,
+      studentId,
+      subject,
+      force,
+      user
+    }) {
+      const client = this.requireClient();
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const { currentIntegration, currentEnrollment } = await this.resolveActiveGameCourse({
+        gameId,
+        studentId,
+        subject,
+        action: "unenroll"
+      });
+      const schoolId = currentEnrollment.school.id;
+      const masteryStatus = await client.getMasteryStatus(currentIntegration.courseId, studentId);
+      if (!masteryStatus && !force) {
+        throw new ValidationError(`Cannot unenroll course: mastery status is unavailable for course ${currentIntegration.courseId}. Pass { force: true } to unenroll without mastery data.`);
+      }
+      if (masteryStatus && !masteryStatus.isComplete && !force) {
+        const unenrollment = {
+          status: "not-mastered",
+          currentCourseId: currentIntegration.courseId,
+          masteredUnits: masteryStatus.masteredUnits,
+          masterableUnits: masteryStatus.masterableUnits
+        };
+        logger20.debug("Skipping game-initiated course unenroll because mastery is incomplete", {
+          event: "timeback.course.unenroll",
+          outcome: "not-mastered",
+          gameId,
+          studentId,
+          courseId: currentIntegration.courseId,
+          subject: currentIntegration.subject,
+          grade: currentIntegration.grade,
+          masteredUnits: masteryStatus.masteredUnits,
+          masterableUnits: masteryStatus.masterableUnits,
+          forced: false,
+          requesterUserId: user.id
+        });
+        return { status: "ok", unenrollment };
+      }
+      const forcedEarlyExit = Boolean(force && (!masteryStatus || !masteryStatus.isComplete));
+      if (forcedEarlyExit) {
+        logger20.warn("Force-unenrolled student before mastery completion", {
+          event: "timeback.course.unenroll",
+          outcome: "force-unenrolled",
+          gameId,
+          studentId,
+          courseId: currentIntegration.courseId,
+          subject: currentIntegration.subject,
+          grade: currentIntegration.grade,
+          masteredUnits: masteryStatus?.masteredUnits,
+          masterableUnits: masteryStatus?.masterableUnits,
+          masteryStatusAvailable: Boolean(masteryStatus),
+          forced: true,
+          requesterUserId: user.id
+        });
+      }
+      await client.edubridge.enrollments.unenroll(studentId, currentIntegration.courseId, schoolId ? { schoolId } : {});
+      client.invalidateEnrollments(studentId);
+      logger20.info("Game-initiated course unenroll completed", {
+        event: "timeback.course.unenroll",
+        outcome: "unenrolled",
+        gameId,
+        studentId,
+        courseId: currentIntegration.courseId,
+        subject: currentIntegration.subject,
+        grade: currentIntegration.grade,
+        masteredUnits: masteryStatus?.masteredUnits,
+        masterableUnits: masteryStatus?.masterableUnits,
+        forced: forcedEarlyExit,
+        requesterUserId: user.id
+      });
+      return {
+        status: "ok",
+        unenrollment: {
+          status: "unenrolled",
+          currentCourseId: currentIntegration.courseId,
+          ...masteryStatus ? {
+            masteredUnits: masteryStatus.masteredUnits,
+            masterableUnits: masteryStatus.masterableUnits
+          } : {},
+          ...forcedEarlyExit ? { forced: true } : {}
+        }
+      };
+    }
     async recordHeartbeat({
       gameId,
       studentId,
@@ -33448,6 +33563,25 @@ var init_timeback_service = __esm(() => {
       });
       return result;
     }
+    async getStudentHighestGradeMastered(timebackId, user, options) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, options.gameId);
+      const integration = await db2.query.gameTimebackIntegrations.findFirst({
+        where: and(eq(gameTimebackIntegrations.gameId, options.gameId), eq(gameTimebackIntegrations.subject, options.subject))
+      });
+      if (!integration) {
+        throw new ValidationError(`Subject "${options.subject}" is not configured for game ${options.gameId}`);
+      }
+      const result = await client.getHighestGradeMastered(timebackId, options.subject);
+      logger20.debug("Retrieved student highest grade mastered", {
+        timebackId,
+        gameId: options.gameId,
+        subject: options.subject,
+        highestGradeMastered: result.highestGradeMastered
+      });
+      return result;
+    }
   };
 });
 
@@ -34677,6 +34811,19 @@ async function getTimebackTokenResponse(config2) {
 function getAuthUrl(environment = "production") {
   return TIMEBACK_AUTH_URLS5[environment];
 }
+function parseEduBridgeGrade(value) {
+  if (value === null || value === undefined || value.trim() === "") {
+    return null;
+  }
+  const parsed = Number(value);
+  return isTimebackGrade3(parsed) ? parsed : null;
+}
+function normalizeHighestGradeMastered(response, subject) {
+  return {
+    subject,
+    highestGradeMastered: parseEduBridgeGrade(response.grades.highestGradeOverall)
+  };
+}
 function handleHttpError(res, errorBody, attempt, retries, url2) {
   const error = new TimebackApiError2(res.status, res.statusText, errorBody);
   if (res.status >= HTTP_STATUS5.CLIENT_ERROR_MIN && res.status < HTTP_STATUS5.CLIENT_ERROR_MAX) {
@@ -35021,7 +35168,8 @@ function createEduBridgeNamespace(client) {
   const analytics = {
     getEnrollmentFacts: async (enrollmentId, options) => client["request"](buildPath(`/edubridge/analytics/enrollment/${enrollmentId}`, {
       timezone: options?.timezone
-    }), "GET")
+    }), "GET"),
+    getHighestGradeMastered: async (studentId, subject) => client["request"](`/edubridge/analytics/highestGradeMastered/${encodeURIComponent(studentId)}/${encodeURIComponent(subject)}`, "GET")
   };
   return {
     enrollments,
@@ -36763,6 +36911,11 @@ class TimebackClient {
       ...options?.include?.perCourse && { courses }
     };
   }
+  async getHighestGradeMastered(studentId, subject) {
+    await this._ensureAuthenticated();
+    const response = await this.edubridge.analytics.getHighestGradeMastered(studentId, subject);
+    return normalizeHighestGradeMastered(response, subject);
+  }
   async getStudentXp(studentId, options) {
     await this._ensureAuthenticated();
     const enrollments = await this.edubridge.enrollments.listByUser(studentId);
@@ -94085,7 +94238,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, 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 logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, 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();
@@ -94323,6 +94476,20 @@ var init_timeback_controller = __esm(() => {
       user: ctx.user
     });
   });
+  unenrollCourse = requireDeveloper(async (ctx) => {
+    const body2 = await parseRequestBody(ctx.request, UnenrollCourseRequestSchema);
+    logger45.debug("Unenrolling student from current course", {
+      userId: ctx.user.id,
+      gameId: body2.gameId,
+      studentId: body2.studentId,
+      subject: body2.subject,
+      force: body2.force
+    });
+    return ctx.services.timeback.unenrollCourse({
+      ...body2,
+      user: ctx.user
+    });
+  });
   getStudentXp = requireDeveloper(async (ctx) => {
     const timebackId = ctx.params.timebackId;
     if (!timebackId) {
@@ -94415,6 +94582,33 @@ var init_timeback_controller = __esm(() => {
       include
     });
   });
+  getStudentHighestGradeMastered = 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 subjectParam = ctx.url.searchParams.get("subject");
+    if (!subjectParam) {
+      throw ApiError.badRequest("Missing required subject query parameter");
+    }
+    if (!isTimebackSubject2(subjectParam)) {
+      throw ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+    }
+    logger45.debug("Getting student highest grade mastered", {
+      requesterId: ctx.user.id,
+      timebackId,
+      gameId,
+      subject: subjectParam
+    });
+    return ctx.services.timeback.getStudentHighestGradeMastered(timebackId, ctx.user, {
+      gameId,
+      subject: subjectParam
+    });
+  });
   getRoster = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const courseId = ctx.params.courseId;
@@ -94750,8 +94944,10 @@ var init_timeback_controller = __esm(() => {
     endActivity,
     heartbeat,
     advanceCourse,
+    unenrollCourse,
     getStudentXp,
     getStudentMastery,
+    getStudentHighestGradeMastered,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -94960,6 +95156,10 @@ async function getMockTimebackUser(db2, gameId) {
   const timebackId = config.timeback.timebackId || "mock-student-00000001";
   return getMockTimebackData(db2, timebackId, gameId);
 }
+function getMockHighestGradeMastered(enrollments, subject) {
+  const subjectGrades = enrollments.filter((enrollment) => enrollment.subject === subject).map((enrollment) => enrollment.grade);
+  return subjectGrades.length > 0 ? Math.max(...subjectGrades) : null;
+}
 async function buildMockUserResponse(db2, user, gameId) {
   const timeback3 = user.timebackId ? await getMockTimebackData(db2, user.timebackId, gameId) : undefined;
   if (gameId) {
@@ -95654,6 +95854,7 @@ var init_timeback6 = __esm(() => {
   timebackRouter.post("/end-activity", handle2(timeback2.endActivity));
   timebackRouter.post("/heartbeat", handle2(timeback2.heartbeat));
   timebackRouter.post("/advance-course", handle2(timeback2.advanceCourse));
+  timebackRouter.post("/unenroll-course", handle2(timeback2.unenrollCourse));
   timebackRouter.get("/user", async (c2) => {
     const user = c2.get("user");
     const gameId = c2.get("gameId");
@@ -95806,6 +96007,39 @@ var init_timeback6 = __esm(() => {
     }
     return handle2(timeback2.getStudentMastery)(c2);
   });
+  timebackRouter.get("/student-highest-grade-mastered/:timebackId", async (c2) => {
+    const user = c2.get("user");
+    if (!user) {
+      const error2 = ApiError.unauthorized("Must be logged in to get student highest grade mastered");
+      return c2.json(createErrorResponse(error2), error2.status);
+    }
+    if (shouldMockTimeback()) {
+      const url2 = new URL(c2.req.url);
+      const subject = url2.searchParams.get("subject");
+      const contextGameId = c2.get("gameId");
+      const gameId = url2.searchParams.get("gameId") || (typeof contextGameId === "string" ? contextGameId : undefined);
+      if (!subject) {
+        const error2 = ApiError.badRequest("Missing required subject query parameter");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (!gameId) {
+        const error2 = ApiError.badRequest("Missing required gameId query parameter");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (!isTimebackSubject2(subject)) {
+        const error2 = ApiError.badRequest(`Invalid subject: ${subject}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      const db2 = c2.get("db");
+      const enrollments = await getMockEnrollments(db2);
+      const gameScopedEnrollments = filterEnrollmentsByGame(enrollments, gameId);
+      return c2.json({
+        subject,
+        highestGradeMastered: getMockHighestGradeMastered(gameScopedEnrollments, subject)
+      });
+    }
+    return handle2(timeback2.getStudentHighestGradeMastered)(c2);
+  });
 });
 
 // src/routes/integrations/lti.ts
@@ -98183,7 +98417,8 @@ program2.name("playcademy-sandbox").description("Local development server for Pl
       port,
       url: `http://localhost:${port}/api`,
       startedAt: Date.now(),
-      projectRoot: process.cwd()
+      projectRoot: process.cwd(),
+      gameId: server.gameId
     });
     const totalCourses = project?.timebackCourses?.length ?? 0;
     const excludedCount = options.timebackExcludedCourses ? options.timebackExcludedCourses.split(",").filter(Boolean).length : 0;

package/dist/constants.js

@@ -84,8 +84,10 @@ var init_timeback = __esm(() => {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
     GET_MASTERY: "/integrations/timeback/mastery",
+    GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
     HEARTBEAT: "/integrations/timeback/heartbeat",
-    ADVANCE_COURSE: "/integrations/timeback/advance-course"
+    ADVANCE_COURSE: "/integrations/timeback/advance-course",
+    UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
   };
   TIMEBACK_COURSE_DEFAULTS = {
     gradingScheme: "STANDARD",

package/dist/mocks/timeback.d.ts

@@ -30,6 +30,7 @@ export declare function getMockTimebackData(db: DatabaseInstance, timebackId: st
  * Uses the configured timebackId from sandbox config.
  */
 export declare function getMockTimebackUser(db: DatabaseInstance, gameId?: string): Promise<UserTimebackData>;
+export declare function getMockHighestGradeMastered(enrollments: UserEnrollment[], subject: string): number | null;
 /**
  * Build a complete user response with mock timeback data.
  * Used to bypass api-core when in mock mode (avoids real API calls).

package/dist/server.js

@@ -248,8 +248,10 @@ var init_timeback2 = __esm(() => {
     END_ACTIVITY: "/integrations/timeback/end-activity",
     GET_XP: "/integrations/timeback/xp",
     GET_MASTERY: "/integrations/timeback/mastery",
+    GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
     HEARTBEAT: "/integrations/timeback/heartbeat",
-    ADVANCE_COURSE: "/integrations/timeback/advance-course"
+    ADVANCE_COURSE: "/integrations/timeback/advance-course",
+    UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
   };
   TIMEBACK_COURSE_DEFAULTS = {
     gradingScheme: "STANDARD",
@@ -1075,7 +1077,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.4.1",
+    version: "0.4.2-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -28246,8 +28248,10 @@ var init_constants3 = __esm(() => {
       END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
       GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
       GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
+      GET_HIGHEST_GRADE_MASTERED: `/api${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}`,
       HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
-      ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`
+      ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`,
+      UNENROLL_COURSE: `/api${TIMEBACK_ROUTES.UNENROLL_COURSE}`
     }
   };
 });
@@ -29125,6 +29129,7 @@ var init_utils6 = __esm(() => {
     };
   });
   init_constants7();
+  init_constants7();
   if (process.env.DEBUG === "true") {
     process.env.TERM = "dumb";
   }
@@ -29901,7 +29906,7 @@ function isValidAdminAttributionDate(value) {
   const date3 = new Date(Date.UTC(year, month - 1, day, 12, 0, 0));
   return date3.getUTCFullYear() === year && date3.getUTCMonth() + 1 === month && date3.getUTCDate() === day;
 }
-var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
+var TIMEBACK_GRADES, TIMEBACK_SUBJECTS4, TimebackGradeSchema, TimebackSubjectSchema, CourseGoalsSchema, UpdateGameTimebackIntegrationRequestSchema, TimebackActivityDataSchema, EndActivityRequestSchema, GameRunMetricsSchema, GameCourseMetricsSchema, GameMetricsResponseSchema, AdvanceCourseRequestSchema, UnenrollCourseRequestSchema, HeartbeatRequestSchema, PopulateStudentRequestSchema, DerivedPlatformCourseConfigSchema, TimebackBaseConfigSchema, PlatformTimebackSetupRequestSchema, AdminTimebackMutationBaseSchema, AdminAttributionDateSchema, ADMIN_GRANT_XP_MIN = -1e5, ADMIN_GRANT_XP_MAX = 1e5, ADMIN_GRANT_XP_AMOUNT_RANGE_MESSAGE, GrantTimebackXpRequestSchema, AdjustTimebackTimeRequestSchema, AdjustTimebackMasteryRequestSchema, ReconcileMasteryForConfigChangeSchema, EnrollStudentRequestSchema, UnenrollStudentRequestSchema, ReactivateEnrollmentRequestSchema, InsertAssessmentTestSchema, CreateAssessmentRequestSchema, ReorderAssessmentsRequestSchema, ReorderQuestionsRequestSchema;
 var init_schemas4 = __esm(() => {
   init_drizzle_zod();
   init_esm();
@@ -30003,6 +30008,12 @@ var init_schemas4 = __esm(() => {
     studentId: exports_external.string().min(1),
     subject: TimebackSubjectSchema.optional()
   });
+  UnenrollCourseRequestSchema = exports_external.object({
+    gameId: exports_external.string().uuid(),
+    studentId: exports_external.string().min(1),
+    subject: TimebackSubjectSchema.optional(),
+    force: exports_external.boolean().optional()
+  });
   HeartbeatRequestSchema = exports_external.object({
     gameId: exports_external.string().uuid(),
     studentId: exports_external.string().min(1),
@@ -33207,15 +33218,14 @@ var init_timeback_service = __esm(() => {
         inProgress: result.inProgress
       };
     }
-    async advanceCourse({
+    async resolveActiveGameCourse({
       gameId,
       studentId,
       subject,
-      user
+      action
     }) {
       const client = this.requireClient();
       const db2 = this.deps.db;
-      await this.deps.validateDeveloperAccess(user, gameId);
       const integrations = await db2.query.gameTimebackIntegrations.findMany({
         where: subject ? and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.subject, subject)) : eq(gameTimebackIntegrations.gameId, gameId)
       });
@@ -33230,12 +33240,30 @@ var init_timeback_service = __esm(() => {
       }
       const subjectsInPlay = new Set(enrolledIntegrations.map((i2) => i2.subject));
       if (subjectsInPlay.size > 1) {
-        throw new ValidationError(`Ambiguous Timeback advance: student is enrolled in ${subjectsInPlay.size} parallel ladders (${[...subjectsInPlay].join(", ")}); pass { subject } to disambiguate`);
+        throw new ValidationError(`Ambiguous Timeback ${action}: student is enrolled in ${subjectsInPlay.size} parallel ladders (${[...subjectsInPlay].join(", ")}); pass { subject } to disambiguate`);
       }
       const currentIntegration = enrolledIntegrations.toSorted((left, right) => left.grade - right.grade)[0];
+      const currentEnrollment = enrollments.find((enrollment) => enrollment.course.id === currentIntegration.courseId);
+      return { currentIntegration, currentEnrollment, enrollments };
+    }
+    async advanceCourse({
+      gameId,
+      studentId,
+      subject,
+      user
+    }) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const { currentIntegration, enrollments } = await this.resolveActiveGameCourse({
+        gameId,
+        studentId,
+        subject,
+        action: "advance"
+      });
       const masteryStatus = await client.getMasteryStatus(currentIntegration.courseId, studentId);
       if (!masteryStatus) {
-        throw new ValidationError(`Cannot advance course: mastery status is unavailable for course ${currentIntegration.courseId}. Ensure the course has mastery configuration and the student has enrollment analytics before calling client.timeback.advanceCourse().`);
+        throw new ValidationError(`Cannot advance course: mastery status is unavailable for course ${currentIntegration.courseId}. Ensure the course has mastery configuration and the student has enrollment analytics before calling client.timeback.course.advance().`);
       }
       if (!masteryStatus.isComplete) {
         const promotion2 = {
@@ -33273,6 +33301,93 @@ var init_timeback_service = __esm(() => {
       });
       return { status: "ok", promotion };
     }
+    async unenrollCourse({
+      gameId,
+      studentId,
+      subject,
+      force,
+      user
+    }) {
+      const client = this.requireClient();
+      await this.deps.validateDeveloperAccess(user, gameId);
+      const { currentIntegration, currentEnrollment } = await this.resolveActiveGameCourse({
+        gameId,
+        studentId,
+        subject,
+        action: "unenroll"
+      });
+      const schoolId = currentEnrollment.school.id;
+      const masteryStatus = await client.getMasteryStatus(currentIntegration.courseId, studentId);
+      if (!masteryStatus && !force) {
+        throw new ValidationError(`Cannot unenroll course: mastery status is unavailable for course ${currentIntegration.courseId}. Pass { force: true } to unenroll without mastery data.`);
+      }
+      if (masteryStatus && !masteryStatus.isComplete && !force) {
+        const unenrollment = {
+          status: "not-mastered",
+          currentCourseId: currentIntegration.courseId,
+          masteredUnits: masteryStatus.masteredUnits,
+          masterableUnits: masteryStatus.masterableUnits
+        };
+        logger20.debug("Skipping game-initiated course unenroll because mastery is incomplete", {
+          event: "timeback.course.unenroll",
+          outcome: "not-mastered",
+          gameId,
+          studentId,
+          courseId: currentIntegration.courseId,
+          subject: currentIntegration.subject,
+          grade: currentIntegration.grade,
+          masteredUnits: masteryStatus.masteredUnits,
+          masterableUnits: masteryStatus.masterableUnits,
+          forced: false,
+          requesterUserId: user.id
+        });
+        return { status: "ok", unenrollment };
+      }
+      const forcedEarlyExit = Boolean(force && (!masteryStatus || !masteryStatus.isComplete));
+      if (forcedEarlyExit) {
+        logger20.warn("Force-unenrolled student before mastery completion", {
+          event: "timeback.course.unenroll",
+          outcome: "force-unenrolled",
+          gameId,
+          studentId,
+          courseId: currentIntegration.courseId,
+          subject: currentIntegration.subject,
+          grade: currentIntegration.grade,
+          masteredUnits: masteryStatus?.masteredUnits,
+          masterableUnits: masteryStatus?.masterableUnits,
+          masteryStatusAvailable: Boolean(masteryStatus),
+          forced: true,
+          requesterUserId: user.id
+        });
+      }
+      await client.edubridge.enrollments.unenroll(studentId, currentIntegration.courseId, schoolId ? { schoolId } : {});
+      client.invalidateEnrollments(studentId);
+      logger20.info("Game-initiated course unenroll completed", {
+        event: "timeback.course.unenroll",
+        outcome: "unenrolled",
+        gameId,
+        studentId,
+        courseId: currentIntegration.courseId,
+        subject: currentIntegration.subject,
+        grade: currentIntegration.grade,
+        masteredUnits: masteryStatus?.masteredUnits,
+        masterableUnits: masteryStatus?.masterableUnits,
+        forced: forcedEarlyExit,
+        requesterUserId: user.id
+      });
+      return {
+        status: "ok",
+        unenrollment: {
+          status: "unenrolled",
+          currentCourseId: currentIntegration.courseId,
+          ...masteryStatus ? {
+            masteredUnits: masteryStatus.masteredUnits,
+            masterableUnits: masteryStatus.masterableUnits
+          } : {},
+          ...forcedEarlyExit ? { forced: true } : {}
+        }
+      };
+    }
     async recordHeartbeat({
       gameId,
       studentId,
@@ -33447,6 +33562,25 @@ var init_timeback_service = __esm(() => {
       });
       return result;
     }
+    async getStudentHighestGradeMastered(timebackId, user, options) {
+      const client = this.requireClient();
+      const db2 = this.deps.db;
+      await this.deps.validateDeveloperAccess(user, options.gameId);
+      const integration = await db2.query.gameTimebackIntegrations.findFirst({
+        where: and(eq(gameTimebackIntegrations.gameId, options.gameId), eq(gameTimebackIntegrations.subject, options.subject))
+      });
+      if (!integration) {
+        throw new ValidationError(`Subject "${options.subject}" is not configured for game ${options.gameId}`);
+      }
+      const result = await client.getHighestGradeMastered(timebackId, options.subject);
+      logger20.debug("Retrieved student highest grade mastered", {
+        timebackId,
+        gameId: options.gameId,
+        subject: options.subject,
+        highestGradeMastered: result.highestGradeMastered
+      });
+      return result;
+    }
   };
 });
 
@@ -34676,6 +34810,19 @@ async function getTimebackTokenResponse(config2) {
 function getAuthUrl(environment = "production") {
   return TIMEBACK_AUTH_URLS5[environment];
 }
+function parseEduBridgeGrade(value) {
+  if (value === null || value === undefined || value.trim() === "") {
+    return null;
+  }
+  const parsed = Number(value);
+  return isTimebackGrade3(parsed) ? parsed : null;
+}
+function normalizeHighestGradeMastered(response, subject) {
+  return {
+    subject,
+    highestGradeMastered: parseEduBridgeGrade(response.grades.highestGradeOverall)
+  };
+}
 function handleHttpError(res, errorBody, attempt, retries, url2) {
   const error = new TimebackApiError2(res.status, res.statusText, errorBody);
   if (res.status >= HTTP_STATUS5.CLIENT_ERROR_MIN && res.status < HTTP_STATUS5.CLIENT_ERROR_MAX) {
@@ -35020,7 +35167,8 @@ function createEduBridgeNamespace(client) {
   const analytics = {
     getEnrollmentFacts: async (enrollmentId, options) => client["request"](buildPath(`/edubridge/analytics/enrollment/${enrollmentId}`, {
       timezone: options?.timezone
-    }), "GET")
+    }), "GET"),
+    getHighestGradeMastered: async (studentId, subject) => client["request"](`/edubridge/analytics/highestGradeMastered/${encodeURIComponent(studentId)}/${encodeURIComponent(subject)}`, "GET")
   };
   return {
     enrollments,
@@ -36762,6 +36910,11 @@ class TimebackClient {
       ...options?.include?.perCourse && { courses }
     };
   }
+  async getHighestGradeMastered(studentId, subject) {
+    await this._ensureAuthenticated();
+    const response = await this.edubridge.analytics.getHighestGradeMastered(studentId, subject);
+    return normalizeHighestGradeMastered(response, subject);
+  }
   async getStudentXp(studentId, options) {
     await this._ensureAuthenticated();
     const enrollments = await this.edubridge.enrollments.listByUser(studentId);
@@ -94084,7 +94237,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, 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 logger45, populateStudent, getUser, getUserEnrollments, getUserById, setupIntegration, getIntegrations, updateIntegration, getIntegrationConfig, verifyIntegration, getConfig, deleteIntegrations, endActivity, heartbeat, advanceCourse, unenrollCourse, getStudentXp, getStudentMastery, getStudentHighestGradeMastered, 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();
@@ -94322,6 +94475,20 @@ var init_timeback_controller = __esm(() => {
       user: ctx.user
     });
   });
+  unenrollCourse = requireDeveloper(async (ctx) => {
+    const body2 = await parseRequestBody(ctx.request, UnenrollCourseRequestSchema);
+    logger45.debug("Unenrolling student from current course", {
+      userId: ctx.user.id,
+      gameId: body2.gameId,
+      studentId: body2.studentId,
+      subject: body2.subject,
+      force: body2.force
+    });
+    return ctx.services.timeback.unenrollCourse({
+      ...body2,
+      user: ctx.user
+    });
+  });
   getStudentXp = requireDeveloper(async (ctx) => {
     const timebackId = ctx.params.timebackId;
     if (!timebackId) {
@@ -94414,6 +94581,33 @@ var init_timeback_controller = __esm(() => {
       include
     });
   });
+  getStudentHighestGradeMastered = 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 subjectParam = ctx.url.searchParams.get("subject");
+    if (!subjectParam) {
+      throw ApiError.badRequest("Missing required subject query parameter");
+    }
+    if (!isTimebackSubject2(subjectParam)) {
+      throw ApiError.badRequest(`Invalid subject: ${subjectParam}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+    }
+    logger45.debug("Getting student highest grade mastered", {
+      requesterId: ctx.user.id,
+      timebackId,
+      gameId,
+      subject: subjectParam
+    });
+    return ctx.services.timeback.getStudentHighestGradeMastered(timebackId, ctx.user, {
+      gameId,
+      subject: subjectParam
+    });
+  });
   getRoster = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const courseId = ctx.params.courseId;
@@ -94749,8 +94943,10 @@ var init_timeback_controller = __esm(() => {
     endActivity,
     heartbeat,
     advanceCourse,
+    unenrollCourse,
     getStudentXp,
     getStudentMastery,
+    getStudentHighestGradeMastered,
     getRoster,
     getStudentOverview,
     getGameMetrics,
@@ -94959,6 +95155,10 @@ async function getMockTimebackUser(db2, gameId) {
   const timebackId = config.timeback.timebackId || "mock-student-00000001";
   return getMockTimebackData(db2, timebackId, gameId);
 }
+function getMockHighestGradeMastered(enrollments, subject) {
+  const subjectGrades = enrollments.filter((enrollment) => enrollment.subject === subject).map((enrollment) => enrollment.grade);
+  return subjectGrades.length > 0 ? Math.max(...subjectGrades) : null;
+}
 async function buildMockUserResponse(db2, user, gameId) {
   const timeback3 = user.timebackId ? await getMockTimebackData(db2, user.timebackId, gameId) : undefined;
   if (gameId) {
@@ -95653,6 +95853,7 @@ var init_timeback6 = __esm(() => {
   timebackRouter.post("/end-activity", handle2(timeback2.endActivity));
   timebackRouter.post("/heartbeat", handle2(timeback2.heartbeat));
   timebackRouter.post("/advance-course", handle2(timeback2.advanceCourse));
+  timebackRouter.post("/unenroll-course", handle2(timeback2.unenrollCourse));
   timebackRouter.get("/user", async (c2) => {
     const user = c2.get("user");
     const gameId = c2.get("gameId");
@@ -95805,6 +96006,39 @@ var init_timeback6 = __esm(() => {
     }
     return handle2(timeback2.getStudentMastery)(c2);
   });
+  timebackRouter.get("/student-highest-grade-mastered/:timebackId", async (c2) => {
+    const user = c2.get("user");
+    if (!user) {
+      const error2 = ApiError.unauthorized("Must be logged in to get student highest grade mastered");
+      return c2.json(createErrorResponse(error2), error2.status);
+    }
+    if (shouldMockTimeback()) {
+      const url2 = new URL(c2.req.url);
+      const subject = url2.searchParams.get("subject");
+      const contextGameId = c2.get("gameId");
+      const gameId = url2.searchParams.get("gameId") || (typeof contextGameId === "string" ? contextGameId : undefined);
+      if (!subject) {
+        const error2 = ApiError.badRequest("Missing required subject query parameter");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (!gameId) {
+        const error2 = ApiError.badRequest("Missing required gameId query parameter");
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      if (!isTimebackSubject2(subject)) {
+        const error2 = ApiError.badRequest(`Invalid subject: ${subject}. Valid subjects: ${TIMEBACK_SUBJECTS4.join(", ")}`);
+        return c2.json(createErrorResponse(error2), error2.status);
+      }
+      const db2 = c2.get("db");
+      const enrollments = await getMockEnrollments(db2);
+      const gameScopedEnrollments = filterEnrollmentsByGame(enrollments, gameId);
+      return c2.json({
+        subject,
+        highestGradeMastered: getMockHighestGradeMastered(gameScopedEnrollments, subject)
+      });
+    }
+    return handle2(timeback2.getStudentHighestGradeMastered)(c2);
+  });
 });
 
 // src/routes/integrations/lti.ts

package/package.json

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