Add the device.last_api_heartbeat_change_date term to the model

Resolves: #644
Change-type: minor

src/balena-model.ts

@@ -682,6 +682,7 @@ export interface Device {
 		id: Types['Serial']['Read'];
 		actor: { __id: Actor['Read']['id'] } | [Actor['Read']];
 		api_heartbeat_state: 'online' | 'offline' | 'timeout' | 'unknown';
+		last_api_heartbeat_change_date: Types['Date Time']['Read'] | null;
 		uuid: Types['Text']['Read'];
 		local_id: Types['Short Text']['Read'] | null;
 		device_name: Types['Short Text']['Read'] | null;
@@ -777,6 +778,7 @@ export interface Device {
 		id: Types['Serial']['Write'];
 		actor: Actor['Write']['id'];
 		api_heartbeat_state: 'online' | 'offline' | 'timeout' | 'unknown';
+		last_api_heartbeat_change_date: Types['Date Time']['Write'] | null;
 		uuid: Types['Text']['Write'];
 		local_id: Types['Short Text']['Write'] | null;
 		device_name: Types['Short Text']['Write'] | null;

src/balena.sbvr

@@ -82,6 +82,9 @@ Term: alias
 Term: api heartbeat state
 	Concept Type: Short Text (Type)
 
+Term: last api heartbeat change date
+	Concept Type: Date Time (Type)
+
 Term: api port
 	Concept Type: Integer (Type)
 
@@ -368,6 +371,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 change date
+		Necessity: each device has at most one last api heartbeat change date.
+
 	Fact type: device has env var name
 		Term Form: device environment variable
 		Database Table Name: device environment variable
@@ -445,7 +451,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

@@ -259,7 +259,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({
@@ -268,10 +268,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_api_heartbeat_change_date: Date.now(),
+				},
 			});
 		} catch ($err) {
 			err = $err;

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

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

src/translations/v6/v6.sbvr

@@ -82,6 +82,9 @@ Term: alias
 Term: api heartbeat state
 	Concept Type: Short Text (Type)
 
+Term: last api heartbeat change date
+	Concept Type: Date Time (Type)
+
 Term: api port
 	Concept Type: Integer (Type)
 
@@ -378,6 +381,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 change date
+		Necessity: each device has at most one last api heartbeat change date.
+
 	Fact type: device has env var name
 		Term Form: device environment variable
 		Database Table Name: device environment variable