@dronedeploy/rocos-js-sdk 4.1.0 → 4.2.1

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

@@ -0,0 +1,128 @@
+"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;
+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;
+/**
+ * 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.
+ */
+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.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/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/index.d.ts

@@ -51,6 +51,7 @@ export * from './maps/Map';
 export * from './maps/MapContent';
 export * from './maps/MapEdge';
 export * from './maps/MapNode';
+export * from './maps/MapPath';
 export * from './maps/Panorama';
 export * from './message';
 export * from './params/ICallerParams';

package/esm/models/index.js

@@ -51,6 +51,7 @@ export * from './maps/Map';
 export * from './maps/MapContent';
 export * from './maps/MapEdge';
 export * from './maps/MapNode';
+export * from './maps/MapPath';
 export * from './maps/Panorama';
 export * from './message';
 export * from './params/ICallerParams';

package/esm/models/maps/MapPath.d.ts

@@ -0,0 +1,143 @@
+import { Quaternion, Vector3 } from '../graph';
+import { MapContentNode } from './MapContent';
+/**
+ * A path (polyline or polygon) in a robot map, as returned by
+ * `GET /graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}` — the same shape the
+ * rocos-agent map component's `paths/get` service reports.
+ *
+ * A path is stored as a sub-graph following the `go-common/graph/paths` convention: a parent
+ * node (type `path.parent.v1`, or any existing node acting as anchor) plus one member node
+ * per vertex, wired by `path.start.v1` / `path.belongs.v1` / `path.edge.v1` edges. The path
+ * id IS the parent node id.
+ */
+export interface MapPath {
+    /** The path id (= parent node id). */
+    id: string;
+    /** Whether the path is a closed polygon (true) or an open polyline (false). */
+    closed: boolean;
+    /** The full parent node. */
+    parent: MapContentNode;
+    /** Ordered member (vertex) node ids, walked start → end. */
+    members: string[];
+}
+/** Filters for `MapService.listPaths`. */
+export interface ListPathsFilter {
+    /** Only include paths with this closed flag (omit for both). */
+    closed?: boolean;
+    /**
+     * Only include paths whose parent node type is in this list (omit for all).
+     *
+     * Wire-format caveat: the server takes this as a single comma-separated query parameter
+     * (`?types=a,b`), so a node type that itself contains a comma cannot be expressed — it
+     * would be split into two wrong filter terms and silently match nothing. Node types are
+     * free-form text server-side, so this is conceivable if unlikely; avoid commas in type
+     * names, or filter client-side over `listPaths` + `getPath` results if you must.
+     */
+    types?: string[];
+}
+/**
+ * Body of `POST /graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append`. Appends
+ * already-existing member nodes to a path, creating the path (and its `path.parent.v1`
+ * parent node) when absent — an existing node of any client-writable type is reused as the
+ * anchor instead.
+ *
+ * Members must already exist in the map (400 otherwise). `closed` is only applied while the
+ * path is empty; supplying a value that conflicts with a non-empty path's stored flag is
+ * rejected with 409 (use {@link MapService.replacePath} to change closed-ness). `data` keys
+ * are merged onto the parent node.
+ */
+export interface AppendToPathRequest {
+    closed?: boolean;
+    data?: Record<string, unknown>;
+    members: string[];
+}
+/**
+ * A rigid-body transform positioning one path vertex relative to the frame named in the
+ * enclosing request. `rot` is optional and defaults to identity — path vertices are
+ * typically plain positions. Field naming matches {@link AffineTransform} (`pos`/`rot`);
+ * the service marshals onto the server's `translation`/`rotation` wire shape.
+ */
+export interface PathPointTransform {
+    rot?: Quaternion;
+    pos: Vector3;
+}
+/**
+ * One vertex in a path payload. `id` is optional; when blank the server mints a UUID.
+ *
+ * `transform` is required by the append endpoint (which only creates vertices). In a path
+ * replace its presence carries the intent: supplied means the position is declarative (the
+ * vertex is created or — when the path exclusively owns the node — recreated at that
+ * position, which is how vertices are moved), while omitted means "reuse the existing node
+ * in place, position untouched".
+ */
+export interface PathPoint {
+    id?: string;
+    data?: Record<string, unknown>;
+    transform?: PathPointTransform;
+}
+/**
+ * A {@link PathPoint} whose transform is mandatory, for the append/transformable body —
+ * that endpoint only creates vertices, so every point needs a position. Requiring it at the
+ * type level moves the server's 400 for a transform-less point to compile time.
+ */
+export interface TransformablePathPoint extends PathPoint {
+    transform: PathPointTransform;
+}
+/**
+ * Body of `POST /graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}/append/transformable`.
+ * For each point it creates a node (`nodeType`, default `FRAME`) positioned by a `TRANSFORM`
+ * edge from the existing `frame` node, and appends them all to the path in one transaction —
+ * the cloud analog of the rocos-agent's `paths/append/currentPosition`, with the caller
+ * supplying positions instead of the robot's live pose.
+ *
+ * Every point must carry a `transform` (enforced by {@link TransformablePathPoint}; the
+ * server also rejects a transform-less point with 400 — append only creates vertices; use
+ * {@link MapService.appendToPath} to append existing nodes). Node creation is create-only: a
+ * point id that already exists in the map is rejected with 409 and the whole append rolls
+ * back. `closed` and `data` behave as in {@link AppendToPathRequest}.
+ */
+export interface AppendTransformablePointsRequest {
+    closed?: boolean;
+    data?: Record<string, unknown>;
+    frame: string;
+    nodeType?: string;
+    points: TransformablePathPoint[];
+}
+/** Response of the append/transformable endpoint: the created vertex ids, in path order. */
+export interface AppendPathPointsResponse {
+    ids: string[];
+}
+/**
+ * Body of `PUT /graphs/projects/{projectId}/maps/{mapId}/paths/{pathId}` — the editor
+ * primitive. Declares the path's entire desired state; vertex move/insert/delete/reorder
+ * and closed-flag changes all reach the server as one idempotent call.
+ *
+ * The existing structure is torn down (old vertices exclusively owned by the path are
+ * deleted; shared members are detached, never moved or deleted; the parent node always
+ * survives) and rebuilt from `points`. Each point's `transform` carries its intent:
+ *
+ * - **With a transform** the position is declarative: the vertex is created (as `nodeType`,
+ *   default `FRAME`, positioned by a `TRANSFORM` edge from `frame`), and for the path's own
+ *   vertices same id + new transform = a move. A transform on a node the path doesn't
+ *   exclusively own is rejected with 409.
+ * - **Without a transform** the point reuses an existing node in place, position untouched
+ *   (400 if it doesn't exist) — how shared waypoints stay in the path.
+ *
+ * `parentType` applies when the parent node is created (default `path.parent.v1`); against
+ * an existing parent it must match (409) or be omitted (reused as-is, the anchored-path
+ * model). Replacing can also repair a structurally malformed path (which `getPath` reports
+ * as 422). Repeated identical PUTs are hash-stable: the server skips the map-timestamp bump
+ * and SUMMARY rewrite when the result matches what is stored.
+ *
+ * Access rules match {@link MapService.deletePath} (replace deletes vertices): the
+ * environment map is off-limits, the dronedeploy map is admin-only, normal maps are open to
+ * any caller with project access.
+ */
+export interface ReplacePathRequest {
+    closed: boolean;
+    parentType?: string;
+    nodeType?: string;
+    data?: Record<string, unknown>;
+    frame?: string;
+    points: PathPoint[];
+}

