# Typescript SDK

The eGain API client SDK for TypeScript supports both Node.js and browser environments, offering a modern, type-safe interface for integrating with eGain's Knowledge Portal Manager, AI Services, and Ingestion APIs.

div
a
svg
path

    View on GitHub
  
### License

The following licenses are required to use the SDK:

* If the user is an agent, then the *Knowledge + AI* license is required.
* If the user is a customer, the *Self-Service* and *Advanced Self-Service* licenses must be available.


## SDK Installation

The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers.

### NPM


```bash
npm add @egain/egain-api-typescript
```

### PNPM


```bash
pnpm add @egain/egain-api-typescript
```

### Bun


```bash
bun add @egain/egain-api-typescript
```

### Yarn


```bash
yarn add @egain/egain-api-typescript
```

> [!NOTE]
This package is published with CommonJS and ES Modules (ESM) support.


## SDK Example Usage

### Get Article by ID


```typescript
import { Egain } from "@egain/egain-api-typescript";

const egain = new Egain({
  accessToken: process.env["EGAIN_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await egain.portal.article.getArticleById({
    acceptLanguage: "en-US",
    portalID: "PROD-1000",
    articleID: "PROD-2996",
    language: "en-US",
    articleAdditionalAttributes: [
      "averageRating",
    ],
    customAdditionalAttributes: "country_name",
    publishViewId: "PROD-3203",
    workflowMilestone: "publish",
  });

  console.log(result);
}

run();
```

### Retrieve Chunks


```typescript
import { Egain } from "@egain/egain-api-typescript";

const egain = new Egain({
  accessToken: process.env["EGAIN_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await egain.aiservices.retrieve.retrieveChunks({
    q: "fair lending",
    portalID: "PROD-1000",
    filterUserProfileID: "PROD-3210",
    language: "en-US",
    filterTags: {
      "PROD-1234": [
        "PROD-2000",
        "PROD-2003",
      ],
      "PROD-2005": [
        "PROD-2007",
      ],
    },
    retrieveRequest: {
      channel: {
        name: "Eight Bank Website",
      },
    },
  });

  console.log(result);
}

run();
```

## Authentication

### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name | Type | Scheme | Environment Variable |
|  --- | --- | --- | --- |
| `accessToken` | http | HTTP Bearer | `EGAIN_ACCESS_TOKEN` |


To authenticate with the API the `accessToken` parameter must be set when initializing the SDK client instance. For example:


```typescript
import { Egain } from "@egain/egain-api-typescript";

const egain = new Egain({
  accessToken: process.env["EGAIN_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await egain.portal.article.getArticleById({
    acceptLanguage: "en-US",
    portalID: "PROD-1000",
    articleID: "PROD-2996",
    language: "en-US",
    articleAdditionalAttributes: [
      "averageRating",
    ],
    customAdditionalAttributes: "country_name",
    publishViewId: "PROD-3203",
    workflowMilestone: "publish",
  });

  console.log(result);
}

run();
```

## Error Handling

[`EgainError`] is the base class for all HTTP error responses. It has the following properties:

| Property | Type | Description |
|  --- | --- | --- |
| `error.message` | `string` | Error message |
| `error.statusCode` | `number` | HTTP response status code eg `404` |
| `error.headers` | `Headers` | HTTP response headers |
| `error.body` | `string` | HTTP body. Can be empty string if no body is returned. |
| `error.rawResponse` | `Response` | Raw HTTP response |
| `error.data$` |  | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |


### Example


```typescript
import { Egain } from "@egain/egain-api-typescript";
import * as errors from "egain-api-client/models/errors";

const egain = new Egain({
  accessToken: process.env["EGAIN_ACCESS_TOKEN"] ?? "",
});

async function run() {
  try {
    const result = await egain.portal.article.getArticleById({
      acceptLanguage: "en-US",
      portalID: "PROD-1000",
      articleID: "PROD-2996",
      language: "en-US",
      articleAdditionalAttributes: [
        "averageRating",
      ],
      customAdditionalAttributes: "country_name",
      publishViewId: "PROD-3203",
      workflowMilestone: "publish",
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.EgainError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.WSErrorCommon) {
        console.log(error.data$.code); // string
        console.log(error.data$.developerMessage); // string
        console.log(error.data$.details); // Detail[]
        console.log(error.data$.userMessage); // string
      }
    }
  }
}

run();
```

## Server Selection

### Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:


```typescript
import { Egain } from "@egain/egain-api-typescript";

const egain = new Egain({
  serverURL: "https://${API_DOMAIN}/knowledge/portalmgr/v4",
  accessToken: process.env["EGAIN_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await egain.portal.article.getArticleById({
    acceptLanguage: "en-US",
    portalID: "PROD-1000",
    articleID: "PROD-2996",
    language: "en-US",
    articleAdditionalAttributes: [
      "averageRating",
    ],
    customAdditionalAttributes: "country_name",
    publishViewId: "PROD-3203",
    workflowMilestone: "publish",
  });

  console.log(result);
}

run();
```