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/hooks.ts

@@ -0,0 +1,9 @@
+import { hooks } from '@balena/pinejs';
+
+hooks.addPureHook('PATCH', 'resin', 'device', {
+	POSTPARSE: ({ request }) => {
+		if (request.values.api_heartbeat_state != null) {
+			request.values.last_api_heartbeat_state_change_event = new Date();
+		}
+	},
+});

src/hooks.ts

@@ -4,6 +4,7 @@ import './features/application-types/hooks';
 import './features/ci-cd/hooks';
 import './features/cascade-delete/hooks';
 import './features/devices/hooks';
+import './features/device-heartbeat/hooks';
 import './features/device-types/hooks';
 import './features/device-urls/hooks';
 import './features/hostapp/hooks';

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;