@openfin/core 33.76.27 → 33.76.36

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

@@ -12,14 +12,178 @@ export interface ChannelMessage extends Message<any> {
     providerIdentity: ProviderIdentity;
     connectAction: boolean;
 }
+/**
+ * The Channel API allows an OpenFin application to create a channel as a {@link ChannelProvider ChannelProvider},
+ * or connect to a channel as a {@link ChannelClient ChannelClient}.
+ * @remarks The "handshake" between the communication partners is
+ * simplified when using a channel.  A request to connect to a channel as a client will return a promise that resolves if/when the channel has been created. Both the
+ * provider and client can dispatch actions that have been registered on their opposites, and dispatch returns a promise that resolves with a payload from the other
+ * communication participant. There can be only one provider per channel, but many clients.  Version `9.61.35.*` or later is required for both communication partners.
+ *
+ * Asynchronous Methods:
+ *  * {@link Channel.create create(channelName, options)}
+ *  * {@link Channel.connect connect(channelName, options)}
+ *  * {@link Channel.onChannelConnect onChannelConnect(listener)}
+ *  * {@link Channel.onChannelDisconnect onChannelDisconnect(listener)}
+ */
 export declare class Channel extends EmitterBase<ChannelEvent> {
     #private;
+    /**
+     * @internal
+     */
     constructor(wire: Transport);
+    /**
+     *
+     * @internal
+     */
     getAllChannels(): Promise<ProviderIdentity[]>;
+    /**
+     * Listens for channel connections.
+     *
+     * @param listener - callback to execute.
+     *
+     * @example
+     *
+     * ```js
+     * const listener = (channelPayload) => console.log(channelPayload); // see return value below
+     *
+     * fin.InterApplicationBus.Channel.onChannelConnect(listener);
+     *
+     * // example shape
+     * {
+     *     "topic": "channel",
+     *     "type": "connected",
+     *     "uuid": "OpenfinPOC",
+     *     "name": "OpenfinPOC",
+     *     "channelName": "counter",
+     *     "channelId": "OpenfinPOC/OpenfinPOC/counter"
+     * }
+     *
+     * ```
+     */
     onChannelConnect(listener: (...args: any[]) => void): Promise<void>;
+    /**
+     * Listen for channel disconnections.
+     *
+     * @param listener - callback to execute.
+     *
+     * @example
+     *
+     * ```js
+     * const listener = (channelPayload) => console.log(channelPayload); // see return value below
+     *
+     * fin.InterApplicationBus.Channel.onChannelDisconnect(listener);
+     *
+     * // example shape
+     * {
+     *     "topic": "channel",
+     *     "type": "disconnected",
+     *     "uuid": "OpenfinPOC",
+     *     "name": "OpenfinPOC",
+     *     "channelName": "counter",
+     *     "channelId": "OpenfinPOC/OpenfinPOC/counter"
+     * }
+     *
+     * ```
+     */
     onChannelDisconnect(listener: (...args: any[]) => void): Promise<void>;
     private safeConnect;
+    /**
+     * Connect to a channel. If you wish to send a payload to the provider, add a payload property to the options argument.
+     * EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
+     *
+     * @param channelName - Name of the target channel.
+     * @param options - Connection options.
+     * @returns Returns a promise that resolves with an instance of {@link ChannelClient ChannelClient}.
+     *
+     * @remarks The connection request will be routed to the channelProvider if/when the channel is created.  If the connect
+     * request is sent prior to creation, the promise will not resolve or reject until the channel is created by a channelProvider
+     * (whether or not to wait for creation is configurable in the connectOptions).
+     *
+     * The connect call returns a promise that will resolve with a channelClient bus if accepted by the channelProvider, or reject if
+     * the channelProvider throws an error to reject the connection. This bus can communicate with the Provider, but not to other
+     * clients on the channel. Using the bus, the channelClient can register actions and middleware. Channel lifecycle can also be
+     * handled with an onDisconnection listener.
+     *
+     * @example
+     *
+     * ```js
+     * async function makeClient(channelName) {
+     *    // A payload can be sent along with channel connection requests to help with authentication
+     *    const connectPayload = { payload: 'token' };
+     *
+     *    // If the channel has been created this request will be sent to the provider.  If not, the
+     *    // promise will not be resolved or rejected until the channel has been created.
+     *    const clientBus = await fin.InterApplicationBus.Channel.connect(channelName, connectPayload);
+     *
+     *    clientBus.onDisconnection(channelInfo => {
+     *        // handle the channel lifecycle here - we can connect again which will return a promise
+     *        // that will resolve if/when the channel is re-created.
+     *        makeClient(channelInfo.channelName);
+     *    })
+     *
+     *    clientBus.register('topic', (payload, identity) => {
+     *        // register a callback for a topic to which the channel provider can dispatch an action
+     *        console.log('Action dispatched by provider: ', JSON.stringify(identity));
+     *        console.log('Payload sent in dispatch: ', JSON.stringify(payload));
+     *        return {
+     *            echo: payload
+     *        };
+     *    });
+     * }
+     *
+     * makeClient('channelName')
+     * .then(() => console.log('Connected'))
+     * .catch(console.error);
+     * ```
+     */
     connect(channelName: string, options?: OpenFin.ChannelConnectOptions): Promise<ChannelClient>;
+    /**
+     * Create a new channel.
+     * You must provide a unique channelName. If a channelName is not provided, or it is not unique, the creation will fail.
+     * EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
+     *
+     * @param channelName - Name of the channel to be created.
+     * @param options - Creation options.
+     * @returns Returns a promise that resolves with an instance of {@link ChannelProvider ChannelProvider}.
+     *
+     * @remarks If successful, the create method returns a promise that resolves to an instance of the channelProvider bus. The caller
+     * then becomes the “channel provider” and can use the channelProvider bus to register actions and middleware.
+     *
+     * The caller can also set an onConnection and/or onDisconnection listener that will execute on any new channel
+     * connection/disconnection attempt from a channel client. To reject a connection, simply throw an error in the
+     * onConnection listener.  The default behavior is to accept all new connections.
+     *
+     * A map of client connections is updated automatically on client connection and disconnection and saved in the
+     * [read-only] `connections` property on the channelProvider bus.  The channel will exist until the provider
+     * destroys it or disconnects by closing or destroying the context (navigating or reloading). To setup a channel
+     * as a channelProvider, call `Channel.create` with a unique channel name. A map of client connections is updated
+     * automatically on client connection and disconnection.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *    // entity creates a channel and becomes the channelProvider
+     *    const providerBus = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *    providerBus.onConnection((identity, payload) => {
+     *        // can reject a connection here by throwing an error
+     *        console.log('Client connection request identity: ', JSON.stringify(identity));
+     *        console.log('Client connection request payload: ', JSON.stringify(payload));
+     *    });
+     *
+     *    providerBus.register('topic', (payload, identity) => {
+     *        // register a callback for a 'topic' to which clients can dispatch an action
+     *        console.log('Action dispatched by client: ', JSON.stringify(identity));
+     *        console.log('Payload sent in dispatch: ', JSON.stringify(payload));
+     *        return {
+     *            echo: payload
+     *        };
+     *    });
+     * })();
+     * ```
+     */
     create(channelName: string, options?: OpenFin.ChannelCreateOptions): Promise<ChannelProvider>;
 }
 export {};

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

