Skip to content

🚀 Client Library TypeScript

The Cheshire Cat provides a TypeScript API client that allows you to chat with the Cat (using WebSocket) and provides APIs to interact with all the control plane endpoints.
It can be used both in Browser and NodeJS environments.

The package is public released on npm Registry: Cheshire Cat TypeScript API Client

Every endpoint is a CancelablePromise, which means the request can be eventually cancelled.


The API client can be installed through one of the following commands:

npm install ccat-api
# OR
yarn add ccat-api
# OR
pnpm i ccat-api

Getting started

To set up the client, first of all CatClient class need to be imported:

import { CatClient } from 'ccat-api'

const cat = new CatClient({
    baseUrl: 'localhost',
    user: 'user'.
    //... other settings

cat.send('Hello from a user!') // this will send a message to the /ws/user

cat.userId = 'new_user'

cat.send('Hello from a new user!') // this will send a message to the /ws/new_user
The cat is initialized as CatClient with Client Settings; then, for example, a message can be send using the cat.send endpoint.

Client settings


Property Type Default Description
baseUrl string Required The same of CORE_HOST
authKey string '' The same of API_KEY
port number 1865 The same of the CORE_PORT
secure boolean false The same of the CORE_USE_SECURE_PROTOCOLS
user string 'user' The user ID to use for the WebSocket and the API client
instant boolean true Instantly initialize the WebSocket and the API client, or later with .init()
timeout number 10000 Timeout for the endpoints, in milliseconds
ws string undefined An object of type WebSocketSettings

WebSocket settings

Property Type Default Description
path string 'ws' Websocket path to use to communicate with the CCat
retries number 3 The maximum number of retries before calling onFailed
delay number 3000 The delay for reconnect, in milliseconds
onFailed (ErrorCode) => void undefined The function to call after failing all the retries

Then, for example, the LLM can be configured like this:

cat.api.settingsLargeLanguageModel.upsertLlmSetting('LLMOpenAIConfig', {
    openai_api_key: 'OPEN_API_KEY'

A message can be send to the cat as follows:

cat.send('Hello my friend!')

A specific listener (such as onMessage) can be added to the WebSocket events:

cat.onConnected(() => {
    console.log('Socket connected')
}).onMessage(msg => {
}).onError(err => {
}).onDisconnected(() => {
    console.log('Socket disconnected')

The list of plugins can be obtained by:

cat.api.plugins.listAvailablePlugins().then(plugins => {

The repository of this API is public and available on Cheshire Cat Typescript API Client Repository.