@dronedeploy/rocos-js-sdk 4.1.1 → 4.3.0-rc.1

package/cjs/services/RobotStatusService.d.ts

@@ -0,0 +1,37 @@
+import { IBaseService, IRocosSDKConfig, RobotConnectivityStatus, RobotStatus, RocosError } from '../models';
+import { Observable } from 'rxjs';
+import { ReportedRobotStatus } from './robot-status/reportedStatus';
+import { BaseServiceAbstract } from './BaseServiceAbstract';
+/** Per-call tuning for the robot status observables. */
+export interface RobotStatusOptions {
+    /** Services whose connectivity gates ONLINE/DEGRADED. Defaults to the standard expected-services set. */
+    expectedServices?: string[];
+    /** How long without a heartbeat before telemetry-liveness is considered dead (ms). */
+    heartbeatTimeoutMs?: number;
+    /** How often the connections endpoints are polled (ms, floored internally). */
+    connectivityPollMs?: number;
+}
+/**
+ * The single source of truth for a robot's status. It composes the reported
+ * status (health/readiness from the heartbeat), per-service connectivity, and
+ * the canonical indicator colour, so consumers subscribe to one observable
+ * rather than deriving "is the robot online" themselves.
+ */
+export declare class RobotStatusService extends BaseServiceAbstract implements IBaseService {
+    constructor(config: IRocosSDKConfig);
+    getStatus(): boolean;
+    /** Health + readiness as reported by the robot (new topic, legacy heartbeat fallback). */
+    getReportedStatusChanges(projectId: string, callsign: string): Observable<ReportedRobotStatus>;
+    /** Per-service connectivity plus the aggregate verdict, polled. */
+    getConnectivityChanges(projectId: string, callsign: string, opts?: RobotStatusOptions): Observable<RobotConnectivityStatus>;
+    /** One-shot connectivity snapshot: resolves once every expected service is known, or after a timeout. */
+    getConnectivity(projectId: string, callsign: string, opts?: RobotStatusOptions): Promise<RobotConnectivityStatus>;
+    /**
+     * The headline stream: the combined {@link RobotStatus} including the canonical
+     * colour token. This is what status indicators subscribe to.
+     */
+    getRobotStatusChanges(projectId: string, callsign: string, opts?: RobotStatusOptions): Observable<RobotStatus>;
+    protected getError(e: Error): RocosError;
+    private get telemetryService();
+    private connectivityDeps;
+}