@@ -27,13 +27,30 @@ function retryDelay(count) {
     const max = 30000; // max delay
     const step = Math.floor(count / steps);
     const delay = Math.min(max, interval * base ** step);
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
         setTimeout(() => {
             resolve(false);
         }, delay);
     });
 }
+/**
+ * The Channel API allows an OpenFin application to create a channel as a {@link ChannelProvider ChannelProvider},
+ * or connect to a channel as a {@link ChannelClient ChannelClient}.
+ * @remarks The "handshake" between the communication partners is
+ * simplified when using a channel.  A request to connect to a channel as a client will return a promise that resolves if/when the channel has been created. Both the
+ * provider and client can dispatch actions that have been registered on their opposites, and dispatch returns a promise that resolves with a payload from the other
+ * communication participant. There can be only one provider per channel, but many clients.  Version `9.61.35.*` or later is required for both communication partners.
+ *
+ * Asynchronous Methods:
+ *  * {@link Channel.create create(channelName, options)}
+ *  * {@link Channel.connect connect(channelName, options)}
+ *  * {@link Channel.onChannelConnect onChannelConnect(listener)}
+ *  * {@link Channel.onChannelDisconnect onChannelDisconnect(listener)}
+ */
 class Channel extends base_1.EmitterBase {
+    /**
+     * @internal
+     */
     constructor(wire) {
         super(wire, 'channel');
         _Channel_connectionManager.set(this, void 0);
@@ -51,12 +68,64 @@ class Channel extends base_1.EmitterBase {
         }));
         __classPrivateFieldSet(this, _Channel_connectionManager, new connection_manager_1.ConnectionManager(wire), "f");
     }
