@playcademy/sdk 0.18.1-beta.1 → 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.js

@@ -3725,7 +3725,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.18.1-beta.1";
+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, 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';
+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

@@ -4617,7 +4617,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.18.1-beta.1";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.js

@@ -335,7 +335,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.18.1-beta.1";
+var SDK_VERSION = "0.18.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.js

@@ -524,7 +524,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.18.1-beta.1";
+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, 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';
+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';

package/package.json

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