@playcademy/sdk 0.10.0 → 0.10.1-beta.2

package/dist/index.d.ts

@@ -1145,9 +1145,7 @@ interface StartActivityResult {
 
 /**
  * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId. Active enrollment IDs
- * are available at `enrollment.enrollmentIds?.active` when supplied by the
- * platform.
+ * Alias for UserEnrollment without the optional gameId.
  */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
@@ -1253,6 +1251,50 @@ interface TimebackUser extends TimebackUserContext {
      * Call `xp.fetch()` to get XP from the server.
      */
     xp: TimebackUserXp;
+    /**
+     * Mastery data for the current user.
+     * Call `mastery.fetch()` to get mastery progress from the server.
+     */
+    mastery: TimebackUserMastery;
+}
+/**
+ * Mastery data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserMastery {
+    /**
+     * Fetch mastery data from the server.
+     * Returns mastery for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to mastery data
+     *
+     * @example
+     * ```typescript
+     * // Get total mastery for all game courses
+     * const mastery = await client.timeback.user.mastery.fetch()
+     *
+     * // Get mastery for a specific grade/subject
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get mastery with per-course breakdown
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   include: ['perCourse']
+     * })
+     *
+     * // Force fresh data
+     * const mastery = await client.timeback.user.mastery.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
 /**
  * Options for querying student XP.
@@ -1267,6 +1309,19 @@ interface GetXpOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying student mastery.
+ */
+interface GetMasteryOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse' */
+    include?: 'perCourse'[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1285,6 +1340,26 @@ interface XpResponse {
     todayXp?: number;
     courses?: CourseXp[];
 }
+/**
+ * Mastery data for a single course.
+ */
+interface CourseMastery {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    masteredUnits: number;
+    masterableUnits: number;
+    pctComplete: number;
+    isComplete: boolean;
+}
+/**
+ * Response from mastery query.
+ */
+interface MasteryResponse {
+    totalMasteredUnits: number;
+    totalMasterableUnits: number;
+    courses?: CourseMastery[];
+}
 
 /**
  * Core client configuration and lifecycle types

package/dist/index.js

@@ -1145,9 +1145,21 @@ function isValidSubject(value) {
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
   GET_XP: "/integrations/timeback/xp",
+  GET_MASTERY: "/integrations/timeback/mastery",
   HEARTBEAT: "/integrations/timeback/heartbeat",
   ADVANCE_COURSE: "/integrations/timeback/advance-course"
 };
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var 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
+};
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -1705,6 +1717,9 @@ function createTimebackActivityTracker(client) {
       const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
       const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
       const { correctQuestions, totalQuestions } = data;
+      if (data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined) {
+        throw new Error("Cannot provide both masteredUnits and masteredUnitsAbsolute — use one or the other");
+      }
       const request = {
         runId: activity.runId,
         resumeId: activity.resumeId,
@@ -1722,6 +1737,7 @@ function createTimebackActivityTracker(client) {
         },
         xpEarned: data.xpAwarded,
         masteredUnits: data.masteredUnits,
+        masteredUnitsAbsolute: data.masteredUnitsAbsolute,
         extensions: data.extensions
       };
       try {
@@ -1780,6 +1796,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.xp"
   });
+  const masteryCache = createTTLCache({
+    ttl: 5000,
+    keyPrefix: "game.timeback.mastery"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -1847,6 +1867,30 @@ function createTimebackEngine(client) {
             return client["requestGameBackend"](endpoint, "GET");
           }, { force: options.force });
         }
+      },
+      mastery: {
+        fetch: (options) => {
+          const cacheKey = [
+            options.grade ?? "",
+            options.subject ?? "",
+            options.include?.toSorted().join(",") ?? ""
+          ].join(":");
+          return masteryCache.get(cacheKey, async () => {
+            const params = new URLSearchParams;
+            if (options.grade !== undefined) {
+              params.set("grade", String(options.grade));
+            }
+            if (options.subject !== undefined) {
+              params.set("subject", options.subject);
+            }
+            if (options.include?.length) {
+              params.set("include", options.include.join(","));
+            }
+            const queryString = params.toString();
+            const endpoint = `${TIMEBACK_ROUTES.GET_MASTERY}${queryString ? `?${queryString}` : ""}`;
+            return client["requestGameBackend"](endpoint, "GET");
+          }, { force: options.force });
+        }
       }
     },
     activity: {
@@ -1865,7 +1909,8 @@ function createTimebackEngine(client) {
 }
 
 // src/namespaces/game/timeback.ts
-var VALID_INCLUDE_OPTIONS = ["perCourse", "today"];
+var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
+var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   return {
@@ -1901,13 +1946,36 @@ function createTimebackNamespace(client) {
             }
             if (options.include?.length) {
               for (const opt of options.include) {
-                if (!VALID_INCLUDE_OPTIONS.includes(opt)) {
-                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_INCLUDE_OPTIONS.join(", ")}`);
+                if (!VALID_XP_INCLUDE_OPTIONS.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_XP_INCLUDE_OPTIONS.join(", ")}`);
                 }
               }
             }
             return engine.user.xp.fetch(options);
           }
+        },
+        mastery: {
+          fetch: async (options = {}) => {
+            const hasGrade = options.grade !== undefined;
+            const hasSubject = options.subject !== undefined;
+            if (hasGrade !== hasSubject) {
+              throw new Error("Both grade and subject must be provided together");
+            }
+            if (hasGrade && !isValidGrade(options.grade)) {
+              throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+            }
+            if (hasSubject && !isValidSubject(options.subject)) {
+              throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+            }
+            if (options.include?.length) {
+              for (const opt of options.include) {
+                if (!VALID_MASTERY_INCLUDE_OPTIONS.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_MASTERY_INCLUDE_OPTIONS.join(", ")}`);
+                }
+              }
+            }
+            return engine.user.mastery.fetch(options);
+          }
         }
       };
     },

package/dist/internal.d.ts

@@ -3,7 +3,7 @@ import { TimebackGrade, TimebackSubject, TimebackCourseConfig, CourseConfig, Org
 export { QtiTestQuestionRef, QtiTestQuestionsResponse } from '@playcademy/types/timeback';
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest } from '@playcademy/types';
-export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameActivityMetrics, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
+export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { z } from 'zod';
 import { DomainValidationRecords } from '@playcademy/types/game';
@@ -999,9 +999,7 @@ interface StartActivityResult {
 
 /**
  * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId. Active enrollment IDs
- * are available at `enrollment.enrollmentIds?.active` when supplied by the
- * platform.
+ * Alias for UserEnrollment without the optional gameId.
  */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
@@ -1107,6 +1105,50 @@ interface TimebackUser extends TimebackUserContext {
      * Call `xp.fetch()` to get XP from the server.
      */
     xp: TimebackUserXp;
+    /**
+     * Mastery data for the current user.
+     * Call `mastery.fetch()` to get mastery progress from the server.
+     */
+    mastery: TimebackUserMastery;
+}
+/**
+ * Mastery data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserMastery {
+    /**
+     * Fetch mastery data from the server.
+     * Returns mastery for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to mastery data
+     *
+     * @example
+     * ```typescript
+     * // Get total mastery for all game courses
+     * const mastery = await client.timeback.user.mastery.fetch()
+     *
+     * // Get mastery for a specific grade/subject
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get mastery with per-course breakdown
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   include: ['perCourse']
+     * })
+     *
+     * // Force fresh data
+     * const mastery = await client.timeback.user.mastery.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
 /**
  * Options for querying student XP.
@@ -1121,6 +1163,19 @@ interface GetXpOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying student mastery.
+ */
+interface GetMasteryOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse' */
+    include?: 'perCourse'[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1139,6 +1194,26 @@ interface XpResponse {
     todayXp?: number;
     courses?: CourseXp[];
 }
+/**
+ * Mastery data for a single course.
+ */
+interface CourseMastery {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    masteredUnits: number;
+    masterableUnits: number;
+    pctComplete: number;
+    isComplete: boolean;
+}
+/**
+ * Response from mastery query.
+ */
+interface MasteryResponse {
+    totalMasteredUnits: number;
+    totalMasterableUnits: number;
+    courses?: CourseMastery[];
+}
 
 /**
  * Core client configuration and lifecycle types
@@ -2960,6 +3035,10 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 gameId: string;
                 courseId?: string;
             }) => Promise<_playcademy_types.TimebackStudentOverviewResponse>;
+            getGameMetrics: (timebackId: string, options: {
+                gameId: string;
+                runIds?: string[];
+            }) => Promise<_playcademy_types.GameMetricsProxyResponse>;
             getStudentActivity: (timebackId: string, courseId: string, options: {
                 gameId: string;
                 limit?: number;
@@ -3025,4 +3104,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, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MessageEventMap, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, 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, 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 };

package/dist/internal.js

@@ -1145,9 +1145,21 @@ function isValidSubject(value) {
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
   GET_XP: "/integrations/timeback/xp",
+  GET_MASTERY: "/integrations/timeback/mastery",
   HEARTBEAT: "/integrations/timeback/heartbeat",
   ADVANCE_COURSE: "/integrations/timeback/advance-course"
 };
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var 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
+};
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -1705,6 +1717,9 @@ function createTimebackActivityTracker(client) {
       const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
       const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
       const { correctQuestions, totalQuestions } = data;
+      if (data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined) {
+        throw new Error("Cannot provide both masteredUnits and masteredUnitsAbsolute — use one or the other");
+      }
       const request = {
         runId: activity.runId,
         resumeId: activity.resumeId,
@@ -1722,6 +1737,7 @@ function createTimebackActivityTracker(client) {
         },
         xpEarned: data.xpAwarded,
         masteredUnits: data.masteredUnits,
+        masteredUnitsAbsolute: data.masteredUnitsAbsolute,
         extensions: data.extensions
       };
       try {
@@ -1780,6 +1796,10 @@ function createTimebackEngine(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.xp"
   });
+  const masteryCache = createTTLCache({
+    ttl: 5000,
+    keyPrefix: "game.timeback.mastery"
+  });
   const enrollmentsCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.enrollments"
@@ -1847,6 +1867,30 @@ function createTimebackEngine(client) {
             return client["requestGameBackend"](endpoint, "GET");
           }, { force: options.force });
         }
+      },
+      mastery: {
+        fetch: (options) => {
+          const cacheKey = [
+            options.grade ?? "",
+            options.subject ?? "",
+            options.include?.toSorted().join(",") ?? ""
+          ].join(":");
+          return masteryCache.get(cacheKey, async () => {
+            const params = new URLSearchParams;
+            if (options.grade !== undefined) {
+              params.set("grade", String(options.grade));
+            }
+            if (options.subject !== undefined) {
+              params.set("subject", options.subject);
+            }
+            if (options.include?.length) {
+              params.set("include", options.include.join(","));
+            }
+            const queryString = params.toString();
+            const endpoint = `${TIMEBACK_ROUTES.GET_MASTERY}${queryString ? `?${queryString}` : ""}`;
+            return client["requestGameBackend"](endpoint, "GET");
+          }, { force: options.force });
+        }
       }
     },
     activity: {
@@ -1865,7 +1909,8 @@ function createTimebackEngine(client) {
 }
 
 // src/namespaces/game/timeback.ts
-var VALID_INCLUDE_OPTIONS = ["perCourse", "today"];
+var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
+var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   return {
@@ -1901,13 +1946,36 @@ function createTimebackNamespace(client) {
             }
             if (options.include?.length) {
               for (const opt of options.include) {
-                if (!VALID_INCLUDE_OPTIONS.includes(opt)) {
-                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_INCLUDE_OPTIONS.join(", ")}`);
+                if (!VALID_XP_INCLUDE_OPTIONS.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_XP_INCLUDE_OPTIONS.join(", ")}`);
                 }
               }
             }
             return engine.user.xp.fetch(options);
           }
+        },
+        mastery: {
+          fetch: async (options = {}) => {
+            const hasGrade = options.grade !== undefined;
+            const hasSubject = options.subject !== undefined;
+            if (hasGrade !== hasSubject) {
+              throw new Error("Both grade and subject must be provided together");
+            }
+            if (hasGrade && !isValidGrade(options.grade)) {
+              throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+            }
+            if (hasSubject && !isValidSubject(options.subject)) {
+              throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+            }
+            if (options.include?.length) {
+              for (const opt of options.include) {
+                if (!VALID_MASTERY_INCLUDE_OPTIONS.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_MASTERY_INCLUDE_OPTIONS.join(", ")}`);
+                }
+              }
+            }
+            return engine.user.mastery.fetch(options);
+          }
         }
       };
     },
@@ -2577,6 +2645,14 @@ function createTimebackNamespace2(client) {
         }
         return client["request"](`/timeback/student-overview/${timebackId}?${params}`, "GET");
       },
+      getGameMetrics: (timebackId, options) => {
+        const params = new URLSearchParams;
+        for (const runId of options.runIds ?? []) {
+          params.append("runId", runId);
+        }
+        const query = params.toString();
+        return client["request"](`/timeback/game-metrics/${options.gameId}/${timebackId}${query ? `?${query}` : ""}`, "GET");
+      },
       getStudentActivity: (timebackId, courseId, options) => {
         const params = new URLSearchParams({ gameId: options.gameId });
         if (options.limit !== undefined) {

package/dist/server/edge.d.ts

@@ -298,6 +298,11 @@ declare class PlaycademyClient {
             subject?: string;
             include?: ('perCourse' | 'today')[];
         }) => Promise<_playcademy_types.StudentXpResponse>;
+        getStudentMastery: (studentId: string, options?: {
+            grade?: number;
+            subject?: string;
+            include?: 'perCourse'[];
+        }) => Promise<_playcademy_types.StudentMasteryResponse>;
     };
 }
 

package/dist/server/edge.js

@@ -83,6 +83,33 @@ function createTimebackNamespace(client) {
       const queryString = params.toString();
       const endpoint = `/api/timeback/student-xp/${studentId}?${queryString}`;
       return client["request"](endpoint, "GET");
+    },
+    getStudentMastery: async (studentId, options) => {
+      const hasGrade = options?.grade !== undefined;
+      const hasSubject = options?.subject !== undefined;
+      if (hasGrade !== hasSubject) {
+        throw new Error("Both grade and subject must be provided together");
+      }
+      if (hasGrade && !isValidGrade(options.grade)) {
+        throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+      }
+      if (hasSubject && !isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      const params = new URLSearchParams;
+      params.set("gameId", client.gameId);
+      if (options?.grade !== undefined) {
+        params.set("grade", String(options.grade));
+      }
+      if (options?.subject) {
+        params.set("subject", options.subject);
+      }
+      if (options?.include?.length) {
+        params.set("include", options.include.join(","));
+      }
+      const queryString = params.toString();
+      const endpoint = `/api/timeback/student-mastery/${studentId}?${queryString}`;
+      return client["request"](endpoint, "GET");
     }
   };
 }

package/dist/server.d.ts

@@ -298,6 +298,11 @@ declare class PlaycademyClient$1 {
             subject?: string;
             include?: ('perCourse' | 'today')[];
         }) => Promise<_playcademy_types.StudentXpResponse>;
+        getStudentMastery: (studentId: string, options?: {
+            grade?: number;
+            subject?: string;
+            include?: 'perCourse'[];
+        }) => Promise<_playcademy_types.StudentMasteryResponse>;
     };
 }
 

package/dist/server.js

@@ -272,6 +272,33 @@ function createTimebackNamespace(client) {
       const queryString = params.toString();
       const endpoint = `/api/timeback/student-xp/${studentId}?${queryString}`;
       return client["request"](endpoint, "GET");
+    },
+    getStudentMastery: async (studentId, options) => {
+      const hasGrade = options?.grade !== undefined;
+      const hasSubject = options?.subject !== undefined;
+      if (hasGrade !== hasSubject) {
+        throw new Error("Both grade and subject must be provided together");
+      }
+      if (hasGrade && !isValidGrade(options.grade)) {
+        throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+      }
+      if (hasSubject && !isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      const params = new URLSearchParams;
+      params.set("gameId", client.gameId);
+      if (options?.grade !== undefined) {
+        params.set("grade", String(options.grade));
+      }
+      if (options?.subject) {
+        params.set("subject", options.subject);
+      }
+      if (options?.include?.length) {
+        params.set("include", options.include.join(","));
+      }
+      const queryString = params.toString();
+      const endpoint = `/api/timeback/student-mastery/${studentId}?${queryString}`;
+      return client["request"](endpoint, "GET");
     }
   };
 }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest } from '@playcademy/types';
-export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameActivityMetrics, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
+export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
 import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject } from '@playcademy/types/timeback';
 export { QtiTestQuestionRef, QtiTestQuestionsResponse } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
@@ -1502,9 +1502,7 @@ interface StartActivityResult {
 
 /**
  * A TimeBack enrollment for the current game session.
- * Alias for UserEnrollment without the optional gameId. Active enrollment IDs
- * are available at `enrollment.enrollmentIds?.active` when supplied by the
- * platform.
+ * Alias for UserEnrollment without the optional gameId.
  */
 type TimebackEnrollment = Omit<UserEnrollment, 'gameId'>;
 /**
@@ -1610,6 +1608,50 @@ interface TimebackUser extends TimebackUserContext {
      * Call `xp.fetch()` to get XP from the server.
      */
     xp: TimebackUserXp;
+    /**
+     * Mastery data for the current user.
+     * Call `mastery.fetch()` to get mastery progress from the server.
+     */
+    mastery: TimebackUserMastery;
+}
+/**
+ * Mastery data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserMastery {
+    /**
+     * Fetch mastery data from the server.
+     * Returns mastery for all courses in this game, or filter by grade/subject.
+     * Results are cached for 5 seconds (use `force: true` to bypass).
+     *
+     * @param options - Query options
+     * @param options.grade - Grade level to filter (must be used with subject)
+     * @param options.subject - Subject to filter (must be used with grade)
+     * @param options.include - Additional data to include: 'perCourse'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to mastery data
+     *
+     * @example
+     * ```typescript
+     * // Get total mastery for all game courses
+     * const mastery = await client.timeback.user.mastery.fetch()
+     *
+     * // Get mastery for a specific grade/subject
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get mastery with per-course breakdown
+     * const mastery = await client.timeback.user.mastery.fetch({
+     *   include: ['perCourse']
+     * })
+     *
+     * // Force fresh data
+     * const mastery = await client.timeback.user.mastery.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetMasteryOptions): Promise<MasteryResponse>;
 }
 /**
  * Options for querying student XP.
@@ -1624,6 +1666,19 @@ interface GetXpOptions {
     /** Bypass cache and fetch fresh data (default: false) */
     force?: boolean;
 }
+/**
+ * Options for querying student mastery.
+ */
+interface GetMasteryOptions {
+    /** Grade level to filter (must be used with subject) */
+    grade?: TimebackGrade;
+    /** Subject to filter (must be used with grade) */
+    subject?: TimebackSubject;
+    /** Additional data to include: 'perCourse' */
+    include?: 'perCourse'[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
 /**
  * XP data for a single course.
  */
@@ -1642,6 +1697,26 @@ interface XpResponse {
     todayXp?: number;
     courses?: CourseXp[];
 }
+/**
+ * Mastery data for a single course.
+ */
+interface CourseMastery {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    masteredUnits: number;
+    masterableUnits: number;
+    pctComplete: number;
+    isComplete: boolean;
+}
+/**
+ * Response from mastery query.
+ */
+interface MasteryResponse {
+    totalMasteredUnits: number;
+    totalMasterableUnits: number;
+    courses?: CourseMastery[];
+}
 
 /**
  * Core client configuration and lifecycle types
@@ -2067,4 +2142,4 @@ interface AssessmentBankStatus {
 }
 
 export { PlaycademyClient };
-export type { AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetXpOptions, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, 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, 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 };

package/package.json

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