@playcademy/sdk 0.6.1-beta.3 → 0.6.1-beta.5

package/dist/index.d.ts

@@ -476,6 +476,14 @@ interface EndActivityScoreData {
  * @module types/timeback/api
  */
 
+type TimebackPromotionStatus = 'promoted' | 'no-next-course' | 'already-promoted' | 'not-enrolled' | 'not-mastered';
+interface TimebackPromotionResult {
+    status: TimebackPromotionStatus;
+    currentCourseId: string;
+    nextCourseId?: string;
+    masteredUnits?: number;
+    masterableUnits?: number;
+}
 interface EndActivityResponse {
     status: 'ok';
     courseId: string;
@@ -485,6 +493,10 @@ interface EndActivityResponse {
     scoreStatus?: string;
     inProgress?: string;
 }
+interface AdvanceCourseResponse {
+    status: 'ok';
+    promotion: TimebackPromotionResult;
+}
 
 /**
  * User Types
@@ -775,7 +787,7 @@ declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "inventory_items";
@@ -867,7 +879,7 @@ declare const inventoryItems: drizzle_orm_pg_core.PgTableWithColumns<{
             generated: undefined;
         }, {}, {}>;
     };
-    dialect: "pg";
+    dialect: 'pg';
 }>;
 
 type ItemRow = typeof items.$inferSelect;
@@ -1748,8 +1760,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: {
@@ -1773,7 +1785,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>;
@@ -1798,10 +1810,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+        advanceCourse: (options?: {
+            subject?: TimebackSubject;
+        }) => Promise<AdvanceCourseResponse>;
     };
     /**
      * Playcademy Credits (platform currency) management.
@@ -1818,14 +1833,14 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `submit(score, metadata?)` - Record a game score
      */
     scores: {
-        submit: (score: number, metadata?: Record<string, unknown> | undefined) => Promise<ScoreSubmission>;
+        submit: (score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
     };
     /**
      * Read-only leaderboard access for the current game scope.
      * - `fetch(options?)` - Fetch leaderboard entries
      */
     leaderboard: {
-        fetch: (options?: LeaderboardOptions | undefined) => Promise<GameLeaderboardEntry[]>;
+        fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
     };
     /**
      * Demo-mode helpers. Methods throw when called outside `client.mode === 'demo'`,
@@ -1839,7 +1854,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             get: () => Promise<DemoProfile>;
             update: (updates: DemoProfileUpdate) => Promise<DemoProfile>;
         };
-        end: (score: number, options?: DemoEndOptions | undefined) => void;
+        end: (score: number, options?: DemoEndOptions) => void;
     };
     /**
      * Realtime multiplayer authentication.
@@ -1856,13 +1871,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 */

package/dist/index.js

@@ -321,7 +321,7 @@ function formatJSONSingleLine(level, message, context, scope) {
     ...context && Object.keys(context).length > 0 && { context }
   };
   const consoleMethod = getConsoleMethod(level);
-  consoleMethod(JSON.stringify(logEntry));
+  consoleMethod(safeJSONStringify(logEntry));
 }
 function formatJSONPretty(level, message, context, scope) {
   const timestamp = new Date().toISOString();
@@ -333,7 +333,30 @@ function formatJSONPretty(level, message, context, scope) {
     ...context && Object.keys(context).length > 0 && { context }
   };
   const consoleMethod = getConsoleMethod(level);
-  consoleMethod(JSON.stringify(logEntry, null, 2));
+  consoleMethod(safeJSONStringify(logEntry, 2));
+}
+function safeJSONStringify(value, space) {
+  const seen = new WeakSet;
+  try {
+    return JSON.stringify(value, (_key, currentValue) => {
+      if (typeof currentValue === "bigint") {
+        return currentValue.toString();
+      }
+      if (typeof currentValue === "object" && currentValue !== null) {
+        if (seen.has(currentValue)) {
+          return "[Circular]";
+        }
+        seen.add(currentValue);
+      }
+      return currentValue;
+    }, space);
+  } catch {
+    return JSON.stringify({
+      timestamp: new Date().toISOString(),
+      level: "ERROR",
+      message: "[Logger] Failed to serialize log entry"
+    });
+  }
 }
 function getConsoleMethod(level) {
   switch (level) {
@@ -1005,7 +1028,7 @@ function createAssetsNamespace(client) {
     fetch: fetchAsset,
     json: async (path) => {
       const response = await fetchAsset(path);
-      return response.json();
+      return await response.json();
     },
     blob: async (path) => {
       const response = await fetchAsset(path);
@@ -1297,10 +1320,10 @@ var ACHIEVEMENT_DEFINITIONS = [
 var TypeScriptPackages = {
   tsc: "tsc",
   nativePreview: "@typescript/native-preview",
-  nativePreviewPinned: "@typescript/native-preview@7.0.0-dev.20260221.1"
+  nativePreviewBeta: "@typescript/native-preview@beta"
 };
 var TYPESCRIPT_RUNNER = {
-  package: TypeScriptPackages.nativePreviewPinned,
+  package: TypeScriptPackages.nativePreviewBeta,
   bin: "tsgo"
 };
 // ../constants/src/overworld.ts
@@ -1330,7 +1353,8 @@ var BADGES = {
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
   GET_XP: "/integrations/timeback/xp",
-  HEARTBEAT: "/integrations/timeback/heartbeat"
+  HEARTBEAT: "/integrations/timeback/heartbeat",
+  ADVANCE_COURSE: "/integrations/timeback/advance-course"
 };
 // src/core/cache/singleton-cache.ts
 function createSingletonCache() {
@@ -1441,6 +1465,99 @@ function createRealtimeNamespace(client) {
     }
   };
 }
+// 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/core/cache/ttl-cache.ts
+function createTTLCache(options) {
+  const cache = new Map;
+  const { ttl: defaultTTL, keyPrefix = "", onClear } = options;
+  async function get(key, loader, config) {
+    const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
+    const now = Date.now();
+    const effectiveTTL = config?.ttl !== undefined ? config.ttl : defaultTTL;
+    const force = config?.force || false;
+    const skipCache = config?.skipCache || false;
+    if (effectiveTTL === 0 || skipCache) {
+      return loader();
+    }
+    if (!force) {
+      const cached = cache.get(fullKey);
+      if (cached && cached.expiresAt > now) {
+        return cached.value;
+      }
+    }
+    const promise = loader().catch((error) => {
+      cache.delete(fullKey);
+      throw error;
+    });
+    cache.set(fullKey, {
+      value: promise,
+      expiresAt: now + effectiveTTL
+    });
+    return promise;
+  }
+  function clear(key) {
+    if (key === undefined) {
+      cache.clear();
+      onClear?.();
+    } else {
+      const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
+      cache.delete(fullKey);
+    }
+  }
+  function size() {
+    return cache.size;
+  }
+  function prune() {
+    const now = Date.now();
+    for (const [key, entry] of cache.entries()) {
+      if (entry.expiresAt <= now) {
+        cache.delete(key);
+      }
+    }
+  }
+  function getKeys() {
+    const keys = [];
+    const prefixLen = keyPrefix ? keyPrefix.length + 1 : 0;
+    for (const fullKey of cache.keys()) {
+      keys.push(fullKey.substring(prefixLen));
+    }
+    return keys;
+  }
+  function has(key) {
+    const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
+    const cached = cache.get(fullKey);
+    if (!cached) {
+      return false;
+    }
+    const now = Date.now();
+    if (cached.expiresAt <= now) {
+      cache.delete(fullKey);
+      return false;
+    }
+    return true;
+  }
+  return { get, clear, size, prune, getKeys, has };
+}
+
 // ../utils/src/uuid.ts
 var UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 function isValidUUID(value) {
@@ -1450,7 +1567,7 @@ function isValidUUID(value) {
   return UUID_REGEX.test(value);
 }
 
-// src/core/activity-tracker.ts
+// src/core/timeback/activity-tracker.ts
 var DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
 var DEFAULT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
@@ -1923,102 +2040,29 @@ function createTimebackActivityTracker(client) {
   };
 }
 
-// src/core/cache/ttl-cache.ts
-function createTTLCache(options) {
-  const cache = new Map;
-  const { ttl: defaultTTL, keyPrefix = "", onClear } = options;
-  async function get(key, loader, config) {
-    const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
-    const now = Date.now();
-    const effectiveTTL = config?.ttl !== undefined ? config.ttl : defaultTTL;
-    const force = config?.force || false;
-    const skipCache = config?.skipCache || false;
-    if (effectiveTTL === 0 || skipCache) {
-      return loader();
-    }
-    if (!force) {
-      const cached = cache.get(fullKey);
-      if (cached && cached.expiresAt > now) {
-        return cached.value;
-      }
-    }
-    const promise = loader().catch((error) => {
-      cache.delete(fullKey);
-      throw error;
-    });
-    cache.set(fullKey, {
-      value: promise,
-      expiresAt: now + effectiveTTL
-    });
-    return promise;
-  }
-  function clear(key) {
-    if (key === undefined) {
-      cache.clear();
-      onClear?.();
-    } else {
-      const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
-      cache.delete(fullKey);
-    }
-  }
-  function size() {
-    return cache.size;
-  }
-  function prune() {
-    const now = Date.now();
-    for (const [key, entry] of cache.entries()) {
-      if (entry.expiresAt <= now) {
-        cache.delete(key);
-      }
-    }
-  }
-  function getKeys() {
-    const keys = [];
-    const prefixLen = keyPrefix ? keyPrefix.length + 1 : 0;
-    for (const fullKey of cache.keys()) {
-      keys.push(fullKey.substring(prefixLen));
-    }
-    return keys;
-  }
-  function has(key) {
-    const fullKey = keyPrefix ? `${keyPrefix}:${key}` : key;
-    const cached = cache.get(fullKey);
-    if (!cached) {
-      return false;
-    }
-    const now = Date.now();
-    if (cached.expiresAt <= now) {
-      cache.delete(fullKey);
-      return false;
+// src/core/timeback/user.ts
+function createTimebackUserStore(client) {
+  let override;
+  return {
+    snapshot() {
+      return override ?? client["initPayload"]?.timeback;
+    },
+    async refresh() {
+      const response = await client["request"]("/timeback/user", "GET");
+      override = response;
+      return {
+        id: response.id,
+        role: response.role,
+        enrollments: response.enrollments,
+        organizations: response.organizations
+      };
     }
-    return true;
-  }
-  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) {
-  const activityTracker = createTimebackActivityTracker(client);
+// src/core/timeback/engine.ts
+function createTimebackEngine(client) {
+  const userStore = createTimebackUserStore(client);
   const userCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.user"
@@ -2027,42 +2071,84 @@ function createTimebackNamespace(client) {
     ttl: 5000,
     keyPrefix: "game.timeback.xp"
   });
-  function getTimeback() {
-    return client["initPayload"]?.timeback;
+  async function applyPromotion(promotion) {
+    if (promotion.status !== "promoted" && promotion.status !== "already-promoted") {
+      return;
+    }
+    userCache.clear("current");
+    try {
+      await userStore.refresh();
+    } catch {}
   }
+  const activityTracker = createTimebackActivityTracker(client);
+  return {
+    user: {
+      snapshot: () => userStore.snapshot(),
+      fetch: (options) => userCache.get("current", () => userStore.refresh(), options),
+      xp: {
+        fetch: (options) => {
+          const cacheKey = [
+            options.grade ?? "",
+            options.subject ?? "",
+            options.include?.toSorted().join(",") ?? ""
+          ].join(":");
+          return xpCache.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_XP}${queryString ? `?${queryString}` : ""}`;
+            return client["requestGameBackend"](endpoint, "GET");
+          }, { force: options.force });
+        }
+      }
+    },
+    activity: {
+      start: activityTracker.startActivity,
+      pause: activityTracker.pauseActivity,
+      resume: activityTracker.resumeActivity,
+      end: activityTracker.endActivity
+    },
+    async advanceCourse(params) {
+      const response = await client["requestGameBackend"](TIMEBACK_ROUTES.ADVANCE_COURSE, "POST", params?.subject !== undefined ? { subject: params.subject } : {});
+      await applyPromotion(response.promotion);
+      return response;
+    }
+  };
+}
+
+// src/namespaces/game/timeback.ts
+var VALID_INCLUDE_OPTIONS = ["perCourse", "today"];
+function createTimebackNamespace(client) {
+  const engine = createTimebackEngine(client);
   return {
     get user() {
       assertPlatformMode(client, "timeback.user");
       return {
         get id() {
-          return getTimeback()?.id;
+          return engine.user.snapshot()?.id;
         },
         get role() {
-          return getTimeback()?.role;
+          return engine.user.snapshot()?.role;
         },
         get enrollments() {
-          return getTimeback()?.enrollments ?? [];
+          return engine.user.snapshot()?.enrollments ?? [];
         },
         get organizations() {
-          return getTimeback()?.organizations ?? [];
+          return engine.user.snapshot()?.organizations ?? [];
         },
-        fetch: async (options) => userCache.get("current", async () => {
-          const response = await client["request"]("/timeback/user", "GET");
-          const initPayload = client["initPayload"];
-          if (initPayload) {
-            initPayload.timeback = response;
-          }
-          return {
-            id: response.id,
-            role: response.role,
-            enrollments: response.enrollments,
-            organizations: response.organizations
-          };
-        }, options),
+        fetch: (options) => engine.user.fetch(options),
         xp: {
-          fetch: async (options) => {
-            const hasGrade = options?.grade !== undefined;
-            const hasSubject = options?.subject !== undefined;
+          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");
             }
@@ -2072,53 +2158,40 @@ function createTimebackNamespace(client) {
             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) {
+            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(", ")}`);
+                if (!VALID_INCLUDE_OPTIONS.includes(opt)) {
+                  throw new Error(`Invalid include option: ${opt}. Valid options: ${VALID_INCLUDE_OPTIONS.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 });
+            return engine.user.xp.fetch(options);
           }
         }
       };
     },
     startActivity: (metadata, options) => {
       assertPlatformMode(client, "timeback.startActivity()");
-      activityTracker.startActivity(metadata, options);
+      engine.activity.start(metadata, options);
     },
     pauseActivity: () => {
       assertPlatformMode(client, "timeback.pauseActivity()");
-      activityTracker.pauseActivity();
+      engine.activity.pause();
     },
     resumeActivity: () => {
       assertPlatformMode(client, "timeback.resumeActivity()");
-      activityTracker.resumeActivity();
+      engine.activity.resume();
     },
     endActivity: async (data) => {
       assertPlatformMode(client, "timeback.endActivity()");
-      return activityTracker.endActivity(data);
+      return engine.activity.end(data);
+    },
+    advanceCourse: async (options) => {
+      assertPlatformMode(client, "timeback.advanceCourse()");
+      if (options?.subject !== undefined && !isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      return engine.advanceCourse(options);
     }
   };
 }