@playcademy/sandbox 0.11.0 → 0.11.1-beta.2

package/README.md

@@ -199,17 +199,18 @@ bunx @playcademy/sandbox \
   --timeback-student-id your-student-sourcedId
 ```
 
-| Option                           | Description                                            |
-| :------------------------------- | :----------------------------------------------------- |
-| `--timeback-local`               | Enable local TimeBack mode (Docker)                    |
-| `--timeback-oneroster-url <url>` | OneRoster API URL                                      |
-| `--timeback-caliper-url <url>`   | Caliper API URL                                        |
-| `--timeback-course-id <id>`      | Course ID for enrollments                              |
-| `--timeback-student-id <id>`     | Student ID to link to demo user                        |
-| `--timeback-role <role>`         | User role (student, parent, teacher, administrator)    |
-| `--timeback-org-id <id>`         | Organization ID                                        |
-| `--timeback-org-name <name>`     | Organization display name                              |
-| `--timeback-org-type <type>`     | Organization type (school, district, department, etc.) |
+| Option                                  | Description                                                                       |
+| :-------------------------------------- | :-------------------------------------------------------------------------------- |
+| `--timeback-local`                      | Enable local TimeBack mode (Docker)                                               |
+| `--timeback-oneroster-url <url>`        | OneRoster API URL                                                                 |
+| `--timeback-caliper-url <url>`          | Caliper API URL                                                                   |
+| `--timeback-course-id <id>`             | Course ID for enrollments                                                         |
+| `--timeback-student-id <id>`            | Student ID to link to demo user                                                   |
+| `--timeback-role <role>`                | User role (student, parent, teacher, administrator)                               |
+| `--timeback-org-id <id>`                | Organization ID                                                                   |
+| `--timeback-org-name <name>`            | Organization display name                                                         |
+| `--timeback-org-type <type>`            | Organization type (school, district, department, etc.)                            |
+| `--timeback-excluded-courses <courses>` | Comma-separated courses to exclude from enrollment (e.g. `FastMath:3,FastMath:4`) |
 
 ### Environment Variables
 
@@ -262,15 +263,34 @@ The sandbox provides these TimeBack endpoints (matching production platform):
 **Runtime:**
 
 - `POST /api/timeback/end-activity` - Submit activity results
-
-**XP Queries:**
-
-- `GET /api/timeback/xp/today` - Get today's XP
-- `PUT /api/timeback/xp/today` - Update today's XP
-- `GET /api/timeback/xp/total` - Get total XP
-- `GET /api/timeback/xp/history` - Get XP history
-
-These use the same api-core handlers as the production platform, ensuring consistency.
+- `POST /api/timeback/heartbeat` - Record incremental activity heartbeat
+- `POST /api/timeback/advance-course` - Advance a student to the next-grade course
+- `POST /api/timeback/unenroll-course` - Unenroll a student from their active course
+- `POST /api/timeback/populate-student` - No-op in the sandbox (always returns `no_record`)
+
+**Assessments:**
+
+- `POST /api/timeback/assessments/prepare` - Prepare the next assessment attempt
+- `POST /api/timeback/assessments/start` - Start a new assessment attempt
+- `GET /api/timeback/assessments/latest` - Get the user's latest attempt
+- `GET /api/timeback/assessments/:attemptId` - Get a specific attempt
+- `POST /api/timeback/assessments/:attemptId/resume` - Resume an attempt
+- `POST /api/timeback/assessments/:attemptId/progress` - Record mastery progress
+- `POST /api/timeback/assessments/:attemptId/save` - Checkpoint an in-progress attempt
+- `POST /api/timeback/assessments/:attemptId/submit-item` - Score a single item
+- `POST /api/timeback/assessments/:attemptId/submit` - Submit an attempt
+- `POST /api/timeback/assessments/:attemptId/finalize` - Record XP and publish completion
+
+**Student Data:**
+
+- `GET /api/timeback/user` - Get the current user's TimeBack data
+- `GET /api/timeback/user/enrollments` - Get the current user's enrollments
+- `GET /api/timeback/user/:timebackId` - Get a student's TimeBack data
+- `GET /api/timeback/student-xp/:timebackId` - Get a student's XP
+- `GET /api/timeback/student-mastery/:timebackId` - Get a student's mastery
+- `GET /api/timeback/student-highest-grade-mastered/:timebackId` - Get a student's highest grade mastered
+
+These use the same api-core handlers as the production platform, ensuring consistency. The student data routes return mock data when TimeBack runs in mock mode.
 
 When properly configured, your game can call `client.timeback.endActivity()` during local development and see real events appear in your TimeBack dashboard.
 

package/dist/cli.js

@@ -1142,7 +1142,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.11.0",
+    version: "0.11.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -94381,6 +94381,12 @@ function resolvePrimaryAccountRole(roles2) {
   }
   return ACCOUNT_ROLE_PRECEDENCE.find((role) => roles2.some((entry) => entry.role === role)) ?? null;
 }
+function resolveEnrollableAccountRole(user) {
+  if (user.status === "tobedeleted" || String(user.enabledUser) === "false") {
+    return null;
+  }
+  return resolvePrimaryAccountRole(user.roles?.filter((entry) => entry.status !== "tobedeleted"));
+}
 var ACCOUNT_ROLE_PRECEDENCE;
 var init_timeback_admin_util = __esm(() => {
   init_errors2();
@@ -99997,13 +100003,8 @@ class TimebackAdminService {
       let allUsers = [];
       try {
         const page = await client2.api.oneroster.users.list({
-          where: {
-            OR: [
-              { givenName: { contains: trimmedQuery } },
-              { familyName: { contains: trimmedQuery } },
-              { email: { contains: trimmedQuery } }
-            ]
-          },
+          search: trimmedQuery,
+          where: { status: "active", enabledUser: "true" },
           limit: 25
         });
         allUsers = page.data;
@@ -100032,7 +100033,7 @@ class TimebackAdminService {
         pastEnrollmentsByStudent.set(studentId, list);
       }
       const students = allUsers.flatMap((entry) => {
-        const primaryRole = resolvePrimaryAccountRole(entry.roles);
+        const primaryRole = resolveEnrollableAccountRole(entry);
         if (!entry.sourcedId || !primaryRole) {
           return [];
         }
@@ -110366,12 +110367,13 @@ class LeaderboardService {
       eq(gameScores.gameId, gameId),
       eq(users.isAnonymous, isAnonymousUser)
     ];
-    const bestScoresSubquery = db2.select({
+    const bestScoresSubquery = db2.selectDistinctOn([gameScores.userId, gameScores.gameId], {
       userId: gameScores.userId,
       gameId: gameScores.gameId,
-      score: sql`MAX(${gameScores.score})`.as("max_score"),
-      achievedAt: sql`MAX(${gameScores.achievedAt})`.as("max_achieved_at")
-    }).from(gameScores).innerJoin(users, eq(gameScores.userId, users.id)).where(and(...conditions2)).groupBy(gameScores.userId, gameScores.gameId).as("best_scores");
+      score: gameScores.score,
+      achievedAt: gameScores.achievedAt,
+      metadata: gameScores.metadata
+    }).from(gameScores).innerJoin(users, eq(gameScores.userId, users.id)).where(and(...conditions2)).orderBy(gameScores.userId, gameScores.gameId, desc(gameScores.score), asc(gameScores.achievedAt)).as("best_scores");
     const scores = await db2.select({
       userId: users.id,
       username: users.username,
@@ -110379,11 +110381,11 @@ class LeaderboardService {
       userImage: users.image,
       score: bestScoresSubquery.score,
       achievedAt: bestScoresSubquery.achievedAt,
-      metadata: gameScores.metadata,
+      metadata: bestScoresSubquery.metadata,
       gameId: games.id,
       gameTitle: games.displayName,
       gameSlug: games.slug
-    }).from(bestScoresSubquery).innerJoin(users, eq(bestScoresSubquery.userId, users.id)).innerJoin(games, eq(bestScoresSubquery.gameId, games.id)).innerJoin(gameScores, and(eq(gameScores.userId, bestScoresSubquery.userId), eq(gameScores.gameId, bestScoresSubquery.gameId), eq(gameScores.score, bestScoresSubquery.score))).orderBy(desc(bestScoresSubquery.score)).limit(limit).offset(offset);
+    }).from(bestScoresSubquery).innerJoin(users, eq(bestScoresSubquery.userId, users.id)).innerJoin(games, eq(bestScoresSubquery.gameId, games.id)).orderBy(desc(bestScoresSubquery.score), asc(bestScoresSubquery.achievedAt), asc(bestScoresSubquery.userId)).limit(limit).offset(offset);
     setAttributes({
       "app.leaderboard.result_count": scores.length,
       "app.leaderboard.no_result": scores.length === 0
@@ -110623,7 +110625,7 @@ class UserService {
       "app.user.timeback_enriched": false
     });
     const localDay = await this.resolveLocalDay(userData, observedTimeZone);
-    const timeback2 = userData.timebackId ? await this.fetchTimebackData(userData.timebackId, gameId) : undefined;
+    const timeback2 = userData.timebackId ? await this.fetchTimebackProfile(userData.timebackId) : undefined;
     setAttribute("app.user.timeback_enriched", Boolean(timeback2));
     if (gameId) {
       return {
@@ -110728,18 +110730,10 @@ class UserService {
       observedAt: null
     };
   }
-  async fetchTimebackData(timebackId, gameId) {
-    const [{ role, organizations: allOrganizations }, allEnrollments] = await Promise.all([
-      withSpan("timeback.fetch_profile", () => this.fetchStudentProfile(timebackId)),
-      withSpan("timeback.fetch_enrollments", () => this.fetchEnrollments(timebackId))
-    ]);
-    const enrollments = gameId ? filterEnrollmentsByGame(allEnrollments, gameId) : allEnrollments;
-    const organizations = gameId ? this.filterOrganizationsByEnrollments(allOrganizations, enrollments) : allOrganizations;
-    setAttributes({
-      "app.timeback.enrollment_count": enrollments.length,
-      "app.timeback.organization_count": organizations.length
-    });
-    return { id: timebackId, role, enrollments, organizations };
+  async fetchTimebackProfile(timebackId) {
+    const { role, organizations } = await withSpan("timeback.fetch_profile", () => this.fetchStudentProfile(timebackId));
+    setAttribute("app.timeback.organization_count", organizations.length);
+    return { id: timebackId, role, organizations };
   }
   async fetchStudentProfile(timebackId) {
     if (!this.deps.timeback) {
@@ -110778,46 +110772,14 @@ class UserService {
       return { role: "student", organizations: [] };
     }
   }
-  async fetchEnrollments(timebackId) {
-    if (!this.deps.timeback) {
-      setAttribute("app.timeback.client", "unavailable");
-      return [];
-    }
-    try {
-      const enrollments = await this.deps.timeback.roster.getEnrollments(timebackId);
-      const courseIds = enrollments.map((e) => e.courseId).filter((id) => Boolean(id));
-      if (courseIds.length === 0) {
-        return [];
-      }
-      const integrations = await this.deps.db.query.gameTimebackIntegrations.findMany({
-        where: and(inArray(gameTimebackIntegrations.courseId, courseIds), isActiveGameTimebackIntegrationStatus())
-      });
-      return mapEnrollmentsToUserEnrollments(enrollments, integrations);
-    } catch (error88) {
-      addEvent("timeback.enrollment_fetch_failed", {
-        "exception.type": errorType(error88),
-        "app.error.message": errorMessage(error88)
-      });
-      return [];
-    }
-  }
-  filterOrganizationsByEnrollments(organizations, enrollments) {
-    const enrollmentOrgIds = new Set(enrollments.map((e) => e.orgId).filter(Boolean));
-    if (enrollmentOrgIds.size === 0) {
-      return [];
-    }
-    return organizations.filter((o) => enrollmentOrgIds.has(o.id));
-  }
 }
 var LEARNING_TIME_ZONE_REFRESH_INTERVAL_MS;
 var init_user_service = __esm(() => {
   init_drizzle_orm();
   init_src();
-  init_helpers_index();
   init_tables_index();
   init_spans();
   init_errors2();
-  init_timeback_util();
   LEARNING_TIME_ZONE_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
 });
 
@@ -169346,8 +169308,12 @@ async function buildLocalDayContext(db2, user, observedTimeZone) {
     observedAt: null
   };
 }
+function getMockTimebackProfile(timebackId) {
+  const { role, organizations } = getMockStudentProfile();
+  return { id: timebackId, role, organizations };
+}
 async function buildMockUserResponse(db2, user, gameId, observedTimeZone) {
-  const timeback3 = user.timebackId ? await getMockTimebackData(db2, user.timebackId, gameId) : undefined;
+  const timeback3 = user.timebackId ? getMockTimebackProfile(user.timebackId) : undefined;
   const localDay = await buildLocalDayContext(db2, user, observedTimeZone);
   if (gameId) {
     return {

package/dist/mocks/timeback.d.ts

@@ -32,7 +32,7 @@ export declare function getMockTimebackData(db: DatabaseInstance, timebackId: st
 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.
+ * Build a complete user response with mock timeback identity.
  * Used to bypass api-core when in mock mode (avoids real API calls).
  */
 export declare function buildMockUserResponse(db: DatabaseInstance, user: User, gameId?: string, observedTimeZone?: string | null): Promise<AuthenticatedUser | GameUser>;

package/dist/server.js

@@ -1141,7 +1141,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@playcademy/sandbox",
-    version: "0.11.0",
+    version: "0.11.1-beta.2",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -94380,6 +94380,12 @@ function resolvePrimaryAccountRole(roles2) {
   }
   return ACCOUNT_ROLE_PRECEDENCE.find((role) => roles2.some((entry) => entry.role === role)) ?? null;
 }
+function resolveEnrollableAccountRole(user) {
+  if (user.status === "tobedeleted" || String(user.enabledUser) === "false") {
+    return null;
+  }
+  return resolvePrimaryAccountRole(user.roles?.filter((entry) => entry.status !== "tobedeleted"));
+}
 var ACCOUNT_ROLE_PRECEDENCE;
 var init_timeback_admin_util = __esm(() => {
   init_errors2();
@@ -99996,13 +100002,8 @@ class TimebackAdminService {
       let allUsers = [];
       try {
         const page = await client2.api.oneroster.users.list({
-          where: {
-            OR: [
-              { givenName: { contains: trimmedQuery } },
-              { familyName: { contains: trimmedQuery } },
-              { email: { contains: trimmedQuery } }
-            ]
-          },
+          search: trimmedQuery,
+          where: { status: "active", enabledUser: "true" },
           limit: 25
         });
         allUsers = page.data;
@@ -100031,7 +100032,7 @@ class TimebackAdminService {
         pastEnrollmentsByStudent.set(studentId, list);
       }
       const students = allUsers.flatMap((entry) => {
-        const primaryRole = resolvePrimaryAccountRole(entry.roles);
+        const primaryRole = resolveEnrollableAccountRole(entry);
         if (!entry.sourcedId || !primaryRole) {
           return [];
         }
@@ -110365,12 +110366,13 @@ class LeaderboardService {
       eq(gameScores.gameId, gameId),
       eq(users.isAnonymous, isAnonymousUser)
     ];
-    const bestScoresSubquery = db2.select({
+    const bestScoresSubquery = db2.selectDistinctOn([gameScores.userId, gameScores.gameId], {
       userId: gameScores.userId,
       gameId: gameScores.gameId,
-      score: sql`MAX(${gameScores.score})`.as("max_score"),
-      achievedAt: sql`MAX(${gameScores.achievedAt})`.as("max_achieved_at")
-    }).from(gameScores).innerJoin(users, eq(gameScores.userId, users.id)).where(and(...conditions2)).groupBy(gameScores.userId, gameScores.gameId).as("best_scores");
+      score: gameScores.score,
+      achievedAt: gameScores.achievedAt,
+      metadata: gameScores.metadata
+    }).from(gameScores).innerJoin(users, eq(gameScores.userId, users.id)).where(and(...conditions2)).orderBy(gameScores.userId, gameScores.gameId, desc(gameScores.score), asc(gameScores.achievedAt)).as("best_scores");
     const scores = await db2.select({
       userId: users.id,
       username: users.username,
@@ -110378,11 +110380,11 @@ class LeaderboardService {
       userImage: users.image,
       score: bestScoresSubquery.score,
       achievedAt: bestScoresSubquery.achievedAt,
-      metadata: gameScores.metadata,
+      metadata: bestScoresSubquery.metadata,
       gameId: games.id,
       gameTitle: games.displayName,
       gameSlug: games.slug
-    }).from(bestScoresSubquery).innerJoin(users, eq(bestScoresSubquery.userId, users.id)).innerJoin(games, eq(bestScoresSubquery.gameId, games.id)).innerJoin(gameScores, and(eq(gameScores.userId, bestScoresSubquery.userId), eq(gameScores.gameId, bestScoresSubquery.gameId), eq(gameScores.score, bestScoresSubquery.score))).orderBy(desc(bestScoresSubquery.score)).limit(limit).offset(offset);
+    }).from(bestScoresSubquery).innerJoin(users, eq(bestScoresSubquery.userId, users.id)).innerJoin(games, eq(bestScoresSubquery.gameId, games.id)).orderBy(desc(bestScoresSubquery.score), asc(bestScoresSubquery.achievedAt), asc(bestScoresSubquery.userId)).limit(limit).offset(offset);
     setAttributes({
       "app.leaderboard.result_count": scores.length,
       "app.leaderboard.no_result": scores.length === 0
@@ -110622,7 +110624,7 @@ class UserService {
       "app.user.timeback_enriched": false
     });
     const localDay = await this.resolveLocalDay(userData, observedTimeZone);
-    const timeback2 = userData.timebackId ? await this.fetchTimebackData(userData.timebackId, gameId) : undefined;
+    const timeback2 = userData.timebackId ? await this.fetchTimebackProfile(userData.timebackId) : undefined;
     setAttribute("app.user.timeback_enriched", Boolean(timeback2));
     if (gameId) {
       return {
@@ -110727,18 +110729,10 @@ class UserService {
       observedAt: null
     };
   }
-  async fetchTimebackData(timebackId, gameId) {
-    const [{ role, organizations: allOrganizations }, allEnrollments] = await Promise.all([
-      withSpan("timeback.fetch_profile", () => this.fetchStudentProfile(timebackId)),
-      withSpan("timeback.fetch_enrollments", () => this.fetchEnrollments(timebackId))
-    ]);
-    const enrollments = gameId ? filterEnrollmentsByGame(allEnrollments, gameId) : allEnrollments;
-    const organizations = gameId ? this.filterOrganizationsByEnrollments(allOrganizations, enrollments) : allOrganizations;
-    setAttributes({
-      "app.timeback.enrollment_count": enrollments.length,
-      "app.timeback.organization_count": organizations.length
-    });
-    return { id: timebackId, role, enrollments, organizations };
+  async fetchTimebackProfile(timebackId) {
+    const { role, organizations } = await withSpan("timeback.fetch_profile", () => this.fetchStudentProfile(timebackId));
+    setAttribute("app.timeback.organization_count", organizations.length);
+    return { id: timebackId, role, organizations };
   }
   async fetchStudentProfile(timebackId) {
     if (!this.deps.timeback) {
@@ -110777,46 +110771,14 @@ class UserService {
       return { role: "student", organizations: [] };
     }
   }
-  async fetchEnrollments(timebackId) {
-    if (!this.deps.timeback) {
-      setAttribute("app.timeback.client", "unavailable");
-      return [];
-    }
-    try {
-      const enrollments = await this.deps.timeback.roster.getEnrollments(timebackId);
-      const courseIds = enrollments.map((e) => e.courseId).filter((id) => Boolean(id));
-      if (courseIds.length === 0) {
-        return [];
-      }
-      const integrations = await this.deps.db.query.gameTimebackIntegrations.findMany({
-        where: and(inArray(gameTimebackIntegrations.courseId, courseIds), isActiveGameTimebackIntegrationStatus())
-      });
-      return mapEnrollmentsToUserEnrollments(enrollments, integrations);
-    } catch (error88) {
-      addEvent("timeback.enrollment_fetch_failed", {
-        "exception.type": errorType(error88),
-        "app.error.message": errorMessage(error88)
-      });
-      return [];
-    }
-  }
-  filterOrganizationsByEnrollments(organizations, enrollments) {
-    const enrollmentOrgIds = new Set(enrollments.map((e) => e.orgId).filter(Boolean));
-    if (enrollmentOrgIds.size === 0) {
-      return [];
-    }
-    return organizations.filter((o) => enrollmentOrgIds.has(o.id));
-  }
 }
 var LEARNING_TIME_ZONE_REFRESH_INTERVAL_MS;
 var init_user_service = __esm(() => {
   init_drizzle_orm();
   init_src();
-  init_helpers_index();
   init_tables_index();
   init_spans();
   init_errors2();
-  init_timeback_util();
   LEARNING_TIME_ZONE_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
 });
 
@@ -169345,8 +169307,12 @@ async function buildLocalDayContext(db2, user, observedTimeZone) {
     observedAt: null
   };
 }
+function getMockTimebackProfile(timebackId) {
+  const { role, organizations } = getMockStudentProfile();
+  return { id: timebackId, role, organizations };
+}
 async function buildMockUserResponse(db2, user, gameId, observedTimeZone) {
-  const timeback3 = user.timebackId ? await getMockTimebackData(db2, user.timebackId, gameId) : undefined;
+  const timeback3 = user.timebackId ? getMockTimebackProfile(user.timebackId) : undefined;
   const localDay = await buildLocalDayContext(db2, user, observedTimeZone);
   if (gameId) {
     return {

package/package.json

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