@finsemble/finsemble-ui 8.2.1 → 8.3.0-beta.1

package/clients/Interop/FinsembleDesktopAgent.js

@@ -9,16 +9,29 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _HeartbeatMonitor_declareDead, _HeartbeatMonitor_timeoutHandle, _HeartbeatMonitor_disconnectHandlers, _ChannelProxy_desktopAgent, _FinsembleDesktopAgent_connected, _FinsembleDesktopAgent_heartbeatMonitor, _FinsembleDesktopAgent_startHasBeenCalled, _FinsembleDesktopAgent_uuid, _FinsembleDesktopAgent_clientChannel, _FinsembleDesktopAgent_intentHandlers, _FinsembleDesktopAgent_contextHandlers, _FinsembleDesktopAgent_queue, _FinsembleDesktopAgent_routerClient, _FinsembleDesktopAgent_startup, _FinsembleDesktopAgent_FSBLVersion;
+var _HeartbeatMonitor_declareDead, _HeartbeatMonitor_timeoutHandle, _HeartbeatMonitor_disconnectHandlers, _ChannelProxy_desktopAgent, _FinsembleDesktopAgent_connected, _FinsembleDesktopAgent_heartbeatMonitor, _FinsembleDesktopAgent_startHasBeenCalled, _FinsembleDesktopAgent_uuid, _FinsembleDesktopAgent_clientChannel, _FinsembleDesktopAgent_intentHandlers, _FinsembleDesktopAgent_contextHandlers, _FinsembleDesktopAgent_privateChannelSubscription, _FinsembleDesktopAgent_intentResultPromiseMap, _FinsembleDesktopAgent_intentResultPromiseResolveMap, _FinsembleDesktopAgent_queue, _FinsembleDesktopAgent_routerClient, _FinsembleDesktopAgent_startup, _FinsembleDesktopAgent_existingChannelProxy;
+/**
+ * Regarding 1.2 compatibility. FDC3 1.2 defined some functions as synchronous which are now asynchronous. To provide
+ * backward compatibility for these functions, we return a Promise which has additional members attached (usually an
+ * unsubscribe function). Apps using either 1.2 or 2.0 will receive an interface that is a superset of what they expect.
+ *
+ * The resulting code is complex. It should be aggressively removed when FDC3 1.2 is retired, back to simple async functions
+ * that return Promise<Listener>.
+ *
+ * For Typescript support, 1.2 apps can simply install the 1.2 version of the "@finos/fdc3" npm module
+ */
 import uuidv4 from "uuid-random";
-import { OpenError, ResolveError, } from "@finos/fdc3";
+import { OpenError, ResolveError, ResultError, ChannelError, } from "@finos/fdc3";
 import Logger from "../logger";
 import ConfigClient from "../configClient";
 import SystemManagerClient from "../../common/systemManagerClient";
 import { Globals } from "../../common/Globals";
 import { SERVER_CHANNEL } from "./types";
 import { mmAdd, mmRemove, errorAsString, } from "./types";
