@playcademy/sdk 0.2.10 → 0.2.12

package/dist/internal.js

@@ -1185,7 +1185,7 @@ var ACHIEVEMENT_DEFINITIONS = [
   }
 ];
 // ../constants/src/typescript.ts
-var TSC_PACKAGE = "@typescript/native-preview";
+var TSC_PACKAGE = "typescript";
 var USE_NATIVE_TSC = TSC_PACKAGE.includes("native-preview");
 // ../constants/src/overworld.ts
 var ITEM_SLUGS = {
@@ -1212,7 +1212,8 @@ var BADGES = {
 };
 // ../constants/src/timeback.ts
 var TIMEBACK_ROUTES = {
-  END_ACTIVITY: "/integrations/timeback/end-activity"
+  END_ACTIVITY: "/integrations/timeback/end-activity",
+  GET_XP: "/integrations/timeback/xp"
 };
 // src/core/cache/singleton-cache.ts
 function createSingletonCache() {
@@ -1390,6 +1391,26 @@ function createTTLCache(options) {
   return { get, clear, size, prune, getKeys, has };
 }
 
+// src/core/guards.ts
+var VALID_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var VALID_SUBJECTS = [
+  "Reading",
+  "Language",
+  "Vocabulary",
+  "Social Studies",
+  "Writing",
+  "Science",
+  "FastMath",
+  "Math",
+  "None"
+];
+function isValidGrade(value) {
+  return typeof value === "number" && Number.isInteger(value) && VALID_GRADES.includes(value);
+}
+function isValidSubject(value) {
+  return typeof value === "string" && VALID_SUBJECTS.includes(value);
+}
+
 // src/namespaces/game/timeback.ts
 function createTimebackNamespace(client) {
   let currentActivity = null;
@@ -1397,6 +1418,10 @@ function createTimebackNamespace(client) {
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.user"
   });
+  const xpCache = createTTLCache({
+    ttl: 5000,
+    keyPrefix: "game.timeback.xp"
+  });
   const getTimeback = () => client["initPayload"]?.timeback;
   return {
     get user() {
@@ -1427,6 +1452,49 @@ function createTimebackNamespace(client) {
               organizations: response.organizations
             };
           }, options);
+        },
+        xp: {
+          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(", ")}`);
+            }
+            const validIncludeOptions = ["perCourse", "today"];
+            if (options?.include?.length) {
+              for (const opt of options.include) {
+                if (!validIncludeOptions.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${validIncludeOptions.join(", ")}`);
+                }
+              }
+            }
+            const cacheKey = [
+              options?.grade ?? "",
+              options?.subject ?? "",
+              options?.include?.sort().join(",") ?? ""
+            ].join(":");
+            return xpCache.get(cacheKey, async () => {
+              const params = new URLSearchParams;
+              if (hasGrade) {
+                params.set("grade", String(options.grade));
+              }
+              if (hasSubject) {
+                params.set("subject", options.subject);
+              }
+              if (options?.include?.length) {
+                params.set("include", options.include.join(","));
+              }
+              const queryString = params.toString();
+              const endpoint = `${TIMEBACK_ROUTES.GET_XP}${queryString ? `?${queryString}` : ""}`;
+              return client["requestGameBackend"](endpoint, "GET");
+            }, { force: options?.force });
+          }
         }
       };
     },
@@ -1769,9 +1837,9 @@ function createDevNamespace(client) {
         }
         throw new Error("No deployment actions specified (need metadata, file, or backend)");
       },
