@playcademy/sdk 0.12.1-beta.1 → 0.12.1-beta.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _playcademy_types from '@playcademy/types';
-import { TimebackGrade, TimebackSubject } from '@playcademy/types/timeback';
+import { TimebackGrade, TimebackSubject, HeartbeatRequest } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
@@ -511,6 +511,12 @@ declare enum MessageEvents {
      * - `metadata?`: `Record<string, unknown>`
      */
     DEMO_END = "PLAYCADEMY_DEMO_END",
+    /**
+     * Game shares its latest TimeBack heartbeat window with the parent shell.
+     * The shell can relay this payload during top-level page teardown, which is
+     * more reliable than relying only on cross-origin iframe unload events.
+     */
+    TIMEBACK_HEARTBEAT_RELAY = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -578,6 +584,8 @@ interface MessageEventMap {
     [MessageEvents.KEY_EVENT]: KeyEventPayload;
     /** Demo end signal from game */
     [MessageEvents.DEMO_END]: DemoEndPayload;
+    /** Latest TimeBack heartbeat window for parent-shell unload relay */
+    [MessageEvents.TIMEBACK_HEARTBEAT_RELAY]: TimebackHeartbeatRelayRequest;
     /** Authentication state change notification */
     [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
     /** OAuth callback data from popup/new-tab windows */
@@ -1442,6 +1450,8 @@ interface InitPayload {
     mode?: PlaycademyMode;
     /** Launch session correlation ID (UUID, set by platform on game launch) */
     launchId?: string;
+    /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
+    hasHeartbeatRelay?: boolean;
 }
 interface GameContextPayload {
     token: string;
@@ -1547,6 +1557,9 @@ interface DemoEndOptions {
 interface DemoEndPayload extends DemoEndOptions {
     score: number;
 }
+type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
+    windowStartedAtMs: number;
+};
 
 /**
  * SDK-specific API response types

package/dist/index.js

@@ -25,6 +25,7 @@ var MessageEvents;
   MessageEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
   MessageEvents2["KEY_EVENT"] = "PLAYCADEMY_KEY_EVENT";
   MessageEvents2["DEMO_END"] = "PLAYCADEMY_DEMO_END";
+  MessageEvents2["TIMEBACK_HEARTBEAT_RELAY"] = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY";
   MessageEvents2["AUTH_STATE_CHANGE"] = "PLAYCADEMY_AUTH_STATE_CHANGE";
   MessageEvents2["AUTH_CALLBACK"] = "PLAYCADEMY_AUTH_CALLBACK";
 })(MessageEvents ||= {});
@@ -85,7 +86,8 @@ class PlaycademyMessaging {
       "PLAYCADEMY_EXIT" /* EXIT */,
       "PLAYCADEMY_TELEMETRY" /* TELEMETRY */,
       "PLAYCADEMY_KEY_EVENT" /* KEY_EVENT */,
-      "PLAYCADEMY_DEMO_END" /* DEMO_END */
+      "PLAYCADEMY_DEMO_END" /* DEMO_END */,
+      "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */
     ];
     const shouldUsePostMessage = isIframe && iframeToParentEvents.includes(eventType);
     return {
@@ -1242,6 +1244,7 @@ function isValidUUID(value) {
 var DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
 var DEFAULT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
+var RELAY_INTERVAL_MS = 1000;
 var HEARTBEAT_RETRY_POLICY = { retryableMethods: ["POST"] };
 var USER_ACTIVITY_EVENTS = ["keydown", "pointerdown", "pointermove", "wheel"];
 var USER_ACTIVITY_LISTENER_OPTIONS = { capture: true };
@@ -1275,6 +1278,14 @@ function computeWindowAndReset(activity) {
   activity.windowPausedAtStart = totalPaused;
   return { activeMs, pausedMs: windowPaused, windowStartedAtMs };
 }
+function computeWindowSnapshot(activity) {
+  const now = Date.now();
+  const totalPaused = getCurrentPausedTotal(activity, now);
+  const windowPaused = totalPaused - activity.windowPausedAtStart;
+  const windowElapsed = now - activity.windowStartTime;
+  const activeMs = Math.max(0, windowElapsed - windowPaused);
+  return { activeMs, pausedMs: windowPaused, windowStartedAtMs: activity.windowStartTime };
+}
 function markPersistedTiming(activity, timing) {
   activity.totalPersistedActiveMs += timing.activeMs;
   activity.totalPersistedPausedMs += timing.pausedMs;
@@ -1340,6 +1351,10 @@ function createTimebackActivityTracker(client) {
   let boundShellPauseHandler = null;
   let boundShellResumeHandler = null;
   let boundPageHideHandler = null;
+  let relayIntervalId = null;
+  let lastRelayedActiveMs = -1;
+  let lastRelayedPausedMs = -1;
+  let lastRelayedWindowStart = -1;
   function startHeartbeatInterval(activity) {
     if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
       return;
@@ -1355,10 +1370,12 @@ function createTimebackActivityTracker(client) {
     activity.windowStartTime = now;
     activity.windowPausedAtStart = pausedAtReset;
     startHeartbeatInterval(activity);
+    startRelayInterval();
   }
   function markPausedHeartbeatTimedOut(activity) {
     activity.pausedHeartbeatTimeoutId = null;
     activity.pausedHeartbeatTimedOut = true;
+    stopRelayInterval();
     stopHeartbeatInterval(activity);
   }
   function armPausedHeartbeatTimeout(activity, startedAt = Date.now()) {
@@ -1506,14 +1523,47 @@ function createTimebackActivityTracker(client) {
     }
     syncInactivityTracking();
   }
+  function startRelayInterval() {
+    if (relayIntervalId !== null) {
+      return;
+    }
+    relayIntervalId = setInterval(() => {
+      const activity = currentActivity;
+      if (!activity) {
+        return;
+      }
+      const timing = computeWindowSnapshot(activity);
+      if (timing.activeMs === lastRelayedActiveMs && timing.pausedMs === lastRelayedPausedMs && timing.windowStartedAtMs === lastRelayedWindowStart) {
+        return;
+      }
+      lastRelayedActiveMs = timing.activeMs;
+      lastRelayedPausedMs = timing.pausedMs;
+      lastRelayedWindowStart = timing.windowStartedAtMs;
+      const body = buildHeartbeatBody(activity, timing);
+      try {
+        messaging.send("PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */, body);
+      } catch {}
+    }, RELAY_INTERVAL_MS);
+  }
+  function stopRelayInterval() {
+    if (relayIntervalId !== null) {
+      clearInterval(relayIntervalId);
+      relayIntervalId = null;
+      lastRelayedActiveMs = -1;
+      lastRelayedPausedMs = -1;
+      lastRelayedWindowStart = -1;
+    }
+  }
   function handleVisibilityChange() {
     if (!currentActivity) {
       return;
     }
     if (document.visibilityState === "hidden") {
       addPauseReason("hidden");
+      flushFinalHeartbeatBeacon();
     } else {
       removePauseReason("hidden");
+      startRelayInterval();
     }
   }
   function handleShellPause() {
@@ -1553,7 +1603,7 @@ function createTimebackActivityTracker(client) {
       }
     });
   }
-  function handlePageHide() {
+  function flushFinalHeartbeatBeacon() {
     applyOverdueInactivity();
     const activity = currentActivity;
     if (!activity) {
@@ -1564,26 +1614,34 @@ function createTimebackActivityTracker(client) {
       return;
     }
     const body = buildHeartbeatBody(activity, timing, 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 true;
+    stopRelayInterval();
+    try {
+      messaging.send("PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */, body);
+    } catch {}
+    if (!client["initPayload"]?.hasHeartbeatRelay) {
+      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
+          });
+          return response.ok;
+        } catch {
+          return false;
         }
-      } catch {}
-      return false;
-    });
+      });
+    }
+  }
+  function handlePageHide() {
+    flushFinalHeartbeatBeacon();
   }
   function cleanupListeners() {
     if (boundVisibilityHandler && typeof document !== "undefined") {
@@ -1615,6 +1673,7 @@ function createTimebackActivityTracker(client) {
     if (currentActivity?.heartbeatIntervalId != null) {
       stopHeartbeatInterval(currentActivity);
     }
+    stopRelayInterval();
   }
   return {
     currentRunId() {
@@ -1665,6 +1724,7 @@ function createTimebackActivityTracker(client) {
         }
       }
       startHeartbeatInterval(currentActivity);
+      startRelayInterval();
       if (typeof globalThis.window !== "undefined") {
         boundPageHideHandler = handlePageHide;
         globalThis.window.addEventListener("pagehide", boundPageHideHandler);
@@ -2318,7 +2378,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.12.1-beta.1";
+var SDK_VERSION = "0.12.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 import { SchemaInfo } from '@playcademy/cloudflare';
-import { TimebackGrade, TimebackSubject, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
+import { TimebackGrade, TimebackSubject, HeartbeatRequest, TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/types/timeback';
 export { QtiTestQuestionRef, QtiTestQuestionsResponse } from '@playcademy/types/timeback';
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest } from '@playcademy/types';
@@ -291,6 +291,12 @@ declare enum MessageEvents {
      * - `metadata?`: `Record<string, unknown>`
      */
     DEMO_END = "PLAYCADEMY_DEMO_END",
+    /**
+     * Game shares its latest TimeBack heartbeat window with the parent shell.
+     * The shell can relay this payload during top-level page teardown, which is
+     * more reliable than relying only on cross-origin iframe unload events.
+     */
+    TIMEBACK_HEARTBEAT_RELAY = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -358,6 +364,8 @@ interface MessageEventMap {
     [MessageEvents.KEY_EVENT]: KeyEventPayload;
     /** Demo end signal from game */
     [MessageEvents.DEMO_END]: DemoEndPayload;
+    /** Latest TimeBack heartbeat window for parent-shell unload relay */
+    [MessageEvents.TIMEBACK_HEARTBEAT_RELAY]: TimebackHeartbeatRelayRequest;
     /** Authentication state change notification */
     [MessageEvents.AUTH_STATE_CHANGE]: AuthStateChangePayload;
     /** OAuth callback data from popup/new-tab windows */
@@ -1293,6 +1301,8 @@ interface InitPayload {
     mode?: PlaycademyMode;
     /** Launch session correlation ID (UUID, set by platform on game launch) */
     launchId?: string;
+    /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
+    hasHeartbeatRelay?: boolean;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -1437,6 +1447,9 @@ interface DemoEndOptions {
 interface DemoEndPayload extends DemoEndOptions {
     score: number;
 }
+type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
+    windowStartedAtMs: number;
+};
 
 /**
  * SDK-specific API response types
@@ -3152,4 +3165,4 @@ declare class PlaycademyInternalClient extends PlaycademyBaseClient {
 }
 
 export { ApiError, MessageEvents, PlaycademyInternalClient as PlaycademyClient, PlaycademyError, PlaycademyInternalClient, extractApiErrorInfo, messaging };
-export type { ApiErrorCode, ApiErrorInfo, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, MessageEventMap, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { ApiErrorCode, ApiErrorInfo, AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, ErrorResponseBody, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, MessageEventMap, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

package/dist/internal.js

@@ -25,6 +25,7 @@ var MessageEvents;
   MessageEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
   MessageEvents2["KEY_EVENT"] = "PLAYCADEMY_KEY_EVENT";
   MessageEvents2["DEMO_END"] = "PLAYCADEMY_DEMO_END";
+  MessageEvents2["TIMEBACK_HEARTBEAT_RELAY"] = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY";
   MessageEvents2["AUTH_STATE_CHANGE"] = "PLAYCADEMY_AUTH_STATE_CHANGE";
   MessageEvents2["AUTH_CALLBACK"] = "PLAYCADEMY_AUTH_CALLBACK";
 })(MessageEvents ||= {});
@@ -85,7 +86,8 @@ class PlaycademyMessaging {
       "PLAYCADEMY_EXIT" /* EXIT */,
       "PLAYCADEMY_TELEMETRY" /* TELEMETRY */,
       "PLAYCADEMY_KEY_EVENT" /* KEY_EVENT */,
-      "PLAYCADEMY_DEMO_END" /* DEMO_END */
+      "PLAYCADEMY_DEMO_END" /* DEMO_END */,
+      "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */
     ];
     const shouldUsePostMessage = isIframe && iframeToParentEvents.includes(eventType);
     return {
@@ -1242,6 +1244,7 @@ function isValidUUID(value) {
 var DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
 var DEFAULT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
+var RELAY_INTERVAL_MS = 1000;
 var HEARTBEAT_RETRY_POLICY = { retryableMethods: ["POST"] };
 var USER_ACTIVITY_EVENTS = ["keydown", "pointerdown", "pointermove", "wheel"];
 var USER_ACTIVITY_LISTENER_OPTIONS = { capture: true };
@@ -1275,6 +1278,14 @@ function computeWindowAndReset(activity) {
   activity.windowPausedAtStart = totalPaused;
   return { activeMs, pausedMs: windowPaused, windowStartedAtMs };
 }
+function computeWindowSnapshot(activity) {
+  const now = Date.now();
+  const totalPaused = getCurrentPausedTotal(activity, now);
+  const windowPaused = totalPaused - activity.windowPausedAtStart;
+  const windowElapsed = now - activity.windowStartTime;
+  const activeMs = Math.max(0, windowElapsed - windowPaused);
+  return { activeMs, pausedMs: windowPaused, windowStartedAtMs: activity.windowStartTime };
+}
 function markPersistedTiming(activity, timing) {
   activity.totalPersistedActiveMs += timing.activeMs;
   activity.totalPersistedPausedMs += timing.pausedMs;
@@ -1340,6 +1351,10 @@ function createTimebackActivityTracker(client) {
   let boundShellPauseHandler = null;
   let boundShellResumeHandler = null;
   let boundPageHideHandler = null;
+  let relayIntervalId = null;
+  let lastRelayedActiveMs = -1;
+  let lastRelayedPausedMs = -1;
+  let lastRelayedWindowStart = -1;
   function startHeartbeatInterval(activity) {
     if (activity.heartbeatIntervalMs === Infinity || activity.heartbeatIntervalId !== null) {
       return;
@@ -1355,10 +1370,12 @@ function createTimebackActivityTracker(client) {
     activity.windowStartTime = now;
     activity.windowPausedAtStart = pausedAtReset;
     startHeartbeatInterval(activity);
+    startRelayInterval();
   }
   function markPausedHeartbeatTimedOut(activity) {
     activity.pausedHeartbeatTimeoutId = null;
     activity.pausedHeartbeatTimedOut = true;
+    stopRelayInterval();
     stopHeartbeatInterval(activity);
   }
   function armPausedHeartbeatTimeout(activity, startedAt = Date.now()) {
@@ -1506,14 +1523,47 @@ function createTimebackActivityTracker(client) {
     }
     syncInactivityTracking();
   }
+  function startRelayInterval() {
+    if (relayIntervalId !== null) {
+      return;
+    }
+    relayIntervalId = setInterval(() => {
+      const activity = currentActivity;
+      if (!activity) {
+        return;
+      }
+      const timing = computeWindowSnapshot(activity);
+      if (timing.activeMs === lastRelayedActiveMs && timing.pausedMs === lastRelayedPausedMs && timing.windowStartedAtMs === lastRelayedWindowStart) {
+        return;
+      }
+      lastRelayedActiveMs = timing.activeMs;
+      lastRelayedPausedMs = timing.pausedMs;
+      lastRelayedWindowStart = timing.windowStartedAtMs;
+      const body = buildHeartbeatBody(activity, timing);
+      try {
+        messaging.send("PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */, body);
+      } catch {}
+    }, RELAY_INTERVAL_MS);
+  }
+  function stopRelayInterval() {
+    if (relayIntervalId !== null) {
+      clearInterval(relayIntervalId);
+      relayIntervalId = null;
+      lastRelayedActiveMs = -1;
+      lastRelayedPausedMs = -1;
+      lastRelayedWindowStart = -1;
+    }
+  }
   function handleVisibilityChange() {
     if (!currentActivity) {
       return;
     }
     if (document.visibilityState === "hidden") {
       addPauseReason("hidden");
+      flushFinalHeartbeatBeacon();
     } else {
       removePauseReason("hidden");
+      startRelayInterval();
     }
   }
   function handleShellPause() {
@@ -1553,7 +1603,7 @@ function createTimebackActivityTracker(client) {
       }
     });
   }
-  function handlePageHide() {
+  function flushFinalHeartbeatBeacon() {
     applyOverdueInactivity();
     const activity = currentActivity;
     if (!activity) {
@@ -1564,26 +1614,34 @@ function createTimebackActivityTracker(client) {
       return;
     }
     const body = buildHeartbeatBody(activity, timing, 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 true;
+    stopRelayInterval();
+    try {
+      messaging.send("PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY" /* TIMEBACK_HEARTBEAT_RELAY */, body);
+    } catch {}
+    if (!client["initPayload"]?.hasHeartbeatRelay) {
+      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
+          });
+          return response.ok;
+        } catch {
+          return false;
         }
-      } catch {}
-      return false;
-    });
+      });
+    }
+  }
+  function handlePageHide() {
+    flushFinalHeartbeatBeacon();
   }
   function cleanupListeners() {
     if (boundVisibilityHandler && typeof document !== "undefined") {
@@ -1615,6 +1673,7 @@ function createTimebackActivityTracker(client) {
     if (currentActivity?.heartbeatIntervalId != null) {
       stopHeartbeatInterval(currentActivity);
     }
+    stopRelayInterval();
   }
   return {
     currentRunId() {
@@ -1665,6 +1724,7 @@ function createTimebackActivityTracker(client) {
         }
       }
       startHeartbeatInterval(currentActivity);
+      startRelayInterval();
       if (typeof globalThis.window !== "undefined") {
         boundPageHideHandler = handlePageHide;
         globalThis.window.addEventListener("pagehide", boundPageHideHandler);
@@ -3009,7 +3069,7 @@ async function request({
   return rawText && rawText.length > 0 ? rawText : undefined;
 }
 // src/version.ts
-var SDK_VERSION = "0.12.1-beta.1";
+var SDK_VERSION = "0.12.1-beta.2";
 
 // src/clients/base.ts
 class PlaycademyBaseClient {

package/dist/server/edge.js

@@ -233,7 +233,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.12.1-beta.1";
+var SDK_VERSION = "0.12.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/server.js

@@ -422,7 +422,7 @@ function extractApiErrorInfo(error) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.12.1-beta.1";
+var SDK_VERSION = "0.12.1-beta.2";
 
 // src/server/request.ts
 async function makeApiRequest(opts) {

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 import * as _playcademy_types from '@playcademy/types';
 import { GameManifest } from '@playcademy/types';
 export { AuthenticatedUser, DeveloperStatusEnumType, DeveloperStatusResponse, DeveloperStatusValue, GameCourseMetrics, GameLeaderboardEntry, GameManifest, GameMetricComparisonKind, GameMetricComparisonMetric, GameMetricComparisonRow, GameMetricComparisonRowStatus, GameMetricsProxyResponse, GameMetricsResponse, GameMetricsUnsupportedReason, GamePlatform, GameRunMetrics, GameRunMetricsComparison, GameRunMetricsComparisonStatus, GameRunMetricsComparisonSummary, GameTimebackIntegration, GameType, GameUser, LeaderboardEntry, LeaderboardOptions, LeaderboardTimeframe, ManifestV1, ManifestV2, ManifestVersions, PopulateStudentResponse, UserEnrollment, UserInfo, UserOrganization, UserRank, UserRankResponse, UserRoleEnumType, UserScore, UserTimebackData } from '@playcademy/types';
-import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject } from '@playcademy/types/timeback';
+import { TimebackCourseConfig, CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig, TimebackGrade, TimebackSubject, HeartbeatRequest } from '@playcademy/types/timeback';
 export { QtiTestQuestionRef, QtiTestQuestionsResponse } from '@playcademy/types/timeback';
 import { TimebackUserRole, UserEnrollment, UserOrganization, UserInfo } from '@playcademy/types/user';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
@@ -157,6 +157,12 @@ declare enum MessageEvents {
      * - `metadata?`: `Record<string, unknown>`
      */
     DEMO_END = "PLAYCADEMY_DEMO_END",
+    /**
+     * Game shares its latest TimeBack heartbeat window with the parent shell.
+     * The shell can relay this payload during top-level page teardown, which is
+     * more reliable than relying only on cross-origin iframe unload events.
+     */
+    TIMEBACK_HEARTBEAT_RELAY = "PLAYCADEMY_TIMEBACK_HEARTBEAT_RELAY",
     /**
      * Notifies about authentication state changes.
      * Can be sent in both directions depending on auth flow.
@@ -1799,6 +1805,8 @@ interface InitPayload {
     mode?: PlaycademyMode;
     /** Launch session correlation ID (UUID, set by platform on game launch) */
     launchId?: string;
+    /** When `true`, the parent shell provides a heartbeat relay via postMessage, so the SDK can skip its own `fetch({ keepalive })` beacon on pagehide. Defaults to `false`. */
+    hasHeartbeatRelay?: boolean;
 }
 /**
  * Simplified user data passed to games via InitPayload
@@ -1943,6 +1951,9 @@ interface DemoEndOptions {
 interface DemoEndPayload extends DemoEndOptions {
     score: number;
 }
+type TimebackHeartbeatRelayRequest = Omit<HeartbeatRequest, 'gameId' | 'studentId' | 'windowStartedAtMs' | 'windowSequence'> & {
+    windowStartedAtMs: number;
+};
 
 /**
  * SDK-specific API response types
@@ -2182,4 +2193,4 @@ interface AssessmentBankStatus {
 }
 
 export { PlaycademyClient };
-export type { AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };
+export type { AssessmentBankStatus, AssessmentRow, AssessmentSummary, AuthCallbackPayload, AuthOptions, AuthProviderType, AuthResult, AuthServerMessage, AuthStateChangePayload, AuthStateUpdate, BetterAuthApiKey, BetterAuthApiKeyResponse, BetterAuthSignInResponse, BucketFile, ClientConfig, ClientEvents, CourseMastery, CourseXp, DemoEndOptions, DemoEndPayload, DevUploadEvent, DevUploadHooks, EventListeners, ExternalGame, FetchedGame, Game, GameContextPayload, GameCustomHostname, GameInitUser, GameRow as GameRecord, GameTokenResponse, GetHighestGradeMasteredOptions, GetMasteryOptions, GetXpOptions, HighestGradeMasteredResponse, HostedGame, InitErrorPayload, InitPayload, KVKeyEntry, KVKeyMetadata, KVSeedEntry, KVStatsResponse, KeyEventPayload, LoginResponse, MasteryResponse, PlatformTimebackUser, PlatformTimebackUserContext, PlaycademyMode, PlaycademyServerClientConfig, PlaycademyServerClientState, ScoreSubmission, StartActivityOptions, StartActivityResult, TelemetryPayload, TimebackEnrollment, TimebackHeartbeatRelayRequest, TimebackInitContext, TimebackOrganization, TimebackUser, TimebackUserContext, TimebackUserHighestGradeMastered, TimebackUserMastery, TimebackUserRefreshField, TimebackUserRefreshOptions, TimebackUserXp, TokenRefreshPayload, TokenType, UpsertGameMetadataInput, UserRow as User, XpResponse };

package/package.json

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