package/esm/models/maps/MapPath.js

@@ -0,0 +1 @@
+export {};

package/esm/models/robot-status/RobotStatusEnums.d.ts

@@ -45,7 +45,7 @@ export declare enum ServiceConnection {
  * expected services.
  */
 export declare enum RobotConnectivity {
-    /** Every expected service reports connected. */
+    /** At least one expected service is connected and none is disconnected. */
     ONLINE = "online",
     /** Some, but not all, expected services report connected. */
     DEGRADED = "degraded",

package/esm/models/robot-status/RobotStatusEnums.js

@@ -49,7 +49,7 @@ export var ServiceConnection;
  */
 export var RobotConnectivity;
 (function (RobotConnectivity) {
-    /** Every expected service reports connected. */
+    /** At least one expected service is connected and none is disconnected. */
     RobotConnectivity["ONLINE"] = "online";
     /** Some, but not all, expected services report connected. */
     RobotConnectivity["DEGRADED"] = "degraded";

package/esm/services/MapService.d.ts

@@ -1,6 +1,7 @@
 import { AddEdgeRequest, AddEdgeResponse, AddTransformEdgeRequest } from '../models/maps/MapEdge';
 import { AddNodeRequest, AddNodeResponse, AddTransformableNodeRequest } from '../models/maps/MapNode';
 import { AddPanoramaRequest, AddPanoramaResponse, CreateObservation, Observation } from '../models/maps/Panorama';
+import { AppendPathPointsResponse, AppendToPathRequest, AppendTransformablePointsRequest, ListPathsFilter, MapPath, ReplacePathRequest } from '../models/maps/MapPath';
 import { Asset, IBaseService, IRocosSDKConfig, Map, MapContent, RocosError } from '../models';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 /**
@@ -334,4 +335,104 @@ export declare class MapService extends BaseServiceAbstract implements IBaseServ
      * @param edgeId The ID of the edge to delete.
      */
     deleteEdge(projectId: string, mapId: string, edgeId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    listPaths(projectId: string, mapId: string, filter?: ListPathsFilter): Promise<string[]>;
+    /**
+     * 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: string, mapId: string, pathId: string): Promise<MapPath>;
+    /**
+     * 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.
+     */
+    appendToPath(projectId: string, mapId: string, pathId: string, body: AppendToPathRequest): Promise<void>;
+    /**
+     * 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: string, mapId: string, pathId: string, body: AppendTransformablePointsRequest): Promise<AppendPathPointsResponse>;
+    /**
+     * 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.
+     */
+    replacePath(projectId: string, mapId: string, pathId: string, body: ReplacePathRequest): Promise<void>;
+    /**
+     * 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: string, mapId: string, pathId: string, opts?: {
+        deleteMembers?: boolean;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    private pathPointToWire;
 }