+    /**
+     *
+     * @internal
+     */
     async getAllChannels() {
         return this.wire.sendAction('get-all-channels').then(({ payload }) => payload.data);
     }
+    /**
+     * Listens for channel connections.
+     *
+     * @param listener - callback to execute.
+     *
+     * @example
+     *
+     * ```js
+     * const listener = (channelPayload) => console.log(channelPayload); // see return value below
+     *
+     * fin.InterApplicationBus.Channel.onChannelConnect(listener);
+     *
+     * // example shape
+     * {
+     *     "topic": "channel",
+     *     "type": "connected",
+     *     "uuid": "OpenfinPOC",
+     *     "name": "OpenfinPOC",
+     *     "channelName": "counter",
+     *     "channelId": "OpenfinPOC/OpenfinPOC/counter"
+     * }
+     *
+     * ```
+     */
     async onChannelConnect(listener) {
         await this.on('connected', listener);
     }
+    /**
+     * Listen for channel disconnections.
+     *
+     * @param listener - callback to execute.
+     *
+     * @example
+     *
+     * ```js
+     * const listener = (channelPayload) => console.log(channelPayload); // see return value below
+     *
+     * fin.InterApplicationBus.Channel.onChannelDisconnect(listener);
+     *
+     * // example shape
+     * {
+     *     "topic": "channel",
+     *     "type": "disconnected",
+     *     "uuid": "OpenfinPOC",
+     *     "name": "OpenfinPOC",
+     *     "channelName": "counter",
+     *     "channelId": "OpenfinPOC/OpenfinPOC/counter"
+     * }
+     *
+     * ```
+     */
     async onChannelDisconnect(listener) {
         await this.on('disconnected', listener);
     }
@@ -111,6 +180,55 @@ class Channel extends base_1.EmitterBase {
         throw new Error(`No channel found for channelName: ${channelName}.`);
         /* eslint-enable no-await-in-loop, no-constant-condition */
     }
+    /**
+     * Connect to a channel. If you wish to send a payload to the provider, add a payload property to the options argument.
+     * EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
+     *
+     * @param channelName - Name of the target channel.
+     * @param options - Connection options.
+     * @returns Returns a promise that resolves with an instance of {@link ChannelClient ChannelClient}.
+     *
+     * @remarks The connection request will be routed to the channelProvider if/when the channel is created.  If the connect
+     * request is sent prior to creation, the promise will not resolve or reject until the channel is created by a channelProvider
+     * (whether or not to wait for creation is configurable in the connectOptions).
+     *
+     * The connect call returns a promise that will resolve with a channelClient bus if accepted by the channelProvider, or reject if
+     * the channelProvider throws an error to reject the connection. This bus can communicate with the Provider, but not to other
+     * clients on the channel. Using the bus, the channelClient can register actions and middleware. Channel lifecycle can also be
+     * handled with an onDisconnection listener.
+     *
+     * @example
+     *
+     * ```js
+     * async function makeClient(channelName) {
+     *    // A payload can be sent along with channel connection requests to help with authentication
+     *    const connectPayload = { payload: 'token' };
+     *
+     *    // If the channel has been created this request will be sent to the provider.  If not, the
+     *    // promise will not be resolved or rejected until the channel has been created.
+     *    const clientBus = await fin.InterApplicationBus.Channel.connect(channelName, connectPayload);
+     *
+     *    clientBus.onDisconnection(channelInfo => {
+     *        // handle the channel lifecycle here - we can connect again which will return a promise
+     *        // that will resolve if/when the channel is re-created.
+     *        makeClient(channelInfo.channelName);
+     *    })
+     *
+     *    clientBus.register('topic', (payload, identity) => {
+     *        // register a callback for a topic to which the channel provider can dispatch an action
+     *        console.log('Action dispatched by provider: ', JSON.stringify(identity));
+     *        console.log('Payload sent in dispatch: ', JSON.stringify(payload));
+     *        return {
+     *            echo: payload
+     *        };
+     *    });
+     * }
+     *
+     * makeClient('channelName')
+     * .then(() => console.log('Connected'))
+     * .catch(console.error);
+     * ```
+     */
     async connect(channelName, options = {}) {
         // Make sure we don't connect before listeners are set up
         // This also errors if we're not in OpenFin, ensuring we don't run unnecessary code
@@ -149,6 +267,52 @@ class Channel extends base_1.EmitterBase {
         });
         return channel;
     }
