@lableb/javascript-sdk/README.md

Lableb cloud search client for javascript

# Lableb Cloud Search's Javascript Client

Javascript library built to ease your integration with [Lableb](https://lableb.com).

# Installation

```sh
yarn add @lableb/javascript-sdk
# OR
npm install @lableb/javascript-sdk
```

### Browsers

```html
<script src="https://unpkg.com/@lableb/javascript-sdk/dist/LablebSDK.min.js"></script>
```

For browser users you need to access `LablebClient` from `window.LablebSDK.LablebClient`.


```js
const lablebClient = window.LablebSDK.LablebClient();
```

### ES Module in browser 

For browser ESM module 

```html
<script type="module" src="https://unpkg.com/@lableb/javascript-sdk/dist/browser/index.esm.js"></script>
```


### Node.js 

```js
const { LablebClient } = require('@lableb/javascript-sdk');
```

or

```js
const LablebClient = require('@lableb/javascript-sdk').default;
```

### ESM

```js
import LablebClient from '@lableb/javascript-sdk';
```


# Overview

Lableb's client empower you with all the needed functions for a full search experience including: search, autocomplete, recommendation, indexing, deleting documents and send feedbacks.

It's usage made easy for new users with a very good defaults, and the more you need from it, the more options you can use to suits your advanced usages.

> Note: This library is built with [Promises](https://github.com/getify/You-Dont-Know-JS/blob/1st-ed/async%20%26%20performance/ch3.md), and basically all functions return promises, so stay tuned, and make your functions `async`hronous.

To start, just create your very first client instance

```js
const lablebClient = LablebClient();
```


Now `lablebClient` has all the functions needed for your application.

We'll do a simple search example:

```js
const { code, response, time } = await lablebClient.search({ 
  APIKey: API_KEY,
  platformName: PLATFORM_NAME,
  query: 'water',
});

const searchResults = response.results;
```

That's it, we just passed the required fields:
- Platform name
- API Key: used to authenticate your search request, visit [Lableb Dashboard](https://dashboard.lableb.com) to create a new one.
- query is what you're searching for, or basically your end-users' query.

Now you can do more than that, but sticking with the spirit of going fast and easy, that was all what you need.


# Options

When creating a new instance of the client you can pass nothing, or pass an option object which can save your time passing the same options over and over to the client's inner functions like search, autocomplete, recommend.


## Pass nothing

```js
const lablebClient = LablebClient();
```

Now for every inner function you have to pass at least an `API Key` and a `Platform Name`

Search

```js
const { code, response, time } = await lablebClient.search({ 
  APIKey: API_KEY,
  platformName: PLATFORM_NAME,
  query: 'water',
});
```

Autocomplete

```js
const { code, response, time } = await lablebClient.autocomplete({ 
  APIKey: API_KEY,
  platformName: PLATFORM_NAME,
  query: 'water',
});
```

And so on...

## Pass the global options

You noticed that we repeatedly passed the shared options to many functions, to end that repetition, you can pass any shared option you find in this library to the main `LablebClient` that create the instance for you, and you're all set and ready.

```js
const lablebClient = LablebClient({
  APIKey: API_KEY,
  platformName: PLATFORM_NAME,
});
```

Now for the other functions you just pass the required options


Search

```js
const { code, response, time } = await lablebClient.search({ 
  query: 'water',
});
```

Autocomplete

```js
const { code, response, time } = await lablebClient.autocomplete({ 
  query: 'water',
});
```

And so on...


## When passing options to an inner function might be useful?

Imagine you want to use the same options for all functions(search, autocomplete, recommend, ...etc) but for one function you have a single different option.

You can pass the unique option value only to this specific function call which will override the previously saved value(passed to `LablebClient` globally).

Example:

```js
const lablebClient = LablebClient({
  searchHandler: SEARCH_HANDLER_1,
});

const { code, response, time } = await lablebClient.search({ 
  searchHandler: SEARCH_HANDLER_2,
  query: 'water',
});
```

Now this search function call will have `searchHandler` value set to `SEARCH_HANDLER_2` as it override the global option passed to create the client.


## Options fields and types


Options pass to `LablebClient` are plain JS object, and all it's properties are optional

| property              | type   | default   | description |
| --------------------- | -------| --------- | --------------- |
| platformName          | string | -         | Your platform name as written at [Lableb Dashboard](https://dashboard.lableb.com) |
| indexName             | string | index     | The used data index name as created at [Lableb Dashboard \| Collections](https://dashboard.lableb.com) |
| APIKey                | string | -         | Search, Autocomplete, Recommend, and Feedback API Key |
| indexingAPIKey        | string | -         | Index, Delete API Key |
| searchHandler         | string | default   | The used search handler name as found at [Lableb Dashboard \| Collections \| Handlers](https://dashboard.lableb.com) |
| autocompleteHandler   | string | suggest   | The used autocomplete handler name as found at [Lableb Dashboard \| Collections \| Handlers](https://dashboard.lableb.com) |
| recommendHandler      | string | recommend | The used recommend handler name as found at [Lableb Dashboard \| Collections \| Handlers](https://dashboard.lableb.com) |
| interceptors          | array of functions | [] | pass an array of interceptors functions to manipulate the request before being sent to Lableb. [Read in details](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/interceptors.md) |
| userId                | string | -         | end user id |
| userIp                | string | -         | end user IP address |
| userCountry           | string | -         | end user country code(ISO-3166) |
| sessionId             | string | -         | uniques session Id for your end user |
| sessionIdGenerator    | function | -       | pass callback that generate unique session id string |


> Note: Creating API Key in [Lableb Dashboard]((https://dashboard.lableb.com))
>
> When creating a new API key, make sure you check "search" permission in order to make this key usable for search, autocomplete and recommend requests 

> Note: Creating Indexing API Key in [Lableb Dashboard]((https://dashboard.lableb.com))
>
> When creating a new Indexing API Key, make sure you check "index" permission in order to make this key usable in indexing, and delete requests


# Lableb's client API


## Search

Query your existing data at [Lableb](https://lableb.com) by sending text queries

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

const { code, response, time } = await lablebClient.search({
  query: 'water'
});

const searchResults = response.results;
```

Read about [Search API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/search.md) in details.






## Autocomplete

Get instant auto-complete results for the best typing experience for your end-users, where it can better help them find what they need.

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

const { code, response, time } = await lablebClient.autocomplete({
  query: 'wat'
});

const autocompleteResults = response.results;
```

Read about [Autocomplete API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/autocomplete.md) in details.




## Recommend

Smart applications display relevant data for their users, `Recommend` enable you to get the most relevant data(document/product/article...) your users are interacting with now, which will better increase your revenue, visits count, and the time a user spent on your application.

Pass down the data Id you want relevant data for, and the `recommend` function will return the best possible results.

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

const { code, response, time } = await lablebClient.recommend({
  id: '475'
});

const recommendResults = response.results;
```

Read about [Recommend API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/recommend.md) in details.



## Indexing

Adding or uploading your data to [Lableb](https://lableb.com) is called `indexing`.

Indexing is a very smooth experience, passing down the data as an array is all what it does, the only required thing is your data objects must match your data `schema` made at [Lableb Dashboard](https://dashboard.lableb.com).

Assuming your platform schema has an `id` and `title` as required fields.

```js
const lablebClient = LablebClient({
    indexingAPIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

await lablebClient.index({
  documents: [
    { id: '1', title: 'Finding water in Africa' },
    { id: '2', title: 'How important is water for daily life?' }
  ]
});
```

> Note: You need to use a special API Key for `indexing` and `delete`, we call it `indexingAPIKey`, you can create it inside [Lableb Dashboard](https://dashboard.lableb.com), where you choose to add `index` permission to the created API Key.

Read about [Indexing API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/indexing.md) in details.


> Note: How to update already indexed data
> 
> To update any existing data you have at Lableb, just re index it again, and it will be updated automatically for you.


## Delete

Remove your data from `Lableb` can be justified for many reasons, wrong data, stalled data, not needed anymore data... anyway you can absolutely remove any piece of data using its unique id.

```js
const lablebClient = LablebClient({
    indexingAPIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

await lablebClient.delete({
  documentId: '274'
});
```

Read about [Delete API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/delete.md) in details.


## Search By ID

Fetching single document from [Lableb](https://lableb.com) 

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});

const { code, response, time } = await lablebClient.searchById({
  id: '297424'
});

const searchResult = response;
```

Read about [Search By ID API](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/search-by-id.md) in details.


## Feedback

Sending feedback to Lableb help you study and understand your users behavior at a deeper level through various analytics at [Lableb Dashboard](https://dashboard.lableb.com).

You can access a feedback object that contains search, autocomplete, recommend feedbacks functions respectively where you have many options to send in the feedback, and you can either send a single feedback to Lableb at a time, or send a batch of feedbacks in one call. 

Each feedback object has two functions: `single` and `batch`

Search Feedback Example:

  - To Send single search feedback to Lableb use `feedback.search.single` function
  - To Send many search feedbacks at once to Lableb use `feedback.search.batch` function


Of course there is similar functions for autocomplete and recommend feedback respectively.



#### When feedback is usually used in application?

Feedback requests are usually fired from the UI(based on users' behavior).

When you do a search at [Lableb](https://lableb.com) you get back the search results and display them for your end users, when a user clicks or interact with the displayed result, you send a search feedback to [Lableb](https://lableb.com), and so on.

When your end users interacts with an autocomplete results, you send an autocomplete feedback, and when the end-users interact with a recommend result, you send a recommend feedback.


#### Feedback APIs:
- [Search Feedback](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/search-feedback.md)
- [Autocomplete Feedback](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/autocomplete-feedback.md)
- [Recommend Feedback](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/recommend-feedback.md)


------------------------

## Real Examples

We have included several simple examples regarding different modules format(esm, cjs) and different environment(node.js, browser) you can check them at [examples folder](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/examples)

Don't forget to only change the import statement in browsers examples, or do `yarn install` for node.js examples.

------------------------

## Test and code coverage

This library is tested with `jest` and has 100% code coverage(run [coverage results](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/coverage/lcov-report/index.html) in your browser.)


------------------------


## FAQ: 

  - What is a document at Lableb?
    
    It's a synonyms for data, product, article, and what you call it depends on your platform, whether it's e-commerce, blog, ...etc

  - How can I user `promises` in old browsers?

    if you're using an old version of `EcmaScript` and want to use the `async/await` syntax you easily do by install `babel-polyfill`

  - What is the difference between API Key and indexing API Key?

    API Key can only be used for `search`, `autocomplete`, `recommend`, and `feedbacks`, while indexing API Key is only used for `indexing` and `delete`.

  - Can I call `index` function in browser?

    Yes, but doing so will expose your Index API Key in developers tools, so we recommend leaving `indexing` and `delete` only for the server.

  - I have an issue, what can I do to solve it?

    If you find an issue you can open an [issue](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/issues) at the git repository, or contact us at [support@lableb.com](mailto:support@lableb.com)