@dronedeploy/rocos-js-sdk 4.1.0 → 4.2.1

package/esm/services/MapService.js

@@ -1,4 +1,4 @@
-import { API_GRAPHS_MAPS_COPY_URL, API_GRAPHS_MAPS_DEPLOYED_URL, API_GRAPHS_MAPS_DEPLOY_URL, API_GRAPHS_MAPS_GEOJSON_URL, API_GRAPHS_MAPS_MERGE_URL, API_GRAPHS_MAPS_NEW_URL, API_GRAPHS_MAPS_URL, API_GRAPHS_MAP_CONTENT_URL, API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL, API_GRAPHS_MAP_EDGES_ADD_URL, API_GRAPHS_MAP_EDGE_URL, API_GRAPHS_MAP_ID_URL, API_GRAPHS_MAP_METADATA_URL, API_GRAPHS_MAP_NODES_ADD_TRANSFORMABLE_URL, API_GRAPHS_MAP_NODES_ADD_URL, API_GRAPHS_MAP_NODE_URL, API_GRAPHS_OBSERVATIONS_URL, API_GRAPHS_OBSERVATION_KEYS_URL, API_GRAPHS_PANORAMA, API_GRAPHS_PANORAMAS_URL, API_GRAPHS_PANORAMA_OBSERVATIONS_URL, } from '../constants/api';
+import { API_GRAPHS_MAPS_COPY_URL, API_GRAPHS_MAPS_DEPLOYED_URL, API_GRAPHS_MAPS_DEPLOY_URL, API_GRAPHS_MAPS_GEOJSON_URL, API_GRAPHS_MAPS_MERGE_URL, API_GRAPHS_MAPS_NEW_URL, API_GRAPHS_MAPS_URL, API_GRAPHS_MAP_CONTENT_URL, API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL, API_GRAPHS_MAP_EDGES_ADD_URL, API_GRAPHS_MAP_EDGE_URL, API_GRAPHS_MAP_ID_URL, API_GRAPHS_MAP_METADATA_URL, API_GRAPHS_MAP_NODES_ADD_TRANSFORMABLE_URL, API_GRAPHS_MAP_NODES_ADD_URL, API_GRAPHS_MAP_NODE_URL, API_GRAPHS_MAP_PATHS_URL, API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL, API_GRAPHS_MAP_PATH_APPEND_URL, API_GRAPHS_MAP_PATH_URL, API_GRAPHS_OBSERVATIONS_URL, API_GRAPHS_OBSERVATION_KEYS_URL, API_GRAPHS_PANORAMA, API_GRAPHS_PANORAMAS_URL, API_GRAPHS_PANORAMA_OBSERVATIONS_URL, } from '../constants/api';
 import { RocosError, errorCodes } from '../models';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 import { RocosLogger } from '../logger/RocosLogger';
