@playcademy/sandbox 0.3.17-beta.20 → 0.3.17-beta.22

package/dist/cli.js

@@ -1330,7 +1330,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.3.17-beta.20",
+    version: "0.3.17-beta.22",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -30922,21 +30922,25 @@ class TimebackAdminService {
     });
     return new Map(results);
   }
+  async fetchCaliperEventsForStudent(client, studentId, source, limit) {
+    const actorId = `${client.getBaseUrl().replace(/\/$/, "")}/ims/oneroster/rostering/v1p2/users/${studentId}`;
+    const { events } = await client.caliper.events.list({
+      limit,
+      actorId,
+      ...source.sourceMode === "production" ? { sensor: source.sensorUrl } : {},
+      extensions: {
+        gameId: source.gameId
+      }
+    });
+    return events;
+  }
   async listRecentActivityForStudent(client, studentId, source, relevantCourseIds, maxResults = TimebackAdminService.RECENT_ACTIVITY_LIMIT) {
     if (relevantCourseIds.size === 0) {
       return [];
     }
     try {
-      const actorId = `${client.getBaseUrl().replace(/\/$/, "")}/ims/oneroster/rostering/v1p2/users/${studentId}`;
       const eventLimit = Math.min(Math.max(200, maxResults * 20), TimebackAdminService.MAX_RECENT_ACTIVITY_EVENT_FETCH);
-      const { events } = await client.caliper.events.list({
-        limit: eventLimit,
-        actorId,
-        ...source.sourceMode === "production" ? { sensor: source.sensorUrl } : {},
-        extensions: {
-          gameId: source.gameId
-        }
-      });
+      const events = await this.fetchCaliperEventsForStudent(client, studentId, source, eventLimit);
       return TimebackAdminService.mapRecentActivityItems(events, relevantCourseIds).slice(0, maxResults);
     } catch (error) {
       logger16.warn("Failed to load recent Caliper activity", {
@@ -31060,6 +31064,42 @@ class TimebackAdminService {
     const hasMore = allActivities.length > safeOffset + safeLimit;
     return { activities, hasMore };
   }
+  async getActivityDetail(user, options) {
+    const { gameId, studentId, courseId, activityId, runId } = options;
+    const client = this.requireClient();
+    await this.deps.validateGameManagementAccess(user, gameId);
+    const [integration, gameSource] = await Promise.all([
+      this.deps.db.query.gameTimebackIntegrations.findFirst({
+        where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.courseId, courseId))
+      }),
+      this.getGameActivitySource(gameId)
+    ]);
+    if (!integration) {
+      throw new NotFoundError("Timeback integration", `${gameId}:${courseId}`);
+    }
+    await this.assertStudentEnrolledInCourse(client, studentId, courseId);
+    const events = await this.fetchCaliperEventsForStudent(client, studentId, gameSource, TimebackAdminService.MAX_RECENT_ACTIVITY_EVENT_FETCH);
+    const relevantCourseIds = new Set([courseId]);
+    let matchedEvents;
+    let activity;
+    if (runId) {
+      const gameplayEvents = events.filter((event) => (event.type === "ActivityEvent" || event.type === "TimeSpentEvent") && !isCaliperRemediationOrCompletionEvent(event));
+      const groups = groupCaliperEventsByRun(gameplayEvents);
+      matchedEvents = [...groups.values()].find((group) => group.some((event) => getCanonicalRunId(event.session) === runId && event.externalId === activityId)) ?? [];
+      activity = mapCaliperEventGroupToActivity(matchedEvents, relevantCourseIds);
+    } else {
+      matchedEvents = events.filter((event) => event.externalId === activityId);
+      if (matchedEvents.length > 0) {
+        activity = mapCaliperEventToRemediationActivity(matchedEvents[0], relevantCourseIds) ?? mapCaliperEventGroupToActivity(matchedEvents, relevantCourseIds);
+      } else {
+        activity = null;
+      }
+    }
+    if (!activity) {
+      throw new NotFoundError("Activity", activityId);
+    }
+    return { activity, rawEvents: matchedEvents };
+  }
   async grantManualXp(data, user) {
     const { client, sensorUrl, appName, actor } = await this.resolveAdminMutationContext(data.gameId, data.courseId, user, data.studentId);
     await client.recordAdminXpAdjustment({
@@ -36277,7 +36317,7 @@ class MasteryTracker {
   }
   async checkProgress(input) {
     const { studentId, courseId, resourceId, masteredUnits } = input;
-    if (typeof masteredUnits !== "number" || masteredUnits <= 0) {
+    if (typeof masteredUnits !== "number" || masteredUnits === 0) {
       return;
     }
     const status = await this.calculateStatus({
@@ -36289,9 +36329,11 @@ class MasteryTracker {
     if (!status) {
       return;
     }
+    const wasComplete = status.historicalMasteredUnits >= status.masterableUnits;
     return {
       pctCompleteApp: status.pctCompleteApp,
-      masteryAchieved: status.historicalMasteredUnits < status.masterableUnits && status.isComplete
+      masteryAchieved: !wasComplete && status.isComplete,
+      masteryRevoked: wasComplete && !status.isComplete
     };
   }
   async getStatus(input) {
@@ -36332,7 +36374,7 @@ class MasteryTracker {
       return;
     }
     const historicalMasteredUnits = this.sumAnalyticsMetric(facts, "masteredUnits");
-    const totalMastered = historicalMasteredUnits + additionalMasteredUnits;
+    const totalMastered = Math.max(0, historicalMasteredUnits + additionalMasteredUnits);
     const rawPct = totalMastered / masterableUnits * 100;
     const pctCompleteApp = Math.min(100, Math.max(0, Math.round(rawPct)));
     return {
@@ -36382,6 +36424,45 @@ class MasteryTracker {
       });
     }
   }
+  async revokeCompletionEntry(studentId, courseId, classId, appName) {
+    const ids = deriveSourcedIds2(courseId);
+    const lineItemId = `${ids.course}-mastery-completion-assessment`;
+    const resultId = `${lineItemId}:${studentId}:completion`;
+    try {
+      await this.onerosterNamespace.assessmentLineItems.findOrCreate(lineItemId, {
+        sourcedId: lineItemId,
+        title: "Mastery Completion",
+        status: ONEROSTER_STATUS4.active,
+        ...classId ? { class: { sourcedId: classId } } : { course: { sourcedId: ids.course } },
+        ...ids.componentResource ? { componentResource: { sourcedId: ids.componentResource } } : {}
+      });
+      await this.onerosterNamespace.assessmentResults.upsert(resultId, {
+        sourcedId: resultId,
+        status: ONEROSTER_STATUS4.active,
+        assessmentLineItem: { sourcedId: lineItemId },
+        student: { sourcedId: studentId },
+        score: 0,
+        scoreDate: new Date().toISOString(),
+        scoreStatus: SCORE_STATUS4.notSubmitted,
+        inProgress: "true",
+        metadata: {
+          isMasteryCompletion: true,
+          appName
+        }
+      });
+      log.info("[MasteryTracker] Revoked mastery completion entry", {
+        studentId,
+        lineItemId,
+        resultId
+      });
+    } catch (error) {
+      log.error("[MasteryTracker] Failed to revoke mastery completion entry", {
+        studentId,
+        lineItemId,
+        error
+      });
+    }
+  }
   async resolveMasterableUnits(resourceId) {
     if (!resourceId) {
       return;
@@ -36591,6 +36672,9 @@ class ProgressRecorder {
         sensorUrl: progressData.sensorUrl
       });
     }
+    if (masteryProgress?.masteryRevoked) {
+      await this.masteryTracker.revokeCompletionEntry(studentId, courseId, progressData.classId, progressData.appName);
+    }
     await this.emitCaliperEvent({
       studentId,
       studentEmail,
@@ -94183,7 +94267,7 @@ var init_schemas11 = __esm(() => {
       inactiveSeconds: exports_external.number().nonnegative().optional()
     }).optional(),
     xpEarned: exports_external.number().optional(),
-    masteredUnits: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().optional(),
     extensions: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
   });
   AdvanceCourseRequestSchema = exports_external.object({
@@ -96478,7 +96562,7 @@ var init_sprite_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger64, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getStudentActivity, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
+var logger64, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -96814,6 +96898,31 @@ var init_timeback_controller = __esm(() => {
       offset
     });
   });
+  getActivityDetail = requireGameManagementAccess(async (ctx) => {
+    const timebackId = ctx.params.timebackId;
+    const courseId = ctx.params.courseId;
+    const activityId = ctx.params.activityId;
+    const gameId = ctx.url.searchParams.get("gameId") || undefined;
+    const runId = ctx.url.searchParams.get("runId") || undefined;
+    if (!timebackId || !courseId || !activityId || !gameId) {
+      throw ApiError.badRequest("Missing timebackId, courseId, or activityId path parameter, or gameId query parameter");
+    }
+    logger64.debug("Getting activity detail", {
+      requesterId: ctx.user.id,
+      timebackId,
+      courseId,
+      activityId,
+      gameId,
+      runId
+    });
+    return ctx.services.timebackAdmin.getActivityDetail(ctx.user, {
+      gameId,
+      studentId: timebackId,
+      courseId,
+      activityId,
+      runId
+    });
+  });
   grantXp = requireDeveloper(async (ctx) => {
     const body2 = await parseRequestBody(ctx.request, GrantTimebackXpRequestSchema);
     logger64.debug("Granting manual XP", {
@@ -96916,6 +97025,7 @@ var init_timeback_controller = __esm(() => {
     getRoster,
     getStudentOverview,
     getStudentActivity,
+    getActivityDetail,
     grantXp,
     adjustTime,
     adjustMastery,

package/dist/server.js

@@ -1329,7 +1329,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.3.17-beta.20",
+    version: "0.3.17-beta.22",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -30921,21 +30921,25 @@ class TimebackAdminService {
     });
     return new Map(results);
   }
+  async fetchCaliperEventsForStudent(client, studentId, source, limit) {
+    const actorId = `${client.getBaseUrl().replace(/\/$/, "")}/ims/oneroster/rostering/v1p2/users/${studentId}`;
+    const { events } = await client.caliper.events.list({
+      limit,
+      actorId,
+      ...source.sourceMode === "production" ? { sensor: source.sensorUrl } : {},
+      extensions: {
+        gameId: source.gameId
+      }
+    });
+    return events;
+  }
   async listRecentActivityForStudent(client, studentId, source, relevantCourseIds, maxResults = TimebackAdminService.RECENT_ACTIVITY_LIMIT) {
     if (relevantCourseIds.size === 0) {
       return [];
     }
     try {
-      const actorId = `${client.getBaseUrl().replace(/\/$/, "")}/ims/oneroster/rostering/v1p2/users/${studentId}`;
       const eventLimit = Math.min(Math.max(200, maxResults * 20), TimebackAdminService.MAX_RECENT_ACTIVITY_EVENT_FETCH);
-      const { events } = await client.caliper.events.list({
-        limit: eventLimit,
-        actorId,
-        ...source.sourceMode === "production" ? { sensor: source.sensorUrl } : {},
-        extensions: {
-          gameId: source.gameId
-        }
-      });
+      const events = await this.fetchCaliperEventsForStudent(client, studentId, source, eventLimit);
       return TimebackAdminService.mapRecentActivityItems(events, relevantCourseIds).slice(0, maxResults);
     } catch (error) {
       logger16.warn("Failed to load recent Caliper activity", {
@@ -31059,6 +31063,42 @@ class TimebackAdminService {
     const hasMore = allActivities.length > safeOffset + safeLimit;
     return { activities, hasMore };
   }
+  async getActivityDetail(user, options) {
+    const { gameId, studentId, courseId, activityId, runId } = options;
+    const client = this.requireClient();
+    await this.deps.validateGameManagementAccess(user, gameId);
+    const [integration, gameSource] = await Promise.all([
+      this.deps.db.query.gameTimebackIntegrations.findFirst({
+        where: and(eq(gameTimebackIntegrations.gameId, gameId), eq(gameTimebackIntegrations.courseId, courseId))
+      }),
+      this.getGameActivitySource(gameId)
+    ]);
+    if (!integration) {
+      throw new NotFoundError("Timeback integration", `${gameId}:${courseId}`);
+    }
+    await this.assertStudentEnrolledInCourse(client, studentId, courseId);
+    const events = await this.fetchCaliperEventsForStudent(client, studentId, gameSource, TimebackAdminService.MAX_RECENT_ACTIVITY_EVENT_FETCH);
+    const relevantCourseIds = new Set([courseId]);
+    let matchedEvents;
+    let activity;
+    if (runId) {
+      const gameplayEvents = events.filter((event) => (event.type === "ActivityEvent" || event.type === "TimeSpentEvent") && !isCaliperRemediationOrCompletionEvent(event));
+      const groups = groupCaliperEventsByRun(gameplayEvents);
+      matchedEvents = [...groups.values()].find((group) => group.some((event) => getCanonicalRunId(event.session) === runId && event.externalId === activityId)) ?? [];
+      activity = mapCaliperEventGroupToActivity(matchedEvents, relevantCourseIds);
+    } else {
+      matchedEvents = events.filter((event) => event.externalId === activityId);
+      if (matchedEvents.length > 0) {
+        activity = mapCaliperEventToRemediationActivity(matchedEvents[0], relevantCourseIds) ?? mapCaliperEventGroupToActivity(matchedEvents, relevantCourseIds);
+      } else {
+        activity = null;
+      }
+    }
+    if (!activity) {
+      throw new NotFoundError("Activity", activityId);
+    }
+    return { activity, rawEvents: matchedEvents };
+  }
   async grantManualXp(data, user) {
     const { client, sensorUrl, appName, actor } = await this.resolveAdminMutationContext(data.gameId, data.courseId, user, data.studentId);
     await client.recordAdminXpAdjustment({
@@ -36276,7 +36316,7 @@ class MasteryTracker {
   }
   async checkProgress(input) {
     const { studentId, courseId, resourceId, masteredUnits } = input;
-    if (typeof masteredUnits !== "number" || masteredUnits <= 0) {
+    if (typeof masteredUnits !== "number" || masteredUnits === 0) {
       return;
     }
     const status = await this.calculateStatus({
@@ -36288,9 +36328,11 @@ class MasteryTracker {
     if (!status) {
       return;
     }
+    const wasComplete = status.historicalMasteredUnits >= status.masterableUnits;
     return {
       pctCompleteApp: status.pctCompleteApp,
-      masteryAchieved: status.historicalMasteredUnits < status.masterableUnits && status.isComplete
+      masteryAchieved: !wasComplete && status.isComplete,
+      masteryRevoked: wasComplete && !status.isComplete
     };
   }
   async getStatus(input) {
@@ -36331,7 +36373,7 @@ class MasteryTracker {
       return;
     }
     const historicalMasteredUnits = this.sumAnalyticsMetric(facts, "masteredUnits");
-    const totalMastered = historicalMasteredUnits + additionalMasteredUnits;
+    const totalMastered = Math.max(0, historicalMasteredUnits + additionalMasteredUnits);
     const rawPct = totalMastered / masterableUnits * 100;
     const pctCompleteApp = Math.min(100, Math.max(0, Math.round(rawPct)));
     return {
@@ -36381,6 +36423,45 @@ class MasteryTracker {
       });
     }
   }
+  async revokeCompletionEntry(studentId, courseId, classId, appName) {
+    const ids = deriveSourcedIds2(courseId);
+    const lineItemId = `${ids.course}-mastery-completion-assessment`;
+    const resultId = `${lineItemId}:${studentId}:completion`;
+    try {
+      await this.onerosterNamespace.assessmentLineItems.findOrCreate(lineItemId, {
+        sourcedId: lineItemId,
+        title: "Mastery Completion",
+        status: ONEROSTER_STATUS4.active,
+        ...classId ? { class: { sourcedId: classId } } : { course: { sourcedId: ids.course } },
+        ...ids.componentResource ? { componentResource: { sourcedId: ids.componentResource } } : {}
+      });
+      await this.onerosterNamespace.assessmentResults.upsert(resultId, {
+        sourcedId: resultId,
+        status: ONEROSTER_STATUS4.active,
+        assessmentLineItem: { sourcedId: lineItemId },
+        student: { sourcedId: studentId },
+        score: 0,
+        scoreDate: new Date().toISOString(),
+        scoreStatus: SCORE_STATUS4.notSubmitted,
+        inProgress: "true",
+        metadata: {
+          isMasteryCompletion: true,
+          appName
+        }
+      });
+      log.info("[MasteryTracker] Revoked mastery completion entry", {
+        studentId,
+        lineItemId,
+        resultId
+      });
+    } catch (error) {
+      log.error("[MasteryTracker] Failed to revoke mastery completion entry", {
+        studentId,
+        lineItemId,
+        error
+      });
+    }
+  }
   async resolveMasterableUnits(resourceId) {
     if (!resourceId) {
       return;
@@ -36590,6 +36671,9 @@ class ProgressRecorder {
         sensorUrl: progressData.sensorUrl
       });
     }
+    if (masteryProgress?.masteryRevoked) {
+      await this.masteryTracker.revokeCompletionEntry(studentId, courseId, progressData.classId, progressData.appName);
+    }
     await this.emitCaliperEvent({
       studentId,
       studentEmail,
@@ -94182,7 +94266,7 @@ var init_schemas11 = __esm(() => {
       inactiveSeconds: exports_external.number().nonnegative().optional()
     }).optional(),
     xpEarned: exports_external.number().optional(),
-    masteredUnits: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().optional(),
     extensions: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
   });
   AdvanceCourseRequestSchema = exports_external.object({
@@ -96477,7 +96561,7 @@ var init_sprite_controller = __esm(() => {
 });
 
 // ../api-core/src/controllers/timeback.controller.ts
-var logger64, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getStudentActivity, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
+var logger64, getTodayXp, getTotalXp, updateTodayXp, getXpHistory, populateStudent, getUser, getUserById, setupIntegration, getIntegrations, verifyIntegration, getConfig2, deleteIntegrations, endActivity, heartbeat, advanceCourse, getStudentXp, getRoster, getStudentOverview, getStudentActivity, getActivityDetail, grantXp, adjustTime, adjustMastery, toggleCompletion, searchStudents, enrollStudent, unenrollStudent, timeback2;
 var init_timeback_controller = __esm(() => {
   init_esm();
   init_schemas_index();
@@ -96813,6 +96897,31 @@ var init_timeback_controller = __esm(() => {
       offset
     });
   });
+  getActivityDetail = requireGameManagementAccess(async (ctx) => {
+    const timebackId = ctx.params.timebackId;
+    const courseId = ctx.params.courseId;
+    const activityId = ctx.params.activityId;
+    const gameId = ctx.url.searchParams.get("gameId") || undefined;
+    const runId = ctx.url.searchParams.get("runId") || undefined;
+    if (!timebackId || !courseId || !activityId || !gameId) {
+      throw ApiError.badRequest("Missing timebackId, courseId, or activityId path parameter, or gameId query parameter");
+    }
+    logger64.debug("Getting activity detail", {
+      requesterId: ctx.user.id,
+      timebackId,
+      courseId,
+      activityId,
+      gameId,
+      runId
+    });
+    return ctx.services.timebackAdmin.getActivityDetail(ctx.user, {
+      gameId,
+      studentId: timebackId,
+      courseId,
+      activityId,
+      runId
+    });
+  });
   grantXp = requireDeveloper(async (ctx) => {
     const body2 = await parseRequestBody(ctx.request, GrantTimebackXpRequestSchema);
     logger64.debug("Granting manual XP", {
@@ -96915,6 +97024,7 @@ var init_timeback_controller = __esm(() => {
     getRoster,
     getStudentOverview,
     getStudentActivity,
+    getActivityDetail,
     grantXp,
     adjustTime,
     adjustMastery,

package/package.json

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