@openfin/core 33.76.27 → 33.76.36

package/src/api/platform/provider.d.ts

@@ -2,8 +2,8 @@ import * as OpenFin from '../../OpenFin';
 type WindowOptionsChangedEvent = OpenFin.WindowEvents.WindowOptionsChangedEvent;
 /**
  * This class handles Platform actions. It does not need to be used directly by developers.
- * However, its methods can be overriden by passing an `overrideCallback` to {@link Platform#init Platform.init}
- * in order to implement custom Platform behavior. (See {@tutorial Platform.init})
+ * However, its methods can be overriden by passing an `overrideCallback` to {@link Platform.PlatformModule.init Platform.init}
+ * in order to implement custom Platform behavior. (See {@link Platform.PlatformModule.init Platform.init})
  *
  * For an overview of Provider customization, see
  * {@link https://developers.openfin.co/docs/platform-customization#section-customizing-platform-behavior}.
@@ -11,25 +11,103 @@ type WindowOptionsChangedEvent = OpenFin.WindowEvents.WindowOptionsChangedEvent;
 export interface PlatformProvider {
     /**
      * Handles requests to create a window in the current platform.
-     * @param { WindowOption } payload Window options for the window to be created.
-     * @param { Identity } [identity] If {@link Platform#createWindow Platform.createWindow} was called, the identity of the caller will be here.
-     * If `createWindow` was called as part of applying a snapshot or creating a view without a target window, `identity` will be undefined.
+     * @param payload Window options for the window to be created.
+     * @param identity If {@link Platform.Platform#createWindow Platform.createWindow} was called, the identity of the caller will be here.
+     *
+     * @remarks If `createWindow` was called as part of applying a snapshot or creating a view without a target window,
+     * `identity` will be undefined.
+     *
+     * Allows overriding a platform's default window creation behavior. All calls to {@link Platform#createWindow Platform.createWindow}
+     * will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async createWindow(options, callerIdentity) {
+     *             if (options.reason === 'tearout') {
+     *                 // Perhaps in our platform, we want tearout windows to have a certain initial context value
+     *                 const customContext = {
+     *                     security: 'STOCK',
+     *                     currentView: 'detailed'
+     *                 }
+     *                 return super.createWindow({ ...options, customContext }, callerIdentity);
+     *             }
+     *             // default behavior for all other creation reasons
+     *             return super.createWindow(options, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     createWindow(options: OpenFin.PlatformWindowCreationOptions, identity?: OpenFin.Identity): Promise<OpenFin.Window>;
     /**
      * Gets the current state of windows and their views and returns a snapshot object containing that info.
-     * @param { undefined } payload Undefined unless you've defined a custom `getSnapshot` protocol.
-     * @param { Identity } identity Identity of the entity that called {@link Platform#getSnapshot Platform.getSnapshot}.
-     * @return { Promise<Snapshot> } Snapshot of current platform state.
+     * @param payload Undefined unless you've defined a custom `getSnapshot` protocol.
+     * @param identity Identity of the entity that called {@link Platform.Platform#getSnapshot Platform.getSnapshot}.
+     * @returns Snapshot of current platform state.
+     *
+     * @remarks Allows overriding a platform's default snapshot behavior. All calls to
+     * {@link Platform#getSnapshot Platform.getSnapshot} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     // Extend default behavior
+     *     class MyOverride extends PlatformProvider {
+     *         async getSnapshot(payload, callerIdentity) {
+     *             // Call super to access vanilla platform behavior
+     *             const snapshot = await super.getSnapshot();
+     *             // Perform any additional logic needed
+     *             const modifiedSnapshot = { ...snapshot, answer: 42 }
+     *             await saveSnapshotToServer(modifiedSnapshot);
+     *             return modifiedSnapshot;
+     *         }
+     *     }
+     *     // Return instance with methods to be consumed by Platform
+     *     return new MyOverride();
+     * };
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function saveSnapshotToServer(snapshot) {
+     *     // Send a snapshot to the server, store it locally somewhere, etc.
+     * }
+     * ```
      */
     getSnapshot(payload: undefined, identity: OpenFin.Identity): Promise<OpenFin.Snapshot>;
     /**
      * **NOTE**: Internal use only. It is not recommended to manage the state of individual views.
      * Gets the current state of a single view and returns an object with the options needed to restore that view as part of a snapshot.
-     * @param { Identity } payload Identity of the view.
-     * @return { Promise<ViewState> }
+     * @param payload Identity of the view.
+     *
      * @internal
      * @experimental
+     *
+     * @remarks Allows overriding a platform's default `getViewSnapshot` behavior. All calls to
+     * {@link Platform#getViewSnapshot Platform.getViewSnapshot} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     // Extend default behavior
+     *     class MyOverride extends PlatformProvider {
+     *         async getViewSnapshot(payload) {
+     *             // Call super to access vanilla platform behavior
+     *             const defaultViewSnapshot = await super.getViewSnapshot(payload);
+     *             // Perform any additional logic needed
+     *             const modifiedSnapshot = { ...defaultViewSnapshot, answer: 42 }
+     *             return modifiedSnapshot;
+     *         }
+     *     }
+     *     // Return instance with methods to be consumed by Platform
+     *     return new MyOverride();
+     * };
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     getViewSnapshot(payload: {
         viewIdentity: OpenFin.Identity;
@@ -38,107 +116,350 @@ export interface PlatformProvider {
      * Called when a snapshot is being applied and some windows in that snapshot would be fully or partially off-screen.
      * Returns an array of windows with modified positions, such that any off-screen windows are positioned in the top left
      * corner of the main monitor.
-     * @param { Snapshot } snapshot The snapshot to be applied.
-     * @param { WindowOptions[] } outOfBoundsWindows An array of WindowOptions for any windows that would be off-screen.
-     * @return { Promise<WindowOptions[]> } An array of WindowOptions with their position modified to fit on screen.
+     * @param snapshot The snapshot to be applied.
+     * @param outOfBoundsWindows An array of WindowOptions for any windows that would be off-screen.
+     * @returns An array of WindowOptions with their position modified to fit on screen.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async positionOutOfBoundsWindows(
+     *             snapshot, // The snapshot currently being applied
+     *             outOfBoundsWindows // An array of options for all windows that would be fully or partially off-screen.
+     *         ) {
+     *             // By default, this function cascades out-of-bounds windows from the top left of the main monitor.
+     *             // Perhaps we wish to instead position all such windows on the bottom right.
+     *
+     *             // First, find the coordinates of the bottom right of the primary monitor
+     *             const {
+     *                 primaryMonitor: {
+     *                     availableRect: { right, bottom }
+     *                 }
+     *             } = await fin.System.getMonitorInfo();
+     *
+     *             // Update the coordinates of each out-of-bounds window to be bottom right
+     *             const newWindows = snapshot.windows.map((windowOptions) => {
+     *                 if (outOfBoundsWindows.find(w => w.name === windowOptions.name)) {
+     *                     // If the window is out of bounds, set a new initial top and left
+     *                     const { defaultHeight, defaultWidth } = windowOptions;
+     *                     return {
+     *                         ...windowOptions,
+     *                         defaultTop: bottom - defaultHeight,
+     *                         defaultLeft: right - defaultWidth
+     *                     }
+     *                 } else {
+     *                     return windowOptions;
+     *                 }
+     *             })
+     *
+     *             // Return all windows with desired bounds
+     *             return newWindows;
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     positionOutOfBoundsWindows(snapshot: OpenFin.Snapshot, outOfBoundsWindows: OpenFin.WindowCreationOptions[]): Promise<OpenFin.WindowCreationOptions[]>;
     /**
      * Handles requests to apply a snapshot to the current Platform.
-     * @param { ApplySnapshotPayload } payload Payload containing the snapshot to be applied, as well as any options.
-     * @param { Identity } [identity] Identity of the entity that called {@link Platform#applySnapshot Platform.applySnapshot}.
+     * @param payload Payload containing the snapshot to be applied, as well as any options.
+     * @param identity Identity of the entity that called {@link Platform.Platform#applySnapshot Platform.applySnapshot}.
      * Undefined if called internally (e.g. when opening the initial snapshot).
-     * @return { Promise<void> }
+     *
+     *
+     * @remarks Allows overriding a platform's default snapshot behavior. All calls to
+     * {@link Platform#applySnapshot Platform.applySnapshot} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (Provider) => {
+     *     class Override extends Provider {
+     *         async applySnapshot(payload, callerIdentity) {
+     *             const { snapshot, options } = payload;
+     *             // Perhaps in our platform, we wish to always use the closeExistingWindows option
+     *             return super.applySnapshot(
+     *                 { snapshot, options: { ...options, closeExistingWindows: true }},
+     *                 callerIdentity
+     *             );
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     applySnapshot(payload: OpenFin.ApplySnapshotPayload, identity?: OpenFin.Identity): Promise<void>;
     /**
      * Closes the current Platform and all child windows and views.
-     * @param { undefined } payload Undefined unless you have implemented a custom quite protocol.
-     * @param { Identity } identity Identity of the entity that called {@link Platform#quit Platform.quit}.
-     * @return { Promise<void> }
+     * @param payload Undefined unless you have implemented a custom quite protocol.
+     * @param identity Identity of the entity that called {@link Platform.Platform#quit Platform.quit}.
+     *
+     *
+     * @remarks Allows overriding a platform's default shutdown behavior. All calls to {@link Platform#quit Platform.quit} will
+     * pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async quit(payload, callerIdentity) {
+     *             // Perhaps in our platform, we wish to take a snapshot and save it somewhere before shutting down
+     *             const snapshot = await this.getSnapshot();
+     *             await saveSnapshot(snapshot);
+     *             return super.quit(payload, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function saveSnapshot(snapshot) {
+     *     // Save the snapshot in localstorage, send to a server, etc.
+     * }
+     * ```
      */
     quit(payload: undefined, identity: OpenFin.Identity): Promise<void>;
     /**
      * Closes a view
-     * @param { CloseViewPayload } payload Specifies the `target` view to be closed.
-     * @param { Identity } identity Identity of the entity that called {@link Platform#closeView Platform.closeView}.
+     * @param payload Specifies the `target` view to be closed.
+     * @param identity Identity of the entity that called {@link Platform.Platform#closeView Platform.closeView}.
+     *
+     * @remarks Allows overriding a platform's default view closing behavior. All calls to
+     * {@link Platform#closeView Platform.closeView} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async closeView(payload, callerIdentity) {
+     *             const { view } = payload;
+     *             // Perhaps in our platform, we want to take a snapshot and save it somewhere before closing certain views.
+     *             if (view.name === 'my-special-view') {
+     *                 const snapshot = await fin.Platform.getCurrentSync().getSnapshot();
+     *                 await saveSnapshot(snapshot);
+     *             }
+     *             return super.closeView(options, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function saveSnapshot(snapshot) {
+     *     // Save the snapshot in localstorage, send to a server, etc.
+     * }
+     * ```
      */
     closeView(payload: OpenFin.CloseViewPayload, identity?: OpenFin.Identity): Promise<any>;
     /**
      * Creates a new view and attaches it to a specified target window.
-     * @param { CreateViewPayload } payload Creation options for the new view.
-     * @param { Identity } identity Identity of the entity that called {@link Platform#createView Platform.createView}.
-     * @return { Promise<void> }
+     * @param payload Creation options for the new view.
+     * @param identity Identity of the entity that called {@link Platform.Platform#createView Platform.createView}.
+     *
      */
     createView(payload: OpenFin.CreateViewPayload, identity: OpenFin.Identity): Promise<OpenFin.View>;
     /** Handles requests to fetch manifests in the current platform.
-     * @param { FetchManifestPayload } payload Payload containing the manifestUrl to be fetched.
-     * @param { Identity } callerIdentity If {@link Platform#fetchManifest Platform.fetchManifest}
+     * @param payload Payload containing the manifestUrl to be fetched.
+     * @param callerIdentity If {@link Platform.Platform#fetchManifest Platform.fetchManifest}
      * was called, the identity of the caller will be here.
-     * If `fetchManifest` was called internally, `callerIdentity` will be the provider's identity.
+     *
+     * @remarks If `fetchManifest` was called internally, `callerIdentity` will be the provider's identity.
+     *
+     * Allows overriding a platform's default behavior when fetching manifests.  Overwriting this call will change how
+     * {@link Platform#launchContentManifest Platform.launchContentManifest} and
+     * {@link https://developers.openfin.co/docs/starting-the-platform-and-launching-content#section-deep-linking-fin-or-fins-link fins links}
+     * fetch manifests.  All calls to {@link Platform#fetchManifest Platform.fetchManifest} will also pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (Provider) => {
+     *     class Override extends Provider {
+     *         async fetchManifest(payload, callerIdentity) {
+     *             const { manifestUrl } = payload;
+     *
+     *             // I want to fetch certain URLs from the platform provider so that renderer-side cookies will be sent
+     *             if (manifestUrl === 'https://www.my-internal-manifest.com') {
+     *                 const manifest = await fetch(manifestUrl);
+     *                 return manifest.json();
+     *             }
+     *
+     *             // Any requests that might be cross-origin should still be sent from the browser process
+     *             return super.fetchManifest(payload);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     fetchManifest(payload: OpenFin.FetchManifestPayload, callerIdentity: OpenFin.Identity): Promise<any>;
     /**
      * Replaces a Platform window's layout with a new layout. Any views that were in the old layout but not the new layout will be destroyed.
-     * @param { ReplaceLayoutPayload } payload Contains the `target` window and an `opts` object with a `layout` property to apply.
-     * @param { Identity } [identity] Identity of the entity that called {@link Platform#replaceLayout Platform.replaceLayout}.
+     * @param payload Contains the `target` window and an `opts` object with a `layout` property to apply.
+     * @param identity Identity of the entity that called {@link PlatformProvider#replaceLayout Platform.replaceLayout}.
      * Undefined if `replaceLayout` is called internally (e.g. while applying a snapshot).
-     * @return { Promise<void> }
+     *
+     *
+     * @remarks Allows overriding a platform's default replaceLayout behavior. All calls to
+     * {@link Platform#replaceLayout Platform.replaceLayout} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async replaceLayout(payload, callerIdentity) {
+     *             // Perhaps in our platform, we wish to save an updated snapshot each time a layout is replaced
+     *             await super.replaceLayout(payload, callerIdentity);
+     *             const updatedSnapshot = await fin.Platform.getCurrentSync().getSnapshot();
+     *             await saveSnapshot(updatedSnapshot);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function saveSnapshot(snapshot) {
+     *     // Save the snapshot in localstorage, send to a server, etc.
+     * }
+     * ```
      */
     replaceLayout(payload: OpenFin.ReplaceLayoutPayload, identity?: OpenFin.Identity): Promise<void>;
     replaceView(payload: OpenFin.ReplaceViewPayload, identity?: OpenFin.Identity): Promise<void>;
