# JS-Connector

### JS-Connector

Javascript Wrapper for InfinityJSON V3 API

### How to install

#### Using `<script>` tag

1. Download `loop54-js-connector.js` (for development) from <https://static.loop54.com/lib/js/loop54-js-connector.js> or `loop54-js-connector.min.js` (for production) from <https://static.loop54.com/lib/js/loop54-js-connector.min.js>
2. Host the file on your own servers or the CDN on your choice
3. Include a `<script>` tag with an `src` attribute that points to your hosted file
4. You should now have access to the global variable `Loop54`.
5. Create and use a Infinity client as [explained below](#how-to-use)

#### Using Node Package Manager (NPM) as AMD (wg. RequireJS) or CJS (eg. NodeJS):

1. Install the package with `npm install --save loop54-js-connector`
2. Require it in your project with `require('loop54-js-connector');` or with `define(["loop54-js-connector"], function(getClient) { /* ... */ })`
3. Create and use a Infinity client as [explained below](#how-to-use)

#### Using Node Package Manager (NPM) in a ESM environment (eg. Babel):

1. Install the package with `npm install --save loop54-js-connector`
2. Require it in your project with `const getClient = require('loop54-js-connector');` or `import getClient from 'loop54-js-connector';`
3. Create and use a Infinity client as [explained below](#how-to-use)

### How to use

#### Transpilation

If you’re using NPM to include the connector in your build pipeline, (for instance using Rollup or Webpack), note that the module is exported as a pure ES6 module, and it is not bundled with dependencies, transpiled or otherwise prepared for live environment. You will need to make those preparations as part of your own pipeline.

#### Configure

When creating a client, you will need to set the endpoint to match the one you will get from Loop54.

If you included `loop54-js-connector.js` (or `loop54-js-connector.min.js`) in a script tag, you can get a configured client from the global Infinityobject:

**Get client from global Infinityobject**

```
var client = Loop54.getClient('URL_TO_YOUR_ENDPOINT');
```

If you imported the connector as an ECMAScript module (with require(‘loop54-js-connector’) or equivalent), you can call the getClient function directly:

**Get client from imported function**

```
var client = getClient('URL_TO_YOUR_ENDPOINT');
```

#### Making API requests

**Search example with promise**

```
var options = {skip:0,take:20}; //this will take the first 20 results

client.search("R2 droids", options)
    .then(function(response){
        if(response.data.error) {
            console.log(response.data.error.title);
        } else {
            console.log("found " + response.data.results.count + " results");
        }
    });
```

**Search example with callback**

```
var options = {skip:0,take:20}; //this will take the first 20 results

var callback = function(response){
    if(response.data.error) {
        console.log(response.data.error.title);
    } else {
        console.log("found " + response.data.results.count + " results");
    }
}

client.search("R2 droids", options, callback);
```

The `options` and `callback` parameters are optional. As seen above, `client.search` will return a Promise.

All API operations work the same way with regards to `options` and `callback`.

**Cancelling a request**

All requests can be cancelled, which is useful when the user types fast.

Using promise:

```
const request = client.search("R2 droids", {}); //create request
request.then(response => if(!response.cancelled) console.log('done')); //attach continuation
request.cancel(); // cancel the request
```

Using callback:

```
var callback = function(response) { if(!response.cancelled) console.log('done'); } //create callback
const request = client.search("R2 droids", {}, callback);  //create request
request.cancel(); // cancel the request
```

**Create events example**

```
var entity = {type:"Product",id:"1234"};

var callback = function(response){
    if(response.data.error) {
        console.log(response.data.error.title);
    } else {
        console.log("success");
    }
}

client.createEvent("click",entity,null,null,null,callback);
```

See <http://docs.loop54.com> for more code samples.

#### But wait! I don’t want the Connector to handle user ID:s for me!

If you for some reason want to handle user ID:s yourself instead of letting the Connector do it using cookies, you can set the user ID when retrieving a client like this:

**Configuration example with custom user ID**

```
var client = Loop54.getClient('URL_TO_YOUR_ENDPOINT','YOUR_USER_ID');
```

#### Features

The connector supports the following API operations:

* Search
* Autocomplete
* GetEntities
* GetEntitiesByAttribute
* GetRelatedEntities
* CreateEvent
* CreateEvents
* GetIndexedAttributes
* GetIndexedAttributeValues

It also aids in developing a Infinityintegration by:

* Taking care of user ID and cookies (note that you need to ask your user’s consent)
* Setting required HTTP headers
* Serializing and deserializing requests and responses
* Friendlier error handling than HTTP error codes for common mistakes
* Tested in Chrome 69, Safari 12, Firefox 62, Opera 56, IE 11, and Edge 42

### Developing the library

A Linux or MacOS environment is required. Windows is not supported and the npm commands below will fail on it.

#### Development

1. Git clone this repository
2. in the folder, run `npm install` to install all dependencies
3. run `npm run dev` to start the webserver, open up <http://localhost:3001/#search> and try out the basic features

#### Build

run `npm run bundle` to build the source code into /lib folder

#### Tests

`npm run test` to do check if the tests passes

All tests are located in the `test` folder

#### Contributors

Thanks to [Doru Moisa](https://github.com/moisadoru) for [PR #1](https://github.com/LoopFiftyFour/JS-Connector/pull/1)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fact-finder.com/infinity/connectors/js-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.