package/cjs/services/RobotStatusService.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RobotStatusService = void 0;
+const connectivity_1 = require("./robot-status/connectivity");
+const models_1 = require("../models");
+const rxjs_1 = require("rxjs");
+const reportedStatus_1 = require("./robot-status/reportedStatus");
+const BaseServiceAbstract_1 = require("./BaseServiceAbstract");
+const RocosLogger_1 = require("../logger/RocosLogger");
+const RocosStore_1 = require("../store/RocosStore");
+const getRobotStatusColour_1 = require("../helpers/getRobotStatusColour");
+/** Upper bound on how long the one-shot {@link RobotStatusService.getConnectivity} waits to settle. */
+const ONE_SHOT_TIMEOUT_MS = 10000;
+const isKnown = (status) => {
+    return Object.values(status.services).every((connection) => connection !== models_1.ServiceConnection.UNKNOWN);
+};
+const robotStatusEquals = (a, b) => {
+    if (a.health !== b.health || a.readiness !== b.readiness)
+        return false;
+    if (a.connectivity.overall !== b.connectivity.overall)
+        return false;
+    const keys = Object.keys(a.connectivity.services);
+    if (keys.length !== Object.keys(b.connectivity.services).length)
+        return false;
+    return keys.every((key) => a.connectivity.services[key] === b.connectivity.services[key]);
+};
+/**
+ * The single source of truth for a robot's status. It composes the reported
+ * status (health/readiness from the heartbeat), per-service connectivity, and
+ * the canonical indicator colour, so consumers subscribe to one observable
+ * rather than deriving "is the robot online" themselves.
+ */
+class RobotStatusService extends BaseServiceAbstract_1.BaseServiceAbstract {
+    constructor(config) {
+        super(config);
+        this.logger = RocosLogger_1.RocosLogger.getInstance(`RobotStatusService(${this.config.url})`);
+    }
+    getStatus() {
+        return true;
+    }
+    /** Health + readiness as reported by the robot (new topic, legacy heartbeat fallback). */
+    getReportedStatusChanges(projectId, callsign) {
+        return (0, reportedStatus_1.getReportedStatusChanges)(this.telemetryService, projectId, callsign);
+    }
+    /** Per-service connectivity plus the aggregate verdict, polled. */
+    getConnectivityChanges(projectId, callsign, opts) {
+        return (0, connectivity_1.getConnectivityChanges)(this.connectivityDeps(projectId, callsign, opts), projectId, callsign, opts?.expectedServices, opts?.connectivityPollMs);
+    }
+    /** One-shot connectivity snapshot: resolves once every expected service is known, or after a timeout. */
+    getConnectivity(projectId, callsign, opts) {
+        // Capture the latest snapshot explicitly: on timeout, refCount teardown would otherwise
+        // hand a fresh (all-UNKNOWN seed) re-subscription to the fallback rather than the last value.
+        let latest;
+        const changes$ = this.getConnectivityChanges(projectId, callsign, opts).pipe((0, rxjs_1.tap)((status) => {
+            latest = status;
+        }), (0, rxjs_1.shareReplay)({ bufferSize: 1, refCount: true }));
+        return (0, rxjs_1.firstValueFrom)(changes$.pipe((0, rxjs_1.first)(isKnown), 
+        // Don't wait forever on a persistently-unknown service — fall back to the latest snapshot seen.
+        (0, rxjs_1.timeout)({ first: ONE_SHOT_TIMEOUT_MS, with: () => (latest ? (0, rxjs_1.of)(latest) : changes$.pipe((0, rxjs_1.take)(1))) })));
+    }
+    /**
+     * The headline stream: the combined {@link RobotStatus} including the canonical
+     * colour token. This is what status indicators subscribe to.
+     */
+    getRobotStatusChanges(projectId, callsign, opts) {
+        const reported$ = this.getReportedStatusChanges(projectId, callsign).pipe(
+        // Seed so the combined stream emits (e.g. gray) before the first heartbeat arrives.
+        (0, rxjs_1.startWith)({ health: models_1.RobotHealth.UNKNOWN, readiness: models_1.RobotReadiness.UNKNOWN }));
+        const connectivity$ = this.getConnectivityChanges(projectId, callsign, opts);
+        return (0, rxjs_1.combineLatest)([reported$, connectivity$]).pipe((0, rxjs_1.map)(([reported, connectivity]) => ({
+            health: reported.health,
+            readiness: reported.readiness,
+            connectivity,
+            colour: (0, getRobotStatusColour_1.getRobotStatusColour)({ health: reported.health, readiness: reported.readiness, connectivity }),
+        })), (0, rxjs_1.distinctUntilChanged)(robotStatusEquals));
+    }
+    getError(e) {
+        return new models_1.RocosError(e, models_1.errorCodes.ROBOT_STATUS_SERVICE_ERROR);
+    }
+    get telemetryService() {
+        return RocosStore_1.RocosStore.getSDKInstance(this.config).getTelemetryService();
+    }
+    connectivityDeps(projectId, callsign, opts) {
+        return {
+            httpGet: (url) => {
+                return this.callGet(url, `Failed to get connection status for ${callsign} in project ${projectId}.`);
+            },
+            baseUrl: this.config.url,
+            insecure: this.config.insecure,
+            telemetryLiveness$: (0, reportedStatus_1.getTelemetryLiveness)(this.telemetryService, projectId, callsign, opts?.heartbeatTimeoutMs),
+        };
+    }
+}
+exports.RobotStatusService = RobotStatusService;

package/cjs/services/index.d.ts

@@ -17,6 +17,7 @@ export * from './ProfileService';
 export * from './ProjectService';
 export * from './RTPWebRTCService';
 export * from './RobotService';
+export * from './RobotStatusService';
 export * from './ScheduleService';
 export * from './SearchService';
 export * from './SpotProvisioningService';

package/cjs/services/index.js

@@ -33,6 +33,7 @@ __exportStar(require("./ProfileService"), exports);
 __exportStar(require("./ProjectService"), exports);
 __exportStar(require("./RTPWebRTCService"), exports);
 __exportStar(require("./RobotService"), exports);
