@openfin/cloud-interop-core-api 0.0.1-alpha.6d7b62b → 0.0.1-alpha.6da3439

package/{dist/bundle.d.ts → bundle.d.ts}

@@ -1,12 +1,24 @@
 import mqtt from 'mqtt';
 import { z } from 'zod';
 
+/**
+ * Raised when an interop client receives an aggregate of intents from other connected sessions
+ * @public
+ */
 export declare type AggregateIntentDetailsEvent = {
     responses: IntentDetailsEvent[];
 };
 
+/**
+ * Represents an app intent
+ * @public
+ */
 export declare type AppIdentifier = z.infer<typeof appIdentifierSchema>;
 
+/**
+ * Schema for an AppIdentifier
+ * @public
+ */
 declare const appIdentifierSchema: z.ZodObject<{
     appId: z.ZodString;
     instanceId: z.ZodOptional<z.ZodString>;
@@ -18,8 +30,16 @@ declare const appIdentifierSchema: z.ZodObject<{
     instanceId?: string | undefined;
 }>;
 
+/**
+ * Represents an app intent
+ * @public
+ */
 export declare type AppIntent = z.infer<typeof appIntentSchema>;
 
+/**
+ * Schema for an app intent
+ * @public
+ */
 declare const appIntentSchema: z.ZodObject<{
     intent: z.ZodObject<{
         displayName: z.ZodString;
@@ -175,30 +195,36 @@ export declare class AuthorizationError extends CloudInteropAPIError {
 }
 
 /**
- * @internal
  * Represents a base event for the cloud interop api
+ * @public
  * @property {Source} source - The source of the event
  * @property {HistoryRecord} history - A trail of timestamps of when the context hit various points in the system
  */
-declare type BaseCloudInteropAPIEvent = {
+export declare type BaseCloudInteropAPIEvent = {
     /**
      * The source of the event
      */
     source: Source;
     /**
      * A trail of timestamps of when the event hit various points in the system
+     * @internal
      */
     history?: HistoryRecord;
 };
 
 /**
  * Represents an Intent Discovery Event
+ * @public
  */
-declare type BaseIntentDiscoveryEvent = BaseIntentEvent & {
+export declare type BaseIntentDiscoveryEvent = BaseIntentEvent & {
     discoveryId: string;
 };
 
-declare type BaseIntentEvent = BaseCloudInteropAPIEvent & {
+/**
+ * Represents a base intent event
+ * @public
+ */
+export declare type BaseIntentEvent = BaseCloudInteropAPIEvent & {
     /**
      * The session id of the interop client that initiated an intent action
      */
@@ -208,9 +234,8 @@ declare type BaseIntentEvent = BaseCloudInteropAPIEvent & {
 /**
  * Represents a single connection to a Cloud Interop service
  *
- * @export
- * @class CloudInteropAPI
- * @implements {Client}
+ * @public
+ * @class
  */
 export declare class CloudInteropAPI {
     #private;
@@ -221,7 +246,7 @@ export declare class CloudInteropAPI {
      * Connects and creates a session on the Cloud Interop service
      *
      * @param {ConnectParameters} parameters - The parameters to use to connect
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during connection
      * @throws {AuthorizationError} - If the connection is unauthorized
@@ -230,7 +255,7 @@ export declare class CloudInteropAPI {
     /**
      * Disconnects from the Cloud Interop service
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during disconnection
      */
@@ -240,14 +265,14 @@ export declare class CloudInteropAPI {
      *
      * @param {string} contextGroup - The context group to publish to
      * @param {object} context - The context to publish
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      */
-    setContext(contextGroup: string, context: object): Promise<void>;
+    setContext(contextGroup: string, context: InferredContext): Promise<void>;
     /**
      * Starts an intent discovery operation
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during intent discovery
      */
@@ -256,6 +281,7 @@ export declare class CloudInteropAPI {
     reportAppIntents(discoveryId: string, intents: AppIntent[]): Promise<boolean>;
     sendIntentResult(initiatingSessionId: string, result: IntentResult): Promise<void>;
     parseSessionId(appId: AppIdentifier | string): string;
+    parseAppId(appId: AppIdentifier | string): string;
     addEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
     removeEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
     once<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
@@ -275,6 +301,9 @@ export declare type CloudInteropSettings = {
     url: string;
 };
 
+/**
+ * @internal
+ */
 export declare type CommandMessage = ReportIntentsCommand | IntentDetailsCommand | RaiseIntentCommand | IntentResultCommand;
 
 /**
@@ -347,9 +376,7 @@ export declare type ConnectParameters = {
 
 /**
  * Represents a context received from another cloud interop publisher
- *
- * @export
- * @type ContextEvent
+ * @public
  * @property {string} contextGroup - The context group
  * @property {object} context - The context
  */
@@ -364,6 +391,10 @@ export declare type ContextEvent = BaseCloudInteropAPIEvent & {
     context?: InferredContext;
 };
 
+/**
+ * Schema for context object
+ * @public
+ */
 declare const contextSchema: z.ZodIntersection<z.ZodObject<{
     type: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
@@ -389,6 +420,14 @@ export declare type CreateSessionResponse = {
     sourceId: string;
 };
 
+declare const errorSchema: z.ZodObject<{
+    error: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+}, {
+    error: string;
+}>;
+
 export declare type EventListenersMap = Map<keyof EventMap, Array<(...args: Parameters<EventMap[keyof EventMap]>) => void>>;
 
 export declare type EventMap = {
@@ -407,9 +446,14 @@ export declare type EventMap = {
 
 /**
  * Options for finding intents by intent name or context
+ * @public
  */
 export declare type FindIntentOptions = z.infer<typeof findIntentOptionsSchema>;
 
+/**
+ * Schema for findOptions for the StartDiscovery operation
+ * @public
+ */
 declare const findIntentOptionsSchema: z.ZodUnion<[z.ZodObject<{
     type: z.ZodLiteral<"find-intent">;
     intent: z.ZodString;
@@ -480,8 +524,8 @@ declare const findIntentOptionsSchema: z.ZodUnion<[z.ZodObject<{
 }>]>;
 
 /**
- * @internal
  * A trace record for performance monitoring
+ * @internal
  */
 declare type HistoryRecord = {
     /**
@@ -503,19 +547,33 @@ declare type HistoryRecord = {
     clientReceived?: number;
 };
 
+/**
+ * Represents a context object
+ * @public
+ */
 export declare type InferredContext = z.infer<typeof contextSchema>;
 
+export declare type InferredError = z.infer<typeof errorSchema>;
+
+/**
+ * @internal
+ */
 export declare type IntentDetailsCommand = IntentDetailsEvent & {
     command: 'intent-details';
 };
 
 /**
  * Raised when an interop client receives intents from other connected sessions
+ * @public
  */
 export declare type IntentDetailsEvent = BaseIntentDiscoveryEvent & {
     intents: AppIntent[];
 };
 
+/**
+ * Represents an intent resolution
+ * @public
+ */
 export declare type IntentResolution = z.infer<typeof intentResolutionSchema>;
 
 declare const intentResolutionSchema: z.ZodObject<{
@@ -570,19 +628,31 @@ declare const intentResolutionSchema: z.ZodObject<{
     } & Record<string, any>) | undefined;
 }>;
 
+/**
+ * Represents an intent result
+ * @public
+ */
 export declare type IntentResult = z.infer<typeof intentResultSchema>;
 
+/**
+ * @internal
+ */
 export declare type IntentResultCommand = IntentResultEvent & {
     command: 'intent-result';
 };
 
 /**
  * Raised when an interop client receives an intent result after raising an intent on a target session
+ * @public
  */
 export declare type IntentResultEvent = BaseIntentEvent & {
     result: IntentResult;
 };
 
+/**
+ * Schema for the result of an intent
+ * @public
+ */
 declare const intentResultSchema: z.ZodUnion<[z.ZodObject<{
     error: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -645,18 +715,23 @@ export declare type LogLevel = 'log' | 'debug' | 'info' | 'warn' | 'error';
 
 /**
  * Options used to raise an Intent
+ * @public
  */
 export declare type RaiseIntentAPIOptions = {
     raiseOptions: RaiseIntentOptions;
     appId: AppIdentifier | string;
 };
 
+/**
+ * @internal
+ */
 export declare type RaiseIntentCommand = RaiseIntentEvent & {
     command: 'raise-intent';
 };
 
 /**
  * Raised when an interop client invokes an intent
+ * @public
  */
 export declare type RaiseIntentEvent = BaseIntentEvent & {
     targetSessionId: string;
@@ -665,9 +740,14 @@ export declare type RaiseIntentEvent = BaseIntentEvent & {
 
 /**
  * Options for raising an intent by intent name or context
+ * @public
  */
 export declare type RaiseIntentOptions = z.infer<typeof raiseIntentOptionsSchema>;
 
+/**
+ * Schema for raiseOptions for the RaiseIntent operation
+ * @public
+ */
 declare const raiseIntentOptionsSchema: z.ZodUnion<[z.ZodObject<{
     type: z.ZodLiteral<"raise-intent">;
     intent: z.ZodString;
@@ -731,12 +811,16 @@ declare const raiseIntentOptionsSchema: z.ZodUnion<[z.ZodObject<{
     } & Record<string, any>;
 }>]>;
 
+/**
+ * @internal
+ */
 export declare type ReportIntentsCommand = ReportIntentsEvent & {
     command: 'report-intents';
 };
 
 /**
  * Raised when an interop client requests intents from other connected sessions.
+ * @public
  */
 export declare type ReportIntentsEvent = BaseIntentDiscoveryEvent & {
     /**
@@ -754,6 +838,7 @@ export declare type ReportIntentsEvent = BaseIntentDiscoveryEvent & {
 
 /**
  * Represents a source session
+ * @public
  */
 export declare type Source = {
     /**
@@ -780,6 +865,7 @@ export declare type Source = {
 
 /**
  * Options used to start an Intent Discovery Operation, with possible constraints for the responses
+ * @public
  */
 export declare type StartIntentDiscoveryOptions = {
     findOptions: FindIntentOptions;

package/{dist/index.cjs → index.cjs}

@@ -46,6 +46,8 @@ class EventController {
     }
 }
 
+const isErrorIntentResult = (result) => 'error' in result;
+
 const APP_ID_DELIM = '::';
 const getRequestHeaders = (connectionParameters) => {
     const headers = {};
@@ -72,13 +74,9 @@ const getRequestHeaders = (connectionParameters) => {
  * @param source
  * @returns
  */
-const encodeAppIntents = (appIntents, { sessionId, sourceId }) => appIntents.map((intent) => ({
+const encodeAppIntents = (appIntents, source) => appIntents.map((intent) => ({
     ...intent,
-    apps: intent.apps.map((app) => {
-        const id = encodeURIComponent(app.appId);
-        const sId = encodeURIComponent(sourceId);
-        return { ...app, appId: `${id}${APP_ID_DELIM}${sId}${APP_ID_DELIM}${sessionId}` };
-    }),
+    apps: intent.apps.map((app) => ({ ...app, appId: encodeAppId(app.appId, source) })),
 }));
 /**
  * Decodes all app intents by URI decoding the parts previously encoded by `encodeAppIntents`
@@ -87,19 +85,35 @@ const encodeAppIntents = (appIntents, { sessionId, sourceId }) => appIntents.map
  */
 const decodeAppIntents = (appIntents) => appIntents.map((intent) => ({
     ...intent,
-    apps: intent.apps.map((app) => {
-        const [encodedAppId, encodedSourceId, sessionId] = app.appId.split(APP_ID_DELIM);
-        const id = decodeURIComponent(encodedAppId);
-        const sourceId = decodeURIComponent(encodedSourceId);
-        return { ...app, appId: `${id}${APP_ID_DELIM}${sourceId}${APP_ID_DELIM}${sessionId}` };
-    }),
+    apps: intent.apps.map((app) => ({ ...app, appId: decodeAppId(app.appId) })),
 }));
+const encodeAppId = (appIdString, { sessionId, sourceId }) => {
+    const id = encodeURIComponent(appIdString);
+    const sId = encodeURIComponent(sourceId);
+    return `${id}${APP_ID_DELIM}${sId}${APP_ID_DELIM}${sessionId}`;
+};
+const decodeAppId = (appId) => {
+    const [encodedAppId, encodedSourceId, sessionId] = appId.split(APP_ID_DELIM);
+    const id = decodeURIComponent(encodedAppId);
+    const sourceId = decodeURIComponent(encodedSourceId);
+    return `${id}${APP_ID_DELIM}${sourceId}${APP_ID_DELIM}${sessionId}`;
+};
 /**
- * Decodes the app id to extract the sessionId, returns '' if not able to parse
- * @param app
- * @returns
+ * Decodes the AppIdentifier to extract the appId, sourceId, and sessionId.
+ * @returns an object with:
+ * - appId: The appId, or the original appId if unable to parse.
+ * - sourceId: The sourceId, or an '' if unable to parse.
+ * - sessionId: The sessionId, or an '' if unable to parse.
  */
-const parseSessionId = (appId) => (typeof appId === 'string' ? appId : appId.appId).split(APP_ID_DELIM)?.[2]?.trim() ?? '';
+const parseCloudAppId = (appId = '') => {
+    const originalAppString = typeof appId === 'string' ? appId : (appId.appId ?? '');
+    const parts = originalAppString.split(APP_ID_DELIM);
+    return {
+        appId: parts[0]?.trim() ?? originalAppString,
+        sourceId: parts[1]?.trim() ?? '',
+        sessionId: parts[2]?.trim() ?? '',
+    };
+};
 const getSourceFromSession = (sessionDetails) => ({
     sessionId: sessionDetails.sessionId,
     sourceId: sessionDetails.sourceId,
@@ -148,13 +162,18 @@ class IntentController {
                 body: JSON.stringify({ findOptions }),
             });
             if (!startResponse.ok) {
-                throw new Error(startResponse.statusText);
+                throw new Error(`Error creating intent discovery record: ${startResponse.statusText}`);
             }
             // TODO: type this response?
             const json = await startResponse.json();
             this.#discovery.id = json.discoveryId;
             this.#discovery.sessionCount = json.sessionCount;
             this.#discovery.state = 'in-progress';
+            if (this.#discovery.sessionCount === 1) {
+                // since we have no other connected sessions, we can end discovery immediately
+                await this.#endIntentDiscovery(false);
+                return;
+            }
             // Listen out for discovery results directly sent to us
             await this.#mqttClient.subscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`);
             this.#discoveryTimeout = setTimeout(() => this.#endIntentDiscovery(), clampedTimeout);
@@ -165,10 +184,8 @@ class IntentController {
             throw new CloudInteropAPIError('Error starting intent discovery', 'ERR_STARTING_INTENT_DISCOVERY', error);
         }
     }
-    async #endIntentDiscovery() {
+    async #endIntentDiscovery(mqttUnsubscribe = true) {
         if (this.#discovery.state !== 'in-progress') {
-            // TODO: remove debug logs
-            this.#logger('debug', 'Intent discovery not in progress');
             return;
         }
         if (this.#discoveryTimeout) {
@@ -178,10 +195,12 @@ class IntentController {
         this.#discovery.state = 'ended';
         // emit our aggregated events
         this.#events.emitEvent('aggregate-intent-details', { responses: this.#discovery.pendingIntentDetailsEvents });
-        // gracefully end discovery
-        await this.#mqttClient.unsubscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`).catch(() => {
-            this.#logger('warn', `Error ending intent discovery: could not unsubscribe from discovery id ${this.#discovery.id}`);
-        });
+        if (mqttUnsubscribe) {
+            // gracefully end discovery
+            await this.#mqttClient.unsubscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`).catch(() => {
+                this.#logger('warn', `Error ending intent discovery: could not unsubscribe from discovery id ${this.#discovery.id}`);
+            });
+        }
         await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}/${this.#discovery.id}`, {
             method: 'DELETE',
             headers: getRequestHeaders(this.#connectionParams),
@@ -190,7 +209,6 @@ class IntentController {
             if (!deleteResponse.ok) {
                 throw new Error(`Error ending intent discovery: ${deleteResponse.statusText}`);
             }
-            this.#logger('debug', 'Intent discovery ended');
         })
             .catch((error) => {
             this.#logger('warn', `Error ending intent discovery: ${error}`);
@@ -199,7 +217,7 @@ class IntentController {
         this.#discovery = newDiscovery();
     }
     async raiseIntent({ raiseOptions, appId }) {
-        const targetSessionId = parseSessionId(appId);
+        const targetSessionId = parseCloudAppId(appId).sessionId;
         if (!targetSessionId) {
             // TODO: should we add more info here about the format?
             throw new CloudInteropAPIError(`Invalid AppId specified, must be encoded as a cloud-session app id`, 'ERR_INVALID_TARGET_SESSION_ID');
@@ -234,6 +252,13 @@ class IntentController {
         return false;
     }
     async sendIntentResult(initiatingSessionId, result) {
+        if (!isErrorIntentResult(result)) {
+            // cloud-encode the source app id to support chained intent actions over cloud
+            // https://fdc3.finos.org/docs/2.0/api/spec#resolution-object -> "Use metadata about the resolving app instance to target a further intent"
+            const source = getSourceFromSession(this.#sessionDetails);
+            const encoded = encodeAppId(typeof result.source === 'string' ? result.source : result.source.appId, source);
+            result.source = typeof result.source === 'string' ? encoded : { ...result.source, appId: encoded };
+        }
         const { sessionId } = getSourceFromSession(this.#sessionDetails);
         const resultResponse = await fetch(`${this.#url}/api/intents/${initiatingSessionId}/result/${sessionId}`, {
             method: 'POST',
@@ -311,9 +336,8 @@ const BadUserNamePasswordError = 134;
 /**
  * Represents a single connection to a Cloud Interop service
  *
- * @export
- * @class CloudInteropAPI
- * @implements {Client}
+ * @public
+ * @class
  */
 class CloudInteropAPI {
     #cloudInteropSettings;
@@ -342,7 +366,7 @@ class CloudInteropAPI {
      * Connects and creates a session on the Cloud Interop service
      *
      * @param {ConnectParameters} parameters - The parameters to use to connect
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during connection
      * @throws {AuthorizationError} - If the connection is unauthorized
@@ -454,7 +478,7 @@ class CloudInteropAPI {
     /**
      * Disconnects from the Cloud Interop service
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during disconnection
      */
@@ -466,7 +490,7 @@ class CloudInteropAPI {
      *
      * @param {string} contextGroup - The context group to publish to
      * @param {object} context - The context to publish
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      */
     async setContext(contextGroup, context) {
@@ -493,7 +517,7 @@ class CloudInteropAPI {
     /**
      * Starts an intent discovery operation
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during intent discovery
      */
@@ -514,7 +538,10 @@ class CloudInteropAPI {
         return this.#intents?.sendIntentResult(initiatingSessionId, result);
     }
     parseSessionId(appId) {
-        return parseSessionId(appId);
+        return parseCloudAppId(appId).sessionId;
+    }
+    parseAppId(appId) {
+        return parseCloudAppId(appId).appId;
     }
     addEventListener(type, callback) {
         this.#events.addEventListener(type, callback);
@@ -526,10 +553,13 @@ class CloudInteropAPI {
         this.#events.once(type, callback);
     }
     async #disconnect(fireDisconnectedEvent) {
-        if (!this.#sessionDetails || !this.#connectionParams) {
+        if (!this.#sessionDetails) {
             return;
         }
         try {
+            if (!this.#connectionParams) {
+                throw new Error('Connect parameters must be provided');
+            }
             const disconnectResponse = await fetch(`${this.#cloudInteropSettings.url}/api/sessions/${this.#sessionDetails.sessionId}`, {
                 method: 'DELETE',
                 headers: getRequestHeaders(this.#connectionParams),
@@ -565,8 +595,13 @@ class CloudInteropAPI {
             if (contextEvent.source.sessionId === sessionDetails.sessionId) {
                 return;
             }
-            const { contextGroup, context, source, history } = contextEvent;
-            this.#events.emitEvent('context', { contextGroup, context, source, history: { ...history, clientReceived: Date.now() } });
+            const { context, payload, contextGroup, channelName, source, history } = contextEvent;
+            this.#events.emitEvent('context', {
+                contextGroup: channelName || contextGroup,
+                context: payload || context,
+                source,
+                history: { ...history, clientReceived: Date.now() },
+            });
         }
         else if (topic.startsWith(`${sessionDetails.sessionRootTopic}/commands`)) {
             this.#handleCommandMessage(messageEnvelope);

package/{dist/index.mjs → index.mjs}

@@ -44,6 +44,8 @@ class EventController {
     }
 }
 
+const isErrorIntentResult = (result) => 'error' in result;
+
 const APP_ID_DELIM = '::';
 const getRequestHeaders = (connectionParameters) => {
     const headers = {};
@@ -70,13 +72,9 @@ const getRequestHeaders = (connectionParameters) => {
  * @param source
  * @returns
  */
-const encodeAppIntents = (appIntents, { sessionId, sourceId }) => appIntents.map((intent) => ({
+const encodeAppIntents = (appIntents, source) => appIntents.map((intent) => ({
     ...intent,
-    apps: intent.apps.map((app) => {
-        const id = encodeURIComponent(app.appId);
-        const sId = encodeURIComponent(sourceId);
-        return { ...app, appId: `${id}${APP_ID_DELIM}${sId}${APP_ID_DELIM}${sessionId}` };
-    }),
+    apps: intent.apps.map((app) => ({ ...app, appId: encodeAppId(app.appId, source) })),
 }));
 /**
  * Decodes all app intents by URI decoding the parts previously encoded by `encodeAppIntents`
@@ -85,19 +83,35 @@ const encodeAppIntents = (appIntents, { sessionId, sourceId }) => appIntents.map
  */
 const decodeAppIntents = (appIntents) => appIntents.map((intent) => ({
     ...intent,
-    apps: intent.apps.map((app) => {
-        const [encodedAppId, encodedSourceId, sessionId] = app.appId.split(APP_ID_DELIM);
-        const id = decodeURIComponent(encodedAppId);
-        const sourceId = decodeURIComponent(encodedSourceId);
-        return { ...app, appId: `${id}${APP_ID_DELIM}${sourceId}${APP_ID_DELIM}${sessionId}` };
-    }),
+    apps: intent.apps.map((app) => ({ ...app, appId: decodeAppId(app.appId) })),
 }));
+const encodeAppId = (appIdString, { sessionId, sourceId }) => {
+    const id = encodeURIComponent(appIdString);
+    const sId = encodeURIComponent(sourceId);
+    return `${id}${APP_ID_DELIM}${sId}${APP_ID_DELIM}${sessionId}`;
+};
+const decodeAppId = (appId) => {
+    const [encodedAppId, encodedSourceId, sessionId] = appId.split(APP_ID_DELIM);
+    const id = decodeURIComponent(encodedAppId);
+    const sourceId = decodeURIComponent(encodedSourceId);
+    return `${id}${APP_ID_DELIM}${sourceId}${APP_ID_DELIM}${sessionId}`;
+};
 /**
- * Decodes the app id to extract the sessionId, returns '' if not able to parse
- * @param app
- * @returns
+ * Decodes the AppIdentifier to extract the appId, sourceId, and sessionId.
+ * @returns an object with:
+ * - appId: The appId, or the original appId if unable to parse.
+ * - sourceId: The sourceId, or an '' if unable to parse.
+ * - sessionId: The sessionId, or an '' if unable to parse.
  */
-const parseSessionId = (appId) => (typeof appId === 'string' ? appId : appId.appId).split(APP_ID_DELIM)?.[2]?.trim() ?? '';
+const parseCloudAppId = (appId = '') => {
+    const originalAppString = typeof appId === 'string' ? appId : (appId.appId ?? '');
+    const parts = originalAppString.split(APP_ID_DELIM);
+    return {
+        appId: parts[0]?.trim() ?? originalAppString,
+        sourceId: parts[1]?.trim() ?? '',
+        sessionId: parts[2]?.trim() ?? '',
+    };
+};
 const getSourceFromSession = (sessionDetails) => ({
     sessionId: sessionDetails.sessionId,
     sourceId: sessionDetails.sourceId,
@@ -146,13 +160,18 @@ class IntentController {
                 body: JSON.stringify({ findOptions }),
             });
             if (!startResponse.ok) {
-                throw new Error(startResponse.statusText);
+                throw new Error(`Error creating intent discovery record: ${startResponse.statusText}`);
             }
             // TODO: type this response?
             const json = await startResponse.json();
             this.#discovery.id = json.discoveryId;
             this.#discovery.sessionCount = json.sessionCount;
             this.#discovery.state = 'in-progress';
+            if (this.#discovery.sessionCount === 1) {
+                // since we have no other connected sessions, we can end discovery immediately
+                await this.#endIntentDiscovery(false);
+                return;
+            }
             // Listen out for discovery results directly sent to us
             await this.#mqttClient.subscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`);
             this.#discoveryTimeout = setTimeout(() => this.#endIntentDiscovery(), clampedTimeout);
@@ -163,10 +182,8 @@ class IntentController {
             throw new CloudInteropAPIError('Error starting intent discovery', 'ERR_STARTING_INTENT_DISCOVERY', error);
         }
     }
-    async #endIntentDiscovery() {
+    async #endIntentDiscovery(mqttUnsubscribe = true) {
         if (this.#discovery.state !== 'in-progress') {
-            // TODO: remove debug logs
-            this.#logger('debug', 'Intent discovery not in progress');
             return;
         }
         if (this.#discoveryTimeout) {
@@ -176,10 +193,12 @@ class IntentController {
         this.#discovery.state = 'ended';
         // emit our aggregated events
         this.#events.emitEvent('aggregate-intent-details', { responses: this.#discovery.pendingIntentDetailsEvents });
-        // gracefully end discovery
-        await this.#mqttClient.unsubscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`).catch(() => {
-            this.#logger('warn', `Error ending intent discovery: could not unsubscribe from discovery id ${this.#discovery.id}`);
-        });
+        if (mqttUnsubscribe) {
+            // gracefully end discovery
+            await this.#mqttClient.unsubscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`).catch(() => {
+                this.#logger('warn', `Error ending intent discovery: could not unsubscribe from discovery id ${this.#discovery.id}`);
+            });
+        }
         await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}/${this.#discovery.id}`, {
             method: 'DELETE',
             headers: getRequestHeaders(this.#connectionParams),
@@ -188,7 +207,6 @@ class IntentController {
             if (!deleteResponse.ok) {
                 throw new Error(`Error ending intent discovery: ${deleteResponse.statusText}`);
             }
-            this.#logger('debug', 'Intent discovery ended');
         })
             .catch((error) => {
             this.#logger('warn', `Error ending intent discovery: ${error}`);
@@ -197,7 +215,7 @@ class IntentController {
         this.#discovery = newDiscovery();
     }
     async raiseIntent({ raiseOptions, appId }) {
-        const targetSessionId = parseSessionId(appId);
+        const targetSessionId = parseCloudAppId(appId).sessionId;
         if (!targetSessionId) {
             // TODO: should we add more info here about the format?
             throw new CloudInteropAPIError(`Invalid AppId specified, must be encoded as a cloud-session app id`, 'ERR_INVALID_TARGET_SESSION_ID');
@@ -232,6 +250,13 @@ class IntentController {
         return false;
     }
     async sendIntentResult(initiatingSessionId, result) {
+        if (!isErrorIntentResult(result)) {
+            // cloud-encode the source app id to support chained intent actions over cloud
+            // https://fdc3.finos.org/docs/2.0/api/spec#resolution-object -> "Use metadata about the resolving app instance to target a further intent"
+            const source = getSourceFromSession(this.#sessionDetails);
+            const encoded = encodeAppId(typeof result.source === 'string' ? result.source : result.source.appId, source);
+            result.source = typeof result.source === 'string' ? encoded : { ...result.source, appId: encoded };
+        }
         const { sessionId } = getSourceFromSession(this.#sessionDetails);
         const resultResponse = await fetch(`${this.#url}/api/intents/${initiatingSessionId}/result/${sessionId}`, {
             method: 'POST',
@@ -309,9 +334,8 @@ const BadUserNamePasswordError = 134;
 /**
  * Represents a single connection to a Cloud Interop service
  *
- * @export
- * @class CloudInteropAPI
- * @implements {Client}
+ * @public
+ * @class
  */
 class CloudInteropAPI {
     #cloudInteropSettings;
@@ -340,7 +364,7 @@ class CloudInteropAPI {
      * Connects and creates a session on the Cloud Interop service
      *
      * @param {ConnectParameters} parameters - The parameters to use to connect
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during connection
      * @throws {AuthorizationError} - If the connection is unauthorized
@@ -452,7 +476,7 @@ class CloudInteropAPI {
     /**
      * Disconnects from the Cloud Interop service
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during disconnection
      */
@@ -464,7 +488,7 @@ class CloudInteropAPI {
      *
      * @param {string} contextGroup - The context group to publish to
      * @param {object} context - The context to publish
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      */
     async setContext(contextGroup, context) {
@@ -491,7 +515,7 @@ class CloudInteropAPI {
     /**
      * Starts an intent discovery operation
      *
-     * @return {*}  {Promise<void>}
+     * @returns {*} {Promise<void>}
      * @memberof CloudInteropAPI
      * @throws {CloudInteropAPIError} - If an error occurs during intent discovery
      */
@@ -512,7 +536,10 @@ class CloudInteropAPI {
         return this.#intents?.sendIntentResult(initiatingSessionId, result);
     }
     parseSessionId(appId) {
-        return parseSessionId(appId);
+        return parseCloudAppId(appId).sessionId;
+    }
+    parseAppId(appId) {
+        return parseCloudAppId(appId).appId;
     }
     addEventListener(type, callback) {
         this.#events.addEventListener(type, callback);
@@ -524,10 +551,13 @@ class CloudInteropAPI {
         this.#events.once(type, callback);
     }
     async #disconnect(fireDisconnectedEvent) {
-        if (!this.#sessionDetails || !this.#connectionParams) {
+        if (!this.#sessionDetails) {
             return;
         }
         try {
+            if (!this.#connectionParams) {
+                throw new Error('Connect parameters must be provided');
+            }
             const disconnectResponse = await fetch(`${this.#cloudInteropSettings.url}/api/sessions/${this.#sessionDetails.sessionId}`, {
                 method: 'DELETE',
                 headers: getRequestHeaders(this.#connectionParams),
@@ -563,8 +593,13 @@ class CloudInteropAPI {
             if (contextEvent.source.sessionId === sessionDetails.sessionId) {
                 return;
             }
-            const { contextGroup, context, source, history } = contextEvent;
-            this.#events.emitEvent('context', { contextGroup, context, source, history: { ...history, clientReceived: Date.now() } });
+            const { context, payload, contextGroup, channelName, source, history } = contextEvent;
+            this.#events.emitEvent('context', {
+                contextGroup: channelName || contextGroup,
+                context: payload || context,
+                source,
+                history: { ...history, clientReceived: Date.now() },
+            });
         }
         else if (topic.startsWith(`${sessionDetails.sessionRootTopic}/commands`)) {
             this.#handleCommandMessage(messageEnvelope);

package/package.json

@@ -1,241 +1,18 @@
 {
-    "name": "@openfin/cloud-interop-core-api",
-    "version": "0.0.1-alpha.6d7b62b",
-    "type": "module",
-    "description": "",
-    "files": [
-        "./dist/*"
-    ],
-    "main": "./dist/index.cjs",
-    "browser": "./dist/index.mjs",
-    "types": "./dist/bundle.d.ts",
-    "scripts": {
-        "build": "rimraf dist && tsx scripts/build.ts",
-        "build:watch": "NODE_ENV=development npx nodemon --watch ./src -e .ts -x \"npm run build || exit 1\"",
-        "typecheck": "tsc --noEmit",
-        "test": "jest --coverage",
-        "lint": "eslint . --max-warnings 0",
-        "lint:fix": "eslint . --fix --max-warnings 0",
-        "pack": "pushd dist && npm pack && popd"
-    },
-    "author": "",
-    "license": "SEE LICENSE IN LICENSE.md",
-    "devDependencies": {
-        "@microsoft/api-extractor": "^7.49.1",
-        "@rollup/plugin-commonjs": "^28.0.1",
-        "@rollup/plugin-inject": "^5.0.5",
-        "@rollup/plugin-node-resolve": "^15.2.3",
-        "@rollup/plugin-typescript": "^11.1.6",
-        "@types/jest": "^29.5.14",
-        "@types/node": "^22.7.7",
-        "@typescript-eslint/eslint-plugin": "^7.5.0",
-        "@typescript-eslint/parser": "^7.15.0",
-        "dotenv-defaults": "^5.0.2",
-        "eslint": "^8.57.0",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint-plugin-check-file": "^2.8.0",
-        "eslint-plugin-prettier": "^5.2.1",
-        "eslint-plugin-simple-import-sort": "^12.1.1",
-        "eslint-plugin-unicorn": "^55.0.0",
-        "eslint-plugin-unused-imports": "^4.1.4",
-        "jest": "^29.7.0",
-        "nodemon": "^3.1.9",
-        "prettier": "^3.3.3",
-        "rollup": "^4.30.1",
-        "ts-jest": "^29.2.5",
-        "tsx": "^4.19.2",
-        "typescript": "^5.7.3"
-    },
-    "optionalDependencies": {
-        "@rollup/rollup-linux-x64-gnu": "*"
-    },
-    "dependencies": {
-        "@openfin/shared-utils": "file:../shared-utils",
-        "mqtt": "^5.3.1",
-        "zod": "^3.24.1"
-    },
-    "eslintConfig": {
-        "env": {
-            "browser": true,
-            "node": true
-        },
-        "parser": "@typescript-eslint/parser",
-        "parserOptions": {
-            "ecmaVersion": "latest",
-            "project": true,
-            "sourceType": "module"
-        },
-        "extends": [
-            "eslint:recommended",
-            "plugin:@typescript-eslint/recommended",
-            "plugin:@typescript-eslint/strict",
-            "plugin:unicorn/recommended",
-            "plugin:prettier/recommended"
-        ],
-        "plugins": [
-            "prettier",
-            "check-file",
-            "simple-import-sort",
-            "unused-imports"
-        ],
-        "rules": {
-            "unused-imports/no-unused-imports": "warn",
-            "unicorn/prevent-abbreviations": [
-                "error",
-                {
-                    "replacements": {
-                        "props": false,
-                        "prop": false,
-                        "ref": false,
-                        "args": false,
-                        "arg": false,
-                        "src": false,
-                        "dev": false,
-                        "str": false,
-                        "req": false,
-                        "res": false
-                    }
-                }
-            ],
-            "@typescript-eslint/no-non-null-assertion": "error",
-            "unicorn/no-nested-ternary": "off",
-            "unicorn/no-array-for-each": "off",
-            "unicorn/no-useless-undefined": "off",
-            "unicorn/no-null": "off",
-            "eqeqeq": [
-                "error",
-                "always"
-            ],
-            "no-alert": "error",
-            "no-eval": "error",
-            "prettier/prettier": "warn",
-            "simple-import-sort/imports": [
-                "error",
-                {
-                    "groups": [
-                        [
-                            "^react$"
-                        ],
-                        [
-                            "^react"
-                        ],
-                        [
-                            "^next"
-                        ],
-                        [
-                            "^zod"
-                        ],
-                        [
-                            "^@radix-ui/"
-                        ],
-                        [
-                            "^[^.]"
-                        ],
-                        [
-                            "@/components/ui/.*"
-                        ],
-                        [
-                            "@/components/.*"
-                        ],
-                        [
-                            "@/config/.*"
-                        ],
-                        [
-                            "@/lib/.*"
-                        ],
-                        [
-                            "^\\.\\.(?!/?$)",
-                            "^\\.\\./?$"
-                        ],
-                        [
-                            "^\\./(?=.*/)(?!/?$)",
-                            "^\\.(?!/?$)",
-                            "^\\./?$"
-                        ],
-                        [
-                            "^.+\\.s?css$"
-                        ]
-                    ]
-                }
-            ],
-            "check-file/no-index": "off",
-            "check-file/filename-naming-convention": [
-                "error",
-                {
-                    "**/*.{jsx,tsx}": "KEBAB_CASE",
-                    "**/*.{js,ts}": "KEBAB_CASE"
-                },
-                {
-                    "ignoreMiddleExtensions": true
-                }
-            ],
-            "check-file/filename-blocklist": [
-                "error",
-                {
-                    "**/*.spec.js": "*.test.js",
-                    "**/*.spec.jsx": "*.test.jsx",
-                    "**/*.spec.ts": "*.test.ts",
-                    "**/*.spec.tsx": "*.test.tsx"
-                }
-            ],
-            "no-restricted-syntax": [
-                "error",
-                {
-                    "selector": "TSEnumDeclaration",
-                    "message": "Prefer string unions to enums."
-                }
-            ],
-            "curly": [
-                "error",
-                "multi-line"
-            ],
-            "@typescript-eslint/consistent-type-definitions": [
-                "error",
-                "type"
-            ],
-            "@typescript-eslint/no-unused-vars": [
-                "warn",
-                {
-                    "argsIgnorePattern": "^_",
-                    "varsIgnorePattern": "^_"
-                }
-            ],
-            "@typescript-eslint/no-explicit-any": "warn"
-        },
-        "ignorePatterns": [
-            "node_modules",
-            "out",
-            "build",
-            "scripts",
-            "dist",
-            "coverage",
-            "tests",
-            "rollup.config.mjs",
-            "examples"
-        ]
-    },
-    "jest": {
-        "collectCoverage": true,
-        "collectCoverageFrom": [
-            "src/**/*.ts"
-        ],
-        "coverageReporters": [
-            "lcov",
-            "text-summary"
-        ],
-        "preset": "ts-jest",
-        "restoreMocks": true,
-        "setupFiles": [],
-        "testMatch": [
-            "**/tests/*.test.ts"
-        ],
-        "testTimeout": 100000
-    },
-    "prettier": {
-        "printWidth": 160,
-        "semi": true,
-        "singleQuote": true,
-        "tabWidth": 4,
-        "trailingComma": "all"
-    }
+  "name": "@openfin/cloud-interop-core-api",
+  "version": "0.0.1-alpha.6da3439",
+  "type": "module",
+  "description": "",
+  "main": "./index.cjs",
+  "browser": "./index.mjs",
+  "types": "./bundle.d.ts",
+  "author": "",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "optionalDependencies": {
+    "@rollup/rollup-linux-x64-gnu": "*"
+  },
+  "dependencies": {
+    "mqtt": "^5.3.1",
+    "zod": "^3.24.2"
+  }
 }

package/dist/LICENSE.md

@@ -1,4 +0,0 @@
-Learn more about OpenFin licensing at the links listed below or email us at support@openfin.co with questions.
-
-- [Developer agreement](https://openfin.co/developer-agreement)
-

package/dist/README.md

@@ -1,14 +0,0 @@
-# @openfin/cloud-interop-core-api
-
-This package contains the core interop library that handles all interactions with the Here™ Cloud Interop Service.
-
-It is callable via browser or node applications.
-
-
-## Authentication
-
-The library supports authentication with the Here™ Cloud Interop Service using the following methods:
- - Basic Authentication
- - JWT Token Authentication
- - Default Authentication i.e. Interactive session based authentication using cookies
-

package/dist/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "@openfin/cloud-interop-core-api",
-  "version": "0.0.1-alpha",
-  "type": "module",
-  "description": "",
-  "main": "./index.cjs",
-  "browser": "./index.mjs",
-  "types": "./bundle.d.ts",
-  "author": "",
-  "license": "SEE LICENSE IN LICENSE.md",
-  "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "*"
-  },
-  "dependencies": {
-    "mqtt": "^5.3.1",
-    "zod": "^3.24.1"
-  }
-}