@playcademy/sdk 0.18.0 → 0.18.1-beta.2

package/README.md

@@ -1,6 +1,9 @@
 # @playcademy/sdk
 
-TypeScript SDK for building games on the Playcademy platform.
+**TypeScript SDK for building games on the Playcademy platform.**
+
+Use the browser client to connect a game to platform services, or the server client to handle
+authenticated operations in a game backend. Platform tooling uses the separate internal entry point.
 
 ## Overview
 
@@ -21,6 +24,21 @@ The SDK is the interface between your game and the Playcademy platform. It provi
 | `@playcademy/sdk/types`    | Type-only imports                                                                        |
 | `@playcademy/sdk/test`     | Test utilities                                                                           |
 
+## Installation
+
+Install the SDK in your game project:
+
+```bash
+bun add @playcademy/sdk
+```
+
+For Vite-based games, add the development plugin and follow its
+[setup guide](../vite-plugin/README.md):
+
+```bash
+bun add -d @playcademy/vite-plugin
+```
+
 ## Quick Start
 
 ```typescript
@@ -160,8 +178,10 @@ navigation, feedback, and submission independently:
   resume.
 - `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 returned canonical routing snapshot. Each receipt includes the trusted item `score` and
+  `isCorrect` verdict used by Platform to choose that snapshot; authored answers and private routing
+  data remain server-only. `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
@@ -309,9 +329,46 @@ try {
 
 ## Development
 
-In development, the SDK connects to a local sandbox started by `@playcademy/vite-plugin`. The sandbox provides mock auth, a local API, and game asset serving — no platform account needed.
+For SDK contributors working in this monorepo, the primary workflow starts at the repository root:
+
+```bash
+bun dev
+```
+
+This starts the shared platform development environment. Run validation from the root as well:
+
+```bash
+bun run check
+bun run test unit
+```
+
+For game developers consuming the SDK outside the monorepo, run your game's development command
+with `@playcademy/vite-plugin` configured. The plugin starts a local sandbox with mock auth, a local
+API, and game asset serving — no platform account or monorepo checkout is needed.
 
 ```typescript
 // Automatic — vite plugin handles everything
 const client = await PlaycademyClient.init()
 ```
+
+## Dependencies
+
+- Peer dependencies: TypeScript (`^5 || ^6`) and Drizzle ORM (`^0.42.0`), as declared in
+  [package.json](./package.json).
+- Workspace development dependencies include `@playcademy/types`, `@playcademy/constants`,
+  `@playcademy/utils`, and `@playcademy/test-utils`. Contributors install these through the root
+  workspace; game projects do not need to install private workspace packages.
+- `@playcademy/vite-plugin` provides local sandbox integration for Vite games.
+
+## Examples
+
+- [Basic game](../../examples/basic) — browser SDK initialization and platform services.
+- [Full-stack game](../../examples/full-stack) — game backend routes and server-side integration.
+- [TimeBack game](../../examples/timeback) — activity tracking, hosted assessments, and local fixtures.
+
+## Related Packages
+
+- [@playcademy/vite-plugin](../vite-plugin) — Vite integration and local game development.
+- [playcademy](../cli) — CLI for game setup, deployment, and platform operations.
+- [@playcademy/types](../types) — shared platform API contracts.
+- [@playcademy/ui-react](../ui-react) — React assessment rendering and game UI components.

package/dist/index.d.ts

@@ -1555,7 +1555,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         assessments: {
-            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            prepare: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentPreparationResult>;
+            start: (input: _playcademy_types.StartAssessmentInput, options?: _playcademy_types.StartAssessmentOptions) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
             get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             stop: (attemptId: string) => Promise<{

package/dist/index.js

@@ -2780,6 +2780,13 @@ function createScoresNamespace(client) {
     }
   };
 }
+// src/core/timeback/assessment-request.ts
+function canonicalAssessmentInput(input) {
+  const request = { ...input };
+  delete request.preparationReceipt;
+  return request;
+}
+
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -3065,6 +3072,38 @@ function validateAssessmentFilters(options) {
     }
   }
 }
+function validateStartAssessmentInput(input) {
+  if (!input.activityId?.trim()) {
+    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") {
+    return;
+  }
+  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.candidateItemsPerStandard !== undefined && (!Number.isInteger(input.candidateItemsPerStandard) || input.candidateItemsPerStandard <= 0 || input.candidateItemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard)) {
+    throw new Error(`candidateItemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard}`);
+  }
+}
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   const pendingAssessmentSubmissions = new Map;
@@ -3149,38 +3188,18 @@ function createTimebackNamespace(client) {
   registerPauseProbe(client, () => engine.activity.isManuallyPaused());
   return {
     assessments: {
-      start: async (input) => {
+      prepare: async (input) => {
+        assertPlatformMode(client, "timeback.assessments.prepare()");
+        validateStartAssessmentInput(input);
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/prepare`, "POST", canonicalAssessmentInput(input));
+      },
+      start: async (input, options) => {
         assertPlatformMode(client, "timeback.assessments.start()");
-        if (!input.activityId?.trim()) {
-          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");
-          }
-          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.candidateItemsPerStandard !== undefined && (!Number.isInteger(input.candidateItemsPerStandard) || input.candidateItemsPerStandard <= 0 || input.candidateItemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard)) {
-            throw new Error(`candidateItemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard}`);
-          }
-        }
-        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        validateStartAssessmentInput(input);
+        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", {
+          ...canonicalAssessmentInput(input),
+          ...options?.preparationReceipt === undefined ? {} : { preparationReceipt: options.preparationReceipt }
+        });
         return syncAssessmentTracking(snapshot);
       },
       latest: async (options) => {
@@ -3706,7 +3725,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.18.0";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // 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, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, FinalizeAssessmentInput, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, SettledAssessmentAttemptSnapshot, StartAssessmentInput, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult } from '@playcademy/types/timeback';
+export { AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, FinalizeAssessmentInput, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, SettledAssessmentAttemptSnapshot, StartAssessmentInput, StartAssessmentOptions, 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';

package/dist/internal.js

@@ -2780,6 +2780,13 @@ function createScoresNamespace(client) {
     }
   };
 }
