@openfin/workspace-platform 13.0.7 → 13.1.0

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

@@ -1,5 +1,6 @@
 import * as DockAPI from './dock';
 import * as HomeAPI from './home';
+import * as IntegrationsAPI from './integrations';
 import * as LegacyAPI from './legacy';
 import * as StorefrontAPI from './store';
 export * from './shapes/common';
@@ -23,3 +24,7 @@ export { DockAPI as Dock };
   Namespace for Legacy integrations.
 */
 export { LegacyAPI as Legacy };
+/**
+  Namespace for Microflows integrations.
+*/
+export { IntegrationsAPI as Integrations };

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

@@ -0,0 +1,155 @@
+import { WorkflowIntegration } from '../../../client-api/src/shapes/integrations';
+import { Microsoft365ConnectionConfig, Microsoft365IntegrationConfig, Microsoft365Workflows, Microsoft365WorkflowType, MicrosoftEntityTypeConfig, MicrosoftSearchWorkflowConfig } from './microsoft.shapes';
+export type { Microsoft365IntegrationConfig, Microsoft365ConnectionConfig, Microsoft365Workflows, MicrosoftSearchWorkflowConfig, MicrosoftEntityTypeConfig };
+/**
+ * The Microsoft365WorkflowIntegration class is a WorkflowIntegration that provides Microsoft 365 integration.
+ * This integration allows you to search for Microsoft 365 entities and perform actions on them using Home.
+ */
+export declare class Microsoft365WorkflowIntegration extends WorkflowIntegration {
+    /** Instance of the Microsoft365Connection class. */
+    private connection;
+    /** The configuration object for the integration. */
+    config: Microsoft365IntegrationConfig;
+    /** The name of the integration. Used for Analytics */
+    workflowIntegrationName: string;
+    /** The current searchResponse. This can be used to update results. */
+    private searchResponse;
+    /** The minimum length of a query before the search will be triggered. */
+    private readonly minQueryLength;
+    /** Set of all possible filters that can be applied to the search results. This is based on the config provided. */
+    private readonly searchTypePossibleFilters;
+    /** A LRU cache of profile pictures. */
+    private readonly profilePictureCache;
+    /**
+     * Creates an instance of Microsoft365WorkflowIntegration.
+     *
+     * @param config The configuration object for the integration.
+     *
+     * @example
+     * ```ts
+     * const microsoft365Integration = new Microsoft365WorkflowIntegration({
+     *      connect: {
+     *          clientId: microsoft365Config.clientId,       // Client ID of the registered app
+     *          tenantId: microsoft365Config.tenantId,       // Tenant ID of the registered app
+     *          redirectUri: microsoft365Config.redirectUri  // Redirect URI of the registered app. This _must_ be the same domain as the app (providerUrl).
+     *      },
+     * });
+     *
+     * await WorkspacePlatform.init({
+     *     browserOptions: {},
+     *     integrations: [microsoft365Integration]
+     * })
+     */
+    constructor(config: Microsoft365IntegrationConfig);
+    /**
+     * Connects to the Microsoft 365 API using the provided configuration.
+     *
+     * @param config Defaults to the config provided to the constructor, but can be overridden here.
+     *
+     * @example
+     * ```ts
+     * await microsoft365Integration.connect({
+     *     clientId: microsoft365Config.clientId,
+     *     tenantId: microsoft365Config.tenantId,
+     *     redirectUri: microsoft365Config.redirectUri
+     * });
+     * ```
+     */
+    connect: (config?: Microsoft365ConnectionConfig) => Promise<void>;
+    /**
+     * Gets the Microsoft365Connection instance.
+     * If we are not connected, this method will connect before returning the connection.
+     *
+     * @returns The Microsoft365Connection instance.
+     */
+    private getConnection;
+    /**
+     * Wrapper around the Microsoft365Connection.executeApiRequest method.
+     * If the request fails due to an expired auth token, this method will reconnect and retry the request.
+     * If we are not connected, this method will connect before executing the request.
+     *
+     * @param args Arguments to pass to the Microsoft365Connection.executeApiRequest method.
+     * @returns The response from the Microsoft365Connection.executeApiRequest method.
+     */
+    private executeApiRequest;
+    private executeBatchApiRequest;
+    /**
+     * Executes a batch API request and maps the response to search results.
+     *
+     * If the request fails, we return an a single error result.
+     */
+    private executeBatchQuery;
+    /**
+     * Maps the response from a batch API request to search results.
+     *
+     * @param batchResponse The response from a batch API request.
+     * @returns An array of search results.
+     */
+    private mapBatchResponseToSearchResults;
+    /**
+     * Handles a search result being focused.
+     * @param result The search result that was focused.
+     */
+    private handleResultFocus;
+    private launchUrlInBrowser;
+    /**
+     * Handles a search result (ChatMessage) action being clicked.
+     * @param result The search result that was clicked.
+     * @returns A promise that resolves when the action has been handled.
+     */
+    private handleChatMessageUserAction;
+    /**
+     * Handles a search result (User) action being clicked.
+     * @param result The search result that was clicked.
+     * @returns A promise that resolves when the action has been handled.
+     */
+    private handleUserAction;
+    /**
+     * Handles a search result being actioned by the user.
+     * @param result The search result that was actioned.
+     */
+    private handleAction;
+    /**
+     * Creates a search result for a user.
+     * Called when a `user` search result is focused in the search results.
+     * @param res The search result to create a user result for.
+     */
+    private createUserResult;
+    private onUserInput;
+    private onResultDispatch;
+    /**
+     * Initializes a given workflow.
+     *
+     * This method is automatically called when `disableAutoInitialize` is set to `false` in the workflow configuration.
+     *
+     * Use this method if you need to call it manually (not at platform initialization).
+     *
+     *
+     * @param workflow The workflow to initialize.
+     *
+     * @example
+     * ```ts
+     * const microsoft365WorkflowIntegration = new Microsoft365WorkflowIntegration({
+     *     connect: {
+     *         clientId: microsoft365Config.clientId,
+     *         tenantId: microsoft365Config.tenantId,
+     *         redirectUri: microsoft365Config.redirectUri
+     *     },
+     *     workflows: {
+     *         search: {
+     *             disableAutoInitialize: true
+     *         }
+     *     }
+     * });
+     *
+     * await platformInit({
+     *     overrideCallback,
+     *     browserOptions: {},
+     *     integrations: [microsoft365WorkflowIntegration]
+     * });
+     *
+     * await microsoft365WorkflowIntegration.initializeWorkflow('search');
+     * ```
+     */
+    initializeWorkflow: (workflow: Microsoft365WorkflowType) => Promise<void>;
+}

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

