@playcademy/sdk 0.11.1-beta.1 → 0.11.1-beta.2

package/dist/index.d.ts

@@ -1262,6 +1262,12 @@ interface TimebackUser extends TimebackUserContext {
      * Call `mastery.fetch()` to get mastery progress from the server.
      */
     mastery: TimebackUserMastery;
+    /**
+     * Highest-grade-mastered data for the current user.
+     * Call `highestGradeMastered.fetch({ subject })` to get the student's
+     * highest mastered grade for a subject.
+     */
+    highestGradeMastered: TimebackUserHighestGradeMastered;
 }
 /**
  * Mastery data access for the current user.
@@ -1302,6 +1308,17 @@ interface TimebackUserMastery {
      */
     fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
+/**
+ * Highest-grade-mastered data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserHighestGradeMastered {
+    /**
+     * Fetch the highest grade the current student has mastered for a subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     */
+    fetch(options: GetHighestGradeMasteredOptions): Promise<HighestGradeMasteredResponse>;
+}
 /**
  * Options for querying student XP.
  */
@@ -1328,6 +1345,15 @@ interface GetMasteryOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying highest grade mastered.
+ */
+interface GetHighestGradeMasteredOptions {
+    /** Subject to query */
+    subject: TimebackSubject;
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1366,6 +1392,13 @@ interface MasteryResponse {
     totalMasterableUnits: number;
     courses?: CourseMastery[];
 }
+/**
+ * Response from highest-grade-mastered query.
+ */
+interface HighestGradeMasteredResponse {
+    subject: TimebackSubject;
+    highestGradeMastered: TimebackGrade | null;
+}
 
 /**
  * Core client configuration and lifecycle types

package/dist/index.js

@@ -1146,6 +1146,7 @@ var TIMEBACK_ROUTES = {
   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",
   UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
@@ -1801,6 +1802,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.mastery"
   });
+  const highestGradeMasteredCache = createTTLCache({
+    ttl: 5000,
+    keyPrefix: "game.timeback.highestGradeMastered"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -1809,6 +1814,7 @@ function createTimebackEngine(client) {
     userCache.clear("current");
     enrollmentsCache.clear("current");
     xpCache.clear();
+    highestGradeMasteredCache.clear();
     try {
       await userStore.refresh();
     } catch {}
@@ -1896,6 +1902,14 @@ function createTimebackEngine(client) {
             return client["requestGameBackend"](endpoint, "GET");
           }, { force: options.force });
         }
+      },
+      highestGradeMastered: {
+        fetch: (options) => highestGradeMasteredCache.get(options.subject, async () => {
+          const params = new URLSearchParams;
+          params.set("subject", options.subject);
+          const endpoint = `${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}?${params.toString()}`;
+          return client["requestGameBackend"](endpoint, "GET");
+        }, { force: options.force })
       }
     },
     activity: {
@@ -1993,6 +2007,17 @@ function createTimebackNamespace(client) {
             }
             return engine.user.mastery.fetch(options);
           }
+        },
+        highestGradeMastered: {
+          fetch: async (options) => {
+            if (!options?.subject) {
+              throw new Error("subject is required");
+            }
+            if (!isValidSubject(options.subject)) {
+              throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+            }
+            return engine.user.highestGradeMastered.fetch(options);
+          }
         }
       };
     },

package/dist/internal.d.ts

@@ -1110,6 +1110,12 @@ interface TimebackUser extends TimebackUserContext {
      * Call `mastery.fetch()` to get mastery progress from the server.
      */
     mastery: TimebackUserMastery;
+    /**
+     * Highest-grade-mastered data for the current user.
+     * Call `highestGradeMastered.fetch({ subject })` to get the student's
+     * highest mastered grade for a subject.
+     */
+    highestGradeMastered: TimebackUserHighestGradeMastered;
 }
 /**
  * Mastery data access for the current user.
@@ -1150,6 +1156,17 @@ interface TimebackUserMastery {
      */
     fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
+/**
+ * Highest-grade-mastered data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserHighestGradeMastered {
+    /**
+     * Fetch the highest grade the current student has mastered for a subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     */
+    fetch(options: GetHighestGradeMasteredOptions): Promise<HighestGradeMasteredResponse>;
+}
 /**
  * Options for querying student XP.
  */
