@dronedeploy/rocos-js-sdk 4.4.4 → 4.4.6

package/esm/constants/api.d.ts

@@ -36,7 +36,7 @@ export declare const API_PROJECT_ASSET_INTEGRATION_PROVIDERS_PATH_URL = "https:/
 export declare const API_PROJECT_ASSET_INTEGRATIONS_PATH_URL = "https://{url}/projects/{projectId}/integrations";
 export declare const API_PROJECT_ASSET_INTEGRATION_PATH_URL = "https://{url}/projects/{projectId}/integrations/{integrationId}";
 export declare const API_PROJECT_ROBOT_ASSET_PATH_URL = "https://{url}/projects/{projectId}/robots/{callsign}/assets";
-export declare const API_PROJECT_FLOW_ASSET_PATH_URL = "https://{url}/projects/{projectId}/flows/{callsign}/assets";
+export declare const API_PROJECT_FLOW_ASSET_PATH_URL = "https://{url}/projects/{projectId}/flows/{flowId}/instances/{flowInstance}/assets";
 export declare const API_PROJECT_MISSION_ASSETS_PATH_URL = "https://{url}/projects/{projectId}/missionassets";
 export declare const API_PROJECT_MISSION_ASSET_PATH_URL = "https://{url}/projects/{projectId}/missionassets/{assetId}";
 export declare const API_PROJECT_MAPPED_ASSETS_PATH_URL = "https://{url}/projects/{projectId}/mappedassets";
@@ -126,7 +126,7 @@ export declare const API_DD_INTEGRATION_LEVELS_URL = "https://{url}/projects/{pr
 export declare const API_GRAPHS_MAPS_URL = "https://{url}/graphs/projects/{projectId}/maps";
 export declare const API_GRAPHS_MAPS_NEW_URL = "https://{url}/graphs/projects/{projectId}/maps/new";
 export declare const API_GRAPHS_MAPS_DEPLOYED_URL = "https://{url}/graphs/projects/{projectId}/maps/deployed?callsign={callsign}";
-export declare const API_GRAPHS_MAPS_MERGE_URL = "https://{url}/graphs/projects/{projectId}/maps/merge";
+export declare const API_GRAPHS_MAPS_UNION_URL = "https://{url}/graphs/projects/{projectId}/maps/union";
 export declare const API_GRAPHS_MAP_ID_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}";
 export declare const API_GRAPHS_MAP_CONTENT_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/content";
 export declare const API_GRAPHS_MAP_METADATA_URL = "https://{url}/graphs/projects/{projectId}/maps/{mapId}/metadata";
@@ -152,6 +152,7 @@ export declare const API_GRAPHS_TARGET_UPLOAD_URL = "https://{url}/graphs/projec
 export declare const API_GRAPHS_TARGETS_URL = "https://{url}/graphs/projects/{projectId}/targets";
 export declare const API_GRAPHS_ASSETS_UPLOAD_URL = "https://{url}/graphs/projects/{projectId}/assets/upload";
 export declare const API_GRAPHS_ASSETS_URL = "https://{url}/graphs/projects/{projectId}/assets";
+export declare const API_GRAPHS_TARGET_MEDIA_URL = "https://{url}/graphs/projects/{projectId}/targets/{targetId}/media";
 export declare const API_PROJECT_WORKFLOW_URL = "https://{url}/projects/{projectId}/automate/flows";
 export declare const API_PROJECT_WORKFLOW_ID_URL = "https://{url}/projects/{projectId}/automate/flows/{workflowId}";
 export declare const API_PROJECT_WORKFLOW_ASSET_URL = "https://{url}/projects/{projectId}/automate/flows/{workflowId}/assets";

package/esm/constants/api.js

@@ -36,7 +36,7 @@ export const API_PROJECT_ASSET_INTEGRATION_PROVIDERS_PATH_URL = 'https://{url}/p
 export const API_PROJECT_ASSET_INTEGRATIONS_PATH_URL = 'https://{url}/projects/{projectId}/integrations';
 export const API_PROJECT_ASSET_INTEGRATION_PATH_URL = 'https://{url}/projects/{projectId}/integrations/{integrationId}';
 export const API_PROJECT_ROBOT_ASSET_PATH_URL = 'https://{url}/projects/{projectId}/robots/{callsign}/assets';
