@dronedeploy/rocos-js-sdk 4.4.4 → 4.4.5

package/esm/api/streams/telemetry/TelemetryStreamAbstract.js

@@ -1,16 +1,18 @@
 import { BehaviorSubject, Subject } from 'rxjs';
-import { CallsignsLookup, CallsignsLookupType, RocosTelemetryMessage, StreamOptions, SubscriberStatusEnum, } from '../../../models';
+import { CallsignsLookup, RocosTelemetryMessage, StreamOptions, SubscriberStatusEnum, } from '../../../models';
 import { GRPC_SOURCE_NOOP, GRPC_SOURCE_SUBSCRIBED } from '../../../constants/grpc';
 import { QueryOrPredicate, TelemetryAckStatus, TelemetryQueryRequest, TelemetryRequest, UnsubscribeOperation, } from '../../../grpc/teletubby_pb';
 import { IDENTIFIER_NAME_TELEMETRY } from '../../../constants/identifier';
 import { RocosStore } from '../../../store/RocosStore';
 import { StreamHeartbeat } from '../../atoms/StreamHeartbeat';
 import { StreamRegister } from '../../StreamRegister';
+import { arrayRemove } from '../../../helpers/arrayRemove';
 import { arrayUnique } from '../../../helpers/arrayUnique';
 import { filter } from 'rxjs/operators';
 import { getSubscriptionsDifference } from '../../../helpers/getSubscriptionsDifference';
 export class TelemetryStreamAbstract {
     constructor(config) {
+        this.telemetryActionQueue = Promise.resolve();
         // /////////////////
         // Subscriber Check
         this.timerIntervalInSec = 1;
@@ -61,23 +63,36 @@ export class TelemetryStreamAbstract {
     addSubscription(params) {
         this.logger.info('Adding subscriptions from stream', params.uniqueId);
         if (!this.subscriptions.has(params.uniqueId)) {
+            const isQuery = this.isQueryLookup();
             // get subscriptions before change
-            const before = this.getSubscriptions();
+            const before = isQuery ? {} : this.getSubscriptions();
             this.subscriptions.set(params.uniqueId, {
                 ...params,
                 count: 1, // set the count to one just in case it's set in param
             });
             // get subscriptions after change
-            const after = this.getSubscriptions();
-            // assign the current values from state after change
-            this.callsignsLookup = new CallsignsLookup(Object.keys(after));
-            this.sources = arrayUnique(Object.values(after).reduce((a, v) => a.concat(v), []));
-            // compare before and after subscriptions and only add the difference
-            const { toAdd } = getSubscriptionsDifference(before, after);
-            // only subscribe if the subscriberId exists, otherwise the messages will be subscribed on lazy load
-            if (toAdd.callsigns.length && toAdd.sources.length) {
-                this.logger.debug('New subscriptions added, we need to refresh sources', { toAdd });
-                void this.takeTelemetryAction('subscribe', new CallsignsLookup(toAdd.callsigns), toAdd.sources);
+            const after = isQuery ? {} : this.getSubscriptions();
+            if (isQuery) {
+                // A query stream selects its callsigns server-side, so the callsign-keyed view above holds
+                // nothing for it: keep the query and diff on sources alone.
+                const sourcesBefore = this.sources;
+                this.sources = this.getSubscribedSources();
+                const toAdd = arrayRemove(this.sources, sourcesBefore);
+                if (toAdd.length) {
+                    this.logger.debug('New query subscriptions added, we need to refresh sources', { toAdd });
+                    void this.enqueueTelemetryAction('subscribe', this.callsignsLookup, toAdd);
+                }
+            }
+            else {
+                // assign the current values from state after change
+                this.callsignsLookup = new CallsignsLookup(Object.keys(after));
+                this.sources = arrayUnique(Object.values(after).reduce((a, v) => a.concat(v), []));
+                // compare before and after subscriptions and only add the difference
+                const { toAdd } = getSubscriptionsDifference(before, after);
+                if (toAdd.callsigns.length && toAdd.sources.length) {
+                    this.logger.debug('New subscriptions added, we need to refresh sources', { toAdd });
+                    void this.enqueueTelemetryAction('subscribe', new CallsignsLookup(toAdd.callsigns), toAdd.sources);
+                }
             }
         }
         else {
@@ -97,16 +112,24 @@ export class TelemetryStreamAbstract {
         if (subs.count)
             return;
         this.logger.info('Removing subscriptions from stream registry', params.uniqueId);
-        const before = this.getSubscriptions();
+        const isQuery = this.isQueryLookup();
+        const before = isQuery ? {} : this.getSubscriptions();
         this.subscriptions.delete(params.uniqueId);
-        const after = this.getSubscriptions();
-        // Do this before we send the telemetry request so that new subscriptions don't get this stream from the register while it is closing
-        if (!this.subscriptions.size) {
-            this.logger.info('No subscriptions remaining closing stream', params.uniqueId);
-            this.stopStream();
-            // self remove when no subscriptions are left
-            StreamRegister.getInstance().removeStream(this);
-            this.logger.info('Stream closed');
+        const after = isQuery ? {} : this.getSubscriptions();
+        if (isQuery) {
+            const sourcesBefore = this.sources;
+            this.sources = this.getSubscribedSources();
+            const toRemove = arrayRemove(sourcesBefore, this.sources);
+            if (toRemove.length) {
+                this.logger.debug('Query subscriptions removed, we need to refresh sources', { toRemove });
+                try {
+                    await this.enqueueTelemetryAction('unsubscribe', this.callsignsLookup, toRemove, terminateReceiverGroup);
+                }
+                catch (err) {
+                    this.logger.error(`Failed to unsubscribe: ${err}`);
+                }
+            }
+            return;
         }
         // assign the current values from state after change
         this.callsignsLookup = new CallsignsLookup(Object.keys(after));
@@ -115,13 +138,23 @@ export class TelemetryStreamAbstract {
         if (toRemove.callsigns.length && toRemove.sources.length) {
             this.logger.debug('Subscriptions removed, we need to refresh sources', { toRemove });
             try {
-                await this.takeTelemetryAction('unsubscribe', new CallsignsLookup(toRemove.callsigns), toRemove.sources, terminateReceiverGroup);
+                await this.enqueueTelemetryAction('unsubscribe', new CallsignsLookup(toRemove.callsigns), toRemove.sources, terminateReceiverGroup);
             }
             catch (err) {
                 this.logger.error(`Failed to unsubscribe: ${err}`);
             }
         }
     }
+    isQueryLookup() {
+        return this.callsignsLookup?.isQuery() ?? false;
+    }
+    getSubscribedSources() {
+        const sources = [];
+        this.subscriptions.forEach((data) => {
+            sources.push(...data.sources);
+        });
+        return arrayUnique(sources);
+    }
     sendAcknowledgment(uid, status, noRetry) {
         return this.sendAcknowledgmentInternal(uid, status, noRetry);
     }
@@ -171,8 +204,8 @@ export class TelemetryStreamAbstract {
                 this.subscriberId = subscriberId;
                 rocosMessage.subscriberId = this.subscriberId;
                 this.logger.info('onData', `subscriberId has been updated - ${subscriberId}`, { subscriberId });
-                void this.takeTelemetryAction('subscribe');
-                this.heartbeat.start(this.sendHeartbeat, this.sendHeartbeatTime);
+                void this.enqueueTelemetryAction('subscribe');
+                this.heartbeat.start(() => this.sendHeartbeat(), this.sendHeartbeatTime);
                 isRobotMessage = false;
                 break;
             }
@@ -208,25 +241,40 @@ export class TelemetryStreamAbstract {
             });
         }
     }
+    /**
+     * Gateway subscription state is a set mutated by deltas, so ordering is correctness: a concurrent
+     * unsubscribe landing last strands a subscribe and nothing re-adds it.
+     */
+    enqueueTelemetryAction(actionType, callsignsLookup, sources, terminate) {
+        const takeAction = () => this.takeTelemetryAction(actionType, callsignsLookup, sources, terminate);
+        const run = this.telemetryActionQueue.then(takeAction);
+        // The tail only signals whose turn it is, so it must never reject, otherwise one failed op
+        // would wedge every op queued behind it. Callers still see the failure through `run`.
+        this.telemetryActionQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
     async takeTelemetryAction(actionType, callsignsLookup, sources, terminate) {
         this.logger.debug('takeTelemetryAction', actionType);
-        if (!this.subscriberId || !this.projectId) {
-            this.logger.debug('takeTelemetryAction', actionType, `${actionType} without subscriberId or projectId - message will not send out`, {
-                subscriberId: this.subscriberId,
-                projectId: this.projectId,
-            });
+        // A config fault, not a race: this stream can never address a request.
+        if (!this.projectId) {
+            this.logger.warn('takeTelemetryAction', actionType, `${actionType} without a projectId - dropped`);
+            return Promise.resolve();
+        }
+        if (!this.subscriberId) {
+            // Deferred, not lost: `onData` re-asserts `this.sources` when the subscriberId arrives.
+            this.logger.debug('takeTelemetryAction', actionType, `${actionType} before the receiver was registered - deferred to the post-registration re-assert`);
             return Promise.resolve();
         }
         const actionSources = sources ?? this.sources;
         const actionCallsigns = callsignsLookup ?? this.callsignsLookup;
-        if (this.callsignsLookup.lookupType === CallsignsLookupType.List) {
+        if (!actionCallsigns.isQuery()) {
             // Compose the request message
             const req = TelemetryRequest.create({
                 subscriberId: this.subscriberId,
                 requestedActions: [
                     {
                         operation: actionType,
-                        callsigns: actionCallsigns.lookupValue,
+                        callsigns: actionCallsigns.getCallsigns(),
                         sources: actionSources,
                     },
                 ],
@@ -238,12 +286,12 @@ export class TelemetryStreamAbstract {
             // Send the message to back-end.
             return this.requestTelemetry(req);
         }
-        else if (actionCallsigns.lookupType === CallsignsLookupType.Query) {
-            const lookupValue = actionCallsigns.lookupValue;
+        const query = actionCallsigns.getQuery();
+        if (query) {
             // We don't support nested query at the moment
             const queryOrPredicatesList = [];
             // Loop through user provided predicates to construct a telemetry query request
-            lookupValue.predicates.forEach((callsignsPredicate) => {
+            query.predicates.forEach((callsignsPredicate) => {
                 const queryOrPredicate = QueryOrPredicate.create({
                     content: {
                         oneofKind: 'predicate',
@@ -262,7 +310,7 @@ export class TelemetryStreamAbstract {
                 sources: actionSources,
                 operation: actionType,
                 callsignQuery: {
-                    operation: lookupValue.operation.valueOf(),
+                    operation: query.operation.valueOf(),
                     queryOrPredicates: queryOrPredicatesList,
                 },
             });
@@ -379,16 +427,11 @@ export class TelemetryStreamAbstract {
         this.lastRobotMessageReceived = undefined;
         this.registerReceiver();
     }
-    isFoundCallsign(callsign) {
-        return this.callsignsLookup.lookupType === CallsignsLookupType.List
-            ? this.callsignsLookup.lookupValue.indexOf(callsign) !== -1
-            : true; // If callsigns lookup option is query, we always return true
-    }
     isFoundSource(source) {
         return this.sources.indexOf(source) !== -1;
     }
     isRegisteredMessage(callsign, source) {
-        return this.isFoundCallsign(callsign) && this.isFoundSource(source);
+        return this.callsignsLookup.includesCallsign(callsign) && this.isFoundSource(source);
     }
     updateReceivedDataStatsWithMessage(msg) {
         const { source } = msg;

package/esm/api/streams/webRTCSignalling/WebRTCSignallingStreamAbstract.js

@@ -1,7 +1,7 @@
 import { AddIceCandidateRequest, GetDetailsRequest, OfferRequest, OperatorConnectRequest, } from '../../../grpc/pigeon_pb';
 import { SubscriberStatusEnum, } from '../../../models';
 import { BehaviorSubject } from 'rxjs';
-import { IDENTIFIER_NAME_COMMAND } from '../../../constants/identifier';
+import { IDENTIFIER_NAME_WEBRTC_SIGNALLING } from '../../../constants/identifier';
 import { RocosStore } from '../../../store/RocosStore';
 import { StreamRegister } from '../../StreamRegister';
 import { filter } from 'rxjs/operators';
@@ -9,7 +9,7 @@ export class WebRTCSignallingStreamAbstract {
     constructor(config) {
         this.subscriberStatus = SubscriberStatusEnum.STOPPED;
         this.scope = config.scope;
-        this.identifier = StreamRegister.getIdentifier(IDENTIFIER_NAME_COMMAND, this.scope);
+        this.identifier = StreamRegister.getIdentifier(IDENTIFIER_NAME_WEBRTC_SIGNALLING, this.scope);
         this.token = config.token;
         this.url = config.url;
         this.statusStream$ = new BehaviorSubject(SubscriberStatusEnum.STOPPED);

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/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/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',