@@ -1176,6 +1193,15 @@ interface GetMasteryOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying highest grade mastered.
+ */
+interface GetHighestGradeMasteredOptions {
+    /** Subject to query */
+    subject: TimebackSubject;
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1214,6 +1240,13 @@ interface MasteryResponse {
     totalMasterableUnits: number;
     courses?: CourseMastery[];
 }
+/**
+ * Response from highest-grade-mastered query.
+ */
+interface HighestGradeMasteredResponse {
+    subject: TimebackSubject;
+    highestGradeMastered: TimebackGrade | null;
+}
 
 /**
  * Core client configuration and lifecycle types
@@ -3104,4 +3137,4 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
 }
 
 export { ApiError, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetMasteryOptions, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, MessageEventMap, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { ApiErrorCode, ApiErrorInfo, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, MessageEventMap, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

package/dist/internal.js

@@ -1146,6 +1146,7 @@ var TIMEBACK_ROUTES = {
   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",
   UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
@@ -1801,6 +1802,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.mastery"
   });
+  const highestGradeMasteredCache = createTTLCache({
+    ttl: 5000,
+    keyPrefix: "game.timeback.highestGradeMastered"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -1809,6 +1814,7 @@ function createTimebackEngine(client) {
     userCache.clear("current");
     enrollmentsCache.clear("current");
     xpCache.clear();
+    highestGradeMasteredCache.clear();
     try {
       await userStore.refresh();
     } catch {}
@@ -1896,6 +1902,14 @@ function createTimebackEngine(client) {
             return client["requestGameBackend"](endpoint, "GET");
           }, { force: options.force });
         }
+      },
+      highestGradeMastered: {
+        fetch: (options) => highestGradeMasteredCache.get(options.subject, async () => {
+          const params = new URLSearchParams;
+          params.set("subject", options.subject);
+          const endpoint = `${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}?${params.toString()}`;
+          return client["requestGameBackend"](endpoint, "GET");
+        }, { force: options.force })
       }
     },
     activity: {
@@ -1993,6 +2007,17 @@ function createTimebackNamespace(client) {
             }
             return engine.user.mastery.fetch(options);
           }
+        },
+        highestGradeMastered: {
+          fetch: async (options) => {
+            if (!options?.subject) {
+              throw new Error("subject is required");
+            }
+            if (!isValidSubject(options.subject)) {
+              throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+            }
+            return engine.user.highestGradeMastered.fetch(options);
+          }
         }
       };
     },

package/dist/server/edge.d.ts

@@ -303,6 +303,9 @@ declare class PlaycademyClient {
             subject?: string;
             include?: 'perCourse'[];
         }) => Promise<_playcademy_types.StudentMasteryResponse>;
+        getStudentHighestGradeMastered: (studentId: string, options: {
+            subject: string;
+        }) => Promise<_playcademy_types.StudentHighestGradeMasteredResponse>;
     };
 }
 

package/dist/server/edge.js

@@ -110,6 +110,16 @@ function createTimebackNamespace(client) {
       const queryString = params.toString();
       const endpoint = `/api/timeback/student-mastery/${studentId}?${queryString}`;
       return client["request"](endpoint, "GET");
+    },
+    getStudentHighestGradeMastered: async (studentId, options) => {
+      if (!isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      const params = new URLSearchParams;
+      params.set("gameId", client.gameId);
+      params.set("subject", options.subject);
+      const endpoint = `/api/timeback/student-highest-grade-mastered/${encodeURIComponent(studentId)}?${params.toString()}`;
+      return client["request"](endpoint, "GET");
     }
   };
 }

package/dist/server.d.ts

@@ -303,6 +303,9 @@ declare class PlaycademyClient$1 {
             subject?: string;
             include?: 'perCourse'[];
         }) => Promise<_playcademy_types.StudentMasteryResponse>;
+        getStudentHighestGradeMastered: (studentId: string, options: {
+            subject: string;
+        }) => Promise<_playcademy_types.StudentHighestGradeMasteredResponse>;
     };
 }
 

package/dist/server.js

@@ -299,6 +299,16 @@ function createTimebackNamespace(client) {
       const queryString = params.toString();
       const endpoint = `/api/timeback/student-mastery/${studentId}?${queryString}`;
       return client["request"](endpoint, "GET");
+    },
+    getStudentHighestGradeMastered: async (studentId, options) => {
+      if (!isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      const params = new URLSearchParams;
+      params.set("gameId", client.gameId);
+      params.set("subject", options.subject);
+      const endpoint = `/api/timeback/student-highest-grade-mastered/${encodeURIComponent(studentId)}?${params.toString()}`;
+      return client["request"](endpoint, "GET");
     }
   };
 }

package/dist/types.d.ts

@@ -1619,6 +1619,12 @@ interface TimebackUser extends TimebackUserContext {
      * Call `mastery.fetch()` to get mastery progress from the server.
      */
     mastery: TimebackUserMastery;
+    /**
+     * Highest-grade-mastered data for the current user.
+     * Call `highestGradeMastered.fetch({ subject })` to get the student's
+     * highest mastered grade for a subject.
+     */
+    highestGradeMastered: TimebackUserHighestGradeMastered;
 }
 /**
  * Mastery data access for the current user.
@@ -1659,6 +1665,17 @@ interface TimebackUserMastery {
      */
     fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
+/**
+ * Highest-grade-mastered data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserHighestGradeMastered {
+    /**
+     * Fetch the highest grade the current student has mastered for a subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     */
+    fetch(options: GetHighestGradeMasteredOptions): Promise<HighestGradeMasteredResponse>;
+}
 /**
  * Options for querying student XP.
  */
@@ -1685,6 +1702,15 @@ interface GetMasteryOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying highest grade mastered.
+ */
+interface GetHighestGradeMasteredOptions {
+    /** Subject to query */
+    subject: TimebackSubject;
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1723,6 +1749,13 @@ interface MasteryResponse {
     totalMasterableUnits: number;
     courses?: CourseMastery[];
 }
+/**
+ * Response from highest-grade-mastered query.
+ */
+interface HighestGradeMasteredResponse {
+    subject: TimebackSubject;
+    highestGradeMastered: TimebackGrade | null;
+}
 
 /**
  * Core client configuration and lifecycle types
@@ -2148,4 +2181,4 @@ interface AssessmentBankStatus {
 }
 
 export { PlaycademyClient };
-export type { AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetMasteryOptions, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.11.1-beta.1",
+    "version": "0.11.1-beta.2",
     "type": "module",
     "exports": {
         ".": {