@openfin/core 33.76.31 → 33.76.36

package/src/api/interappbus/channel/provider.js

@@ -15,7 +15,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChannelProvider = void 0;
 const channel_1 = require("./channel");
 const runtimeVersioning_1 = require("../../../util/runtimeVersioning");
+/**
+ * Instance created to enable use of a channel as a provider. Allows for communication with the {@link ChannelClient ChannelClients} by invoking an action on
+ * a single client via {@link ChannelProvider#dispatch dispatch} or all clients via {@link ChannelProvider#publish publish}
+ * and to listen for communication from clients by registering an action via {@link ChannelProvider#register register}.
+ *
+ * Synchronous Methods:
+ *  * {@link ChannelProvider#onConnection onConnection(listener)}
+ *  * {@link ChannelProvider#onDisconnection onDisconnection(listener)}
+ *  * {@link ChannelProvider#publish publish(action, payload)}
+ *  * {@link ChannelProvider#register register(action, listener)}
+ *  * {@link ChannelProvider#remove remove(action)}
+ *
+ * Asynchronous Methods:
+ *  * {@link ChannelProvider#destroy destroy()}
+ *  * {@link ChannelProvider#dispatch dispatch(to, action, payload)}
+ *  * {@link ChannelProvider#getAllClientInfo getAllClientInfo()}
+ *
+ * Middleware:
+ * <br>Middleware functions receive the following arguments: (action, payload, senderId).
+ * The return value of the middleware function will be passed on as the payload from beforeAction, to the action listener, to afterAction
+ * unless it is undefined, in which case the most recently defined payload is used.  Middleware can be used for side effects.
+ *  * {@link ChannelProvider#setDefaultAction setDefaultAction(middleware)}
+ *  * {@link ChannelProvider#onError onError(middleware)}
+ *  * {@link ChannelProvider#beforeAction beforeAction(middleware)}
+ *  * {@link ChannelProvider#afterAction afterAction(middleware)}
+ */
 class ChannelProvider extends channel_1.ChannelBase {
+    /**
+     * a read-only array containing all the identities of connecting clients.
+     */
     get connections() {
         return [...__classPrivateFieldGet(this, _ChannelProvider_connections, "f")];
     }
@@ -35,6 +64,9 @@ class ChannelProvider extends channel_1.ChannelBase {
     static setProviderRemoval(provider, remove) {
         ChannelProvider.removalMap.set(provider, remove);
     }
+    /**
+     * @internal
+     */
     constructor(providerIdentity, wire, strategy) {
         super();
         _ChannelProvider_connections.set(this, void 0);
@@ -70,6 +102,32 @@ class ChannelProvider extends channel_1.ChannelBase {
         __classPrivateFieldSet(this, _ChannelProvider_strategy, strategy, "f");
         strategy.receive(this.processAction);
     }
+    /**
+     * Dispatch an action to a specified client. Returns a promise for the result of executing that action on the client side.
+     *
+     * @param to - Identity of the target client.
+     * @param action - Name of the action to be invoked by the client.
+     * @param payload - Payload to be sent along with the action.
+     *
+     * @remarks
+     *
+     * Because multiple clients can share the same `name` and `uuid`, when dispatching from a provider to a client,
+     * the `identity` you provide must include the client's unique `endpointId` property. This `endpointId` is
+     * passed to the provider in both the `Provider.onConnection` callback and in any registered action callbacks.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', async (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return await provider.dispatch(identity, 'client-action', 'Hello, World!');
+     *     });
+     * })();
+     * ```
+     */
     dispatch(to, action, payload) {
         var _a;
         const endpointId = (_a = to.endpointId) !== null && _a !== void 0 ? _a : this.getEndpointIdForOpenFinId(to, action);
@@ -82,15 +140,99 @@ class ChannelProvider extends channel_1.ChannelBase {
         __classPrivateFieldGet(this, _ChannelProvider_connections, "f").push(senderId);
         return this.connectListener(senderId, payload);
     }
+    /**
+     * Publish an action and payload to every connected client.
+     * Synchronously returns an array of promises for each action (see dispatch).
+     *
+     * @param action
+     * @param payload
+     *
+     * @example
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', async (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return await Promise.all(provider.publish('client-action', { message: 'Broadcast from provider'}));
+     *     });
+     * })();
+     * ```
+     */
     publish(action, payload) {
         return this.connections.map((to) => __classPrivateFieldGet(this, _ChannelProvider_strategy, "f").send(to.endpointId, action, payload));
     }
+    /**
+     * Register a listener that is called on every new client connection.
+     *
+     * @remarks It is passed the identity of the connecting client and a payload if it was provided to Channel.connect.
+     * If you wish to reject the connection, throw an error. Be sure to synchronously provide an onConnection upon receipt of
+     * the channelProvider to ensure all potential client connections are caught by the listener.
+     *
+     * Because multiple clients can exist at the same `name` and `uuid`, in order to distinguish between individual clients,
+     * the `identity` argument in a provider's `onConnection` callback contains an `endpointId` property. When dispatching from a
+     * provider to a client, the `endpointId` property must be provided in order to send an action to a specific client.
+     *
+     * @example
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.onConnection(identity => {
+     *         console.log('Client connected', identity);
+     *     });
+     * })();
+     * ```
+     *
+     * Reject connection:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.onConnection(identity => {
+     *         throw new Error('Connection Rejected');
+     *     });
+     * })();
+     * ```
+     * @param listener
+     */
     onConnection(listener) {
         this.connectListener = listener;
     }
+    /**
+     * Register a listener that is called on client disconnection. It is passed the disconnection event of the disconnecting
+     * client.
+     *
+     * @param listener
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.onDisconnection(evt => {
+     *         console.log('Client disconnected', `uuid: ${evt.uuid}, name: ${evt.name}`);
+     *     });
+     * })();
+     * ```
+     */
     onDisconnection(listener) {
         this.disconnectListener = listener;
     }
+    /**
+     * Destroy the channel, raises `disconnected` events on all connected channel clients.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.destroy();
+     * })();
+     * ```
+     */
     async destroy() {
         const protectedObj = __classPrivateFieldGet(this, _ChannelProvider_protectedObj, "f");
         const { channelName } = protectedObj.providerIdentity;
@@ -98,6 +240,36 @@ class ChannelProvider extends channel_1.ChannelBase {
         await protectedObj.wire.sendAction('destroy-channel', { channelName });
         __classPrivateFieldGet(this, _ChannelProvider_close, "f").call(this);
     }
+    /**
+     * Returns an array with info on every Client connected to the Provider
+     *
+     * @example
+     *
+     * ```js
+     * const provider = await fin.InterApplicationBus.Channel.create('openfin');
+     * const client = await fin.InterApplicationBus.Channel.connect('openfin');
+     * const clientInfo = await provider.getAllClientInfo();
+     *
+     * console.log(clientInfo);
+     *
+     * // [
+     * //    {
+     * //        "uuid": "openfin",
+     * //        "name": "openfin-view",
+     * //        "endpointId": "6d4c7ca8-4a74-4634-87f8-760558229613",
+     * //        "entityType": "view",
+     * //        "url": "https://openfin.co"
+     * //    },
+     * //    {
+     * //        "uuid": "openfin2",
+     * //        "name": "openfin-view2",
+     * //        "endpointId": "4z5d8ab9-2b81-3691-91ex-142179382511",
+     * //        "entityType": "view",
+     * //        "url": "https://example.com"
+     * //    }
+     * //]
+     * ```
+     */
     async getAllClientInfo() {
         return this.connections.map((clientInfo) => {
             const { uuid, name, endpointId, entityType, connectionUrl } = clientInfo;

package/src/api/interappbus/index.d.ts

@@ -5,7 +5,7 @@ import { Transport, Message } from '../../transport/transport';
 import { Channel } from './channel/index';
 /**
  * A messaging bus that allows for pub/sub messaging between different applications.
- * @namespace
+ *
  */
 export default class InterApplicationBus extends Base {
     Channel: Channel;
@@ -17,27 +17,36 @@ export default class InterApplicationBus extends Base {
     protected emitter: EventEmitter;
     on: any;
     removeAllListeners: any;
+    /**
+     * @internal
+     */
     constructor(wire: Transport);
     /**
      * Publishes a message to all applications running on OpenFin Runtime that
      * are subscribed to the specified topic.
-     * @param { string } topic The topic on which the message is sent
-     * @param { any } message The message to be published. Can be either a primitive
+     * @param topic The topic on which the message is sent
+     * @param message The message to be published. Can be either a primitive
      * data type (string, number, or boolean) or composite data type (object, array)
      * that is composed of other primitive or composite data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.publish
+     *
+     * @example
+     * ```js
+     * fin.InterApplicationBus.publish('topic', 'hello').then(() => console.log('Published')).catch(err => console.log(err));
+     * ```
      */
     publish(topic: string, message: any): Promise<void>;
     /**
      * Sends a message to a specific application on a specific topic.
-     * @param { Identity } destination The identity of the application to which the message is sent
-     * @param { string } topic The topic on which the message is sent
-     * @param { any } message The message to be sent. Can be either a primitive data
+     * @param destination The identity of the application to which the message is sent
+     * @param topic The topic on which the message is sent
+     * @param message The message to be sent. Can be either a primitive data
      * type (string, number, or boolean) or composite data type (object, array) that
      * is composed of other primitive or composite data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.send
+     *
+     * @example
+     * ```js
+     * fin.InterApplicationBus.send(fin.me, 'topic', 'Hello there!').then(() => console.log('Message sent')).catch(err => console.log(err));
+     * ```
      */
     send(destination: {
         uuid: string;
@@ -45,15 +54,22 @@ export default class InterApplicationBus extends Base {
     }, topic: string, message: any): Promise<void>;
     /**
      * Subscribes to messages from the specified application on the specified topic.
-     * @param { Identity } source This object is described in the Identity in the typedef
-     * @param { string } topic The topic on which the message is sent
-     * @param { function } listener A function that is called when a message has
+     * @param source This object is described in the Identity in the typedef
+     * @param topic The topic on which the message is sent
+     * @param listener A function that is called when a message has
      * been received. It is passed the message, uuid and name of the sending application.
      * The message can be either a primitive data type (string, number, or boolean) or
      * composite data type (object, array) that is composed of other primitive or composite
      * data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.subscribe
+     *
+     * @example
+     * ```js
+     * // subscribe to a specified application
+     * fin.InterApplicationBus.subscribe(fin.me, 'topic', sub_msg => console.log(sub_msg)).then(() => console.log('Subscribed to the specified application')).catch(err => console.log(err));
+     *
+     * // subscribe to wildcard
+     * fin.InterApplicationBus.subscribe({ uuid: '*' }, 'topic', sub_msg => console.log(sub_msg)).then(() => console.log('Subscribed to *')).catch(err => console.log(err));
+     * ```
      */
     subscribe(source: {
         uuid: string;
@@ -61,11 +77,27 @@ export default class InterApplicationBus extends Base {
     }, topic: string, listener: any): Promise<void>;
     /**
      * Unsubscribes to messages from the specified application on the specified topic.
-     * @param { Identity } source This object is described in the Identity in the typedef
-     * @param { string } topic The topic on which the message is sent
-     * @param { function } listener A callback previously registered with subscribe()
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.unsubscribe
+     *
+     * @remarks If you are listening to all apps on a topic, (i.e you passed `{ uuid:'*' }` to the subscribe function)
+     * then you need to pass `{ uuid:'*' }` to unsubscribe as well. If you are listening to a specific application,
+     * (i.e you passed `{ uuid:'some_app' }` to the subscribe function) then you need to provide the same identifier to
+     * unsubscribe, unsubscribing to `*` on that same topic will not unhook your initial listener otherwise.
+     *
+     * @param source This object is described in the Identity in the typedef
+     * @param topic The topic on which the message is sent
+     * @param listener A callback previously registered with subscribe()
+     *
+     * @example
+     * ```js
+     * const listener = console.log;
+     *
+     * // If any application publishes a message on topic `foo`, our listener will be called.
+     * await fin.InterApplicationBus.subscribe({ uuid:'*' }, 'foo', listener)
+     *
+     * // When you want to unsubscribe, you need to specify the uuid of the app you'd like to
+     * // unsubscribe from (or `*`) and provide the same function you gave the subscribe function
+     * await fin.InterApplicationBus.unsubscribe({ uuid:'*' }, 'foo', listener)
+     * ```
      */
     unsubscribe(source: {
         uuid: string;
@@ -76,6 +108,9 @@ export default class InterApplicationBus extends Base {
     protected createSubscriptionKey(uuid: string, name: string, topic: string): string;
     protected onmessage(message: Message<InterAppPayload>): boolean;
 }
+/**
+ * @internal
+ */
 export declare class InterAppPayload {
     sourceUuid: string;
     sourceWindowName: string;

package/src/api/interappbus/index.js

@@ -8,9 +8,12 @@ const index_1 = require("./channel/index");
 const validate_1 = require("../../util/validate");
 /**
  * A messaging bus that allows for pub/sub messaging between different applications.
- * @namespace
+ *
  */
 class InterApplicationBus extends base_1.Base {
+    /**
+     * @internal
+     */
     constructor(wire) {
         super(wire);
         this.events = {
@@ -27,12 +30,15 @@ class InterApplicationBus extends base_1.Base {
     /**
      * Publishes a message to all applications running on OpenFin Runtime that
      * are subscribed to the specified topic.
-     * @param { string } topic The topic on which the message is sent
-     * @param { any } message The message to be published. Can be either a primitive
+     * @param topic The topic on which the message is sent
+     * @param message The message to be published. Can be either a primitive
      * data type (string, number, or boolean) or composite data type (object, array)
      * that is composed of other primitive or composite data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.publish
+     *
+     * @example
+     * ```js
+     * fin.InterApplicationBus.publish('topic', 'hello').then(() => console.log('Published')).catch(err => console.log(err));
+     * ```
      */
     publish(topic, message) {
         return this.wire
@@ -45,13 +51,16 @@ class InterApplicationBus extends base_1.Base {
     }
     /**
      * Sends a message to a specific application on a specific topic.
-     * @param { Identity } destination The identity of the application to which the message is sent
-     * @param { string } topic The topic on which the message is sent
-     * @param { any } message The message to be sent. Can be either a primitive data
+     * @param destination The identity of the application to which the message is sent
+     * @param topic The topic on which the message is sent
+     * @param message The message to be sent. Can be either a primitive data
      * type (string, number, or boolean) or composite data type (object, array) that
      * is composed of other primitive or composite data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.send
+     *
+     * @example
+     * ```js
+     * fin.InterApplicationBus.send(fin.me, 'topic', 'Hello there!').then(() => console.log('Message sent')).catch(err => console.log(err));
+     * ```
      */
     async send(destination, topic, message) {
         const errorMsg = (0, validate_1.validateIdentity)(destination);
@@ -68,15 +77,22 @@ class InterApplicationBus extends base_1.Base {
     }
     /**
      * Subscribes to messages from the specified application on the specified topic.
-     * @param { Identity } source This object is described in the Identity in the typedef
-     * @param { string } topic The topic on which the message is sent
-     * @param { function } listener A function that is called when a message has
+     * @param source This object is described in the Identity in the typedef
+     * @param topic The topic on which the message is sent
+     * @param listener A function that is called when a message has
      * been received. It is passed the message, uuid and name of the sending application.
      * The message can be either a primitive data type (string, number, or boolean) or
      * composite data type (object, array) that is composed of other primitive or composite
      * data types
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.subscribe
+     *
+     * @example
+     * ```js
+     * // subscribe to a specified application
+     * fin.InterApplicationBus.subscribe(fin.me, 'topic', sub_msg => console.log(sub_msg)).then(() => console.log('Subscribed to the specified application')).catch(err => console.log(err));
+     *
+     * // subscribe to wildcard
+     * fin.InterApplicationBus.subscribe({ uuid: '*' }, 'topic', sub_msg => console.log(sub_msg)).then(() => console.log('Subscribed to *')).catch(err => console.log(err));
+     * ```
      */
     subscribe(source, topic, listener) {
         const subKey = this.createSubscriptionKey(source.uuid, source.name || '*', topic);
@@ -96,11 +112,27 @@ class InterApplicationBus extends base_1.Base {
     }
     /**
      * Unsubscribes to messages from the specified application on the specified topic.
-     * @param { Identity } source This object is described in the Identity in the typedef
-     * @param { string } topic The topic on which the message is sent
-     * @param { function } listener A callback previously registered with subscribe()
-     * @return {Promise.<void>}
-     * @tutorial InterApplicationBus.unsubscribe
+     *
+     * @remarks If you are listening to all apps on a topic, (i.e you passed `{ uuid:'*' }` to the subscribe function)
+     * then you need to pass `{ uuid:'*' }` to unsubscribe as well. If you are listening to a specific application,
+     * (i.e you passed `{ uuid:'some_app' }` to the subscribe function) then you need to provide the same identifier to
+     * unsubscribe, unsubscribing to `*` on that same topic will not unhook your initial listener otherwise.
+     *
+     * @param source This object is described in the Identity in the typedef
+     * @param topic The topic on which the message is sent
+     * @param listener A callback previously registered with subscribe()
+     *
+     * @example
+     * ```js
+     * const listener = console.log;
+     *
+     * // If any application publishes a message on topic `foo`, our listener will be called.
+     * await fin.InterApplicationBus.subscribe({ uuid:'*' }, 'foo', listener)
+     *
+     * // When you want to unsubscribe, you need to specify the uuid of the app you'd like to
+     * // unsubscribe from (or `*`) and provide the same function you gave the subscribe function
+     * await fin.InterApplicationBus.unsubscribe({ uuid:'*' }, 'foo', listener)
+     * ```
      */
     unsubscribe(source, topic, listener) {
         const sourceWindowName = source.name || '*';
@@ -163,6 +195,9 @@ class InterApplicationBus extends base_1.Base {
     }
 }
 exports.default = InterApplicationBus;
+/**
+ * @internal
+ */
 class InterAppPayload {
 }
 exports.InterAppPayload = InterAppPayload;

package/src/api/interop/Factory.d.ts

@@ -11,26 +11,46 @@ import { InteropClient } from './InteropClient';
  */
 /**
  * Manages creation of Interop Brokers and Interop Clients. These APIs are called under-the-hood in Platforms.
- * @namespace
- * @alias Interop
+ *
  */
 export default class InteropModule extends Base {
     /**
      * Initializes an Interop Broker. This is called under-the-hood for Platforms.
-     * @param { string } name - Name of the Interop Broker.
-     * @param { OverrideCallback<InteropBroker> } [override] - A callback function that can be used to extend or replace default Interop Broker behavior.
-     * @return {Promise.<InteropBroker>}
-     * @tutorial Interop.init
+     *
+     * @remarks For Platforms, this is set up automatically. We advise to only create your own Interop Broker
+     * when not using a Platform app. You can override functions in the Interop Broker. More info {@link InteropBroker here}.
+     *
+     * @param name - Name of the Interop Broker.
+     * @param override - A callback function that can be used to extend or replace default Interop Broker behavior.
+     *
+     * @example
+     * ``` js
+     * const interopBroker = await fin.Interop.init('openfin');
+     * const contextGroups = await interopBroker.getContextGroups();
+     * console.log(contextGroups);
+     * ```
      * @static
      */
     init(name: string, override?: OpenFin.OverrideCallback<InteropBroker>): Promise<InteropBroker>;
     /**
      * Connects a client to an Interop broker. This is called under-the-hood for Views in a Platform.
-     * @param { string } name - The name of the Interop Broker to connect to. For Platforms, this will default to the uuid of the Platform.
-     * @param { InteropConfig } [interopConfig] - Information relevant to the Interop Broker. Typically a declaration of
+     *
+     * @remarks
+     * @param name - The name of the Interop Broker to connect to. For Platforms, this will default to the uuid of the Platform.
+     * @param interopConfig - Information relevant to the Interop Broker. Typically a declaration of
      * what context(s) the entity wants to subscribe to, and the current Context Group of the entity.
-     * @return {InteropClient}
-     * @tutorial Interop.connectSync
+     *
+     * @example
+     * ```js
+     * const interopConfig = {
+     *     currentContextGroup: 'green'
+     * }
+     *
+     * const interopBroker = await fin.Interop.init('openfin');
+     * const client = await fin.Interop.connectSync('openfin', interopConfig);
+     * const contextGroupInfo = await client.getInfoForContextGroup();
+     * console.log(contextGroupInfo);
+     * ```
      * @static
      */
     connectSync(name: string, interopConfig?: OpenFin.InteropConfig): InteropClient;

package/src/api/interop/Factory.js

@@ -17,16 +17,24 @@ const BrokerParamAccessError = 'You have attempted to use or modify InteropBroke
  */
 /**
  * Manages creation of Interop Brokers and Interop Clients. These APIs are called under-the-hood in Platforms.
- * @namespace
- * @alias Interop
+ *
  */
 class InteropModule extends base_1.Base {
     /**
      * Initializes an Interop Broker. This is called under-the-hood for Platforms.
-     * @param { string } name - Name of the Interop Broker.
-     * @param { OverrideCallback<InteropBroker> } [override] - A callback function that can be used to extend or replace default Interop Broker behavior.
-     * @return {Promise.<InteropBroker>}
-     * @tutorial Interop.init
+     *
+     * @remarks For Platforms, this is set up automatically. We advise to only create your own Interop Broker
+     * when not using a Platform app. You can override functions in the Interop Broker. More info {@link InteropBroker here}.
+     *
+     * @param name - Name of the Interop Broker.
+     * @param override - A callback function that can be used to extend or replace default Interop Broker behavior.
+     *
+     * @example
+     * ``` js
+     * const interopBroker = await fin.Interop.init('openfin');
+     * const contextGroups = await interopBroker.getContextGroups();
+     * console.log(contextGroups);
+     * ```
      * @static
      */
     async init(name, override = defaultOverride) {
@@ -59,11 +67,23 @@ class InteropModule extends base_1.Base {
     }
     /**
      * Connects a client to an Interop broker. This is called under-the-hood for Views in a Platform.
-     * @param { string } name - The name of the Interop Broker to connect to. For Platforms, this will default to the uuid of the Platform.
-     * @param { InteropConfig } [interopConfig] - Information relevant to the Interop Broker. Typically a declaration of
+     *
+     * @remarks
+     * @param name - The name of the Interop Broker to connect to. For Platforms, this will default to the uuid of the Platform.
+     * @param interopConfig - Information relevant to the Interop Broker. Typically a declaration of
      * what context(s) the entity wants to subscribe to, and the current Context Group of the entity.
-     * @return {InteropClient}
-     * @tutorial Interop.connectSync
+     *
+     * @example
+     * ```js
+     * const interopConfig = {
+     *     currentContextGroup: 'green'
+     * }
+     *
+     * const interopBroker = await fin.Interop.init('openfin');
+     * const client = await fin.Interop.connectSync('openfin', interopConfig);
+     * const contextGroupInfo = await client.getInfoForContextGroup();
+     * console.log(contextGroupInfo);
+     * ```
      * @static
      */
     connectSync(name, interopConfig) {