+// src/core/timeback/assessment-request.ts
+function canonicalAssessmentInput(input) {
+  const request = { ...input };
+  delete request.preparationReceipt;
+  return request;
+}
+
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -3065,6 +3072,38 @@ function validateAssessmentFilters(options) {
     }
   }
 }
+function validateStartAssessmentInput(input) {
+  if (!input.activityId?.trim()) {
+    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") {
+    return;
+  }
+  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.candidateItemsPerStandard !== undefined && (!Number.isInteger(input.candidateItemsPerStandard) || input.candidateItemsPerStandard <= 0 || input.candidateItemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard)) {
+    throw new Error(`candidateItemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard}`);
+  }
+}
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
   const pendingAssessmentSubmissions = new Map;
@@ -3149,38 +3188,18 @@ function createTimebackNamespace(client) {
   registerPauseProbe(client, () => engine.activity.isManuallyPaused());
   return {
     assessments: {
-      start: async (input) => {
+      prepare: async (input) => {
+        assertPlatformMode(client, "timeback.assessments.prepare()");
+        validateStartAssessmentInput(input);
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/prepare`, "POST", canonicalAssessmentInput(input));
+      },
+      start: async (input, options) => {
         assertPlatformMode(client, "timeback.assessments.start()");
-        if (!input.activityId?.trim()) {
-          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");
-          }
-          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.candidateItemsPerStandard !== undefined && (!Number.isInteger(input.candidateItemsPerStandard) || input.candidateItemsPerStandard <= 0 || input.candidateItemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard)) {
-            throw new Error(`candidateItemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.candidateItemsPerStandard}`);
-          }
-        }
-        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        validateStartAssessmentInput(input);
+        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", {
+          ...canonicalAssessmentInput(input),
+          ...options?.preparationReceipt === undefined ? {} : { preparationReceipt: options.preparationReceipt }
+        });
         return syncAssessmentTracking(snapshot);
       },
       latest: async (options) => {
@@ -4598,7 +4617,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.18.0";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.d.ts

@@ -370,7 +370,8 @@ declare class PlaycademyClient {
     /** TimeBack integration methods (endActivity) */
     timeback: {
         assessments: {
-            start: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            prepare: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentPreparationResult>;
+            start: (studentId: string, input: _playcademy_types.StartAssessmentInput, options?: _playcademy_types.StartAssessmentOptions) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             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>;

package/dist/server/edge.js

@@ -10,6 +10,13 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
+// src/core/timeback/assessment-request.ts
+function canonicalAssessmentInput(input) {
+  const request = { ...input };
+  delete request.preparationReceipt;
+  return request;
+}
+
 // ../constants/src/auth.ts
 var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
   games: ["read", "write", "delete"],
@@ -86,7 +93,13 @@ function createTimebackNamespace(client) {
   }
   return {
     assessments: {
-      start: (studentId, input) => client["request"]("/api/timeback/assessments/start", "POST", { ...input, gameId: client.gameId, studentId }),
+      prepare: (studentId, input) => client["request"]("/api/timeback/assessments/prepare", "POST", { ...canonicalAssessmentInput(input), gameId: client.gameId, studentId }),
+      start: (studentId, input, options) => client["request"]("/api/timeback/assessments/start", "POST", {
+        ...canonicalAssessmentInput(input),
+        ...options?.preparationReceipt === undefined ? {} : { preparationReceipt: options.preparationReceipt },
+        gameId: client.gameId,
+        studentId
+      }),
       latest: (studentId, options) => {
         const params = new URLSearchParams({
           gameId: client.gameId,
@@ -322,7 +335,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.18.0";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -370,7 +370,8 @@ declare class PlaycademyClient$1 {
     /** TimeBack integration methods (endActivity) */
     timeback: {
         assessments: {
-            start: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            prepare: (studentId: string, input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentPreparationResult>;
+            start: (studentId: string, input: _playcademy_types.StartAssessmentInput, options?: _playcademy_types.StartAssessmentOptions) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             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>;

package/dist/server.js

@@ -199,6 +199,13 @@ var init_config_loader = __esm(() => {
   init_file_loader();
 });
 
+// src/core/timeback/assessment-request.ts
+function canonicalAssessmentInput(input) {
+  const request = { ...input };
+  delete request.preparationReceipt;
+  return request;
+}
+
 // ../constants/src/auth.ts
 var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
   games: ["read", "write", "delete"],
@@ -275,7 +282,13 @@ function createTimebackNamespace(client) {
   }
   return {
     assessments: {
-      start: (studentId, input) => client["request"]("/api/timeback/assessments/start", "POST", { ...input, gameId: client.gameId, studentId }),
+      prepare: (studentId, input) => client["request"]("/api/timeback/assessments/prepare", "POST", { ...canonicalAssessmentInput(input), gameId: client.gameId, studentId }),
+      start: (studentId, input, options) => client["request"]("/api/timeback/assessments/start", "POST", {
+        ...canonicalAssessmentInput(input),
+        ...options?.preparationReceipt === undefined ? {} : { preparationReceipt: options.preparationReceipt },
+        gameId: client.gameId,
+        studentId
+      }),
       latest: (studentId, options) => {
         const params = new URLSearchParams({
           gameId: client.gameId,
@@ -511,7 +524,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.18.0";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // 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, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, FinalizeAssessmentInput, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, SettledAssessmentAttemptSnapshot, StartAssessmentInput, StartDiagnosticAssessmentInput, SubmitAssessmentInput, SubmitAssessmentItemInput, SubmitAssessmentItemResult, SubmitDiagnosticAssessmentItemInput, SubmitDiagnosticAssessmentItemResult } from '@playcademy/types/timeback';
+export { AssessmentAttemptSnapshot, AssessmentAwardRecord, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemGrading, AssessmentItemSubmission, AssessmentMasteryAward, AssessmentPreparationResult, AssessmentResponseUpdate, AssessmentResponseValue, AssessmentResponses, AssessmentSaveResult, AssessmentScore, AssessmentStandardRef, AssessmentSubmitResult, ConventionalAssessmentAttemptSnapshot, ConventionalAssessmentSubmitResult, DiagnosticAssessmentItemReceipt, DiagnosticAssessmentSubmitResult, DiagnosticRoutingSnapshot, DiagnosticRoutingTrackSnapshot, ELevel, FinalizeAssessmentInput, PlatformRoutedDiagnosticAttemptSnapshot, PlatformRoutedDiagnosticSelectionContext, PlayableAssessment, PlayableAssessmentAttemptSnapshot, PlayableAssessmentChoice, PlayableAssessmentGraphic, PlayableAssessmentHotspot, PlayableAssessmentInteraction, PlayableAssessmentItem, PlayableContentNode, SaveAssessmentInput, SettledAssessmentAttemptSnapshot, StartAssessmentInput, StartAssessmentOptions, 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';
@@ -2011,7 +2011,8 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         assessments: {
-            start: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
+            prepare: (input: _playcademy_types.StartAssessmentInput) => Promise<_playcademy_types.AssessmentPreparationResult>;
+            start: (input: _playcademy_types.StartAssessmentInput, options?: _playcademy_types.StartAssessmentOptions) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             latest: (options: _playcademy_types.GetLatestAssessmentOptions) => Promise<_playcademy_types.LatestAssessmentResult | null>;
             get: (attemptId: string) => Promise<_playcademy_types.AssessmentAttemptSnapshot>;
             stop: (attemptId: string) => Promise<{

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.18.0",
+    "version": "0.18.1-beta.2",
     "type": "module",
     "exports": {
         ".": {