@playcademy/sdk 0.16.1-beta.22 → 0.16.1-beta.24

package/README.md

@@ -122,21 +122,25 @@ Hosted assessments use the same methods locally and when deployed:
 const attempt = await client.timeback.assessments.start({
     activityId: 'math-diagnostic',
     purpose: 'diagnostic',
+    diagnosticKey: 'math.grade-5-placement',
     subject: 'Math',
     grade: 5,
 })
 
-const saved = await client.timeback.assessments.save(attempt.attemptId, {
-    expectedResponseVersion: attempt.responseVersion,
-    responses: {
-        [attempt.assessment.items[0].identifier]: { RESPONSE: 'A' },
-    },
-})
+if (attempt.flow !== 'platform-routed-item-submit' || !attempt.routing.next) {
+    throw new Error('Expected an active routed diagnostic')
+}
 
-const completed = await client.timeback.assessments.submit(attempt.attemptId, {
-    expectedResponseVersion: saved.responseVersion,
+const current = attempt.routing.next
+const committed = await client.timeback.assessments.submitItem(attempt.attemptId, {
+    expectedResponseVersion: attempt.responseVersion,
     submissionId: crypto.randomUUID(),
+    routingNodeKey: current.nodeKey,
+    itemIdentifier: current.itemIdentifier,
+    responses: { RESPONSE: 'A' },
 })
+
+// Repeat with committed.routing.next. When routing is ready, submit() only finalizes.
 ```
 
 `start()` resumes a compatible unfinished attempt or selects content for a fixed test or standards
@@ -144,20 +148,24 @@ review. Save payloads merge at both the item and response levels; omitted values
 and `null` clears one response. Keep the returned `responseVersion` and send it with the next
 mutation.
 
-The returned `flow` is authoritative and is derived from `purpose`; callers do not configure
+The returned `flow` is authoritative and is derived from the selected assessment; callers do not configure
 navigation, feedback, and submission independently:
 
-- `attempt-submit` is used for diagnostic, end-of-course, and mastery attempts. Responses remain
-  editable through `save()` until `submit()` finalizes the whole attempt and returns feedback.
+- `attempt-submit` is used for end-of-course and mastery attempts. Responses remain editable
+  through `save()` until `submit()` finalizes the whole attempt and returns feedback.
 - `item-submit` is used for review attempts. Submit each administered item with `submitItem()`.
   That operation atomically saves the item's responses, locks them, and returns safe immediate
   feedback. Give each item request its own stable `submissionId` and reuse that ID for an ambiguous
   retry; the returned canonical `itemSubmissions` ledger identifies committed items after retry or
   resume.
-
-The host rejects `submitItem()` for attempt-submit flows, rejects `submit()` until an item-submit
-attempt has administered at least one item, and enforces `expectedResponseVersion` for every
-mutation.
+- `platform-routed-item-submit` is used for adaptive diagnostics. Render only
+  `routing.next.itemIdentifier`, submit it with `routing.next.nodeKey`, and replace local state with
+  the returned canonical routing snapshot. Diagnostic receipts never reveal correctness or score,
+  and `submit()` becomes available only after routing reports `ready-to-complete`.
+
+The host rejects the wrong mutation for each flow, rejects premature finalization, and enforces
+`expectedResponseVersion` for every mutation. Hosted and local providers execute the same routing
+manifest contract; game code never selects the provider.
 
 For local development, import the current ordered catalog before starting the dev host:
 

package/dist/index.js

@@ -1206,8 +1206,11 @@ class ChildSession {
     }
     this.#markOpenWindowFlushable();
     this.#forwardDirtyWindows();
-    window.removeEventListener("message", this.#onChildMessage);
-    window.removeEventListener("pagehide", this.#onPageHide);
+    const win = globalThis.window;
+    if (win) {
+      win.removeEventListener("message", this.#onChildMessage);
+      win.removeEventListener("pagehide", this.#onPageHide);
+    }
     messaging.unlisten("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, this.#onTokenRefresh);
     messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, this.#onLauncherPause);
     messaging.unlisten("PLAYCADEMY_RESUME" /* RESUME */, this.#onLauncherResume);
@@ -3150,6 +3153,12 @@ function createTimebackNamespace(client) {
           throw new Error("activityId is required");
         }
         validateAssessmentFilters(input);
+        if (input.purpose === "diagnostic" && !input.diagnosticKey?.trim()) {
+          throw new Error("diagnosticKey is required for diagnostic assessments");
+        }
+        if (input.purpose === "diagnostic" && input.diagnosticKey.trim().length > 200) {
+          throw new Error("diagnosticKey must contain at most 200 characters");
+        }
         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");
@@ -3232,6 +3241,9 @@ function createTimebackNamespace(client) {
         if (!input.itemIdentifier?.trim()) {
           throw new Error("itemIdentifier is required");
         }
+        if (input.routingNodeKey !== undefined && !input.routingNodeKey.trim()) {
+          throw new Error("routingNodeKey must be non-empty when provided");
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit-item`, "POST", input);
       },
       submit: async (attemptId, input) => {
@@ -3670,7 +3682,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.22";
+var SDK_VERSION = "0.16.1-beta.24";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -1,7 +1,7 @@
 import { SchemaInfo } from '@playcademy/cloudflare';
 import { GamePermission, AUTH_PROVIDER_IDS } from '@playcademy/constants';
 import { TimebackGrade, TimebackSubject, ELevel, HeartbeatRequest, EndActivityRequest, EndActivityScoreData, EndActivityResponse, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
-export { AssessmentAttemptSnapshot, AssessmentFlow, AssessmentItemSubmission, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ELevel, PlayableAssessment, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, StartAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult } from '@playcademy/types/timeback';
+export { AssessmentAttemptSnapshot, AssessmentFlow, AssessmentItemSubmission, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, StartAssessmentInput, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult } from '@playcademy/types/timeback';
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest, LocalDayContext } from '@playcademy/types';
 export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
@@ -3659,6 +3659,11 @@ interface QtiLibraryQueryOptions {
     page?: number;
     limit?: number;
 }
+interface ReviewMappingUpdateResult {
+    itemCount: number;
+    standardCount: number;
+    sourceFingerprint: string;
+}
 
 /**
  * Internal Playcademy SDK client with all namespaces.
@@ -4021,7 +4026,7 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
             list: (gameId: string, courseId: string) => Promise<_playcademy_types.AssessmentSummary[]>;
             create: (gameId: string, courseId: string, data: {
                 title: string;
-                purpose: _playcademy_types.AssessmentPurpose;
+                purpose: Exclude<_playcademy_types.AssessmentPurpose, 'diagnostic'>;
                 standard?: _playcademy_types.AssessmentStandardRef;
             }) => Promise<_playcademy_types.AssessmentRow>;
             attachExisting: (gameId: string, courseId: string, manifest: _playcademy_types.AssessmentAssociationImportManifest) => Promise<_playcademy_types.AssessmentAssociationImportResponse>;
@@ -4029,8 +4034,10 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
                 title?: string;
                 purpose?: _playcademy_types.AssessmentPurpose;
                 standard?: _playcademy_types.AssessmentStandardRef;
+                diagnostic?: _playcademy_types.DiagnosticAssessmentDefinitionInput | null;
                 status?: _playcademy_types.AssessmentStatus;
             }) => Promise<_playcademy_types.AssessmentRow>;
+            updateReviewMapping: (gameId: string, courseId: string, testIdentifier: string) => Promise<ReviewMappingUpdateResult>;
             reorder: (gameId: string, courseId: string, purpose: _playcademy_types.AssessmentPurpose, testIdentifiers: string[]) => Promise<{
                 success: boolean;
             }>;
@@ -4038,7 +4045,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, standard?: _playcademy_types.AssessmentStandardRef) => Promise<_playcademy_types.AssessmentRow>;
+            copy: (gameId: string, courseId: string, testIdentifier: string, purpose: Exclude<_playcademy_types.AssessmentPurpose, 'diagnostic'>, 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

@@ -1206,8 +1206,11 @@ class ChildSession {
     }
     this.#markOpenWindowFlushable();
     this.#forwardDirtyWindows();
-    window.removeEventListener("message", this.#onChildMessage);
-    window.removeEventListener("pagehide", this.#onPageHide);
+    const win = globalThis.window;
+    if (win) {
+      win.removeEventListener("message", this.#onChildMessage);
+      win.removeEventListener("pagehide", this.#onPageHide);
+    }
     messaging.unlisten("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, this.#onTokenRefresh);
     messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, this.#onLauncherPause);
     messaging.unlisten("PLAYCADEMY_RESUME" /* RESUME */, this.#onLauncherResume);
@@ -3150,6 +3153,12 @@ function createTimebackNamespace(client) {
           throw new Error("activityId is required");
         }
         validateAssessmentFilters(input);
+        if (input.purpose === "diagnostic" && !input.diagnosticKey?.trim()) {
+          throw new Error("diagnosticKey is required for diagnostic assessments");
+        }
+        if (input.purpose === "diagnostic" && input.diagnosticKey.trim().length > 200) {
+          throw new Error("diagnosticKey must contain at most 200 characters");
+        }
         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");
@@ -3232,6 +3241,9 @@ function createTimebackNamespace(client) {
         if (!input.itemIdentifier?.trim()) {
           throw new Error("itemIdentifier is required");
         }
+        if (input.routingNodeKey !== undefined && !input.routingNodeKey.trim()) {
+          throw new Error("routingNodeKey must be non-empty when provided");
+        }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit-item`, "POST", input);
       },
       submit: async (attemptId, input) => {
@@ -4111,6 +4123,7 @@ function createAssessmentNamespace(client) {
     update: (gameId, courseId, testIdentifier, data) => client["request"](assessmentPath(gameId, courseId, testIdentifier), "PATCH", {
       body: data
     }),
+    updateReviewMapping: (gameId, courseId, testIdentifier) => client["request"](assessmentPath(gameId, courseId, testIdentifier, "review-mapping"), "POST"),
     reorder: (gameId, courseId, purpose, testIdentifiers) => client["request"](assessmentPath(gameId, courseId, "order"), "PUT", {
       body: { purpose, testIdentifiers }
     }),
@@ -4549,7 +4562,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.22";
+var SDK_VERSION = "0.16.1-beta.24";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.js

@@ -313,7 +313,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.22";
+var SDK_VERSION = "0.16.1-beta.24";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.js

@@ -502,7 +502,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.22";
+var SDK_VERSION = "0.16.1-beta.24";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -2,7 +2,7 @@ import * as _playcademy_types from '@playcademy/types';
 import { GameManifest, LocalDayContext } from '@playcademy/types';
 export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, LocalDayContext, LocalDaySource, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
 import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject, ELevel, EndActivityRequest, HeartbeatRequest, EndActivityScoreData, EndActivityResponse } from '@playcademy/types/timeback';
-export { AssessmentAttemptSnapshot, AssessmentFlow, AssessmentItemSubmission, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ELevel, PlayableAssessment, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, StartAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult } from '@playcademy/types/timeback';
+export { AssessmentAttemptSnapshot, AssessmentFlow, AssessmentItemSubmission, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, StartAssessmentInput, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 import { GamePermission, AUTH_PROVIDER_IDS } from '@playcademy/constants';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';

package/package.json

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