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

package/dist/index.js

@@ -23746,7 +23746,7 @@ import path from "node:path";
 // package.json
 var package_default = {
   name: "@playcademy/vite-plugin",
-  version: "0.3.3-beta.1",
+  version: "0.3.3-beta.2",
   type: "module",
   exports: {
     ".": {
@@ -24339,6 +24339,8 @@ var TIMEBACK_COURSE_DEFAULTS;
 var TIMEBACK_RESOURCE_DEFAULTS;
 var TIMEBACK_COMPONENT_DEFAULTS;
 var TIMEBACK_COMPONENT_RESOURCE_DEFAULTS;
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES;
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE;
 var init_timeback2 = __esm(() => {
   TIMEBACK_ROUTES = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
@@ -24383,6 +24385,17 @@ var init_timeback2 = __esm(() => {
     sortOrder: 1,
     lessonType: "quiz"
   };
+  TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+    xp: 1,
+    mastery: 0,
+    score: 2
+  };
+  TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+    xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+    mastery: 0,
+    time: 60,
+    score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+  };
 });
 var WORKER_NAMING;
 var SECRETS_PREFIX = "secrets_";
@@ -25177,7 +25190,7 @@ var package_default2;
 var init_package = __esm(() => {
   package_default2 = {
     name: "@playcademy/sandbox",
-    version: "0.4.1-beta.1",
+    version: "0.4.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -53873,7 +53886,7 @@ var CourseGoalsSchema;
 var UpdateGameTimebackIntegrationRequestSchema;
 var TimebackActivityDataSchema;
 var EndActivityRequestSchema;
-var GameActivityMetricsSchema;
+var GameRunMetricsSchema;
 var GameCourseMetricsSchema;
 var GameMetricsResponseSchema;
 var AdvanceCourseRequestSchema;
@@ -53972,22 +53985,22 @@ var init_schemas4 = __esm(() => {
     message: "Cannot provide both masteredUnits and masteredUnitsAbsolute",
     path: ["masteredUnitsAbsolute"]
   });
-  GameActivityMetricsSchema = exports_external.object({
+  GameRunMetricsSchema = exports_external.object({
+    runId: exports_external.string().uuid(),
     activityId: exports_external.string().min(1),
     activityName: exports_external.string().optional(),
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    completionCount: exports_external.number().int().nonnegative(),
-    lastCompletedAt: exports_external.string().datetime().optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    score: exports_external.number().min(0).max(100).optional()
   });
   GameCourseMetricsSchema = exports_external.object({
     grade: TimebackGradeSchema,
     subject: TimebackSubjectSchema,
-    totalXp: exports_external.number().nonnegative(),
-    masteredUnits: exports_external.number().int().nonnegative(),
-    activeTimeSeconds: exports_external.number().nonnegative(),
-    activities: exports_external.array(GameActivityMetricsSchema).optional()
+    totalXp: exports_external.number().nonnegative().optional(),
+    masteredUnits: exports_external.number().int().nonnegative().optional(),
+    activeTimeSeconds: exports_external.number().nonnegative().optional(),
+    activities: exports_external.array(GameRunMetricsSchema).optional()
   });
   GameMetricsResponseSchema = exports_external.object({
     studentId: exports_external.string().min(1),
@@ -54257,6 +54270,122 @@ function compareEnrollmentsByRecency(a, b) {
 var init_timeback_admin_util = __esm(() => {
   init_errors();
 });
+function createMetricRow(definition) {
+  const { gameValue, kind, metric, timebackValue, tolerance } = definition;
+  if (timebackValue === undefined && gameValue === undefined) {
+    return null;
+  }
+  if (gameValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_reported_by_game",
+      ...timebackValue !== undefined ? { timebackValue } : {}
+    };
+  }
+  if (timebackValue === undefined) {
+    return {
+      metric,
+      kind,
+      status: "not_recorded_by_timeback",
+      gameValue
+    };
+  }
+  const delta = gameValue - timebackValue;
+  const isDiscrepant = tolerance === 0 ? delta !== 0 : Math.abs(delta) >= tolerance;
+  return {
+    metric,
+    kind,
+    status: isDiscrepant ? "discrepant" : "matched",
+    timebackValue,
+    gameValue,
+    delta
+  };
+}
+function createRunComparison(activity, gameRun) {
+  const runId = activity.runId ?? "";
+  if (!gameRun) {
+    return {
+      runId,
+      status: "not_reported",
+      discrepancyCount: 0,
+      rows: []
+    };
+  }
+  const rows = [
+    createMetricRow({
+      metric: "xp",
+      kind: "number",
+      timebackValue: activity.xpDelta,
+      gameValue: gameRun.totalXp,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.xp
+    }),
+    createMetricRow({
+      metric: "mastery",
+      kind: "number",
+      timebackValue: activity.masteredUnitsDelta,
+      gameValue: gameRun.masteredUnits,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.mastery
+    }),
+    createMetricRow({
+      metric: "time",
+      kind: "time",
+      timebackValue: activity.timeDeltaSeconds,
+      gameValue: gameRun.activeTimeSeconds,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.time
+    }),
+    createMetricRow({
+      metric: "score",
+      kind: "percent",
+      timebackValue: activity.score,
+      gameValue: gameRun.score,
+      tolerance: TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE.score
+    })
+  ].filter((row) => row !== null);
+  const discrepancyCount = rows.filter((row) => row.status === "discrepant").length;
+  return {
+    runId,
+    status: discrepancyCount > 0 ? "discrepant" : "matched",
+    discrepancyCount,
+    rows
+  };
+}
+function summarizeGameRunMetricsComparison(comparison) {
+  return {
+    runId: comparison.runId,
+    status: comparison.status,
+    discrepancyCount: comparison.discrepancyCount,
+    ...comparison.reason ? { reason: comparison.reason } : {}
+  };
+}
+function buildGameRunMetricComparisons(activities, course, response) {
+  const activitiesWithRunIds = activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0);
+  const comparisons = new Map;
+  if (activitiesWithRunIds.length === 0) {
+    return comparisons;
+  }
+  if (!response.supported) {
+    for (const activity of activitiesWithRunIds) {
+      comparisons.set(activity.runId, {
+        runId: activity.runId,
+        status: "unavailable",
+        discrepancyCount: 0,
+        reason: response.reason,
+        rows: []
+      });
+    }
+    return comparisons;
+  }
+  const gameCourseMetrics = response.metrics.courses.find((gameCourse) => gameCourse.grade === course.grade && gameCourse.subject === course.subject);
+  const gameRunsById = new Map(gameCourseMetrics?.activities?.map((gameRun) => [gameRun.runId.toLowerCase(), gameRun]));
+  for (const activity of activitiesWithRunIds) {
+    comparisons.set(activity.runId, createRunComparison(activity, gameRunsById.get(activity.runId.toLowerCase())));
+  }
+  return comparisons;
+}
+var init_timeback_game_metrics_comparison_util = __esm(() => {
+  init_src();
+});
 async function upsertMasteryCompletionEntry(params) {
   const { client, courseId, studentId, appName, action } = params;
   const ids = deriveSourcedIds(courseId);
@@ -54643,6 +54772,8 @@ class TimebackAdminService {
   static ANALYTICS_CONCURRENCY = 8;
   static MASTERABLE_UNITS_CONCURRENCY = 4;
   static GAME_METRICS_FETCH_TIMEOUT_MS = 1e4;
+  static GAME_METRICS_LIST_FETCH_TIMEOUT_MS = 3000;
+  static GAME_METRICS_RUN_IDS_PER_REQUEST = 50;
   constructor(deps) {
     this.deps = deps;
   }
@@ -54652,13 +54783,42 @@ class TimebackAdminService {
     }
     return this.deps.config.localGameUrls[slug2] ?? deployedUrl;
   }
-  static resolveGameMetricsUrl(baseUrl) {
+  static resolveGameMetricsUrl(baseUrl, runIds) {
     try {
-      return new URL("/__playcademy/metrics", baseUrl);
+      const url2 = new URL("/__playcademy/metrics", baseUrl);
+      for (const runId of runIds ?? []) {
+        url2.searchParams.append("runId", runId);
+      }
+      return url2;
     } catch {
       return null;
     }
   }
+  static normalizeRunIds(runIds, limit = Number.POSITIVE_INFINITY) {
+    const normalized = [];
+    const seen = new Set;
+    for (const runId of runIds ?? []) {
+      const value = runId.trim().toLowerCase();
+      if (isValidUUID(value) && !seen.has(value)) {
+        seen.add(value);
+        normalized.push(value);
+        if (normalized.length >= limit) {
+          break;
+        }
+      }
+    }
+    return normalized;
+  }
+  static chunkRunIds(runIds) {
+    const chunks = [];
+    for (let index2 = 0;index2 < runIds.length; index2 += this.GAME_METRICS_RUN_IDS_PER_REQUEST) {
+      chunks.push(runIds.slice(index2, index2 + this.GAME_METRICS_RUN_IDS_PER_REQUEST));
+    }
+    return chunks;
+  }
+  static isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+  }
   static roundXpToTenths(value) {
     const rounded = Math.round(value * TimebackAdminService.XP_PRECISION_FACTOR) / TimebackAdminService.XP_PRECISION_FACTOR;
     return Object.is(rounded, -0) ? 0 : rounded;
@@ -54819,6 +54979,56 @@ class TimebackAdminService {
     const remediationItems = events.map((event) => mapCaliperEventToRemediationActivity(event, relevantCourseIds)).filter((item) => Boolean(item));
     return [...groupedGameplayItems, ...remediationItems].toSorted((a, b) => b.occurredAt.localeCompare(a.occurredAt));
   }
+  async getGameMetricComparisonsForActivities(user, options) {
+    const runIds = TimebackAdminService.normalizeRunIds(options.activities.map((activity) => activity.runId).filter((runId) => Boolean(runId)));
+    if (runIds.length === 0) {
+      return new Map;
+    }
+    const activitiesByRunId = new Map(options.activities.filter((activity) => typeof activity.runId === "string" && activity.runId.length > 0).map((activity) => [activity.runId.toLowerCase(), activity]));
+    const comparisons = new Map;
+    await Promise.all(TimebackAdminService.chunkRunIds(runIds).map(async (chunk) => {
+      const activities = [];
+      for (const runId of chunk) {
+        const activity = activitiesByRunId.get(runId);
+        if (activity) {
+          activities.push(activity);
+        }
+      }
+      if (activities.length === 0) {
+        return;
+      }
+      let response;
+      try {
+        response = await this.getGameMetrics(options.gameId, options.studentId, user, {
+          runIds: chunk,
+          timeoutMs: options.timeoutMs
+        });
+      } catch (error) {
+        response = {
+          supported: false,
+          reason: "fetch_failed",
+          details: error instanceof Error ? error.message : String(error)
+        };
+      }
+      for (const [runId, comparison] of buildGameRunMetricComparisons(activities, options.course, response)) {
+        comparisons.set(runId, comparison);
+      }
+    }));
+    return comparisons;
+  }
+  async attachGameMetricSummariesToActivities(user, options) {
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, options);
+    if (comparisons.size === 0) {
+      return [...options.activities];
+    }
+    return options.activities.map((activity) => {
+      const comparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+      return comparison ? {
+        ...activity,
+        gameMetricsComparison: summarizeGameRunMetricsComparison(comparison)
+      } : activity;
+    });
+  }
   async getStudentEnrollmentsByCourseId(client, studentId, courseIds, options) {
     const enrollments = new Map;
     const allEnrollments = new Map;
@@ -54978,7 +55188,7 @@ class TimebackAdminService {
     });
     return { gameId, courseId, students: deduped };
   }
-  async getGameMetrics(gameId, timebackId, user) {
+  async getGameMetrics(gameId, timebackId, user, options) {
     const client = this.requireClient();
     await this.deps.validateGameManagementAccess(user, gameId);
     const [targetUser, integrations, game2, deployment] = await Promise.all([
@@ -55013,7 +55223,8 @@ class TimebackAdminService {
     if (!metricsBaseUrl) {
       return { supported: false, reason: "no_active_deployment" };
     }
-    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl);
+    const runIds = TimebackAdminService.normalizeRunIds(options?.runIds, TimebackAdminService.GAME_METRICS_RUN_IDS_PER_REQUEST);
+    const metricsUrl = TimebackAdminService.resolveGameMetricsUrl(metricsBaseUrl, runIds);
     if (!metricsUrl) {
       return {
         supported: false,
@@ -55023,7 +55234,7 @@ class TimebackAdminService {
     }
     const token = await this.deps.mintPlatformServiceToken(gameId, targetUser.id);
     const controller = new AbortController;
-    const timeout = setTimeout(() => controller.abort(), TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
+    const timeout = setTimeout(() => controller.abort(), options?.timeoutMs ?? TimebackAdminService.GAME_METRICS_FETCH_TIMEOUT_MS);
     let response;
     try {
       response = await fetch(metricsUrl, {
@@ -55035,10 +55246,19 @@ class TimebackAdminService {
         signal: controller.signal
       });
     } catch (error) {
+      const timedOut = TimebackAdminService.isAbortError(error);
+      let details;
+      if (timedOut) {
+        details = "Game metrics request timed out";
+      } else if (error instanceof Error) {
+        details = error.message;
+      } else {
+        details = String(error);
+      }
       return {
         supported: false,
-        reason: "fetch_failed",
-        details: error instanceof Error ? error.message : String(error)
+        reason: timedOut ? "timeout" : "fetch_failed",
+        details
       };
     } finally {
       clearTimeout(timeout);
@@ -55142,7 +55362,14 @@ class TimebackAdminService {
     const allActivities = await this.listRecentActivityForStudent(client, studentId, gameSource, relevantCourseIds, fetchLimit);
     const activities = allActivities.slice(safeOffset, safeOffset + safeLimit);
     const hasMore = allActivities.length > safeOffset + safeLimit;
-    return { activities, hasMore };
+    const activitiesWithGameMetrics = await this.attachGameMetricSummariesToActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities,
+      timeoutMs: TimebackAdminService.GAME_METRICS_LIST_FETCH_TIMEOUT_MS
+    });
+    return { activities: activitiesWithGameMetrics, hasMore };
   }
   async getActivityDetail(user, options) {
     const { gameId, studentId, courseId, activityId, runId } = options;
@@ -55178,7 +55405,22 @@ class TimebackAdminService {
     if (!activity) {
       throw new NotFoundError("Activity", activityId);
     }
-    return { activity, rawEvents: matchedEvents };
+    const comparisons = await this.getGameMetricComparisonsForActivities(user, {
+      gameId,
+      studentId,
+      course: { grade: integration.grade, subject: integration.subject },
+      activities: [activity]
+    });
+    const gameMetricsComparison = activity.runId ? comparisons.get(activity.runId) : undefined;
+    const activityWithGameMetrics = gameMetricsComparison ? {
+      ...activity,
+      gameMetricsComparison: summarizeGameRunMetricsComparison(gameMetricsComparison)
+    } : activity;
+    return {
+      activity: activityWithGameMetrics,
+      rawEvents: matchedEvents,
+      ...gameMetricsComparison ? { gameMetricsComparison } : {}
+    };
   }
   async grantManualXp(data, user) {
     const { client, sensorUrl, appName, actor } = await this.resolveAdminMutationContext(data.gameId, data.courseId, user, data.studentId);
@@ -55466,6 +55708,7 @@ var init_timeback_admin_service = __esm(() => {
   init_errors();
   init_timeback_admin_metrics_util();
   init_timeback_admin_util();
+  init_timeback_game_metrics_comparison_util();
   init_timeback_mastery_completion_util();
   init_timeback_util();
   logger17 = log.scope("TimebackAdminService");
@@ -120916,15 +121159,19 @@ var init_timeback_controller = __esm(() => {
   getGameMetrics = requireGameManagementAccess(async (ctx) => {
     const gameId = ctx.params.gameId;
     const timebackId = ctx.params.timebackId;
+    const runIds = [
+      ...new Set(ctx.url.searchParams.getAll("runId").map((runId) => runId.trim().toLowerCase()).filter(isValidUUID))
+    ];
     if (!gameId || !timebackId) {
       throw ApiError.badRequest("Missing gameId or timebackId path parameter");
     }
     logger45.debug("Getting game metrics", {
       requesterId: ctx.user.id,
       gameId,
-      timebackId
+      timebackId,
+      runIds
     });
-    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user);
+    return ctx.services.timebackAdmin.getGameMetrics(gameId, timebackId, ctx.user, { runIds });
   });
   getStudentActivity = requireGameManagementAccess(async (ctx) => {
     const timebackId = ctx.params.timebackId;
@@ -122767,6 +123014,17 @@ var POSTHOG_CONFIG = {
 var TIMEBACK_ORG_SOURCED_ID2 = "PLAYCADEMY";
 var TIMEBACK_ORG_NAME2 = "Playcademy Studios";
 var TIMEBACK_ORG_TYPE2 = "department";
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES2 = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE2 = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES2.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES2.score
+};
 // src/lib/sandbox/timeback.ts
 function detectTimebackOptions() {
   if (process.env.TIMEBACK_LOCAL === "true") {
@@ -122983,6 +123241,8 @@ var TIMEBACK_COURSE_DEFAULTS2;
 var TIMEBACK_RESOURCE_DEFAULTS2;
 var TIMEBACK_COMPONENT_DEFAULTS2;
 var TIMEBACK_COMPONENT_RESOURCE_DEFAULTS2;
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES3;
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE3;
 var init_timeback7 = __esm8(() => {
   TIMEBACK_ROUTES2 = {
     END_ACTIVITY: "/integrations/timeback/end-activity",
@@ -123027,6 +123287,17 @@ var init_timeback7 = __esm8(() => {
     sortOrder: 1,
     lessonType: "quiz"
   };
+  TIMEBACK_GAME_METRIC_DECIMAL_PLACES3 = {
+    xp: 1,
+    mastery: 0,
+    score: 2
+  };
+  TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE3 = {
+    xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES3.xp,
+    mastery: 0,
+    time: 60,
+    score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES3.score
+  };
 });
 var WORKER_NAMING2;
 var init_cloudflare2 = __esm8(() => {

package/package.json

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