@openfin/cloud-api 0.0.1-alpha.d7ba187 → 0.0.1-alpha.d83fa08

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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';
+import { InteropColorChannel } from '@openfin/shared-utils/schemas/interop';
 
 /**
  * NotificationsClient is a client for accessing and interacting with the Notifications your application has created.
@@ -298,40 +299,42 @@ declare function launchSupertab(id: string): Promise<void>;
 declare function launchWorkspace(id: string): Promise<void>;
 
 /**
- * Function that is called when the Search Agent receives an action from Here™’s search UI that has been triggered by the user on one of the Agent’s search results.
+ * Function that is called when the Search 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.
+ * @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
+ * Function that is called when the Search 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 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.
+ * 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;
+type SearchAction$1 = {
     /**
-     * A fuller description of the action that will be displayed in Here™’s search UI when the user hovers over the action button.
+     * 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.
+     * Icon that will be displayed within the action button in HERE's search UI.
+     *
+     * This can be a URL/data URI string (used for both Light and Dark modes),
+     * or an object containing separate icons for Light and Dark modes.
      */
-    lightIcon?: string;
+    icon?: string | {
+        dark: string;
+        light: string;
+    };
     /**
      * Internal identifier for the action which is used to identify the action in the {@link OnActionListener}.
      */
@@ -342,7 +345,9 @@ type SearchAction = {
     title?: string;
 };
 /**
- * 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.
+ * 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 = {
     /**
@@ -351,11 +356,13 @@ type SearchAgent = {
      * 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.
+ * 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.
  */
@@ -386,13 +393,13 @@ type SearchAgentConfigurationData<T> = {
  */
 type SearchAgentRegistrationConfig = {
     /**
-     * This listener is called when the Search Agent receives an action from Here™’s search UI that has been triggered by the user on one of the Agent’s search results.
+     * This listener is called when the Search 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.
+     * The listener returns a response back to HERE that includes a URL to navigate to.
      */
     onAction: OnActionListener;
     /**
-     * This listener is called when the Search Agent receives a query from Here™’s search UI and returns relevant search results.
+     * This listener is called when the Search Agent receives a query from HERE's search UI and returns relevant search results.
      *
      * Note: When the Search Agent is not ready this listener will not be called.
      */
@@ -401,13 +408,13 @@ 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.
+     * The query entered by the user in HERE's search UI.
      */
     query: string;
     /**
@@ -418,7 +425,7 @@ type SearchListenerRequest = {
 /**
  * Context data included with a search request.
  */
-type SearchRequestContext = {
+type SearchRequestContext$1 = {
     /**
      * The page number of the search results to return.
      */
@@ -435,26 +442,26 @@ type SearchRequestContext = {
 /**
  * Return type of the {@link OnSearchListener}.
  */
-type SearchResponse = {
+type SearchResponse$1 = {
     /**
-     * The search results to display in Here™’s search UI.
+     * 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.
      */
     data?: Record<string, unknown>;
     /**
-     * URL or data URI of an icon that will be displayed with the search result in Here™’s search UI.
+     * URL or data URI of an icon that will be displayed with the search result in HERE's search UI.
      */
     icon?: string;
     /**
@@ -462,26 +469,26 @@ type SearchResult = {
      */
     key: string;
     /**
-     * Secondary text that will be displayed with the search result in Here™’s search UI.
+     * 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.
+     * Primary text that will be displayed with the search result in HERE's search UI.
      */
     title: string;
 };
 /**
  * Return type of the {@link OnActionListener}.
  */
-type SearchResultActionResponse = {
+type SearchResultActionResponse$1 = {
     /**
-     * URL that Here™ should navigate to.
+     * 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.
+ * 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.
  *
@@ -503,7 +510,7 @@ type SearchResultActionResponse = {
  */
 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.
+ * 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.
  *
  * @param config The configuration for the Search Agent.
  *
@@ -554,6 +561,10 @@ declare function getAgentConfiguration<T extends object>(): Promise<SearchAgentC
  *                         name: "view-owner",
  *                         description: `Go to ${ownerName} in My Web App`,
  *                         title: "View Owner",
+ *                         icon: {
+ *                             dark: "data:image/svg+xml,...",
+ *                             light: "data:image/svg+xml,...",
+ *                         },
  *                     },
  *                 ],
  *                 data: {
@@ -583,24 +594,351 @@ declare function getAgentConfiguration<T extends object>(): Promise<SearchAgentC
  * // 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 = {
+    /**
+     * 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;
+    /**
+     * Icon that will be displayed within the action button in HERE's search UI.
+     *
+     * This can be a URL/data URI string (used for both Light and Dark modes),
+     * or an object containing separate icons for Light and Dark modes.
+     */
+    icon?: string | {
+        dark: string;
+        light: 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;
+};
+
+/**
+ * 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",
+ *                         icon: {
+ *                             dark: "data:image/svg+xml,...",
+ *                             light: "data:image/svg+xml,...",
+ *                         },
+ *                     },
+ *                 ],
+ *                 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_SearchAgentConfigurationData<T> = SearchAgentConfigurationData<T>;
-type index_SearchAgentRegistrationConfig = SearchAgentRegistrationConfig;
+type index_Agent = Agent;
+type index_AgentFeatures = AgentFeatures;
+type index_AgentRegistrationConfig = AgentRegistrationConfig;
+type index_AgentSearchFilter = AgentSearchFilter;
+declare const index_InteropColorChannel: typeof 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_getAgentConfiguration: typeof getAgentConfiguration;
+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_SearchAgentConfigurationData as SearchAgentConfigurationData, 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_getAgentConfiguration as getAgentConfiguration, 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, index_InteropColorChannel as InteropColorChannel, type index_OnSearchActionListener as OnSearchActionListener, type index_OnSearchRequestListener as OnSearchRequestListener, type index_SearchListenerRequest as SearchListenerRequest, type index_SearchResult as SearchResult, index_getConfiguration as getConfiguration, index_register as register };
 }
 
 declare global {
@@ -609,4 +947,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 };