@playcademy/sdk 0.16.1-beta.9 → 0.17.1-beta.1

package/dist/server/edge.d.ts

@@ -142,6 +142,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -174,6 +187,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -359,9 +374,13 @@ 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>;
-            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+            submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentRequest, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;
+            finalize: (studentId: string, attemptId: string, input: _playcademy_types.FinalizeAssessmentInput, context: {
+                sensorUrl: string;
+            }) => Promise<_playcademy_types.AssessmentFinalizeResult>;
         };
         endActivity: (studentId: string, payload: _playcademy_types.EndActivityPayload) => Promise<_playcademy_types.EndActivityResponse>;
         getStudentXp: (studentId: string, options?: {

package/dist/server/edge.js

@@ -18,6 +18,8 @@ var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
 };
 // ../constants/src/platform.ts
 var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
+var PLAYCADEMY_ASSESSMENT_ASSET_SHA256_HEADER = "x-playcademy-content-sha256";
+var ASSESSMENT_ASSET_MAX_BYTES = 4 * 1024 * 1024;
 // ../constants/src/timeback.ts
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
@@ -44,7 +46,7 @@ var TIMEBACK_SUBJECTS = [
 var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
 var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
   standards: 20,
-  itemsPerStandard: 5,
+  candidateItemsPerStandard: 2,
   standardFieldLength: 128
 };
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
@@ -108,12 +110,20 @@ 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,
         studentId,
         appName: client.config.name,
         sensorUrl: context.sensorUrl
+      }),
+      finalize: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/finalize`, "POST", {
+        ...input,
+        gameId: client.gameId,
+        studentId,
+        appName: client.config.name,
+        sensorUrl: context.sensorUrl
       })
     },
     endActivity: async (studentId, payload) => {
@@ -312,7 +322,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.9";
+var SDK_VERSION = "0.17.1-beta.1";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.d.ts

@@ -142,6 +142,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -174,6 +187,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -359,9 +374,13 @@ 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>;
-            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentInput, context: {
+            submitItem: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentItemInput) => Promise<_playcademy_types.SubmitAssessmentItemResult>;
+            submit: (studentId: string, attemptId: string, input: _playcademy_types.SubmitAssessmentRequest, context: {
                 sensorUrl: string;
             }) => Promise<_playcademy_types.AssessmentSubmitResult>;
+            finalize: (studentId: string, attemptId: string, input: _playcademy_types.FinalizeAssessmentInput, context: {
+                sensorUrl: string;
+            }) => Promise<_playcademy_types.AssessmentFinalizeResult>;
         };
         endActivity: (studentId: string, payload: _playcademy_types.EndActivityPayload) => Promise<_playcademy_types.EndActivityResponse>;
         getStudentXp: (studentId: string, options?: {

package/dist/server.js

@@ -207,6 +207,8 @@ var DEFAULT_PERSONAL_API_KEY_PERMISSIONS = {
 };
 // ../constants/src/platform.ts
 var PLAYCADEMY_BROWSER_TIME_ZONE_HEADER = "x-playcademy-browser-time-zone";
+var PLAYCADEMY_ASSESSMENT_ASSET_SHA256_HEADER = "x-playcademy-content-sha256";
+var ASSESSMENT_ASSET_MAX_BYTES = 4 * 1024 * 1024;
 // ../constants/src/timeback.ts
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
@@ -233,7 +235,7 @@ var TIMEBACK_SUBJECTS = [
 var ASSESSMENT_PURPOSES = ["end_of_course", "diagnostic", "review", "mastery"];
 var TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS = {
   standards: 20,
-  itemsPerStandard: 5,
+  candidateItemsPerStandard: 2,
   standardFieldLength: 128
 };
 var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
@@ -297,12 +299,20 @@ 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,
         studentId,
         appName: client.config.name,
         sensorUrl: context.sensorUrl
+      }),
+      finalize: (studentId, attemptId, input, context) => client["request"](`/api/timeback/assessments/${encodeURIComponent(attemptId)}/finalize`, "POST", {
+        ...input,
+        gameId: client.gameId,
+        studentId,
+        appName: client.config.name,
+        sensorUrl: context.sensorUrl
       })
     },
     endActivity: async (studentId, payload) => {
@@ -501,7 +511,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.9";
+var SDK_VERSION = "0.17.1-beta.1";
 
 // 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, AssessmentFinalizeResult, AssessmentFlow, AssessmentItemSubmission, 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';
 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';
@@ -363,6 +363,19 @@ interface DashboardThemeConfig {
     /** Secondary/accent color as a hex string, e.g. '#ffd166' */
     secondary?: string;
 }
+/**
+ * Child-catalog contract generation (see @playcademy/sdk/contracts).
+ * The extractor is a repo-local script (run with the CLI's runtime) that
+ * prints `{ generatedFrom, deliveries }` as JSON on stdout; the CLI
+ * validates, stamps the contract fields, and writes
+ * `.playcademy/catalog.json` deterministically. The document carries no
+ * app identity — consuming repos assign the namespace key from sync
+ * provenance.
+ */
+interface CatalogConfig {
+    /** Path to the extractor script, relative to the config file. */
+    extractor: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -395,6 +408,8 @@ interface PlaycademyConfig {
     dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
+    /** Child-catalog contract generation (`playcademy catalog`) */
+    catalog?: CatalogConfig;
 }
 
 /**
@@ -1999,8 +2014,13 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
             start: (input: _playcademy_types.StartAssessmentInput) => 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<{
+                attemptId: string;
+            }>;
             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>;
+            finalize: (attemptId: string, input: _playcademy_types.FinalizeAssessmentInput) => Promise<_playcademy_types.AssessmentFinalizeResult>;
         };
         readonly user: TimebackUser;
         readonly currentRunId: string | undefined;
@@ -2339,6 +2359,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 +2396,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 +2423,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.9",
+    "version": "0.17.1-beta.1",
     "type": "module",
     "exports": {
         ".": {
@@ -21,6 +21,12 @@
             "import": "./dist/types.js",
             "require": "./dist/types.js"
         },
+        "./contracts": {
+            "source": "./src/contracts.ts",
+            "types": "./dist/contracts.d.ts",
+            "import": "./dist/contracts.js",
+            "require": "./dist/contracts.js"
+        },
         "./internal": {
             "source": "./src/internal.ts",
             "types": "./dist/internal.d.ts",