feat: add deviceActionMessages to StudioBlueprintManifest and resolve action errors server-side

Author: rjmunro

meteor/server/api/client.ts

@@ -30,6 +30,7 @@ import {
 } from '../security/check'
 import { UserActionsLog } from '../collections'
 import { executePeripheralDeviceFunctionWithCustomTimeout } from './peripheralDevice/executeFunction'
+import { resolveActionResult } from './peripheralDevice'
 import { LeveledLogMethodFixed } from '@sofie-automation/corelib/dist/logging'
 import { assertConnectionHasOneOfPermissions } from '../security/auth'
 
@@ -458,7 +459,7 @@ class ServerClientAPIClass extends MethodContextAPI implements NewClientAPI {
 		actionId: string,
 		payload?: Record<string, any>
 	) {
-		return ServerClientAPI.callPeripheralDeviceFunctionOrAction(
+		const result = await ServerClientAPI.callPeripheralDeviceFunctionOrAction(
 			this,
 			context,
 			deviceId,
@@ -470,6 +471,7 @@ class ServerClientAPIClass extends MethodContextAPI implements NewClientAPI {
 			actionId,
 			payload
 		)
+		return resolveActionResult(deviceId, result)
 	}
 	async callBackgroundPeripheralDeviceFunction(
 		deviceId: PeripheralDeviceId,

meteor/server/api/peripheralDevice.ts

@@ -74,7 +74,7 @@ import { assertConnectionHasOneOfPermissions } from '../security/auth'
 import { DBStudio } from '@sofie-automation/corelib/dist/dataModel/Studio'
 import { getRootSubpath } from '../lib'
 import { evalBlueprint } from './blueprints/cache'
-import { StudioBlueprintManifest } from '@sofie-automation/blueprints-integration'
+import { StudioBlueprintManifest, TSR } from '@sofie-automation/blueprints-integration'
 import { StatusMessageResolver } from '@sofie-automation/corelib'
 import { interpollateTranslation } from '@sofie-automation/corelib/dist/TranslatableMessage'
 import { Blueprint } from '@sofie-automation/corelib/dist/dataModel/Blueprint'
@@ -188,6 +188,82 @@ async function resolveDeviceStatusDetails(
 	}
 }
 
+/**
+ * Resolve a TSR ActionExecutionResult using the Studio blueprint's deviceActionMessages.
+ * If the result has a structured `code` and `context`, and the blueprint defines a custom
+ * message template for that code, the `response` field is replaced with the resolved message.
+ *
+ * @param deviceId - The peripheral device ID (used to look up the studio and blueprint)
+ * @param result - The action execution result from TSR
+ * @returns The result with `response` resolved if a custom message was found
+ */
+export async function resolveActionResult(
+	deviceId: PeripheralDeviceId,
+	result: TSR.ActionExecutionResult
+): Promise<TSR.ActionExecutionResult> {
+	if (result.result === TSR.ActionExecutionResultCode.Ok) return result
+	if (!result.code) return result
+
+	try {
+		const device = (await PeripheralDevices.findOneAsync(deviceId, {
+			projection: { name: 1, studioAndConfigId: 1 },
+		})) as Pick<PeripheralDevice, 'name' | 'studioAndConfigId'> | undefined
+
+		if (!device?.studioAndConfigId?.studioId) return result
+
+		const studio = (await Studios.findOneAsync(device.studioAndConfigId.studioId, {
+			projection: { blueprintId: 1 },
+		})) as Pick<DBStudio, 'blueprintId'> | undefined
+
+		if (!studio?.blueprintId) return result
+
+		const blueprint = (await Blueprints.findOneAsync(studio.blueprintId, {
+			projection: { _id: 1, name: 1, code: 1 },
+		})) as Pick<Blueprint, '_id' | 'name' | 'code'> | undefined
+
+		if (!blueprint) return result
+
+		const blueprintManifest = evalBlueprint(blueprint) as StudioBlueprintManifest
+
+		if (!blueprintManifest.deviceActionMessages) return result
+
+		const resolver = new StatusMessageResolver(blueprint._id, blueprintManifest.deviceActionMessages, undefined)
+
+		// Use the existing TSR response as the fallback default message
+		const defaultMessage = result.response?.key ?? ''
+
+		const resolved = resolver.getDeviceStatusMessage(
+			result.code,
+			{
+				...(result.context ?? {}),
+				deviceName: device.name,
+				deviceId: unprotectString(deviceId),
+			},
+			defaultMessage
+		)
+
+		if (resolved === null) {
+			// Message suppressed by blueprint
+			return result
+		}
+
+		// resolved.key is either the custom blueprint message or the defaultMessage
+		if (resolved.key === defaultMessage) {
+			// No custom message found - keep original response unchanged
+			return result
+		}
+
+		const interpolated = interpollateTranslation(resolved.key, resolved.args)
+		return {
+			...result,
+			response: { key: interpolated },
+		}
+	} catch (e) {
+		logger.error(`Error resolving device action messages: ${e}`)
+		return result
+	}
+}
+
 export namespace ServerPeripheralDeviceAPI {
 	export async function initialize(
 		context: MethodContext,

packages/blueprints-integration/src/api/studio.ts

@@ -109,6 +109,31 @@ export interface StudioBlueprintManifest<
 	 */
 	deviceStatusMessages?: Record<string, string | DeviceStatusMessageFunction>
 
+	/**
+	 * Alternate device action error messages, to override the default messages from TSR devices.
+	 * Keys are action error code strings from TSR devices (e.g., 'ACTION_HTTPSEND_REQUEST_FAILED').
+	 *
+	 * Similar to deviceStatusMessages but applies to device action execution failures
+	 * (e.g., HTTP Send failures, device restart failures) rather than ongoing status errors.
+	 *
+	 * Import action error codes from 'timeline-state-resolver-types' for type safety.
+	 * Values can be:
+	 * - String templates using {{variable}} syntax for interpolation with context values
+	 * - Functions that receive DeviceStatusContext and return a custom message string
+	 * - Empty string to suppress the message entirely (action result will show as generic error)
+	 *
+	 * @example
+	 * ```typescript
+	 * import { HttpSendActionErrorCode } from 'timeline-state-resolver-types'
+	 *
+	 * deviceActionMessages: {
+	 *   [HttpSendActionErrorCode.REQUEST_FAILED]: 'Failed to trigger graphics: {{errorMessage}}',
+	 *   [HttpSendActionErrorCode.MISSING_URL]: 'HTTP action not configured - missing URL',
+	 * }
+	 * ```
+	 */
+	deviceActionMessages?: Record<string, string | DeviceStatusMessageFunction | undefined>
+
 	/** Returns the items used to build the baseline (default state) of a studio, this is the baseline used when there's no active rundown */
 	getBaseline: (context: IStudioBaselineContext) => BlueprintResultStudioBaseline