@playcademy/sdk 0.16.1-beta.10 → 0.16.1-beta.11

package/README.md

@@ -144,6 +144,20 @@ 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
+navigation, feedback, and submission independently:
+
+- `attempt-submit` is used for diagnostic and end-of-course attempts. Responses remain editable
+  through `save()` until `submit()` finalizes the whole attempt and returns feedback.
+- `item-submit` is used for review and mastery attempts. Submit each item in assessment order 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 every item-submit
+item is committed, and enforces `expectedResponseVersion` for every mutation.
+
 For local development, import the current ordered catalog before starting the dev host:
 
 ```bash

package/dist/index.d.ts

@@ -1559,6 +1559,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             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>;
+            submitItem: (attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
         };
         readonly user: TimebackUser;

package/dist/index.js

@@ -3042,6 +3042,22 @@ function createTimebackNamespace(client) {
         }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/save`, "POST", input);
       },
+      submitItem: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.submitItem()");
+        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");
+        }
+        if (!input.itemIdentifier?.trim()) {
+          throw new Error("itemIdentifier is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit-item`, "POST", input);
+      },
       submit: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.submit()");
         if (!attemptId?.trim()) {
@@ -3460,7 +3476,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.10";
+var SDK_VERSION = "0.16.1-beta.11";
 
 // 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 { ELevel } 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';
 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';

package/dist/internal.js

@@ -3042,6 +3042,22 @@ function createTimebackNamespace(client) {
         }
         return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/save`, "POST", input);
       },
+      submitItem: async (attemptId, input) => {
+        assertPlatformMode(client, "timeback.assessments.submitItem()");
+        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");
+        }
+        if (!input.itemIdentifier?.trim()) {
+          throw new Error("itemIdentifier is required");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit-item`, "POST", input);
+      },
       submit: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.submit()");
         if (!attemptId?.trim()) {
@@ -4336,7 +4352,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.10";
+var SDK_VERSION = "0.16.1-beta.11";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.d.ts

@@ -359,6 +359,7 @@ declare class PlaycademyClient {
             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>;
+            submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;

package/dist/server/edge.js

@@ -108,6 +108,7 @@ function createTimebackNamespace(client) {
         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 }),
+      submitItem: (studentId, attemptId, input) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit-item`, "POST", { ...input, gameId: client.gameId, studentId }),
       submit: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit`, "POST", {
         ...input,
         gameId: client.gameId,
@@ -312,7 +313,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.10";
+var SDK_VERSION = "0.16.1-beta.11";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -359,6 +359,7 @@ declare class PlaycademyClient$1 {
             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>;
+            submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;

package/dist/server.js

@@ -297,6 +297,7 @@ function createTimebackNamespace(client) {
         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 }),
+      submitItem: (studentId, attemptId, input) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit-item`, "POST", { ...input, gameId: client.gameId, studentId }),
       submit: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/submit`, "POST", {
         ...input,
         gameId: client.gameId,
@@ -501,7 +502,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.10";
+var SDK_VERSION = "0.16.1-beta.11";
 
 // 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 { ELevel } 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';
 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';
@@ -2000,6 +2000,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             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>;
+            submitItem: (attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
             submit: (attemptId: string, input: _playcademy_types.SubmitAssessmentInput) => Promise<_playcademy_types.AssessmentSubmitResult>;
         };
         readonly user: TimebackUser;

package/package.json

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