@playcademy/sdk 0.16.1-beta.7 → 0.16.1-beta.9

package/README.md

@@ -139,9 +139,10 @@ const completed = await client.timeback.assessments.submit(attempt.attemptId, {
 })
 ```
 
-`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.
+`start()` resumes a compatible unfinished attempt or selects content for a fixed test or standards
+review. Save payloads merge at both the item and response levels; omitted values remain unchanged,
+and `null` clears one response. Keep the returned `responseVersion` and send it with the next
+mutation.
 
 For local development, import the current ordered catalog before starting the dev host:
 

package/dist/index.js

@@ -823,7 +823,12 @@ var TIMEBACK_SUBJECTS = [
   "Math",
   "None"
 ];
-var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
+var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
+  standards: 20,
+  itemsPerStandard: 5,
+  standardFieldLength: 128
+};
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
@@ -2952,7 +2957,7 @@ 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");
+    throw new Error("purpose must be end_of_course, diagnostic, review, or mastery");
   }
   if (options.grade !== undefined && !isValidGrade(options.grade)) {
     throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
@@ -2960,6 +2965,17 @@ function validateAssessmentFilters(options) {
   if (options.subject !== undefined && !isValidSubject(options.subject)) {
     throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
   }
+  if (options.purpose === "mastery") {
+    const { standard } = options;
+    const framework = typeof standard?.framework === "string" ? standard.framework.trim() : "";
+    const identifier = typeof standard?.identifier === "string" ? standard.identifier.trim() : "";
+    if (!framework || !identifier) {
+      throw new Error("mastery standard requires a canonical framework and identifier");
+    }
+    if (framework.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength || identifier.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength) {
+      throw new Error(`mastery standard fields must be at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength} characters`);
+    }
+  }
 }
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
@@ -2972,6 +2988,25 @@ function createTimebackNamespace(client) {
           throw new Error("activityId is required");
         }
         validateAssessmentFilters(input);
+        if (input.purpose === "review") {
+          if (!Array.isArray(input.standards) || input.standards.length === 0) {
+            throw new Error("standards must contain at least one standard for review");
+          }
+          if (input.standards.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards) {
+            throw new Error(`standards must contain at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards} standards`);
+          }
+          for (const standard of input.standards) {
+            if (!standard || typeof standard !== "object" || !standard.framework?.trim() || !standard.identifier?.trim()) {
+              throw new Error("review standards require a framework and identifier");
+            }
+            if (standard.framework.trim().length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength || standard.identifier.trim().length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength) {
+              throw new Error(`review standard fields must be at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength} characters`);
+            }
+          }
+          if (input.itemsPerStandard !== undefined && (!Number.isInteger(input.itemsPerStandard) || input.itemsPerStandard <= 0 || input.itemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard)) {
+            throw new Error(`itemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard}`);
+          }
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
       },
       latest: async (options) => {
@@ -2984,6 +3019,10 @@ function createTimebackNamespace(client) {
         if (options.grade !== undefined) {
           params.set("grade", String(options.grade));
         }
+        if (options.purpose === "mastery") {
+          params.set("standardFramework", options.standard.framework);
+          params.set("standardIdentifier", options.standard.identifier);
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/latest?${params.toString()}`, "GET");
       },
       get: async (attemptId) => {
@@ -3421,7 +3460,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.7";
+var SDK_VERSION = "0.16.1-beta.9";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -3985,10 +3985,12 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             create: (gameId: string, courseId: string, data: {
                 title: string;
                 purpose: _playcademy_types.AssessmentPurpose;
+                standard?: _playcademy_types.AssessmentStandardRef;
             }) => Promise<_playcademy_types.AssessmentRow>;
             update: (gameId: string, courseId: string, testIdentifier: string, data: {
                 title?: string;
                 purpose?: _playcademy_types.AssessmentPurpose;
+                standard?: _playcademy_types.AssessmentStandardRef;
                 status?: _playcademy_types.AssessmentStatus;
             }) => Promise<_playcademy_types.AssessmentRow>;
             reorder: (gameId: string, courseId: string, purpose: _playcademy_types.AssessmentPurpose, testIdentifiers: string[]) => Promise<{
@@ -3998,7 +4000,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 action: 'discarded' | 'archived';
             }>;
             listTestLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentTestListResponse>;
-            copy: (gameId: string, courseId: string, testIdentifier: string, purpose: _playcademy_types.AssessmentPurpose) => Promise<_playcademy_types.AssessmentRow>;
+            copy: (gameId: string, courseId: string, testIdentifier: string, purpose: _playcademy_types.AssessmentPurpose, standard?: _playcademy_types.AssessmentStandardRef) => Promise<_playcademy_types.AssessmentRow>;
             listQuestions: (gameId: string, courseId: string, testIdentifier: string) => Promise<_playcademy_types.QtiTestQuestionsResponse>;
             listQuestionLibrary: (gameId: string, courseId: string, options?: QtiLibraryQueryOptions) => Promise<_playcademy_types.QtiAssessmentItemListResponse>;
             createQuestion: (gameId: string, courseId: string, testIdentifier: string, data: _playcademy_types.QtiQuestionCreateInput) => Promise<_playcademy_types.QtiTestQuestionRef>;

package/dist/internal.js

@@ -823,7 +823,12 @@ var TIMEBACK_SUBJECTS = [
   "Math",
   "None"
 ];
-var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
+var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
+  standards: 20,
+  itemsPerStandard: 5,
+  standardFieldLength: 128
+};
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
@@ -2952,7 +2957,7 @@ 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");
+    throw new Error("purpose must be end_of_course, diagnostic, review, or mastery");
   }
   if (options.grade !== undefined && !isValidGrade(options.grade)) {
     throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
@@ -2960,6 +2965,17 @@ function validateAssessmentFilters(options) {
   if (options.subject !== undefined && !isValidSubject(options.subject)) {
     throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
   }
+  if (options.purpose === "mastery") {
+    const { standard } = options;
+    const framework = typeof standard?.framework === "string" ? standard.framework.trim() : "";
+    const identifier = typeof standard?.identifier === "string" ? standard.identifier.trim() : "";
+    if (!framework || !identifier) {
+      throw new Error("mastery standard requires a canonical framework and identifier");
+    }
+    if (framework.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength || identifier.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength) {
+      throw new Error(`mastery standard fields must be at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength} characters`);
+    }
+  }
 }
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
@@ -2972,6 +2988,25 @@ function createTimebackNamespace(client) {
           throw new Error("activityId is required");
         }
         validateAssessmentFilters(input);
+        if (input.purpose === "review") {
+          if (!Array.isArray(input.standards) || input.standards.length === 0) {
+            throw new Error("standards must contain at least one standard for review");
+          }
+          if (input.standards.length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards) {
+            throw new Error(`standards must contain at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standards} standards`);
+          }
+          for (const standard of input.standards) {
+            if (!standard || typeof standard !== "object" || !standard.framework?.trim() || !standard.identifier?.trim()) {
+              throw new Error("review standards require a framework and identifier");
+            }
+            if (standard.framework.trim().length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength || standard.identifier.trim().length > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength) {
+              throw new Error(`review standard fields must be at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength} characters`);
+            }
+          }
+          if (input.itemsPerStandard !== undefined && (!Number.isInteger(input.itemsPerStandard) || input.itemsPerStandard <= 0 || input.itemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard)) {
+            throw new Error(`itemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard}`);
+          }
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
       },
       latest: async (options) => {
@@ -2984,6 +3019,10 @@ function createTimebackNamespace(client) {
         if (options.grade !== undefined) {
           params.set("grade", String(options.grade));
         }
+        if (options.purpose === "mastery") {
+          params.set("standardFramework", options.standard.framework);
+          params.set("standardIdentifier", options.standard.identifier);
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/latest?${params.toString()}`, "GET");
       },
       get: async (attemptId) => {
@@ -3863,8 +3902,8 @@ function createAssessmentNamespace(client) {
     }),
     remove: (gameId, courseId, testIdentifier) => client["request"](assessmentPath(gameId, courseId, testIdentifier), "DELETE"),
     listTestLibrary: (gameId, courseId, options = {}) => client["request"](`${assessmentPath(gameId, courseId, "test-library")}${buildQtiLibraryQueryString(options)}`, "GET"),
