@playcademy/sdk 0.16.0 → 0.16.1-beta.2

package/README.md

@@ -116,6 +116,44 @@ await client.timeback.startActivity(
 )
 ```
 
+Hosted assessments use the same methods locally and when deployed:
+
+```typescript
+const attempt = await client.timeback.assessments.start({
+    activityId: 'math-diagnostic',
+    purpose: 'diagnostic',
+    subject: 'Math',
+    grade: 5,
+})
+
+const saved = await client.timeback.assessments.save(attempt.attemptId, {
+    expectedResponseVersion: attempt.responseVersion,
+    responses: {
+        [attempt.assessment.items[0].identifier]: { RESPONSE: 'A' },
+    },
+})
+
+const completed = await client.timeback.assessments.submit(attempt.attemptId, {
+    expectedResponseVersion: saved.responseVersion,
+    submissionId: crypto.randomUUID(),
+})
+```
+
+`start()` resumes an unfinished attempt or selects the next live test. Save payloads are
+question deltas, but each included question replaces its complete response state; use `null` to
+clear an answer. Keep the returned `responseVersion` and send it with the next mutation.
+
+For local development, import the current ordered catalog before starting the dev host:
+
+```bash
+playcademy timeback assessments import
+playcademy dev
+```
+
+The host reads `.playcademy/timeback/assessment-fixtures.json` and keeps local attempts in memory.
+Restarting the dev host resets mutable attempt state. Deployed games use TimeBack automatically;
+game code never selects the provider or reads fixture content.
+
 ### `client.backend`
 
 HTTP client for game-specific backend functions deployed via `playcademy deploy`.

package/dist/index.d.ts

@@ -1037,6 +1037,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */
     timeback: {
+        assessments: {
+            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
+            get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
+        };
         readonly user: TimebackUser;
         readonly currentRunId: string | undefined;
         startActivity: (metadata: _playcademy_types.ActivityData, options?: StartActivityOptions) => StartActivityResult;

package/dist/index.js

@@ -1118,25 +1118,12 @@ function createScoresNamespace(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);
-}
+// ../constants/src/auth.ts
+var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
+  games: ["read", "write", "delete"],
+  users: ["read:self", "write:self"],
+  dev: ["read", "write"]
+};
 // ../constants/src/platform.ts
 var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
 // ../constants/src/timeback.ts
@@ -1147,8 +1134,22 @@ var TIMEBACK_ROUTES = {
   GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
   HEARTBEAT: "/integrations/timeback/heartbeat",
   ADVANCE_COURSE: "/integrations/timeback/advance-course",
-  UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
+  UNENROLL_COURSE: "/integrations/timeback/unenroll-course",
+  ASSESSMENTS: "/integrations/timeback/assessments"
 };
+var TIMEBACK_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var TIMEBACK_SUBJECTS = [
+  "Reading",
+  "Language",
+  "Vocabulary",
+  "Social Studies",
+  "Writing",
+  "Science",
+  "FastMath",
+  "Math",
+  "None"
+];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
   mastery: 0,
@@ -1160,6 +1161,19 @@ var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
   time: 60,
   score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
 };
+// src/core/guards.ts
+var VALID_GRADES = TIMEBACK_GRADES;
+var VALID_SUBJECTS = TIMEBACK_SUBJECTS;
+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);
+}
+function isAssessmentPurpose(value) {
+  return typeof value === "string" && ASSESSMENT_PURPOSES.includes(value);
+}
+
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -2003,9 +2017,73 @@ function createTimebackEngine(client) {
 // src/namespaces/game/timeback.ts
 var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
 var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
+var ASSESSMENTS_ROUTE = TIMEBACK_ROUTES.ASSESSMENTS;
+function validateAssessmentFilters(options) {
+  if (!isAssessmentPurpose(options?.purpose)) {
+    throw new Error("purpose must be end_of_course or diagnostic");
+  }
+  if (options.grade !== undefined && !isValidGrade(options.grade)) {
+    throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+  }
+  if (options.subject !== undefined && !isValidSubject(options.subject)) {
+    throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+  }
+}
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   return {
+    assessments: {
+      start: async (input) => {
+        assertPlatformMode(client, "timeback.assessments.start()");
+        if (!input.activityId?.trim()) {
+          throw new Error("activityId is required");
+        }
+        validateAssessmentFilters(input);
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+      },
+      latest: async (options) => {
+        assertPlatformMode(client, "timeback.assessments.latest()");
+        validateAssessmentFilters(options);
+        const params = new URLSearchParams({ purpose: options.purpose });
+        if (options.subject !== undefined) {
+          params.set("subject", options.subject);
+        }
+        if (options.grade !== undefined) {
+          params.set("grade", String(options.grade));
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/latest?${params.toString()}`, "GET");
+      },
+      get: async (attemptId) => {
+        assertPlatformMode(client, "timeback.assessments.get()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+      },
+      save: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.save()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        if (!Number.isInteger(input.expectedResponseVersion) || input.expectedResponseVersion < 0) {
+          throw new Error("expectedResponseVersion must be a non-negative integer");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/save`, "POST", input);
+      },
+      submit: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.submit()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        if (!Number.isInteger(input.expectedResponseVersion) || input.expectedResponseVersion < 0) {
+          throw new Error("expectedResponseVersion must be a non-negative integer");
+        }
+        if (!input.submissionId?.trim()) {
+          throw new Error("submissionId is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", input);
+      }
+    },
     get user() {
       assertPlatformMode(client, "timeback.user");
       return {
@@ -2391,7 +2469,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.16.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -3483,6 +3483,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             reactivateCourse: (gameId: string, courseId: string) => Promise<_playcademy_types.GameTimebackIntegration>;
             getIntegrationConfig: (gameId: string, courseId: string) => Promise<_playcademy_types.GameTimebackIntegrationConfig>;
             getConfig: (gameId: string) => Promise<_playcademy_types.TimebackSetupRequest['config']>;
+            exportAssessmentFixtures: (gameId: string) => Promise<_playcademy_types.AssessmentRuntimeFixtureBundle>;
         };
         students: {
             get: (timebackId: string, options?: TTLCacheConfig) => Promise<PlatformTimebackUserContext>;

package/dist/internal.js

@@ -1118,25 +1118,12 @@ function createScoresNamespace(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);
-}
+// ../constants/src/auth.ts
+var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
+  games: ["read", "write", "delete"],
+  users: ["read:self", "write:self"],
+  dev: ["read", "write"]
+};
 // ../constants/src/platform.ts
 var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
 // ../constants/src/timeback.ts
@@ -1147,8 +1134,22 @@ var TIMEBACK_ROUTES = {
   GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
   HEARTBEAT: "/integrations/timeback/heartbeat",
   ADVANCE_COURSE: "/integrations/timeback/advance-course",
-  UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
+  UNENROLL_COURSE: "/integrations/timeback/unenroll-course",
+  ASSESSMENTS: "/integrations/timeback/assessments"
 };
+var TIMEBACK_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var TIMEBACK_SUBJECTS = [
+  "Reading",
+  "Language",
+  "Vocabulary",
+  "Social Studies",
+  "Writing",
+  "Science",
+  "FastMath",
+  "Math",
+  "None"
+];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
   mastery: 0,
@@ -1160,6 +1161,19 @@ var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
   time: 60,
   score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
 };
+// src/core/guards.ts
+var VALID_GRADES = TIMEBACK_GRADES;
+var VALID_SUBJECTS = TIMEBACK_SUBJECTS;
+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);
+}
+function isAssessmentPurpose(value) {
+  return typeof value === "string" && ASSESSMENT_PURPOSES.includes(value);
+}
+
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -2003,9 +2017,73 @@ function createTimebackEngine(client) {
 // src/namespaces/game/timeback.ts
 var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
 var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
+var ASSESSMENTS_ROUTE = TIMEBACK_ROUTES.ASSESSMENTS;
+function validateAssessmentFilters(options) {
+  if (!isAssessmentPurpose(options?.purpose)) {
+    throw new Error("purpose must be end_of_course or diagnostic");
+  }
+  if (options.grade !== undefined && !isValidGrade(options.grade)) {
+    throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+  }
+  if (options.subject !== undefined && !isValidSubject(options.subject)) {
+    throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+  }
+}
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   return {
+    assessments: {
+      start: async (input) => {
+        assertPlatformMode(client, "timeback.assessments.start()");
+        if (!input.activityId?.trim()) {
+          throw new Error("activityId is required");
+        }
+        validateAssessmentFilters(input);
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+      },
+      latest: async (options) => {
+        assertPlatformMode(client, "timeback.assessments.latest()");
+        validateAssessmentFilters(options);
+        const params = new URLSearchParams({ purpose: options.purpose });
+        if (options.subject !== undefined) {
+          params.set("subject", options.subject);
+        }
+        if (options.grade !== undefined) {
+          params.set("grade", String(options.grade));
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/latest?${params.toString()}`, "GET");
+      },
+      get: async (attemptId) => {
+        assertPlatformMode(client, "timeback.assessments.get()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+      },
+      save: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.save()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        if (!Number.isInteger(input.expectedResponseVersion) || input.expectedResponseVersion < 0) {
+          throw new Error("expectedResponseVersion must be a non-negative integer");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/save`, "POST", input);
+      },
+      submit: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.submit()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        if (!Number.isInteger(input.expectedResponseVersion) || input.expectedResponseVersion < 0) {
+          throw new Error("expectedResponseVersion must be a non-negative integer");
+        }
+        if (!input.submissionId?.trim()) {
+          throw new Error("submissionId is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", input);
+      }
+    },
     get user() {
       assertPlatformMode(client, "timeback.user");
       return {
@@ -2146,6 +2224,11 @@ function createAdminNamespace(client) {
     }
   };
 }
+// ../utils/src/error.ts
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/namespaces/platform/auth.ts
 function createAuthNamespace(client) {
   return {
@@ -2162,7 +2245,7 @@ function createAuthNamespace(client) {
       } catch (error) {
         return {
           success: false,
-          error: error instanceof Error ? error.message : "Authentication failed"
+          error: errorMessage(error)
         };
       }
     },
@@ -2177,11 +2260,7 @@ function createAuthNamespace(client) {
         body: {
           name: options?.name || `SDK Key - ${new Date().toISOString()}`,
           expiresIn: options?.expiresIn !== undefined ? options.expiresIn : null,
-          permissions: options?.permissions || {
-            games: ["read", "write", "delete"],
-            users: ["read:self", "write:self"],
-            dev: ["read", "write"]
-          }
+          permissions: options?.permissions || DEFAULT_PERSONAL_API_KEY_PERMISSIONS
         }
       }),
       list: async () => client["request"]("/auth/api-key/list", "GET"),
@@ -2914,7 +2993,8 @@ function createTimebackNamespace2(client) {
       deactivateCourse: (gameId, courseId) => client["request"](`/timeback/integrations/${gameId}/${courseId}`, "DELETE"),
       reactivateCourse: (gameId, courseId) => client["request"](`/timeback/integrations/${gameId}/${courseId}/reactivate`, "POST"),
       getIntegrationConfig: (gameId, courseId) => client["request"](`/timeback/integrations/${gameId}/${courseId}`, "GET"),
-      getConfig: (gameId) => client["request"](`/timeback/config/${gameId}`, "GET")
+      getConfig: (gameId) => client["request"](`/timeback/config/${gameId}`, "GET"),
+      exportAssessmentFixtures: (gameId) => client["request"](`/timeback/assessments/fixtures/${gameId}`, "GET")
     },
     students: {
       get: async (timebackId, options) => studentCache.get(timebackId, async () => client["request"](`/timeback/user/${timebackId}`, "GET"), options),
@@ -3239,7 +3319,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.16.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.d.ts

@@ -346,6 +346,15 @@ declare class PlaycademyClient {
     get config(): PlaycademyServerClientState['config'];
     /** TimeBack integration methods (endActivity) */
     timeback: {
+        assessments: {
+            start: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            latest: (studentId: string, options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
+            get: (studentId: string, attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            save: (studentId: string, attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+                sensorUrl: string;
+            }) => Promise<_playcademy_types.AssessmentSubmitResult>;
+        };
         endActivity: (studentId: string, payload: _playcademy_types.EndActivityPayload) => Promise<_playcademy_types.EndActivityResponse>;
         getStudentXp: (studentId: string, options?: {
             grade?: number;

package/dist/server/edge.js

@@ -10,9 +10,27 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
-// 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 = [
+// ../constants/src/auth.ts
+var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
+  games: ["read", "write", "delete"],
+  users: ["read:self", "write:self"],
+  dev: ["read", "write"]
+};
+// ../constants/src/platform.ts
+var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
+// ../constants/src/timeback.ts
+var TIMEBACK_ROUTES = {
+  END_ACTIVITY: "/integrations/timeback/end-activity",
+  GET_XP: "/integrations/timeback/xp",
+  GET_MASTERY: "/integrations/timeback/mastery",
+  GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
+  HEARTBEAT: "/integrations/timeback/heartbeat",
+  ADVANCE_COURSE: "/integrations/timeback/advance-course",
+  UNENROLL_COURSE: "/integrations/timeback/unenroll-course",
+  ASSESSMENTS: "/integrations/timeback/assessments"
+};
+var TIMEBACK_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var TIMEBACK_SUBJECTS = [
   "Reading",
   "Language",
   "Vocabulary",
@@ -23,12 +41,30 @@ var VALID_SUBJECTS = [
   "Math",
   "None"
 ];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+};
+// src/core/guards.ts
+var VALID_GRADES = TIMEBACK_GRADES;
+var VALID_SUBJECTS = TIMEBACK_SUBJECTS;
 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);
 }
+function isAssessmentPurpose(value) {
+  return typeof value === "string" && ASSESSMENT_PURPOSES.includes(value);
+}
 // src/server/namespaces/timeback.ts
 function createTimebackNamespace(client) {
   function enrichActivityData(data) {
@@ -38,6 +74,35 @@ function createTimebackNamespace(client) {
     };
   }
   return {
+    assessments: {
+      start: (studentId, input) => client["request"]("/api/timeback/assessments/start", "POST", { ...input, gameId: client.gameId, studentId }),
+      latest: (studentId, options) => {
+        const params = new URLSearchParams({
+          gameId: client.gameId,
+          studentId,
+          purpose: options.purpose
+        });
+        if (options.subject !== undefined) {
+          params.set("subject", options.subject);
+        }
+        if (options.grade !== undefined) {
+          params.set("grade", String(options.grade));
+        }
+        return client["request"](`/api/timeback/assessments/latest?${params.toString()}`, "GET");
+      },
+      get: (studentId, attemptId) => {
+        const params = new URLSearchParams({ gameId: client.gameId, studentId });
+        return client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}?${params.toString()}`, "GET");
+      },
+      save: (studentId, attemptId, input) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/save`, "POST", { ...input, gameId: client.gameId, studentId }),
+      submit: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit`, "POST", {
+        ...input,
+        gameId: client.gameId,
+        studentId,
+        appName: client.config.name,
+        sensorUrl: context.sensorUrl
+      })
+    },
     endActivity: async (studentId, payload) => {
       if (!isValidGrade(payload.activityData.grade)) {
         throw new Error("activityData.grade must be a valid grade level (-1 to 13)");
@@ -234,7 +299,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.16.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -346,6 +346,15 @@ declare class PlaycademyClient$1 {
     get config(): PlaycademyServerClientState['config'];
     /** TimeBack integration methods (endActivity) */
     timeback: {
+        assessments: {
+            start: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            latest: (studentId: string, options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
+            get: (studentId: string, attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            save: (studentId: string, attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+                sensorUrl: string;
+            }) => Promise<_playcademy_types.AssessmentSubmitResult>;
+        };
         endActivity: (studentId: string, payload: _playcademy_types.EndActivityPayload) => Promise<_playcademy_types.EndActivityResponse>;
         getStudentXp: (studentId: string, options?: {
             grade?: number;

package/dist/server.js

@@ -199,9 +199,27 @@ var init_config_loader = __esm(() => {
   init_file_loader();
 });
 
-// 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 = [
+// ../constants/src/auth.ts
+var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
+  games: ["read", "write", "delete"],
+  users: ["read:self", "write:self"],
+  dev: ["read", "write"]
+};
+// ../constants/src/platform.ts
+var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
+// ../constants/src/timeback.ts
+var TIMEBACK_ROUTES = {
+  END_ACTIVITY: "/integrations/timeback/end-activity",
+  GET_XP: "/integrations/timeback/xp",
+  GET_MASTERY: "/integrations/timeback/mastery",
+  GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
+  HEARTBEAT: "/integrations/timeback/heartbeat",
+  ADVANCE_COURSE: "/integrations/timeback/advance-course",
+  UNENROLL_COURSE: "/integrations/timeback/unenroll-course",
+  ASSESSMENTS: "/integrations/timeback/assessments"
+};
+var TIMEBACK_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var TIMEBACK_SUBJECTS = [
   "Reading",
   "Language",
   "Vocabulary",
@@ -212,12 +230,30 @@ var VALID_SUBJECTS = [
   "Math",
   "None"
 ];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+};
+// src/core/guards.ts
+var VALID_GRADES = TIMEBACK_GRADES;
+var VALID_SUBJECTS = TIMEBACK_SUBJECTS;
 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);
 }
+function isAssessmentPurpose(value) {
+  return typeof value === "string" && ASSESSMENT_PURPOSES.includes(value);
+}
 // src/server/namespaces/timeback.ts
 function createTimebackNamespace(client) {
   function enrichActivityData(data) {
@@ -227,6 +263,35 @@ function createTimebackNamespace(client) {
     };
   }
   return {
+    assessments: {
+      start: (studentId, input) => client["request"]("/api/timeback/assessments/start", "POST", { ...input, gameId: client.gameId, studentId }),
+      latest: (studentId, options) => {
+        const params = new URLSearchParams({
+          gameId: client.gameId,
+          studentId,
+          purpose: options.purpose
+        });
+        if (options.subject !== undefined) {
+          params.set("subject", options.subject);
+        }
+        if (options.grade !== undefined) {
+          params.set("grade", String(options.grade));
+        }
+        return client["request"](`/api/timeback/assessments/latest?${params.toString()}`, "GET");
+      },
+      get: (studentId, attemptId) => {
+        const params = new URLSearchParams({ gameId: client.gameId, studentId });
+        return client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}?${params.toString()}`, "GET");
+      },
+      save: (studentId, attemptId, input) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/save`, "POST", { ...input, gameId: client.gameId, studentId }),
+      submit: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit`, "POST", {
+        ...input,
+        gameId: client.gameId,
+        studentId,
+        appName: client.config.name,
+        sensorUrl: context.sensorUrl
+      })
+    },
     endActivity: async (studentId, payload) => {
       if (!isValidGrade(payload.activityData.grade)) {
         throw new Error("activityData.grade must be a valid grade level (-1 to 13)");
@@ -423,7 +488,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.16.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -1465,6 +1465,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */
     timeback: {
+        assessments: {
+            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
+            get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            save: (attemptId: string, input: _playcademy_types.SaveAssessmentInput) => Promise<_playcademy_types.AssessmentSaveResult>;
+            submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
+        };
         readonly user: TimebackUser;
         readonly currentRunId: string | undefined;
         startActivity: (metadata: _playcademy_types.ActivityData, options?: StartActivityOptions) => StartActivityResult;

package/package.json

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