@@ -451,4 +451,144 @@ export class MapService extends BaseServiceAbstract {
     deleteEdge(projectId, mapId, edgeId) {
         return this.callDelete(formatServiceUrl(API_GRAPHS_MAP_EDGE_URL, { url: this.config.url, projectId, mapId, edgeId }, this.config.insecure), 'Failed to delete edge.');
     }
+    /**
+     * List the paths (polylines/polygons) in a map. A path is a sub-graph following the
+     * `go-common/graph/paths` convention shared with the rocos-agent's map component; this
+     * mirrors the agent's `paths/list` service, returning the parent node ids of every path
+     * that survives the filters.
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map to list paths from.
+     * @param filter Optional closed-flag and parent-node-type filters. The type filter goes
+     * over the wire as one comma-separated query parameter, so types containing a comma
+     * cannot be expressed (see {@link ListPathsFilter.types}).
+     * @returns The path ids (= parent node ids), sorted.
+     */
+    async listPaths(projectId, mapId, filter) {
+        const queryParams = {};
+        if (filter?.closed !== undefined)
+            queryParams.closed = filter.closed.toString();
+        if (filter?.types?.length)
+            queryParams.types = filter.types.join(',');
+        const resp = await this.callGet(formatServiceUrl(API_GRAPHS_MAP_PATHS_URL, { url: this.config.url, projectId, mapId }, this.config.insecure), 'Failed to list paths.', queryParams);
+        return resp.paths;
+    }
+    /**
+     * Get one path: its closed flag, full parent node, and ordered member node ids — the same
+     * shape as the agent's `paths/get` response. An existing node with no path structure is
+     * reported as an empty open path; a missing node is 404; stored structure violating the
+     * path convention (e.g. multiple start edges) is 422 (repair it with {@link replacePath}).
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map the path lives in.
+     * @param pathId The path id (= parent node id).
+     */
+    getPath(projectId, mapId, pathId) {
+        return this.callGet(formatServiceUrl(API_GRAPHS_MAP_PATH_URL, { url: this.config.url, projectId, mapId, pathId }, this.config.insecure), 'Failed to get path.');
+    }
+    /**
+     * Append already-existing member nodes to a path, creating the path when absent —
+     * mirroring the agent's `paths/append`. Members must already exist (400 otherwise);
+     * `path.index` numbering continues from the existing member count. A `closed` value
+     * conflicting with a non-empty path's stored flag is rejected with 409 (unlike the agent,
+     * which silently ignores it) — change closed-ness with {@link replacePath}.
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map the path lives in.
+     * @param pathId The path id (= parent node id).
+     * @param body The members to append, plus optional closed flag and parent data.
+     */
+    async appendToPath(projectId, mapId, pathId, body) {
+        await this.callPost(formatServiceUrl(API_GRAPHS_MAP_PATH_APPEND_URL, { url: this.config.url, projectId, mapId, pathId }, this.config.insecure), body, 'Failed to append to path.');
+    }
+    /**
+     * Create one positioned vertex node per point and append them all to a path in one
+     * transaction — the cloud analog of the agent's `paths/append/currentPosition`, with the
+     * caller supplying positions instead of the robot's live pose. Every point must carry a
+     * transform (append only creates; use {@link appendToPath} for existing nodes); a point id
+     * that already exists is a 409 and the whole append rolls back.
+     *
+     * Wire-shape note: the server receives each point's transform as
+     * `{ rotation, translation }`. This method marshals the caller-facing `rot`/`pos`
+     * (matching the node/panorama transform naming) onto that shape before POSTing.
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map the path lives in.
+     * @param pathId The path id (= parent node id).
+     * @param body The frame, points, and optional node type / closed flag / parent data.
+     * @returns The created vertex node ids, in path order (server-minted UUIDs for blank ids).
+     */
+    appendTransformablePointsToPath(projectId, mapId, pathId, body) {
+        const wireBody = {
+            closed: body.closed,
+            data: body.data,
+            frame: body.frame,
+            nodeType: body.nodeType,
+            points: body.points.map((p) => this.pathPointToWire(p)),
+        };
+        return this.callPost(formatServiceUrl(API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL, { url: this.config.url, projectId, mapId, pathId }, this.config.insecure), wireBody, 'Failed to append points to path.');
+    }
+    /**
+     * Replace a path's entire structure in one idempotent call — the editor primitive for
+     * vertex move/insert/delete/reorder and closed-flag changes. See {@link ReplacePathRequest}
+     * for the full semantics; the essentials:
+     *
+     * - A point WITH a transform declares its position; for the path's own vertices, same id +
+     *   new transform = a move. A transform on a node the path doesn't exclusively own is 409.
+     * - A point WITHOUT a transform reuses an existing node in place (400 if missing).
+     * - Old vertices exclusively owned by the path and not re-referenced are deleted; shared
+     *   members are detached, never moved or deleted.
+     * - `parentType` must match an existing parent (409) or be omitted; it applies on create.
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map the path lives in.
+     * @param pathId The path id (= parent node id).
+     * @param body The path's desired state.
+     */
+    async replacePath(projectId, mapId, pathId, body) {
+        const wireBody = {
+            closed: body.closed,
+            parentType: body.parentType,
+            nodeType: body.nodeType,
+            data: body.data,
+            frame: body.frame,
+            points: body.points.map((p) => this.pathPointToWire(p)),
+        };
+        await this.callPut(formatServiceUrl(API_GRAPHS_MAP_PATH_URL, { url: this.config.url, projectId, mapId, pathId }, this.config.insecure), wireBody, 'Failed to replace path.');
+    }
+    /**
+     * Delete a path's structure, mirroring the agent's `paths/delete`: idempotent (a missing
+     * path still returns success), member nodes preserved by default, and the parent node
+     * itself deleted only when it is a pure `path.parent.v1` (an anchored path keeps its
+     * anchor node, minus the path edges).
+     *
+     * With `deleteMembers`, member nodes exclusively owned by the path (no remaining edges
+     * beyond their positioning `TRANSFORM`) are also removed; anything referenced elsewhere
+     * survives. Access rules match {@link deleteNode}: environment off-limits, dronedeploy
+     * admin-only, normal maps open to any caller with project access.
+     *
+     * @param projectId The ID of the project the map belongs to.
+     * @param mapId The ID of the map the path lives in.
+     * @param pathId The path id (= parent node id).
+     * @param opts Set `deleteMembers` to also remove exclusively-owned vertex nodes.
+     */
+    deletePath(projectId, mapId, pathId, opts) {
+        let url = formatServiceUrl(API_GRAPHS_MAP_PATH_URL, { url: this.config.url, projectId, mapId, pathId }, this.config.insecure);
+        if (opts?.deleteMembers)
+            url += '?deleteMembers=true';
+        return this.callDelete(url, 'Failed to delete path.');
+    }
+    /**
+     * Marshal a caller-facing {@link PathPoint} onto the server's wire shape: `rot`/`pos`
+     * become `rotation`/`translation`, and an absent transform stays absent (its presence
+     * carries intent in a replace). A missing `rot` is left for the server to default to
+     * identity.
+     */
+    pathPointToWire(p) {
+        return {
+            id: p.id,
+            data: p.data,
+            transform: p.transform ? { rotation: p.transform.rot, translation: p.transform.pos } : undefined,
+        };
+    }
 }

