@openfin/core 33.76.31 → 33.76.36

package/src/api/interop/fdc3/fdc3-2.0.js

@@ -70,16 +70,16 @@ const PrivateChannelClient_1 = require("./PrivateChannelClient");
 /**
  * @callback ContextHandler
  * @variation 2
- * @param { Context } context
- * @param { ContextMetadata } [contextMetadata]
- * @returns { void }
+ * @param context
+ * @param contextMetadata
+ *
  */
 /**
  * @callback IntentHandler
  * @variation 2
- * @param { Context } context
- * @param { ContextMetadata } [contextMetadata]
- * @returns { Promise<IntentResult> | void }
+ * @param context
+ * @param contextMetadata
+ *
  */
 /**
  * @typedef { object } IntentMetadata
@@ -97,7 +97,7 @@ const PrivateChannelClient_1 = require("./PrivateChannelClient");
 /**
  * @name getResult
  * @function
- * @returns { Promise<IntentResult> }
+ *
  */
 /**
  * @typedef { object } IntentResolution
@@ -123,11 +123,8 @@ const PrivateChannelClient_1 = require("./PrivateChannelClient");
  * @property { function } disconnect
  */
 /**
- * @class
- * @alias fdc3v2
  * @version 2.0
- * @hideconstructor
- * @desc The FDC3 Client Library provides a set APIs to be used for FDC3 compliance,
+ * The FDC3 Client Library provides a set APIs to be used for FDC3 compliance,
  * while using our Interop API under the hood. In order to use this set of APIs
  * you will need to set up your own {@link InteropBroker InteropBroker} or use a Platform application, which does the setup for you. Refer to our documentation on
  * our {@link https://developers.openfin.co/of-docs/docs/enable-context-sharing Interop API}.
@@ -168,9 +165,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Launches an app, specified via an AppIdentifier object.
-     * @param { AppIdentifier | TargetApp } app
-     * @param { Context } [context]
-     * @returns { Promise<AppIdentifier> }
+     * @param app
+     * @param context
+     *
      * @tutorial fdc3.open
      */
     async open(app, context) {
@@ -181,8 +178,8 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Find all the available instances for a particular application.
-     * @param { AppIdentifier } app
-     * @returns { Promise<Array<AppIdentifier>> }
+     * @param app
+     *
      * @tutorial fdc3v2.findInstances
      */
     async findInstances(app) {
@@ -199,8 +196,8 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Retrieves the AppMetadata for an AppIdentifier, which provides additional metadata (such as icons, a title and description) from the App Directory record for the application, that may be used for display purposes.
-     * @param { AppIdentifier } app
-     * @returns { Promise<AppMetadata(2)> }
+     * @param app
+     *
      * @tutorial fdc3v2.getAppMetadata
      */
     async getAppMetadata(app) {
@@ -217,8 +214,8 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Broadcasts a context for the channel of the current entity.
-     * @param { Context } context - New context to set.
-     * @returns { Promise<void> }
+     * @param context - New context to set.
+     *
      * @tutorial fdc3.broadcast
      */
     async broadcast(context) {
@@ -226,9 +223,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Add a context handler for incoming context. If an entity is part of a context group, and then sets its context handler, it will receive all of its declared contexts. If you wish to listen for all incoming contexts, pass `null` for the contextType argument.
-     * @param { string | null } contextType
-     * @param { ContextHandler(2) } handler
-     * @returns { Listener }
+     * @param contextType
+     * @param handler
+     *
      * @tutorial fdc3.addContextListener
      */
     async addContextListener(contextType, handler) {
@@ -256,10 +253,10 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Find out more information about a particular intent by passing its name, and optionally its context and resultType.
-     * @param { string } intent Name of the Intent
-     * @param { Context } [context] Context
-     * @param { string } [resultType] The type of result returned for any intent specified during resolution.
-     * @returns { Promise<AppIntent(2)> }
+     * @param intent Name of the Intent
+     * @param context Context
+     * @param resultType The type of result returned for any intent specified during resolution.
+     *
      * @tutorial fdc3.findIntent
      */
     async findIntent(intent, context, resultType) {
@@ -276,9 +273,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Find all the available intents for a particular context.
-     * @param { Context } context
-     * @param { string } [resultType] The type of result returned for any intent specified during resolution.
-     * @returns { Promise<Array<AppIntent(2)>> }
+     * @param context
+     * @param resultType The type of result returned for any intent specified during resolution.
+     *
      * @tutorial fdc3v2.findIntentsByContext
      */
     async findIntentsByContext(context, resultType) {
@@ -296,10 +293,10 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Raises a specific intent for resolution against apps registered with the desktop agent.
-     * @param { string } intent Name of the Intent
-     * @param { Context } context Context associated with the Intent
-     * @param { AppIdentifier | TargetApp } [app]
-     * @returns { Promise<IntentResolution(2)> }
+     * @param intent Name of the Intent
+     * @param context Context associated with the Intent
+     * @param app
+     *
      * @tutorial fdc3v2.raiseIntent
      */
     async raiseIntent(intent, context, app) {
@@ -319,9 +316,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Finds and raises an intent against apps registered with the desktop agent based purely on the type of the context data.
-     * @param { Context } context Context associated with the Intent
-     * @param { AppIdentifier | TargetApp } [app]
-     * @returns { Promise<IntentResolution(2)> }
+     * @param context Context associated with the Intent
+     * @param app
+     *
      * @tutorial fdc3v2.raiseIntentForContext
      */
     async raiseIntentForContext(context, app) {
@@ -342,9 +339,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Adds a listener for incoming intents.
-     * @param { string } intent  Name of the Intent
-     * @param { IntentHandler(2) } handler A callback that handles a context event and may return a promise of a Context or Channel object to be returned to the application that raised the intent.
-     * @returns { Promise<Listener> }
+     * @param intent  Name of the Intent
+     * @param handler A callback that handles a context event and may return a promise of a Context or Channel object to be returned to the application that raised the intent.
+     *
      * @tutorial fdc3.addIntentListener
      */
     async addIntentListener(intent, handler) {
@@ -384,7 +381,7 @@ class Fdc3Module2 extends base_1.Base {
     /**
      * Returns a Channel object for the specified channel, creating it as an App Channel if it does not exist.
      * @param channelId
-     * @returns { Promise<Channel> }
+     *
      * @tutorial fdc3.getOrCreateChannel
      */
     async getOrCreateChannel(channelId) {
@@ -392,7 +389,7 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Returns a Channel with an auto-generated identity that is intended for private communication between applications. Primarily used to create channels that will be returned to other applications via an IntentResolution for a raised intent.
-     * @returns { Promise<PrivateChannel> }
+     *
      * @tutorial fdc3v2.createPrivateChannel
      */
     async createPrivateChannel() {
@@ -404,7 +401,7 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Retrieves a list of the User Channels available for the app to join.
-     * @returns { Promise<Channel[]>}
+     *
      * @tutorial fdc3v2.getUserChannels
      */
     async getUserChannels() {
@@ -417,7 +414,7 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Retrieves a list of the User Channels available for the app to join.
-     * @returns { Promise<Channel[]>}
+     *
      * @deprecated Please use {@link fdc3.getUserChannels fdc3.getUserChannels} instead
      * @tutorial fdc3.getSystemChannels
      */
@@ -427,8 +424,8 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Join an app to a specified User channel.
-     * @param { string } channelId Channel name
-     * @returns { Promise<void> }
+     * @param channelId Channel name
+     *
      * @tutorial fdc3v2.joinUserChannel
      */
     async joinUserChannel(channelId) {
@@ -436,9 +433,9 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Join an app to a specified User channel.
-     * @param { string } channelId Channel name
+     * @param channelId Channel name
      * @deprecated Please use {@link fdc3.joinUserChannel fdc3.joinUserChannel} instead
-     * @returns { Promise<void> }
+     *
      * @tutorial fdc3.joinChannel
      */
     async joinChannel(channelId) {
@@ -447,7 +444,7 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Returns the Channel object for the current User channel membership
-     * @returns { Promise<FDC3.Channel | null> }
+     *
      * @tutorial fdc3.getCurrentChannel
      */
     async getCurrentChannel() {
@@ -463,7 +460,7 @@ class Fdc3Module2 extends base_1.Base {
     }
     /**
      * Removes the app from any User channel membership.
-     * @returns { Promise<void> }
+     *
      * @tutorial fdc3.leaveCurrentChannel
      */
     async leaveCurrentChannel() {
@@ -472,7 +469,7 @@ class Fdc3Module2 extends base_1.Base {
     /**
      * Retrieves information about the FDC3 implementation, including the supported version of the FDC3 specification, the name of the provider of the implementation, its own version number, details of whether optional API features are implemented and the metadata of the calling application according to the desktop agent.
      * fdc3HandleGetInfo must be overridden in the InteropBroker so that the ImplementationMetadata will have the appMetadata info.
-     * @returns { Promise<ImplementationMetadata(2)> }
+     *
      * @tutorial fdc3v2.getInfo
      */
     async getInfo() {

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

@@ -1,3 +1,11 @@
+/**
+ * Entry point for the OpenFin Interop namespace.
+ *
+ * "InteropModule" contains static members of the `Interop` namespace (available under `fin.Interop`), while `InteropClient` and
+ * `InteropBroker` document instances of their respective classes.
+ *
+ * @packageDocumentation
+ */
 import InteropModule from './Factory';
 export default InteropModule;
 export * from './InteropClient';

package/src/api/interop/index.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Entry point for the OpenFin Interop namespace.
+ *
+ * "InteropModule" contains static members of the `Interop` namespace (available under `fin.Interop`), while `InteropClient` and
+ * `InteropBroker` document instances of their respective classes.
+ *
+ * @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/platform/Factory.d.ts

@@ -3,111 +3,167 @@ import { Transport } from '../../transport/transport';
 import { Base } from '../base';
 import { LayoutModule } from './layout/index';
 type Channel = OpenFin.Fin['InterApplicationBus']['Channel'];
-/**
- * @PORTED
- * InitPlatformOptions interface
- * @typedef { object } InitPlatformOptions
- * @property { OverrideCallback } [overrideCallback] a callback function that can be used to extend or replace default Provider behavior.
- */
-/**
- * @PORTED
- * @typedef { same | different } ProcessAffinityStrategy
- * @summary Strategy to place views that share a domain into different process affinities or the same process affinity.
- * @property { string } same views in the same domain will have the same process affinity.
- * @property { string } different views in the same domain will have different process affinities.
- */
-/**
- * @PORTED
- * @typedef { object } PlatformOptions
- * @summary The options object required by {@link Platform#start Platform.start}
- * Any {@link ApplicationOptions Application option} is also a valid platform option
- * @property {Array.<Object>} [commands] Configuration for keyboard commands.
- * For details and usage, see [Using Keyboard Commands]{@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands}.
- * @property {DefaultWindowOptions} [defaultWindowOptions] Default window options apply to all platform windows.
- * @property {View~options} [defaultViewOptions] Default view options apply to all platform views.
- * @property {ProcessAffinityStrategy} [viewProcessAffinityStrategy] 'same' | 'different'.
- */
-/**
- * @PORTED
- * @typedef { object } DefaultWindowOptions
- * @summary Default window options apply to all platform windows.
- * Any {@link Window~options Window option} is also a valid Default Window option
- * used by default in any window that is created in the current platform's scope.
- * Individual window options will override these defaults.
- * @property {string} [stylesheetUrl]
- * Specify a path of a custom CSS file to be injected to all of the platform's windows.
- * _note_: this option is only applied to windows that use the Default OpenFin Window.
- * Windows with a specified url (Custom Windows) will not be affected by this option.
- */
-/**
- * @DELETED
- * Snapshot interface
- * @typedef { object } Snapshot
- * @property { WindowOption[] } windows The array of window options objects
- */
-/**
- * @lends Platform
- */
 export default class PlatformModule extends Base {
     private _channel;
     Layout: LayoutModule;
+    /**
+     * @internal
+     */
     constructor(wire: Transport, channel: Channel);
     /**
      * Initializes a Platform. Must be called from the Provider when using a custom provider.
-     * @param { InitPlatformOptions } [options] - platform options including a callback function that can be used to extend or replace
+     * @param options - platform options including a callback function that can be used to extend or replace
      * default Provider behavior.
-     * @return {Promise.<void>}
-     * @tutorial Platform.init
+     *
+     * @remarks Must be called from the Provider when using a custom provider.
+     *
+     * @example
+     *
+     * ```js
+     * // From Provider context
+     * await fin.Platform.init();
+     * // Platform API is now hooked up and windows contained in the manifest snapshot are open.
+     * ```
+     *
+     * `Platform.init` accepts an options object that can contain a callback function which can be used to extend or
+     * replace default Provider behavior. As an argument, this function will receive the `Provider` class, which is
+     * used to handle Platform actions. The function must return an object with methods to handle Platform API actions.
+     * The recommended approach is to extend the `Provider` class, overriding the methods you wish to alter, and return an
+     * instance of your subclass:
+     *
+     * ```js
+     * const overrideCallback = async (PlatformProvider) => {
+     *     // Actions can be performed before initialization.
+     *     // e.g. we might authenticate a user, set up a Channel, etc before initializing the Platform.
+     *     const { manifestUrl } = await fin.Application.getCurrentSync().getInfo();
+     *
+     *     // Extend or replace default PlatformProvider behavior by extending the PlatformProvider class.
+     *     class MyOverride extends PlatformProvider {
+     *         // Default behavior can be changed by implementing methods with the same names as those used by the default PlatformProvider.
+     *         async getSnapshot() {
+     *             // Since we are extending the class, we can call `super` methods to access default behavior.
+     *             const snapshot = await super.getSnapshot();
+     *             // But we can modify return values.
+     *             return { ...snapshot, answer: 42, manifestUrl };
+     *         }
+     *         async replaceLayout({ opts, target }) {
+     *             // To disable an API method, overwrite with a noop function.
+     *             return;
+     *         }
+     *     }
+     *     // Return instance with methods to be consumed by Platform.
+     *     // The returned object must implement all methods of the PlatformProvider class.
+     *     // By extending the class, we can simply inherit methods we do not wish to alter.
+     *     return new MyOverride();
+     * };
+     *
+     * fin.Platform.init({overrideCallback});
+     * ```
      * @experimental
      * @static
      */
     init(options?: OpenFin.InitPlatformOptions): Promise<void>;
     /**
      * Asynchronously returns a Platform object that represents an existing platform.
-     * @param { Identity } identity
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.wrap
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const { identity } = fin.me;
+     * const platform = await fin.Platform.wrap(identity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     wrap(identity: OpenFin.ApplicationIdentity): Promise<OpenFin.Platform>;
     /**
      * Synchronously returns a Platform object that represents an existing platform.
-     * @param { Identity } identity
-     * @return {Platform}
-     * @tutorial Platform.wrapSync
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const { identity } = fin.me;
+     * const platform = fin.Platform.wrapSync(identity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     wrapSync(identity: OpenFin.ApplicationIdentity): OpenFin.Platform;
     /**
      * Asynchronously returns a Platform object that represents the current platform.
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.getCurrent
+     *
+     * @example
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     getCurrent(): Promise<OpenFin.Platform>;
     /**
      * Synchronously returns a Platform object that represents the current platform.
-     * @return {Platform}
-     * @tutorial Platform.getCurrentSync
+     *
+     * @example
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     getCurrentSync(): OpenFin.Platform;
     /**
      * Creates and starts a Platform and returns a wrapped and running Platform instance. The wrapped Platform methods can
      * be used to launch content into the platform.  Promise will reject if the platform is already running.
-     * @param { PlatformOptions } platformOptions
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.start
+     * @param platformOptions
+     *
+     * @example
+     * ```js
+     * try {
+     *     const platform = await fin.Platform.start({
+     *         uuid: 'platform-1',
+     *         autoShow: false,
+     *         defaultWindowOptions: {
+     *             stylesheetUrl: 'css-sheet-url',
+     *             cornerRounding: {
+     *                 height: 10,
+     *                 width: 10
+     *             }
+     *         }
+     *     });
+     *     console.log('Platform is running', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * ```
      * @static
      */
     start(platformOptions: OpenFin.PlatformOptions): Promise<OpenFin.Platform>;
     /**
      * Retrieves platforms's manifest and returns a wrapped and running Platform.  If there is a snapshot in the manifest,
      * it will be launched into the platform.
-     * @param {string} manifestUrl - The URL of platform's manifest.
-     * @param {RvmLaunchOptions} [opts] - Parameters that the RVM will use.
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.startFromManifest
+     * @param manifestUrl - The URL of platform's manifest.
+     * @param opts - Parameters that the RVM will use.
+     *
+     * @example
+     * ```js
+     * try {
+     *     const platform = await fin.Platform.startFromManifest('https://openfin.github.io/golden-prototype/public.json');
+     *     console.log('Platform is running, wrapped platform: ', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * // For a local manifest file:
+     * try {
+     *     const platform = await fin.Platform.startFromManifest('file:///C:/somefolder/app.json');
+     *     console.log('Platform is running, wrapped platform: ', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * ```
      * @static
      */
     startFromManifest(manifestUrl: string, opts?: OpenFin.RvmLaunchOptions): Promise<OpenFin.Platform>;