+    /**
+     * @internal
+     */
     launchIntoPlatform(payload: OpenFin.LaunchIntoPlatformPayload): Promise<void>;
     /**
      * Handles requests to set a window's context. `target` may be a window or a view.
      * If it is a window, that window's `customContext` will be updated.
      * If it is a view, the `customContext` of that view's current host window will be updated.
-     * @param { SetWindowContextPayload } payload Object containing the requested `context` update,
+     * @param payload Object containing the requested `context` update,
      * the `target`'s identity, and the target's `entityType`.
-     * @param { Identity } [identity] Identity of the entity that called {@link Platform#setWindowContext Platform.setWindowContext}.
+     * @param identity Identity of the entity that called {@link Platform.Platform#setWindowContext Platform.setWindowContext}.
      * Undefined if `setWindowContext` is called internally (e.g. while applying a snapshot).
-     * @return { Promise<any> } The new context.
+     * @returns The new context.
+     *
+     * @remarks Allows overriding a platform's default setWindowContext behavior.
+     * All calls to {@link Platform#setWindowContext Platform.setWindowContext} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async setWindowContext(payload, callerIdentity) {
+     *             // Perhaps in our platform, we wish to only take context updates from windows
+     *             // and ignore updates sent from views.
+     *             if (payload.entityType === 'view') {
+     *                 throw new Error('Updating window context from a view is not permitted in this platform.');
+     *             }
+     *             return super.setWindowContext(payload, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     setWindowContext(payload: OpenFin.SetWindowContextPayload, identity?: OpenFin.Identity): Promise<any>;
     /**
      * Handles requests to get a window's context. `target` may be a window or a view.
      * If it is a window, that window's `customContext` will be returned.
      * If it is a view, the `customContext` of that view's current host window will be returned.
-     * @param { GetWindowContextPayload } payload Object containing the requested `context` update,
+     * @param payload Object containing the requested `context` update,
      * the `target`'s identity, and the target's `entityType`.
-     * @param { Identity } [identity] Identity of the entity that called {@link Platform#getWindowContext Platform.getWindowContext}.
+     * @param identity Identity of the entity that called {@link Platform.Platform#getWindowContext Platform.getWindowContext}.
      * Undefined when `getWindowContext` is called internally
      * (e.g. when getting a window's context for the purpose of raising a "host-context-changed" event on a reparented view).
-     * @return { Promise<any> } The new context.
+     * @returns The new context.
+     *
+     * @remarks Allows overriding a platform's default getWindowContext behavior. All calls to
+     * {@link Platform#getWindowContext Platform.getWindowContext} will pass through the override.
+     *
+     * @example
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async getWindowContext(payload, callerIdentity) {
+     *             // Perhaps in our platform, we wish to make window context available only to views from a given domain.
+     *             const { entityType } = callerIdentity;
+     *             if (entityType === 'view') {
+     *                 const { url } = await fin.View.wrapSync(callerIdentity).getInfo();
+     *                 if (!url.startsWith('https://my.trusted-domain.com')) {
+     *                     throw new Error('Only apps from trusted domains may use window context in this platform.');
+     *                 }
+     *             }
+     *             return super.getWindowContext(payload, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     getWindowContext(payload: OpenFin.GetWindowContextPayload, identity?: OpenFin.Identity): Promise<any>;
     /**
      * Called when a window's `customContext` is updated. Responsible for raising the `host-context-updated` event on that window's child views.
-     * @param { WindowOptionsChangedEvent<'window', 'options-changed'> } payload The event payload for the window whose context has changed.
+     * @param payload The event payload for the window whose context has changed.
      * The new context will be contained as `payload.diff.customContext.newVal`.
-     * @return { Promise<HostContextChangedPayload> } The event that it raised.
+     * @returns The event that it raised.
      */
     onWindowContextUpdated(payload: WindowOptionsChangedEvent): Promise<OpenFin.HostContextChangedPayload | undefined>;
     /**
      * Closes a Window.
      * By default it will fire any before unload handler set by a View in the Window.
      * This can be disabled by setting skipBeforeUnload in the options object of the payload.
-     * This method is called by {@link Platform#closeWindow Platform.closeWindow}.
-     * @param {CloseWindowPayload} payload Object that contains the Window Identity and related options.
-     * @param {Identity} callerIdentity
-     * @returns {Promise<void>}
+     * This method is called by {@link Platform.Platform#closeWindow Platform.closeWindow}.
+     * @param payload Object that contains the Window Identity and related options.
+     * @param callerIdentity
+     *
+     *
+     * @remarks This method calls a number of Platform Provider methods:
+     *
+     * * {@link PlatformProvider#getViewsForWindowClose}
+     * * {@link PlatformProvider#checkViewsForPreventUnload}
+     * * {@link PlatformProvider#getUserDecisionForBeforeUnload}
+     * * {@link PlatformProvider#handleViewsAndWindowClose}
+     *
+     *
+     * @example
+     *
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async closeWindow(payload, callerIdentity) {
+     *             const { windowId: { uuid, name }, options: { skipBeforeUnload } } = payload;
+     *             console.log(`${uuid}/${name} is closing and skipBeforeUnload is set to: ${skipBeforeUnload}`);
+     *             return super.closeWindow(payload, callerIdentity);
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     * ```
      */
     closeWindow(payload: OpenFin.CloseWindowPayload, callerIdentity: OpenFin.Identity): Promise<void>;
     /**
      * Gets all the Views attached to a Window that should close along with it. This is meant to be overridable
      * in the case where you want to return other Views that may not be attached to the Window that is closing.
      * @param winId Identity of the Window that is closing
-     * @returns { Promise<View> }
+     *
      */
     getViewsForWindowClose(windowId: OpenFin.Identity): Promise<OpenFin.View[]>;
     /**
      * It takes in an array of Views and returns an object specifying which of them are trying to prevent an unload and which are not.
-     * @param {View[]} views Array of Views
-     * @returns { Promise<ViewStatuses> }
+     * @param views Array of Views
+     *
      */
     checkViewsForPreventUnload(views: OpenFin.View[]): Promise<OpenFin.ViewStatuses>;
     /**
@@ -146,17 +467,43 @@ export interface PlatformProvider {
      * Called in {@link PlatformProvider#closeWindow PlatformProvider.closeWindow}.
      * Normally you would use this method to show a dialog indicating that there are Views that are trying to prevent an unload.
      * By default it will always return all Views passed into it as meaning to close.
-     * @param {ViewsPreventingUnloadPayload} payload
-     * @tutorial PlatformProvider.getUserDecisionForBeforeUnload
-     * @returns {Promise<BeforeUnloadUserDecision>}
+     * @param payload
+     * @example
+     *
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async getUserDecisionForBeforeUnload(payload, callerIdentity) {
+     *             const { windowShouldClose, viewsPreventingUnload, viewsNotPreventingUnload, windowId, closeType } = payload;
+     *
+     *             // launch dialog and wait for user response
+     *             const continueWithClose = await showDialog(viewsPreventingUnload, windowId, closeType);
+     *
+     *             if (continueWithClose) {
+     *                 return { windowShouldClose, viewsToClose: [...viewsNotPreventingUnload, ...viewsPreventingUnload] };
+     *             } else {
+     *                 return { windowShouldClose: false, viewsToClose: [] };
+     *             }
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function showDialog(viewsPreventingUnload, windowId, closeType) {
+     *     // Show a dialog and await for user response
+     * }
+     * ```
+     *
      */
     getUserDecisionForBeforeUnload(payload: OpenFin.ViewsPreventingUnloadPayload): Promise<OpenFin.BeforeUnloadUserDecision>;
     /**
      * Handles the closing of a Window and/or its Views. Called in {@link PlatformProvider#closeWindow PlatformProvider.closeWindow}.
      * The return of {@link PlatformProvider#getUserDecisionForBeforeUnload PlatformProvider.getUserDecisionForBeforeUnload} is passed into this method.
-     * @param {Identity} winId Identity of the Window
-     * @param {BeforeUnloadUserDecision} userDecision Decision object
-     * @returns {Promise<void>}
+     * @param winId Identity of the Window
+     * @param userDecision Decision object
+     *
      */
     handleViewsAndWindowClose(windowId: OpenFin.Identity, userDecision: OpenFin.BeforeUnloadUserDecision): Promise<void>;
 }