package/esm/services/robot-status/connectivity.d.ts

@@ -0,0 +1,65 @@
+import { IConnectedCallsign, RobotConnectivity, RobotConnectivityStatus, ServiceConnection } from '../../models';
+import { Observable } from 'rxjs';
+/**
+ * Service id → public path prefix, for services that expose the standard
+ * `connections` endpoint. New services adopting the convention are added here.
+ * The `telemetry` (Teletubby) endpoint joins this once built — see EAI-718/719.
+ */
+export declare const CONNECTION_SERVICE_PREFIXES: Record<string, string>;
+/**
+ * The telemetry-liveness signal is derived from heartbeat freshness rather than
+ * an HTTP endpoint, so it is handled specially (its observable is supplied by
+ * the caller). See `getTelemetryLiveness`.
+ */
+export declare const TELEMETRY_LIVENESS_SERVICE = "telemetry-liveness";
+/**
+ * The services evaluated by default. The `telemetry` connections endpoint joins
+ * this list once Teletubby exposes it (follow-up).
+ */
+export declare const DEFAULT_EXPECTED_SERVICES: string[];
+/** Authenticated GET used to poll a service's `connections` endpoint. */
+export type ConnectionsHttpGet = (url: string) => Promise<IConnectedCallsign>;
+/**
+ * Builds the `connections` endpoint URL for a service — per-callsign when a
+ * callsign is given, otherwise the bulk per-project variant.
+ */
+export declare const buildConnectionsUrl: (serviceId: string, baseUrl: string, projectId: string, callsign?: string, insecure?: boolean) => string;
+/** Maps a `connections` endpoint response onto a {@link ServiceConnection}. */
+export declare const mapConnectionStatus: (connection?: IConnectedCallsign | null) => ServiceConnection;
+/**
+ * Aggregates per-service connection states into an overall verdict:
+ * - `ONLINE`   — at least one service connected and none disconnected.
+ * - `DEGRADED` — a genuine mix: some connected, some disconnected.
+ * - `OFFLINE`  — nothing connected.
+ *
+ * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup
+ * settles on `OFFLINE` (gray) rather than a spurious flashing-red degraded state.
+ *
+ * Note: this optimism also means a service held `UNKNOWN` indefinitely (e.g. an
+ * endpoint whose polls keep failing) does not by itself pull the aggregate below
+ * `ONLINE` — a deliberate v1 tradeoff to keep transient errors from flapping the
+ * indicator. Surfacing a long-lived failure distinctly (likely via health rather
+ * than connectivity) is left as a future refinement.
+ */
+export declare const aggregateConnectivity: (services: Record<string, ServiceConnection>) => RobotConnectivity;
+/**
+ * Polls a single service's `connections` endpoint on an interval, emitting its
+ * {@link ServiceConnection} (change-only). A failed/timed-out poll yields
+ * `UNKNOWN` (held transitional) rather than `DISCONNECTED`, to avoid a spurious
+ * degraded flash on a transient error.
+ */
+export declare const getServiceConnectionChanges: (httpGet: ConnectionsHttpGet, url: string, pollMs?: number) => Observable<ServiceConnection>;
+export interface ConnectivityDeps {
+    httpGet: ConnectionsHttpGet;
+    baseUrl: string;
+    insecure?: boolean;
+    /** The telemetry-liveness signal (from `getTelemetryLiveness`), folded in as one service. */
+    telemetryLiveness$: Observable<ServiceConnection>;
+}
+/**
+ * Emits the robot's {@link RobotConnectivityStatus} — the per-service breakdown
+ * plus the aggregate verdict — for the configured `expectedServices`. HTTP
+ * services are polled; `telemetry-liveness` uses the supplied observable; any
+ * unrecognised service id resolves to `UNKNOWN`.
+ */
+export declare const getConnectivityChanges: (deps: ConnectivityDeps, projectId: string, callsign: string, expectedServices?: string[], pollMs?: number) => Observable<RobotConnectivityStatus>;

