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

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;
@@ -1910,6 +1911,15 @@ type EmbedActivity = EmbedActivityCompleted | EmbedActivityAbandoned | EmbedActi
 /** The child called `endActivity()` and its report was relayed. */
 interface EmbedActivityCompleted {
     status: 'completed';
+    /**
+     * The platform run this completion records under. One run ends in at
+     * most one completion (the server dedupes on it), and a resumed launch
+     * keeps the interrupted run's id — so this doubles as the completion's
+     * attempt identity: feed it to whatever consumes the result and drop
+     * anything you have seen before. Absent only for pure UX embeds
+     * (launched without `timeback`), which record nothing.
+     */
+    runId?: string;
     /** Correct answers, from the child's report. */
     correct: number;
     /** Total questions, from the child's report. */
@@ -1938,6 +1948,12 @@ interface EmbedActivityCompleted {
  */
 interface EmbedActivityAbandoned {
     status: 'abandoned';
+    /**
+     * The platform run the launch was recording under, when one had
+     * opened. Absent when the child never started an activity or the
+     * launch was a pure UX embed.
+     */
+    runId?: string;
     timing: EmbedSessionTiming;
     /**
      * The final resume envelope, when the child checkpointed during the
@@ -1959,6 +1975,13 @@ interface EmbedActivityFailed {
 interface EmbedSession {
     /** The mounted child iframe. Useful for focus management. */
     readonly iframe: HTMLIFrameElement;
+    /**
+     * The platform run this launch records under, or null before the run
+     * opens (the child's first activity) and for pure UX embeds. Stable
+     * once set; also echoed on the finished record, which is where most
+     * callers should read it.
+     */
+    readonly runId: string | null;
     /**
      * The latest resume envelope, live during play; null until the child
      * first checkpoints. Read it on your own cadence to persist

package/dist/index.js

@@ -1119,6 +1119,9 @@ class ChildSession {
     this.#abandon();
     this.#teardown();
   }
+  get runId() {
+    return this.#parentRunId;
+  }
   get checkpoint() {
     if (!this.#hasCheckpoint) {
       return null;
@@ -1227,6 +1230,9 @@ class ChildSession {
       status: "abandoned",
       timing: this.#relayedTiming()
     };
+    if (this.#parentRunId) {
+      activity.runId = this.#parentRunId;
+    }
     const resume = this.checkpoint;
     if (resume) {
       activity.resume = resume;
@@ -1251,9 +1257,11 @@ class ChildSession {
     }
     this.#settled = true;
     this.#clearResume();
+    this.#ensureBridgeRun();
     let endMemo = null;
     this.#resolveFinished({
       status: "completed",
+      runId: this.#parentRunId ?? undefined,
       correct: childReport.scoreData.correctQuestions,
       total: childReport.scoreData.totalQuestions,
       timing: this.#completedTiming(childReport),
@@ -3042,6 +3050,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 +3484,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.12";
 
 // 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';
@@ -2977,6 +2977,15 @@ type EmbedActivity = EmbedActivityCompleted | EmbedActivityAbandoned | EmbedActi
 /** The child called `endActivity()` and its report was relayed. */
 interface EmbedActivityCompleted {
     status: 'completed';
+    /**
+     * The platform run this completion records under. One run ends in at
+     * most one completion (the server dedupes on it), and a resumed launch
+     * keeps the interrupted run's id — so this doubles as the completion's
+     * attempt identity: feed it to whatever consumes the result and drop
+     * anything you have seen before. Absent only for pure UX embeds
+     * (launched without `timeback`), which record nothing.
+     */
+    runId?: string;
     /** Correct answers, from the child's report. */
     correct: number;
     /** Total questions, from the child's report. */
@@ -3005,6 +3014,12 @@ interface EmbedActivityCompleted {
  */
 interface EmbedActivityAbandoned {
     status: 'abandoned';
+    /**
+     * The platform run the launch was recording under, when one had
+     * opened. Absent when the child never started an activity or the
+     * launch was a pure UX embed.
+     */
+    runId?: string;
     timing: EmbedSessionTiming;
     /**
      * The final resume envelope, when the child checkpointed during the
@@ -3026,6 +3041,13 @@ interface EmbedActivityFailed {
 interface EmbedSession {
     /** The mounted child iframe. Useful for focus management. */
     readonly iframe: HTMLIFrameElement;
+    /**
+     * The platform run this launch records under, or null before the run
+     * opens (the child's first activity) and for pure UX embeds. Stable
+     * once set; also echoed on the finished record, which is where most
+     * callers should read it.
+     */
+    readonly runId: string | null;
     /**
      * The latest resume envelope, live during play; null until the child
      * first checkpoints. Read it on your own cadence to persist

package/dist/internal.js

@@ -1119,6 +1119,9 @@ class ChildSession {
     this.#abandon();
     this.#teardown();
   }
+  get runId() {
+    return this.#parentRunId;
+  }
   get checkpoint() {
     if (!this.#hasCheckpoint) {
       return null;
@@ -1227,6 +1230,9 @@ class ChildSession {
       status: "abandoned",
       timing: this.#relayedTiming()
     };
+    if (this.#parentRunId) {
+      activity.runId = this.#parentRunId;
+    }
     const resume = this.checkpoint;
     if (resume) {
       activity.resume = resume;
@@ -1251,9 +1257,11 @@ class ChildSession {
     }
     this.#settled = true;
     this.#clearResume();
+    this.#ensureBridgeRun();
     let endMemo = null;
     this.#resolveFinished({
       status: "completed",
+      runId: this.#parentRunId ?? undefined,
       correct: childReport.scoreData.correctQuestions,
       total: childReport.scoreData.totalQuestions,
       timing: this.#completedTiming(childReport),
@@ -3042,6 +3050,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 +4360,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.12";
 
 // 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.12";
 
 // 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.12";
 
 // 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;
@@ -2339,6 +2340,15 @@ type EmbedActivity = EmbedActivityCompleted | EmbedActivityAbandoned | EmbedActi
 /** The child called `endActivity()` and its report was relayed. */
 interface EmbedActivityCompleted {
     status: 'completed';
+    /**
+     * The platform run this completion records under. One run ends in at
+     * most one completion (the server dedupes on it), and a resumed launch
+     * keeps the interrupted run's id — so this doubles as the completion's
+     * attempt identity: feed it to whatever consumes the result and drop
+     * anything you have seen before. Absent only for pure UX embeds
+     * (launched without `timeback`), which record nothing.
+     */
+    runId?: string;
     /** Correct answers, from the child's report. */
     correct: number;
     /** Total questions, from the child's report. */
@@ -2367,6 +2377,12 @@ interface EmbedActivityCompleted {
  */
 interface EmbedActivityAbandoned {
     status: 'abandoned';
+    /**
+     * The platform run the launch was recording under, when one had
+     * opened. Absent when the child never started an activity or the
+     * launch was a pure UX embed.
+     */
+    runId?: string;
     timing: EmbedSessionTiming;
     /**
      * The final resume envelope, when the child checkpointed during the
@@ -2388,6 +2404,13 @@ interface EmbedActivityFailed {
 interface EmbedSession {
     /** The mounted child iframe. Useful for focus management. */
     readonly iframe: HTMLIFrameElement;
+    /**
+     * The platform run this launch records under, or null before the run
+     * opens (the child's first activity) and for pure UX embeds. Stable
+     * once set; also echoed on the finished record, which is where most
+     * callers should read it.
+     */
+    readonly runId: string | null;
     /**
      * The latest resume envelope, live during play; null until the child
      * first checkpoints. Read it on your own cadence to persist

package/package.json

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