@playcademy/sdk 0.4.1-beta.3 → 0.4.1-beta.5

package/dist/internal.js

@@ -1274,7 +1274,8 @@ var BADGES = {
 // ../constants/src/timeback.ts
 var TIMEBACK_ROUTES = {
   END_ACTIVITY: "/integrations/timeback/end-activity",
-  GET_XP: "/integrations/timeback/xp"
+  GET_XP: "/integrations/timeback/xp",
+  HEARTBEAT: "/integrations/timeback/heartbeat"
 };
 // src/core/cache/singleton-cache.ts
 function createSingletonCache() {
@@ -1378,6 +1379,325 @@ function createRealtimeNamespace(client) {
     }
   };
 }
+// src/core/activity-tracker.ts
+var DEFAULT_HIDDEN_TIMEOUT_MS = 10 * 60 * 1000;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+function getCurrentPausedTotal(activity, now = Date.now()) {
+  if (activity.pauseStartTime === null) {
+    return activity.pausedTime;
+  }
+  return activity.pausedTime + (now - activity.pauseStartTime);
+}
+function computeWindowAndReset(activity) {
+  const now = Date.now();
+  const totalPaused = getCurrentPausedTotal(activity, now);
+  if (activity.pauseStartTime !== null) {
+    activity.pausedTime = totalPaused;
+    activity.pauseStartTime = now;
+  }
+  const windowPaused = totalPaused - activity.windowPausedAtStart;
+  const windowElapsed = now - activity.windowStartTime;
+  const activeMs = Math.max(0, windowElapsed - windowPaused);
+  activity.windowStartTime = now;
+  activity.windowPausedAtStart = totalPaused;
+  activity.windowSequence++;
+  return { activeMs, pausedMs: windowPaused };
+}
+function markPersistedTiming(activity, timing) {
+  activity.totalPersistedActiveMs += timing.activeMs;
+  activity.totalPersistedPausedMs += timing.pausedMs;
+}
+function queueHeartbeatFlush(activity, timing, flush) {
+  markPersistedTiming(activity, timing);
+  async function doFlush() {
+    await flush();
+  }
+  if (activity.flushInFlight) {
+    const previousFlush = activity.flushInFlight.catch(() => {
+      return;
+    });
+    activity.flushInFlight = previousFlush.then(doFlush);
+  } else {
+    activity.flushInFlight = doFlush();
+  }
+  return activity.flushInFlight;
+}
+function stopHeartbeatInterval(activity) {
+  if (activity.heartbeatIntervalId === null) {
+    return;
+  }
+  clearInterval(activity.heartbeatIntervalId);
+  activity.heartbeatIntervalId = null;
+}
+function createTimebackActivityTracker(client) {
+  let currentActivity = null;
+  let boundVisibilityHandler = null;
+  let boundShellPauseHandler = null;
+  let boundShellResumeHandler = null;
+  let boundPageHideHandler = null;
+  function startHeartbeatInterval(activity) {
+    if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
+      return;
+    }
+    activity.heartbeatIntervalId = setInterval(() => {
+      flushHeartbeat();
+    }, activity.heartbeatIntervalMs);
+  }
+  function addPauseReason(reason) {
+    if (!currentActivity) {
+      return;
+    }
+    const wasPaused = currentActivity.pauseReasons.size > 0;
+    currentActivity.pauseReasons.add(reason);
+    if (!wasPaused && currentActivity.pauseReasons.size > 0) {
+      currentActivity.pauseStartTime = Date.now();
+    }
+  }
+  function removePauseReason(reason) {
+    if (!currentActivity) {
+      return;
+    }
+    currentActivity.pauseReasons.delete(reason);
+    if (currentActivity.pauseReasons.size === 0 && currentActivity.pauseStartTime !== null) {
+      currentActivity.pausedTime += Date.now() - currentActivity.pauseStartTime;
+      currentActivity.pauseStartTime = null;
+    }
+  }
+  function handleVisibilityChange() {
+    if (!currentActivity) {
+      return;
+    }
+    if (document.visibilityState === "hidden") {
+      addPauseReason("hidden");
+      if (currentActivity.hiddenTimeoutMs !== Infinity) {
+        if (currentActivity.hiddenTimeoutId !== null) {
+          clearTimeout(currentActivity.hiddenTimeoutId);
+        }
+        const activity = currentActivity;
+        currentActivity.hiddenTimeoutId = setTimeout(() => {
+          if (currentActivity === activity) {
+            activity.hiddenTimeoutId = null;
+            activity.hiddenTimedOut = true;
+            stopHeartbeatInterval(activity);
+          }
+        }, activity.hiddenTimeoutMs);
+      }
+    } else {
+      const shouldResetWindow = currentActivity.hiddenTimedOut;
+      if (currentActivity.hiddenTimeoutId !== null) {
+        clearTimeout(currentActivity.hiddenTimeoutId);
+        currentActivity.hiddenTimeoutId = null;
+      }
+      removePauseReason("hidden");
+      if (shouldResetWindow) {
+        const now = Date.now();
+        const pausedAtReset = getCurrentPausedTotal(currentActivity, now);
+        currentActivity.hiddenTimedOut = false;
+        currentActivity.windowStartTime = now;
+        currentActivity.windowPausedAtStart = pausedAtReset;
+        startHeartbeatInterval(currentActivity);
+      }
+    }
+  }
+  function handleShellPause() {
+    addPauseReason("shell");
+  }
+  function handleShellResume() {
+    removePauseReason("shell");
+  }
+  function buildHeartbeatBody(activity, timing, sequence, isFinal) {
+    return {
+      runId: activity.runId,
+      activityData: activity.metadata,
+      timingData: { activeMs: timing.activeMs, pausedMs: timing.pausedMs },
+      windowSequence: sequence,
+      isFinal
+    };
+  }
+  async function flushHeartbeat(isFinal) {
+    const activity = currentActivity;
+    if (!activity) {
+      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);
+    await queueHeartbeatFlush(trackedActivity, timing, async () => {
+      try {
+        await client["requestGameBackend"](TIMEBACK_ROUTES.HEARTBEAT, "POST", body);
+      } catch {}
+    });
+  }
+  function handlePageHide() {
+    const activity = currentActivity;
+    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);
+    queueHeartbeatFlush(activity, timing, async () => {
+      try {
+        const baseUrl = client["getGameBackendUrl"]();
+        const url = `${baseUrl}${TIMEBACK_ROUTES.HEARTBEAT}`;
+        const headers = {
+          "Content-Type": "application/json",
+          ...client["authStrategy"].getHeaders()
+        };
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          keepalive: true
+        });
+        if (response.ok) {
+          return;
+        }
+      } catch {}
+    });
+  }
+  function cleanupListeners() {
+    if (boundVisibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", boundVisibilityHandler);
+      boundVisibilityHandler = null;
+    }
+    if (boundShellPauseHandler) {
+      messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
+      boundShellPauseHandler = null;
+    }
+    if (boundShellResumeHandler) {
+      messaging.unlisten("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+      boundShellResumeHandler = null;
+    }
+    if (boundPageHideHandler && typeof globalThis.window !== "undefined") {
+      globalThis.window.removeEventListener("pagehide", boundPageHideHandler);
+      boundPageHideHandler = null;
+    }
+    if (currentActivity?.hiddenTimeoutId != null) {
+      clearTimeout(currentActivity.hiddenTimeoutId);
+    }
+    if (currentActivity?.heartbeatIntervalId != null) {
+      stopHeartbeatInterval(currentActivity);
+    }
+  }
+  return {
+    startActivity(metadata, options) {
+      cleanupListeners();
+      const now = Date.now();
+      const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+      currentActivity = {
+        runId: crypto.randomUUID(),
+        startTime: now,
+        metadata,
+        pausedTime: 0,
+        pauseStartTime: null,
+        pauseReasons: new Set,
+        hiddenTimeoutId: null,
+        hiddenTimedOut: false,
+        hiddenTimeoutMs: options?.hiddenTimeoutMs ?? DEFAULT_HIDDEN_TIMEOUT_MS,
+        windowStartTime: now,
+        windowPausedAtStart: 0,
+        windowSequence: 0,
+        heartbeatIntervalId: null,
+        heartbeatIntervalMs,
+        flushInFlight: null,
+        totalPersistedActiveMs: 0,
+        totalPersistedPausedMs: 0
+      };
+      if (typeof document !== "undefined") {
+        boundVisibilityHandler = handleVisibilityChange;
+        document.addEventListener("visibilitychange", boundVisibilityHandler);
+        if (document.visibilityState === "hidden") {
+          handleVisibilityChange();
+        }
+      }
+      startHeartbeatInterval(currentActivity);
+      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);
+    },
+    pauseActivity() {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before pauseActivity().");
+      }
+      if (currentActivity.pauseReasons.has("manual")) {
+        throw new Error("Activity is already paused.");
+      }
+      addPauseReason("manual");
+    },
+    resumeActivity() {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before resumeActivity().");
+      }
+      if (!currentActivity.pauseReasons.has("manual")) {
+        throw new Error("Activity is not paused.");
+      }
+      removePauseReason("manual");
+    },
+    async endActivity(data) {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before endActivity().");
+      }
+      const activity = currentActivity;
+      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;
+      const request = {
+        runId: activity.runId,
+        activityData: activity.metadata,
+        scoreData: {
+          correctQuestions,
+          totalQuestions
+        },
+        timingData: {
+          durationSeconds
+        },
+        sessionTimingData: {
+          activeSeconds: unreportedActiveMs / 1000,
+          ...unreportedPausedMs > 0 ? { inactiveSeconds: unreportedPausedMs / 1000 } : {}
+        },
+        xpEarned: data.xpAwarded,
+        masteredUnits: data.masteredUnits,
+        extensions: data.extensions
+      };
+      try {
+        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request);
+        if (currentActivity === activity) {
+          currentActivity = null;
+        }
+        return response;
+      } catch (error) {
+        if (currentActivity === activity) {
+          currentActivity = null;
+        }
+        throw error;
+      }
+    }
+  };
+}
+
 // src/core/cache/ttl-cache.ts
 function createTTLCache(options) {
   const cache = new Map;
@@ -1473,7 +1793,7 @@ function isValidSubject(value) {
 
 // src/namespaces/game/timeback.ts
 function createTimebackNamespace(client) {
-  let currentActivity = null;
+  const activityTracker = createTimebackActivityTracker(client);
   const userCache = createTTLCache({
     ttl: 5 * 60 * 1000,
     keyPrefix: "game.timeback.user"
@@ -1558,70 +1878,16 @@ function createTimebackNamespace(client) {
         }
       };
     },
-    startActivity: (metadata) => {
-      currentActivity = {
-        startTime: Date.now(),
-        metadata,
-        pausedTime: 0,
-        pauseStartTime: null
-      };
+    startActivity: (metadata, options) => {
+      activityTracker.startActivity(metadata, options);
     },
     pauseActivity: () => {
-      if (!currentActivity) {
-        throw new Error("No activity in progress. Call startActivity() before pauseActivity().");
-      }
-      if (currentActivity.pauseStartTime !== null) {
-        throw new Error("Activity is already paused.");
-      }
-      currentActivity.pauseStartTime = Date.now();
+      activityTracker.pauseActivity();
     },
     resumeActivity: () => {
-      if (!currentActivity) {
-        throw new Error("No activity in progress. Call startActivity() before resumeActivity().");
-      }
-      if (currentActivity.pauseStartTime === null) {
-        throw new Error("Activity is not paused.");
-      }
-      const pauseDuration = Date.now() - currentActivity.pauseStartTime;
-      currentActivity.pausedTime += pauseDuration;
-      currentActivity.pauseStartTime = null;
+      activityTracker.resumeActivity();
     },
-    endActivity: async (data) => {
-      if (!currentActivity) {
-        throw new Error("No activity in progress. Call startActivity() before endActivity().");
-      }
-      if (currentActivity.pauseStartTime !== null) {
-        const pauseDuration = Date.now() - currentActivity.pauseStartTime;
-        currentActivity.pausedTime += pauseDuration;
-        currentActivity.pauseStartTime = null;
-      }
-      const endTime = Date.now();
-      const totalElapsed = endTime - currentActivity.startTime;
-      const activeTime = totalElapsed - currentActivity.pausedTime;
-      const durationSeconds = Math.floor(activeTime / 1000);
-      const { correctQuestions, totalQuestions } = data;
-      const request = {
-        activityData: currentActivity.metadata,
-        scoreData: {
-          correctQuestions,
-          totalQuestions
-        },
-        timingData: {
-          durationSeconds
-        },
-        xpEarned: data.xpAwarded,
-        masteredUnits: data.masteredUnits,
-        extensions: data.extensions
-      };
-      try {
-        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request);
-        currentActivity = null;
-        return response;
-      } catch (error) {
-        currentActivity = null;
-        throw error;
-      }
-    }
+    endActivity: async (data) => activityTracker.endActivity(data)
   };
 }
 // src/namespaces/platform/auth.ts
@@ -2570,6 +2836,16 @@ function createTimebackNamespace2(client) {
       }),
       toggleCompletion: (request) => client["request"]("/timeback/toggle-completion", "POST", {
         body: request
+      }),
+      searchStudents: (gameId, courseId, query) => {
+        const params = new URLSearchParams({ q: query });
+        return client["request"](`/timeback/search-students/${gameId}/${courseId}?${params}`, "GET");
+      },
+      enrollStudent: (request) => client["request"]("/timeback/enroll-student", "POST", {
+        body: request
+      }),
+      unenrollStudent: (request) => client["request"]("/timeback/unenroll-student", "POST", {
+        body: request
       })
     }
   };