@@ -0,0 +1,147 @@
+import { HomeProvider } from '../../../client-api/src/shapes/home';
+import { IntegrationWorkflows, WorkflowConfig, WorkflowIntegrationConfig } from '../../../client-api/src/shapes/integrations';
+/**
+ * Configuration object for the Microsoft 365 workflow integration.
+ *
+ * Used for choosing which Microsoft 365 entities to include in the search results.
+ *
+ * @example
+ * ```ts
+ * const config: MicrosoftEntityTypeConfig = {
+ *     message: true,
+ *     chatMessage: true,
+ *     drive: false,
+ *     event: false,
+ *     user: true,
+ *     contact: false,
+ *     list: false,
+ * };
+ * ```
+ */
+export interface MicrosoftEntityTypeConfig {
+    /**
+     * Whether or not to include messages (Outlook Emails) in the search results.
+     *
+     * `'Mail.ReadWrite.Shared'` OAuth scopes are required to access this data.
+     * If these scopes are not provided, user Authentication will fail.
+     *
+     * @default true
+     */
+    message: boolean;
+    /**
+     * Whether or not to include messages (Teams Messages) in the search results.
+     *
+     * `'Chat.Read' OR 'Chat.ReadWrite' AND 'ChannelMessage.Read.All'` OAuth scopes are required to access this data.
+     * If these scopes are not provided, user Authentication will fail.
+     *
+     * Futhermore, the `openUrlWithBrowser` permission must be enabled in the application manifest. This should support the `msteams` protocols. This is used for opening the Teams client when action-ing a Teams message.
+     * See the [Developer Guide](https://developers.openfin.co/of-docs/docs/api-security) for more information.
+     *
+     * @default true
+     */
+    chatMessage: boolean;
+    /**
+     * Whether or not to include files (OneDrive Files) in the search results.
+     * @default true
+     */
+    drive: boolean;
+    /**
+     * Whether or not to include events (Outlook Calendar Events) in the search results.
+     *
+     * `'Calendars.Read' OR 'Calendars.ReadWrite'` OAuth scopes are required to access this data.
+     * If these scopes are not provided, user Authentication will fail.
+     *
+     * @default true
+     */
+    event: boolean;
+    /**
+     * Whether or not to include users (People) in the search results.
+     *
+     * `'User.Read.All' AND 'Presence.Read.All'` OAuth scopes are required to access this data.
+     * If these scopes are not provided, user Authentication will fail.
+     *
+     * @default true
+     */
+    user: boolean;
+    /**
+     * Whether or not to include contacts (Outlook Contacts) in the search results.
+     *
+     * `'Contacts.Read.Shared'` OAuth scopes are required to access this data.
+     * If these scopes are not provided, user Authentication will fail.
+     *
+     * @default true
+     */
+    contact: boolean;
+    /**
+     * Whether or not to include lists (SharePoint Lists) in the search results.
+     *
+     * `'Sites.Read.All' OR 'Sites.ReadWrite.All' AND 'Mail.ReadWrite.Shared'` OAuth scope is required to access this data.
+     * @default true
+     */
+    list: boolean;
+}
+/**
+ * Configuration object for the Microsoft 365 Search workflow integration.
+ *
+ * All properties are optional. If they are omitted, the default values will be used.
+ */
+export interface MicrosoftSearchWorkflowConfig extends WorkflowConfig {
+    /**
+     * Configuration object for the HomeProvider.
+     *
+     * Use this to configure the HomeProvider for example, adding a custom logo or name.
+     *
+     * See {@link HomeProvider} for configuration options.
+     */
+    homeProvider?: Omit<HomeProvider, 'onUserInput' | 'onResultDispatch'>;
+    /**
+     * Configuration object for the Microsoft 365 entity types to include in the search results.
+     *
+     * Use this to enable/disable the different Microsoft 365 entity types.
+     *
+     * See {@link MicrosoftEntityTypeConfig} for configuration options.
+     */
+    MicrosoftEntityTypeConfig?: MicrosoftEntityTypeConfig;
+    /**
+     * The `msteams://` deep link can be used to open a Microsoft Teams chat in the Microsoft Teams desktop application.
+     *
+     * This _requires_ that the user has the Microsoft Teams desktop application installed. Else the call will silently fail.
+     *
+     * @default true
+     */
+    useTeamsDeepLink?: boolean;
+}
+export interface Microsoft365Workflows extends IntegrationWorkflows {
+    /**
+     * The Search workflow for the Microsoft 365 integration.
+     *
+     * This workflow is used to search for Microsoft 365 entities.
+     *
+     * To disable the Search workflow, set the disabled property in the workflow config to `false`.
+     *
+     * See {@link MicrosoftSearchWorkflowConfig} for configuration options.
+     */
+    search?: MicrosoftSearchWorkflowConfig;
+}
+export interface Microsoft365ConnectionConfig {
+    /**
+     * The client ID of the Microsoft 365 application.
+     */
+    clientId: string;
+    /**
+     * The tenant ID of the Microsoft 365 application.
+     */
+    tenantId: string;
+    /**
+     * The redirect URI of the Microsoft 365 application.
+     */
+    redirectUri: string;
+}
+/**
+ * Configuration object for the Microsoft 365 workflow integration.
+ */
+export interface Microsoft365IntegrationConfig extends WorkflowIntegrationConfig {
+    connect: Microsoft365ConnectionConfig;
+    workflows?: Microsoft365Workflows;
+}
+export declare type Microsoft365WorkflowType = 'search';

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

