@playcademy/sdk 0.6.1-beta.2 → 0.6.1-beta.4

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
@@ -1802,6 +1814,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+        advanceCourse: (options?: {
+            subject?: TimebackSubject | undefined;
+        } | undefined) => Promise<AdvanceCourseResponse>;
     };
     /**
      * Playcademy Credits (platform currency) management.

package/dist/index.js

@@ -1330,7 +1330,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 +1442,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 +1544,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 +2017,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 +2048,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 +2135,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);
     }
   };
 }

package/dist/internal.js

@@ -1330,7 +1330,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 +1442,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 +1544,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 +2017,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 +2048,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 +2135,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);
     }
   };
 }

package/dist/types.d.ts

@@ -332,6 +332,14 @@ interface GameTimebackIntegration {
     createdAt: Date;
     updatedAt: Date;
 }
+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;
@@ -341,6 +349,10 @@ interface EndActivityResponse {
     scoreStatus?: string;
     inProgress?: string;
 }
+interface AdvanceCourseResponse {
+    status: 'ok';
+    promotion: TimebackPromotionResult;
+}
 
 /**
  * Achievement Types
@@ -5295,6 +5307,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;
+        advanceCourse: (options?: {
+            subject?: TimebackSubject | undefined;
+        } | undefined) => Promise<AdvanceCourseResponse>;
     };
     /**
      * Playcademy Credits (platform currency) management.

package/package.json

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