package/esm/services/robot-status/connectivity.js

@@ -0,0 +1,120 @@
+import { API_SERVICE_CONNECTIONS_URL, API_SERVICE_CONNECTION_URL } from '../../constants/api';
+import { ConnectionStatus, RobotConnectivity, ServiceConnection, } from '../../models';
+import { catchError, combineLatest, distinctUntilChanged, from, map, of, startWith, switchMap, timer, } from 'rxjs';
+import { formatServiceUrl } from '../../helpers/formatServiceUrl';
+/**
+ * Service id → public path prefix, for services that expose the standard
+ * `connections` endpoint. New services adopting the convention are added here.
+ * The `telemetry` (Teletubby) endpoint joins this once built — see EAI-718/719.
+ */
+export const CONNECTION_SERVICE_PREFIXES = {
+    'robot-configs': 'robot-configs',
+    'robot-services': 'robot-services',
+};
+/**
+ * The telemetry-liveness signal is derived from heartbeat freshness rather than
+ * an HTTP endpoint, so it is handled specially (its observable is supplied by
+ * the caller). See `getTelemetryLiveness`.
+ */
+export const TELEMETRY_LIVENESS_SERVICE = 'telemetry-liveness';
+/**
+ * The services evaluated by default. The `telemetry` connections endpoint joins
+ * this list once Teletubby exposes it (follow-up).
+ */
+export const DEFAULT_EXPECTED_SERVICES = [TELEMETRY_LIVENESS_SERVICE, 'robot-configs', 'robot-services'];
+const DEFAULT_CONNECTIVITY_POLL_MS = 5000;
+/**
+ * Builds the `connections` endpoint URL for a service — per-callsign when a
+ * callsign is given, otherwise the bulk per-project variant.
+ */
+export const buildConnectionsUrl = (serviceId, baseUrl, projectId, callsign, insecure) => {
+    const template = callsign ? API_SERVICE_CONNECTION_URL : API_SERVICE_CONNECTIONS_URL;
+    const params = { url: baseUrl, service: CONNECTION_SERVICE_PREFIXES[serviceId], projectId };
+    if (callsign)
+        params.callsign = callsign;
+    return formatServiceUrl(template, params, insecure);
+};
+/** Maps a `connections` endpoint response onto a {@link ServiceConnection}. */
+export const mapConnectionStatus = (connection) => {
+    if (connection?.status === ConnectionStatus.CONNECTED)
+        return ServiceConnection.CONNECTED;
+    if (connection?.status === ConnectionStatus.DISCONNECTED)
+        return ServiceConnection.DISCONNECTED;
+    return ServiceConnection.UNKNOWN;
+};
+/**
+ * Aggregates per-service connection states into an overall verdict:
+ * - `ONLINE`   — at least one service connected and none disconnected.
+ * - `DEGRADED` — a genuine mix: some connected, some disconnected.
+ * - `OFFLINE`  — nothing connected.
+ *
+ * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup
+ * settles on `OFFLINE` (gray) rather than a spurious flashing-red degraded state.
+ *
+ * Note: this optimism also means a service held `UNKNOWN` indefinitely (e.g. an
+ * endpoint whose polls keep failing) does not by itself pull the aggregate below
+ * `ONLINE` — a deliberate v1 tradeoff to keep transient errors from flapping the
+ * indicator. Surfacing a long-lived failure distinctly (likely via health rather
+ * than connectivity) is left as a future refinement.
+ */
+export const aggregateConnectivity = (services) => {
+    const values = Object.values(services);
+    const hasConnected = values.includes(ServiceConnection.CONNECTED);
+    const hasDisconnected = values.includes(ServiceConnection.DISCONNECTED);
+    if (hasConnected && hasDisconnected)
+        return RobotConnectivity.DEGRADED;
+    if (hasConnected)
+        return RobotConnectivity.ONLINE;
+    return RobotConnectivity.OFFLINE;
+};
+/**
+ * Polls a single service's `connections` endpoint on an interval, emitting its
+ * {@link ServiceConnection} (change-only). A failed/timed-out poll yields
+ * `UNKNOWN` (held transitional) rather than `DISCONNECTED`, to avoid a spurious
+ * degraded flash on a transient error.
+ */
+export const getServiceConnectionChanges = (httpGet, url, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    return timer(0, pollMs).pipe(switchMap(() => {
+        return from(httpGet(url)).pipe(map(mapConnectionStatus), catchError(() => of(ServiceConnection.UNKNOWN)));
+    }), startWith(ServiceConnection.UNKNOWN), distinctUntilChanged());
+};
+const connectivityEquals = (a, b) => {
+    if (a.overall !== b.overall)
+        return false;
+    const keys = Object.keys(a.services);
+    if (keys.length !== Object.keys(b.services).length)
+        return false;
+    return keys.every((key) => a.services[key] === b.services[key]);
+};
+/**
+ * Emits the robot's {@link RobotConnectivityStatus} — the per-service breakdown
+ * plus the aggregate verdict — for the configured `expectedServices`. HTTP
+ * services are polled; `telemetry-liveness` uses the supplied observable; any
+ * unrecognised service id resolves to `UNKNOWN`.
+ */
+export const getConnectivityChanges = (deps, projectId, callsign, expectedServices = DEFAULT_EXPECTED_SERVICES, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    // combineLatest([]) completes without emitting; emit an explicit empty/offline status instead.
+    if (expectedServices.length === 0) {
+        return of({ overall: RobotConnectivity.OFFLINE, services: {} });
+    }
+    const perService = expectedServices.map((serviceId) => {
+        let source$;
+        if (serviceId === TELEMETRY_LIVENESS_SERVICE) {
+            source$ = deps.telemetryLiveness$;
+        }
+        else if (serviceId in CONNECTION_SERVICE_PREFIXES) {
+            const url = buildConnectionsUrl(serviceId, deps.baseUrl, projectId, callsign, deps.insecure);
+            source$ = getServiceConnectionChanges(deps.httpGet, url, pollMs);
+        }
+        else {
+            source$ = of(ServiceConnection.UNKNOWN);
+        }
+        return source$.pipe(startWith(ServiceConnection.UNKNOWN), map((connection) => ({ serviceId, connection })));
+    });
+    return combineLatest(perService).pipe(map((entries) => {
+        const services = {};
+        for (const { serviceId, connection } of entries)
+            services[serviceId] = connection;
+        return { overall: aggregateConnectivity(services), services };
+    }), distinctUntilChanged(connectivityEquals));
+};

