@playcademy/sdk 0.4.1-beta.6 → 0.4.1-beta.7

package/dist/index.d.ts

@@ -997,6 +997,19 @@ interface StartActivityOptions {
      * final unload/endActivity flushes still run.
      */
     heartbeatIntervalMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
 }
 
 /**

package/dist/index.js

@@ -1379,6 +1379,15 @@ function createRealtimeNamespace(client) {
     }
   };
 }
+// ../utils/src/uuid.ts
+var UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isValidUUID(value) {
+  if (!value || typeof value !== "string") {
+    return false;
+  }
+  return UUID_REGEX.test(value);
+}
+
 // src/core/activity-tracker.ts
 var DEFAULT_HIDDEN_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
@@ -1389,6 +1398,7 @@ function getCurrentPausedTotal(activity, now = Date.now()) {
   return activity.pausedTime + (now - activity.pauseStartTime);
 }
 function computeWindowAndReset(activity) {
+  const windowStartedAtMs = activity.windowStartTime;
   const now = Date.now();
   const totalPaused = getCurrentPausedTotal(activity, now);
   if (activity.pauseStartTime !== null) {
@@ -1400,8 +1410,7 @@ function computeWindowAndReset(activity) {
   const activeMs = Math.max(0, windowElapsed - windowPaused);
   activity.windowStartTime = now;
   activity.windowPausedAtStart = totalPaused;
-  activity.windowSequence++;
-  return { activeMs, pausedMs: windowPaused };
+  return { activeMs, pausedMs: windowPaused, windowStartedAtMs };
 }
 function markPersistedTiming(activity, timing) {
   activity.totalPersistedActiveMs += timing.activeMs;
@@ -1505,12 +1514,13 @@ function createTimebackActivityTracker(client) {
   function handleShellResume() {
     removePauseReason("shell");
   }
-  function buildHeartbeatBody(activity, timing, sequence, isFinal) {
+  function buildHeartbeatBody(activity, timing, isFinal) {
     return {
       runId: activity.runId,
+      resumeId: activity.resumeId,
       activityData: activity.metadata,
       timingData: { activeMs: timing.activeMs, pausedMs: timing.pausedMs },
-      windowSequence: sequence,
+      windowStartedAtMs: timing.windowStartedAtMs,
       isFinal
     };
   }
@@ -1520,12 +1530,11 @@ function createTimebackActivityTracker(client) {
       return;
     }
     const trackedActivity = activity;
-    const sequence = trackedActivity.windowSequence;
     const timing = computeWindowAndReset(trackedActivity);
     if (timing.activeMs === 0 && timing.pausedMs === 0) {
       return;
     }
-    const body = buildHeartbeatBody(trackedActivity, timing, sequence, isFinal);
+    const body = buildHeartbeatBody(trackedActivity, timing, isFinal);
     await queueHeartbeatFlush(trackedActivity, timing, async () => {
       try {
         await client["requestGameBackend"](TIMEBACK_ROUTES.HEARTBEAT, "POST", body);
@@ -1537,12 +1546,11 @@ function createTimebackActivityTracker(client) {
     if (!activity) {
       return;
     }
-    const sequence = activity.windowSequence;
     const timing = computeWindowAndReset(activity);
     if (timing.activeMs === 0 && timing.pausedMs === 0) {
       return;
     }
-    const body = buildHeartbeatBody(activity, timing, sequence, true);
+    const body = buildHeartbeatBody(activity, timing, true);
     queueHeartbeatFlush(activity, timing, async () => {
       try {
         const baseUrl = client["getGameBackendUrl"]();
@@ -1589,11 +1597,15 @@ function createTimebackActivityTracker(client) {
   }
   return {
     startActivity(metadata, 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.`);
+      }
       cleanupListeners();
       const now = Date.now();
       const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
       currentActivity = {
-        runId: crypto.randomUUID(),
+        runId: options?.runId ?? crypto.randomUUID(),
+        resumeId: crypto.randomUUID(),
         startTime: now,
         metadata,
         pausedTime: 0,
@@ -1604,7 +1616,6 @@ function createTimebackActivityTracker(client) {
         hiddenTimeoutMs: options?.hiddenTimeoutMs ?? DEFAULT_HIDDEN_TIMEOUT_MS,
         windowStartTime: now,
         windowPausedAtStart: 0,
-        windowSequence: 0,
         heartbeatIntervalId: null,
         heartbeatIntervalMs,
         flushInFlight: null,
@@ -1666,6 +1677,7 @@ function createTimebackActivityTracker(client) {
       const { correctQuestions, totalQuestions } = data;
       const request = {
         runId: activity.runId,
+        resumeId: activity.resumeId,
         activityData: activity.metadata,
         scoreData: {
           correctQuestions,

package/dist/internal.d.ts

@@ -457,7 +457,7 @@ interface TimebackStudentCourseOverview {
     completionStatus: CourseCompletionStatus;
     history: TimebackStudentHistoryPoint[];
 }
-type TimebackRecentActivityKind = 'activity' | 'time-spent' | 'remediation-xp' | 'remediation-time' | 'remediation-mastery' | 'course-completed' | 'course-resumed';
+type TimebackRecentActivityKind = 'activity' | 'activity-in-progress' | 'time-spent' | 'remediation-xp' | 'remediation-time' | 'remediation-mastery' | 'course-completed' | 'course-resumed';
 interface TimebackRecentActivity {
     id: string;
     kind: TimebackRecentActivityKind;
@@ -471,6 +471,8 @@ interface TimebackRecentActivity {
     xpDelta?: number;
     timeDeltaSeconds?: number;
     masteredUnitsDelta?: number;
+    runId?: string;
+    sessionCount?: number;
 }
 interface TimebackStudentOverviewResponse {
     student: {
@@ -491,6 +493,7 @@ interface GrantTimebackXpRequest {
     xp: number;
     reason: string;
     date?: string;
+    useCurrentTime?: boolean;
 }
 interface AdjustTimebackTimeRequest {
     gameId: string;
@@ -499,6 +502,8 @@ interface AdjustTimebackTimeRequest {
     seconds: number;
     reason: string;
     date?: string;
+    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
+    useCurrentTime?: boolean;
 }
 interface AdjustTimebackMasteryRequest {
     gameId: string;
@@ -507,6 +512,8 @@ interface AdjustTimebackMasteryRequest {
     units: number;
     reason: string;
     date?: string;
+    /** See {@link GrantTimebackXpRequest.useCurrentTime}. */
+    useCurrentTime?: boolean;
 }
 interface ToggleCourseCompletionRequest {
     gameId: string;

package/dist/internal.js

@@ -1379,6 +1379,15 @@ function createRealtimeNamespace(client) {
     }
   };
 }
