Add last_api_heartbeat_state_change_event to the device model

Resolves: #644
Change-type: minor

src/balena-model.ts

@@ -350,6 +350,7 @@ export interface Device {
 	id: number;
 	actor: number;
 	api_heartbeat_state: 'online' | 'offline' | 'timeout' | 'unknown';
+	last_api_heartbeat_state_change_event: DateString | null;
 	uuid: string;
 	local_id: string | null;
 	device_name: string | null;

src/balena.sbvr

@@ -160,6 +160,9 @@ Term: known issue list
 Term: label name
 	Concept Type: Short Text (Type)
 
+Term: last api heartbeat state change event
+	Concept Type: Date Time (Type)
+
 Term: last connectivity event
 	Concept Type: Date Time (Type)
 
@@ -365,6 +368,9 @@ Term: device
 		Necessity: each device has exactly one api heartbeat state
 		Definition: "online" or "offline" or "timeout" or "unknown"
 
+	Fact type: device has last api heartbeat state change event
+		Necessity: each device has at most one last api heartbeat state change event.
+
 	Fact type: device has env var name
 		Term Form: device environment variable
 		Database Table Name: device environment variable
@@ -440,7 +446,7 @@ Fact type: user (Auth) has public key
 -- user public key
 
 Fact type: user public key has title
-    Necessity: each user public key has exactly one title
+	Necessity: each user public key has exactly one title
 
 
 -- application type

src/features/device-heartbeat/index.ts

@@ -245,7 +245,7 @@ export class DeviceOnlineStateManager extends EventEmitter<{
 
 		try {
 			// patch the api_heartbeat_state value to the new state...
-			const body = {
+			const baseBody = {
 				api_heartbeat_state: newState,
 			};
 			await api.resin.patch({
@@ -254,10 +254,13 @@ export class DeviceOnlineStateManager extends EventEmitter<{
 				id: deviceId,
 				options: {
 					$filter: {
-						$not: body,
+						$not: baseBody,
 					},
 				},
-				body,
+				body: {
+					...baseBody,
+					last_api_heartbeat_state_change_event: Date.now(),
+				},
 			});
 		} catch ($err) {
 			err = $err;

src/migrations/0077-device-last-api-heartbeat-state-change-event.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "device"
+ADD COLUMN IF NOT EXISTS "last api heartbeat state change event" TIMESTAMP NULL;