+__exportStar(require("./RobotStatusService"), exports);
 __exportStar(require("./ScheduleService"), exports);
 __exportStar(require("./SearchService"), exports);
 __exportStar(require("./SpotProvisioningService"), exports);

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

@@ -0,0 +1,76 @@
+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[];
+/**
+ * Floor for the connections-endpoint poll interval. Guards against a caller
+ * passing `0` (or any tiny value), which would otherwise poll the API on every
+ * event-loop tick.
+ */
+export declare const MIN_CONNECTIVITY_POLL_MS = 250;
+/** Clamps a requested poll interval up to {@link MIN_CONNECTIVITY_POLL_MS}. */
+export declare const clampPollInterval: (pollMs: number) => number;
+/** 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.
+ *
+ * `pollMs` is floored at {@link MIN_CONNECTIVITY_POLL_MS} so the endpoint can't
+ * be polled unreasonably fast.
+ */
+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/cjs/services/robot-status/connectivity.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnectivityChanges = exports.getServiceConnectionChanges = exports.aggregateConnectivity = exports.mapConnectionStatus = exports.buildConnectionsUrl = exports.clampPollInterval = exports.MIN_CONNECTIVITY_POLL_MS = exports.DEFAULT_EXPECTED_SERVICES = exports.TELEMETRY_LIVENESS_SERVICE = exports.CONNECTION_SERVICE_PREFIXES = void 0;
+const api_1 = require("../../constants/api");
+const models_1 = require("../../models");
+const rxjs_1 = require("rxjs");
+const formatServiceUrl_1 = require("../../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.
+ */
+exports.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`.
+ */
+exports.TELEMETRY_LIVENESS_SERVICE = 'telemetry-liveness';
+/**
+ * The services evaluated by default. The `telemetry` connections endpoint joins
+ * this list once Teletubby exposes it (follow-up).
+ */
+exports.DEFAULT_EXPECTED_SERVICES = [exports.TELEMETRY_LIVENESS_SERVICE, 'robot-configs', 'robot-services'];
+const DEFAULT_CONNECTIVITY_POLL_MS = 5000;
+/**
+ * Floor for the connections-endpoint poll interval. Guards against a caller
+ * passing `0` (or any tiny value), which would otherwise poll the API on every
+ * event-loop tick.
+ */
+exports.MIN_CONNECTIVITY_POLL_MS = 250;
+/** Clamps a requested poll interval up to {@link MIN_CONNECTIVITY_POLL_MS}. */
+const clampPollInterval = (pollMs) => Math.max(pollMs, exports.MIN_CONNECTIVITY_POLL_MS);
+exports.clampPollInterval = clampPollInterval;
+/**
+ * Builds the `connections` endpoint URL for a service — per-callsign when a
+ * callsign is given, otherwise the bulk per-project variant.
+ */
+const buildConnectionsUrl = (serviceId, baseUrl, projectId, callsign, insecure) => {
+    const template = callsign ? api_1.API_SERVICE_CONNECTION_URL : api_1.API_SERVICE_CONNECTIONS_URL;
+    const params = { url: baseUrl, service: exports.CONNECTION_SERVICE_PREFIXES[serviceId], projectId };
+    if (callsign)
+        params.callsign = callsign;
+    return (0, formatServiceUrl_1.formatServiceUrl)(template, params, insecure);
+};
+exports.buildConnectionsUrl = buildConnectionsUrl;
+/** Maps a `connections` endpoint response onto a {@link ServiceConnection}. */
+const mapConnectionStatus = (connection) => {
+    if (connection?.status === models_1.ConnectionStatus.CONNECTED)
+        return models_1.ServiceConnection.CONNECTED;
+    if (connection?.status === models_1.ConnectionStatus.DISCONNECTED)
+        return models_1.ServiceConnection.DISCONNECTED;
+    return models_1.ServiceConnection.UNKNOWN;
+};
+exports.mapConnectionStatus = mapConnectionStatus;
+/**
+ * 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.
+ */
+const aggregateConnectivity = (services) => {
+    const values = Object.values(services);
+    const hasConnected = values.includes(models_1.ServiceConnection.CONNECTED);
+    const hasDisconnected = values.includes(models_1.ServiceConnection.DISCONNECTED);
+    if (hasConnected && hasDisconnected)
+        return models_1.RobotConnectivity.DEGRADED;
+    if (hasConnected)
+        return models_1.RobotConnectivity.ONLINE;
+    return models_1.RobotConnectivity.OFFLINE;
+};
+exports.aggregateConnectivity = aggregateConnectivity;
+/**
+ * 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.
+ *
+ * `pollMs` is floored at {@link MIN_CONNECTIVITY_POLL_MS} so the endpoint can't
+ * be polled unreasonably fast.
+ */
+const getServiceConnectionChanges = (httpGet, url, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    return (0, rxjs_1.timer)(0, (0, exports.clampPollInterval)(pollMs)).pipe((0, rxjs_1.switchMap)(() => {
+        return (0, rxjs_1.from)(httpGet(url)).pipe((0, rxjs_1.map)(exports.mapConnectionStatus), (0, rxjs_1.catchError)(() => (0, rxjs_1.of)(models_1.ServiceConnection.UNKNOWN)));
+    }), (0, rxjs_1.startWith)(models_1.ServiceConnection.UNKNOWN), (0, rxjs_1.distinctUntilChanged)());
+};
+exports.getServiceConnectionChanges = getServiceConnectionChanges;
+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`.
+ */
+const getConnectivityChanges = (deps, projectId, callsign, expectedServices = exports.DEFAULT_EXPECTED_SERVICES, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    // combineLatest([]) completes without emitting; emit an explicit empty/offline status instead.
+    if (expectedServices.length === 0) {
+        return (0, rxjs_1.of)({ overall: models_1.RobotConnectivity.OFFLINE, services: {} });
+    }
+    const perService = expectedServices.map((serviceId) => {
+        let source$;
+        if (serviceId === exports.TELEMETRY_LIVENESS_SERVICE) {
+            source$ = deps.telemetryLiveness$;
+        }
+        else if (serviceId in exports.CONNECTION_SERVICE_PREFIXES) {
+            const url = (0, exports.buildConnectionsUrl)(serviceId, deps.baseUrl, projectId, callsign, deps.insecure);
+            source$ = (0, exports.getServiceConnectionChanges)(deps.httpGet, url, pollMs);
+        }
+        else {
+            source$ = (0, rxjs_1.of)(models_1.ServiceConnection.UNKNOWN);
+        }
+        return source$.pipe((0, rxjs_1.startWith)(models_1.ServiceConnection.UNKNOWN), (0, rxjs_1.map)((connection) => ({ serviceId, connection })));
+    });
+    return (0, rxjs_1.combineLatest)(perService).pipe((0, rxjs_1.map)((entries) => {
+        const services = {};
+        for (const { serviceId, connection } of entries)
+            services[serviceId] = connection;
+        return { overall: (0, exports.aggregateConnectivity)(services), services };
+    }), (0, rxjs_1.distinctUntilChanged)(connectivityEquals));
+};
+exports.getConnectivityChanges = getConnectivityChanges;

package/cjs/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/cjs/services/robot-status/reportedStatus.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTelemetryLiveness = exports.getReportedStatusChanges = exports.parseRobotReadiness = exports.parseRobotHealth = exports.LEGACY_HEARTBEAT_SOURCE = exports.ROBOT_STATUS_SOURCE = void 0;
+const rxjs_1 = require("rxjs");
+const models_1 = require("../../models");
+/** The new agent topic carrying health + readiness (replaces the heartbeat). */
+exports.ROBOT_STATUS_SOURCE = '/diagnostics/robot/status';
+/** The legacy heartbeat topic — liveness only, no status payload. */
+exports.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}.
+ */
+const parseRobotHealth = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'normal':
+            return models_1.RobotHealth.NORMAL;
+        case 2:
+        case '2':
+        case 'abnormal':
+            return models_1.RobotHealth.ABNORMAL;
+        case 3:
+        case '3':
+        case 'critical':
+            return models_1.RobotHealth.CRITICAL;
+        default:
+            return models_1.RobotHealth.UNKNOWN;
+    }
+};
+exports.parseRobotHealth = parseRobotHealth;
+/** As {@link parseRobotHealth}, for {@link RobotReadiness}. */
+const parseRobotReadiness = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'idle':
+            return models_1.RobotReadiness.IDLE;
+        case 2:
+        case '2':
+        case 'busy':
+            return models_1.RobotReadiness.BUSY;
+        default:
+            return models_1.RobotReadiness.UNKNOWN;
+    }
+};
+exports.parseRobotReadiness = parseRobotReadiness;
+/**
+ * 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.
+ */
+const getReportedStatusChanges = (telemetry, projectId, callsign) => {
+    const new$ = telemetry
+        .subscribe({ projectId, callsigns: [callsign], sources: [exports.ROBOT_STATUS_SOURCE] })
+        .pipe((0, rxjs_1.map)((message) => ({
+        from: 'new',
+        status: {
+            health: (0, exports.parseRobotHealth)(message.payload?.health),
+            readiness: (0, exports.parseRobotReadiness)(message.payload?.readiness),
+        },
+    })));
+    const legacy$ = telemetry.subscribe({ projectId, callsigns: [callsign], sources: [exports.LEGACY_HEARTBEAT_SOURCE] }).pipe((0, rxjs_1.map)(() => ({
+        from: 'legacy',
+        status: { health: models_1.RobotHealth.NORMAL, readiness: models_1.RobotReadiness.IDLE },
+    })));
+    return (0, rxjs_1.merge)(new$, legacy$).pipe((0, rxjs_1.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 }), (0, rxjs_1.map)((acc) => acc.status), (0, rxjs_1.filter)((status) => status !== undefined), (0, rxjs_1.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.
+    (0, rxjs_1.catchError)(() => (0, rxjs_1.of)({ health: models_1.RobotHealth.UNKNOWN, readiness: models_1.RobotReadiness.UNKNOWN })));
+};
+exports.getReportedStatusChanges = getReportedStatusChanges;
+/**
+ * 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.
+ */
+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: [exports.ROBOT_STATUS_SOURCE, exports.LEGACY_HEARTBEAT_SOURCE] })
+        .pipe((0, rxjs_1.map)(() => Date.now()));
+    return (0, rxjs_1.combineLatest)([lastMessageAt$.pipe((0, rxjs_1.startWith)(startedAt)), (0, rxjs_1.interval)(intervalMs)]).pipe((0, rxjs_1.map)(([lastMessageAt]) => {
+        const now = Date.now();
+        // No message yet, but still within the initial grace period.
+        if (lastMessageAt === startedAt && now - startedAt <= heartbeatTimeoutMs)
+            return models_1.ServiceConnection.UNKNOWN;
+        if (now - lastMessageAt > heartbeatTimeoutMs)
+            return models_1.ServiceConnection.DISCONNECTED;
+        return models_1.ServiceConnection.CONNECTED;
+    }), (0, rxjs_1.startWith)(models_1.ServiceConnection.UNKNOWN), (0, rxjs_1.distinctUntilChanged)(), (0, rxjs_1.catchError)(() => (0, rxjs_1.of)(models_1.ServiceConnection.UNKNOWN)));
+};
+exports.getTelemetryLiveness = getTelemetryLiveness;