-export const API_PROJECT_FLOW_ASSET_PATH_URL = 'https://{url}/projects/{projectId}/flows/{callsign}/assets';
+export const API_PROJECT_FLOW_ASSET_PATH_URL = 'https://{url}/projects/{projectId}/flows/{flowId}/instances/{flowInstance}/assets';
 export const API_PROJECT_MISSION_ASSETS_PATH_URL = 'https://{url}/projects/{projectId}/missionassets';
 export const API_PROJECT_MISSION_ASSET_PATH_URL = 'https://{url}/projects/{projectId}/missionassets/{assetId}';
 export const API_PROJECT_MAPPED_ASSETS_PATH_URL = 'https://{url}/projects/{projectId}/mappedassets';
@@ -128,7 +128,7 @@ export const API_DD_INTEGRATION_LEVELS_URL = 'https://{url}/projects/{projectId}
 export const API_GRAPHS_MAPS_URL = 'https://{url}/graphs/projects/{projectId}/maps';
 export const API_GRAPHS_MAPS_NEW_URL = 'https://{url}/graphs/projects/{projectId}/maps/new';
 export const API_GRAPHS_MAPS_DEPLOYED_URL = 'https://{url}/graphs/projects/{projectId}/maps/deployed?callsign={callsign}';
-export const API_GRAPHS_MAPS_MERGE_URL = 'https://{url}/graphs/projects/{projectId}/maps/merge';
+export const API_GRAPHS_MAPS_UNION_URL = 'https://{url}/graphs/projects/{projectId}/maps/union';
 export const API_GRAPHS_MAP_ID_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}';
 export const API_GRAPHS_MAP_CONTENT_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/content';
 export const API_GRAPHS_MAP_METADATA_URL = 'https://{url}/graphs/projects/{projectId}/maps/{mapId}/metadata';
@@ -154,6 +154,7 @@ export const API_GRAPHS_TARGET_UPLOAD_URL = 'https://{url}/graphs/projects/{proj
 export const API_GRAPHS_TARGETS_URL = 'https://{url}/graphs/projects/{projectId}/targets';
 export const API_GRAPHS_ASSETS_UPLOAD_URL = 'https://{url}/graphs/projects/{projectId}/assets/upload';
 export const API_GRAPHS_ASSETS_URL = 'https://{url}/graphs/projects/{projectId}/assets';
+export const API_GRAPHS_TARGET_MEDIA_URL = 'https://{url}/graphs/projects/{projectId}/targets/{targetId}/media';
 export const API_PROJECT_WORKFLOW_URL = 'https://{url}/projects/{projectId}/automate/flows';
 export const API_PROJECT_WORKFLOW_ID_URL = 'https://{url}/projects/{projectId}/automate/flows/{workflowId}';
 export const API_PROJECT_WORKFLOW_ASSET_URL = 'https://{url}/projects/{projectId}/automate/flows/{workflowId}/assets';

package/esm/constants/identifier.d.ts

@@ -1,6 +1,7 @@
 export declare const IDENTIFIER_NAME_TELEMETRY = "telemetry";
 export declare const IDENTIFIER_NAME_CALLER = "caller";
 export declare const IDENTIFIER_NAME_COMMAND = "command";
+export declare const IDENTIFIER_NAME_WEBRTC_SIGNALLING = "webRTCSignalling";
 export declare const IDENTIFIER_NAME_CONTROL = "control";
 export declare const IDENTIFIER_NAME_SEARCH = "search";
 export declare const IDENTIFIER_NAME_FILE_ACCESSOR = "fileAccessor";

package/esm/constants/identifier.js

@@ -1,6 +1,7 @@
 export const IDENTIFIER_NAME_TELEMETRY = 'telemetry';
 export const IDENTIFIER_NAME_CALLER = 'caller';
 export const IDENTIFIER_NAME_COMMAND = 'command';
