feat(companion): add publishHeartbeat helper across platform clients

src/companion/index.ts

@@ -41,5 +41,6 @@ export type {
   PlatformClientOptions,
   RegisterPushTokenInput,
   SharedStatusInput,
+  HeartbeatStatusInput,
   PlatformBootstrapResult,
 } from './platformClients.js';

src/companion/platformClients.integration.test.ts

@@ -121,7 +121,7 @@ describe('platform clients integration', () => {
       const boot = await client.bootstrap();
       expect(boot.register.registered).toBe(true);
       expect(boot.capabilities.node.id).toBe('macos-e2e');
-      const status = await client.setStatus({
+      const status = await client.publishHeartbeat({
         appVersion: '1.0.0',
         statusText: 'menu-bar-active',
         powerSource: 'ac',

src/companion/platformClients.test.ts

@@ -168,4 +168,19 @@ describe('platform companion clients', () => {
       capabilities: expect.any(Object),
     });
   });
+
+  it('publishHeartbeat uses safe defaults for status payload', async () => {
+    const mock = createRuntimeMock();
+    const client = new AndroidCompanionClient({ runtime: mock.runtime, nodeId: 'android-node' });
+
+    await client.publishHeartbeat();
+
+    expect(mock.setNodeStatus).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: 'android',
+        statusText: 'heartbeat',
+        powerSource: 'unknown',
+      }),
+    );
+  });
 });

src/companion/platformClients.ts

@@ -38,6 +38,14 @@ export type SharedStatusInput = Omit<
   'platform'
 >;
 
+export interface HeartbeatStatusInput {
+  appVersion?: SharedStatusInput['appVersion'];
+  deviceName?: SharedStatusInput['deviceName'];
+  statusText?: SharedStatusInput['statusText'];
+  batteryPct?: SharedStatusInput['batteryPct'];
+  powerSource?: SharedStatusInput['powerSource'];
+}
+
 export interface PlatformBootstrapResult {
   register: NodeRegisterResult;
   capabilities: NodeCapabilitiesResult;
@@ -96,6 +104,16 @@ export class MacOSCompanionClient {
     });
   }
 
+  publishHeartbeat(input: HeartbeatStatusInput = {}): Promise<NodeStatusSetResult> {
+    return this.setStatus({
+      appVersion: input.appVersion,
+      deviceName: input.deviceName,
+      statusText: input.statusText ?? 'heartbeat',
+      batteryPct: input.batteryPct,
+      powerSource: input.powerSource ?? 'unknown',
+    });
+  }
+
   setLocation(location: SetNodeLocationInput): Promise<NodeLocationSetResult> {
     return this.runtime.setNodeLocation(location);
   }
@@ -195,6 +213,16 @@ export class IOSCompanionClient {
     });
   }
 
+  publishHeartbeat(input: HeartbeatStatusInput = {}): Promise<NodeStatusSetResult> {
+    return this.setStatus({
+      appVersion: input.appVersion,
+      deviceName: input.deviceName,
+      statusText: input.statusText ?? 'heartbeat',
+      batteryPct: input.batteryPct,
+      powerSource: input.powerSource ?? 'unknown',
+    });
+  }
+
   setLocation(location: SetNodeLocationInput): Promise<NodeLocationSetResult> {
     return this.runtime.setNodeLocation(location);
   }
@@ -294,6 +322,16 @@ export class AndroidCompanionClient {
     });
   }
 
+  publishHeartbeat(input: HeartbeatStatusInput = {}): Promise<NodeStatusSetResult> {
+    return this.setStatus({
+      appVersion: input.appVersion,
+      deviceName: input.deviceName,
+      statusText: input.statusText ?? 'heartbeat',
+      batteryPct: input.batteryPct,
+      powerSource: input.powerSource ?? 'unknown',
+    });
+  }
+
   setLocation(location: SetNodeLocationInput): Promise<NodeLocationSetResult> {
     return this.runtime.setNodeLocation(location);
   }