-      seed: async (slug, code, environment) => {
+      seed: async (slug, code, environment, secrets) => {
         return client["request"](`/games/${slug}/seed`, "POST", {
-          body: { code, environment }
+          body: { code, environment, secrets }
         });
       },
       upsert: async (slug, metadata) => client["request"](`/games/${slug}`, "PUT", { body: metadata }),

package/dist/server.d.ts

@@ -295,6 +295,27 @@ interface EndActivityResponse {
     scoreStatus?: string;
     inProgress?: string;
 }
+/**
+ * XP data for a single course.
+ */
+interface StudentCourseXp {
+    grade: number;
+    subject: string;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from student XP query.
+ */
+interface StudentXpResponse {
+    /** Total XP across all queried courses */
+    totalXp: number;
+    /** Today's XP (if requested) */
+    todayXp?: number;
+    /** Per-course XP breakdown (if requested) */
+    courses?: StudentCourseXp[];
+}
 
 /**
  * @fileoverview Server SDK Type Definitions
@@ -588,6 +609,13 @@ declare class PlaycademyClient {
      * ```
      */
     static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+    /**
+     * Fetch gameId from API using the API token.
+     *
+     * @private
+     * @throws {Error} Always throws - gameId fetching not yet implemented
+     * @todo Implement API endpoint to fetch gameId from API token
+     */
     private fetchGameId;
     /**
      * Makes an authenticated HTTP request to the API.
@@ -617,6 +645,11 @@ declare class PlaycademyClient {
     /** TimeBack integration methods (endActivity) */
     timeback: {
         endActivity: (studentId: string, payload: EndActivityPayload) => Promise<EndActivityResponse>;
+        getStudentXp: (studentId: string, options?: {
+            grade?: number;
+            subject?: string;
+            include?: ("perCourse" | "today")[];
+        }) => Promise<StudentXpResponse>;
     };
 }
 

package/dist/server.js

@@ -1,4 +1,4 @@
-// src/server/guards.ts
+// src/core/guards.ts
 var VALID_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
 var VALID_SUBJECTS = [
   "Reading",
@@ -17,7 +17,6 @@ function isValidGrade(value) {
 function isValidSubject(value) {
   return typeof value === "string" && VALID_SUBJECTS.includes(value);
 }
-
 // src/server/namespaces/timeback.ts
 function createTimebackNamespace(client) {
   function enrichActivityData(data) {
@@ -44,6 +43,33 @@ function createTimebackNamespace(client) {
         xpEarned: payload.xpEarned,
         masteredUnits: payload.masteredUnits
       });
+    },
+    getStudentXp: 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-xp/${studentId}?${queryString}`;
+      return client["request"](endpoint, "GET");
     }
   };
 }

package/dist/types.d.ts

@@ -800,7 +800,7 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "user";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "admin" | "developer" | "player";
+            data: "admin" | "player" | "developer";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -817,7 +817,7 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "user";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "approved" | "none" | "pending";
+            data: "none" | "pending" | "approved";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1006,7 +1006,7 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "games";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "external" | "hosted";
+            data: "hosted" | "external";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1057,7 +1057,7 @@ declare const games: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "games";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "godot" | "unity" | "web";
+            data: "web" | "godot" | "unity";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1333,7 +1333,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "production" | "staging";
+            data: "staging" | "production";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1350,7 +1350,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "active" | "blocked" | "deleted" | "pending" | "pending_deletion" | "pending_deployment" | "pending_validation";
+            data: "pending" | "active" | "pending_validation" | "pending_deployment" | "pending_deletion" | "blocked" | "deleted";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1367,7 +1367,7 @@ declare const gameCustomHostnames: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "game_custom_hostnames";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "active" | "deleted" | "initializing" | "pending_deployment" | "pending_issuance" | "pending_validation";
+            data: "active" | "pending_validation" | "pending_deployment" | "deleted" | "initializing" | "pending_issuance";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -1529,7 +1529,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "items";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+            data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -2220,7 +2220,7 @@ declare const mapElements: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "map_elements";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "door_in" | "door_out" | "game_entry" | "game_registry" | "info" | "npc_interaction" | "quest_trigger" | "teleport";
+            data: "info" | "game_entry" | "game_registry" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -2773,7 +2773,7 @@ declare const characterComponents: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "character_components";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "accessory" | "body" | "eyes" | "hairstyle" | "outfit";
+            data: "accessory" | "body" | "outfit" | "hairstyle" | "eyes";
             driverParam: string;
             notNull: true;
             hasDefault: false;
@@ -3299,7 +3299,7 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "notifications";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "high" | "low" | "normal" | "urgent";
+            data: "low" | "normal" | "high" | "urgent";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -3316,7 +3316,7 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "notifications";
             dataType: "string";
             columnType: "PgEnumColumn";
-            data: "clicked" | "delivered" | "dismissed" | "expired" | "pending" | "seen";
+            data: "pending" | "delivered" | "seen" | "clicked" | "dismissed" | "expired";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -3477,33 +3477,33 @@ declare const UpsertGameMetadataSchema: z.ZodEffects<z.ZodObject<{
     gameType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["hosted", "external"]>>>;
     externalUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
     metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
+    displayName: string;
+    gameType: "hosted" | "external";
+    platform: "web" | "godot" | "unity";
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }, {
     displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+    platform: "web" | "godot" | "unity";
     metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
+    gameType?: "hosted" | "external" | undefined;
     externalUrl?: string | undefined;
-}>, {
-    displayName: string;
     mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+}>, {
     metadata: Record<string, unknown>;
-    gameType: "external" | "hosted";
+    displayName: string;
+    gameType: "hosted" | "external";
+    platform: "web" | "godot" | "unity";
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }, {
     displayName: string;
-    mapElementId?: string | null | undefined;
-    platform: "godot" | "unity" | "web";
+    platform: "web" | "godot" | "unity";
     metadata?: Record<string, unknown> | undefined;
-    gameType?: "external" | "hosted" | undefined;
+    gameType?: "hosted" | "external" | undefined;
     externalUrl?: string | undefined;
+    mapElementId?: string | null | undefined;
 }>;
 
 declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
@@ -3597,7 +3597,7 @@ declare const InsertItemSchema: drizzle_zod.BuildSchema<"insert", {
         tableName: "items";
         dataType: "string";
         columnType: "PgEnumColumn";
-        data: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade";
+        data: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
         driverParam: string;
         notNull: true;
         hasDefault: true;
@@ -3692,24 +3692,24 @@ declare const UpdateItemSchema: z.ZodObject<Omit<{
     imageUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     createdAt: z.ZodOptional<z.ZodDate>;
-}, "createdAt" | "id">, "strip", z.ZodTypeAny, {
+}, "id" | "createdAt">, "strip", z.ZodTypeAny, {
+    description?: string | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     slug?: string | undefined;
-    gameId?: string | null | undefined;
     displayName?: string | undefined;
-    description?: string | null | undefined;
-    type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
+    gameId?: string | null | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }, {
+    description?: string | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    type?: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other" | undefined;
     slug?: string | undefined;
-    gameId?: string | null | undefined;
     displayName?: string | undefined;
-    description?: string | null | undefined;
-    type?: "accessory" | "badge" | "collectible" | "consumable" | "currency" | "other" | "trophy" | "unlock" | "upgrade" | undefined;
+    gameId?: string | null | undefined;
     isPlaceable?: boolean | undefined;
     imageUrl?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
 }>;
 declare const InsertCurrencySchema: drizzle_zod.BuildSchema<"insert", {
     id: drizzle_orm_pg_core.PgColumn<{
@@ -3819,16 +3819,16 @@ declare const InsertCurrencySchema: drizzle_zod.BuildSchema<"insert", {
     isPrimary: z.ZodDefault<z.ZodBoolean>;
 }>;
 declare const UpdateCurrencySchema: z.ZodObject<{
-    itemId: z.ZodOptional<z.ZodString>;
     symbol: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    itemId: z.ZodOptional<z.ZodString>;
     isPrimary: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
-    itemId?: string | undefined;
     symbol?: string | null | undefined;
+    itemId?: string | undefined;
     isPrimary?: boolean | undefined;
 }, {
-    itemId?: string | undefined;
     symbol?: string | null | undefined;
+    itemId?: string | undefined;
     isPrimary?: boolean | undefined;
 }>;
 declare const InsertShopListingSchema: drizzle_zod.BuildSchema<"insert", {
@@ -4039,28 +4039,28 @@ declare const UpdateShopListingSchema: z.ZodObject<{
     updatedAt: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodDate>>>;
 }, "strip", z.ZodTypeAny, {
     id?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | null | undefined;
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
-    createdAt?: Date | undefined;
-    updatedAt?: Date | null | undefined;
 }, {
     id?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | null | undefined;
+    isActive?: boolean | undefined;
     itemId?: string | undefined;
     currencyId?: string | undefined;
     price?: number | undefined;
     sellBackPercentage?: number | null | undefined;
     stock?: number | null | undefined;
-    isActive?: boolean | undefined;
     availableFrom?: Date | null | undefined;
     availableUntil?: Date | null | undefined;
-    createdAt?: Date | undefined;
-    updatedAt?: Date | null | undefined;
 }>;
 
 type GameRow = typeof games.$inferSelect;
@@ -4873,6 +4873,9 @@ declare abstract class PlaycademyBaseClient {
      * Initializes connection monitoring if enabled.
      */
     private _initializeConnectionMonitor;
+    /**
+     * Initializes an internal game session for automatic session management.
+     */
     private _initializeInternalSession;
     /**
      * Current user data and inventory management.
@@ -4916,8 +4919,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     runtime: {
         getGameToken: (gameId: string, options?: {
-            apply?: boolean | undefined;
-        } | undefined) => Promise<GameTokenResponse>;
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
         exit: () => Promise<void>;
         onInit: (handler: (context: GameContextPayload) => void) => void;
         onTokenRefresh: (handler: (data: {
@@ -4941,7 +4944,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         getListenerCounts: () => Record<string, number>;
         assets: {
             url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
-            fetch: (path: string, options?: RequestInit | undefined) => Promise<Response>;
+            fetch: (path: string, options?: RequestInit) => Promise<Response>;
             json: <T = unknown>(path: string) => Promise<T>;
             blob: (path: string) => Promise<Blob>;
             text: (path: string) => Promise<string>;
@@ -4984,7 +4987,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `submit(gameId, score, metadata?)` - Record a game score
      */
     scores: {
-        submit: (gameId: string, score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
     /**
      * Realtime multiplayer authentication.
@@ -5001,13 +5004,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - Routes are relative to your game's deployment (e.g., '/hello' → your-game.playcademy.gg/api/hello)
      */
     backend: {
-        get<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        delete<T = unknown>(path: string, headers?: Record<string, string> | undefined): Promise<T>;
-        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<T>;
-        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string> | undefined): Promise<Response>;
+        get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        delete<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
+        request<T = unknown>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+        download(path: string, method?: Method, body?: unknown, headers?: Record<string, string>): Promise<Response>;
         url(pathOrStrings: string | TemplateStringsArray, ...values: unknown[]): string;
     };
     /** Auto-initializes a PlaycademyClient with context from the environment */
@@ -5065,6 +5068,45 @@ interface TimebackUserContext {
     /** User's organizations (schools/districts) */
     organizations: TimebackOrganization[];
 }
+/**
+ * XP data access for the current user.
+ * Results are cached for 5 seconds to avoid redundant network requests.
+ */
+interface TimebackUserXp {
+    /**
+     * Fetch XP data from the server.
+     * Returns XP 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', 'today'
+     * @param options.force - Bypass cache and fetch fresh data (default: false)
+     * @returns Promise resolving to XP data
+     *
+     * @example
+     * ```typescript
+     * // Get total XP for all game courses
+     * const xp = await client.timeback.user.xp.fetch()
+     *
+     * // Get XP for a specific grade/subject
+     * const xp = await client.timeback.user.xp.fetch({
+     *   grade: 3,
+     *   subject: 'Math'
+     * })
+     *
+     * // Get XP with per-course breakdown
+     * const xp = await client.timeback.user.xp.fetch({
+     *   include: ['perCourse', 'today']
+     * })
+     *
+     * // Force fresh data
+     * const xp = await client.timeback.user.xp.fetch({ force: true })
+     * ```
+     */
+    fetch(options?: GetXpOptions): Promise<XpResponse>;
+}
 /**
  * TimeBack user object with both cached getters and fetch method.
  */
@@ -5078,6 +5120,42 @@ interface TimebackUser extends TimebackUserContext {
     fetch(options?: {
         force?: boolean;
     }): Promise<TimebackUserContext>;
+    /**
+     * XP data for the current user.
+     * Call `xp.fetch()` to get XP from the server.
+     */
+    xp: TimebackUserXp;
+}
+/**
+ * Options for querying student XP.
+ */
+interface GetXpOptions {
+    /** 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', 'today' */
+    include?: ('perCourse' | 'today')[];
+    /** Bypass cache and fetch fresh data (default: false) */
+    force?: boolean;
+}
+/**
+ * XP data for a single course.
+ */
+interface CourseXp {
+    grade: TimebackGrade;
+    subject: TimebackSubject;
+    title: string;
+    totalXp: number;
+    todayXp?: number;
+}
+/**
+ * Response from XP query.
+ */
+interface XpResponse {
+    totalXp: number;
+    todayXp?: number;
+    courses?: CourseXp[];
 }
 
 /**
@@ -5716,4 +5794,4 @@ interface PlaycademyServerClientState {
 }
 
 export { AchievementCompletionType, NotificationStatus, NotificationType, PlaycademyClient };
-export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpSummaryResponse };
+export type { AchievementCurrent, AchievementHistoryEntry, AchievementProgressResponse, AchievementScopeType, AchievementWithStatus, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, AuthenticatedUser, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, CharacterComponentRow as CharacterComponent, CharacterComponentType, CharacterComponentWithSpriteUrl, CharacterComponentsOptions, ClientConfig, ClientEvents, ConnectionStatePayload, CourseXp, CreateCharacterData, CreateMapObjectData, CurrencyRow as Currency, DevUploadEvent, DevUploadHooks, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, DisconnectContext, DisconnectHandler, DisplayAlertPayload, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameLeaderboardEntry, MapRow as GameMap, GamePlatform, GameRow as GameRecord, GameSessionRow as GameSession, GameTimebackIntegration, GameTokenResponse, GameType, GameUser, GetXpOptions, HostedGame, InitPayload, InsertCurrencyInput, InsertItemInput, InsertShopListingInput, InteractionType, InventoryItemRow as InventoryItem, InventoryItemWithItem, InventoryMutationResponse, ItemRow as Item, ItemType, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LevelConfigRow as LevelConfig, LevelProgressResponse, LevelUpCheckResult, LoginResponse, ManifestV1, MapData, MapElementRow as MapElement, MapElementMetadata, MapElementWithGame, MapObjectRow as MapObject, MapObjectWithItem, NotificationRow as Notification, NotificationStats, PlaceableItemMetadata, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyServerClientConfig, PlaycademyServerClientState, PlayerCharacterRow as PlayerCharacter, PlayerCharacterAccessoryRow as PlayerCharacterAccessory, PlayerCurrency, PlayerInventoryItem, PlayerProfile, PlayerSessionPayload, PopulateStudentResponse, RealtimeTokenResponse, ScoreSubmission, ShopCurrency, ShopDisplayItem, ShopListingRow as ShopListing, ShopViewResponse, SpriteAnimationFrame, SpriteConfigWithDimensions, SpriteTemplateRow as SpriteTemplate, SpriteTemplateData, StartSessionResponse, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserXp, TodayXpResponse, TokenRefreshPayload, TokenType, TotalXpResponse, UpdateCharacterData, UpdateCurrencyInput, UpdateItemInput, UpdateShopListingInput, UpsertGameMetadataInput, UserRow as User, UserEnrollment, UserInfo, UserLevelRow as UserLevel, UserLevelWithConfig, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData, XPAddResult, XpHistoryResponse, XpResponse, XpSummaryResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.2.10",
+    "version": "0.2.12",
     "type": "module",
     "exports": {
         ".": {
@@ -44,12 +44,12 @@
         "@playcademy/data": "0.0.1",
         "@playcademy/logger": "0.0.1",
         "@playcademy/types": "0.0.1",
-        "@playcademy/sandbox": "0.3.11",
+        "@playcademy/sandbox": "0.3.13",
         "@playcademy/test": "0.0.1",
         "@playcademy/timeback": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
-        "playcademy": "0.16.3",
+        "playcademy": "0.16.5",
         "rollup": "^4.50.2",
         "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2"