@playcademy/sdk 0.16.1-beta.6 → 0.16.1-beta.8

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"];
+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, or review");
   }
   if (options.grade !== undefined && !isValidGrade(options.grade)) {
     throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
@@ -2972,6 +2977,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) => {
@@ -3421,7 +3445,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.6";
+var SDK_VERSION = "0.16.1-beta.8";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -3216,6 +3216,29 @@ interface BucketFile {
     lastModified: string;
     contentType?: string;
 }
+/**
+ * Options for a single-page bucket listing
+ */
+interface BucketListPageOptions {
+    /** Restrict results to keys starting with this prefix */
+    prefix?: string;
+    /** Opaque continuation cursor from the previous page's result */
+    cursor?: string;
+    /** Page size (1-1000); the server may return fewer */
+    limit?: number;
+    /** Roll deeper keys into `prefixes` entries, S3 delimiter style */
+    delimiter?: string;
+}
+/**
+ * One page of a bucket listing
+ */
+interface BucketFilePage {
+    files: BucketFile[];
+    /** Rolled-up common prefixes; present for delimiter listings that found any */
+    prefixes?: string[];
+    /** Present only when more pages remain */
+    cursor?: string;
+}
 /**
  * KV key entry
  */
@@ -3790,6 +3813,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             };
             bucket: {
                 list: (slug: string, prefix?: string) => Promise<BucketFile[]>;
+                listPage: (slug: string, options?: BucketListPageOptions) => Promise<BucketFilePage>;
                 get: (slug: string, key: string) => Promise<ArrayBuffer>;
                 put: (slug: string, key: string, content: Blob | ArrayBuffer | Uint8Array, contentType?: string) => Promise<void>;
                 initiateUpload: (slug: string, key: string, contentType: string) => Promise<{
@@ -4051,4 +4075,4 @@ interface BeginInitHandshakeOptions {
 declare function beginInitHandshake({ iframe, origin, payload, onTimeout, onSendError }: BeginInitHandshakeOptions): () => void;
 
 export { ApiError, HANDSHAKE_MAX_DURATION_MS, HANDSHAKE_RESEND_INTERVAL_MS, INIT_WAIT_TIMEOUT_MS, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, beginInitHandshake, extractApiErrorInfo, isTrustedIframeMessage, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { ApiErrorCode, ApiErrorInfo, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, MessageEventMap, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

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"];
+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, or review");
   }
   if (options.grade !== undefined && !isValidGrade(options.grade)) {
     throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
@@ -2972,6 +2977,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) => {
@@ -3461,8 +3485,26 @@ class DeployPipeline {
 }
 
 // src/namespaces/platform/dev.ts
+var BUCKET_LIST_PAGE_SIZE = 1000;
 function createDevNamespace(client) {
   const deploy = new DeployPipeline(client);
+  async function fetchBucketPage(slug, options = {}) {
+    const params = new URLSearchParams;
+    if (options.prefix) {
+      params.set("prefix", options.prefix);
+    }
+    if (options.cursor) {
+      params.set("cursor", options.cursor);
+    }
+    if (options.limit !== undefined) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.delimiter) {
+      params.set("delimiter", options.delimiter);
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return client["request"](`/games/${slug}/bucket${query}`, "GET");
+  }
   return {
     status: {
       apply: () => client["request"]("/dev/apply", "POST"),
@@ -3594,10 +3636,22 @@ function createDevNamespace(client) {
       },
       bucket: {
         list: async (slug, prefix) => {
-          const params = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
-          const result = await client["request"](`/games/${slug}/bucket${params}`, "GET");
-          return result.files;
+          const files = [];
+          let cursor;
+          do {
+            const page = await fetchBucketPage(slug, {
+              prefix,
+              cursor,
+              limit: BUCKET_LIST_PAGE_SIZE
+            });
+            for (const file of page.files) {
+              files.push(file);
+            }
+            cursor = page.cursor;
+          } while (cursor);
+          return files;
         },
+        listPage: fetchBucketPage,
         get: async (slug, key) => {
           const res = await client["request"](`/games/${slug}/bucket/${encodeURIComponent(key)}`, "GET", { raw: true });
           if (!res.ok) {
@@ -4266,7 +4320,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.6";
+var SDK_VERSION = "0.16.1-beta.8";
 
 // 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"];
+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,
@@ -303,7 +308,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.6";
+var SDK_VERSION = "0.16.1-beta.8";
 
 // 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"];
+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,
@@ -492,7 +497,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.6";
+var SDK_VERSION = "0.16.1-beta.8";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -2578,6 +2578,29 @@ interface BucketFile {
     lastModified: string;
     contentType?: string;
 }
+/**
+ * Options for a single-page bucket listing
+ */
+interface BucketListPageOptions {
+    /** Restrict results to keys starting with this prefix */
+    prefix?: string;
+    /** Opaque continuation cursor from the previous page's result */
+    cursor?: string;
+    /** Page size (1-1000); the server may return fewer */
+    limit?: number;
+    /** Roll deeper keys into `prefixes` entries, S3 delimiter style */
+    delimiter?: string;
+}
+/**
+ * One page of a bucket listing
+ */
+interface BucketFilePage {
+    files: BucketFile[];
+    /** Rolled-up common prefixes; present for delimiter listings that found any */
+    prefixes?: string[];
+    /** Present only when more pages remain */
+    cursor?: string;
+}
 /**
  * KV key entry
  */
@@ -2671,4 +2694,4 @@ interface PlatformTimebackUser extends PlatformTimebackUserContext {
 }
 
 export { PlaycademyClient };
-export type { AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, BucketFilePage, BucketListPageOptions, ChildCheckpointRelay, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EmbedActivity, EmbedActivityAbandoned, EmbedActivityCompleted, EmbedActivityFailed, EmbedLaunchOptions, EmbedResumeEnvelope, EmbedResumeStore, EmbedSession, EmbedSessionTiming, EmbedTimebackRecording, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LaunchIntent, LoginResponse, MasteryResponse, ParentGameContext, ParentGameHandle, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackActivityEndRelay, TimebackActivityStartRelay, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

package/package.json

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