package/esm/services/robot-status/reportedStatus.d.ts

@@ -0,0 +1,38 @@
+import { Observable } from 'rxjs';
+import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+import { TelemetryService } from '../TelemetryService';
+/** The new agent topic carrying health + readiness (replaces the heartbeat). */
+export declare const ROBOT_STATUS_SOURCE = "/diagnostics/robot/status";
+/** The legacy heartbeat topic — liveness only, no status payload. */
+export declare const LEGACY_HEARTBEAT_SOURCE = "/rocos/agent/telemetry/heartbeat";
+export interface ReportedRobotStatus {
+    health: RobotHealth;
+    readiness: RobotReadiness;
+}
+/**
+ * Maps a `robot/status` wire value (integer, or its string equivalent) to a
+ * {@link RobotHealth}. Anything unrecognised — including `0` / `'unknown'` —
+ * resolves to {@link RobotHealth.UNKNOWN}.
+ */
+export declare const parseRobotHealth: (value: unknown) => RobotHealth;
+/** As {@link parseRobotHealth}, for {@link RobotReadiness}. */
+export declare const parseRobotReadiness: (value: unknown) => RobotReadiness;
+/**
+ * Emits the robot's reported health/readiness, subscribing to the new
+ * `robot/status` topic and the legacy heartbeat concurrently.
+ *
+ * The new topic takes precedence: once any `robot/status` message has been seen,
+ * legacy heartbeats no longer affect the reported value. While only the legacy
+ * heartbeat is present, a live heartbeat is reported as `NORMAL`/`IDLE` — which
+ * preserves today's "online ⇒ green" behaviour for agents not yet emitting the
+ * new topic.
+ */
+export declare const getReportedStatusChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<ReportedRobotStatus>;
+/**
+ * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
+ * either the new `robot/status` topic or the legacy heartbeat) has been received
+ * within `heartbeatTimeoutMs`. Mirrors {@link TelemetryService.monitorTelemetryWithTimeout}
+ * but spans both topics and maps onto {@link ServiceConnection} so it can be
+ * folded into connectivity aggregation as just another service entry.
+ */
+export declare const getTelemetryLiveness: (telemetry: TelemetryService, projectId: string, callsign: string, heartbeatTimeoutMs?: number, intervalMs?: number) => Observable<ServiceConnection>;

