Add last_changed_api_heartbeat_state_on__date to the device model

Resolves: #644
Change-type: minor

src/balena-model.ts

@@ -357,6 +357,7 @@ export interface Device {
 	id: number;
 	actor: { __id: number } | [Actor];
 	api_heartbeat_state: 'online' | 'offline' | 'timeout' | 'unknown';
+	last_changed_api_heartbeat_state_on__date: DateString | null;
 	uuid: string;
 	local_id: string | null;
 	device_name: string | null;

src/balena.sbvr

@@ -368,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 [last changed api heartbeat state on] date
+		Necessity: each device [last changed api heartbeat state on] at most one date.
+
 	Fact type: device has env var name
 		Term Form: device environment variable
 		Database Table Name: device environment variable
@@ -443,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

@@ -246,7 +246,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({
@@ -255,10 +255,17 @@ export class DeviceOnlineStateManager extends EventEmitter<{
 				id: deviceId,
 				options: {
 					$filter: {
-						$not: body,
+						$not: baseBody,
 					},
 				},
-				body,
+				body: {
+					...baseBody,
+					// Since the heartbeat manager is the only place that we update the heartbeat state
+					// we are updating the heartbeat's change date in here rather than a hook, so that
+					// we can avoid the extra DB request that a generic hook would require for checking
+					// whether the value actually changed or not.
+					last_changed_api_heartbeat_state_on__date: Date.now(),
+				},
 			});
 		} catch ($err) {
 			err = $err;

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

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

src/translations/v6/v6.sbvr

@@ -378,6 +378,9 @@ Term: device
 		Necessity: each device has exactly one api heartbeat state
 		Definition: "online" or "offline" or "timeout" or "unknown"
 
+	Fact type: device [last changed api heartbeat state on] date
+		Necessity: each device [last changed api heartbeat state on] at most one date.
+
 	Fact type: device has env var name
 		Term Form: device environment variable
 		Database Table Name: device environment variable