-    copy: (gameId, courseId, testIdentifier, purpose) => client["request"](assessmentPath(gameId, courseId, "copies"), "POST", {
-      body: { testIdentifier, purpose }
+    copy: (gameId, courseId, testIdentifier, purpose, standard) => client["request"](assessmentPath(gameId, courseId, "copies"), "POST", {
+      body: { testIdentifier, purpose, standard }
     }),
     listQuestions: (gameId, courseId, testIdentifier) => client["request"](assessmentPath(gameId, courseId, testIdentifier, "questions"), "GET"),
     listQuestionLibrary: (gameId, courseId, options = {}) => client["request"](`${assessmentPath(gameId, courseId, "question-library")}${buildQtiLibraryQueryString(options)}`, "GET"),
@@ -4296,7 +4335,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.7";
+var SDK_VERSION = "0.16.1-beta.9";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.js

@@ -41,7 +41,12 @@ var TIMEBACK_SUBJECTS = [
   "Math",
   "None"
 ];
-var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
+var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
+  standards: 20,
+  itemsPerStandard: 5,
+  standardFieldLength: 128
+};
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
@@ -92,6 +97,10 @@ function createTimebackNamespace(client) {
         if (options.grade !== undefined) {
           params.set("grade", String(options.grade));
         }
+        if (options.purpose === "mastery") {
+          params.set("standardFramework", options.standard.framework);
+          params.set("standardIdentifier", options.standard.identifier);
+        }
         return client["request"](`/api/timeback/assessments/latest?${params.toString()}`, "GET");
       },
       get: (studentId, attemptId) => {
@@ -303,7 +312,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.7";
+var SDK_VERSION = "0.16.1-beta.9";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.js

@@ -230,7 +230,12 @@ var TIMEBACK_SUBJECTS = [
   "Math",
   "None"
 ];
-var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic"];
+var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
+var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
+  standards: 20,
+  itemsPerStandard: 5,
+  standardFieldLength: 128
+};
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
 var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
   xp: 1,
@@ -281,6 +286,10 @@ function createTimebackNamespace(client) {
         if (options.grade !== undefined) {
           params.set("grade", String(options.grade));
         }
+        if (options.purpose === "mastery") {
+          params.set("standardFramework", options.standard.framework);
+          params.set("standardIdentifier", options.standard.identifier);
+        }
         return client["request"](`/api/timeback/assessments/latest?${params.toString()}`, "GET");
       },
       get: (studentId, attemptId) => {
@@ -492,7 +501,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.7";
+var SDK_VERSION = "0.16.1-beta.9";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/package.json

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