feat: REST API to list surfaces and set brightness

[FusselTV]

Adds a surfaces resource to the REST API from #4259: GET /api/v2/surfaces/v1 lists all known surfaces with their state (name, connection, size, brightness and current page), and PATCH /api/v2/surfaces/v1/:surfaceId sets the brightness of a connected surface. Replaces #4293, which added the same thing to the legacy /api router, as suggested there.

Use cases:

• Set or dim a surface's brightness from an external system or automation.
• A planned Home Assistant integration that exposes each surface as a light with a brightness slider.
• Read surface state over plain HTTP for dashboards or scripts.

errorResponses moved from ConnectionsRestApi.ts to RestApi/schemas/common.ts so both resources share one definition, the generated spec for connections is unchanged.

Two things I would like a view on:

• The endpoints require plain read/write rather than a resource scope like connections. Surfaces hold no secrets and there is no token UI yet, so a surfaces scope felt speculative.
• openapi-stable.json is not regenerated yet. The change is additive so the compatibility test passes, and I would rather freeze the contract once the response shape is agreed. Happy to add that commit before merge.

Tested end to end against a Stream Deck + and a Stream Deck Network Dock.

Related to #1964, #4266 and #4273.

Summary by CodeRabbit

• New Features

  • Added REST API endpoints for listing connected surfaces and updating their brightness.
  • Added validation and documented responses for surface data, page information, grid sizes, and brightness requests.
  • Added support for authorization, pagination metadata, offline surfaces, and read-only access handling.

• Bug Fixes

  • Standardized REST API error responses across endpoints.
  • Ensured surface routes are included in API routing and documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7cdba6ed-480f-44b1-9995-9e8aa25780c7

📥 Commits

Reviewing files that changed from the base of the PR and between dbd22ee and 2a56a02.

📒 Files selected for processing (2)

• companion/lib/Surface/SurfacesRestApi.ts
• companion/test/Surface/SurfacesRestApi.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• companion/test/Surface/SurfacesRestApi.test.ts
• companion/lib/Surface/SurfacesRestApi.ts

---

📝 Walkthrough

Walkthrough

Changes

The REST API now exposes typed surface listing and brightness update endpoints. Surface routes are mounted through the controller and registered in OpenAPI. Shared error responses replace the connection API’s local definition. Tests cover authorization, validation, page mapping, and surface state errors.

Surface REST API

Layer / File(s)	Summary
Surface endpoint contracts and behavior companion/lib/Surface/SurfacesRestApi.ts, companion/lib/Service/RestApi/schemas/common.ts, companion/lib/Instance/Connection/ConnectionsRestApi.ts	Adds typed surface schemas, GET and PATCH handlers, page resolution, brightness updates, OpenAPI contracts, and shared error responses.
Router and OpenAPI integration companion/lib/Surface/Controller.ts, companion/lib/Service/RestApi/RestApiRouter.ts, companion/lib/Service/RestApi/openapi.ts	Creates the surface router through SurfaceController, mounts it from registry.surfaces, and registers surface paths in OpenAPI.
Endpoint integration tests companion/test/Surface/SurfacesRestApi.test.ts, companion/test/Instance/Connection/ConnectionsRestApi.test.ts	Tests surface listing, brightness updates, authorization, validation, page mapping, unknown surfaces, disconnected surfaces, and router factory wiring.

Poem

Surfaces wake in ordered rows,
Brightness shifts where the signal flows.
Pages resolve, errors align,
OpenAPI records each sign.
Tests guard the routes with care.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a REST API to list surfaces and set brightness.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d3977468-1b42-4ce6-a952-ac9578664446

📥 Commits

Reviewing files that changed from the base of the PR and between 76656f7 and dbd22ee.

📒 Files selected for processing (8)

• companion/lib/Instance/Connection/ConnectionsRestApi.ts
• companion/lib/Service/RestApi/RestApiRouter.ts
• companion/lib/Service/RestApi/openapi.ts
• companion/lib/Service/RestApi/schemas/common.ts
• companion/lib/Surface/Controller.ts
• companion/lib/Surface/SurfacesRestApi.ts
• companion/test/Instance/Connection/ConnectionsRestApi.test.ts
• companion/test/Surface/SurfacesRestApi.test.ts

[Copilot]

Pull request overview

Adds a new Surfaces resource to the v2 REST API, enabling external systems (e.g. automations/Home Assistant) to query surface state and set brightness via scoped bearer-token auth, with OpenAPI registration.

Changes:

• Added GET /api/v2/surfaces/v1 to list all known surfaces and their current state (incl. page context).
• Added PATCH /api/v2/surfaces/v1/:surfaceId to set brightness for a connected surface.
• Centralized shared OpenAPI error response definitions (errorResponses) for reuse across resources, and registered the new resource in OpenAPI generation.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
companion/test/Surface/SurfacesRestApi.test.ts	New e2e-style router tests for listing surfaces and patching brightness (auth + error cases).
companion/test/Instance/Connection/ConnectionsRestApi.test.ts	Updates REST API router test registry wiring to include the new surfaces resource.
companion/lib/Surface/SurfacesRestApi.ts	Implements surfaces REST router, zod schemas, endpoint specs, and OpenAPI path registration.
companion/lib/Surface/Controller.ts	Exposes createRestApiRouter() on SurfaceController to mount the surfaces REST resource via the registry.
companion/lib/Service/RestApi/schemas/common.ts	Adds shared errorResponses definition for OpenAPI endpoint specs.
companion/lib/Service/RestApi/RestApiRouter.ts	Mounts the new surfaces router under the v2 REST API base path.
companion/lib/Service/RestApi/openapi.ts	Registers surfaces endpoints into the generated OpenAPI document.
companion/lib/Instance/Connection/ConnectionsRestApi.ts	Switches connections resource to reuse the shared errorResponses definition.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.