@openfin/workspace-platform 4.3.0 → 4.7.0

package/search-api/src/common.d.ts

@@ -0,0 +1,104 @@
+import { InternalSearchListenerRequest, InternalSearchListenerResponse } from './internal-shapes';
+import { Action, DeregisterListener, DispatchedSearchResult, Identity, RegisterListener, ScoreOrder, SearchProvider, SearchRequest, SearchResult } from './shapes';
+export declare const defaultSearchTopic = "all";
+/**
+ * The stream id that data is requested and transported back to the creator of a search topic on.
+ */
+export declare const remoteProviderDataStreamId = "0";
+/**
+ * The stream id that handles search request to the creator of a search topic from remote client like views.
+ */
+export declare const remoteClientSearchStreamId = "1";
+/**
+ * The stream id for registering a remote search provider with the creator of a search topic.
+ */
+export declare const remoteProviderRegistrationStreamId = "2";
+/**
+ * The stream id for deregistering a remote search provider with the creator of a search topic.
+ */
+export declare const remoteProviderDeregistrationStreamId = "3";
+/**
+ * The stream id for sharing remote search provider information with the creator of a search topic.
+ */
+export declare const remoteProviderInfoStreamId = "4";
+/**
+ * The stream id for dispatching search results back to a remote search provider.
+ */
+export declare const remoteProviderDispatchStreamId = "5";
+/**
+ * The stream id for notifying remote search providers that the request have closed.
+ */
+export declare const remoteSearchCloseStreamId = "6";
+export declare const noop: () => void;
+/**
+ * Apply given namespace to topic.
+ * @param namespace the namespace to apply.
+ * @param topicId the original topic id.
+ */
+export declare function getNamespacedTopic(namespace: string, topicId: string): string;
+/**
+ * Get the channel name for search topic.
+ * @param namespacedTopic the namespaced search topic id.
+ */
+export declare function getTopicChannelName(namespacedTopic: string): string;
+export declare function addRegisterListener(namespacedTopic: string, listener: RegisterListener): void;
+export declare function removeRegisterListener(namespacedTopic: string, listener: RegisterListener): void;
+export declare function addDeregisterListener(namespacedTopic: string, listener: DeregisterListener): void;
+export declare function removeDeregisterListener(namespacedTopic: string, listener: DeregisterListener): void;
+/**
+ * Add a provider.
+ * @param namespacedTopic the namespaced search topic to register the provider on.
+ * @param provider the search provider to register.
+ */
+export declare function addProvider(namespacedTopic: string, provider: SearchProvider): void;
+/**
+ * Remove a provider.
+ * @param namespacedTopic the namespaced search topic of the provider.
+ * @param id the id of the provider.
+ */
+export declare function removeProvider(namespacedTopic: string, id: string): void;
+/**
+ * Get all providers for a topic.
+ * @param namespacedTopic the namespaced search topic.
+ */
+export declare function getProviders(namespacedTopic: string): SearchProvider[];
+/**
+ * Clears all search providers for a search topic.
+ * @param namespacedTopic the namespaced search topic.
+ */
+export declare function clearProviders(namespacedTopic: string): void;
+/**
+ * Get a provider for a topic.
+ * @param namespacedTopic the namespaced search topic that the provider is registered on.
+ * @param name the name of the search provider.
+ */
+export declare function getProvider(namespacedTopic: string, id: string): SearchProvider | null;
+/**
+ * Make a dispatched search result.
+ * @param result the original search result.
+ * @param action the action this search result is dispatched with.
+ */
+export declare function makeDispatchedSearchResult(result: SearchResult, dispatcherIdentity: Identity, actionParam?: Action): DispatchedSearchResult;
+/**
+ * Algorithm for aggregating search results.
+ *
+ * Any search results in the old set of results will be replaced with
+ * new search results if their `key` field matches.
+ *
+ * The array will then be sorted by `score`.
+ */
+export declare function aggregate(oldResultsParam: SearchResult[], newResults: SearchResult[], order?: ScoreOrder): SearchResult[];
+/**
+ * Creates a wrapper around a search listener response that can be used internally
+ * to listen for search results that were added to the buffer or response status changes.
+ * @param scoreOrder the order to aggregate search results in.
+ */
+export declare function makeInternalSearchListenerResponse(scoreOrder?: ScoreOrder): InternalSearchListenerResponse;
+/**
+ * Creates a wrapper around a search listener request that can be used
+ * internally to close the request.
+ * @param topic the topic the search request was dispatched on.
+ * @param id the id of the search request.
+ * @param req the search request.
+ */
+export declare function makeInternalSearchListenerRequest(topic: string, id: string, req: SearchRequest): InternalSearchListenerRequest;

