feat(devices): compute effective online status with stale heartbeat ttl

Backend/utils/device-status.ts

@@ -0,0 +1,32 @@
+import { getDeviceOnlineStaleSeconds } from './env';
+
+export type EffectiveDeviceStatus = 'online' | 'offline';
+
+type EffectiveDeviceStatusParams = {
+  status: string | null | undefined;
+  lastSeenAt: Date | null | undefined;
+  now?: Date;
+  staleAfterSeconds?: number;
+};
+
+export const getEffectiveDeviceStatus = ({
+  status,
+  lastSeenAt,
+  now = new Date(),
+  staleAfterSeconds = getDeviceOnlineStaleSeconds(),
+}: EffectiveDeviceStatusParams): EffectiveDeviceStatus => {
+  if (status !== 'online') {
+    return 'offline';
+  }
+
+  if (!(lastSeenAt instanceof Date) || Number.isNaN(lastSeenAt.getTime())) {
+    return 'offline';
+  }
+
+  const elapsedMs = now.getTime() - lastSeenAt.getTime();
+  if (elapsedMs < 0) {
+    return 'online';
+  }
+
+  return elapsedMs <= staleAfterSeconds * 1000 ? 'online' : 'offline';
+};

Backend/utils/env.ts

@@ -32,3 +32,19 @@ export const getRequiredEnv = (name: string): string => {
 export const getBetterAuthBaseUrl = (): string => {
   return getFirstDefinedEnv('BETTER_AUTH_BASE_URL', 'BETTER_AUTH_URL') ?? `http://localhost:${process.env.PORT ?? '3000'}`;
 };
+
+const DEFAULT_DEVICE_ONLINE_STALE_SECONDS = 30;
+
+export const getDeviceOnlineStaleSeconds = (): number => {
+  const value = getFirstDefinedEnv('DEVICE_ONLINE_STALE_SECONDS');
+  if (!value) {
+    return DEFAULT_DEVICE_ONLINE_STALE_SECONDS;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    return DEFAULT_DEVICE_ONLINE_STALE_SECONDS;
+  }
+
+  return parsed;
+};