@playcademy/sdk 0.16.1-beta.9 → 0.17.0

package/README.md

@@ -122,21 +122,25 @@ Hosted assessments use the same methods locally and when deployed:
 const attempt = await client.timeback.assessments.start({
     activityId: 'math-diagnostic',
     purpose: 'diagnostic',
+    diagnosticKey: 'math.grade-5-placement',
     subject: 'Math',
     grade: 5,
 })
 
-const saved = await client.timeback.assessments.save(attempt.attemptId, {
-    expectedResponseVersion: attempt.responseVersion,
-    responses: {
-        [attempt.assessment.items[0].identifier]: { RESPONSE: 'A' },
-    },
-})
+if (attempt.flow !== 'platform-routed-item-submit' || !attempt.routing.next) {
+    throw new Error('Expected an active routed diagnostic')
+}
 
-const completed = await client.timeback.assessments.submit(attempt.attemptId, {
-    expectedResponseVersion: saved.responseVersion,
+const current = attempt.routing.next
+const committed = await client.timeback.assessments.submitItem(attempt.attemptId, {
+    expectedResponseVersion: attempt.responseVersion,
     submissionId: crypto.randomUUID(),
+    routingNodeKey: current.nodeKey,
+    itemIdentifier: current.itemIdentifier,
+    responses: { RESPONSE: 'A' },
 })
+
+// Repeat with committed.routing.next. When routing is ready, submit() only finalizes.
 ```
 
 `start()` resumes a compatible unfinished attempt or selects content for a fixed test or standards
@@ -144,6 +148,25 @@ 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 the selected assessment; callers do not configure
+navigation, feedback, and submission independently:
+
+- `attempt-submit` is used for end-of-course and mastery attempts. Responses remain editable
+  through `save()` until `submit()` finalizes the whole attempt and returns feedback.
+- `item-submit` is used for review attempts. Submit each administered item 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.
+- `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 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
+manifest contract; game code never selects the provider.
+
 For local development, import the current ordered catalog before starting the dev host:
 
 ```bash

package/dist/contracts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The child-catalog contract: what a child game publishes about its
+ * deliverable lessons, per lesson id and level. A parent course authority
+ * resolves its lesson references against this document at compile time and
+ * fails closed at runtime on anything not `ready` in production.
+ *
+ * Ownership and flow: each child repo generates `.playcademy/catalog.json`
+ * from its own registry (`playcademy catalog generate`); a sync workflow
+ * carries copies into parent repos. Children never read the parent's
+ * compiled authority — this file and the launch payload are the entire
+ * surface between them.
+ *
+ * The document deliberately carries no app identity. The consuming repo
+ * assigns the namespace key (e.g. 'form', 'math-cakes') from sync
+ * provenance via its own repo → app map, so a child cannot misdeclare
+ * who it is and a typo cannot mint a phantom namespace.
+ */
+/** Contract identifier carried by every catalog document. */
+declare const CHILD_CATALOG_CONTRACT: 'playcademy-child-catalog-v1';
+/** The completion-evidence contract a catalog declares its runs report. */
+declare const CHILD_ATTEMPT_CONTRACT: 'playcademy-child-attempt-v1';
+/** Delivery levels a catalog may declare (serving-id dialect, lowercase). */
+declare const CATALOG_LEVELS: readonly ['e1', 'e2', 'e3', 'e4'];
+type CatalogLevel = (typeof CATALOG_LEVELS)[number];
+/**
+ * ready: real content. simulated: placeholder — playable for preview and
+ * simulation, never creditable in production. unavailable: intentionally
+ * absent at this level. Consumers must treat unknown values and missing
+ * levels as unavailable (fail closed).
+ */
+declare const CATALOG_READINESS: readonly ['ready', 'simulated', 'unavailable'];
+type CatalogReadiness = (typeof CATALOG_READINESS)[number];
+interface ChildCatalog {
+    /** The contract identifier. */
+    contract: typeof CHILD_CATALOG_CONTRACT;
+    /** The completion-evidence contract a catalog declares its runs report. */
+    evidence: typeof CHILD_ATTEMPT_CONTRACT;
+    /** The tool that generated this document (repo-relative path). */
+    generatedBy: string;
+    /** The in-repo source of truth the document was derived from. */
+    generatedFrom: string;
+    /** Lesson id → level → readiness. */
+    deliveries: Record<string, Partial<Record<CatalogLevel, CatalogReadiness>>>;
+}
+
+export { CATALOG_LEVELS, CATALOG_READINESS, CHILD_ATTEMPT_CONTRACT, CHILD_CATALOG_CONTRACT };
+export type { CatalogLevel, CatalogReadiness, ChildCatalog };

package/dist/contracts.js

@@ -0,0 +1,23 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/contracts/child-catalog.ts
+var CHILD_CATALOG_CONTRACT = "playcademy-child-catalog-v1";
+var CHILD_ATTEMPT_CONTRACT = "playcademy-child-attempt-v1";
+var CATALOG_LEVELS = ["e1", "e2", "e3", "e4"];
+var CATALOG_READINESS = ["ready", "simulated", "unavailable"];
+export {
+  CHILD_CATALOG_CONTRACT,
+  CHILD_ATTEMPT_CONTRACT,
+  CATALOG_READINESS,
+  CATALOG_LEVELS
+};

package/dist/index.d.ts

@@ -1558,7 +1558,11 @@ 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>;
         };
         readonly user: TimebackUser;
@@ -1910,6 +1914,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 +1951,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 +1978,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