package/search-api/src/errors.d.ts

@@ -0,0 +1,5 @@
+export declare const providerNotExist: Error;
+export declare const providerExists: Error;
+export declare const badPayload: Error;
+export declare const subscriptionRejected: Error;
+export declare const channelNotExist: Error;

package/search-api/src/fin/index.d.ts

@@ -0,0 +1,6 @@
+import type { Identity } from '../shapes';
+import type { Channel, ChannelClient } from './shapes';
+export declare function getIdentity(): Identity;
+export declare function getPlatformNamespace(): string | undefined;
+export declare function connectToChannel(name: string): Promise<ChannelClient>;
+export declare function createChannel(name: string): Promise<Channel>;

package/search-api/src/fin/shapes.d.ts

@@ -0,0 +1,23 @@
+import type { Identity } from '../shapes';
+export declare type MessageListener = (message: any, identity: Identity) => any;
+export declare type ConnectionListener = (identity: Identity) => Promise<void>;
+/**
+ * Represents a channel client.
+ */
+export interface ChannelClient {
+    register(topic: string, listener: MessageListener): void;
+    dispatch(topic: string, message: any): Promise<any>;
+    disconnect(): Promise<void>;
+    onDisconnection(listeber: ConnectionListener): void;
+}
+/**
+ * Represents a channel.
+ */
+export interface Channel {
+    register(topic: string, listener: MessageListener): void;
+    publish(topic: string, message: any): Promise<void>;
+    dispatch(to: Identity, topic: string, message: any): Promise<any>;
+    onConnection(listener: ConnectionListener): void;
+    onDisconnection(listener: ConnectionListener): void;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,7 @@
+import * as client from './client';
+import * as provider from './provider';
+export declare const create: typeof provider.create;
+export declare const subscribe: typeof client.subscribe;
+export declare const defaultTopic = "all";
+export type { SearchProviderResponse, SearchRequest, SearchTopicClient, SearchTopic, SearchProviderInfo, ScoreOrder, Action, SearchResult, SearchListenerRequest, SearchListenerResponse, UserInputListener, DispatchedSearchResult, ResultDispatchListener, SearchProvider, SearchTopicSubscribeRequest, SearchTag, SearchResponse } from './shapes';
+export { SearchTagBackground } from './shapes';

package/search-api/src/internal-shapes.d.ts

@@ -0,0 +1,134 @@
+import type { DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProviderResponse, SearchProviderResponseGeneratorState, SearchRequest, SearchResponse, SearchResult } from './shapes';
+/**
+ * Message for dispatching a search request.
+ * This interface is used when sending a dispatch request from a remote OpenFin identity
+ * to the search topic creator.
+ */
+export interface InternalSearchRequest extends SearchRequest {
+    /**
+     * The id of the search request.
+     * On initial search request from remote provider, this ID is generated.
+     * The remote OpenFin identity is required to pass this id on all subsequent requests.
+     */
+    id?: string;
+}
+/**
+ * Response for a remote search request.
+ */
+export interface InternalSearchResponse {
+    /**
+     * The ID of the search request the response pertains to.
+     */
+    id: string;
+    /**
+     * True if the all search providers have responded to the search request.
+     */
+    done?: boolean;
+    /**
+     * The state of the search response generator.
+     */
+    state: SearchProviderResponseGeneratorState;
+    /**
+     * The current list of responses.
+     */
+    value: SearchProviderResponse[];
+}
+/**
+ * Close a search request.
+ * Used to notify search topic creator that a remote OpenFin identity has closed a search request.
+ */
+export interface InternalSearchCloseRequest {
+    /**
+     * The id of the remote search request to close.
+     */
+    id: string;
+}
+/**
+ * Request data from a specific remote search provider.
+ * This interface is used when requesting data from a search provider that is maintained in another OpenFin application.
+ */
+export interface InternalDataRequest {
+    id: string;
+    query: string;
+    context: any;
+    providerId: string;
+    targets: string[];
+}
+export declare enum InternalSearchListenerResponseStatus {
+    /**
+     * The intial status of a new search listener response object.
+     *
+     * Denotes that the search provider listener has not taken use of the search listener response object,
+     * as in `response.open()` nor `response.close()` has not been called yet.
+     */
+    Initial = 0,
+    /**
+     * Denotes that the search provider is done sending new or updated search results
+     * for the corresponding request.
+     */
+    Open = 1,
+    /**
+     * Denotes that the search provider is done sending new or updated search results
+     * for the corresponding request.
+     */
+    Close = 2
+}
+/**
+ * Respond to the provider data request with data.
+ * This interface is used when responding to the provider with data from datasources maintained in views.
+ */
+export interface InternalDataResponse extends SearchResponse {
+    id: string;
+    providerId: string;
+    revoked?: string[];
+    status?: InternalSearchListenerResponseStatus;
+}
+export interface InternalErrorResponse {
+    /**
+     * An error message, denoting that something went wrong.
+     */
+    error: string;
+}
+/**
+ * Dispatch search result back to provider with an action.
+ * This interface is used when dispatching a search result that came from a provider in another window or view.
+ */
+export interface InternalDispatchRequest {
+    result: DispatchedSearchResult;
+    providerId: string;
+}
+export interface InternalSearchListenerResponse {
+    getResultBuffer(): SearchResult[];
+    setResultBuffer(results: SearchResult[]): void;
+    getRevokedBuffer(): string[];
+    setRevokedBuffer(resultIds: string[]): void;
+    onChange(): void;
+    getStatus(): InternalSearchListenerResponseStatus;
+    res: SearchListenerResponse;
+}
+export interface InternalSearchListenerRequest {
+    close(): void;
+    req: SearchListenerRequest;
+}
+export interface InternalSearchResponseGeneratorHooks {
+    setState(state: SearchProviderResponseGeneratorState): void;
+}
+export interface InternalSearchTopicContext {
+    /**
+     * The search topic identifier passed via a `subscribe` or `create` call.
+     * This identifier is unique to the platform the search topic was created in.
+     */
+    topic: string;
+    /**
+     * The namespace of the search topic.
+     *
+     * This is used for scoping, such that two platform for example can declare
+     * the same topic ID without name collisions.
+     */
+    namespace: string;
+    /**
+     * The search topic concatenated with the namespace.
+     * This ID is unique across the desktop.
+     */
+    namespacedTopic: string;
+}

package/search-api/src/logger.d.ts

@@ -0,0 +1 @@
+export declare function error(err: Error): void;

package/search-api/src/provider/index.d.ts

@@ -0,0 +1,8 @@
+import type { SearchTopic, SearchTopicCreateRequest } from '../shapes';
+/**
+ * Create a topic.
+ * If the OpenFin identity creating the topic is running in a platform, the search topic will be sandboxed to the platform.
+ * In order to subscribe to a sandboxed search topic, the UUID of the platform must be specifed explicitly or the subscribing OpenFin identity must be running in the platform.
+ * @param req the topic create request.
+ */
+export declare function create(req?: string | SearchTopicCreateRequest): Promise<SearchTopic>;

package/search-api/src/provider/internal.d.ts

@@ -0,0 +1,33 @@
+import { InternalSearchTopicContext } from '../internal-shapes';
+import { Action, SearchProvider, SearchProviderInfo, SearchProviderResponseGeneratorExtended, SearchRequest, SearchResult } from '../shapes';
+/**
+ * Get all registered providers' info for an topic.
+ * @param namespacedTopic the namespaced search topic id.
+ */
+export declare function getAllProviders(namespacedTopic: string): SearchProviderInfo[];
+/**
+ * Register a provider.
+ * @param namespacedTopic the namespaced search topic to register the provider on.
+ * @param provider the provider to register.
+ */
+export declare function register(namespacedTopic: string, provider: SearchProvider): void;
+/**
+ * Deregister a provider.
+ * @param namespacedTopic the namespaced search topic to deregister the provider on.
+ * @param name the name of the search provider to deregister.
+ */
+export declare function deregister(namespacedTopic: string, name: string): void;
+/**
+ * Dispatch a search result back to the respective provider.
+ * @param namespacedTopic the namespaced search topic id.
+ * @param providerId the name of the provider to dispatch the result back to.
+ * @param result the search result to dispatch back to the provider.
+ * @param action the action to dispatch the search result with.
+ */
+export declare function dispatch(namespacedTopic: string, providerId: string, result: SearchResult, action: Action): Promise<void>;
+/**
+ * Returns an extended search generator object.
+ * @param ctx the search topic context.
+ * @param req the search request.
+ */
+export declare function search({ namespacedTopic, topic }: InternalSearchTopicContext, req: SearchRequest): SearchProviderResponseGeneratorExtended;

package/search-api/src/provider/remote/channel-factory.d.ts

@@ -0,0 +1,6 @@
+import { InternalSearchTopicContext } from '../../internal-shapes';
+/**
+ * Create a channel for interacting with remote search providers.
+ * @param ctx the context of the search topic to create the channel for.
+ */
+export declare function create(ctx: InternalSearchTopicContext): Promise<import("../../fin/shapes").Channel>;

package/search-api/src/provider/remote/channel.d.ts

@@ -0,0 +1,23 @@
+import type { Channel } from '../../fin/shapes';
+/**
+ * Get the OpenFin channel that represents a topic.
+ * If not found, will throw an error.
+ * @param topicId the search topic id.
+ */
+export declare function getOrFail(topicId: string): Channel;
+/**
+ * Get the OpenFin channel that represents a topic.
+ * @param topicId the search topic id.
+ */
+export declare function get(topicId: string): Channel;
+/**
+ * Set the OpenFin channel for a search topic.
+ * @param topic the search topic id.
+ * @param channel the channel for the search topic.
+ */
+export declare function set(topic: string, channel: Channel): void;
+/**
+ * Remove the channel corresponding to a search topic.
+ * @param topic the search topic.
+ */
+export declare function remove(topic: string): void;

package/search-api/src/provider/remote/connection.d.ts

@@ -0,0 +1,20 @@
+import { InternalSearchTopicContext } from '../../internal-shapes';
+import type { Identity, SubscriptionListener } from '../../shapes';
+/**
+ * Add a listener that is called whenever someone remotely subscribes to a search topic.
+ * @param namespacedTopic the namespaced search topic.
+ * @param listener the subscription listener to add.
+ */
+export declare function addSubscriptionListener(namespacedTopic: string, listener: SubscriptionListener): void;
+/**
+ * Remove a listener that is called whenever someone remotely subscribes to a search topic.
+ * @param namespacedTopic the namespaced search topic.
+ * @param listener the listener to remove.
+ */
+export declare function removeSubscriptionListener(namespacedTopic: string, listener: SubscriptionListener): void;
+/**
+ * Called when a remote OpenFin identity connects to a channel to listen on topic invocations.
+ * If a subscription listener registered for this search topic returns false, the request will be rejected.
+ * @param ctx the search topic context.
+ */
+export declare function makeStreamListener({ namespacedTopic }: InternalSearchTopicContext): (identity: Identity) => Promise<void>;

package/search-api/src/provider/remote/data.d.ts

@@ -0,0 +1,23 @@
+import { InternalDataResponse } from '../../internal-shapes';
+import type { DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProviderInfo } from '../../shapes';
+/**
+ * Listens for pushed new/updated remote search provider results or status changes.
+ * When a message is received, call all listeners corresponding to the response.
+ * @param namespacedTopic the namespaced search topic.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (res: InternalDataResponse) => void;
+/**
+ * Make a search listener for a remote search provider.
+ * This listener will be called by the provider when the topic is searched.
+ * When called, the listener waits and returns the response from the view for the data request.
+ * @param topicId the search topic for the listener.
+ * @param info the provider info.
+ */
+export declare function makeOnSearch(topicId: string, info: SearchProviderInfo): (request: SearchListenerRequest, response: SearchListenerResponse) => Promise<InternalDataResponse>;
+/**
+ * Make a dispatch result listener for a remote search provider.
+ * When called, the listener sends a result dispatch request to the underlying remote OpenFin identity.
+ * @param topicId the search topic id.
+ * @param info the remote search provider info.
+ */
+export declare function makeOnResultDispatch(topicId: string, info: SearchProviderInfo): (result: DispatchedSearchResult) => Promise<any>;

package/search-api/src/provider/remote/deregistration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Make a channel listener for deregistering remote search providers from search topics.
+ * @param namespacedTopic the namespaced search topic.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (name: string) => void;

package/search-api/src/provider/remote/disconnect.d.ts

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

package/search-api/src/provider/remote/disconnection.d.ts

@@ -0,0 +1,9 @@
+import type { DisconnectListener, Identity } from '../../shapes';
+export declare function addDisconnectListener(namespacedTopic: string, listener: DisconnectListener): void;
+export declare function removeDisconnectListener(namespacedTopic: string, listener: DisconnectListener): void;
+/**
+ * Called when a remote OpenFin identity disconnects from the channel for a search topic.
+ * Disconnecting will clean up all search providers correlated to the OpenFin identity.
+ * @param namespacedTopic the namespaced search topic id.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (identity: Identity) => Promise<void>;

package/search-api/src/provider/remote/dispatch.d.ts

@@ -0,0 +1,7 @@
+import type { InternalDispatchRequest } from '../../internal-shapes';
+import type { Identity } from '../../shapes';
+/**
+ * Make a channel listener for proxying search result dispatch from a remote OpenFin identity back to the respective provider.
+ * @param namespacedTopic the namespaced search topic id.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (req: InternalDispatchRequest, identity: Identity) => Promise<void>;

package/search-api/src/provider/remote/info.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Make a channel listener for sending search provider info to a remote OpenFin identity.
+ * @param namespacedTopic the context of the search topic to get the provider info from.
+ */
+export declare function makeStreamListener(namespacedTopic: string): () => Promise<import("../..").SearchProviderInfo[]>;

package/search-api/src/provider/remote/registration.d.ts

@@ -0,0 +1,23 @@
+import type { Identity, SearchProviderInfo } from '../../shapes';
+/**
+ * Add a remote search provider.
+ * @param topic the search topic to add the provider on.
+ * @param info the search provider info. Must include identity.
+ */
+export declare function addRemoteProvider(topic: string, info: SearchProviderInfo): void;
+/**
+ * Removes a remote search provider.
+ * @param topic the search topic id.
+ * @param name the name of the search provider.
+ */
+export declare function removeRemoteProvider(topic: string, id: string): void;
+/**
+ * Remove all search providers registered by the remote OpenFin identity.
+ * @param topic the search topic to remove the providers on.
+ * @param identity the identity that registered the remote search providers.
+ */
+export declare function removeRemoteProvidersForIdentity(topic: string, identity: Identity): void;
+/**
+ * Make a channel listener that allows remote OpenFin identities to register a search provider to a search topic.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (info: SearchProviderInfo, identity: Identity) => void;

package/search-api/src/provider/remote/search-close.d.ts

@@ -0,0 +1,14 @@
+import type { InternalSearchCloseRequest } from '../../internal-shapes';
+import type { Identity } from '../../shapes';
+/**
+ * Sends a message notifying a remote OpenFin identity that a search request has been closed.
+ * @param topicId the search topic id.
+ * @param identity the remote OpenFin identity to notify.
+ * @param requestId the search request id.
+ */
+export declare function sendRequestCloseToIdentity(topicId: string, identity: Identity, requestId: string): Promise<any>;
+/**
+ * Listen for search request close messages from remote providers.
+ * On message, close the remote search request.
+ */
+export declare function makeStreamListener(namespacedTopic: string): (req: InternalSearchCloseRequest) => void;

package/search-api/src/provider/remote/search.d.ts

@@ -0,0 +1,8 @@
+import type { InternalErrorResponse, InternalSearchRequest, InternalSearchResponse, InternalSearchTopicContext } from '../../internal-shapes';
+export declare function closeRemoteSearchRequest(topicId: string, requestId: string): void;
+/**
+ * Listen for search requests from remote OpenFin identities.
+ * On message, setup search generator that remote identity can check the status of in subsequent requests.
+ * @param namespacedTopic the search topic context.
+ */
+export declare function makeStreamListener(ctx: InternalSearchTopicContext): (request: InternalSearchRequest, ...p: any[]) => Promise<InternalSearchResponse | InternalErrorResponse>;