@interopio/search-api/search.d.ts

Glue42 Search API

/* eslint-disable @typescript-eslint/no-explicit-any */
import { IOConnectCore } from "@interopio/core";

/**
 * @docname Search
 * @intro
 * The Search API offers two distinct functionalities: you can use it to create both search providers and search clients.
 * Search providers are apps that respond to search queries, whereas search clients are apps that initiate searches.
 * For instance, a search provider may return a list of instruments as a response to a search query, and may also support
 * one or more actions - like showing a chart for the selected instrument. Actions may be executed when the user clicks
 * on a result in the UI of a search client app. You may present multiple actions as options to the user via the search
 * client UI, so that they may choose how to handle the search result depending on their current needs.
 * The Search API also enables you to define search types, set debounce time for search queries,
 * set limits for search results and more.
 *
 * The Search API is accessible via the `io.search` object.
 */
export namespace IOConnectSearch {

    /**
     * @ignore
     */
    export interface Config {} // eslint-disable-line @typescript-eslint/no-empty-interface

    /**
     * Search API.
     */
    export interface API {

        /**
         * Search API version.
         */
        version: string;

        /**
         * Sets the debounce interval for search queries.
         * @param milliseconds Interval in milliseconds to use as debounce interval.
         */
        setDebounceMS(milliseconds: number): void;

        /**
         * Retrieves the current debounce interval for search queries.
         */
        getDebounceMS(): number;

        /**
         * Retrieves a list of all available search providers.
         */
        listProviders(): Promise<ProviderData[]>;

        /**
         * Retrieves a list of all available search types from all search providers.
         */
        listTypes(): Promise<SearchType[]>;

        /**
         * Creates a search query.
         * @param queryConfig Settings for creating a search query.
         */
        query(queryConfig: QueryConfig): Promise<Query>;

        /**
         * Registers a search provider.
         * @param config Settings for registering a search provider.
         */
        registerProvider(config: ProviderRegistrationConfig): Promise<Provider>;
    }

    /**
     * Describes a created search query.
     */
    export interface Query {

        /**
         * Cancels the search query.
         */
        cancel(): Promise<void>;

        /**
         * Notifies when a batch with results from the search query is received.
         * @param callback Callback function for handling the event. Receives as an argument an object holding
         * a list of the available search result and details about the search provider that has sent the results.
         */
        onResults(callback: (resultBatch: QueryResultBatch) => void): UnsubscribeFunction;

        /**
         * Notifies when the search query is completed, i.e. when all search operations
         * in all search providers have been completed.
         * @param callback Callback function for handling the event.
         */
        onCompleted(callback: () => void): UnsubscribeFunction;

        /**
         * Notifies when there is an error in the search process.
         * @param callback Callback function for handling the event. Receives as an argument an object holding
         * the error message sent by the search provider and data describing the provider that has sent the error.
         */
        onError(callback: (error: QueryError) => void): UnsubscribeFunction;
    }

    /**
     * Describes a registered search provider.
     */
    export interface Provider extends ProviderData {

        /**
         * Notifies when a search query is received.
         * @param callback Callback function for handling the event. Receives as an argument an object describing the search query.
         */
        onQuery(callback: (query: ProviderQuery) => void): UnsubscribeFunction;

        /**
         * Notifies when a search query is canceled.
         * @param callback Callback function for handling the event. Receives as an argument an object with an `id` property
         * holding the ID of the canceled search query.
         */
        onQueryCancel(callback: (query: { id: string }) => void): UnsubscribeFunction;

        /**
         * Unregisters the search provider from the framework.
         */
        unregister(): Promise<void>;
    }

    /**
     * Search provider details.
     */
    export interface ProviderData {

        /**
         * Unique ID of the Interop instance of the app.
         */
        interopId: string;

        /**
         * Unique app ID within the framework.
         */
        id: string;

        /**
         * Name of the search provider.
         */
        name: string;

        /**
         * Name of the app that has registered the search provider.
         */
        appName?: string;

        /**
         * List of search types with which the search provider works.
         */
        types?: SearchType[];
    }

    /**
     * Settings for creating a search query.
     */
    export interface QueryConfig {

        /**
         * String for which to query the search providers.
         */
        search: string;

        /**
         * List of search providers to query.
         */
        providers?: ProviderData[];

        /**
         * List of search types in which the search client app is interested.
         */
        types?: SearchType[];

