@interopio/search-api/README.md

Glue42 Search API

# IO Connect Search API

Apps can perform searches and provide results for others' searches.

For example, let's say an app provides Seinfeld quotes, and wants to make those quotes available to any other app. The Seinfeld app could register itself as a search provider with this:

```js
// Registering as a provider
const provider = await glue.search.registerProvider({
    name: "Seinfeld-Quotes"
});

// Registering how the provider will respond to queries
provider.onQuery(({search, sendResults, done}) => {
    const textOfQuote = doStuffInternally(search);
    
    sendResults({
        type: {
            name: "tv-quote",
            displayName: "Seinfeld Quotes"
        },
        id: "quote-123",
        description: textOfQuote
    });

    done();
})
```

Now, let's say an app is interested to see if there are any Seinfeld quotes with the word "architect". It would use the following function:

```js
const query = await glue.search.query({search: "architect"});
query.onResults((result) => {
/*
// Example value for result - 
{
    provider: {
        id: "INTERNAL_ID",
        interopId: "INTERNAL_INSTANCE_ID",
        name: "Seinfeld-Quotes"     // The search provider's name
        appName: "seinfeld-app",    // The app that registered the search provider
    },
    result: {
        type: {
            name: "tv-quote",
            displayName: "Seinfeld Quotes"
        },
        id: "quote-123",
        description: "You know I always wanted to pretend I was an architect.
    }
}
*/
})
```

## Checklists

If you're writing a custom search provider, here are things to make sure you implement:

Basics
- [ ] Registering provider
- [ ] Generate and send results

Other considerations:
- [ ] Call `done()` once you are done (in case queriers are waiting on `onCompleted()`)
- [ ] Are you checking the `types` property? You don't want to ignore the restrictions the querier placed on their query.
- [ ] Are you checking the `maxResults` property? You don't want to return more that the querier asked for.
- [ ] Ditto for `maxResultsByType`
- [ ] Did you set up error handling, and include the `error()` callback if necessary?
- [ ] Do your queries take a long enough time that they might get cancelled? If so, are you handling `onQueryCancel`?


If you're querying a search providerm here are things to make sure you implement:
- [ ] Call the query (eg `const query = await glue.search.query({search: "My search string"})`)
- [ ] Handle `onResults` (eg `query.onResults(displaySearchResult)`)
- [ ] Handle `onError`

Other considerations:
- [ ] Is there a situation where you need to `cancel()` your query?
- [ ] Do you need to limit the quantity of results you receive (using `providerLimits`)?
- [ ] Do you need `onCompleted`, to see when different search providers have finished? If so, does it also make sense to include a timeout (in case a search provider *doesn't* indicate when they're `done()`?)
- [ ] Are you interested in only certain **types** of content? Would it make sense to call `listTypes()` to see if the type you're looking is being provided? Would it makse sense to limit your search results to a certain type?
- [ ] Are you interested in only certain **providers**? Would it make sense to call `listProviders()` to see if the provider you're looking is present? Would it makse sense to limit your search results to certain providers?
- [ ] Sometimes, search results include `actions`. If that makes sense for your use cases, are you handling incoming actions?


## API

glue.search has the following methods:
- getDebounceMS
- listProviders
- listTypes
- query
- registerProvider
- setDebounceMS
- version

### registerProvider

Config options for `.registerProvider()` are:
- `name` (required)
- `types` (optional but recommended). If you register a custom type, it will appear in the `.listTypes` method.

```js
const provider = await glue.search.registerProvider({name: "test"});
```

```js
const provider = await glue.search.registerProvider({
    name: "test", 
    types: [
        {name: "application"}
    ]
});
```

`registerProvider` returns a promise that resolves to a `Provider` object. This has the following available methods:
- `onQuery` - callback when search queries are executed
- `onQueryCancel` - callback when an app cancels its search query
- `unregister` - an unregistration method. 

:::tip
Search providers are automatically unregistered when windows are closed. Unregistration is a good cleanup action, but may not be required.
:::

The `onQuery` callback provides a `ProviderQuery` object, with the following properties:
- id - referenced when cancelling the query
- search - the text being searched for
- providers - the providers the querier is interested in
- types - the SearchTypes the querier is interested in
- providerLimits.maxResults - the maximum number of results the querier wants to receive from each provider
- providerLimits.maxResultsPerType - the maximum number of results PER TYPE the querier wants to recevie from each provider
- sendResult - callback for sending an individual result. (The querier receives this with the `query.onResults()` callback)
- error - callback if there's an error (The querier receives this with the `query.onError()` callback)
- done - callback once all results have been sent (The querier receives this with the `query.done()` callback)

When sending a result, you supply a `QueryResult` object. The properties of that object are:
- type (required) - a `SearchType` (eg: `{name: "application"}`)
- id
- displayName
- description
- iconURL
- metadata
- action - metadata information about a method you'd want to invoke
- secondaryActions - more actions

### query

You create a query object with the `query()` method:
```js
const query = await glue.search.query({search: "My search query"});
```

The `query` method takes the following properties:
- `search` (required) (string) - what you're searching for
- `providers` (`ProviderData[]`) - providers you want to limit your search to
- `types` (`SearchType[]`) - the types of results you want to limit your search to
- `providerLimits.maxResults` (number) - the maximum number of results the querier wants to receive from each provider
- `providerLimits.maxResultsPerType` (number) - the maximum number of results PER TYPE the querier wants to recevie from each provider


The query object you receive has the following methods:
- `cancel()` - Cancels the query. (See provider's `onQueryCancel()`)
- `onResults()` - Callback to receive results (See provider's query handling for `sendResult()`)
- `onCompleted()` - Callback when provider is done (See provider's query handling for `done()`)
- `onError()` - Callback when provider has an error (See provider's query handling for `error()`)

### listProviders

```js
await glue.search.listProviders();
/*
Example results: [
    {
        appName: "fsbl-test-butler",
        id: "INTERNAL_ID",
        interopId: "INSTANCE_ID",
        name: "registered-search-provider-custom-name",
    },
    {
        appName: "tester",
        id: "INTERNAL_ID",
        interopId: "INSTANCE_ID",
        name: "my-tester",
        types: [{name: "test-type"}]
    }
]
*/
```

### listTypes

You can see what search types are available. This is especially useful if you are relying on a custom search type from another app, and want to confirm that that app has already been registered.

```js
await glue.search.listTypes();
/*
Example results: [
    {name: "customSearchType"},
    {name: "application"},
    {name: "layout"},
    {name: "workspace"},
    {name: "swimlane"},
    {name: "action"}
]
*/
```

### getDebounceMS, setDebounceMS

**Default debounce: 0ms**

Queries can be debounced. If you plan on querying based on individual keystrokes or mouse movements, you can potentially generate an unnecessarily large message flurry. Debouncing the queries will reduce search query traffic.

Here are examples of getting/setting the debounce time:
```js
// Get the debounce time:
glue.search.getDebounceMS();    // returns 0 by default

// Set the debounce time to 20ms:
glue.search.setDebounceMS(20);
```

## Actions
TBD


## Developer notes

/* eslint-disable @typescript-eslint/no-explicit-any */

// package name: @interopio/search-api -> adds the Search API

// @interopio/browser-platform -> can use the package to register as a provider or use as a client, by default register as a provider for applications, workspaces, layouts and optionally actions
// @interopio/browser -> can use the package to register as a provider or use as a client
// GD3 -> by default register as a provider for applications, workspaces, layouts and optionally actions

// Foundation: Interop and Shared Context
// lib registers: lazily two methods
// lib uses: shared context to providers state management
// method used when registered as provider to accept queries

// category = display name for type