+// ../utils/src/uuid.ts
+var UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isValidUUID(value) {
+  if (!value || typeof value !== "string") {
+    return false;
+  }
+  return UUID_REGEX.test(value);
+}
+
 // src/core/activity-tracker.ts
 var DEFAULT_HIDDEN_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
@@ -1389,6 +1398,7 @@ function getCurrentPausedTotal(activity, now = Date.now()) {
   return activity.pausedTime + (now - activity.pauseStartTime);
 }
 function computeWindowAndReset(activity) {
+  const windowStartedAtMs = activity.windowStartTime;
   const now = Date.now();
   const totalPaused = getCurrentPausedTotal(activity, now);
   if (activity.pauseStartTime !== null) {
@@ -1400,8 +1410,7 @@ function computeWindowAndReset(activity) {
   const activeMs = Math.max(0, windowElapsed - windowPaused);
   activity.windowStartTime = now;
   activity.windowPausedAtStart = totalPaused;
-  activity.windowSequence++;
-  return { activeMs, pausedMs: windowPaused };
+  return { activeMs, pausedMs: windowPaused, windowStartedAtMs };
 }
 function markPersistedTiming(activity, timing) {
   activity.totalPersistedActiveMs += timing.activeMs;
@@ -1505,12 +1514,13 @@ function createTimebackActivityTracker(client) {
   function handleShellResume() {
     removePauseReason("shell");
   }
-  function buildHeartbeatBody(activity, timing, sequence, isFinal) {
+  function buildHeartbeatBody(activity, timing, isFinal) {
     return {
       runId: activity.runId,
+      resumeId: activity.resumeId,
       activityData: activity.metadata,
       timingData: { activeMs: timing.activeMs, pausedMs: timing.pausedMs },
-      windowSequence: sequence,
+      windowStartedAtMs: timing.windowStartedAtMs,
       isFinal
     };
   }
@@ -1520,12 +1530,11 @@ function createTimebackActivityTracker(client) {
       return;
     }
     const trackedActivity = activity;
-    const sequence = trackedActivity.windowSequence;
     const timing = computeWindowAndReset(trackedActivity);
     if (timing.activeMs === 0 && timing.pausedMs === 0) {
       return;
     }
-    const body = buildHeartbeatBody(trackedActivity, timing, sequence, isFinal);
+    const body = buildHeartbeatBody(trackedActivity, timing, isFinal);
     await queueHeartbeatFlush(trackedActivity, timing, async () => {
       try {
         await client["requestGameBackend"](TIMEBACK_ROUTES.HEARTBEAT, "POST", body);
@@ -1537,12 +1546,11 @@ function createTimebackActivityTracker(client) {
     if (!activity) {
       return;
     }
-    const sequence = activity.windowSequence;
     const timing = computeWindowAndReset(activity);
     if (timing.activeMs === 0 && timing.pausedMs === 0) {
       return;
     }
-    const body = buildHeartbeatBody(activity, timing, sequence, true);
+    const body = buildHeartbeatBody(activity, timing, true);
     queueHeartbeatFlush(activity, timing, async () => {
       try {
         const baseUrl = client["getGameBackendUrl"]();
@@ -1589,11 +1597,15 @@ function createTimebackActivityTracker(client) {
   }
   return {
     startActivity(metadata, 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.`);
+      }
       cleanupListeners();
       const now = Date.now();
       const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
       currentActivity = {
-        runId: crypto.randomUUID(),
+        runId: options?.runId ?? crypto.randomUUID(),
+        resumeId: crypto.randomUUID(),
         startTime: now,
         metadata,
         pausedTime: 0,
@@ -1604,7 +1616,6 @@ function createTimebackActivityTracker(client) {
         hiddenTimeoutMs: options?.hiddenTimeoutMs ?? DEFAULT_HIDDEN_TIMEOUT_MS,
         windowStartTime: now,
         windowPausedAtStart: 0,
-        windowSequence: 0,
         heartbeatIntervalId: null,
         heartbeatIntervalMs,
         flushInFlight: null,
@@ -1666,6 +1677,7 @@ function createTimebackActivityTracker(client) {
       const { correctQuestions, totalQuestions } = data;
       const request = {
         runId: activity.runId,
+        resumeId: activity.resumeId,
         activityData: activity.metadata,
         scoreData: {
           correctQuestions,

package/dist/types.d.ts

@@ -4731,6 +4731,19 @@ interface StartActivityOptions {
      * final unload/endActivity flushes still run.
      */
     heartbeatIntervalMs?: number;
+    /**
+     * Stable identifier for this activity run. When provided, it is used on
+     * every heartbeat and on endActivity instead of a freshly-generated UUID.
+     *
+     * Pass the same `runId` across multiple `startActivity()` calls (for
+     * example, after the player closes and reopens a resumable activity) so
+     * downstream systems can correlate related sessions into a single run.
+     *
+     * Must be a UUID (the backend validates it as such) and unique per
+     * logical run. If omitted, the SDK generates a new UUID on each call,
+     * which means every session is treated as its own run.
+     */
+    runId?: string;
 }
 
 /**

package/package.json

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