feat: Status message customisation by rjmunro · Pull Request #418 · Sofie-Automation/sofie-timeline-state-resolver

rjmunro · 2026-01-14T18:01:14Z

About the Contributor

This pull request is posted on behalf of the BBC.

Type of Contribution

This is a Feature.

Current Behavior

Errors are reported as plain strings. This makes them hard to understand in an machine readable way by e.g. sofie blueprints or translate.

New Behavior

Errors will include error codes and context as well as the message for backwards compatibility.

Testing Instructions

Other Information

Status

PR is ready to be reviewed.
The functionality has been tested by the author.
Relevant unit tests has been added / updated.
Relevant documentation (code comments, system documentation) has been added / updated.

coderabbitai · 2026-01-14T18:01:19Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

Walkthrough

Introduces a structured device-status model: adds DeviceStatusDetail and DeviceStatusInput; changes template interpolation; converts many device integrations to emit typed statusDetails[] via new create...StatusDetail helpers; DeviceInstance normalises DeviceStatusInput → DeviceStatus(active); types/exports and tests updated.

Changes

Structured status core

Layer / File(s)	Summary
Data Shape & new detail type `packages/timeline-state-resolver-types/src/deviceStatusDetail.ts`, `packages/timeline-state-resolver-types/src/device.ts`	Add `DeviceStatusDetail<TCode,TContext>`; add optional `statusDetails?: DeviceStatusDetail[]` to `DeviceStatus`; add exported `DeviceStatusInput` union (messages-based
Template API change `packages/timeline-state-resolver-types/src/templateString.ts`, `packages/timeline-state-resolver-types/src/__tests__/templateString.spec.ts`	Change `interpolateTemplateString(template, context)` signature and behavior: only `{{word}}` placeholders; preserve `{{key}}` when context value is undefined/null; default context in helper.
Public re-exports `packages/timeline-state-resolver-types/src/index.ts`	Re-export new typings modules (`integrations/httpWatcher.js`, `deviceStatusDetail.js`).

Per-integration status typing & messages

Layer / File(s)	Summary
Status code/type additions `packages/timeline-state-resolver-types/src/integrations/*.ts`	Add per-integration `StatusCode` consts, derived union types, `StatusContextMap`, `StatusDetail<T> = DeviceStatusDetail<..., ...>`, and `StatusMessages` for many integrations (atem, casparCG, httpWatcher, hyperdeck, lawo, obs, osc, panasonicPTZ, pharos, quantel, shotoku, sisyfos, sofieChef, telemetrics, tricaster, vizMSE, vmix, websocketClient, etc.).

Message factory helpers

Layer / File(s)	Summary
create...StatusDetail helpers `packages/timeline-state-resolver/src/integrations/*/messages.ts`	Add typed `create<Integration>StatusDetail<T>(code, context)` helpers that enforce context shape and produce `{ code, context, message }` by interpolating `*StatusMessages[code]` (fallback to `code`).

Integrations: getStatus migrations

Layer / File(s)	Summary
Integration getStatus `packages/timeline-state-resolver/src/integrations/*/index.ts`	Change many device `getStatus()` signatures to return `DeviceStatusInput`; replace `messages: string[]` with `statusDetails: DeviceStatusDetail[]`; persist `init` options where needed; add defensive guards for optional connections.
HTTP watcher specifics `packages/timeline-state-resolver/src/integrations/httpWatcher/index.ts`	Refactor to emit specific `HTTPWatcherStatusDetail` codes and use `_setStatus` to compare serialized details and emit `connectionChanged` on change.
WebSocket connection tracking `packages/timeline-state-resolver/src/integrations/websocketClient/connection.ts`	Track `lastError` and `disconnectReason`; `connectionStatus()` returns `DeviceStatusInput` with `CONNECTION_FAILED` / `NOT_CONNECTED` `statusDetails` carrying context.

Device core, normalization, and API

Layer / File(s)	Summary
DeviceInstance normalization `packages/timeline-state-resolver/src/service/DeviceInstance.ts`	Add `normaliseDeviceStatus(DeviceStatusInput, active)` to convert inputs into full `DeviceStatus` with `active`; `getStatus()` returns normalized `DeviceStatus`; `connectionChanged` handlers accept `DeviceStatusInput` and emit normalized `DeviceStatus`; constructor order adjusted so `deviceName` set before device instantiation.
Device core typings `packages/timeline-state-resolver/src/devices/device.ts`, `packages/timeline-state-resolver/src/integrations/abstract/index.ts`	Switch legacy device/event types to use `DeviceStatusInput` for `getStatus()` / `connectionChanged` payloads.
Public API updates `packages/timeline-state-resolver-api/src/device.ts`, `packages/timeline-state-resolver-api/src/tsr-api.ts`	Expose `DeviceStatusInput` in re-exports; add `deviceName: string` to `DeviceContextAPI`; update `getStatus()` and `connectionChanged` callback typings to use `DeviceStatusInput`.

Tests & helpers

Layer / File(s)	Summary
Test updates `packages/timeline-state-resolver/src/integrations//__tests__/.spec.ts`, `packages/timeline-state-resolver/src/service/__tests__/deviceInstance.spec.ts`, `packages/timeline-state-resolver-types/src/__tests__/templateString.spec.ts`	Update assertions to expect `statusDetails` arrays and new template interpolation behavior; add `deviceName` to mocked `DeviceContextAPI` in test helpers.
Integration test adjustments examples: `.../atem/__tests__/atem.spec.ts`, `.../httpWatcher/__tests__/httpwatcher.spec.ts`, `.../hyperdeck/__tests__/hyperdeck.spec.ts`, `.../telemetrics/__tests__/telemetrics.spec.ts`	Replace string-message assertions with structured `DeviceStatusDetail` objects or message-match expectations on `statusDetails` entries.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Integration as Device Integration
  participant DeviceInstance as DeviceInstance / Context
  participant Normaliser as normaliseDeviceStatus
  participant Consumers as Event Consumers

  Integration->>DeviceInstance: connectionChanged(status: DeviceStatusInput) / getStatus() -> DeviceStatusInput
  DeviceInstance->>Normaliser: normaliseDeviceStatus(statusInput, active?)
  Normaliser-->>DeviceInstance: DeviceStatus { statusCode, statusDetails, active }
  DeviceInstance->>Consumers: emit normalized DeviceStatus

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Sofie-Automation/sofie-timeline-state-resolver#424 — overlaps Sisyfos integration/status changes.
Sofie-Automation/sofie-timeline-state-resolver#434 — related udpSend integration/type adjustments.
Sofie-Automation/sofie-timeline-state-resolver#444 — related OGraf/status-typing updates.

Suggested labels

Contribution from BBC

Suggested reviewers

Julusian
jstarpl

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

rjmunro · 2026-01-14T18:02:27Z

@coderabbitai review

coderabbitai · 2026-01-14T18:02:33Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@packages/timeline-state-resolver/README.md`:
- Around line 129-134: The example uses a placeholder comment for the context
parameter type in createMyDeviceError; replace it with a mapped type so the
context is strongly typed (e.g., use MyDeviceErrorContextMap[T] as the context
type) and ensure a MyDeviceErrorContextMap type exists mapping each
MyDeviceErrorCode to its context shape; update the function signature for
createMyDeviceError<T extends MyDeviceErrorCode>(code: T, context:
MyDeviceErrorContextMap[T]): DeviceStatusError<T> and import/declare
MyDeviceErrorContextMap where needed so the example compiles and gives concrete
types for each error code.

In `@packages/timeline-state-resolver/src/deviceErrorMessages.ts`:
- Around line 34-38: The JSDoc example output is inconsistent with the template
interpolation: update the example so the output matches the actual template
behavior used by errorsToMessages; either adjust the allMessages template for
AtemErrorCode.DISCONNECTED to not include {{host}} or change the expected
messages array to include the host (e.g., "ATEM disconnected from
192.168.1.10"); reference the AtemErrorCode.DISCONNECTED entry and the
errorsToMessages/allMessages usage in the example and ensure the example's input
context (host) and expected output align.

In `@packages/timeline-state-resolver/src/index.ts`:
- Around line 12-18: The export lists a non-existent symbol AtemErrorContext
causing the build to fail; update the export block to remove AtemErrorContext
and instead export the actual context types exported by the errors module
(AtemErrorContextMap, AtemDisconnectedContext, AtemPsuFaultContext) or re-export
whichever specific context aliases you need (e.g., export type AtemErrorContext
= AtemErrorContextMap if you prefer a single alias), ensuring the exported
symbols match those declared in the './integrations/atem/errors' module.

🧹 Nitpick comments (1)

packages/timeline-state-resolver/src/__tests__/deviceErrorMessages.spec.ts (1)
11-13: Minor: Test context differs from actual definition.

The test defines host: string as required, but in errors.ts, AtemDisconnectedContext has host?: string (optional). This inconsistency is minor since it doesn't affect test correctness, but consider aligning them for consistency.
♻️ Suggested fix
 interface AtemDisconnectedContext extends DeviceErrorContextBase {
-	host: string
+	host?: string
 }

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dddc23e and 4031274.

📒 Files selected for processing (10)

packages/timeline-state-resolver-types/src/device.ts
packages/timeline-state-resolver-types/src/deviceError.ts
packages/timeline-state-resolver-types/src/index.ts
packages/timeline-state-resolver/README.md
packages/timeline-state-resolver/src/__tests__/deviceErrorMessages.spec.ts
packages/timeline-state-resolver/src/deviceErrorMessages.ts
packages/timeline-state-resolver/src/index.ts
packages/timeline-state-resolver/src/integrations/atem/__tests__/atem.spec.ts
packages/timeline-state-resolver/src/integrations/atem/errors.ts
packages/timeline-state-resolver/src/integrations/atem/index.ts

🧰 Additional context used

🧬 Code graph analysis (4)

packages/timeline-state-resolver-types/src/device.ts (1)

packages/timeline-state-resolver-types/src/deviceError.ts (1)

DeviceStatusError (27-35)

packages/timeline-state-resolver/src/deviceErrorMessages.ts (1)

packages/timeline-state-resolver-types/src/deviceError.ts (1)

DeviceStatusError (27-35)

packages/timeline-state-resolver/src/integrations/atem/errors.ts (1)

packages/timeline-state-resolver-types/src/deviceError.ts (2)

DeviceErrorContextBase (5-8)

DeviceStatusError (27-35)

packages/timeline-state-resolver/src/__tests__/deviceErrorMessages.spec.ts (3)

packages/timeline-state-resolver/src/index.ts (2)

AtemErrorCode (14-14)

AtemErrorMessages (15-15)

packages/timeline-state-resolver-types/src/deviceError.ts (2)

DeviceErrorContextBase (5-8)

DeviceStatusError (27-35)

packages/timeline-state-resolver/src/deviceErrorMessages.ts (1)

errorsToMessages (40-48)

🪛 GitHub Actions: Node CI

packages/timeline-state-resolver-types/src/deviceError.ts