@openfin/core 33.76.27 → 33.76.36

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

@@ -1,3 +1,14 @@
+/**
+ * Entry point for the OpenFin Frame namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "FrameModule" is used for
+ * the module containing static members of the `Frame` namespace (available under `fin.Frame`), while `Frame` documents
+ * instances of the OpenFin `Frame` class.
+ *
+ * Because the `Frame` name aliases a DOM entity, the documentation pipeline prefixes the name with an underscore.
+ *
+ * @packageDocumentation
+ */
 import _FrameModule from './Factory';
 export default _FrameModule;
 export * from './Instance';

package/src/api/frame/index.js

@@ -1,4 +1,15 @@
 "use strict";
+/**
+ * Entry point for the OpenFin Frame namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "FrameModule" is used for
+ * the module containing static members of the `Frame` namespace (available under `fin.Frame`), while `Frame` documents
+ * instances of the OpenFin `Frame` class.
+ *
+ * Because the `Frame` name aliases a DOM entity, the documentation pipeline prefixes the name with an underscore.
+ *
+ * @packageDocumentation
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/src/api/global-hotkey/index.d.ts

@@ -3,36 +3,104 @@ import { EmitterBase } from '../base';
 import { Transport } from '../../transport/transport';
 /**
  * The GlobalHotkey module can register/unregister a global hotkeys.
- * @namespace
+ *
  */
 export default class GlobalHotkey extends EmitterBase<OpenFin.GlobalHotkeyEvent> {
+    /**
+     * @internal
+     */
     constructor(wire: Transport);
     /**
      * Registers a global hotkey with the operating system.
-     * @param { string } hotkey a hotkey string
-     * @param { Function } listener called when the registered hotkey is pressed by the user.
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.register
+     * @param hotkey a hotkey string
+     * @param listener called when the registered hotkey is pressed by the user.
+     *
+     * @remarks The `hotkey` parameter expects an electron compatible [accelerator](https://github.com/electron/electron/blob/master/docs/api/accelerator.md) and the `listener` will be called if the `hotkey` is pressed by the user.
+     * If successfull, the hotkey will be 'claimed' by the application, meaning that this register call can be called multiple times from within the same application but will fail if another application has registered the hotkey.
+     * <br>The register call will fail if given any of these reserved Hotkeys:
+     * * `CommandOrControl+0`
+     * * `CommandOrControl+=`
+     * * `CommandOrControl+Plus`
+     * * `CommandOrControl+-`
+     * * `CommandOrControl+_`
+     * * `CommandOrControl+Shift+I`
+     * * `F5`
+     * * `CommandOrControl+R`
+     * * `Shift+F5`
+     * * `CommandOrControl+Shift+R`
+     *
+     * Raises the `registered` event.
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.register(hotkey, () => {
+     * console.log(`${hotkey} pressed`);
+     * })
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error registering the hotkey', err);
+     * });
+     * ```
      */
     register(hotkey: string, listener: (...args: any[]) => void): Promise<void>;
     /**
      * Unregisters a global hotkey with the operating system.
-     * @param { string } hotkey a hotkey string
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.unregister
+     * @param hotkey a hotkey string
+     *
+     * @remarks This method will unregister all existing registrations of the hotkey within the application.
+     * Raises the `unregistered` event.
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.unregister(hotkey)
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering the hotkey', err);
+     * });
+     * ```
      */
     unregister(hotkey: string): Promise<void>;
     /**
      * Unregisters all global hotkeys for the current application.
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.unregisterAll
+     *
+     * @remarks Raises the `unregistered` event for each hotkey unregistered.
+     *
+     * @example
+     * ```js
+     * fin.GlobalHotkey.unregisterAll()
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering all hotkeys for this application', err);
+     * });
+     * ```
      */
     unregisterAll(): Promise<void>;
     /**
      * Checks if a given hotkey has been registered
-     * @param { string } hotkey a hotkey string
-     * @return {Promise.<boolean>}
-     * @tutorial GlobalHotkey.isRegistered
+     * @param hotkey a hotkey string
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.isRegistered(hotkey)
+     * .then((registered) => {
+     *     console.log(`hotkey ${hotkey} is registered ? ${registered}`);
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering the hotkey', err);
+     * });
+     * ```
      */
     isRegistered(hotkey: string): Promise<boolean>;
 }

