@openfin/workspace 13.1.5 → 14.0.14

package/README.md

@@ -4,20 +4,20 @@ The Workspace Client APIs enable custom integrations with OpenFin Workspace.
 
 ## Prerequisites
 
--   [Node.js](https://nodejs.org/en/) v16.0.0 or higher
--   [npm](https://www.npmjs.com/)
+- [Node.js](https://nodejs.org/en/) v16.0.0 or higher
+- [npm](https://www.npmjs.com/)
 
 ## Install
 
 With npm:
 
-```
+```sh
 $ npm i @openfin/workspace@latest
 ```
 
 With yarn:
 
-```
+```sh
 $ yarn global add @openfin/workspace
 ```
 
@@ -27,8 +27,8 @@ Prior to using Workspace, a Workspace Platform must be initialized.
 
 ### Home API
 
--   [Overview](https://developers.openfin.co/of-docs/docs/cli-providers)
--   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/home.html)
+- [Overview](https://developers.openfin.co/of-docs/docs/cli-providers)
+- [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/home.html)
 
 ```ts
 import Home, CLIProvider from '@openfin/workspace';
@@ -64,8 +64,8 @@ searchButton.addEventListener('click', () => {
 
 ### Storefront API
 
--   [Overview](https://developers.openfin.co/of-docs/docs/provide-storefront-content)
--   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/store.html)
+- [Overview](https://developers.openfin.co/of-docs/docs/provide-storefront-content)
+- [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/store.html)
 
 ```ts
 import { Storefront, StorefrontProvider } from "@openfin/workspace";
@@ -97,8 +97,8 @@ await Storefront.show();
 
 ### Dock API
 
--   [Overview](https://developers.openfin.co/of-docs/docs/dock-overview)
--   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/dock.html)
+- [Overview](https://developers.openfin.co/of-docs/docs/dock-overview)
+- [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/dock.html)
 
 ```ts
 const provider: DockProvider = {
@@ -154,7 +154,7 @@ await Dock.show();
 
 ## For more information
 
--   [Developer guide](https://developers.openfin.co/of-docs/docs/overview-of-workspace).
--   [API reference](https://developer.openfin.co/workspace/docs/api/latest/index.html).
--   See the [workspace-starter](https://github.com/built-on-openfin/workspace-starter) project for example code.
--   See the [versions page](https://developer.openfin.co/versions/#/?product=Workspace) for a list of all available versions.
+- [Developer guide](https://developers.openfin.co/of-docs/docs/overview-of-workspace).
+- [API reference](https://developer.openfin.co/workspace/docs/api/latest/index.html).
+- See the [workspace-starter](https://github.com/built-on-openfin/workspace-starter) project for example code.
+- See the [versions page](https://developer.openfin.co/versions/#/?product=Workspace) for a list of all available versions.

package/client-api/src/dock.d.ts

@@ -2,9 +2,23 @@ import type { DockProvider } from './shapes/dock';
 import { DockProviderRegistration } from './shapes/dock';
 export * from './shapes/dock';
 /**
- * Registers a Dock provider
- * @returns promise - invokes action
+ * API function to register a Dock provider.
+ *
+ * @remarks A Workspace Platform must be initialized.
+ *
+ * @throws An error if the Workspace Platform is not initialized.
+ * @throws An error if a Dock provider for this Workspace Platform is already registered.
+ * @throws An error if the Dock provider configuration contains buttons with duplicate ids. If no ids are specified, the buttons will be assigned ids automatically.
+ *
+ * @param provider - The Dock provider to register.
+ *
+ * @returns A promise that resolves with a `DockProviderRegistration` object once the Dock provider is successfully registered. This contains the client API version, Workspace Version and a function to update the Dock provider configuration.
+ *
+ * @example Register a Dock provider with a single button.
+ *
  * ```ts
+ * import { Dock, type DockProvider } from '@openfin/workspace';
+ *
  * const provider: DockProvider = {
  *      id: 'provider-id',
  *      title: 'Sample Dock',
@@ -21,36 +35,58 @@ export * from './shapes/dock';
  * };
  *
  * await Dock.register(provider)
+ *
+ * await Dock.show()
  * ```
  */
 export declare const register: (provider: DockProvider) => Promise<DockProviderRegistration>;
 /**
- * API function to Deregister a Dock provider
+ * API function to deregister a Dock provider.
+ *
+ * @remarks A Workspace Platform must be initialized, and the Dock provider must be registered for this function to take effect.
+ *
+ * @throws an error if the provider is not registered.
  *
- * @returns a promise that resolves once the dock is deregistered
+ * @returns a promise that resolves once the Dock provider is successfully deregistered.
+ *
+ * @example Deregister a Dock provider.
  *
  * ```ts
+ * import { Dock } from '@openfin/workspace';
+ *
  * await Dock.deregister();
  * ```
  */
 export declare const deregister: () => Promise<void>;
 /**
- * API function to minimize Dock
+ * API function to show the Dock UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Dock provider must be registered for this function to take effect.
  *
- * @returns a promise that resolves once the dock is minimized
+ * @returns a promise that resolves once the Dock UI is hidden
+ *
+ * @example Show a Dock provider.
  *
  * ```ts
- * await Dock.minimize();
+ * import { Dock } from '@openfin/workspace';
+ *
+ * await Dock.show();
  * ```
  */
 export declare const minimize: () => Promise<void>;
 /**
- * API function to show Dock
+ * API function to hide the Dock UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Dock provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Dock UI is hidden
  *
- * @returns a promise that resolves once the dock is shown
+ * @example Hide a Dock provider.
  *
  * ```ts
- * await Dock.show();
+ * import { Dock } from '@openfin/workspace';
+ *
+ * await Dock.hide();
  * ```
  */
 export declare const show: () => Promise<void>;

package/client-api/src/home.d.ts

@@ -2,20 +2,91 @@ import type { CLIProvider, HomeProvider } from './shapes/home';
 import { HomeRegistration } from './shapes/home';
 export * from './shapes/home';
 /**
- * Register a provider that can return search results to Home.
- * @param provider the Home provider implementation.
+ * API function to register a Home provider.
+ *
+ * @remarks A Workspace Platform must be initialized.
+ *
+ * @throws An error if the Workspace Platform is not initialized.
+ * @throws An error if a Home provider with the same `id` is already registered.
+ *
+ * @param provider - The Home provider to register.
+ *
+ * @returns A promise that resolves with a `HomeRegistration` object once the Dock provider is successfully registered. This contains the client API version, Workspace Version and a function to set the search query.
+ *
+ * @example **Register a Basic Home provider**
+ *
+ * ```ts
+ * import { Home, type HomeProvider } from '@openfin/workspace';
+ *
+ * const provider: HomeProvider = {
+ *     title: "My Home Provider"
+ *     inputPlaceholder: "Search with My Home Provider",
+ *     icon: "https://www.openfin.co/favicon-32x32.png",
+ *     listTitle: "My Home Provider Results",
+ *     logoUrl: "https://www.openfin.co/favicon-32x32.png",
+ *     id: "my-home-provider",
+ *     onUserInput: (req, res) => {
+ *         console.log(req.query);
+ *         return { results: [], context: { filters: [] } }
+ *     },
+ *     dispatchFocusEvents: true,
+ * };
+ *
+ * await Home.register(provider)
+ *
+ * await Home.show()
+ * ```
  */
 export declare const register: (provider: HomeProvider | CLIProvider) => Promise<HomeRegistration>;
 /**
- * Deregister a provider.
+ * API function to deregister a Home provider.
+ *
+ * @remarks A Workspace Platform must be initialized, and the Home provider must be registered for this function to take effect.
+ *
+ * @throws an error if the provider is not registered.
+ *
  * @param providerId the Home provider ID.
+ *
+ * @returns a promise that resolves once the Home provider is successfully deregistered.
+ *
+ * @example Deregister a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.deregister('my-home-provider');
+ * ```
  */
 export declare const deregister: (providerId: string) => Promise<void>;
 /**
- * Show the Home UI.
+ * API function to show the Home UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Home provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Home UI is hidden
+ *
+ * @example Show a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.show();
+ * ```
  */
 export declare function show(): Promise<void>;
 /**
- * Hide the Home UI.
+ * API function to hide the Home UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Home provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Home UI is hidden
+ *
+ * @example Hide a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.hide();
+ * ```
  */
 export declare function hide(): Promise<void>;

package/client-api/src/home.test.d.ts

@@ -1 +1 @@
-export {};
+import '@common/test/fin-mocks';

package/client-api/src/index.d.ts

@@ -9,22 +9,22 @@ export * from './shapes/home';
 export * from './shapes/store';
 export * from './shapes/dock';
 /**
-  Namespace for Storefront integrations.
-*/
+ * Namespace for Storefront integrations.
+ */
 export { StorefrontAPI as Storefront };
 /**
-  Namespace for Home integrations.
-*/
+ * Namespace for Home integrations.
+ */
 export { HomeAPI as Home };
 /**
-  Namespace for Dock integrations.
-*/
+ * Namespace for Dock integrations.
+ */
 export { DockAPI as Dock };
 /**
-  Namespace for Legacy integrations.
-*/
+ * Namespace for Legacy integrations.
+ */
 export { LegacyAPI as Legacy };
 /**
-  Namespace for Microflows integrations.
-*/
+ * Namespace for Microflows integrations.
+ */
 export { IntegrationsAPI as Integrations };

package/client-api/src/integrations/microsoft.shapes.d.ts

@@ -148,17 +148,17 @@ export interface Microsoft365IntegrationConfig extends WorkflowIntegrationConfig
 /**
  * @internal
  */
-declare type MicrosoftGraphAPIHttpMethod = 'GET' | 'HEAD' | 'PATCH' | 'POST' | 'PUT' | 'DELETE';
+type MicrosoftGraphAPIHttpMethod = 'GET' | 'HEAD' | 'PATCH' | 'POST' | 'PUT' | 'DELETE';
 /**
  * https://docs.microsoft.com/en-us/graph/json-batching#request-format
  * @internal
  */
-export declare type GraphBatchRequest = GraphBatchRequestItem[];
+export type GraphBatchRequest = GraphBatchRequestItem[];
 /**
  * https://docs.microsoft.com/en-us/graph/json-batching#request-format
  * @internal
  */
-export declare type GraphBatchRequestItem = {
+export type GraphBatchRequestItem = {
     body?: any;
     headers?: {
         [id: string]: string;
@@ -170,13 +170,13 @@ export declare type GraphBatchRequestItem = {
 /**
  * @internal
  */
-export declare type GraphBatchRequestResponse = {
+export type GraphBatchRequestResponse = {
     responses: GraphBatchRequestResponseItem[];
 };
 /**
  * @internal
  */
-export declare type GraphBatchRequestResponseItem = {
+export type GraphBatchRequestResponseItem = {
     body: any;
     headers: HeadersInit;
     id: string;
@@ -185,15 +185,15 @@ export declare type GraphBatchRequestResponseItem = {
 /**
  * @internal
  */
-export declare type GraphListResponse<T = unknown> = {
+export type GraphListResponse<T = unknown> = {
     value: T[];
 };
 /** @internal */
-export declare type Microsoft365DocumentType = 'Email' | 'Chat Message' | 'Event' | 'Document' | 'Contact' | 'User' | 'List';
+export type Microsoft365DocumentType = 'Email' | 'Chat Message' | 'Event' | 'Document' | 'Contact' | 'User' | 'List';
 /** @internal */
-declare type Microsoft365TypeFilterType = 'Document' | 'Contact' | 'Chat Message' | 'Message' | 'Event' | 'List';
+type Microsoft365TypeFilterType = 'Document' | 'Contact' | 'Chat Message' | 'Message' | 'Event' | 'List';
 /** @internal */
-export declare type Microsoft365HomeSearchFilterTypeFilter = {
+export type Microsoft365HomeSearchFilterTypeFilter = {
     value: Microsoft365TypeFilterType;
     isSelected: boolean;
 };

package/client-api/src/internal/home/handlers/data.d.ts

@@ -0,0 +1,3 @@
+import { HomeClientApiDataRequest, HomeInternalDataResponse, HomeInternalErrorResponse, InternalDataResponse } from '../../../../../common/src/api/shapes/home';
+export declare function pushDataResponse(res: InternalDataResponse): Promise<void>;
+export declare function handleDataRequest(req: HomeClientApiDataRequest): Promise<HomeInternalDataResponse | HomeInternalErrorResponse>;

package/client-api/src/internal/home/handlers/data.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/home/handlers/disconnect.d.ts

@@ -0,0 +1 @@
+export declare function handleChannelDisconnection(): Promise<void>;

package/client-api/src/internal/home/handlers/disconnect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/home/handlers/index.d.ts

@@ -0,0 +1,6 @@
+import { SearchAPIClientChannelClient } from '../../../../../common/src/api/protocol/shapes/search';
+type HomeWorkspaceAPIClientChannelClient = SearchAPIClientChannelClient & {
+    homeChannelActionsRegistered?: boolean;
+};
+export declare function registerHomeChannelClientActions(channel: HomeWorkspaceAPIClientChannelClient): void;
+export {};

package/client-api/src/internal/home/handlers/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/home/handlers/result-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type OpenFin from '@openfin/core';
+import type { HomeClientApiDispatchRequest } from '../../../../../common/src/api/shapes/home';
+export declare function handleResultDispatch(req: HomeClientApiDispatchRequest, identity: OpenFin.Identity): Promise<void>;

package/client-api/src/internal/home/handlers/result-dispatch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/home/handlers/search-close.d.ts

@@ -0,0 +1,5 @@
+import type { HomeClientApiSearchCloseRequest } from '../../../../../common/src/api/shapes/home';
+/**
+ * Listens for search requests that have been closed.
+ */
+export declare function handleSearchRequestClose(req: HomeClientApiSearchCloseRequest): void;

package/client-api/src/internal/home/handlers/search-close.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/home/index.d.ts

@@ -0,0 +1,4 @@
+import { ProvidersMap } from '../../../../client-api/src/internal/providers';
+import { CLIProvider, HomeProvider, RegisterMetaInfoInternal } from '../..';
+export declare const HomeProviders: ProvidersMap<HomeProvider | CLIProvider>;
+export declare const registerHomeProviderInternal: (provider: HomeProvider | CLIProvider) => Promise<RegisterMetaInfoInternal>;

package/client-api/src/internal/home/requests.d.ts

@@ -0,0 +1,5 @@
+import type { InternalSearchListenerRequest } from '../../../../common/src/api/shapes/home';
+/**
+ * Map of search requests.
+ */
+export declare const searchRequests: Map<string, InternalSearchListenerRequest>;

package/client-api/src/internal/providers.d.ts

@@ -0,0 +1,63 @@
+import { ProviderType } from '../../../common/src/api/provider';
+export declare class ProviderNotRegisteredError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+export declare class ProviderAlreadyRegisteredError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+export declare class FailedToGetProviderError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+/**
+ * Utility class for managing providers.
+ */
+export declare class ProvidersMap<T extends {
+    id: string;
+}> {
+    private readonly providersMap;
+    private readonly providerType;
+    constructor(providerType: ProviderType);
+    /**
+     * Asserts that a provider is not already registered.
+     * @param provider The provider to check.
+     * @throws ProviderAlreadyRegisteredError if the provider already exists.
+     */
+    assertNotAlreadyRegistered(id: string): void;
+    /**
+     * Asserts that a provider is registered.
+     * @param provider The provider to check.
+     * @throws ProviderAlreadyRegisteredError if the provider already exists.
+     */
+    assertRegistered(id: string): void;
+    /**
+     * Gets a provider by id.
+     * @param id The id of the provider to get.
+     * @returns The provider if it exists, otherwise undefined.
+     */
+    getProvider(id: string): T | undefined;
+    /**
+     * Checks if a provider exists.
+     * @param id The id of the provider to check.
+     * @returns True if the provider exists, otherwise false.
+     */
+    hasProvider(id: string): boolean;
+    /**
+     * Sets a provider.
+     * @param provider The provider to set.
+     */
+    setProvider(provider: T): void;
+    /**
+     * Deletes a provider.
+     * @param id The id of the provider to delete.
+     */
+    deleteProvider(id: string): void;
+    /**
+     * Gets a provider by id or throws an error if it does not exist.
+     * @param id The id of the provider to get.
+     * @returns The provider if it exists.
+     * @throws An error if the provider does not exist.
+     * @see {@link ProviderNotRegisteredError}
+     */
+    getProviderOrFail(id: string): T;
+    clearProviders(): void;
+}

package/client-api/src/internal/providers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/client-api/src/internal/storefront/handlers.d.ts

@@ -0,0 +1,9 @@
+import { WorkspaceAPIClientChannelClient } from '../../../../common/src/api/protocol/workspace';
+type StorefrontWorkspaceAPIClientChannelClient = WorkspaceAPIClientChannelClient & {
+    storefrontChannelActionsRegistered?: boolean;
+};
+/**
+ *  Registers a channel action for each function in the Storefront provider.
+ */
+export declare const registerStorefrontChannelClientActions: (channel: StorefrontWorkspaceAPIClientChannelClient) => void;
+export {};

package/client-api/src/internal/storefront/index.d.ts

@@ -0,0 +1,4 @@
+import { ProvidersMap } from '../../../../client-api/src/internal/providers';
+import { RegisterMetaInfoInternal, StorefrontProvider } from '../../../../client-api/src/shapes';
+export declare const StorefrontProviders: ProvidersMap<StorefrontProvider>;
+export declare const registerStorefrontProviderInternal: (provider: StorefrontProvider) => Promise<RegisterMetaInfoInternal>;

package/client-api/src/{internal.d.ts → internal/try-dispatch.d.ts}

@@ -1,4 +1,4 @@
-import { WorkspaceChannelAction } from '../../common/src/api/protocol/shapes/workspace';
+import { WorkspaceChannelAction } from '../../../common/src/api/protocol/shapes/workspace';
 export interface ChannelDispatch {
     action: WorkspaceChannelAction;
     payload?: any;

package/client-api/src/legacy.d.ts

@@ -1,3 +1,4 @@
-import * as workspacesApi from '../../common/src/api/workspaces';
-export declare const getPages: () => Promise<import("@common/api/pages/shapes").Page[]>;
-export declare const getWorkspaces: () => Promise<workspacesApi.Workspace[]>;
+/** @deprecated */
+export declare const getPages: () => unknown;
+/** @deprecated */
+export declare const getWorkspaces: () => unknown;

package/client-api/src/shapes/common.d.ts

@@ -1,14 +1,31 @@
 export type { Action, DispatchedAction, DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProviderInfo, SearchResult, ScoreOrder, SearchTag, SearchProvider, UserInputListener, ResultDispatchListener, SearchResponse } from '../../../search-api/src/index';
 export type { Workspace } from '../../../common/src/api/workspaces';
-export type { Page, PageLayout, PageLayoutDetails, PanelConfig, PanelConfigHorizontal, PanelConfigVertical, PanelPosition } from '../../../common/src/api/pages/shapes';
 export { SearchTagBackground, ActionTrigger } from '../../../search-api/src/shapes';
 export type { ProviderInfo } from './provider';
 export type { BaseCustomButtonConfig, BaseCustomDropdownConfig, BaseCustomDropdownItem, BaseCustomDropdownItems, CustomActionSpecifier, CustomButtonConfig, CustomDropdownConfig } from '../../../common/src/api/action';
 /**
- * return by component.register function
+ * Registration meta info
+ *
+ * Returned when a Workspace component is registered.
  */
 export interface RegistrationMetaInfo {
+    /**
+     * Client API version
+     *
+     * This is the version of the Workspace client API that is being used to register the component.
+     */
     clientAPIVersion: string;
+    /**
+     * Workspace version
+     *
+     * This is the version of Workspace that the Workspace component is running on.
+     * This could be used to determine if the component is running on a version of Workspace that supports a particular feature.
+     */
     workspaceVersion: string;
 }
-export declare type RegisterMetaInfoInternal = Pick<RegistrationMetaInfo, 'workspaceVersion'>;
+/**
+ * Response from the Workspace Provider when a component is registered.
+ *
+ * @internal
+ */
+export type RegisterMetaInfoInternal = Pick<RegistrationMetaInfo, 'workspaceVersion'>;