package/src/api/snapshot-source/Factory.d.ts

@@ -1,37 +1,52 @@
 import type * as OpenFin from '../../OpenFin';
 import { Base } from '../base';
 import { SnapshotSource } from './Instance';
-/**
- * @REMOVED
- * @typedef { object } SnapshotProvider
- * @property {getSnapshot} [getSnapshot]
- * @property {applySnapshot} [applySnapshot]
- */
-/**
- * @lends SnapshotSource
- */
 export default class SnapshotSourceModule extends Base {
     /**
      * Initializes a SnapshotSource with the getSnapshot and applySnapshot methods defined.
-     * @param { SnapshotProvider } provider
-     * @return { Promise<void> }
-     * @tutorial SnapshotSource.init
+     * @param provider
+     *
+     * @example
+     * ```js
+     * const snapshotProvider = {
+     *     async getSnapshot() {
+     *       const bounds = await fin.me.getBounds();
+     *       return bounds;
+     *      },
+     *     async applySnapshot(snapshot) {
+     *       await fin.me.setBounds(snapshot);
+     *       return undefined;
+     *     }
+     * }
+     *
+     * await fin.SnapshotSource.init(snapshotProvider);
+     * ```
      * @static
      */
     init<T = any>(provider: OpenFin.SnapshotProvider<T>): Promise<void>;
     /**
      * Synchronously returns a SnapshotSource object that represents the current SnapshotSource.
-     * @param { Identity } identity
-     * @return { SnapshotSource }
-     * @tutorial SnapshotSource.wrapSync
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const snapshotSource = fin.SnapshotSource.wrapSync(fin.me);
+     * // Use wrapped instance's getSnapshot method, e.g.:
+     * const snapshot = await snapshotSource.getSnapshot();
+     * ```
      * @static
      */
     wrapSync(identity: OpenFin.ApplicationIdentity): SnapshotSource;
     /**
      * Asynchronously returns a SnapshotSource object that represents the current SnapshotSource.
-     * @param { Identity } identity
-     * @return { Promise.<SnapshotSource> }
-     * @tutorial SnapshotSource.wrap
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const snapshotSource = await fin.SnapshotSource.wrap(fin.me);
+     * // Use wrapped instance's getSnapshot method, e.g.:
+     * const snapshot = await snapshotSource.getSnapshot();
+     * ```
      * @static
      */
     wrap(identity: OpenFin.ApplicationIdentity): Promise<SnapshotSource>;