package/src/api/global-hotkey/index.js

@@ -3,18 +3,50 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const base_1 = require("../base");
 /**
  * The GlobalHotkey module can register/unregister a global hotkeys.
- * @namespace
+ *
  */
 class GlobalHotkey extends base_1.EmitterBase {
+    /**
+     * @internal
+     */
     constructor(wire) {
         super(wire, 'global-hotkey');
     }
     /**
      * Registers a global hotkey with the operating system.
-     * @param { string } hotkey a hotkey string
-     * @param { Function } listener called when the registered hotkey is pressed by the user.
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.register
+     * @param hotkey a hotkey string
+     * @param listener called when the registered hotkey is pressed by the user.
+     *
+     * @remarks The `hotkey` parameter expects an electron compatible [accelerator](https://github.com/electron/electron/blob/master/docs/api/accelerator.md) and the `listener` will be called if the `hotkey` is pressed by the user.
+     * If successfull, the hotkey will be 'claimed' by the application, meaning that this register call can be called multiple times from within the same application but will fail if another application has registered the hotkey.
+     * <br>The register call will fail if given any of these reserved Hotkeys:
+     * * `CommandOrControl+0`
+     * * `CommandOrControl+=`
+     * * `CommandOrControl+Plus`
+     * * `CommandOrControl+-`
+     * * `CommandOrControl+_`
+     * * `CommandOrControl+Shift+I`
+     * * `F5`
+     * * `CommandOrControl+R`
+     * * `Shift+F5`
+     * * `CommandOrControl+Shift+R`
+     *
+     * Raises the `registered` event.
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.register(hotkey, () => {
+     * console.log(`${hotkey} pressed`);
+     * })
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error registering the hotkey', err);
+     * });
+     * ```
      */
     async register(hotkey, listener) {
         // TODO: fix typing (hotkey events are not typed)
@@ -25,9 +57,23 @@ class GlobalHotkey extends base_1.EmitterBase {
     }
     /**
      * Unregisters a global hotkey with the operating system.
-     * @param { string } hotkey a hotkey string
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.unregister
+     * @param hotkey a hotkey string
+     *
+     * @remarks This method will unregister all existing registrations of the hotkey within the application.
+     * Raises the `unregistered` event.
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.unregister(hotkey)
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering the hotkey', err);
+     * });
+     * ```
      */
     async unregister(hotkey) {
         // TODO: fix typing (hotkey events are not typed)
@@ -38,8 +84,19 @@ class GlobalHotkey extends base_1.EmitterBase {
     }
     /**
      * Unregisters all global hotkeys for the current application.
-     * @return {Promise.<void>}
-     * @tutorial GlobalHotkey.unregisterAll
+     *
+     * @remarks Raises the `unregistered` event for each hotkey unregistered.
+     *
+     * @example
+     * ```js
+     * fin.GlobalHotkey.unregisterAll()
+     * .then(() => {
+     *     console.log('Success');
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering all hotkeys for this application', err);
+     * });
+     * ```
      */
     async unregisterAll() {
         await Promise.all(this.eventNames()
@@ -52,9 +109,20 @@ class GlobalHotkey extends base_1.EmitterBase {
     }
     /**
      * Checks if a given hotkey has been registered
-     * @param { string } hotkey a hotkey string
-     * @return {Promise.<boolean>}
-     * @tutorial GlobalHotkey.isRegistered
+     * @param hotkey a hotkey string
+     *
+     * @example
+     * ```js
+     * const hotkey = 'CommandOrControl+X';
+     *
+     * fin.GlobalHotkey.isRegistered(hotkey)
+     * .then((registered) => {
+     *     console.log(`hotkey ${hotkey} is registered ? ${registered}`);
+     * })
+     * .catch(err => {
+     *     console.log('Error unregistering the hotkey', err);
+     * });
+     * ```
      */
     async isRegistered(hotkey) {
         const { payload: { data } } = await this.wire.sendAction('global-hotkey-is-registered', { hotkey });

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

@@ -7,6 +7,9 @@ type ChannelAction = OpenFin.ChannelAction;
 export declare class ProtectedItems {
     providerIdentity: ProviderIdentity;
     wire: Transport;
+    /**
+     * @internal
+     */
     constructor(providerIdentity: ProviderIdentity, wire: Transport);
 }
 export declare class ChannelBase {
@@ -18,11 +21,265 @@ export declare class ChannelBase {
     private static defaultAction;
     constructor();
     protected processAction(topic: string, payload: unknown, senderIdentity: ProviderIdentity | OpenFin.ClientIdentity): Promise<unknown>;
+    /**
+     * Register middleware that fires before the action.
+     *
+     * @param func
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     provider.beforeAction((action, payload, identity) => {
+     *         //The payload can be altered here before handling the action.
+     *         payload.received = Date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     client.register('client-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     client.beforeAction((action, payload, identity) => {
+     *         //The payload can be altered here before handling the action.
+     *         payload.received = Date.now();
+     *         return payload;
+     *     });
+     *
+     *     const providerResponse = await client.dispatch('provider-action', { message: 'Hello From the client' });
+     *     console.log(providerResponse);
+     * })();
+     * ```
+     */
     beforeAction(func: ChannelMiddleware): void;
+    /**
+     * Register an error handler. This is called before responding on any error.
+     *
+     * @param func
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload);
+     *         throw new Error('Action error');
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     provider.onError((action, error, identity) => {
+     *         console.log('uncaught Exception in action:', action);
+     *         console.error(error);
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     client.register('client-action', (payload, identity) => {
+     *         console.log(payload);
+     *         throw new Error('Action error');
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     client.onError((action, error, identity) => {
+     *         console.log('uncaught Exception in action:', action);
+     *         console.error(error);
+     *     });
+     * })();
+     * ```
+     */
     onError(func: ErrorMiddleware): void;
+    /**
+     * Register middleware that fires after the action.
+     *
+     * @param func
+     *
+     * @remarks If the action does not return the payload, then the afterAction will not have access to the payload object.
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await provider.afterAction((action, payload, identity) => {
+     *         //the payload can be altered here after handling the action but before sending an acknowledgement.
+     *         payload.sent = date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await client.afterAction((action, payload, identity) => {
+     *         //the payload can be altered here after handling the action but before sending an acknowledgement.
+     *         payload.sent = date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     */
     afterAction(func: ChannelMiddleware): void;
+    /**
+     * Remove an action by action name.
+     *
+     * @param action
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await provider.remove('provider-action');
+     *
+     * })();
+     * ```
+     */
     remove(action: string): void;
+    /**
+     * Registers a default action. This is used any time an action that has not been registered is invoked.
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.setDefaultAction((action, payload, identity) => {
+     *         console.log(`Client with identity ${JSON.stringify(identity)} has attempted to dispatch unregistered action: ${action}.`);
+     *
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.setDefaultAction((action, payload, identity) => {
+     *         console.log(`Provider with identity ${JSON.stringify(identity)} has attempted to dispatch unregistered action: ${action}.`);
+     *
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     * })();
+     * ```
+     * @param func
+     */
     setDefaultAction(func: ChannelMiddleware): void;
+    /**
+     * Register an action to be called by dispatching from any channelClient or channelProvider.
+     *
+     * @param topic
+     * @param listener
+     *
+     * @remarks The return value will be sent back as an acknowledgement to the original caller. You can throw an
+     * error to send a negative-acknowledgement and the error will reject the promise returned to the sender by the
+     * dispatch call.  Once a listener is registered for a particular action, it stays in place receiving and responding
+     * to incoming messages until it is removed.  This messaging mechanism works exactly the same when messages are
+     * dispatched from the provider to a client.  However, the provider has an additional publish method that sends messages
+     * to all connected clients.
+     *
+     * Because multiple clients can share the same `name` and `uuid`, in order to distinguish between individual clients,
+     * the `identity` argument in a provider's registered action 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
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *        console.log('Action dispatched by client: ', identity);
+     *        console.log('Payload sent in dispatch: ', payload);
+     *
+     *        return { echo: payload };
+     *    });
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *        console.log('Action dispatched by client: ', identity);
+     *        console.log('Payload sent in dispatch: ', payload);
+     *
+     *        return { echo: payload };
+     *    });
+     * })();
+     * ```
+     */
     register(topic: string, listener: ChannelAction): boolean;
 }
 export {};