+    /**
+     * Create a new channel.
+     * You must provide a unique channelName. If a channelName is not provided, or it is not unique, the creation will fail.
+     * EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
+     *
+     * @param channelName - Name of the channel to be created.
+     * @param options - Creation options.
+     * @returns Returns a promise that resolves with an instance of {@link ChannelProvider ChannelProvider}.
+     *
+     * @remarks If successful, the create method returns a promise that resolves to an instance of the channelProvider bus. The caller
+     * then becomes the “channel provider” and can use the channelProvider bus to register actions and middleware.
+     *
+     * The caller can also set an onConnection and/or onDisconnection listener that will execute on any new channel
+     * connection/disconnection attempt from a channel client. To reject a connection, simply throw an error in the
+     * onConnection listener.  The default behavior is to accept all new connections.
+     *
+     * A map of client connections is updated automatically on client connection and disconnection and saved in the
+     * [read-only] `connections` property on the channelProvider bus.  The channel will exist until the provider
+     * destroys it or disconnects by closing or destroying the context (navigating or reloading). To setup a channel
+     * as a channelProvider, call `Channel.create` with a unique channel name. A map of client connections is updated
+     * automatically on client connection and disconnection.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *    // entity creates a channel and becomes the channelProvider
+     *    const providerBus = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *    providerBus.onConnection((identity, payload) => {
+     *        // can reject a connection here by throwing an error
+     *        console.log('Client connection request identity: ', JSON.stringify(identity));
+     *        console.log('Client connection request payload: ', JSON.stringify(payload));
+     *    });
+     *
+     *    providerBus.register('topic', (payload, identity) => {
+     *        // register a callback for a 'topic' to which clients can dispatch an action
+     *        console.log('Action dispatched by client: ', JSON.stringify(identity));
+     *        console.log('Payload sent in dispatch: ', JSON.stringify(payload));
+     *        return {
+     *            echo: payload
+     *        };
+     *    });
+     * })();
+     * ```
+     */
     async create(channelName, options) {
         if (!channelName) {
             throw new Error('Please provide a channelName to create a channel');

package/src/api/interappbus/channel/provider.d.ts

@@ -6,22 +6,194 @@ type ProviderIdentity = OpenFin.ProviderIdentity;
 type ClientIdentity = OpenFin.ClientIdentity;
 export type ConnectionListener = (identity: ClientIdentity, connectionMessage?: any) => Promise<any> | any;
 export type DisconnectionListener = (identity: ClientIdentity) => any;
+/**
+ * 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)}
+ */
 export declare class ChannelProvider extends ChannelBase {
     #private;
     private static removalMap;
     private connectListener;
     private disconnectListener;
+    /**
+     * a read-only array containing all the identities of connecting clients.
+     */
     get connections(): OpenFin.ClientConnectionPayload[];
     static handleClientDisconnection(channel: ChannelProvider, payload: any): void;
     static setProviderRemoval(provider: ChannelProvider, remove: Function): void;
+    /**
+     * @internal
+     */
     constructor(providerIdentity: ProviderIdentity, wire: Transport, strategy: AnyStrategy);
+    /**
+     * 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: OpenFin.ClientIdentity | OpenFin.Identity, action: string, payload?: any): Promise<any>;
     protected processAction: (action: string, payload: any, senderIdentity: OpenFin.ClientIdentity | OpenFin.ClientIdentityMultiRuntime) => Promise<any>;
     processConnection(senderId: OpenFin.ClientConnectionPayload, payload: any): Promise<any>;
+    /**
+     * 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: string, payload: any): Promise<any>[];
+    /**
+     * 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: ConnectionListener): void;
+    /**
+     * 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: DisconnectionListener): void;
+    /**
+     * 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();
+     * })();
+     * ```
+     */
     destroy(): Promise<void>;
+    /**
+     * 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"
+     * //    }
+     * //]
+     * ```
+     */
     getAllClientInfo(): Promise<Array<OpenFin.ClientInfo>>;
     private checkForClientConnection;
     private isClientConnected;