@@ -0,0 +1,80 @@
+import { CLIFilter } from '../../../client-api/src/index';
+import { CLISearchResultContact, HomeProvider } from '../../../client-api/src/shapes/home';
+import type { Presence } from '@microsoft/microsoft-graph-types';
+import type * as MicrosoftGraphTypes from '@microsoft/microsoft-graph-types';
+import { Microsoft365DocumentType, MicrosoftEntityTypeConfig, MicrosoftSearchWorkflowConfig } from './microsoft.shapes';
+export declare const getDefaultMicrosoftConfig: () => {
+    workflows: {
+        search: MicrosoftSearchWorkflowConfig;
+    };
+};
+/** Map of MicrosoftEntityTypeConfig keys to their corresponding Microsoft365DocumentType. */
+export declare const SEARCH_FILTER_TYPE_MAP: {
+    [K in keyof MicrosoftEntityTypeConfig]: Microsoft365DocumentType;
+};
+/**
+ * Some Microsoft 365 APIs require specific OAuth scopes to be provided. This map contains the required scopes for each MicrosoftEntityTypeConfig key.
+ * For Example. If the `chatMessage: true` key is set, then the `Chat.Read` and `ChannelMessage.Read.All` scopes are required.
+ */
+export declare const MICROSOFT_365_REQUIRED_SCOPES: {
+    [K in keyof MicrosoftEntityTypeConfig]?: string[];
+};
+export declare const MICROSOFT_365_SEARCH_RESULT_ACTIONS: {
+    readonly teamsCall: "Teams Call";
+    readonly teamsChat: "Teams Chat";
+    readonly email: "Email";
+};
+/**
+ * Extracts the selected filters from the given user input request and constructs a new filter array.
+ *
+ * The function looks for an existing filter with the ID matching `this.searchTypeFilterId` in the request.
+ * If such a filter is found, its selected options are preserved in the new filter array.
+ *
+ * The returned filter array includes one filter object for 'Type', which is a multi-select filter with options for 'Document', 'Contact', 'Message', 'Email', and 'Event'.
+ * The 'isSelected' status of these options is determined by their 'isSelected' status in the original request (if present).
+ *
+ * @param req The user input request object from which to extract the selected filters.
+ * @returns An array of CLIFilter objects representing the validated filters.
+ */
+export declare const getValidFilters: (req: Parameters<HomeProvider['onUserInput']>[0], searchTypePossibleFilters: Set<Microsoft365DocumentType>) => CLIFilter[];
+/**
+ * Extracts type filters from the input request.
+ *
+ * @param req - The user input request.
+ *
+ * @returns An object containing boolean flags indicating whether
+ * each of the types (Documents, Contacts, Messages, Emails, Events) should be shown.
+ * If none of the types are selected in the request, all types are marked to be shown.
+ *
+ * @remarks
+ * The function first checks if the `selectedFilters` field in the request's context contains the search type filter ID.
+ * If it does, it extracts the filter options and checks which types have been selected by the user.
+ * If no types are selected or all types are deselected, the function marks all types to be shown.
+ * Otherwise, it marks only the selected types to be shown.
+ */
+export declare const getTypeFiltersFromRequest: (req: Parameters<HomeProvider['onUserInput']>[0], searchTypePossibleFilters: Set<Microsoft365DocumentType>) => {
+    readonly showDocuments: boolean;
+    readonly showContacts: boolean;
+    /** Teams Messages */
+    readonly showChatMessages: boolean;
+    /** Outlook Emails */
+    readonly showMessages: boolean;
+    /** Outlook Events */
+    readonly showEvents: boolean;
+    /** SharePoint Lists */
+    readonly showLists: boolean;
+};
+export declare const getDocumentFiltersFromRequest: (req: Parameters<HomeProvider['onUserInput']>[0]) => {
+    readonly filterFiles: boolean;
+    readonly showWord: boolean;
+    readonly showExcel: boolean;
+    readonly showPowerPoint: boolean;
+    readonly showPDF: boolean;
+    readonly showOneNote: boolean;
+};
+export declare const filterDocumentsFromRequest: (items: MicrosoftGraphTypes.DriveItem[], filter: ReturnType<typeof getDocumentFiltersFromRequest>) => MicrosoftGraphTypes.DriveItem[];
+export declare const getFileType: (fileName?: string) => string;
+export declare const getFileIcon: (fileName?: string) => string;
+export declare const mapMicrosoftAvailabilityToPresence: (availability: Presence) => CLISearchResultContact['templateContent']['onlineStatus'] | undefined;
+/** base64IdToUrl converts a base64 encoded id to a url safe id */
+export declare const base64IdToUrl: (b64Id: string) => string;

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

@@ -0,0 +1,3 @@
+export { Microsoft365WorkflowIntegration } from './integrations/microsoft';
+export type { Microsoft365IntegrationConfig, Microsoft365ConnectionConfig, Microsoft365Workflows, MicrosoftEntityTypeConfig, MicrosoftSearchWorkflowConfig } from './integrations/microsoft';
+export type { WorkflowIntegrationConfig } from './shapes/integrations';

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

@@ -1,4 +1,4 @@
-import { WorkspaceChannelAction } from '../../common/src/api/protocol/workspace';
+import { WorkspaceChannelAction } from '../../common/src/api/protocol/shapes/workspace';
 export interface ChannelDispatch {
     action: WorkspaceChannelAction;
     payload?: any;
@@ -11,7 +11,7 @@ export interface ChannelDispatch {
  * @param action The contemporary action for the provider.
  * @param fallback The deprecated action for the provider.
  * @param fallbackResponse optional response for the fallback action.
- * @returns channel response is returned if action was succesful. If fallback was used, fallbackResponse is returned instead.
+ * @returns channel response is returned if action was successful. If fallback was used, fallbackResponse is returned instead.
  */
 export declare function tryDispatch(action: ChannelDispatch, fallback: ChannelDispatch): Promise<void>;
 export declare function tryDispatch<T = undefined>(action: ChannelDispatch, fallback: ChannelDispatch, fallbackResponse: T): Promise<T>;

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

@@ -129,7 +129,7 @@ export declare enum CLITemplate {
      */
     Loading = "Loading",
     /**
-     * A Template that indicates that a problem occured with the search result details.
+     * A Template that indicates that a problem occurred with the search result details.
      */
     Error = "Error"
 }
@@ -160,11 +160,79 @@ export interface ContactInfo {
      * A flag to indicate that the contact card should display the contact's initials as profile photo if the photo url is undefined.
      */
     useInitials?: boolean;
+    /**
+     * The contact's online status.
+     */
+    onlineStatus?: 'offline' | 'do-not-disturb' | 'busy' | 'away' | 'available';
     /**
      * An array of detail list objects that can be used for logical grouping of contact details.
      */
     details: ListPairs[];
+    /**
+     * An array of buttons to display on the contact card.
+     */
+    buttons?: ContactInfoButtons[];
 }
+export declare type ButtonIcon = 
+/**
+ * The icon used for the button.
+ */
+string | {
+    /**
+     * The icon used for the button in light mode.
+     */
+    light: string;
+    /**
+     * The icon used for the button in dark mode.
+     */
+    dark: string;
+};
+export declare type ContactInfoButtons = {
+    type: 'button';
+    /**
+     * The icon to display on the button.
+     */
+    icon: ButtonIcon;
+    /**
+     * The tooltip to display on the button.
+     */
+    tooltip: string;
+    /**
+     * The action to execute when the button is clicked.
+     */
+    action: string;
+} | {
+    type: 'dropdown';
+    /**
+     * The icon to display on the button.
+     */
+    icon?: ButtonIcon;
+    /**
+     * The tooltip to display on the button.
+     */
+    tooltip: string;
+    /**
+     * The action to execute when the button is clicked.
+     */
+    action?: string;
+    /**
+     * The list of options to display in the dropdown.
+     */
+    options: {
+        /**
+         * The icon to display on the button.
+         */
+        icon?: ButtonIcon;
+        /**
+         * The tooltip to display on the button.
+         */
+        tooltip: string;
+        /**
+         * The action to execute when the button is clicked.
+         */
+        action: string;
+    }[];
+};
 /**
  *  Contact Info Search Result
  */
@@ -276,7 +344,7 @@ export interface CLIProvider extends SearchProvider {
      *          return getAllData();
      *      }
      *
-     *      // Provide an implmentation to fetch query-filtered search results
+     *      // Provide an implementation to fetch query-filtered search results
      *      return getResultsByQuery(query);
      * }
      * ```
@@ -299,7 +367,7 @@ export interface CLIProvider extends SearchProvider {
      *          const availableCommands = await getAvailableCommands();
      *          const commandToExecute = availableCommands.find((command) => command.key === result.key);
      *
-     *          if (commantToExecute != undefined) {
+     *          if (commandToExecute != undefined) {
      *              await commandToExecute.action();
      *          }
      *      } catch (err) {

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

@@ -0,0 +1,36 @@
+import { WorkspacePlatformModule } from '../../../client-api-platform/src/shapes';
+export interface WorkflowConfig extends Record<string, unknown> {
+    /**
+     * If false, will automatically initialize the workflow when the Workspace Platform is initialized.
+     * Else, will need to be initialized by calling initializeWorkflow.
+     *
+     * @default false
+     */
+    disableAutoInitialize?: boolean;
+    /**
+     * If true, will disable this workflow.
+     * @default false
+     */
+    disabled?: boolean;
+}
+export interface IntegrationWorkflows {
+    [key: string]: WorkflowConfig;
+}
+export interface WorkflowDependencies {
+    workspacePlatformAPI: WorkspacePlatformModule;
+}
+export interface WorkflowIntegrationConfig {
+    connect: unknown;
+    workflows?: IntegrationWorkflows;
+    dependencies?: WorkflowDependencies;
+}
+export declare abstract class WorkflowIntegration {
+    workspacePlatformAPI: any;
+    workflowIntegrationName: string;
+    config: WorkflowIntegrationConfig;
+    private initializedWorkflows;
+    constructor(config: WorkflowIntegrationConfig);
+    connect: (config?: any) => Promise<void>;
+    _initializeWorkflows: (config?: WorkflowIntegrationConfig) => Promise<void>;
+    initializeWorkflow(workflow: string): Promise<void>;
+}

package/client-api-platform/src/api/context-menu/utils.d.ts

@@ -14,3 +14,7 @@ export declare const savePageHandler: (identity: OpenFin.Identity, pageId?: stri
 export declare const savePageAsHandler: (identity: OpenFin.Identity, pageId?: string) => Promise<void>;
 export declare const switchWorkspaceHandler: (winIdentity: OpenFin.Identity, workspaceItemData: WorkspaceContextMenuItemData) => Promise<void>;
 export declare const deleteWorkspaceHandler: (winIdentity: OpenFin.Identity, workspaceItemData: WorkspaceContextMenuItemData) => Promise<void>;
+/**
+ * @param viewIdentities Array of views to execute print on.
+ */
+export declare const printSelectedViews: (viewIdentities: OpenFin.Identity[]) => Promise<void>;

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

@@ -1,4 +1,3 @@
 import { DockProviderConfigWithIdentity } from '../../../../client-api/src/shapes';
-export declare const store: import("idb-keyval").UseStore;
 export declare function getDockProviderConfig(providerId: string): Promise<DockProviderConfigWithIdentity | undefined>;
 export declare function saveDockProviderConfig(config: DockProviderConfigWithIdentity): Promise<void>;