-const Uninitialized = "";
+// Timeout value for logging warning when intent response is delayed.
+const WaitForIntentResultTimeout = 5000;
+const PrivateChannelIdPrefix = "Private-Channel-Id";
+const isPrivateChannelId = (channelId) => channelId.includes(PrivateChannelIdPrefix);
 /**
  * Heartbeats are used by the InteropService to detect dead fdc3 client connections. A connection
  * can die if a window crashes or is terminated. Heartbeats are also currently the only way to detect
@@ -64,6 +77,8 @@ class HeartbeatMonitor {
 _HeartbeatMonitor_declareDead = new WeakMap(), _HeartbeatMonitor_timeoutHandle = new WeakMap(), _HeartbeatMonitor_disconnectHandlers = new WeakMap();
 /**
  * Implements FDC3's Channel interface. All actual transmissions still occur through the desktop agent via private functions.
+ *
+ * First pass the ChannelProxy implements PrivateChannel, which is a superset of Channel -- may refine this in second pass.
  */
 class ChannelProxy {
     constructor(desktopAgent, id, type = "app") {
@@ -81,11 +96,11 @@ class ChannelProxy {
      *
      * `Error` with a string from the `ChannelError` enumeration.
      */
-    broadcast(context) {
+    async broadcast(context) {
         if (!context) {
             throw new Error("Invalid arguments. The required context parameter is missing.");
         }
-        __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelBroadcast(this.id, context);
+        await __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelBroadcast(this.id, context);
     }
     /**
      * Returns the last context that was broadcast on this channel. All channels initially have no context, until a
@@ -108,6 +123,7 @@ class ChannelProxy {
     /**
      * Adds a listener for incoming contexts whenever a broadcast happens on this channel.
      */
+    // @ts-ignore <---------------------------------------------------------------------------------------------------------------------
     addContextListener(contextTypeOrHandler, handler) {
         if (contextTypeOrHandler === undefined) {
             throw new Error("Invalid arguments. The contextTypeOrHandler parameter shouldn't be undefined.");
@@ -115,7 +131,60 @@ class ChannelProxy {
         if (typeof contextTypeOrHandler !== "function" && !handler) {
             throw new Error("Invalid arguments. The required handler parameter is missing.");
         }
-        return __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelAddContextListener(this.id, contextTypeOrHandler, handler);
+        // Dangerous code: See note at top of file about 1.2 compatibility
+        const { exchangePromise, unsubscribe } = __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelAddContextListener(this.id, contextTypeOrHandler, handler);
+        let promise = new Promise((resolve) => {
+            exchangePromise.then(() => {
+                resolve({
+                    unsubscribe,
+                });
+            });
+        });
+        promise.unsubscribe = () => {
+            Logger.system.deprecated("Use of the synchronous version of addContextListener from FDC3 1.2 is deprecated. Please switch to `await addContextListener`.");
+            unsubscribe();
+        };
+        return promise;
+    }
+    /**
+     * Adds a listener that will be called each time that the remote app invokes
+     * addContextListener on this channel.
+     *
+     * Desktop Agents MUST call this for each invocation of addContextListener on this
+     * channel, including those that occurred before this handler was registered
+     * (to prevent race conditions).
+     */
+    onAddContextListener(handler) {
+        return __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelOnAddContextListener(this.id, handler);
+    }
+    /**
+     * Adds a listener that will be called whenever the remote app invokes
+     * Listener.unsubscribe() on a context listener that it previously added.
+     *
+     * Desktop Agents MUST call this when disconnect() is called by the other party, for
+     * each listener that they had added.
+     */
+    onUnsubscribe(handler) {
+        return __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelOnUnsubscribe(this.id, handler);
+    }
+    /**
+     * Adds a listener that will be called when the remote app terminates, for example
+     * when its window is closed or because disconnect was called. This is in addition
+     * to calls that will be made to onUnsubscribe listeners.
+     */
+    onDisconnect(handler) {
+        return __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelOnDisconnect(this.id, handler);
+    }
+    /**
+     * May be called to indicate that a participant will no longer interact with this channel.
+     *
+     * After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting
+     * on this channel and MUST automatically call Listener.unsubscribe() for each listener that
+     * they've added (causing any onUnsubscribe handler added by the other party to be called)
+     * before triggering any onDisconnect handler added by the other party.
+     */
+    disconnect() {
+        return __classPrivateFieldGet(this, _ChannelProxy_desktopAgent, "f").channelDisconnect(this.id);
     }
 }
 _ChannelProxy_desktopAgent = new WeakMap();
@@ -128,21 +197,22 @@ export class FinsembleDesktopAgent {
         _FinsembleDesktopAgent_heartbeatMonitor.set(this, new HeartbeatMonitor());
         // A lock that prevents start() from running multiple times
         _FinsembleDesktopAgent_startHasBeenCalled.set(this, false);
-        // uuid is set in connect(), when startup.onReady
-        _FinsembleDesktopAgent_uuid.set(this, "");
+        _FinsembleDesktopAgent_uuid.set(this, "undefined");
         _FinsembleDesktopAgent_clientChannel.set(this, `FSBL.FDC3.Client.${uuidv4()}`);
         _FinsembleDesktopAgent_intentHandlers.set(this, {});
         _FinsembleDesktopAgent_contextHandlers.set(this, {});
+        _FinsembleDesktopAgent_privateChannelSubscription.set(this, {});
+        _FinsembleDesktopAgent_intentResultPromiseMap.set(this, {});
+        _FinsembleDesktopAgent_intentResultPromiseResolveMap.set(this, {});
         // Stores fdc3 calls that are received before a connection is established with the interop service
         // Once a connection is established then the queue is released.
         _FinsembleDesktopAgent_queue.set(this, []);
         _FinsembleDesktopAgent_routerClient.set(this, void 0);
         _FinsembleDesktopAgent_startup.set(this, void 0);
-        _FinsembleDesktopAgent_FSBLVersion.set(this, Uninitialized);
+        _FinsembleDesktopAgent_existingChannelProxy.set(this, {});
         __classPrivateFieldSet(this, _FinsembleDesktopAgent_routerClient, routerClient, "f");
         __classPrivateFieldSet(this, _FinsembleDesktopAgent_startup, startup, "f");
-        this.cacheFSBLVersion();
-        // Per 1.2 spec, dispatch this event as soon as the global fdc3 object exists and is ready to accept API calls.
+        // Per spec, dispatch this event as soon as the global fdc3 object exists and is ready to accept API calls.
         // We should not wait until start() because in some circumstances, start() is not called *until* an API call is made.
         // Skip this if the global Event class is undefined (if running in Node.js such as a unit test). Note: also needed to confirm window.dispatchEvent was available, perhaps because of latest Node version.
         if (Globals.Event && Globals.dispatchEvent) {
@@ -150,21 +220,21 @@ export class FinsembleDesktopAgent {
             Globals.dispatchEvent(event);
         }
     }
-    // Cache FSBL version for use by fdc3.getInfo.
-    async cacheFSBLVersion() {
-        // Since setFSBLVersion is async, there is a timing gap until FDC3 2.0 supports async getInfo(). However, the default for #FSBLVersion covers the gap for now.
-        // It's possible to close this gap now by not dispatching "fdc3Ready" until FSBLVersion is set, but doing that properly requires a change to the fdc3 preload and
-        // then breaks existing apps that don't wait as defined in 1.2 spec.
-        if (__classPrivateFieldGet(this, _FinsembleDesktopAgent_FSBLVersion, "f") == Uninitialized) {
-            __classPrivateFieldSet(this, _FinsembleDesktopAgent_FSBLVersion, "8.1.0", "f");
-        }
-        const { err, data: FSBLVersion } = await ConfigClient.getValue({ field: "finsemble.system.FSBLVersion" });
-        if (!err) {
-            __classPrivateFieldSet(this, _FinsembleDesktopAgent_FSBLVersion, FSBLVersion, "f");
-        }
+    privateChannelId() {
+        return `${PrivateChannelIdPrefix}-${uuidv4()}`;
     }
-    fdc3Error(msg) {
-        return new Error(msg);
+    // This wrapper around startup data is necessary to syncronize access to it since it might not have the correct data until startup.onReady() fires.
+    async fetchStartupData() {
+        await __classPrivateFieldGet(this, _FinsembleDesktopAgent_startup, "f").onReady();
+        const startupData = __classPrivateFieldGet(this, _FinsembleDesktopAgent_startup, "f").getStartupData();
+        const { authenticationToken, windowName } = startupData;
+        // The uuid has the appId encoded for diagnostics, but appId is not available until startup data is ready; therefore must set uuid here the first time this function is called
+        if (__classPrivateFieldGet(this, _FinsembleDesktopAgent_uuid, "f") === "undefined") {
+            __classPrivateFieldSet(this, _FinsembleDesktopAgent_uuid, `fdc3-instanceId-${authenticationToken.meta.appId}=${uuidv4()}`, "f");
+        }
+        const appMetadata = Object.assign(Object.assign({}, authenticationToken.meta), { instanceId: __classPrivateFieldGet(this, _FinsembleDesktopAgent_uuid, "f") });
+        Logger.system.debug(`fetchStartupData`, startupData, windowName, authenticationToken, appMetadata);
+        return { windowName, authenticationToken, appMetadata };
     }
     meta() {
         return {
@@ -217,12 +287,118 @@ export class FinsembleDesktopAgent {
             }
         });
     }
-    triggerIntentListeners(message) {
-        const { intent, context } = message.payload;
-        const handlers = __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent];
-        const functionArray = handlers ? handlers : [];
-        if (context)
-            functionArray.forEach((func) => func(context));
+    // See https://fdc3.finos.org/docs/api/ref/DesktopAgent#examples-1 for supported examples of intents with various return characteristics
+    async triggerIntentListener(message) {
+        const { intent, context, requestId } = message.payload;
+        const handler = __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent];
+        let intentResultError;
+        let result = null;
+        let localIntentResult = undefined;
+        if (typeof handler === "function") {
+            // Set timer to issue warning if handler doesn't return in expect time period (but don't fail since handler could be interacting with user and therefore be very slow)
+            let intentResultTimer = setInterval(() => {
+                Logger.system.warn(`tag:FDC3:raiseIntent No intent result has been returned yet for intent ${intent} -- will continue to wait`, message.payload);
+                intentResultTimer = null;
+            }, WaitForIntentResultTimeout);
+            Logger.system.log(`tag:FDC3:raiseIntent triggering intent listener for intent ${intent}`, message.payload);
+            try {
+                // Wait for the intent handler to return a result
+                localIntentResult = await handler(context);
+                Logger.system.log(`tag:FDC3:raiseIntent handler response for intent ${intent}`, localIntentResult);
+            }
+            catch (err) {
+                Logger.system.error(`tag:FDC3:raiseIntent -- error thrown in handler for intent ${intent}`, context, message.payload);
+                intentResultError = ResultError.IntentHandlerRejected;
+                result = {
+                    type: "intentResult",
+                    meta: this.meta(),
+                    payload: {
+                        intentResultError,
+                        intent,
+                        requestId,
+                    },
+                };
+                this.exchange(result);
+            }
+            // If no error was thrown above when the intent handler was invoked, then return the handler result
+            if (!intentResultError) {
+                clearInterval(intentResultTimer);
+                // convert IntentResult to InteropIntentResult, a form than can be transmitted to InteropService
+                // `?addContextListener` is how we dynamically tell whether the user returned a Channel
+                const intentResult = (localIntentResult === null || localIntentResult === void 0 ? void 0 : localIntentResult.addContextListener)
+                    ? { channelId: localIntentResult === null || localIntentResult === void 0 ? void 0 : localIntentResult.id, channelType: localIntentResult.type }
+                    : localIntentResult;
+                // If intentResult isn't void, then ensure it appears to be either a channel or context
+                if (intentResult && typeof intentResult !== "object") {
+                    Logger.system.error(`IntentResult returned by FDC3 client app for intent ${intent} is rejected since it doesn't match expected channel or context definition`, intentResult);
+                    intentResultError = ResultError.IntentHandlerRejected;
+                }
+                else if (!intentResult) {
+                    intentResultError = ResultError.NoResultReturned;
+                }
+                result = {
+                    type: "intentResult",
+                    meta: this.meta(),
+                    payload: {
+                        intentResult,
+                        intentResultError,
+                        intent,
+                        requestId,
+                    },
+                };
+                this.exchange(result);
+            }
+        }
+        else {
+            Logger.system.error(`Legal listener not found for intent ${intent}`);
+            result = {
+                type: "intentResult",
+                meta: this.meta(),
+                payload: {
+                    intentResultError: ResultError.IntentHandlerRejected,
+                    intent,
+                    requestId,
+                },
+            };
+            this.exchange(result);
+        }
+        Logger.system.log(`tag:FDC3:raiseIntent handler response for intent ${intent}`, result);
+    }
+    async handlePrivateChannelEvent(message) {
+        const { channel, context, targetSubscriberId } = message.payload;
+        const channelSubscriptions = __classPrivateFieldGet(this, _FinsembleDesktopAgent_privateChannelSubscription, "f")[channel];
+        const targetSubscription = channelSubscriptions.find((s) => s.targetSubscriberId === targetSubscriberId);
+        if (targetSubscription) {
+            switch (targetSubscription.subscribeType) {
+                case "onAddContextListener":
+                    targetSubscription.handler(context);
+                    break;
+                case "onUnsubscribe":
+                    targetSubscription.handler(context);
+                    break;
+                case "onDisconnect":
+                    targetSubscription.handler();
+                    break;
+                default: {
+                    Logger.system.error("FDC3 Client: unknown subscribeType in matching targetSubscription", targetSubscription);
+                }
+            }
+        }
+        else {
+            Logger.system.error("FDC3 Client: could not find target subscription", targetSubscriberId, channelSubscriptions);
+        }
+    }
+    async handleIntentResult(message) {
+        const { intent: intentName, intentResult, requestId, intentResultError } = message.payload;
+        // If there is an outstanding resolve function associated with the request id, then invoke it
+        if (typeof __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseResolveMap, "f")[requestId] === "function") {
+            Logger.system.log(`tag:FDC3:raiseIntent result message received for intent ${intentName}`, message);
+            // Resolve the outstanding promise, waited on in the corresponding getResult function, returning the intent result or an error
+            __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseResolveMap, "f")[requestId]({ errorResult: intentResultError, intentResult });
+        }
+        else {
+            Logger.system.error(`Legal internal handler for intent result not found`, message, __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseResolveMap, "f"));
+        }
     }
     handleIncoming(message) {
         Logger.system.debug("FDC3 Client: handleIncoming", message.type, message);
@@ -231,7 +407,13 @@ export class FinsembleDesktopAgent {
                 this.triggerContextListeners(message);
                 break;
             case "intent":
-                this.triggerIntentListeners(message);
+                this.triggerIntentListener(message);
+                break;
+            case "privateChannelEvent":
+                this.handlePrivateChannelEvent(message);
+                break;
+            case "intentResult":
+                this.handleIntentResult(message);
                 break;
             case "heartbeat":
                 this.handleHeartbeat();
@@ -258,6 +440,7 @@ export class FinsembleDesktopAgent {
             return message;
         };
         __classPrivateFieldGet(this, _FinsembleDesktopAgent_queue, "f").forEach(async (entry) => {
+            Logger.system.log(`fdc3.releaseQueue`, entry);
             const { message, handler, resolve } = entry;
             const { err, receiveMessage } = await this.exchange(updateUUID(message), handler);
             resolve({ err, receiveMessage });
@@ -287,7 +470,6 @@ export class FinsembleDesktopAgent {
      * @internal
      */
     async connect() {
-        var _a;
         /**
          * StartupData contains the AuthenticationToken necessary to connect to the interop service. When an app
          * is spawned by Finsemble, the AuthenticationToken is automatically created by the launcher. When an app
@@ -295,10 +477,8 @@ export class FinsembleDesktopAgent {
          * digital signing key. If an app can't be authenticated then Startup ensures that an anonymous
          * AuthenticationToken exists (type "unauthenticated").
          */
-        const startupData = __classPrivateFieldGet(this, _FinsembleDesktopAgent_startup, "f").getStartupData();
-        const { windowName = "Unknown window", authenticationToken } = startupData;
-        Logger.system.log(`fdc3.connect StartupData for ${windowName}`, startupData);
-        __classPrivateFieldSet(this, _FinsembleDesktopAgent_uuid, `fdc3-${(_a = authenticationToken === null || authenticationToken === void 0 ? void 0 : authenticationToken.meta) === null || _a === void 0 ? void 0 : _a.name}-${uuidv4()}`, "f");
+        const { windowName, authenticationToken } = await this.fetchStartupData();
+        Logger.system.log(`fdc3.connect StartupData for ${windowName}`);
         const registerClient = {
             type: "register",
             meta: this.meta(),
@@ -421,7 +601,7 @@ export class FinsembleDesktopAgent {
      * Apps can still directly broadcast and listen to context on any channel via the methods on the Channel class.
      * @param context
      */
-    broadcast(context) {
+    async broadcast(context) {
         if (!context) {
             throw new Error("Invalid arguments. The required context parameter is missing.");
         }
@@ -432,10 +612,10 @@ export class FinsembleDesktopAgent {
                 context,
             },
         };
-        this.exchange(message);
+        await this.exchange(message);
     }
     /** @internal */
-    channelBroadcast(channel, context) {
+    async channelBroadcast(channel, context) {
         const message = {
             type: "broadcast",
             meta: Object.assign(Object.assign({}, this.meta()), { channel }),
@@ -443,13 +623,13 @@ export class FinsembleDesktopAgent {
                 context,
             },
         };
-        this.exchange(message);
+        await this.exchange(message);
     }
     /**
      * Retrieves a list of the System channels available for the app to join.
      * This should include the 'global' channel.
      */
-    async getSystemChannels() {
+    async getUserChannels() {
         var _a;
         const message = {
             type: "systemChannelRequest",
@@ -459,37 +639,37 @@ export class FinsembleDesktopAgent {
         if (err)
             return [];
         const channelNames = (receiveMessage === null || receiveMessage === void 0 ? void 0 : receiveMessage.type) === "systemChannels" ? (_a = receiveMessage === null || receiveMessage === void 0 ? void 0 : receiveMessage.payload) === null || _a === void 0 ? void 0 : _a.channels : [];
-        return channelNames.map((name) => new ChannelProxy(this, name, "system"));
+        return channelNames.map((name) => new ChannelProxy(this, name, "user"));
     }
     /**
-     * Launches/links to an app by name.
-     * If a Context object is passed in, this object will be provided to the opened application via a contextListener.
-     * The Context argument is functionally equivalent to opening the target app with no context and broadcasting the context directly to it.
-     * If opening errors, it returns an Error with a string from the OpenError enumeration.
-     *
-     * @param target
-     * @param context
+     * For backwards compatability.  Retrieves a list of the System channels available for the app to join.
      */
-    async open(target, context) {
-        if (!target) {
-            throw new Error("Invalid arguments. The required target parameter is missing.");
+    async getSystemChannels() {
+        return this.getUserChannels();
+    }
+    async open(app, context) {
+        if (!app) {
+            throw new Error("Invalid arguments. The required 'app' parameter is missing.");
         }
+        const { appMetadata } = await this.fetchStartupData();
         const message = {
             type: "open",
             meta: this.meta(),
             payload: {
-                target,
+                requestingAppId: appMetadata.appId,
+                app,
                 context,
             },
         };
         const { err, receiveMessage } = await this.exchange(message);
         const interopOpenResponse = receiveMessage;
         if (err) {
-            throw this.fdc3Error(OpenError.ResolverUnavailable);
+            throw new Error(OpenError.ResolverUnavailable);
         }
         else if (interopOpenResponse.payload.error) {
-            throw this.fdc3Error(interopOpenResponse.payload.error);
+            throw new Error(interopOpenResponse.payload.error);
         }
+        return interopOpenResponse.payload.appIdentifier;
     }
     /**
      * Find out more information about a particular intent by passing its name, and optionally its context.
@@ -503,28 +683,35 @@ export class FinsembleDesktopAgent {
      * @param intent
      * @param context
      */
-    async findIntent(intent, context) {
+    async findIntent(intent, context, resultType) {
         if (!intent) {
             throw new Error("Invalid arguments. The required intent parameter is missing.");
         }
+        if (context && !context.type) {
+            throw new Error("Invalid arguments. Second parameter must be a valid context.");
+        }
+        if (resultType && typeof resultType !== "string") {
+            throw new Error("Invalid arguments. Third parameter must be a string.");
+        }
         const message = {
             type: "findIntent",
             meta: this.meta(),
             payload: {
                 intent,
                 context,
+                resultType,
             },
         };
         const { err, receiveMessage } = await this.exchange(message);
         const interopFindIntentResponse = receiveMessage;
         if (err) {
-            throw this.fdc3Error(ResolveError.ResolverUnavailable);
+            throw new Error(ResolveError.ResolverUnavailable);
         }
         else if (interopFindIntentResponse.payload.error) {
-            throw this.fdc3Error(interopFindIntentResponse.payload.error);
+            throw new Error(interopFindIntentResponse.payload.error);
         }
         else if (!interopFindIntentResponse.payload.appIntent) {
-            throw this.fdc3Error("Invalid response returned from InteropService for findIntent. No appIntent and no error.");
+            throw new Error("Invalid response returned from InteropService for findIntent. No appIntent and no error.");
         }
         return interopFindIntentResponse.payload.appIntent;
     }
@@ -538,10 +725,16 @@ export class FinsembleDesktopAgent {
      * If the resolution fails, the promise will return an `Error` with a string from the `ResolveError` enumeration.
      * @param context
      */
-    async findIntentsByContext(context) {
+    async findIntentsByContext(context, resultType) {
         if (!context) {
             throw new Error("Invalid arguments. The required context parameter is missing.");
         }
+        if (!context.type) {
+            throw new Error("Invalid arguments. Second parameter must be a valid context.");
+        }
+        if (resultType && typeof resultType !== "string") {
+            throw new Error("Invalid arguments. Second parameter must be a string to identify result type.");
+        }
         // The context parameter was made optional to support a query for all intents. This is consistent with findIntent, however it is not consistent with FDC3 spec plus.
         // a mechanism is still needed to query for contexts. A better solution is to add two new InteropAdmin methods; e.g. getIntents() and getContexts().
         const message = {
@@ -549,28 +742,33 @@ export class FinsembleDesktopAgent {
             meta: this.meta(),
             payload: {
                 context,
+                resultType,
             },
         };
         const { receiveMessage } = await this.exchange(message);
         const interopIntentsList = receiveMessage;
         if (interopIntentsList.payload.error) {
-            throw this.fdc3Error(interopIntentsList.payload.error);
+            throw new Error(interopIntentsList.payload.error);
         }
         return interopIntentsList.payload.intents || [];
     }
+    // @ts-ignore <----------------------------------------------------------------------------------------------------------------------------------------------
+    async createPrivateChannel() {
+        return new ChannelProxy(this, this.privateChannelId(), "private");
+    }
     /**
-     * Raises an intent to the desktop agent to resolve.
+     * Common implementation for raiseIntent() and raiseIntentForContext().
+     *
      * @param intent
      * @param context
      * @param target
      */
-    async raiseIntent(intent, context, target) {
-        if (!intent) {
-            throw new Error("Invalid arguments. The required intent parameter is missing.");
-        }
-        if (!context) {
-            throw new Error("Invalid arguments. The required context parameter is missing.");
+    async raiseIntentInternal(intent, context, target) {
+        if (context && !context.type) {
+            throw new Error("Invalid arguments. Second parameter must be a valid context.");
         }
+        const requestId = `raise-intent-request-Id-${uuidv4()}`;
+        Logger.system.log(`tag:FDC3:raiseIntent initiated for intent ${intent} with ${context ? " context type " : "no context"}${context === null || context === void 0 ? void 0 : context.type}`, context, target, requestId);
         const message = {
             type: "raiseIntent",
             meta: this.meta(),
@@ -578,67 +776,102 @@ export class FinsembleDesktopAgent {
                 intent,
                 context,
                 target,
+                requestId,
             },
         };
+        Logger.system.log(`tag:FDC3:raiseIntent request sent to InteropService for intent ${intent}`, message);
+        // The message received back from the InteropService for the below exchange(message) corresponds to the IntentResolution (signaling the raiseIntent has been successfully sent to the target app, or an error).
+        // Asynchronously, an IntentResult will come in later.
         const { err, receiveMessage } = await this.exchange(message);
         const interopIntentResolution = receiveMessage;
+        Logger.system.log(`tag:FDC3:raiseIntent intent resolution received for intent ${intent}`, err, receiveMessage);
         if (err) {
-            throw this.fdc3Error(ResolveError.ResolverUnavailable);
+            throw new Error(ResolveError.ResolverUnavailable);
         }
         else if (interopIntentResolution.payload.error) {
-            throw this.fdc3Error(interopIntentResolution.payload.error);
+            throw new Error(interopIntentResolution.payload.error);
         }
         else if (!interopIntentResolution.payload.data) {
-            throw this.fdc3Error("Invalid response returned from InteropService for raiseIntent. No data.");
+            throw new Error("Invalid response returned from InteropService for raiseIntent. No data.");
         }
-        return interopIntentResolution.payload.data;
+        /* Allocate a promise for this raiseIntent and map it to the request id to handle the getResult() syncronization.
+
+           This promise is waited on below in the getResult function returned in the raiseIntent response,
+           then resolved in handleIntentResult when the result arrives for the requestId
+         */
+        __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseMap, "f")[requestId] = new Promise((intentResultResolve) => {
+            // Map the resolve function to the requestID to be later invoked to complete this promise when the intent result arrives.
+            __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseResolveMap, "f")[requestId] = intentResultResolve;
+        });
+        const intentResolution = {
+            source: interopIntentResolution.payload.data.source,
+            intent: interopIntentResolution.payload.data.intent,
+            version: interopIntentResolution.payload.data.version,
+            getResult: async () => {
+                let errorResult;
+                let intentResult;
+                Logger.system.log(`tag:FDC3:raiseIntent getResult initiated for intent ${intent}`, message);
+                if (typeof __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseResolveMap, "f")[requestId] === "function") {
+                    // Wait for the corresponding intent result to be returned.
+                    // The promise waited on here is resolved in handleIntentResult when the result with the correct requestId arrives from InteropService.
+                    ({ errorResult, intentResult } = await __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentResultPromiseMap, "f")[requestId]);
+                }
+                else {
+                    errorResult = "could not fulfill intent resolution due to no corresponding result promise";
+                }
+                // Any error has to be thrown here in this original thread of control for the app to receive it -- it cannot be thrown when the result is processed in handleIntentResult
+                if (errorResult) {
+                    throw new Error(errorResult);
+                }
+                else if (!intentResult) {
+                    throw new Error(ResultError.NoResultReturned);
+                }
+                const { channelId, channelType } = intentResult;
+                const fdc3IntentResult = channelId
+                    ? new ChannelProxy(this, channelId, channelType)
+                    : intentResult;
+                Logger.system.log(`tag:FDC3:raiseIntent result returned for intent ${intent}`, fdc3IntentResult);
+                return fdc3IntentResult;
+            },
+        };
+        return intentResolution;
     }
-    /**
-     * Finds and raises an intent against a target app based purely on context data.
-     *
-     * raiseIntentForContext is essentially a raiseIntent without a specific intent specified, hence the same "raiseIntent" Interop message is used.
-     *
-     * @param context
-     * @param target
-     */
-    async raiseIntentForContext(context, target) {
+    async raiseIntent(intent, context, target) {
+        if (!intent) {
+            throw new Error("Invalid arguments. The required intent parameter is missing.");
+        }
         if (!context) {
             throw new Error("Invalid arguments. The required context parameter is missing.");
         }
-        const message = {
-            type: "raiseIntent",
-            meta: this.meta(),
-            payload: {
-                context,
-                target,
-            },
-        };
-        const { err, receiveMessage } = await this.exchange(message);
-        const interopRaiseIntentResponse = receiveMessage;
-        if (err) {
-            throw this.fdc3Error(ResolveError.ResolverUnavailable);
-        }
-        else if (interopRaiseIntentResponse.payload.error) {
-            throw this.fdc3Error(interopRaiseIntentResponse.payload.error);
+        if (!context.type) {
+            throw new Error("Invalid arguments. Second parameter must be a valid context.");
         }
-        else if (!interopRaiseIntentResponse.payload.data) {
-            throw this.fdc3Error("Invalid response returned from InteropService for raiseIntentForContext. No data.");
+        return this.raiseIntentInternal(intent, context, target);
+    }
+    async raiseIntentForContext(context, target) {
+        if (!context) {
+            throw new Error("Invalid arguments. The required context parameter is missing.");
         }
-        return interopRaiseIntentResponse.payload.data;
+        return this.raiseIntentInternal(null, context, target);
     }
     /**
-     * Adds a listener for incoming Intents from the Agent.
+     * Adds a listener for incoming Intents from the Agent.  Unlike addContextListener, there can only be one listener for an intent.
      * @param intent
      * @param handler
      */
     addIntentListener(intent, handler) {
-        if (!handler) {
+        if (!intent) {
             throw new Error("Invalid arguments. The required intent parameter is missing.");
         }
         if (!handler) {
             throw new Error("Invalid arguments. The required handler parameter is missing.");
         }
-        __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent] = mmAdd(__classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f"), intent, handler);
+        if (__classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent]) {
+            throw new Error(`Intent listener already defined for intent ${intent}`);
+        }
+        else {
+            __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent] = handler;
+        }
         const message = {
             type: "subscribeIntent",
             meta: this.meta(),
@@ -646,8 +879,9 @@ export class FinsembleDesktopAgent {
                 intent,
             },
         };
-        this.exchange(message); // don't wait for response
-        return {
+        // Dangerous code: See note at top of file about 1.2 compatibility
+        const exchangePromise = this.exchange(message); // don't wait for response
+        const listener = {
             unsubscribe: () => {
                 const unsubscribeMessage = {
                     type: "unsubscribeIntent",
@@ -657,11 +891,75 @@ export class FinsembleDesktopAgent {
                     },
                 };
                 this.exchange(unsubscribeMessage); // don't wait for response
-                __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent] = mmRemove(__classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f"), intent, handler);
+                delete __classPrivateFieldGet(this, _FinsembleDesktopAgent_intentHandlers, "f")[intent];
+            },
+        };
+        // Dangerous code: See note at top of file about 1.2 compatibility
+        let promise = new Promise((resolve) => {
+            exchangePromise.then(() => {
+                resolve(listener);
+            });
+        });
+        promise.unsubscribe = () => {
+            Logger.system.deprecated("Use of the synchronous version of addIntentListener from FDC3 1.2 is deprecated. Please switch to `await addIntentListener`.");
+            listener.unsubscribe();
+        };
+        return promise;
+    }
+    // Common functions to handler incoming Private Channel events to support onAddListener, onSubscribe, and oDisconnect
+    listenerForPrivateChannelEvent(subscribeType, channel, handler) {
+        // A unique targetSubscriberId must be passed in InteropSubscribeChannelOnAddContext; the InteropService can direct messages to this specific listener by returning the targetSubscriberId in a broadcast message,
+        const targetSubscriberId = `subscriberId.${channel}.${subscribeType}.${Date.now()}_${Math.random()}`;
+        // Bind targetSubscriberId to the specific handler and save in map
+        const handlerSet = { subscribeType, handler, channel, targetSubscriberId };
+        __classPrivateFieldGet(this, _FinsembleDesktopAgent_privateChannelSubscription, "f")[channel] = mmAdd(__classPrivateFieldGet(this, _FinsembleDesktopAgent_privateChannelSubscription, "f"), channel, handlerSet);
+        let message = {
+            type: "subscribePrivateChannelEvent",
+            payload: {
+                subscribeType,
+                channel,
+                targetSubscriberId,
+            },
+            meta: this.meta(),
+        };
+        this.exchange(message);
+        return {
+            unsubscribe: () => {
+                let unsubscribeMessage = {
+                    type: "unsubscribePrivateChannelEvent",
+                    payload: {
+                        subscribeType,
+                        channel,
+                        targetSubscriberId,
+                    },
+                    meta: this.meta(),
+                };
+                __classPrivateFieldGet(this, _FinsembleDesktopAgent_privateChannelSubscription, "f")[channel] = mmRemove(__classPrivateFieldGet(this, _FinsembleDesktopAgent_privateChannelSubscription, "f"), channel, handlerSet);
+                this.exchange(unsubscribeMessage); // Don't wait for response
             },
         };
     }
     /** @internal */
+    channelOnAddContextListener(channel, handler) {
+        return this.listenerForPrivateChannelEvent("onAddContextListener", channel, handler);
+    }
+    /** @internal */
+    channelOnUnsubscribe(channel, handler) {
+        return this.listenerForPrivateChannelEvent("onUnsubscribe", channel, handler);
+    }
+    /** @internal */
+    channelOnDisconnect(channel, handler) {
+        return this.listenerForPrivateChannelEvent("onDisconnect", channel, handler);
+    }
+    /** @internal */
+    channelDisconnect(channel) {
+        let message = {
+            type: "channelDisconnect",
+            meta: Object.assign(Object.assign({}, this.meta()), { channel }),
+        };
+        this.exchange(message);
+    }
+    /** @internal */
     channelAddContextListener(channel, contextTypeOrHandler, handler) {
         // Derives a definitive contextType and handler from the varargs
         // Possibilities: addContextListener(handler) - deprecated 1.1, addContextListener(null, handler), addContextListener(contextType, handler)
@@ -683,8 +981,9 @@ export class FinsembleDesktopAgent {
         };
         if (channel)
             message.meta.channel = channel;
-        this.exchange(message); // Don't wait for response
+        const exchangePromise = this.exchange(message);
         return {
+            exchangePromise,
             unsubscribe: () => {
                 let unsubscribeMessage = {
                     type: "unsubscribeContext",
@@ -713,7 +1012,20 @@ export class FinsembleDesktopAgent {
         if (typeof contextTypeOrHandler !== "function" && !handler) {
             throw new Error("Invalid arguments. The required handler parameter is missing.");
         }
-        return this.channelAddContextListener(null, contextTypeOrHandler, handler);
+        // Dangerous code: See note at top of file about 1.2 compatibility
+        const { exchangePromise, unsubscribe } = this.channelAddContextListener(null, contextTypeOrHandler, handler);
+        let promise = new Promise((resolve) => {
+            exchangePromise.then(() => {
+                resolve({
+                    unsubscribe,
+                });
+            });
+        });
+        promise.unsubscribe = () => {
+            Logger.system.deprecated("Use of the synchronous version of addContextListener from FDC3 1.2 is deprecated. Please switch to `await addContextListener`.");
+            unsubscribe();
+        };
+        return promise;
     }
     /**
      * Joins the app to the specified channel.
@@ -723,10 +1035,18 @@ export class FinsembleDesktopAgent {
      * Error with a string from the ChannelError enumeration.
      * @param channelId
      */
-    async joinChannel(channelId) {
+    async joinUserChannel(channelId) {
         if (!channelId) {
             throw new Error("Invalid arguments. The required channelId parameter is missing.");
         }
+        if (__classPrivateFieldGet(this, _FinsembleDesktopAgent_existingChannelProxy, "f")[channelId]) {
+            Logger.system.error("joinUserChannel: An `app` or `private` channel id was input to joinUserChannels.  Only `user` channels can be joined. ");
+        }
+        // Move this test to the InteropService so no dely is added, which might cause a backwards compatability issue
+        // const userChannels = await this.getUserChannels();
+        // if (userChannels.find((app) => channelId === app.id) === undefined) {
+        // 	throw new Error(ChannelError.NoChannelFound);
+        // }
         const message = {
             type: "joinChannels",
             meta: this.meta(),
@@ -734,7 +1054,17 @@ export class FinsembleDesktopAgent {
                 channels: [channelId],
             },
         };
-        await this.exchange(message);
+        const { err, receiveMessage } = await this.exchange(message);
+        const interopJoinChannelsResponse = receiveMessage;
+        if (err) {
+            throw new Error(err);
+        }
+        else if (interopJoinChannelsResponse.payload.error) {
+            throw new Error(interopJoinChannelsResponse.payload.error);
+        }
+    }
+    async joinChannel(channelId) {
+        return this.joinUserChannel(channelId);
     }
     /**
      * Returns a Channel object for the specified channel, creating it (as an App channel) - if it does not exist.
@@ -743,13 +1073,21 @@ export class FinsembleDesktopAgent {
      */
     async getOrCreateChannel(channelId) {
         if (!channelId) {
-            throw new Error("Invalid arguments. The required channelId parameter is missing.");
+            Logger.system.debug("getOrCreateChannel: The required channelId parameter is missing.");
+            throw new Error(ChannelError.CreationFailed);
         }
-        return new ChannelProxy(this, channelId);
+        else if (isPrivateChannelId(channelId)) {
+            throw new Error(ChannelError.AccessDenied);
+        }
+        // if channel proxy has already been allocated for the channelId, then return it; otherwise allocate a new one
+        let channelInstance = __classPrivateFieldGet(this, _FinsembleDesktopAgent_existingChannelProxy, "f")[channelId];
+        if (!channelInstance) {
+            channelInstance = new ChannelProxy(this, channelId);
+            __classPrivateFieldGet(this, _FinsembleDesktopAgent_existingChannelProxy, "f")[channelId] = channelInstance;
+        }
+        return channelInstance;
     }
     /**
-     * FDC3 2.0 pre-release
-     *
      * Get all joined channels
      *
      * Known race condition: getCurrentChannels() can return an empty string if it is called before the InteropService's linker module
@@ -765,15 +1103,15 @@ export class FinsembleDesktopAgent {
         const { err, receiveMessage } = await this.exchange(message);
         const interopGetCurrentChannelsResponse = receiveMessage;
         if (err) {
-            throw this.fdc3Error(err);
+            throw new Error(err);
         }
         else if (interopGetCurrentChannelsResponse.payload.error) {
-            throw this.fdc3Error(interopGetCurrentChannelsResponse.payload.error);
+            throw new Error(interopGetCurrentChannelsResponse.payload.error);
         }
         else if (!interopGetCurrentChannelsResponse.payload.data) {
-            throw this.fdc3Error("Invalid response returned from InteropService for getCurrentChannels. No data.");
+            throw new Error("Invalid response returned from InteropService for getCurrentChannels. No data.");
         }
-        return interopGetCurrentChannelsResponse.payload.data.map((entry) => new ChannelProxy(this, entry.channel, "system"));
+        return interopGetCurrentChannelsResponse.payload.data.map((entry) => new ChannelProxy(this, entry.channel, "user"));
     }
     /**
      * Returns the Channel object for the current channel membership.
@@ -795,19 +1133,78 @@ export class FinsembleDesktopAgent {
         };
         await this.exchange(message);
     }
+    /**
+     * Return specified app's meta data.
+     */
+    async getAppMetadata(app) {
+        var _a;
+        if (!app || !(app === null || app === void 0 ? void 0 : app.appId)) {
+            throw new Error("getAppMetadata: The required app parameter is missing or not an AppIdentifier.");
+        }
+        const message = {
+            type: "getAppMetadata",
+            app,
+            meta: this.meta(),
+        };
+        const { err, receiveMessage } = await this.exchange(message);
+        const interopGetCurrentChannelsResponse = receiveMessage;
+        if (err) {
+            throw new Error(err);
+        }
+        else if (interopGetCurrentChannelsResponse.payload.error) {
+            throw new Error(interopGetCurrentChannelsResponse.payload.error);
+        }
+        else if (!interopGetCurrentChannelsResponse.payload.appMetadata) {
+            throw new Error("Invalid response returned from InteropService for getCurrentChannels. No data.");
+        }
+        return (_a = interopGetCurrentChannelsResponse.payload) === null || _a === void 0 ? void 0 : _a.appMetadata;
+    }
+    /**
+     * Return all the open instances of given appID.
+     */
+    async findInstances(app) {
+        let instances = [];
+        const message = {
+            type: "findInstances",
+            app,
+            meta: this.meta(),
+        };
+        if (app === null || app === void 0 ? void 0 : app.appId) {
+            const { receiveMessage } = await this.exchange(message);
+            const response = receiveMessage;
+            ({ instances } = response.payload);
+        }
+        return instances;
+    }
     /**
      * Retrieves information about the FDC3 Desktop Agent implementation, such as
      * the implemented version of the FDC3 specification and the name of the implementation
      * provider.
      */
     getInfo() {
-        return {
-            fdc3Version: "1.2",
-            provider: "Finsemble",
-            // This data is added at build time by webpack EnvironmentPlugin
-            providerVersion: __classPrivateFieldGet(this, _FinsembleDesktopAgent_FSBLVersion, "f"),
-        };
+        // Dangerous code: See note at top of file about 1.2 compatibility
+        let p = new Promise(async (resolve) => {
+            const { data: FSBLVersion } = await ConfigClient.getValue({ field: "finsemble.system.FSBLVersion" });
+            const { appMetadata: startupMetadata } = await this.fetchStartupData();
+            // The interopService has more appMetaData than startup, plus it should be the single source of true for an app's metaData
+            const fullAppMetadata = await this.getAppMetadata({ appId: startupMetadata.appId, instanceId: __classPrivateFieldGet(this, _FinsembleDesktopAgent_uuid, "f") });
+            resolve({
+                fdc3Version: "2.0",
+                provider: "Finsemble",
+                providerVersion: FSBLVersion,
+                appMetadata: fullAppMetadata,
+                optionalFeatures: {
+                    OriginatingAppMetadata: true,
+                    UserChannelMembershipAPIs: true,
+                },
+            });
+        });
+        // Backward compatibility for 1.2 which expects this to be synchronous
+        p.fdc3Version = "1.2";
+        p.provider = "Finsemble";
+        p.providerVersion = "8.0.1";
+        return p;
     }
 }
-_FinsembleDesktopAgent_connected = new WeakMap(), _FinsembleDesktopAgent_heartbeatMonitor = new WeakMap(), _FinsembleDesktopAgent_startHasBeenCalled = new WeakMap(), _FinsembleDesktopAgent_uuid = new WeakMap(), _FinsembleDesktopAgent_clientChannel = new WeakMap(), _FinsembleDesktopAgent_intentHandlers = new WeakMap(), _FinsembleDesktopAgent_contextHandlers = new WeakMap(), _FinsembleDesktopAgent_queue = new WeakMap(), _FinsembleDesktopAgent_routerClient = new WeakMap(), _FinsembleDesktopAgent_startup = new WeakMap(), _FinsembleDesktopAgent_FSBLVersion = new WeakMap();
+_FinsembleDesktopAgent_connected = new WeakMap(), _FinsembleDesktopAgent_heartbeatMonitor = new WeakMap(), _FinsembleDesktopAgent_startHasBeenCalled = new WeakMap(), _FinsembleDesktopAgent_uuid = new WeakMap(), _FinsembleDesktopAgent_clientChannel = new WeakMap(), _FinsembleDesktopAgent_intentHandlers = new WeakMap(), _FinsembleDesktopAgent_contextHandlers = new WeakMap(), _FinsembleDesktopAgent_privateChannelSubscription = new WeakMap(), _FinsembleDesktopAgent_intentResultPromiseMap = new WeakMap(), _FinsembleDesktopAgent_intentResultPromiseResolveMap = new WeakMap(), _FinsembleDesktopAgent_queue = new WeakMap(), _FinsembleDesktopAgent_routerClient = new WeakMap(), _FinsembleDesktopAgent_startup = new WeakMap(), _FinsembleDesktopAgent_existingChannelProxy = new WeakMap();
 //# sourceMappingURL=FinsembleDesktopAgent.js.map