package/esm/IRocosSDK.d.ts

@@ -1,9 +1,10 @@
-import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, ProfileService, ProjectService, RTPWebRTCService, RobotService, SearchService, SpotProvisioningService, SpotProvisioningServiceNode, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService } from './services';
+import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, ProfileService, ProjectService, RTPWebRTCService, RobotService, RobotStatusService, SearchService, SpotProvisioningService, SpotProvisioningServiceNode, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService } from './services';
 import { IBaseService, IDebugLevel, ServiceEnum } from './models';
 export declare abstract class IRocosSDK {
     abstract getService<T extends IBaseService>(_name: ServiceEnum): T;
     abstract getAuthService(): AuthService;
     abstract getRobotService(): RobotService;
+    abstract getRobotStatusService(): RobotStatusService;
     abstract getEventService(): EventService;
     abstract getEnvironmentService(): EnvironmentService;
     abstract getProjectService(): ProjectService;

package/esm/RocosSDK.d.ts

@@ -1,4 +1,4 @@
-import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, ProfileService, ProjectService, RTPWebRTCService, RobotService, ScheduleService, SearchService, SpotProvisioningService, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService } from './services';
+import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, ProfileService, ProjectService, RTPWebRTCService, RobotService, RobotStatusService, ScheduleService, SearchService, SpotProvisioningService, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService } from './services';
 import { AuthorisedConfig, IBaseService, IDebugLevel, IRocosSDKConfig, ServiceEnum } from './models';
 import { IRocosSDK } from './IRocosSDK';
 import { Logger } from 'loglevel';
