@openfin/cloud-api 0.0.1-alpha.0034b20

package/dist/index.d.cts

@@ -0,0 +1,559 @@
+import * as OpenFin from '@openfin/core';
+import OpenFin__default from '@openfin/core';
+import * as NotificationsTypes from '@openfin/workspace/notifications';
+
+/**
+ * NotificationsClient is a client for accessing and interacting with the Notifications your application has created.
+ */
+type NotificationsClient = {
+    /**
+     * Adds an event listener to the Notifications service.
+     *
+     * @param event the event name to listen for
+     * @param callback the callback to be invoked when the event is emitted
+     */
+    addEventListener<T extends keyof NotificationEventsMap>(event: T, callback: NotificationEventsMap[T]): void;
+    /**
+     * Removes an event listener from the Notifications service.
+     *
+     * @see {NotificationsClient.addEventListener}
+     *
+     * @remarks If the listener is not found, a warning will be logged to the console.
+     */
+    removeEventListener<T extends keyof NotificationEventsMap>(event: T, callback: NotificationEventsMap[T]): void;
+    /**
+     * Creates a new Notification.
+     *
+     * @remarks `id` should __not__ be provided. Instead, use the id property of the returned notification object. If you supply and `id` property, it will be ignored, with a warning logged to the console.
+     *
+     * @param args
+     */
+    createNotification(...args: Parameters<typeof NotificationsTypes.create>): ReturnType<typeof NotificationsTypes.create>;
+    /**
+     * Updates an existing Notification.
+     */
+    update(...args: Parameters<typeof NotificationsTypes.update>): ReturnType<typeof NotificationsTypes.update>;
+    /**
+     * Clears a Notification with the specified id.
+     */
+    clear(...args: Parameters<typeof NotificationsTypes.clear>): ReturnType<typeof NotificationsTypes.clear>;
+};
+/**
+ * @internal
+ */
+type FlannelCreateNotificationRequest = {
+    version: 1;
+    payload: {
+        notification: NotificationsTypes.NotificationOptions;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelCreateNotificationResponse = {
+    version: 1;
+    payload: {
+        response: NotificationsTypes.Notification<NotificationsTypes.NotificationOptions>;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelUpdateNotificationRequest = {
+    version: 1;
+    payload: {
+        notification: NotificationsTypes.UpdatableNotificationOptions;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelUpdateNotificationResponse = {
+    version: 1;
+    payload: {
+        response: NotificationsTypes.Notification;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelClearNotificationRequest = {
+    version: 1;
+    payload: {
+        notificationId: string;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelClearNotificationResponse = {
+    version: 1;
+    payload: {
+        response: boolean;
+    };
+};
+/**
+ * @internal
+ */
+type FlannelProvider = {
+    'openfin-cloud-create-notification': (arg0: FlannelCreateNotificationRequest) => Promise<FlannelCreateNotificationResponse>;
+    'openfin-cloud-update-notification': (arg0: FlannelUpdateNotificationRequest) => Promise<FlannelUpdateNotificationResponse>;
+    'openfin-cloud-clear-notification': (arg0: FlannelClearNotificationRequest) => Promise<FlannelClearNotificationResponse>;
+};
+type NotificationEventsMap = {
+    'notification-form-values-changed': (event: NotificationsTypes.NotificationFormValuesChangedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-form-submitted': (event: NotificationsTypes.NotificationFormSubmittedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-action': (event: NotificationsTypes.NotificationActionEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-created': (event: NotificationsTypes.NotificationCreatedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-toast-dismissed': (event: NotificationsTypes.NotificationToastDismissedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-closed': (event: NotificationsTypes.NotificationClosedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notifications-count-changed': (event: NotificationsTypes.NotificationsCountChanged & {
+        timestamp: Date;
+    }) => void;
+    'notification-reminder-created': (event: NotificationsTypes.NotificationReminderCreatedEvent & {
+        timestamp: Date;
+    }) => void;
+    'notification-reminder-removed': (event: NotificationsTypes.NotificationReminderRemovedEvent & {
+        timestamp: Date;
+    }) => void;
+};
+/**
+ * @internal
+ */
+type FlannelClient = {
+    'openfin-cloud-event': <T extends keyof NotificationEventsMap>(arg0: {
+        type: T;
+        payload: Parameters<NotificationEventsMap[T]>[0];
+    }) => void;
+};
+/**
+ * @internal
+ */
+type FlannelChannelProvider = {
+    /**
+     * @internal
+     */
+    dispatch: <T extends keyof FlannelClient>(to: OpenFin__default.ClientIdentity | OpenFin__default.Identity, action: T, payload: Parameters<FlannelClient[T]>[0]) => Promise<Awaited<ReturnType<FlannelClient[T]>>>;
+    /**
+     * @internal
+     */
+    register: <T extends keyof FlannelProvider>(action: T, handler: (payload: Parameters<FlannelProvider[T]>[0], id: OpenFin__default.ProviderIdentity | OpenFin__default.ClientIdentity) => ReturnType<FlannelProvider[T]>) => boolean;
+} & Omit<OpenFin__default.ChannelProvider, 'dispatch' | 'register'>;
+
+/**
+ * @returns A client for interacting with the OpenFin Notifications service
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ * @throws {Error} If the app UUID cannot be extracted from the current context
+ *
+ * @example **Basic Usage** Creating a notification, updating it and then clearing it
+ * ```ts
+ * const notificationsClient = await getNotificationsClient();
+ *
+ * const notification = await notificationsClient.createNotification({
+ *     title: 'Hello, World!',
+ *     body: 'This is a notification from the OpenFin Cloud API',
+ * });
+ *
+ * // Use the `id` from the returned notification to interact with it
+ * console.log(notification.id);
+ *
+ * // Update the notification
+ * await notificationsClient.update({
+ *     id: notification.id,
+ *     body: 'This is a notification from the OpenFin Cloud API, that has been updated!',
+ * })
+ *
+ * // Clear the notification
+ * await notificationsClient.clear(notification.id);
+ * ```
+ *
+ * @example **Advanced Usage** Listening for events
+ * ```ts
+ * const notificationsClient = await getNotificationsClient();
+ *
+ * // create the notification
+ * const notification = await notificationsClient.createNotification({
+ *     title: `${window.fin.me.identity.name} Hello, World!`,
+ *     body: `This is a notification from the cloud API example created at ${new Date().toLocaleTimeString()}`,
+ *     buttons: [
+ *         {
+ *             title: 'Acknowledge',
+ *         },
+ *     ],
+ * });
+ *
+ * notificationsClient.addEventListener('notification-action', (event) => {
+ *     console.log('Notification action:', event);
+ * });
+ * ```
+ */
+declare function getNotificationsClient(): Promise<NotificationsClient>;
+
+/**
+ * Represents a collection of returned app permissions
+ */
+type AppPermissions = {
+    permissions: {
+        /**
+         * The name of the permission
+         */
+        name: string;
+        /**
+         * The ID of the permission
+         */
+        id: string;
+    }[];
+};
+/**
+ * @returns The app settings that have been set against the current app
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ */
+declare function getAppSettings(): Promise<unknown>;
+/**
+ * @returns The app settings that have been set against the current app for the current user
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ */
+declare function getAppUserSettings(): Promise<unknown>;
+/**
+ * Assigns a set of user specific settings to the current app
+ *
+ * @returns The app settings that have been set against the current app for the current user
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ */
+declare function setAppUserSettings(settings: unknown): Promise<unknown>;
+/**
+ * @returns The permissions that have been set against the current app for the current user
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ */
+declare function getAppUserPermissions(): Promise<AppPermissions>;
+type LaunchContentOptions = {
+    /** Object containing query param values to be appended to content's URL  */
+    queryParams?: Record<string, string>;
+    /** Defines behavior when instance of content is already running.
+     * If 'multi', copy of the content will be created.
+     * If 'single', the existing instance of content will be focused. */
+    instanceMode?: 'single' | 'multi';
+} & ({
+    targetType?: 'new-window';
+    /** Defines the bounds of the window in which content will open */
+    bounds?: Partial<OpenFin__default.Bounds>;
+} | {
+    targetType: 'window' | 'view';
+    targetIdentity: OpenFin__default.Identity;
+});
+/**
+ * A function allowing the easy launching of content
+ * @param id The id of the content to launch
+ * @returns nothing
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ * @throws {Error} If the function has been unable to look up or launch the content
+ * @throws {Error} If the function is unable to find content with the provided id.
+ */
+declare function launchContent(id: string, options: LaunchContentOptions): Promise<void>;
+/**
+ * A function allowing the easy launching of Supertabs
+ * @param id The id of supertab
+ * @returns nothing
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ * @throws {Error} If the function has been unable to look up or launch the supertab
+ * @throws {Error} If the function is unable to find supertab with the provided id.
+ */
+declare function launchSupertab(id: string): Promise<void>;
+/**
+ * A function allowing the easy launching of Workspaces
+ * @param id The id of workspace
+ * @returns nothing
+ *
+ * @throws {Error} If the function is called outside of an OpenFin environment
+ * @throws {Error} If the function is called outside of an OpenFin View context
+ * @throws {Error} If the function has been unable to look up or launch the workspace
+ * @throws {Error} If the function is unable to find workspace with the provided id.
+ */
+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.
+ *
+ * @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 OnActionListener = (action: SearchAction, result: SearchResult) => SearchResultActionResponse | Promise<SearchResultActionResponse>;
+/**
+ * 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>;
+/**
+ * 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 = {
+    /**
+     * 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 OnActionListener}.
+     */
+    name: string;
+    /**
+     * Compact title of the action displayed within the action button.
+     */
+    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.
+ */
+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`).
+     */
+    isReady: (ready?: boolean) => Promise<void>;
+};
+/**
+ * Configuration provided when registering a Search Agent.
+ */
+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.
+     *
+     * 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.
+     *
+     * Note: When the Search Agent is not ready this listener will not be called.
+     */
+    onSearch: OnSearchListener;
+};
+/**
+ * Search request data provided to the {@link OnSearchListener}.
+ */
+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 OnSearchListener} 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 = {
+    /**
+     * The page number of the search results to return.
+     */
+    pageNumber: number;
+    /**
+     * The number of search results to return per page.
+     */
+    pageSize: number;
+};
+/**
+ * Return type of the {@link OnSearchListener}.
+ */
+type SearchResponse = {
+    /**
+     * The search results to display in Here™’s search UI.
+     */
+    results: SearchResult[];
+};
+/**
+ * A search result returned by a Search 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 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.
+     */
+    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 OnActionListener}.
+ */
+type SearchResultActionResponse = {
+    /**
+     * URL that Here™ should navigate to.
+     */
+    url: string;
+} | undefined;
+
+/**
+ * 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.
+ *
+ * @returns A promise that resolves with the Search Agent.
+ *
+ * @example Registering a basic Search Agent:
+ * ```ts
+ * // Handle incoming action and return a response that includes the URL to navigate to
+ * const onAction: Search.OnActionListener = (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: Search.OnSearchListener = ({ context, query, signal }) => {
+ *     const { pageNumber, pageSize } = context;
+ *     try {
+ *         let results: Search.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 search agent
+ * const searchAgent = await Search.register({ onAction, onSearch });
+ *
+ * // Set the Search Agent as ready to receive search requests
+ * await searchAgent.isReady();
+ * ```
+ */
+declare function register(config: SearchAgentRegistrationConfig): Promise<SearchAgent>;
+
+type index_OnActionListener = OnActionListener;
+type index_OnSearchListener = OnSearchListener;
+type index_SearchAction = SearchAction;
+type index_SearchAgent = SearchAgent;
+type index_SearchAgentRegistrationConfig = SearchAgentRegistrationConfig;
+type index_SearchListenerRequest = SearchListenerRequest;
+type index_SearchRequestContext = SearchRequestContext;
+type index_SearchResponse = SearchResponse;
+type index_SearchResult = SearchResult;
+type index_SearchResultActionResponse = SearchResultActionResponse;
+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 };
+}
+
+declare global {
+    interface Window {
+        fin: typeof OpenFin.fin;
+    }
+}
+
+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 };