        /**
         * Specifies the maximum total results and/or the maximum results per search type to return.
         */
        providerLimits?: ProviderLimits;
    }

    /**
     * Describes the search query received by the search provider and provides methods for responding to it.
     */
    export interface ProviderQuery extends QueryConfig {

        /**
         * ID for the search query (assigned by the framework).
         */
        id: string;

        /**
         * Sends individual results back to search clients.
         * @param result Individual search result to send back to search clients.
         */
        sendResult(result: QueryResult): void;

        /**
         * Sends errors back to search clients.
         * @param error Error message to send back to search clients.
         */
        error(error: string): void;

        /**
         * Signals the framework that the search operation has been completed.
         */
        done(): void;
    }

    /**
     * Settings for registering a search provider.
     */
    export interface ProviderRegistrationConfig {

        /**
         * Name for the search provider.
         */
        name: string;

        /**
         * Search types with which the provider works.
         */
        types?: SearchType[];
    }

    /**
     * Describes a batch of search results received by search clients.
     */
    export interface QueryResultBatch {

        /**
         * List of individual search results received by search clients.
         */
        results: QueryResult[];

        /**
         * Details about the search provider that has sent the results.
         */
        provider?: ProviderData;
    }

    /**
     * Describes a search operation error received by search clients.
     */
    export interface QueryError {

        /**
         * Error message.
         */
        error: string;

        /**
         * Details about the search provider that has sent the error.
         */
        provider?: ProviderData;
    }

    /**
     * Describes the maximum total results and/or the maximum results per search type to return.
     */
    export interface ProviderLimits {

        /**
         * Maximum total results per search operation to return.
         */
        maxResults?: number;

        /**
         * Maximum results per search type to return.
         */
        maxResultsPerType?: number;
    }

    /**
     * Describes an individual search result received by search clients.
     */
    export interface QueryResult {

        /**
         * The predefined search type of the result.
         */
        type: SearchType;

        /**
         * ID for the search result that can be used by the search client when handling the result.
         */
        id?: string;

        /**
         * Display name for the search result that can be used in a UI.
         */
        displayName?: string;

        /**
         * Description for the search result that can be used in a UI.
         */
        description?: string;

        /**
         * URL pointing to an icon for the search result that can be used in a UI.
         */
        iconURL?: string;

        /**
         * Metadata for the search result that can be used by the search client when handling the result.
         */
        metadata?: any;

        /**
         * A main action that can be used to invoke an already registered Interop method when the user clicks on the search result displayed in a UI.
         * If you need to define multiple actions when handling search results, you can use the `secondaryActions` property instead.
         */
        action?: MainAction;

        /**
         * Secondary actions can be used to invoke different already registered Interop methods if, for example, you want to present the user
         * with a choice of options related to the search result. The `secondaryActions` property can be used independently,
         * without defining a `MainAction` in the `action` property.
         */
        secondaryActions?: SecondaryAction[];
    }

    /**
     * Describes an already registered Interop method to be assigned as a main action to a search result.
     * This allows search clients to invoke the specified Interop method if, for example, the user clicks on the search result in a UI.
     */
    export interface MainAction {

        /**
         * Name of an Interop method to assign as an action for a search result.
         */
        method: string;

        /**
         * Defines the Interop servers that will be targeted when invoking the specified method. Set to `"all"` to invoke the method on all Interop servers offering it.
         * Alternatively, you can pass the Interop ID of a specific Interop server you want to target.
         */
        target?: { instance: string } | "all";

        /**
         * Arguments to be passed to the specified Interop method when a search client invokes it.
         */
        params?: any;
    }

    /**
     * Describes an already registered Interop method to be assigned as a secondary action to a search result.
     */
    export interface SecondaryAction extends MainAction {

        /**
         * Name for the assigned action. May be used to differentiate between actions on the client side.
         */
        name: string;
    }

    /**
     * Describes an entity with which a search provided works.
     */
    export interface SearchType {

        /**
         * Name for the search type.
         */
        name: string;

        /**
         * User-friendly name for the search type that can be displayed in UIs.
         */
        displayName?: string;
    }

    /**
     * Function that can be used to stop receiving notifications about events.
     */
    type UnsubscribeFunction = () => void;
}

export type IOConnectSearchFactoryFunction = (io: IOConnectCore.API, config?: IOConnectSearch.Config) => Promise<void>;
declare const IOSearch: IOConnectSearchFactoryFunction;
export default IOSearch;