@playcademy/sdk 0.2.11 → 0.2.13

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?.toSorted().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 });
+          }
         }
       };
     },

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
@@ -361,6 +382,9 @@ interface CustomRoutesIntegration {
 interface DatabaseIntegration {
     /** Database directory (defaults to 'db') */
     directory?: string;
+    /** Schema strategy: 'push' uses drizzle-kit push-style diffing, 'migrate' uses migration files.
+     *  When omitted, auto-detects based on presence of a migrations directory with _journal.json. */
+    strategy?: 'push' | 'migrate';
 }
 /**
  * Integrations configuration
@@ -588,6 +612,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 +648,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");
     }
   };
 }