@cxco/dcx-connector/README.md

A simple module to retrieve information from DigitalCX

# @CXCO/DCX-CONNECTOR

Library to query DigitalCX endpoints using a common query interface and getting normalized answers. 

---

## Why should I use the @cxco/dcx-connector?

The `@cxco/dcx-connector` is a simple JavaScript library that wraps all the DigitalCX standard endpoints using a simple inbount/outbound data contract. It uses [axios](https://www.npmjs.com/package/axios) under the hood to make the HTTP requests. 
This library also exports the data contracts in case you want to use your own HTTP client but want to normalize the responses.

## Installing

Using npm: 

`npm install @cxco/dcx-connector`

## Quickstart

Performing an 'ask' request:

```javascript 

import { doDcxRequest } from '@cxco/dcx-connector'

const payload = {
    type: 'ask',
    data: {
        userInput: 'some question'
    },
    metadata: {},
    config: {
        baseUrl: 'https://your-digitalcx-endpoint',
        apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx',
        culture: 'en',
        customerKey: 'your-customer-key' // only needed if you're using the new CAIC URL 
        projectKey: 'your-project-key' // only needed if you're using the new CAIC URL
    }
}

const answer = await doDcxRequest(payload)

```

you'll get a response with a payload with two objects inside (**data** and **metadata**):

```json
{
  "data":  {
    "answer": "some answer",
    "dialogOptions":  [],
    "images":  [],
    "links":  [],
    "outputAdditions":  {},
    "type": "answer",
    "videos":  []
  },
  "metadata":  {
    "culture": "en",
    "interactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "id": 0
  }
}
```

## Request Payload

### Type

The request can be of the following types: 
- "ask"
- "dialogstep"
- "event"
- "linkclick"
- "feedback"
- "faq"
- "faqsincategory"
- "defaultfaqs"
- "categorytree"
- "category"
- "searchfaqs"
- "autocomplete"

### Data

The `data` section allows to pass the main information to the request, e.g. what question needs to be asked. The properties are added to the data object depending on the request being made.


|Property Name | Description |
|---|---|
| userInput | The question to be asked to the engine. Used in "ask", "searchfaqs" and "autocomplete" requests|
| dialogPath | When in a dialog, it's a node's "Dialog Path". Used in "ask" and "dialogstep" requests|
| eventName | The event to be triggered. Used in the "event" request|
| classificationId | The Classification Id. Used in "faqsincategory", "defaultfaqs", "categorytree", "category" and "searchfaqs" requests  |
| categoryId | The Category Id. Used in "faqsincategory" and "category" requests |
| faqId | The FAQ Id. Used in the "faq" request|
| interactionId | The interaction Id. Used in "linkclick" and "feedback" requests |    
| linkId | The clicked link id. Used in the "linkclick" request|
| linkUrl | The clicked link URL. Used in the "linkclick" request|
| score | The feedback score. Used in the "feedback" request |
| label |  The feedback label. Used in the "feedback" request |
| comment | The feedback comment. Used in the "feedback" request |



### Metadata

The `metadata` section allows to pass additional information to the request, e.g. minimum number of FAQs needed. The properties depend on the request being made.


| Property Name | Description |
| --- | --- |
| context | Array of context variables and corresponding values|
| includeFaqs | Include FAQs in categories |
| maxFaqs | Maximum number of FAQs to be included in the request |
| minFaqs | Minimum number of FAQs to be included in the request |
| session | Session properties and corresponding values|
| sessionId | The current session Id|
| sessionMode | The session mode |  
| tDialogState | The TDialog state |
| user | User properties and corresponding values|
| max | Maximum number of words from dictionary |
| offset | Offset for autocomplete |
| region | The region where the original data resides, e.g. West Europe or Southeast Asia |
|headers| Object containing properties `referer` and `userAgent`|

### Config

The `config` section contains the information related to the how and where to do the request.

|Property Name | Description | Mandatory |
|---|---|---|
|baseUrl | the URL of the API | yes |
|apiKey | the API key | yes |
|culture | language (en/nl/de) | yes |
|timeout | time in milliseconds until request times out | no |
|customerKey | the customer key (only needed when using the new CAIC URL) | yes/no |
|projectKey | the project key (only needed when using the new CAIC URL)| yes/no |

If you're using the new CAIC URL, the project key and customer key are also needed in the `config`

## Example: using just the data contrats

The "buildRequest" data contract generates an object that is accepted by [axios](https://github.com/axios/axios#axiosrequestconfig) as a request configuration.

```javascript
// import data contracts from the @cxco/dcx-connector
import { buildRequest, buildResponse } from '@cxco/dcx-connector'


const dcxRequest = async (payload) => {

    const requestConfig = buildRequest(payload)

    if (requestConfig === null) {
      throw new Error('Invalid payload')
    }

    const dcxResponse = await httpClient.doRequest(requestConfig)

    return buildResponse(dcxResponse)
}
```