# @telia-ace/knowledge-serviceclient

> Service client for communication with classical ACE Knowledge projections.

Latest version **1.0.32** (published 2023-09-25) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install @telia-ace/knowledge-serviceclient
pnpm add @telia-ace/knowledge-serviceclient
yarn add @telia-ace/knowledge-serviceclient
bun add @telia-ace/knowledge-serviceclient
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.32 |
| Published | 2023-09-25 |
| First published | 2022-03-11 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 98.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Telia Company AB |
| Maintainers | teliajonasrosenlind, lnj851, adomas-liutkus, totte, donami, bratn, andreas.boukaras, gunnarx2, anhe92 |
| Keywords | telia |

## Links

- npm: https://www.npmjs.com/package/@telia-ace/knowledge-serviceclient
- npm.io page: https://npm.io/package/@telia-ace/knowledge-serviceclient

## Dependencies (1)

- [isomorphic-fetch](https://npm.io/package/isomorphic-fetch.md) ^3.0.0

## Recent versions

- 1.0.32 (latest) — 2023-09-25
- 1.0.33-next.1 (next) — 2023-09-27
- 1.0.23-experimental.12 (experimental) — 2023-03-21
- 1.0.33-next.0 — 2023-09-27
- 1.0.32-next.0 — 2023-09-21
- 1.0.31 — 2023-08-16
- 1.0.31-next.9 — 2023-08-16
- 1.0.31-next.8 — 2023-08-14
- 1.0.31-next.7 — 2023-08-14
- 1.0.31-next.6 — 2023-08-14
- 1.0.31-next.5 — 2023-08-14
- 1.0.31-next.4 — 2023-08-09
- 1.0.31-next.3 — 2023-08-09
- 1.0.31-next.2 — 2023-08-09
- 1.0.31-next.1 — 2023-08-09
- … 84 more at https://npm.io/package/@telia-ace/knowledge-serviceclient/versions

## README

# @telia-ace/knowledge-serviceclient

The Service Client provides an API for interacting with classic Humany projections. A projection is a URL representing a subset of content (guides, categories, contact methods etc) in a Humany application.

## Projection URL Format
The standard format of a Projection URL consists of the root application url followed by the projection name.
```
https://[application].humany.net/[projection-name]
```

## Create an instance of Service Client
Create an instance by passing the Projection URL as the first constructor argument.

```javascript
import { ServiceClient } from '@telia-ace/knowledge-serviceclient';

const projection = '[projection-url]';
const serviceClient = new ServiceClient(projection);
```

### Passing additional options
The second constructor argument can be used to pass additional `ServiceClientOptions`.

#### `ServiceClientOptions`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`funnel`**|Funnel to report statistics on.|`string`|
|**`client`**|Unique ID for the client|`string`|
|**`site`**|Site (URI) to report statistics on.|`string`|
|**`paging`**|Default paging options|`object`|

**Comments**
- Funnel, Client and Site can be overriden by using the options parameter on specific API calls.

## Match
Match guides based on a search phrase.
### `match(phrase, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`phrase`**|The phrase to match.|`string`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

### `match(phrase, options, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`phrase`**|The phrase to match.|`string`|
|**`options`**|Additional matching options|`MatchingOptions`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

#### `MatchingOptions`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`statisticsDisabled`**|Whether statistics should be reported for the request.|`boolean` (default: false)|
|**`categoryId `**|Limit the matching to the specified category|`number`|

**Example**
```javascript
serviceClient.match('hello world', (matchResult) => {
  console.log('matched guides:', matchResult.Matches);
});
```

## Get categories

### `getCategories(success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

### `getCategories(options, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`options`**|Additional matching options|`CategoriesOptions`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

#### `CategoriesOptions`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`phrase `**|Get categories containging guides matching a phrase|`string`|
|**`categoryId `**|Limit the matching to the specified category|`number`|
|**`expand`**|Possible values: `'none'`, `'children'`, `'descendants'`|`string`|

**Example**
```javascript
serviceClient.getCategories((categoryResult) => {
  console.log('all categories:', categoryResult.Children);
});
```

## Get guide

### `getGuide(id, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`id`**|Guide ID.|`number`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

### `getGuide(id, options, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`id`**|Guide ID.|`number`|
|**`options`**|Additional guide options.|`GuideOptions`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

### `getGuide(id, connectionKey, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`id`**|Guide ID.|`number`|
|**`connectionKey`**|A connection key (part of dialog) to get.|`string`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

### `getGuide(id, connectionKey, options, success, [error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`id`**|Guide ID.|`number`|
|**`connectionKey`**|A connection key (part of dialog) to get.|`string`|
|**`options`**|Additional guide options.|`GuideOptions`|
|**`success`**|Callback returning the result.|`function`|
|**`error`**|Callback returning a description of the error.|`function`|

#### `GuideOptions`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`statisticsDisabled`**|Whether statistics should be reported for the request.|`boolean` (default: false)|

**Comments**
- If the Guide is not intended to be displayed as a result of a previous match statistics should be disabled.

## Give feedback on guide

### `giveFeedback(id, connectionKey, feedbackType, [success, error])`

|Argument|Description|Type|
|:--:|:--:|:----------|
|**`id`**|Guide ID.|`number`|
|**`connectionKey`**|A connection key (part of dialog) to give feedback on.|`string`|
|**`feedbackType`**|Type of feedback to give (`Positive` or `Negative`).|`string`|

## Accessing the Service Client from a plugin
For implementations running version 4 you can author a plugin and access the current Service Client through the `container` under the key `'matchingClient'`. The value must be resolved asynchronously as in the example below.

```javascript
import { Plugin } from '@telia-ace/knowledge-widget-core';

class MyPlugin extends Plugin {
  initialize() {
    this.container.getAsync('matchingClient').then((matchingClient) => {
      // use 'matchingClient' here
    });  
  }
}
```

---
_Source: https://npm.io/package/@telia-ace/knowledge-serviceclient · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._