@playcademy/sdk 0.16.1-beta.9 → 0.17.0

package/dist/index.js

@@ -800,6 +800,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",
@@ -826,7 +828,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"];
@@ -1119,6 +1121,9 @@ class ChildSession {
     this.#abandon();
     this.#teardown();
   }
+  get runId() {
+    return this.#parentRunId;
+  }
   get checkpoint() {
     if (!this.#hasCheckpoint) {
       return null;
@@ -1203,8 +1208,11 @@ class ChildSession {
     }
     this.#markOpenWindowFlushable();
     this.#forwardDirtyWindows();
-    window.removeEventListener("message", this.#onChildMessage);
-    window.removeEventListener("pagehide", this.#onPageHide);
+    const win = globalThis.window;
+    if (win) {
+      win.removeEventListener("message", this.#onChildMessage);
+      win.removeEventListener("pagehide", this.#onPageHide);
+    }
     messaging.unlisten("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, this.#onTokenRefresh);
     messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, this.#onLauncherPause);
     messaging.unlisten("PLAYCADEMY_RESUME" /* RESUME */, this.#onLauncherResume);
@@ -1227,6 +1235,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 +1262,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),
@@ -1722,6 +1735,29 @@ function createTimebackActivityTracker(client) {
     const resumeRunId = client["initPayload"]?.parent?.resumeRunId;
     return typeof resumeRunId === "string" && isValidUUID(resumeRunId) ? resumeRunId : undefined;
   }
+  function clockAvailability(owner) {
+    if (owner.kind === "assessment" && currentActivity?.owner.kind === "assessment" && currentActivity.owner.attemptId === owner.attemptId) {
+      return "held-by-this-owner";
+    }
+    if (hasLiveSession(client)) {
+      return { unavailable: "embedded-child" };
+    }
+    if (!currentActivity) {
+      return "available";
+    }
+    if (owner.kind === "activity") {
+      return currentActivity.owner.kind === "assessment" ? {
+        unavailable: "other-assessment",
+        runId: currentActivity.runId,
+        attemptId: currentActivity.owner.attemptId
+      } : "available";
+    }
+    return currentActivity.owner.kind === "assessment" ? {
+      unavailable: "other-assessment",
+      runId: currentActivity.runId,
+      attemptId: currentActivity.owner.attemptId
+    } : { unavailable: "ordinary-activity", runId: currentActivity.runId };
+  }
   function startHeartbeatInterval(activity) {
     if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
       return;
@@ -2033,6 +2069,110 @@ function createTimebackActivityTracker(client) {
     }
     stopRelayInterval();
   }
+  async function finishCurrentActivity(discardRelayedTiming) {
+    const activity = currentActivity;
+    if (activity.finishInFlight) {
+      return activity.finishInFlight;
+    }
+    activity.finishInFlight = (async () => {
+      applyOverdueInactivity();
+      cleanupListeners();
+      const relayedWithoutReconciliation = discardRelayedTiming && relaysToParent();
+      await flushHeartbeat(true);
+      if (activity.pauseStartTime !== null) {
+        activity.pausedTime += Date.now() - activity.pauseStartTime;
+        activity.pauseStartTime = null;
+      }
+      const endTime = Date.now();
+      const totalElapsed = endTime - activity.startTime;
+      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
+      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
+      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
+      if (currentActivity === activity) {
+        currentActivity = null;
+      }
+      return {
+        runId: activity.runId,
+        resumeId: activity.resumeId,
+        activityData: activity.metadata,
+        durationSeconds: Math.floor(activeTime / 1000),
+        sessionTimingData: relayedWithoutReconciliation ? { activeSeconds: 0 } : {
+          activeSeconds: unreportedActiveMs / 1000,
+          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+        }
+      };
+    })();
+    return activity.finishInFlight;
+  }
+  function assertValidRunId(options) {
+    if (options?.runId !== undefined && !isValidUUID(options.runId)) {
+      throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+    }
+  }
+  function beginActivity(rawMetadata, options, owner) {
+    const metadata = jsonProjection(rawMetadata);
+    cleanupListeners();
+    const now = Date.now();
+    const runId = owner.kind === "assessment" ? owner.attemptId : options?.runId ?? adoptResumedRunId() ?? crypto.randomUUID();
+    const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
+    const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
+    const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
+    currentActivity = {
+      runId,
+      resumeId: crypto.randomUUID(),
+      owner,
+      startTime: now,
+      metadata,
+      pausedTime: 0,
+      pauseStartTime: null,
+      pauseReasons: new Set,
+      pausedHeartbeatTimeoutId: null,
+      pausedHeartbeatTimedOut: false,
+      pausedHeartbeatTimeoutMs,
+      windowStartTime: now,
+      windowPausedAtStart: 0,
+      heartbeatIntervalId: null,
+      heartbeatIntervalMs,
+      inactivityTimeoutId: null,
+      inactivityTimeoutMs,
+      inactivityTimerStartedAt: null,
+      remainingInactivityMs: inactivityTimeoutMs,
+      flushInFlight: null,
+      finishInFlight: null,
+      totalPersistedActiveMs: 0,
+      totalPersistedPausedMs: 0
+    };
+    if (typeof document !== "undefined") {
+      boundVisibilityHandler = handleVisibilityChange;
+      document.addEventListener("visibilitychange", boundVisibilityHandler);
+      boundUserInteractionHandler = handleUserInteraction;
+      for (const eventName of USER_ACTIVITY_EVENTS) {
+        document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+      }
+      if (document.visibilityState === "hidden") {
+        handleVisibilityChange();
+      }
+    }
+    startHeartbeatInterval(currentActivity);
+    startRelayInterval();
+    if (typeof globalThis.window !== "undefined") {
+      boundPageHideHandler = handlePageHide;
+      globalThis.window.addEventListener("pagehide", boundPageHideHandler);
+    }
+    boundShellPauseHandler = handleShellPause;
+    boundShellResumeHandler = handleShellResume;
+    messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
+    messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+    syncInactivityTracking();
+    if (relaysToParent()) {
+      messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
+        runId,
+        resumeId: currentActivity.resumeId,
+        activityData: metadata
+      });
+    }
+    return { runId };
+  }
   return {
     currentRunId() {
       return currentActivity?.runId;
@@ -2040,74 +2180,40 @@ function createTimebackActivityTracker(client) {
     isActivityManuallyPaused() {
       return currentActivity?.pauseReasons.has("manual") ?? false;
     },
-    startActivity(rawMetadata, options) {
-      if (hasLiveSession(client)) {
+    startActivity(rawMetadata, options, owner = { kind: "activity" }) {
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object" && availability.unavailable === "embedded-child") {
         throw new PlaycademyError("startActivity() is unavailable while an embedded child session is live: the child owns the clock, and a second clock would double-count the lesson. Await the session's finished (or close() it) first.");
       }
-      if (options?.runId !== undefined && !isValidUUID(options.runId)) {
-        throw new Error(`startActivity: \`runId\` must be a UUID (received \`${JSON.stringify(options.runId)}\`). Use crypto.randomUUID() or persist a previously-generated UUID.`);
+      assertValidRunId(options);
+      if (availability === "held-by-this-owner") {
+        return { runId: currentActivity.runId };
       }
-      const metadata = jsonProjection(rawMetadata);
-      cleanupListeners();
-      const now = Date.now();
-      const resumedRunId = adoptResumedRunId();
-      const runId = options?.runId ?? resumedRunId ?? crypto.randomUUID();
-      const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
-      const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
-      const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
-      currentActivity = {
-        runId,
-        resumeId: crypto.randomUUID(),
-        startTime: now,
-        metadata,
-        pausedTime: 0,
-        pauseStartTime: null,
-        pauseReasons: new Set,
-        pausedHeartbeatTimeoutId: null,
-        pausedHeartbeatTimedOut: false,
-        pausedHeartbeatTimeoutMs,
-        windowStartTime: now,
-        windowPausedAtStart: 0,
-        heartbeatIntervalId: null,
-        heartbeatIntervalMs,
-        inactivityTimeoutId: null,
-        inactivityTimeoutMs,
-        inactivityTimerStartedAt: null,
-        remainingInactivityMs: inactivityTimeoutMs,
-        flushInFlight: null,
-        totalPersistedActiveMs: 0,
-        totalPersistedPausedMs: 0
-      };
-      if (typeof document !== "undefined") {
-        boundVisibilityHandler = handleVisibilityChange;
-        document.addEventListener("visibilitychange", boundVisibilityHandler);
-        boundUserInteractionHandler = handleUserInteraction;
-        for (const eventName of USER_ACTIVITY_EVENTS) {
-          document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
-        }
-        if (document.visibilityState === "hidden") {
-          handleVisibilityChange();
+      if (typeof availability === "object") {
+        if (owner.kind === "assessment") {
+          throw new Error(`Cannot track assessment ${owner.attemptId} while activity run ${availability.runId} is active. End the current activity first.`);
         }
+        const blockingAssessment = availability;
+        throw new Error(`Cannot start an activity while assessment ${blockingAssessment.attemptId} is in progress. Submit the assessment first.`);
       }
-      startHeartbeatInterval(currentActivity);
-      startRelayInterval();
-      if (typeof globalThis.window !== "undefined") {
-        boundPageHideHandler = handlePageHide;
-        globalThis.window.addEventListener("pagehide", boundPageHideHandler);
-      }
-      boundShellPauseHandler = handleShellPause;
-      boundShellResumeHandler = handleShellResume;
-      messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
-      messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
-      syncInactivityTracking();
-      if (relaysToParent()) {
-        messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_START" /* TIMEBACK_ACTIVITY_START */, {
-          runId,
-          resumeId: currentActivity.resumeId,
-          activityData: metadata
-        });
+      return beginActivity(rawMetadata, options, owner);
+    },
+    tryStartAssessmentTracking(metadata, attemptId) {
+      if (!isValidUUID(attemptId)) {
+        return { status: "untrackable", reason: "invalid-attempt-id" };
+      }
+      const owner = { kind: "assessment", attemptId };
+      const availability = clockAvailability(owner);
+      if (typeof availability === "object") {
+        return { status: "unavailable", reason: availability.unavailable };
       }
-      return { runId };
+      if (availability === "held-by-this-owner") {
+        return { status: "already-attached", runId: currentActivity.runId };
+      }
+      return {
+        status: "attached",
+        runId: beginActivity(metadata, { runId: attemptId }, owner).runId
+      };
     },
     pauseActivity() {
       if (!currentActivity) {
@@ -2130,47 +2236,40 @@ function createTimebackActivityTracker(client) {
       }
       removePauseReason("manual");
     },
+    async finishAssessmentTracking(expectedAttemptId) {
+      if (!currentActivity || currentActivity.owner.kind !== "assessment" || currentActivity.owner.attemptId !== expectedAttemptId) {
+        return;
+      }
+      return finishCurrentActivity(true);
+    },
     async endActivity(rawData) {
       if (!currentActivity) {
         throw new Error("No activity in progress. Call startActivity() before endActivity().");
       }
+      if (currentActivity.owner.kind === "assessment") {
+        throw new Error(`endActivity() cannot finalize assessment ${currentActivity.owner.attemptId}. Submit it with timeback.assessments.submit() instead.`);
+      }
       const data = jsonProjection(rawData);
       if (!relaysToParent() && typeof data.xpAwarded !== "number") {
         throw new Error("endActivity() requires xpAwarded when reporting directly. It is optional only in child mode, where the parent game decides the award.");
       }
-      const activity = currentActivity;
-      applyOverdueInactivity();
-      cleanupListeners();
-      await flushHeartbeat(true);
-      if (activity.pauseStartTime !== null) {
-        activity.pausedTime += Date.now() - activity.pauseStartTime;
-        activity.pauseStartTime = null;
-      }
-      const endTime = Date.now();
-      const totalElapsed = endTime - activity.startTime;
-      const activeTime = Math.max(0, totalElapsed - activity.pausedTime);
-      const durationSeconds = Math.floor(activeTime / 1000);
-      const unreportedActiveMs = Math.max(0, activeTime - activity.totalPersistedActiveMs);
-      const unreportedPausedMs = Math.max(0, activity.pausedTime - activity.totalPersistedPausedMs);
       const { correctQuestions, totalQuestions } = data;
       if (data.masteredUnits !== undefined && data.masteredUnitsAbsolute !== undefined) {
         throw new Error("Cannot provide both masteredUnits and masteredUnitsAbsolute — use one or the other");
       }
+      const tracking = await finishCurrentActivity(false);
       const request = {
-        runId: activity.runId,
-        resumeId: activity.resumeId,
-        activityData: activity.metadata,
+        runId: tracking.runId,
+        resumeId: tracking.resumeId,
+        activityData: tracking.activityData,
         scoreData: {
           correctQuestions,
           totalQuestions
         },
         timingData: {
-          durationSeconds
-        },
-        sessionTimingData: {
-          activeSeconds: unreportedActiveMs / 1000,
-          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+          durationSeconds: tracking.durationSeconds
         },
+        sessionTimingData: tracking.sessionTimingData,
         xpEarned: data.xpAwarded,
         masteredUnits: data.masteredUnits,
         masteredUnitsAbsolute: data.masteredUnitsAbsolute,
@@ -2178,23 +2277,9 @@ function createTimebackActivityTracker(client) {
       };
       if (relaysToParent()) {
         messaging.send("PLAYCADEMY_TIMEBACK_ACTIVITY_END" /* TIMEBACK_ACTIVITY_END */, request);
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return { status: "relayed", runId: activity.runId };
-      }
-      try {
-        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        return response;
-      } catch (error) {
-        if (currentActivity === activity) {
-          currentActivity = null;
-        }
-        throw error;
+        return { status: "relayed", runId: tracking.runId };
       }
+      return client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request, undefined, { retryPolicy: END_ACTIVITY_RETRY_POLICY });
     }
   };
 }
@@ -2927,8 +3012,10 @@ function createTimebackEngine(client) {
       currentRunId: activityTracker.currentRunId,
       isManuallyPaused: activityTracker.isActivityManuallyPaused,
       start: activityTracker.startActivity,
+      tryStartAssessment: activityTracker.tryStartAssessmentTracking,
       pause: activityTracker.pauseActivity,
       resume: activityTracker.resumeActivity,
+      finishAssessment: activityTracker.finishAssessmentTracking,
       end: activityTracker.endActivity
     },
     course: {
@@ -2955,6 +3042,7 @@ function createTimebackEngine(client) {
 var VALID_XP_INCLUDE_OPTIONS = ["perCourse", "today"];
 var VALID_MASTERY_INCLUDE_OPTIONS = ["perCourse"];
 var ASSESSMENTS_ROUTE = TIMEBACK_ROUTES.ASSESSMENTS;
+var ASSESSMENT_SUBMIT_RETRY_POLICY = END_ACTIVITY_RETRY_POLICY;
 function validateAssessmentFilters(options) {
   if (!isAssessmentPurpose(options?.purpose)) {
     throw new Error("purpose must be end_of_course, diagnostic, review, or mastery");
@@ -2979,6 +3067,85 @@ function validateAssessmentFilters(options) {
 }
 function createTimebackNamespace(client) {
   const engine = createTimebackEngine(client);
+  const pendingAssessmentSubmissions = new Map;
+  const warnedAssessmentTrackingSkips = new Map;
+  function clearAssessmentTrackingWarnings(attemptId) {
+    warnedAssessmentTrackingSkips.delete(attemptId);
+  }
+  function warnAssessmentTrackingSkipped(attemptId, reason) {
+    const warnedReasons = warnedAssessmentTrackingSkips.get(attemptId) ?? new Set;
+    if (warnedReasons.has(reason)) {
+      return;
+    }
+    warnedReasons.add(reason);
+    warnedAssessmentTrackingSkips.set(attemptId, warnedReasons);
+    const remedy = reason === "invalid-attempt-id" ? "The canonical attempt remains usable and submittable, but this sitting cannot be timed. Report the malformed id." : "The canonical attempt remains available; release the current clock owner, then call timeback.assessments.get(attemptId) to retry tracking.";
+    console.warn(`[Playcademy SDK] timeback.assessments: active-time tracking was not attached to assessment ${attemptId} (${reason}). ${remedy}`);
+  }
+  function releasePendingSubmission(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId === submissionId) {
+      pendingAssessmentSubmissions.delete(attemptId);
+    }
+  }
+  function loadAttemptSnapshot(attemptId) {
+    return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+  }
+  async function syncAssessmentTracking(snapshot) {
+    if (pendingAssessmentSubmissions.has(snapshot.attemptId)) {
+      return snapshot;
+    }
+    if (snapshot.status === "completed") {
+      await engine.activity.finishAssessment(snapshot.attemptId);
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+      return snapshot;
+    }
+    if (!snapshot.activityData) {
+      return snapshot;
+    }
+    const attachment = engine.activity.tryStartAssessment(snapshot.activityData, snapshot.attemptId);
+    if (attachment.status === "unavailable" || attachment.status === "untrackable") {
+      warnAssessmentTrackingSkipped(snapshot.attemptId, attachment.reason);
+    } else {
+      clearAssessmentTrackingWarnings(snapshot.attemptId);
+    }
+    return snapshot;
+  }
+  async function resumeAfterDefinitiveFailure(attemptId, submissionId) {
+    if (pendingAssessmentSubmissions.get(attemptId)?.submissionId !== submissionId) {
+      return;
+    }
+    pendingAssessmentSubmissions.delete(attemptId);
+    try {
+      await syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+    } catch {}
+  }
+  async function assessmentSubmissionContext(attemptId, submissionId) {
+    const pending = pendingAssessmentSubmissions.get(attemptId);
+    if (pending) {
+      if (pending.submissionId !== submissionId && !pending.detached) {
+        throw new Error(`Assessment ${attemptId} already has a pending submission. Retry with the original submissionId.`);
+      }
+      pending.detached = false;
+      return {
+        submissionId: pending.submissionId,
+        session: await pending.session
+      };
+    }
+    const session = engine.activity.finishAssessment(attemptId).then((finished) => finished ? {
+      runId: finished.runId,
+      resumeId: finished.resumeId,
+      ...finished.sessionTimingData
+    } : undefined).catch((error) => {
+      releasePendingSubmission(attemptId, submissionId);
+      throw error;
+    });
+    pendingAssessmentSubmissions.set(attemptId, {
+      submissionId,
+      session,
+      detached: false
+    });
+    return { submissionId, session: await session };
+  }
   registerPauseProbe(client, () => engine.activity.isManuallyPaused());
   return {
     assessments: {
@@ -2988,6 +3155,12 @@ function createTimebackNamespace(client) {
           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");
@@ -3003,11 +3176,12 @@ function createTimebackNamespace(client) {
               throw new Error(`review standard fields must be at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.standardFieldLength} characters`);
             }
           }
-          if (input.itemsPerStandard !== undefined && (!Number.isInteger(input.itemsPerStandard) || input.itemsPerStandard <= 0 || input.itemsPerStandard > TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard)) {
-            throw new Error(`itemsPerStandard must be a positive integer at most ${TIMEBACK_ASSESSMENT_REVIEW_REQUEST_LIMITS.itemsPerStandard}`);
+          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}`);
           }
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        const snapshot = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/start`, "POST", input);
+        return syncAssessmentTracking(snapshot);
       },
       latest: async (options) => {
         assertPlatformMode(client, "timeback.assessments.latest()");
@@ -3030,7 +3204,20 @@ function createTimebackNamespace(client) {
         if (!attemptId?.trim()) {
           throw new Error("attemptId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}`, "GET");
+        return syncAssessmentTracking(await loadAttemptSnapshot(attemptId));
+      },
+      stop: async (attemptId) => {
+        assertPlatformMode(client, "timeback.assessments.stop()");
+        if (!attemptId?.trim()) {
+          throw new Error("attemptId is required");
+        }
+        const pending = pendingAssessmentSubmissions.get(attemptId);
+        if (pending) {
+          pending.detached = true;
+        }
+        await engine.activity.finishAssessment(attemptId);
+        clearAssessmentTrackingWarnings(attemptId);
+        return { attemptId };
       },
       save: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.save()");
@@ -3042,6 +3229,25 @@ 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");
+        }
+        if (input.routingNodeKey !== undefined && !input.routingNodeKey.trim()) {
+          throw new Error("routingNodeKey must be non-empty when provided");
+        }
+        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit-item`, "POST", input);
+      },
       submit: async (attemptId, input) => {
         assertPlatformMode(client, "timeback.assessments.submit()");
         if (!attemptId?.trim()) {
@@ -3053,7 +3259,25 @@ function createTimebackNamespace(client) {
         if (!input.submissionId?.trim()) {
           throw new Error("submissionId is required");
         }
-        return client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", input);
+        const { expectedResponseVersion } = input;
+        const { submissionId, session } = await assessmentSubmissionContext(attemptId, input.submissionId);
+        const request = {
+          expectedResponseVersion,
+          submissionId,
+          ...session ? { session } : {}
+        };
+        try {
+          const result = await client["requestGameBackend"](`${ASSESSMENTS_ROUTE}/${encodeURIComponent(attemptId)}/submit`, "POST", request, undefined, { retryPolicy: ASSESSMENT_SUBMIT_RETRY_POLICY });
+          releasePendingSubmission(attemptId, submissionId);
+          await engine.activity.finishAssessment(attemptId);
+          clearAssessmentTrackingWarnings(attemptId);
+          return result;
+        } catch (error) {
+          if (error instanceof ApiError && !error.isRetryable()) {
+            await resumeAfterDefinitiveFailure(attemptId, submissionId);
+          }
+          throw error;
+        }
       }
     },
     get user() {
@@ -3460,7 +3684,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.16.1-beta.9";
+var SDK_VERSION = "0.17.0";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {