@openfin/cloud-api 0.0.1-alpha.ffeba61 → 10.0.0-beta.1c

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as OpenFin from '@openfin/core';
-import OpenFin__default from '@openfin/core';
+import OpenFin__default, { OpenFin as OpenFin$1 } from '@openfin/core';
 import * as NotificationsTypes from '@openfin/workspace/notifications';
 
 /**
@@ -305,7 +305,7 @@ declare function launchWorkspace(id: string): Promise<void>;
  *
  * @returns Result that includes the URL that Here™ should navigate to, or `undefined` if no navigation is required.
  */
-type OnActionListener = (action: SearchAction, result: SearchResult) => SearchResultActionResponse | Promise<SearchResultActionResponse>;
+type OnActionListener = (action: SearchAction$1, result: SearchResult$1) => SearchResultActionResponse$1 | Promise<SearchResultActionResponse$1>;
 /**
  * Function that is called when the Search Agent receives a query from Here™’s search UI
  *
@@ -313,13 +313,13 @@ type OnActionListener = (action: SearchAction, result: SearchResult) => SearchRe
  *
  * @returns Search response data that includes the search results.
  */
-type OnSearchListener = (request: SearchListenerRequest) => SearchResponse | Promise<SearchResponse>;
+type OnSearchListener = (request: SearchListenerRequest$1) => SearchResponse$1 | Promise<SearchResponse$1>;
 /**
  * An action that can be triggered by a user on a search result returned by a Search Agent.
  *
  * Actions are displayed as buttons alongside search results in Here™’s search UI. That is, except for the first action, which is hidden as it is triggered automatically when the user selects the search result.
  */
-type SearchAction = {
+type SearchAction$1 = {
     /**
      * URL or data URI of an icon that will be displayed within the action button when Here™ is in Light mode.
      */
@@ -343,21 +343,48 @@ type SearchAction = {
 };
 /**
  * A Search Agent returns search results to Here™’s search UI in response to user input, and acts on the user’s actions regarding those results.
+ *
+ * @deprecated Use {@link Agent} instead.
  */
 type SearchAgent = {
-    /**
-     * The Search Agent’s custom configuration data configured via the Admin Console.
-     */
-    readonly customData: unknown;
     /**
      * Sets whether or not the Search Agent is ready to provide search results.
      *
      * When a Search Agent is first registered, it will not receive search queries until it is set as ready by calling this function.
      *
      * @param ready Whether the Search Agent is ready to provide search results (defaults to `true`).
+     *
+     * @deprecated Use {@link Agent.setIsReady} instead.
      */
     isReady: (ready?: boolean) => Promise<void>;
 };
+/**
+ * The Search Agent’s configuration data as configured in the Here™ Admin Console.
+ *
+ * @typeParam T Type definition for the `customData` property, containing any custom configuration data specific to the Search Agent.
+ */
+type SearchAgentConfigurationData<T> = {
+    /**
+     * Custom configuration data specific to the Search Agent.
+     */
+    customData?: T;
+    /**
+     * Optional description of the Search Agent.
+     */
+    description?: string;
+    /**
+     * Unique identifier for the Search Agent.
+     */
+    id: string;
+    /**
+     * The display title of the Search Agent.
+     */
+    title: string;
+    /**
+     * The URL of the Search Agent.
+     */
+    url: string;
+};
 /**
  * Configuration provided when registering a Search Agent.
  */
@@ -378,11 +405,11 @@ type SearchAgentRegistrationConfig = {
 /**
  * Search request data provided to the {@link OnSearchListener}.
  */
-type SearchListenerRequest = {
+type SearchListenerRequest$1 = {
     /**
      * Provides additional context for the search request.
      */
-    context: SearchRequestContext;
+    context: SearchRequestContext$1;
     /**
      * The query entered by the user in Here™’s search UI.
      */
@@ -395,7 +422,7 @@ type SearchListenerRequest = {
 /**
  * Context data included with a search request.
  */
-type SearchRequestContext = {
+type SearchRequestContext$1 = {
     /**
      * The page number of the search results to return.
      */
@@ -404,24 +431,28 @@ type SearchRequestContext = {
      * The number of search results to return per page.
      */
     pageSize: number;
+    /**
+     * The unique ID of the query.
+     */
+    queryId: string;
 };
 /**
  * Return type of the {@link OnSearchListener}.
  */
-type SearchResponse = {
+type SearchResponse$1 = {
     /**
      * The search results to display in Here™’s search UI.
      */
-    results: SearchResult[];
+    results: SearchResult$1[];
 };
 /**
  * A search result returned by a Search Agent in response to a search request.
  */
-type SearchResult = {
+type SearchResult$1 = {
     /**
      * Actions that can be triggered by the user against the search result.
      */
-    actions: SearchAction[];
+    actions: SearchAction$1[];
     /**
      * Additional data that can be used by the {@link OnActionListener} when an action is triggered.
      */
@@ -446,13 +477,35 @@ type SearchResult = {
 /**
  * Return type of the {@link OnActionListener}.
  */
-type SearchResultActionResponse = {
+type SearchResultActionResponse$1 = {
     /**
      * URL that Here™ should navigate to.
      */
     url: string;
 } | undefined;
 
+/**
+ * Retrieves the Search Agent’s configuration data, as has been configured in the Here™ Admin Console.
+ *
+ * @returns A promise that resolves with an object containing properties that match the Search Agent’s configuration.
+ *
+ * @example Retrieving the Search Agent’s configuration data:
+ * ```ts
+ * import { Search } from "@openfin/cloud-api";
+ *
+ * // Get the configuration data
+ * const configData = await Search.getAgentConfiguration<{ customField1: string, customField2: string }>();
+ *
+ * // Pick out the standard configuration properties
+ * const { customData, description, id, title, url } = configData;
+ *
+ * // Pick out the custom configuration properties
+ * if (customData) {
+ *   const { customField1, customField2 } = customData;
+ * }
+ * ```
+ */
+declare function getAgentConfiguration<T extends object>(): Promise<SearchAgentConfigurationData<T>>;
 /**
  * Registers a Search Agent that will provide search results to Here™’s search UI in response to user input and act on the user’s actions regarding those results.
  *
@@ -462,6 +515,8 @@ type SearchResultActionResponse = {
  *
  * @example Registering a basic Search Agent:
  * ```ts
+ * import { Search } from "@openfin/cloud-api";
+ *
  * // Handle incoming action and return a response that includes the URL to navigate to
  * const onAction: Search.OnActionListener = (action, result) => {
  *     const { name } = action;
@@ -532,22 +587,345 @@ type SearchResultActionResponse = {
  * // Set the Search Agent as ready to receive search requests
  * await searchAgent.isReady();
  * ```
+ *
+ * @deprecated Use `Agent.register` instead.
+ */
+declare function register$1(config: SearchAgentRegistrationConfig): Promise<SearchAgent>;
+
+type index$1_OnActionListener = OnActionListener;
+type index$1_OnSearchListener = OnSearchListener;
+type index$1_SearchAgent = SearchAgent;
+type index$1_SearchAgentConfigurationData<T> = SearchAgentConfigurationData<T>;
+type index$1_SearchAgentRegistrationConfig = SearchAgentRegistrationConfig;
+declare const index$1_getAgentConfiguration: typeof getAgentConfiguration;
+declare namespace index$1 {
+  export { type index$1_OnActionListener as OnActionListener, type index$1_OnSearchListener as OnSearchListener, type SearchAction$1 as SearchAction, type index$1_SearchAgent as SearchAgent, type index$1_SearchAgentConfigurationData as SearchAgentConfigurationData, type index$1_SearchAgentRegistrationConfig as SearchAgentRegistrationConfig, type SearchListenerRequest$1 as SearchListenerRequest, type SearchRequestContext$1 as SearchRequestContext, type SearchResponse$1 as SearchResponse, type SearchResult$1 as SearchResult, type SearchResultActionResponse$1 as SearchResultActionResponse, index$1_getAgentConfiguration as getAgentConfiguration, register$1 as register };
+}
+
+/**
+ * Function that is called when the Agent receives an action from Here™’s search UI that has been triggered by the user on one of the Agent’s search results.
+ *
+ * @param action The action that was triggered.
+ * @param result The search result that the action was triggered on.
+ *
+ * @returns Result that includes the URL that Here™ should navigate to, or `undefined` if no navigation is required.
+ */
+type OnSearchActionListener = (action: SearchAction, result: SearchResult) => SearchResultActionResponse | Promise<SearchResultActionResponse>;
+/**
+ * Function that is called when the Agent receives a query from Here™’s search UI
+ *
+ * @param request Search request data that includes the query.
+ *
+ * @returns Search response data that includes the search results.
+ */
+type OnSearchRequestListener = (request: SearchListenerRequest) => SearchResponse | Promise<SearchResponse>;
+/**
+ * An action that can be triggered by a user on a search result returned by a Agent.
+ *
+ * Actions are displayed as buttons alongside search results in Here™’s search UI. That is, except for the first action, which is hidden as it is triggered automatically when the user selects the search result.
+ */
+type SearchAction = {
+    /**
+     * URL or data URI of an icon that will be displayed within the action button when Here™ is in Light mode.
+     */
+    darkIcon?: string;
+    /**
+     * A fuller description of the action that will be displayed in Here™’s search UI when the user hovers over the action button.
+     */
+    description?: string;
+    /**
+     * URL or data URI of an icon that will be displayed within the action button when Here™ is in Dark mode.
+     */
+    lightIcon?: string;
+    /**
+     * Internal identifier for the action which is used to identify the action in the {@link OnSearchActionListener}.
+     */
+    name: string;
+    /**
+     * Compact title of the action displayed within the action button.
+     */
+    title?: string;
+};
+/**
+ * Search request data provided to the {@link OnSearchRequestListener}.
+ */
+type SearchListenerRequest = {
+    /**
+     * Provides additional context for the search request.
+     */
+    context: SearchRequestContext;
+    /**
+     * The query entered by the user in Here™’s search UI.
+     */
+    query: string;
+    /**
+     * Provide this signal to any `fetch` requests executed in the {@link OnSearchRequestListener} function as a result of this search request, so that they will be automatically cancelled if a new search request is received before they complete.
+     */
+    signal: AbortSignal;
+};
+/**
+ * Context data included with a search request.
+ */
+type SearchRequestContext = {
+    /**
+     * Filters to apply to the search results.
+     */
+    filters: string[];
+    /**
+     * The locale of the client.
+     */
+    locale: string;
+    /**
+     * The page number of the search results to return.
+     */
+    pageNumber: number;
+    /**
+     * The number of search results to return per page.
+     */
+    pageSize: number;
+    /**
+     * The unique ID of the query.
+     */
+    queryId: string;
+    /**
+     * The timezone of the client.
+     */
+    timeZone: string;
+};
+/**
+ * Return type of the {@link OnSearchRequestListener}.
+ */
+type SearchResponse = {
+    /**
+     * The search results to display in Here™’s search UI.
+     */
+    results: SearchResult[];
+};
+/**
+ * A search result returned by a Agent in response to a search request.
+ */
+type SearchResult = {
+    /**
+     * Actions that can be triggered by the user against the search result.
+     */
+    actions: SearchAction[];
+    /**
+     * Additional data that can be used by the {@link OnSearchActionListener} when an action is triggered.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * URL or data URI of an icon that will be displayed with the search result in Here™’s search UI.
+     */
+    icon?: string;
+    /**
+     * Unique identifier for the search result.
+     */
+    key: string;
+    /**
+     * Secondary text that will be displayed with the search result in Here™’s search UI.
+     */
+    label?: string;
+    /**
+     * Primary text that will be displayed with the search result in Here™’s search UI.
+     */
+    title: string;
+};
+/**
+ * Return type of the {@link OnSearchActionListener}.
+ */
+type SearchResultActionResponse = {
+    /**
+     * URL that Here™ should navigate to.
+     */
+    url: string;
+} | undefined;
+
+type Agent = {
+    /**
+     * The features supported by the Agent.
+     */
+    features: AgentFeatures;
+    /**
+     * Joins the agent to a specific interop channel.
+     *
+     * @throws {InteropFeatureNotSupportedError} if the interop feature is not supported by the agent.
+     */
+    joinInteropChannel: (channelName: InteropColorChannel) => Promise<void>;
+    /**
+     * Sets whether or not the Agent is ready.
+     *
+     * @param ready Whether the Agent is ready (defaults to `true`).
+     */
+    setIsReady: (ready?: boolean) => Promise<void>;
+};
+/**
+ * The features supported by the Agent.
+ */
+type AgentFeatures = {
+    interop?: {
+        defaultChannel?: InteropColorChannel;
+        fdc3Version: OpenFin$1.FDC3.Version;
+    };
+    search?: {
+        filters?: AgentSearchFilter[];
+        supportsPaging: boolean;
+    };
+};
+/**
+ * Configuration provided when registering a Agent.
+ */
+type AgentRegistrationConfig = {
+    /**
+     * Search configuration required if the Agent supports search functionality.
+     */
+    search?: {
+        /**
+         * This listener is called when the Agent receives an action from Here™’s search UI that has been triggered by the user on one of the Agent’s search results.
+         *
+         * The listener returns a response back to Here™ that includes a URL to navigate to.
+         */
+        onAction: OnSearchActionListener;
+        /**
+         * This listener is called when the Agent receives a query from Here™’s search UI and returns relevant search results.
+         *
+         * Note: When the Agent is not ready this listener will not be called.
+         */
+        onSearch: OnSearchRequestListener;
+    };
+};
+/**
+ * A filter that can be applied to the Agent’s search results.
+ */
+type AgentSearchFilter = {
+    icon?: string | {
+        dark: string;
+        light: string;
+    };
+    id: string;
+    title: string;
+};
+type InteropColorChannel = 'blue' | 'indigo' | 'pink' | 'teal' | 'green' | 'orange' | 'red' | 'yellow' | 'gray' | 'none';
+
+/**
+ * Retrieves the Agent’s configuration data, as has been configured in the Here™ Admin Console.
+ *
+ * @returns A promise that resolves with an object containing properties that match the Agent’s configuration.
+ *
+ * @example Retrieving the Agent’s configuration data:
+ * ```ts
+ * import { Agent } from "@openfin/cloud-api";
+ *
+ * // Get the configuration data
+ * const configData = await Agent.getConfiguration<{ customField1: string, customField2: string }>();
+ *
+ * // Pick out the standard configuration properties
+ * const { customData, description, id, title, url } = configData;
+ *
+ * // Pick out the custom configuration properties
+ * if (customData) {
+ *   const { customField1, customField2 } = customData;
+ * }
+ * ```
+ */
+declare const getConfiguration: <T extends Record<string, unknown>>() => Promise<T>;
+/**
+ * Registers an Agent.
+ *
+ * @param config The configuration for the Agent.
+ *
+ * @returns A promise that resolves with the Agent.
+ *
+ * @example Registering an Agent that will provide search results:
+ * ```ts
+ * import { Agent } from "@openfin/cloud-api";
+ *
+ * // Handle incoming action and return a response that includes the URL to navigate to
+ * const onAction: Agent.OnSearchActionListener = (action, result) => {
+ *     const { name } = action;
+ *     const { data, key } = result;
+ *     const { owner, searchResultHostUrl } = data as { owner: { id: string, name: string }, searchResultHostUrl: string };
+ *     const { id: ownerId } = owner;
+ *
+ *     console.log(`Action "${name}" triggered on search result with key "${key}"`);
+ *
+ *     switch (name) {
+ *         case "view-owner":
+ *             return { url: `${searchResultHostUrl}/people/${ownerId}` };
+ *         case "view-result":
+ *             return { url: `${searchResultHostUrl}/record/${key}` };
+ *         default:
+ *             console.warn(`Unknown action: ${name}`);
+ *     }
+ * };
+ *
+ * // Handle incoming search request and return relevant search results
+ * const onSearch: Agent.OnSearchRequestListener = ({ context, query, signal }) => {
+ *     const { pageNumber, pageSize } = context;
+ *     try {
+ *         let results: Agent.SearchResult[] = [];
+ *         const url = `https://my-web-app.com/search?q=${query}&page=${pageNumber}&limit=${pageSize}`;
+ *         const response = await fetch(url, { signal });
+ *         if (!response.ok) {
+ *             throw new Error(`Request failed: ${response.status}`);
+ *         }
+ *         const { searchResults } = await response.json();
+ *         results = searchResults.map((result) => {
+ *             const { iconUrl, id: key, owner, subTitle, title } = result;
+ *             const { name: ownerName } = owner as { id: string, name: string };
+ *             return {
+ *                 actions: [
+ *                     {
+ *                         name: "view-result",
+ *                         description: `Go to ${title} in My Web App`,
+ *                     },
+ *                     {
+ *                         name: "view-owner",
+ *                         description: `Go to ${ownerName} in My Web App`,
+ *                         title: "View Owner",
+ *                     },
+ *                 ],
+ *                 data: {
+ *                     owner,
+ *                     searchResultHostUrl: `https://my-web-app.com`,
+ *                 },
+ *                 icon: iconUrl,
+ *                 key,
+ *                 label: subTitle,
+ *                 title,
+ *             };
+ *         });
+ *         console.log("Returning results", results);
+ *         return { results };
+ *     } catch (err) {
+ *         if ((err as Error).name === "AbortError") {
+ *             // Ignore errors for cancelled requests
+ *             return { results: [] };
+ *         }
+ *         throw err;
+ *     }
+ * };
+ *
+ * // Register the agent
+ * const agent = await Agent.register({ search: { onAction, onSearch } });
+ *
+ * // Set the Agent as ready to receive requests
+ * await agent.isReady();
+ * ```
  */
-declare function register(config: SearchAgentRegistrationConfig): Promise<SearchAgent>;
+declare function register(config: AgentRegistrationConfig): Promise<Agent>;
 
-type index_OnActionListener = OnActionListener;
-type index_OnSearchListener = OnSearchListener;
-type index_SearchAction = SearchAction;
-type index_SearchAgent = SearchAgent;
-type index_SearchAgentRegistrationConfig = SearchAgentRegistrationConfig;
+type index_Agent = Agent;
+type index_AgentFeatures = AgentFeatures;
+type index_AgentRegistrationConfig = AgentRegistrationConfig;
+type index_AgentSearchFilter = AgentSearchFilter;
+type index_InteropColorChannel = InteropColorChannel;
+type index_OnSearchActionListener = OnSearchActionListener;
+type index_OnSearchRequestListener = OnSearchRequestListener;
 type index_SearchListenerRequest = SearchListenerRequest;
-type index_SearchRequestContext = SearchRequestContext;
-type index_SearchResponse = SearchResponse;
-type index_SearchResult = SearchResult;
-type index_SearchResultActionResponse = SearchResultActionResponse;
+declare const index_getConfiguration: typeof getConfiguration;
 declare const index_register: typeof register;
 declare namespace index {
-  export { type index_OnActionListener as OnActionListener, type index_OnSearchListener as OnSearchListener, type index_SearchAction as SearchAction, type index_SearchAgent as SearchAgent, type index_SearchAgentRegistrationConfig as SearchAgentRegistrationConfig, type index_SearchListenerRequest as SearchListenerRequest, type index_SearchRequestContext as SearchRequestContext, type index_SearchResponse as SearchResponse, type index_SearchResult as SearchResult, type index_SearchResultActionResponse as SearchResultActionResponse, index_register as register };
+  export { type index_Agent as Agent, type index_AgentFeatures as AgentFeatures, type index_AgentRegistrationConfig as AgentRegistrationConfig, type index_AgentSearchFilter as AgentSearchFilter, type index_InteropColorChannel as InteropColorChannel, type index_OnSearchActionListener as OnSearchActionListener, type index_OnSearchRequestListener as OnSearchRequestListener, type index_SearchListenerRequest as SearchListenerRequest, index_getConfiguration as getConfiguration, index_register as register };
 }
 
 declare global {
@@ -556,4 +934,4 @@ declare global {
     }
 }
 
-export { type AppPermissions, type LaunchContentOptions, index as Search, type FlannelChannelProvider as __INTERNAL_FlannelChannelProvider, type FlannelClearNotificationRequest as __INTERNAL_FlannelClearNotificationRequest, type FlannelClearNotificationResponse as __INTERNAL_FlannelClearNotificationResponse, type FlannelCreateNotificationRequest as __INTERNAL_FlannelCreateNotificationRequest, type FlannelCreateNotificationResponse as __INTERNAL_FlannelCreateNotificationResponse, type FlannelUpdateNotificationRequest as __INTERNAL_FlannelUpdateNotificationRequest, type FlannelUpdateNotificationResponse as __INTERNAL_FlannelUpdateNotificationResponse, getAppSettings, getAppUserPermissions, getAppUserSettings, getNotificationsClient, launchContent, launchSupertab, launchWorkspace, setAppUserSettings };
+export { index as Agent, type AppPermissions, type LaunchContentOptions, index$1 as Search, type FlannelChannelProvider as __INTERNAL_FlannelChannelProvider, type FlannelClearNotificationRequest as __INTERNAL_FlannelClearNotificationRequest, type FlannelClearNotificationResponse as __INTERNAL_FlannelClearNotificationResponse, type FlannelCreateNotificationRequest as __INTERNAL_FlannelCreateNotificationRequest, type FlannelCreateNotificationResponse as __INTERNAL_FlannelCreateNotificationResponse, type FlannelUpdateNotificationRequest as __INTERNAL_FlannelUpdateNotificationRequest, type FlannelUpdateNotificationResponse as __INTERNAL_FlannelUpdateNotificationResponse, getAppSettings, getAppUserPermissions, getAppUserSettings, getNotificationsClient, launchContent, launchSupertab, launchWorkspace, setAppUserSettings };