package/esm/services/robot-status/reportedStatus.js

@@ -0,0 +1,102 @@
+import { catchError, combineLatest, distinctUntilChanged, filter, interval, map, merge, of, scan, startWith, } from 'rxjs';
+import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+/** The new agent topic carrying health + readiness (replaces the heartbeat). */
+export const ROBOT_STATUS_SOURCE = '/diagnostics/robot/status';
+/** The legacy heartbeat topic — liveness only, no status payload. */
+export const LEGACY_HEARTBEAT_SOURCE = '/rocos/agent/telemetry/heartbeat';
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5000;
+const DEFAULT_INTERVAL_MS = 2000;
+/**
+ * Maps a `robot/status` wire value (integer, or its string equivalent) to a
+ * {@link RobotHealth}. Anything unrecognised — including `0` / `'unknown'` —
+ * resolves to {@link RobotHealth.UNKNOWN}.
+ */
+export const parseRobotHealth = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'normal':
+            return RobotHealth.NORMAL;
+        case 2:
+        case '2':
+        case 'abnormal':
+            return RobotHealth.ABNORMAL;
+        case 3:
+        case '3':
+        case 'critical':
+            return RobotHealth.CRITICAL;
+        default:
+            return RobotHealth.UNKNOWN;
+    }
+};
+/** As {@link parseRobotHealth}, for {@link RobotReadiness}. */
+export const parseRobotReadiness = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'idle':
+            return RobotReadiness.IDLE;
+        case 2:
+        case '2':
+        case 'busy':
+            return RobotReadiness.BUSY;
+        default:
+            return RobotReadiness.UNKNOWN;
+    }
+};
+/**
+ * Emits the robot's reported health/readiness, subscribing to the new
+ * `robot/status` topic and the legacy heartbeat concurrently.
+ *
+ * The new topic takes precedence: once any `robot/status` message has been seen,
+ * legacy heartbeats no longer affect the reported value. While only the legacy
+ * heartbeat is present, a live heartbeat is reported as `NORMAL`/`IDLE` — which
+ * preserves today's "online ⇒ green" behaviour for agents not yet emitting the
+ * new topic.
+ */
+export const getReportedStatusChanges = (telemetry, projectId, callsign) => {
+    const new$ = telemetry
+        .subscribe({ projectId, callsigns: [callsign], sources: [ROBOT_STATUS_SOURCE] })
+        .pipe(map((message) => ({
+        from: 'new',
+        status: {
+            health: parseRobotHealth(message.payload?.health),
+            readiness: parseRobotReadiness(message.payload?.readiness),
+        },
+    })));
+    const legacy$ = telemetry.subscribe({ projectId, callsigns: [callsign], sources: [LEGACY_HEARTBEAT_SOURCE] }).pipe(map(() => ({
+        from: 'legacy',
+        status: { health: RobotHealth.NORMAL, readiness: RobotReadiness.IDLE },
+    })));
+    return merge(new$, legacy$).pipe(scan((acc, event) => {
+        if (event.from === 'new')
+            return { seenNew: true, status: event.status };
+        // Legacy heartbeat: only honoured until the new topic has been seen.
+        return acc.seenNew ? acc : { seenNew: false, status: event.status };
+    }, { seenNew: false, status: undefined }), map((acc) => acc.status), filter((status) => status !== undefined), distinctUntilChanged((a, b) => a.health === b.health && a.readiness === b.readiness), 
+    // A telemetry error would otherwise terminate this stream permanently; fall back to
+    // UNKNOWN/UNKNOWN (matching getTelemetryLiveness) so subscribers get an honest value.
+    catchError(() => of({ health: RobotHealth.UNKNOWN, readiness: RobotReadiness.UNKNOWN })));
+};
+/**
+ * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
+ * either the new `robot/status` topic or the legacy heartbeat) has been received
+ * within `heartbeatTimeoutMs`. Mirrors {@link TelemetryService.monitorTelemetryWithTimeout}
+ * but spans both topics and maps onto {@link ServiceConnection} so it can be
+ * folded into connectivity aggregation as just another service entry.
+ */
+export const getTelemetryLiveness = (telemetry, projectId, callsign, heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS) => {
+    const startedAt = Date.now();
+    const lastMessageAt$ = telemetry
+        .subscribe({ projectId, callsigns: [callsign], sources: [ROBOT_STATUS_SOURCE, LEGACY_HEARTBEAT_SOURCE] })
+        .pipe(map(() => Date.now()));
+    return combineLatest([lastMessageAt$.pipe(startWith(startedAt)), interval(intervalMs)]).pipe(map(([lastMessageAt]) => {
+        const now = Date.now();
+        // No message yet, but still within the initial grace period.
+        if (lastMessageAt === startedAt && now - startedAt <= heartbeatTimeoutMs)
+            return ServiceConnection.UNKNOWN;
+        if (now - lastMessageAt > heartbeatTimeoutMs)
+            return ServiceConnection.DISCONNECTED;
+        return ServiceConnection.CONNECTED;
+    }), startWith(ServiceConnection.UNKNOWN), distinctUntilChanged(), catchError(() => of(ServiceConnection.UNKNOWN)));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dronedeploy/rocos-js-sdk",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Javascript SDK for rocos",
   "main": "cjs/index.js",
   "module": "esm/index.js",