@@ -26,6 +26,10 @@ export declare class RocosSDK implements IRocosSDK {
      * Gets the robot service.
      */
     getRobotService(): RobotService;
+    /**
+     * Gets the robot status service.
+     */
+    getRobotStatusService(): RobotStatusService;
     /**
      * Gets the event service.
      */

package/esm/RocosSDK.js

@@ -1,4 +1,4 @@
-import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, PlatFormTimeService, ProfileService, ProjectService, RTPWebRTCService, RobotService, ScheduleService, SearchService, SpotProvisioningService, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService, } from './services';
+import { AssetStorageService, AuthService, CallerService, CommandService, ConfigGroupService, ControlService, DashboardService, DeviceCredentialsService, EnvironmentService, EvaluatorService, EventService, FileAccessorService, IntegrationService, MapService, PlatFormTimeService, ProfileService, ProjectService, RTPWebRTCService, RobotService, RobotStatusService, ScheduleService, SearchService, SpotProvisioningService, StreamService, TagService, TargetService, TelemetryService, TimeSyncerService, UserService, WebRTCSignallingService, WorkflowService, } from './services';
 import { ServiceEnum } from './models';
 import { RocosLogger } from './logger/RocosLogger';
 import { RocosStore } from './store/RocosStore';
@@ -35,6 +35,9 @@ export class RocosSDK {
                 case ServiceEnum.ROBOT:
                     this.services[name] = new RobotService(config);
                     break;
+                case ServiceEnum.ROBOT_STATUS:
+                    this.services[name] = new RobotStatusService(config);
+                    break;
                 case ServiceEnum.ENVIRONMENT:
                     this.services[name] = new EnvironmentService(config);
                     break;
@@ -130,6 +133,12 @@ export class RocosSDK {
     getRobotService() {
         return this.getService(ServiceEnum.ROBOT);
     }
+    /**
+     * Gets the robot status service.
+     */
+    getRobotStatusService() {
+        return this.getService(ServiceEnum.ROBOT_STATUS);
+    }
     /**
      * Gets the event service.
      */

package/esm/constants/api.d.ts

@@ -56,8 +56,10 @@ export declare const API_PROJECT_ROBOT_COMMAND2_URL = "https://{url}/projects/{p
 export declare const API_PROJECT_ROBOT_BUTTON_URL = "https://{url}/projects/{projectId}/robots/{callsign}/buttons";
 export declare const API_PROJECT_ROBOT_TRIGGER_URL = "https://{url}/projects/{projectId}/robots/{callsign}/triggers";
 export declare const API_PROJECT_ROBOT_GAMEPAD_URL = "https://{url}/projects/{projectId}/robots/{callsign}/gamepads";
-export declare const API_PROJECT_ROBOT_CONFIGS_CONNECTIONS_URL = "https://{url}/robot-configs/connections/projects/{projectId}";
-export declare const API_PROJECT_ROBOT_CONFIGS_CONNECTION_URL = "https://{url}/robot-configs/connections/projects/{projectId}/callsigns/{callsign}";
+export declare const API_SERVICE_CONNECTIONS_URL = "https://{url}/{service}/connections/projects/{projectId}";
+export declare const API_SERVICE_CONNECTION_URL = "https://{url}/{service}/connections/projects/{projectId}/callsigns/{callsign}";
+export declare const API_PROJECT_ROBOT_CONFIGS_CONNECTIONS_URL: string;
+export declare const API_PROJECT_ROBOT_CONFIGS_CONNECTION_URL: string;
 export declare const API_PROJECT_OPERATION_URL = "https://{url}/projects/{projectId}/operations";
 export declare const API_PROJECT_OPERATION_ID_URL = "https://{url}/projects/{projectId}/operations/{operationId}";
 export declare const API_PROJECT_DASHBOARD_URL = "https://{url}/projects/{projectId}/dashboards";
@@ -134,6 +136,10 @@ export declare const API_GRAPHS_MAP_NODE_URL = "https://{url}/graphs/projects/{p
 export declare const API_GRAPHS_MAP_EDGES_ADD_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/add";
 export declare const API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/add/transform";
 export declare const API_GRAPHS_MAP_EDGE_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/{edgeId}";
+export declare const API_GRAPHS_MAP_PATHS_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths";
+export declare const API_GRAPHS_MAP_PATH_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}";
+export declare const API_GRAPHS_MAP_PATH_APPEND_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append";
+export declare const API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append/transformable";
 export declare const API_GRAPHS_MAPS_COPY_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/copy";
 export declare const API_GRAPHS_MAPS_DEPLOY_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/deploy";
 export declare const API_GRAPHS_MAPS_GEOJSON_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/geojson";

package/esm/constants/api.js

@@ -56,8 +56,12 @@ export const API_PROJECT_ROBOT_COMMAND2_URL = 'https://{url}/projects/{projectId
 export const API_PROJECT_ROBOT_BUTTON_URL = 'https://{url}/projects/{projectId}/robots/{callsign}/buttons';
 export const API_PROJECT_ROBOT_TRIGGER_URL = 'https://{url}/projects/{projectId}/robots/{callsign}/triggers';
 export const API_PROJECT_ROBOT_GAMEPAD_URL = 'https://{url}/projects/{projectId}/robots/{callsign}/gamepads';
-export const API_PROJECT_ROBOT_CONFIGS_CONNECTIONS_URL = 'https://{url}/robot-configs/connections/projects/{projectId}';
-export const API_PROJECT_ROBOT_CONFIGS_CONNECTION_URL = 'https://{url}/robot-configs/connections/projects/{projectId}/callsigns/{callsign}';
+// Generic connections endpoint templates. `{service}` is the service's public path prefix
+// (e.g. robot-configs, robot-services); the per-service specialisations below derive from these.
+export const API_SERVICE_CONNECTIONS_URL = 'https://{url}/{service}/connections/projects/{projectId}';
+export const API_SERVICE_CONNECTION_URL = 'https://{url}/{service}/connections/projects/{projectId}/callsigns/{callsign}';
+export const API_PROJECT_ROBOT_CONFIGS_CONNECTIONS_URL = API_SERVICE_CONNECTIONS_URL.replace('{service}', 'robot-configs');
+export const API_PROJECT_ROBOT_CONFIGS_CONNECTION_URL = API_SERVICE_CONNECTION_URL.replace('{service}', 'robot-configs');
 export const API_PROJECT_OPERATION_URL = 'https://{url}/projects/{projectId}/operations';
 export const API_PROJECT_OPERATION_ID_URL = 'https://{url}/projects/{projectId}/operations/{operationId}';
 export const API_PROJECT_DASHBOARD_URL = 'https://{url}/projects/{projectId}/dashboards';
@@ -134,6 +138,10 @@ export const API_GRAPHS_MAP_NODE_URL = 'https://{url}/graphs/projects/{projectId
 export const API_GRAPHS_MAP_EDGES_ADD_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/add';
 export const API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/add/transform';
 export const API_GRAPHS_MAP_EDGE_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/edges/{edgeId}';
+export const API_GRAPHS_MAP_PATHS_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths';
+export const API_GRAPHS_MAP_PATH_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}';
+export const API_GRAPHS_MAP_PATH_APPEND_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append';
+export const API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append/transformable';
 export const API_GRAPHS_MAPS_COPY_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/copy';
 export const API_GRAPHS_MAPS_DEPLOY_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/deploy';
 export const API_GRAPHS_MAPS_GEOJSON_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/geojson';

package/esm/models/RocosError.d.ts

@@ -28,6 +28,7 @@ export declare const errorCodes: {
     TARGET_SERVICE_ERROR: string;
     ENVIRONMENT_SERVICE_ERROR: string;
     TAG_SERVICE_ERROR: string;
+    ROBOT_STATUS_SERVICE_ERROR: string;
 };
 export declare class RocosError extends Error {
     code?: string;