+export const IDENTIFIER_NAME_WEBRTC_SIGNALLING = 'webRTCSignalling';
 export const IDENTIFIER_NAME_CONTROL = 'control';
 export const IDENTIFIER_NAME_SEARCH = 'search';
 export const IDENTIFIER_NAME_FILE_ACCESSOR = 'fileAccessor';

package/esm/helpers/getUniqueId.js

@@ -7,5 +7,6 @@ import { flattenCallsignsLookup } from './flattenCallsignsLookup';
  * @param scope
  */
 export const getUniqueId = (projectId, callsignsLookup, sources, scope) => {
-    return [projectId, ...flattenCallsignsLookup(callsignsLookup), ...sources.sort(), scope].join();
+    // Copy before sorting: the caller keeps this array, and filters incoming messages with it.
+    return [projectId, ...flattenCallsignsLookup(callsignsLookup), ...[...sources].sort(), scope].join();
 };

package/esm/models/callsigns/CallsignsLookup.d.ts

@@ -4,5 +4,9 @@ export declare class CallsignsLookup {
     lookupValue: CallsignsQuery | string[];
     lookupType: CallsignsLookupType;
     constructor(lookupValue: string[] | CallsignsQuery);
+    isQuery(): boolean;
+    getCallsigns(): string[];
+    getQuery(): CallsignsQuery | undefined;
+    includesCallsign(callsign: string): boolean;
     toID(): string[];
 }

package/esm/models/callsigns/CallsignsLookup.js

@@ -19,6 +19,25 @@ export class CallsignsLookup {
             }
         }
     }
