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

package/dist/index.d.ts

@@ -381,74 +381,6 @@ declare function parseOAuthState(state: string): {
 /** Permitted HTTP verbs */
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
-/**
- * User Types
- *
- * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
- *
- * @module types/user
- */
-type UserRoleEnumType = 'admin' | 'player' | 'developer';
-type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
-type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
-type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
-interface UserEnrollment {
-    gameId?: string;
-    courseId: string;
-    grade: number;
-    subject: string;
-    orgId?: string;
-}
-interface UserOrganization {
-    id: string;
-    name: string | null;
-    type: TimebackOrgType | string;
-    isPrimary: boolean;
-}
-interface TimebackStudentProfile {
-    role: TimebackUserRole;
-    organizations: UserOrganization[];
-}
-interface UserTimebackData extends TimebackStudentProfile {
-    id: string;
-    enrollments: UserEnrollment[];
-}
-/**
- * OpenID Connect UserInfo claims (NOT a database row).
- */
-interface UserInfo {
-    sub: string;
-    email: string;
-    name: string | null;
-    email_verified?: boolean;
-    given_name?: string;
-    family_name?: string;
-    issuer?: string;
-    lti_roles?: unknown;
-    lti_context?: unknown;
-    lti_resource_link?: unknown;
-    timeback_id?: string;
-}
-/**
- * Authenticated user for API responses.
- * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
- */
-interface AuthenticatedUser {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name: string | null;
-    image: string | null;
-    username: string | null;
-    role: UserRoleEnumType;
-    developerStatus: DeveloperStatusEnumType;
-    characterCreated: boolean;
-    createdAt: Date;
-    updatedAt: Date;
-    hasTimebackAccount: boolean;
-    timeback?: UserTimebackData;
-}
-
 /**
  * TimeBack Enums & Literal Types
  *
@@ -551,6 +483,74 @@ interface EndActivityResponse {
     inProgress?: string;
 }
 
+/**
+ * User Types
+ *
+ * Enums, DTOs and API response types. Database row types are in @playcademy/data/types.
+ *
+ * @module types/user
+ */
+type UserRoleEnumType = 'admin' | 'player' | 'developer' | 'teacher';
+type DeveloperStatusEnumType = 'none' | 'pending' | 'approved';
+type TimebackUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+type TimebackOrgType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+interface UserEnrollment {
+    gameId?: string;
+    courseId: string;
+    grade: number;
+    subject: string;
+    orgId?: string;
+}
+interface UserOrganization {
+    id: string;
+    name: string | null;
+    type: TimebackOrgType | string;
+    isPrimary: boolean;
+}
+interface TimebackStudentProfile {
+    role: TimebackUserRole;
+    organizations: UserOrganization[];
+}
+interface UserTimebackData extends TimebackStudentProfile {
+    id: string;
+    enrollments: UserEnrollment[];
+}
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+/**
+ * Authenticated user for API responses.
+ * Differs from UserRow: omits timebackId, adds hasTimebackAccount and timeback.
+ */
+interface AuthenticatedUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+    username: string | null;
+    role: UserRoleEnumType;
+    developerStatus: DeveloperStatusEnumType;
+    characterCreated: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    hasTimebackAccount: boolean;
+    timeback?: UserTimebackData;
+}
+
 declare const items: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "items";
     schema: undefined;
@@ -982,6 +982,23 @@ declare abstract class PlaycademyBaseClient {
     };
 }
 
+/**
+ * Options for configuring activity tracking behavior.
+ */
+interface StartActivityOptions {
+    /**
+     * How long the tab can stay hidden before the timing window resets on return.
+     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     */
+    hiddenTimeoutMs?: number;
+    /**
+     * How often to flush periodic heartbeats with accumulated time data.
+     * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
+     * final unload/endActivity flushes still run.
+     */
+    heartbeatIntervalMs?: number;
+}
+
 /**
  * Auto-initializes a PlaycademyClient with context from the environment.
  * Works in both iframe mode (production/development) and standalone mode (local dev).
@@ -1119,7 +1136,7 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      */
     timeback: {
         readonly user: TimebackUser;
-        startActivity: (metadata: ActivityData) => void;
+        startActivity: (metadata: ActivityData, options?: StartActivityOptions | undefined) => void;
         pauseActivity: () => void;
         resumeActivity: () => void;
         endActivity: (data: EndActivityScoreData) => Promise<EndActivityResponse>;

package/dist/index.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/core/auth/strategies.ts