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

package/cjs/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/cjs/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/cjs/RocosSDK.js

@@ -38,6 +38,9 @@ class RocosSDK {
                 case models_1.ServiceEnum.ROBOT:
                     this.services[name] = new services_1.RobotService(config);
                     break;
+                case models_1.ServiceEnum.ROBOT_STATUS:
+                    this.services[name] = new services_1.RobotStatusService(config);
+                    break;
                 case models_1.ServiceEnum.ENVIRONMENT:
                     this.services[name] = new services_1.EnvironmentService(config);
                     break;
@@ -133,6 +136,12 @@ class RocosSDK {
     getRobotService() {
         return this.getService(models_1.ServiceEnum.ROBOT);
     }
+    /**
+     * Gets the robot status service.
+     */
+    getRobotStatusService() {
+        return this.getService(models_1.ServiceEnum.ROBOT_STATUS);
+    }
     /**
      * Gets the event service.
      */

package/cjs/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;

package/cjs/models/RocosError.js

@@ -31,6 +31,7 @@ exports.errorCodes = {
     TARGET_SERVICE_ERROR: 'TARGET_SERVICE_ERROR',
     ENVIRONMENT_SERVICE_ERROR: 'ENVIRONMENT_SERVICE_ERROR',
     TAG_SERVICE_ERROR: 'TAG_SERVICE_ERROR',
+    ROBOT_STATUS_SERVICE_ERROR: 'ROBOT_STATUS_SERVICE_ERROR',
 };
 class RocosError extends Error {
     constructor(err, code, statusCode) {

package/cjs/models/ServiceEnum.d.ts

@@ -17,6 +17,7 @@ export declare enum ServiceEnum {
     PROJECT = "project",
     PROFILE = "profile",
     ROBOT = "robot",
+    ROBOT_STATUS = "robot_status",
     RTP_WEBRTC = "rtp_webrtc",
     SCHEDULE = "schedule",
     SEARCH = "search",

package/cjs/models/ServiceEnum.js

@@ -21,6 +21,7 @@ var ServiceEnum;
     ServiceEnum["PROJECT"] = "project";
     ServiceEnum["PROFILE"] = "profile";
     ServiceEnum["ROBOT"] = "robot";
+    ServiceEnum["ROBOT_STATUS"] = "robot_status";
     ServiceEnum["RTP_WEBRTC"] = "rtp_webrtc";
     ServiceEnum["SCHEDULE"] = "schedule";
     ServiceEnum["SEARCH"] = "search";

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

@@ -17,6 +17,14 @@ export declare const TELEMETRY_LIVENESS_SERVICE = "telemetry-liveness";
  * 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>;
 /**
@@ -47,6 +55,9 @@ export declare const aggregateConnectivity: (services: Record<string, ServiceCon
  * {@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 {

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getConnectivityChanges = exports.getServiceConnectionChanges = exports.aggregateConnectivity = exports.mapConnectionStatus = exports.buildConnectionsUrl = exports.DEFAULT_EXPECTED_SERVICES = exports.TELEMETRY_LIVENESS_SERVICE = exports.CONNECTION_SERVICE_PREFIXES = void 0;
+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");
@@ -26,6 +26,15 @@ exports.TELEMETRY_LIVENESS_SERVICE = 'telemetry-liveness';
  */
 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.
@@ -78,9 +87,12 @@ exports.aggregateConnectivity = aggregateConnectivity;
  * {@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, pollMs).pipe((0, rxjs_1.switchMap)(() => {
+    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)());
 };

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/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;

package/esm/models/RocosError.js

@@ -28,6 +28,7 @@ export const errorCodes = {
     TARGET_SERVICE_ERROR: 'TARGET_SERVICE_ERROR',
     ENVIRONMENT_SERVICE_ERROR: 'ENVIRONMENT_SERVICE_ERROR',
     TAG_SERVICE_ERROR: 'TAG_SERVICE_ERROR',
+    ROBOT_STATUS_SERVICE_ERROR: 'ROBOT_STATUS_SERVICE_ERROR',
 };
 export class RocosError extends Error {
     constructor(err, code, statusCode) {

package/esm/models/ServiceEnum.d.ts

@@ -17,6 +17,7 @@ export declare enum ServiceEnum {
     PROJECT = "project",
     PROFILE = "profile",
     ROBOT = "robot",
+    ROBOT_STATUS = "robot_status",
     RTP_WEBRTC = "rtp_webrtc",
     SCHEDULE = "schedule",
     SEARCH = "search",

package/esm/models/ServiceEnum.js

@@ -18,6 +18,7 @@ export var ServiceEnum;
     ServiceEnum["PROJECT"] = "project";
     ServiceEnum["PROFILE"] = "profile";
     ServiceEnum["ROBOT"] = "robot";
+    ServiceEnum["ROBOT_STATUS"] = "robot_status";
     ServiceEnum["RTP_WEBRTC"] = "rtp_webrtc";
     ServiceEnum["SCHEDULE"] = "schedule";
     ServiceEnum["SEARCH"] = "search";

package/esm/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/esm/services/RobotStatusService.js

@@ -0,0 +1,90 @@
+import { getConnectivityChanges } from './robot-status/connectivity';
+import { RobotHealth, RobotReadiness, RocosError, ServiceConnection, errorCodes, } from '../models';
+import { combineLatest, distinctUntilChanged, first, firstValueFrom, map, of, shareReplay, startWith, take, tap, timeout, } from 'rxjs';
+import { getReportedStatusChanges, getTelemetryLiveness } from './robot-status/reportedStatus';
+import { BaseServiceAbstract } from './BaseServiceAbstract';
+import { RocosLogger } from '../logger/RocosLogger';
+import { RocosStore } from '../store/RocosStore';
+import { getRobotStatusColour } from '../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 !== 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.
+ */
+export class RobotStatusService extends BaseServiceAbstract {
+    constructor(config) {
+        super(config);
+        this.logger = 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 getReportedStatusChanges(this.telemetryService, projectId, callsign);
+    }
+    /** Per-service connectivity plus the aggregate verdict, polled. */
+    getConnectivityChanges(projectId, callsign, opts) {
+        return 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(tap((status) => {
+            latest = status;
+        }), shareReplay({ bufferSize: 1, refCount: true }));
+        return firstValueFrom(changes$.pipe(first(isKnown), 
+        // Don't wait forever on a persistently-unknown service — fall back to the latest snapshot seen.
+        timeout({ first: ONE_SHOT_TIMEOUT_MS, with: () => (latest ? of(latest) : changes$.pipe(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.
+        startWith({ health: RobotHealth.UNKNOWN, readiness: RobotReadiness.UNKNOWN }));
+        const connectivity$ = this.getConnectivityChanges(projectId, callsign, opts);
+        return combineLatest([reported$, connectivity$]).pipe(map(([reported, connectivity]) => ({
+            health: reported.health,
+            readiness: reported.readiness,
+            connectivity,
+            colour: getRobotStatusColour({ health: reported.health, readiness: reported.readiness, connectivity }),
+        })), distinctUntilChanged(robotStatusEquals));
+    }
+    getError(e) {
+        return new RocosError(e, errorCodes.ROBOT_STATUS_SERVICE_ERROR);
+    }
+    get telemetryService() {
+        return 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$: getTelemetryLiveness(this.telemetryService, projectId, callsign, opts?.heartbeatTimeoutMs),
+        };
+    }
+}

package/esm/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/esm/services/index.js

@@ -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/esm/services/robot-status/connectivity.d.ts

@@ -17,6 +17,14 @@ export declare const TELEMETRY_LIVENESS_SERVICE = "telemetry-liveness";
  * 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>;
 /**
@@ -47,6 +55,9 @@ export declare const aggregateConnectivity: (services: Record<string, ServiceCon
  * {@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 {

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

@@ -23,6 +23,14 @@ export const TELEMETRY_LIVENESS_SERVICE = 'telemetry-liveness';
  */
 export const DEFAULT_EXPECTED_SERVICES = [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.
+ */
+export const MIN_CONNECTIVITY_POLL_MS = 250;
+/** Clamps a requested poll interval up to {@link MIN_CONNECTIVITY_POLL_MS}. */
+export const clampPollInterval = (pollMs) => Math.max(pollMs, MIN_CONNECTIVITY_POLL_MS);
 /**
  * Builds the `connections` endpoint URL for a service — per-callsign when a
  * callsign is given, otherwise the bulk per-project variant.
@@ -72,9 +80,12 @@ export const aggregateConnectivity = (services) => {
  * {@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 const getServiceConnectionChanges = (httpGet, url, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
-    return timer(0, pollMs).pipe(switchMap(() => {
+    return timer(0, clampPollInterval(pollMs)).pipe(switchMap(() => {
         return from(httpGet(url)).pipe(map(mapConnectionStatus), catchError(() => of(ServiceConnection.UNKNOWN)));
     }), startWith(ServiceConnection.UNKNOWN), distinctUntilChanged());
 };

package/package.json

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