+    isQuery() {
+        return this.lookupType === CallsignsLookupType.Query;
+    }
+    getCallsigns() {
+        if (this.isQuery())
+            return [];
+        return this.lookupValue;
+    }
+    getQuery() {
+        if (!this.isQuery())
+            return undefined;
+        return this.lookupValue;
+    }
+    // A query resolves its callsigns server side, so there is no local list to match against.
+    includesCallsign(callsign) {
+        if (this.isQuery())
+            return true;
+        return this.getCallsigns().includes(callsign);
+    }
     toID() {
         if (this.lookupType === CallsignsLookupType.List) {
             return this.lookupValue.sort();

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

@@ -41,3 +41,26 @@ export interface RobotStatus {
     connectivity: RobotConnectivityStatus;
     colour: RobotStatusColour;
 }
+/**
+ * One contributor to a reported-status axis, from the agent's
+ * `robot/status/contributors` topic. `status` is the contributor's own verdict
+ * for that axis — the integer wire value mapped onto the enum.
+ */
+export interface RobotStatusContributor<TStatus = RobotHealth | RobotReadiness> {
+    /** Identifier of the contributor, e.g. `battery`. */
+    id: string;
+    /** The agent component that raised it, e.g. `dji`. */
+    component: string;
+    /** Human-readable explanation, e.g. `battery below 20%`; empty when none was given. */
+    reason: string;
+    /** The contributor's verdict for its axis. */
+    status: TStatus;
+}
+/**
+ * The per-contributor breakdown behind a robot's reported health and readiness,
+ * from the agent's `robot/status/contributors` topic.
+ */
+export interface RobotStatusContributors {
+    health: RobotStatusContributor<RobotHealth>[];
+    readiness: RobotStatusContributor<RobotReadiness>[];
+}

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

@@ -30,13 +30,22 @@ export declare enum RobotReadiness {
     BUSY = "busy"
 }
 /**
- * Whether the robot is connected to a single cloud service, as reported by that
- * service's `connections` endpoint (or, for `telemetry-liveness`, derived from
- * heartbeat freshness).
+ * Whether the robot is connected to a single cloud service — reported by that
+ * service's `connections` endpoint, derived from heartbeat freshness (for
+ * `telemetry-liveness`), or supplied by a caller-injected signal
+ * (`RobotStatusOptions.extraServices`), the only source that can report {@link FAILED}.
  */
 export declare enum ServiceConnection {
     CONNECTED = "connected",
     DISCONNECTED = "disconnected",
+    /**
+     * The service reports an explicit fault — a stronger signal than {@link DISCONNECTED} (which just
+     * means "not connected", as expected of a robot that is simply off). A failed virtual-robot
+     * deployment is the motivating case. Any `FAILED` service forces the aggregate to
+     * {@link RobotConnectivity.DEGRADED}, so a fault raises attention even when nothing else is
+     * connected — see `aggregateConnectivity`.
+     */
+    FAILED = "failed",
     /** The service's connectivity has not yet been determined (e.g. not polled). */
     UNKNOWN = "unknown"
 }
@@ -45,10 +54,13 @@ export declare enum ServiceConnection {
  * expected services.
  */
 export declare enum RobotConnectivity {
-    /** At least one expected service is connected and none is disconnected. */
+    /** At least one expected service is connected and none is disconnected or failed. */
     ONLINE = "online",
-    /** Some, but not all, expected services report connected. */
+    /**
+     * Any service reports a fault ({@link ServiceConnection.FAILED}), or a genuine mix — some
+     * connected, some disconnected. A `FAILED` service forces this even when nothing is connected.
+     */
     DEGRADED = "degraded",
-    /** No expected service reports connected. */
+    /** Nothing connected, and nothing failed. */
     OFFLINE = "offline"
 }

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

@@ -32,14 +32,23 @@ export var RobotReadiness;
     RobotReadiness["BUSY"] = "busy";
 })(RobotReadiness || (RobotReadiness = {}));
 /**
- * Whether the robot is connected to a single cloud service, as reported by that
- * service's `connections` endpoint (or, for `telemetry-liveness`, derived from
- * heartbeat freshness).
+ * Whether the robot is connected to a single cloud service — reported by that
+ * service's `connections` endpoint, derived from heartbeat freshness (for
+ * `telemetry-liveness`), or supplied by a caller-injected signal
+ * (`RobotStatusOptions.extraServices`), the only source that can report {@link FAILED}.
  */
 export var ServiceConnection;
 (function (ServiceConnection) {
     ServiceConnection["CONNECTED"] = "connected";
     ServiceConnection["DISCONNECTED"] = "disconnected";
+    /**
+     * The service reports an explicit fault — a stronger signal than {@link DISCONNECTED} (which just
+     * means "not connected", as expected of a robot that is simply off). A failed virtual-robot
+     * deployment is the motivating case. Any `FAILED` service forces the aggregate to
+     * {@link RobotConnectivity.DEGRADED}, so a fault raises attention even when nothing else is
+     * connected — see `aggregateConnectivity`.
+     */
+    ServiceConnection["FAILED"] = "failed";
     /** The service's connectivity has not yet been determined (e.g. not polled). */
     ServiceConnection["UNKNOWN"] = "unknown";
 })(ServiceConnection || (ServiceConnection = {}));
@@ -49,10 +58,13 @@ export var ServiceConnection;
  */
 export var RobotConnectivity;
 (function (RobotConnectivity) {
-    /** At least one expected service is connected and none is disconnected. */
+    /** At least one expected service is connected and none is disconnected or failed. */
     RobotConnectivity["ONLINE"] = "online";
-    /** Some, but not all, expected services report connected. */
+    /**
+     * Any service reports a fault ({@link ServiceConnection.FAILED}), or a genuine mix — some
+     * connected, some disconnected. A `FAILED` service forces this even when nothing is connected.
+     */
     RobotConnectivity["DEGRADED"] = "degraded";
-    /** No expected service reports connected. */
+    /** Nothing connected, and nothing failed. */
     RobotConnectivity["OFFLINE"] = "offline";
 })(RobotConnectivity || (RobotConnectivity = {}));

package/esm/services/AssetStorageService.js

@@ -96,7 +96,12 @@ export class AssetStorageService extends BaseServiceAbstract {
      * @param signedURL
      */
     async listFlowAssets(projectId, flowId, flowInstance, parent = '/', signedURL = false) {
-        return this.callGet(formatServiceUrl(API_PROJECT_FLOW_ASSET_PATH_URL, { url: this.config.url, projectId, flowId, flowInstance }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
+        return this.callGet(formatServiceUrl(API_PROJECT_FLOW_ASSET_PATH_URL, {
+            url: this.config.url,
+            projectId,
+            flowId: encodeURIComponent(flowId),
+            flowInstance: encodeURIComponent(flowInstance),
+        }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
     }
     /**
      * List assets for a mission

package/esm/services/BaseServiceAbstract.js

@@ -41,7 +41,7 @@ export class BaseServiceAbstract {
                 requestConfig.body = JSON.stringify(payload);
                 requestConfig.headers = { ...requestConfig.headers, 'Content-Type': 'application/json' };
             }
-            return this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
+            return await this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
         }
         catch (e) {
             const message = errorMessage;

package/esm/services/BaseStreamService.d.ts

@@ -1,3 +1,4 @@
+import { IAcquiredStream } from '../api/StreamRegister';
 import { IBaseService, IBaseStream, IRocosSDKConfig, IStreamConfig, SubscriberStatusEnum } from '../models';
 import { ISubscriberStatus } from '../models/ISubscriberStatus';
 import { Logger } from 'loglevel';
@@ -10,7 +11,17 @@ export declare abstract class BaseStreamService<T extends IBaseStream, C extends
     protected constructor(name: string, config: IRocosSDKConfig);
     getStatus(): boolean;
     protected initStream(stream: T): Promise<void>;
-    protected createStreamFromConfig(identifier: string, config: C, onAcquire?: (stream: T) => void): Promise<{
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    protected acquireStream(identifier: string, config: C): IAcquiredStream<T>;
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    protected createStreamFromConfig(identifier: string, config: C): Promise<{
         stream: T;
         isNew: boolean;
     }>;

package/esm/services/BaseStreamService.js

@@ -1,7 +1,7 @@
+import { StreamRegister } from '../api/StreamRegister';
 import { SubscriberStatusEnum, Token } from '../models';
 import { RocosLogger } from '../logger/RocosLogger';
 import { RocosStore } from '../store/RocosStore';
-import { StreamRegister } from '../api/StreamRegister';
 import { Subject } from 'rxjs';
 export class BaseStreamService {
     constructor(name, config) {
@@ -29,40 +29,29 @@ export class BaseStreamService {
         }
         authService.startTokenRefreshChecker();
     }
-    async createStreamFromConfig(identifier, config, onAcquire) {
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    acquireStream(identifier, config) {
         const identifierWithScope = StreamRegister.getIdentifier(identifier, config.scope);
-        const streamRegister = StreamRegister.getInstance();
-        let stream = streamRegister.getStream(identifierWithScope);
-        let isNew = false;
-        if (!stream) {
-            isNew = true;
-            stream = this.getStream(config);
+        return StreamRegister.getInstance().acquireStream(identifierWithScope, () => {
+            const stream = this.getStream(config);
             stream.statusStream$.subscribe((msg) => {
                 this.status = msg === SubscriberStatusEnum.STOPPED || msg === SubscriberStatusEnum.ALIVE;
                 this.status$.next(msg);
             });
-            streamRegister.addStream(stream);
-        }
-        // Acquire synchronously with the lookup/registration above, before any await. A stream is
-        // stopped and deregistered the instant its refcount hits zero, so a deferred acquire can land on
-        // a dead instance — including a freshly-registered stream torn down during the init await below.
-        onAcquire?.(stream);
-        if (isNew) {
-            try {
-                await this.initStream(stream);
-            }
-            catch (e) {
-                // Evict eagerly, before the error reaches the subscriber, so a synchronous resubscribe
-                // can't re-acquire this uninitialised instance.
-                streamRegister.removeStream(stream);
-                throw e;
-            }
-            // If a concurrent teardown deregistered this stream during init, init() has opened a receiver
-            // on an instance nothing can reach; close it.
-            if (streamRegister.getStream(identifierWithScope) !== stream) {
-                stream.stopStream();
-            }
-        }
+            return stream;
+        }, (stream) => this.initStream(stream));
+    }
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    async createStreamFromConfig(identifier, config) {
+        const { stream, isNew, ready } = this.acquireStream(identifier, config);
+        await ready;
         return { stream, isNew };
     }
 }

package/esm/services/EnvironmentService.d.ts

@@ -21,6 +21,10 @@ export declare class EnvironmentService extends BaseServiceAbstract implements I
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     set(projectId: string, scene: unknown): Promise<void>;
     /**

package/esm/services/EnvironmentService.js

@@ -33,9 +33,13 @@ export class EnvironmentService extends BaseServiceAbstract {
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     async set(projectId, scene) {
-        return this.callPost(formatServiceUrl(API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
+        return this.callPut(formatServiceUrl(API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
     }
     /**
      * Update Environment

package/esm/services/MapService.d.ts

@@ -36,10 +36,22 @@ export declare class MapService extends BaseServiceAbstract implements IBaseServ
      */
     listDeployedMaps(projectId: string, callsign: string): Promise<Map[]>;
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     merge(projectId: string, maps: [string, string], options: {
         name: string;

package/esm/services/MapService.js

@@ -1,4 +1,4 @@
-import { API_GRAPHS_MAPS_COPY_URL, API_GRAPHS_MAPS_DEPLOYED_URL, API_GRAPHS_MAPS_DEPLOY_URL, API_GRAPHS_MAPS_GEOJSON_URL, API_GRAPHS_MAPS_MERGE_URL, API_GRAPHS_MAPS_NEW_URL, API_GRAPHS_MAPS_URL, API_GRAPHS_MAP_CONTENT_URL, API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL, API_GRAPHS_MAP_EDGES_ADD_URL, API_GRAPHS_MAP_EDGE_URL, API_GRAPHS_MAP_ID_URL, API_GRAPHS_MAP_METADATA_URL, API_GRAPHS_MAP_NODES_ADD_TRANSFORMABLE_URL, API_GRAPHS_MAP_NODES_ADD_URL, API_GRAPHS_MAP_NODE_URL, API_GRAPHS_MAP_PATHS_URL, API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL, API_GRAPHS_MAP_PATH_APPEND_URL, API_GRAPHS_MAP_PATH_URL, API_GRAPHS_OBSERVATIONS_URL, API_GRAPHS_OBSERVATION_KEYS_URL, API_GRAPHS_PANORAMA, API_GRAPHS_PANORAMAS_URL, API_GRAPHS_PANORAMA_OBSERVATIONS_URL, } from '../constants/api';
+import { API_GRAPHS_MAPS_COPY_URL, API_GRAPHS_MAPS_DEPLOYED_URL, API_GRAPHS_MAPS_DEPLOY_URL, API_GRAPHS_MAPS_GEOJSON_URL, API_GRAPHS_MAPS_NEW_URL, API_GRAPHS_MAPS_UNION_URL, API_GRAPHS_MAPS_URL, API_GRAPHS_MAP_CONTENT_URL, API_GRAPHS_MAP_EDGES_ADD_TRANSFORM_URL, API_GRAPHS_MAP_EDGES_ADD_URL, API_GRAPHS_MAP_EDGE_URL, API_GRAPHS_MAP_ID_URL, API_GRAPHS_MAP_METADATA_URL, API_GRAPHS_MAP_NODES_ADD_TRANSFORMABLE_URL, API_GRAPHS_MAP_NODES_ADD_URL, API_GRAPHS_MAP_NODE_URL, API_GRAPHS_MAP_PATHS_URL, API_GRAPHS_MAP_PATH_APPEND_TRANSFORMABLE_URL, API_GRAPHS_MAP_PATH_APPEND_URL, API_GRAPHS_MAP_PATH_URL, API_GRAPHS_OBSERVATIONS_URL, API_GRAPHS_OBSERVATION_KEYS_URL, API_GRAPHS_PANORAMA, API_GRAPHS_PANORAMAS_URL, API_GRAPHS_PANORAMA_OBSERVATIONS_URL, } from '../constants/api';
 import { RocosError, errorCodes } from '../models';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 import { RocosLogger } from '../logger/RocosLogger';
@@ -52,26 +52,38 @@ export class MapService extends BaseServiceAbstract {
         return resp.maps;
     }
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     async merge(projectId, maps, options) {
         if (maps.length !== 2)
             throw new Error('You must provide two maps to merge.');
-        const payload = {
-            projectID: projectId,
-            mapIDLeft: maps[0],
-            mapIDRight: maps[1],
-            name: options.name,
-            description: options.description,
-            callsign: options.callsign,
-        };
-        return this.callPost(formatServiceUrl(API_GRAPHS_MAPS_MERGE_URL, {
+        await this.callPost(formatServiceUrl(API_GRAPHS_MAPS_UNION_URL, {
             url: this.config.url,
             projectId,
-        }, this.config.insecure), payload, 'Failed to merge maps.');
+        }, this.config.insecure), { targetMapId: options.name, sources: [maps[0], maps[1]] }, 'Failed to merge maps.');
+        if (options.description) {
+            try {
+                await this.updateMetadata(projectId, options.name, { description: options.description });
+            }
+            catch (e) {
+                this.logger.error(`Map ${options.name} was created but its description could not be set.`, e);
+            }
+        }
     }
     /** Returns a map in its canonical form
      *

package/esm/services/RobotStatusService.d.ts

@@ -1,4 +1,4 @@
-import { IBaseService, IRocosSDKConfig, RobotConnectivityStatus, RobotStatus, RocosError } from '../models';
+import { IBaseService, IRocosSDKConfig, RobotConnectivityStatus, RobotStatus, RobotStatusContributors, RocosError, ServiceConnection } from '../models';
 import { Observable } from 'rxjs';
 import { ReportedRobotStatus } from './robot-status/reportedStatus';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
@@ -10,6 +10,23 @@ export interface RobotStatusOptions {
     heartbeatTimeoutMs?: number;
     /** How often the connections endpoints are polled (ms, floored internally). */
     connectivityPollMs?: number;
+    /**
+     * Extra per-robot connectivity signals, keyed by service id, folded into
+     * {@link RobotConnectivityStatus.services} and the aggregate on equal footing with the built-in
+     * services. Lets a caller inject a signal the SDK can't derive itself (e.g. virtual-robot
+     * deployment status); emit {@link ServiceConnection.FAILED} to surface a fault as `DEGRADED`.
+     *
+     * A key that collides with a built-in service id (`telemetry-liveness`, `robot-configs`,
+     * `robot-services`) is ignored in favour of the built-in.
+     *
+     * An error from an injected observable is contained as {@link ServiceConnection.UNKNOWN} so it
+     * can't tear down the overall status stream — but it is *terminal* for that signal: unlike the
+     * built-in HTTP poller (which recovers on its next tick), the errored observable is not
+     * resubscribed, so the service stays `UNKNOWN` for the life of the stream (and `getConnectivity`
+     * then waits out its timeout). To report a recoverable fault, emit `FAILED` / `UNKNOWN` as a
+     * value rather than letting the observable error.
+     */
+    extraServices?: Record<string, Observable<ServiceConnection>>;
 }
 /**
  * The single source of truth for a robot's status. It composes the reported
@@ -22,6 +39,8 @@ export declare class RobotStatusService extends BaseServiceAbstract implements I
     getStatus(): boolean;
     /** Health + readiness as reported by the robot (new topic, legacy heartbeat fallback). */
     getReportedStatusChanges(projectId: string, callsign: string): Observable<ReportedRobotStatus>;
+    /** Per-contributor breakdown behind the reported health and readiness, with the reason for each. */
+    getStatusContributorsChanges(projectId: string, callsign: string): Observable<RobotStatusContributors>;
     /** 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. */

package/esm/services/RobotStatusService.js

@@ -1,7 +1,7 @@
 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 { getReportedStatusChanges, getStatusContributorsChanges, getTelemetryLiveness, } from './robot-status/reportedStatus';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 import { RocosLogger } from '../logger/RocosLogger';
 import { RocosStore } from '../store/RocosStore';
@@ -39,6 +39,10 @@ export class RobotStatusService extends BaseServiceAbstract {
     getReportedStatusChanges(projectId, callsign) {
         return getReportedStatusChanges(this.telemetryService, projectId, callsign);
     }
+    /** Per-contributor breakdown behind the reported health and readiness, with the reason for each. */
+    getStatusContributorsChanges(projectId, callsign) {
+        return getStatusContributorsChanges(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);
@@ -85,6 +89,7 @@ export class RobotStatusService extends BaseServiceAbstract {
             baseUrl: this.config.url,
             insecure: this.config.insecure,
             telemetryLiveness$: getTelemetryLiveness(this.telemetryService, projectId, callsign, opts?.heartbeatTimeoutMs),
+            extraServices: opts?.extraServices,
         };
     }
 }

package/esm/services/SearchService.js

@@ -1,7 +1,7 @@
 import { SubscriberStatusEnum, } from '../models';
 import { Subject } from 'rxjs';
 import { BaseStreamService } from './BaseStreamService';
-import { IDENTIFIER_NAME_FILE_ACCESSOR } from '../constants/identifier';
+import { IDENTIFIER_NAME_SEARCH } from '../constants/identifier';
 import { SearchStream } from '../api/streams/search/SearchStream';
 import { finalize } from 'rxjs/operators';
 export class SearchService extends BaseStreamService {
@@ -36,7 +36,7 @@ export class SearchService extends BaseStreamService {
         return stream.deleteProjectData(params);
     }
     async createStream() {
-        const newStream = await this.createStreamFromConfig(IDENTIFIER_NAME_FILE_ACCESSOR, {
+        const newStream = await this.createStreamFromConfig(IDENTIFIER_NAME_SEARCH, {
             url: this.config.url,
             token: this.config.token,
             scope: 'default',

package/esm/services/TargetService.js

@@ -1,4 +1,4 @@
-import { API_GRAPHS_ASSETS_UPLOAD_URL, API_GRAPHS_ASSETS_URL, API_GRAPHS_TARGETS_URL, API_GRAPHS_TARGET_UPLOAD_URL, } from '../constants/api';
+import { API_GRAPHS_ASSETS_UPLOAD_URL, API_GRAPHS_ASSETS_URL, API_GRAPHS_TARGETS_URL, API_GRAPHS_TARGET_MEDIA_URL, API_GRAPHS_TARGET_UPLOAD_URL, } from '../constants/api';
 import { RocosError, errorCodes } from '../models';
 import { BaseServiceAbstract } from './BaseServiceAbstract';
 import { RocosLogger } from '../logger/RocosLogger';
@@ -53,10 +53,10 @@ export class TargetService extends BaseServiceAbstract {
         });
     }
     async addMedia(projectId, targetId, media) {
-        await this.callPost(formatServiceUrl(API_GRAPHS_TARGETS_URL, {
+        await this.callPut(formatServiceUrl(API_GRAPHS_TARGET_MEDIA_URL, {
             url: this.config.url,
             projectId,
-            targetId,
+            targetId: encodeURIComponent(targetId),
         }, this.config.insecure), media, 'Failed to add media to a target');
     }
 }

package/esm/services/TelemetryService.d.ts

@@ -3,7 +3,6 @@ import { CallsignStatus, IRocosSDKConfig, IRocosTelemetryMessage, IStreamStatusM
 import { BaseStreamService } from './BaseStreamService';
 export declare class TelemetryService extends BaseStreamService<ITelemetryStream, ITelemetryStreamConfig> {
     private static grpcWebDeprecationWarned;
-    private statusSubscription;
     private changeStream$;
     private streamStatusSubject$;
     constructor(config: IRocosSDKConfig);
@@ -46,6 +45,6 @@ export declare class TelemetryService extends BaseStreamService<ITelemetryStream
     monitorTelemetryWithTimeout(projectId: string, callsign: string, source: string, heartbeatTimeoutMs?: number, intervalMs?: number): Observable<TelemetryMonitorStatus>;
     protected initStream(stream: ITelemetryStream): Promise<void>;
     private buildScope;
-    private createStream;
+    private buildStreamConfig;
     protected getStream(config: ITelemetryStreamConfig): ITelemetryStream;
 }