@playcademy/sdk 0.2.11 → 0.2.13

package/dist/index.d.ts

@@ -450,6 +450,23 @@ interface AuthenticatedUser {
     timeback?: UserTimebackData;
 }
 
+/**
+ * TimeBack Enums & Literal Types
+ *
+ * Basic type definitions used throughout the TimeBack integration.
+ *
+ * @module types/timeback/types
+ */
+/**
+ * Valid TimeBack subject values for course configuration.
+ * These are the supported subject values for OneRoster courses.
+ */
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
 /**
  * Valid Caliper subject values.
  * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
@@ -618,7 +635,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;
@@ -800,71 +817,6 @@ type InventoryItemWithItem = InventoryItemRow & {
     item: ItemRow;
 };
 
-/**
- * Auto-initializes a PlaycademyClient with context from the environment.
- * Works in both iframe mode (production/development) and standalone mode (local dev).
- *
- * This is the recommended way to initialize the SDK as it automatically:
- * - Detects the runtime environment (iframe vs standalone)
- * - Configures the client with the appropriate context
- * - Sets up event listeners for token refresh
- * - Exposes the client for debugging in development mode
- *
- * @param options - Optional configuration overrides
- * @param options.baseUrl - Override the base URL for API requests
- * @returns Promise resolving to a fully initialized PlaycademyClient
- * @throws Error if not running in a browser context
- *
- * @example
- * ```typescript
- * // Default initialization
- * const client = await PlaycademyClient.init()
- *
- * // With custom base URL
- * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
- * ```
- */
-declare function init<T extends PlaycademyClient = PlaycademyClient>(this: new (...args: ConstructorParameters<typeof PlaycademyClient>) => T, options?: {
-    baseUrl?: string;
-    allowedParentOrigins?: string[];
-    onDisconnect?: DisconnectHandler;
-    enableConnectionMonitoring?: boolean;
-}): Promise<T>;
-
-/**
- * Authenticates a user with email and password.
- *
- * This is a standalone authentication method that doesn't require an initialized client.
- * Use this for login flows before creating a client instance.
- *
- * @deprecated Use client.auth.login() instead for better error handling and automatic token management
- *
- * @param baseUrl - The base URL of the Playcademy API
- * @param email - User's email address
- * @param password - User's password
- * @returns Promise resolving to authentication response with token
- * @throws PlaycademyError if authentication fails or network error occurs
- *
- * @example
- * ```typescript
- * // Preferred approach:
- * const client = new PlaycademyClient({ baseUrl: '/api' })
- * const result = await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password'
- * })
- *
- * // Legacy approach (still works):
- * try {
- *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
- *   const client = new PlaycademyClient({ token: response.token })
- * } catch (error) {
- *   console.error('Login failed:', error.message)
- * }
- * ```
- */
-declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
-
 /**
  * @fileoverview Authentication Strategy Pattern
  *
@@ -999,6 +951,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.
@@ -1018,6 +973,71 @@ declare abstract class PlaycademyBaseClient {
     };
 }
 
+/**
+ * Auto-initializes a PlaycademyClient with context from the environment.
+ * Works in both iframe mode (production/development) and standalone mode (local dev).
+ *
+ * This is the recommended way to initialize the SDK as it automatically:
+ * - Detects the runtime environment (iframe vs standalone)
+ * - Configures the client with the appropriate context
+ * - Sets up event listeners for token refresh
+ * - Exposes the client for debugging in development mode
+ *
+ * @param options - Optional configuration overrides
+ * @param options.baseUrl - Override the base URL for API requests
+ * @returns Promise resolving to a fully initialized PlaycademyClient
+ * @throws Error if not running in a browser context
+ *
+ * @example
+ * ```typescript
+ * // Default initialization
+ * const client = await PlaycademyClient.init()
+ *
+ * // With custom base URL
+ * const client = await PlaycademyClient.init({ baseUrl: 'https://custom.api.com' })
+ * ```
+ */
+declare function init<T extends PlaycademyBaseClient = PlaycademyBaseClient>(this: new (config?: Partial<ClientConfig>) => T, options?: {
+    baseUrl?: string;
+    allowedParentOrigins?: string[];
+    onDisconnect?: DisconnectHandler;
+    enableConnectionMonitoring?: boolean;
+}): Promise<T>;
+
+/**
+ * Authenticates a user with email and password.
+ *
+ * This is a standalone authentication method that doesn't require an initialized client.
+ * Use this for login flows before creating a client instance.
+ *
+ * @deprecated Use client.auth.login() instead for better error handling and automatic token management
+ *
+ * @param baseUrl - The base URL of the Playcademy API
+ * @param email - User's email address
+ * @param password - User's password
+ * @returns Promise resolving to authentication response with token
+ * @throws PlaycademyError if authentication fails or network error occurs
+ *
+ * @example
+ * ```typescript
+ * // Preferred approach:
+ * const client = new PlaycademyClient({ baseUrl: '/api' })
+ * const result = await client.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * })
+ *
+ * // Legacy approach (still works):
+ * try {
+ *   const response = await PlaycademyClient.login('/api', 'user@example.com', 'password')
+ *   const client = new PlaycademyClient({ token: response.token })
+ * } catch (error) {
+ *   console.error('Login failed:', error.message)
+ * }
+ * ```
+ */
+declare function login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+
 /**
  * Playcademy SDK client for game developers.
  * Provides namespaced access to platform features for games running inside Cademy.
@@ -1042,8 +1062,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: {
@@ -1067,7 +1087,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>;
@@ -1110,7 +1130,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.
@@ -1127,13 +1147,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 */
@@ -1191,6 +1211,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.
  */
@@ -1204,6 +1263,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[];
 }
 
 /**

package/dist/index.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 });
+          }
         }
       };
     },