@cognigy/rest-api-client/README.md

Cognigy REST-Client

Typescript / Javascript library to interaction with the `Cognigy.AI 4` RESTful API.

# Installing
```
npm i @cognigy/rest-api-client
```

# Development
## Executing e2e tests
In order to execute the e2e tests located in `src/spec/aiAgentV2.spec.ts`, ensure that you have the following two ENV variables defined:

- **REST_API_CLIENT_E2E_TESTS_API_BASE_URL** - it should point to a Cognigy.AI environments RESTful API, example: `https://api-benni-test.cognigy.dev`
- **REST_API_CLIENT_E2E_TESTS_API_KEY** - it needs to contain a Cognigy.AI RESTful API-key

You can run the test-suite using the following command:

```
REST_API_CLIENT_E2E_TESTS_API_BASE_URL=<your-url> \
REST_API_CLIENT_E2E_TESTS_API_KEY=<your-api-key> \
npm run test:aiAgentsV2
```

# Usage
Once the client has been installed into your Typescript / Javascript project, you have to require the client and create a new instance from it:

**Typescript**
```typescript
import { RestAPIClient } from "@cognigy/rest-api-client";

const client = new RestAPIClient({
	baseUrl: "<api-hostname-cognigy-ai-installation>"
});
```

**Javascript (Node.JS)**
```javascript
const { RestAPIClient } = require("@cognigy/rest-api-client");

const client = new RestAPIClient({
	baseUrl: "<api-hostname-cognigy-ai-installation>"
});
```

## Authentication
In order to authenticate your client, you have to use the `setCredentials` function. Our client supports multiple ways to authenticate, such as:
- API-key
- Basic auth
- OAuth 2

The following example shows how you can use a long-lived `API key` to authenticate and authorize:

**Typescript / Javascript (Node.JS)**
```typescript
client.setCredentials({
	type: "ApiKey",
	apiKey: "<your-api-key>"
});
```

## Making your first call
Let's assume that you have the permissions to create a new `agent / project` within Cognigy.AI and that you are using an API-key to authenticate and authorize calls. This is the minimal example which you can use to create a new virtual agent within Cognigy.AI:

**Typescript / Javascript (Node.JS)**
```typescript
const project = await client.createProject({
	locale: "en-US",
	name: "My new agent"
});
```

This will create the new virtual agent project and return it.

## Publish to npm

This package is published to the [public npm registry](https://www.npmjs.com/package/@cognigy/rest-api-client) by an automated GitHub Action scheduled for Tuesdays at 17:00 UTC (bi-weekly on even weeks), with version numbers aligned to the corresponding Cognigy.AI release version: [boron-release-rest-api-client.yml](https://github.com/Cognigy/cognigy/actions/workflows/boron-release-rest-api-client.yml).

To publish manually, you need to have "admin" access to cognigy organisation. `https://www.npmjs.com/settings/cognigy/members`

Only prerelease dist-tags such as `beta` or `rc` should be published manually; regular releases under the default `latest` tag are handled by the automated workflow.

To publish, pull the changes from the branch, go to clients/rest folder and run the following commands:

```
# verify the user
npm whoami 

# Login to npm if not logged in
npm login

# Publish the package to the default "latest" tag (normally handled by automation)
npm publish

# Or publish the package with a prerelease dist-tag like "beta" or "rc"
-> first bump the version
npm version prerelease --preid=rc
-> then publish
npm publish --tag beta
# npm publish --tag rc
```