Enhance container port metadata with protocol, label, and browsable flag (#24)

* feat: sub-container port state — protocol, label and browsable flag (spec C.7/C.3)

Adapt the SDK to GladysAssistant/Gladys#2786, which adds a `browsable`
field (default true) to the manifest sub-container ports and returns the
full port shape from `GET /container`: a port that serves no web UI (a
WebSocket endpoint waiting for devices, the OCPP case) is shown as a
plain badge instead of an "Open" link.

- ContainerPort typings resynced with the core state: `protocol`, `label`
  and `browsable` added, `host_port` corrected to `number | null` (no
  host port is allocated before the first start); new exported
  ContainerPortProtocol union
- getContainers JSDoc + README document the full port entry and what
  browsable: false means for the integration
- tests: the getContainers fixture carries the real port shape, plus a
  non-browsable port with an unassigned host port; compile-time checks on
  the new fields

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WxpcyV2TFQvTJkYdTa9YET

* test(types): assert host_port nullability with a direct assignment

The optional chaining on `containers[0]?.ports[0]?.host_port` contributes
`undefined` on its own, so the widened `number | null | undefined`
annotation type-checked even when `host_port` was `number` — the check
did not actually prove the field is nullable. Assign `null` straight to
`ContainerPort['host_port']` instead, which fails to compile without the
null in the type.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WxpcyV2TFQvTJkYdTa9YET

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Pierre-Gilles

README.md

@@ -124,7 +124,7 @@ All methods return Promises; host API errors are thrown as `GladysApiError { sta
 | `getConfig()` / `setConfig(partialConfig)` | Configuration values; `getConfig` also refreshes `gladys.config`                                                                                                                                                                                                                                                                                                                                                                      |
 | `getStatus()`                              | Gladys version + integration service status                                                                                                                                                                                                                                                                                                                                                                                           |
 | `setConnectionStatus(connected, message?)` | Application-level connection status shown in the Configuration screen (`message` is an optional multi-language object, e.g. `{ en: 'Token expired' }`). Distinct from the container state machine: a cloud integration can be RUNNING and still disconnected from its third-party service                                                                                                                                             |
-| `getContainers()`                          | Sub-containers declared in the manifest: Docker status, desired state, assigned host ports, granted/available hardware classes                                                                                                                                                                                                                                                                                                        |
+| `getContainers()`                          | Sub-containers declared in the manifest: Docker status, desired state, published ports (`{ container_port, protocol, host_port, label, browsable }`, `host_port: null` while none is assigned yet), granted/available hardware classes                                                                                                                                                                                                |
 | `startContainer(name, { env }?)`           | Creates (if needed) and starts a declared sub-container — typically after generating its config files in `/data`; `env` carries runtime-computed values (secrets never go through the public manifest)                                                                                                                                                                                                                                |
 | `stopContainer(name)`                      | Stops a sub-container; the supervisor will not restart it                                                                                                                                                                                                                                                                                                                                                                             |
 | `restartContainer(name)`                   | Restarts a sub-container, e.g. after rewriting its config through `/data`                                                                                                                                                                                                                                                                                                                                                             |
@@ -607,6 +607,19 @@ const detector = coral.granted && coral.available ? 'edgetpu' : 'cpu'; // adapt
 When the user changes the hardware grants, the affected sub-containers are recreated and `onHardwareUpdated` fires:
 regenerate the configs and (re)start what is needed.
 
+Each entry of `container.ports` mirrors the manifest declaration plus the host port Gladys allocated:
+
+```js
+// [{ container_port: 5000, protocol: 'tcp', host_port: 42115, label: { en: 'Frigate UI' }, browsable: true }]
+const [{ host_port: frigatePort }] = frigate.ports;
+```
+
+The host port is **chosen by Gladys** (a free port, persisted across recreations — never declared in the manifest),
+so read it here rather than assuming one; it is `null` as long as none has been assigned (the container has never
+started). `browsable` mirrors the manifest field: `true` (default) for a port serving a web UI — the supervision
+screen shows an "Open <label>" link — and `false` for a port a browser cannot open, e.g. a WebSocket endpoint
+waiting for devices (the OCPP case), which is shown as a plain `<label> : <host_port>` badge instead.
+
 ### Mediated network discovery
 
 Integration containers run on a bridge network: LAN **broadcast, mDNS and SSDP traffic never reaches them**, and a

index.d.ts

@@ -105,10 +105,25 @@ export interface PublishDiscoveredDevicesResponse extends SuccessResponse {
  */
 export type MultiLanguageMessage = { en: string } & Record<string, string>;
 
+/** Protocol of a published sub-container port. */
+export type ContainerPortProtocol = 'tcp' | 'udp';
+
 /** A published port of a sub-container, with the host port assigned by Gladys. */
 export interface ContainerPort {
   container_port: number;
-  host_port: number;
+  /** Protocol declared in the manifest, `tcp` when omitted. */
+  protocol: ContainerPortProtocol;
+  /** Host port assigned by Gladys, `null` while none has been allocated yet. */
+  host_port: number | null;
+  /** Multi-language label of the port, as declared in the manifest. */
+  label: MultiLanguageMessage;
+  /**
+   * Whether the port serves a web UI reachable from a browser. `false` (manifest
+   * `browsable: false`, e.g. a WebSocket endpoint waiting for devices) — the
+   * supervision screen shows the assigned host port as a badge, without the
+   * "Open" link.
+   */
+  browsable: boolean;
 }
 
 /** State of one requested hardware class of a sub-container (contract C.3). */

lib/gladys-integration.js

@@ -865,7 +865,10 @@ class GladysIntegration extends EventEmitter {
    * @description Fetch the sub-containers declared in the manifest: their
    * Docker status, desired state, assigned host ports and, per requested
    * hardware class, the granted/available flags (contract C.3) — how the
-   * integration knows what to put in its generated configs.
+   * integration knows what to put in its generated configs. Each port carries
+   * `{ container_port, protocol, host_port, label, browsable }`; `host_port` is
+   * `null` while Gladys has not allocated one yet, and `browsable: false` marks
+   * a port that serves no web UI (a WebSocket endpoint for devices, say).
    * @returns {Promise<Array>} The containers; empty if none is declared.
    * @example
    * const containers = await gladys.getContainers();

test/containers.test.js

@@ -43,13 +43,48 @@ describe('connection status & sub-container methods', () => {
           status: 'stopped',
           desired: 'stopped',
           started_at: null,
-          ports: [{ container_port: 5000, host_port: 42115 }],
+          ports: [
+            {
+              container_port: 5000,
+              protocol: 'tcp',
+              host_port: 42115,
+              label: { en: 'Frigate UI', fr: 'Interface Frigate' },
+              browsable: true,
+            },
+          ],
           devices: [{ class: 'coral-usb', granted: true, available: true }],
         },
       ];
       const containers = await gladys.getContainers();
       assert.deepEqual(containers, server.containers);
     });
+
+    it('should keep the browsable flag and the not-yet-assigned host port of a port', async () => {
+      // OCPP-like case: a WebSocket endpoint for devices, no web UI to open
+      server.containers = [
+        {
+          name: 'ocpp',
+          status: 'stopped',
+          desired: 'stopped',
+          started_at: null,
+          ports: [
+            {
+              container_port: 9000,
+              protocol: 'tcp',
+              host_port: null,
+              label: { en: 'OCPP WebSocket' },
+              browsable: false,
+            },
+          ],
+          devices: [],
+        },
+      ];
+      const [container] = await gladys.getContainers();
+      assert.equal(container.ports[0].browsable, false);
+      assert.equal(container.ports[0].host_port, null);
+      assert.equal(container.ports[0].protocol, 'tcp');
+      assert.deepEqual(container.ports[0].label, { en: 'OCPP WebSocket' });
+    });
   });
 
   describe('gladys.startContainer(name, options?)', () => {

test/types/api.test-d.ts

@@ -4,6 +4,8 @@
  */
 import {
   ActionFields,
+  ContainerPort,
+  ContainerPortProtocol,
   createLogger,
   Device,
   DEVICE_FEATURE_CATEGORIES,
@@ -144,13 +146,18 @@ const main = async (): Promise<void> => {
 
   await gladys.setConnectionStatus(false, { en: 'Token expired, please reconnect.', fr: 'Token expiré.' });
   const containers: IntegrationContainer[] = await gladys.getContainers();
-  const hostPort: number | undefined = containers[0]?.ports[0]?.host_port;
+  const hostPort: number | null | undefined = containers[0]?.ports[0]?.host_port;
+  // direct assignment: the optional chaining above would type-check even without the null
+  const unassignedHostPort: ContainerPort['host_port'] = null;
+  const portProtocol: ContainerPortProtocol | undefined = containers[0]?.ports[0]?.protocol;
+  const browsable: boolean | undefined = containers[0]?.ports[0]?.browsable;
+  const portLabel: string | undefined = containers[0]?.ports[0]?.label.en;
   await gladys.startContainer('mqtt', { env: { MQTT_PASSWORD: 's3cr3t' } });
   await gladys.startContainer('mqtt');
   await gladys.stopContainer('mqtt');
   await gladys.restartContainer('frigate');
   const oauthType: string = WEBSOCKET_MESSAGE_TYPES.EXTERNAL_INTEGRATION.OAUTH_GET_AUTHORIZE_URL;
-  void [hostPort, oauthType];
+  void [hostPort, unassignedHostPort, portProtocol, browsable, portLabel, oauthType];
 
   gladys.onWebhook('events', async (request: WebhookRequest) => {
     const line: string = `${request.method} ${request.body ?? ''} ${request.contentType ?? ''}`;