[email protected]

TypeScript/JavaScript client for the ChatKitty API, powered by axios and an OAuth2 Client Credentials flow that’s handled for you.

This package ships:

• A ChatKitty wrapper that:
  • Exchanges your client ID/secret for an access token using OAuth 2.0 Client Credentials.
  • Caches and auto-refreshes tokens with axios-token-interceptor based on expires_in.
  • Instantiates all generated API classes with a preconfigured Configuration.
• Generated API classes and models from the ChatKitty OpenAPI spec.

⚠️ Security note: Because this library uses the Client Credentials flow (requires a client secret), it is intended for server-side use. Do not embed your client secret in browser apps.

Environments

• Recommended: Node.js (server/runtime)
• Bundlers (Webpack/Browserify) are technically supported, but not recommended due to the secret requirement.

Language level

• ES2015+ (ES6)
• Type definitions for TypeScript are included.

Module systems

• CommonJS (CJS)
• ES Modules (ESM)

TypeScript consumers will get types automatically via package.json (ref).

Installation

From npm (recommended):

npm install [email protected]

Quick Start

import { ChatKitty } from 'chatkitty';

const kitty = new ChatKitty({
  clientId: process.env.CHATKITTY_CLIENT_ID!,
  clientSecret: process.env.CHATKITTY_CLIENT_SECRET!,
  // Optional overrides:
  // basePath: 'https://api.chatkitty.com', // API base
  // authorizationBasePath: 'https://authorization.chatkitty.com/oauth/token', // OAuth token URL
});

// Use generated APIs via strongly-typed properties:

// Example: AnalyticsApi
await kitty.AnalyticsApi; // instance of AnalyticsApi

// Example: ApplicationApi
await kitty.ApplicationApi; // instance of ApplicationApi

// Example: ChannelsApi
await kitty.ChannelsApi; // instance of ChannelsApi

// Example: ChatSessionsApi
await kitty.ChatSessionsApi; // instance of ChatSessionsApi

// Example: FunctionVersionsApi
await kitty.FunctionVersionsApi; // instance of FunctionVersionsApi

// Example: FunctionsApi
await kitty.FunctionsApi; // instance of FunctionsApi

// Example: ImportsApi
await kitty.ImportsApi; // instance of ImportsApi

// Example: JobsApi
await kitty.JobsApi; // instance of JobsApi

// Example: MessagesApi
await kitty.MessagesApi; // instance of MessagesApi

// Example: RuntimeApi
await kitty.RuntimeApi; // instance of RuntimeApi

// Example: ThreadsApi
await kitty.ThreadsApi; // instance of ThreadsApi

// Example: UserSessionsApi
await kitty.UserSessionsApi; // instance of UserSessionsApi

// Example: UsersApi
await kitty.UsersApi; // instance of UsersApi


// Example call (replace with a real operation from the docs):
// const res = await kitty.<SomeApi>.<someOperation>(params);
// console.log(res.data);

Configuration

export interface ChatKittyConfiguration {
  clientId: string;            // REQUIRED
  clientSecret: string;        // REQUIRED
  basePath?: string;           // Optional: override API base URL
  authorizationBasePath?: string; // Optional: override OAuth token URL
}

• clientId / clientSecret – Your OAuth2 Client Credentials.
• basePath – Override the API base URL if needed.
• authorizationBasePath – Override the OAuth token endpoint. Defaults to https://authorization.chatkitty.com/oauth/token.

How authentication works

• The client requests an access token with grant_type=client_credentials.

• Tokens are cached and automatically refreshed using expires_in to determine max age.

• Each API call includes Authorization: Bearer <token> and:

  • Accept: application/vnd.chatkitty+json,*/*;q=0.8

No extra work is required—just provide your credentials.

Consuming in Your Project

Install:

npm install [email protected] --save

Use:

import { ChatKitty } from 'chatkitty';

const kitty = new ChatKitty({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

// Call any generated API:

const AnalyticsApi = kitty.AnalyticsApi; // instance is ready to use

const ApplicationApi = kitty.ApplicationApi; // instance is ready to use

const ChannelsApi = kitty.ChannelsApi; // instance is ready to use

const ChatSessionsApi = kitty.ChatSessionsApi; // instance is ready to use

const FunctionVersionsApi = kitty.FunctionVersionsApi; // instance is ready to use

const FunctionsApi = kitty.FunctionsApi; // instance is ready to use

const ImportsApi = kitty.ImportsApi; // instance is ready to use

const JobsApi = kitty.JobsApi; // instance is ready to use

const MessagesApi = kitty.MessagesApi; // instance is ready to use

const RuntimeApi = kitty.RuntimeApi; // instance is ready to use

const ThreadsApi = kitty.ThreadsApi; // instance is ready to use

const UserSessionsApi = kitty.UserSessionsApi; // instance is ready to use

const UsersApi = kitty.UsersApi; // instance is ready to use

Documentation for API Endpoints

All URIs are relative to https://api.chatkitty.com

| Class | Method | HTTP request | Description | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------- | ----------- | | AnalyticsApi | exportMessageAnalytics | POST /analytics/messages | Export message analytics | | AnalyticsApi | exportUserAnalytics | POST /analytics/users | Export user analytics | | ApplicationApi | retrieveApplication | GET /application | Retrieve the authenticated application | | ApplicationApi | retrieveApplicationMessageReadReceiptSummaries | GET /application/message-read-receipt-summaries | Retrieve the authenticated application message read receipt summaries | | ApplicationApi | retrieveApplicationSettings | GET /application/settings | Retrieve the authenticated application settings | | ApplicationApi | updateApplicationSettings | PUT /application/settings | Update the authenticated application settings | | ChannelsApi | addChannelMember | POST /channels/{id}/members | Add a channel member | | ChannelsApi | addChannelModerator | POST /channels/{id}/moderators | Add a channel moderator | | ChannelsApi | createChannel | POST /channels | Create a channel | | ChannelsApi | deleteChannel | DELETE /channels/{id} | Delete a channel | | ChannelsApi | listChannelInvites | GET /channels/{id}/invites | List channel invites | | ChannelsApi | listChannelMembers | GET /channels/{id}/members | List a channel's members | | ChannelsApi | listChannelMemberships | GET /channels/{id}/memberships | List channel memberships | | ChannelsApi | listChannelMessages | GET /channels/{id}/messages | List channel messages | | ChannelsApi | listChannelModerators | GET /channels/{id}/moderators | Lists a channel's moderators | | ChannelsApi | listChannelParticipants | GET /channels/{id}/participants | List channel participants | | ChannelsApi | listChannelReportedMessages | GET /channels/{id}/reported-messages | List channel reported messages | | ChannelsApi | listChannels | GET /channels | List channels | | ChannelsApi | removeChannelMember | DELETE /channels/{id}/members/{user_id} | Remove a channel member | | ChannelsApi | removeChannelModerator | DELETE /channels/{id}/moderators/{user_id} | Remove a channel moderator | | ChannelsApi | retrieveChannel | GET /channels/{id} | Retrieve a channel | | ChannelsApi | sendChannelEvent | POST /channels/{id}/events | Send a channel event | | ChannelsApi | sendChannelInvite | POST /channels/{id}/invites | Send a channel invite | | ChannelsApi | sendChannelKeystrokes | POST /channels/{id}/keystrokes | Send channel keystrokes | | ChannelsApi | sendChannelMessage | POST /channels/{id}/messages | Send a channel message | | ChannelsApi | updateChannel | PATCH /channels/{id} | Update a channel | | ChatSessionsApi | listChatSessions | GET /chat-sessions | List chat sessions | | FunctionVersionsApi | retrieveFunctionVersion | GET /function-versions/{id} | Retrieve a chat function version | | FunctionsApi | createFunctionVersion | POST /functions/{id}/versions | Create a chat function version | | FunctionsApi | listFunctionInvocations | GET /functions/{id}/invocations | List chat function invocations | | FunctionsApi | listFunctionVersions | GET /functions/{id}/versions | List chat function versions | | FunctionsApi | retrieveFunction | GET /functions/{id} | Retrieve a chat function | | FunctionsApi | retrieveFunctionCurrentVersion | GET /functions/{id}/current-version | Retrieve chat function current version | | ImportsApi | importChannelMembers | POST /imports/channels/{id}/members | Import channel members | | ImportsApi | importChannels | POST /imports/channels | Import channels | | ImportsApi | importMessages | POST /imports/messages | Import messages | | ImportsApi | importUsers | POST /imports/users | Import users | | JobsApi | listJobs | GET /jobs | List jobs | | JobsApi | retrieveJob | GET /jobs/{id} | Retrieve a job | | MessagesApi | deleteMessage | DELETE /messages/{id} | Delete a message | | MessagesApi | deleteMessages | DELETE /messages | Delete messages | | MessagesApi | listMessageReadReceipts | GET /messages/{id}/read-receipts | List message read receipts | | MessagesApi | listMessages | GET /messages | List messages | | MessagesApi | retrieveMessage | GET /messages/{id} | Retrieve a message | | MessagesApi | updateMessage | PATCH /messages/{id} | Update a message | | RuntimeApi | createNodejsRuntimeFunction | POST /runtimes/nodejs/functions | Create a NodeJS chat runtime function | | RuntimeApi | listNodejsRuntimeFunctions | GET /runtimes/nodejs/functions | List NodeJS chat runtime functions | | RuntimeApi | retrieveNodejsRuntime | GET /runtimes/nodejs | Retrieve NodeJS chat runtime | | RuntimeApi | updateNodejsRuntimeDependencies | PUT /runtimes/nodejs/dependencies | Update NodeJS chat runtime NPM dependencies | | RuntimeApi | updateNodejsRuntimeEnvironmentVariables | PUT /runtimes/nodejs/environment-variables | Update NodeJS chat runtime environment variables | | RuntimeApi | updateNodejsRuntimeInitializationScript | PUT /runtimes/nodejs/initialization-script | Update NodeJS chat runtime initialization script | | ThreadsApi | listThreadMessages | GET /threads/{id}/messages | List reply thread messages | | ThreadsApi | retrieveThread | GET /threads/{id} | Retrieve a thread | | ThreadsApi | sendThreadKeystrokes | POST /threads/{id}/keystrokes | Send thread keystrokes | | ThreadsApi | sendThreadMessage | POST /threads/{id}/messages | Send a reply thread message | | UserSessionsApi | listUserSessions | GET /user-sessions | List user sessions | | UsersApi | checkUserExists | HEAD /users | Check a user exists | | UsersApi | countUserUnreadMessages | GET /users/{id}/messages/unread/count | Counts the number of unread messages for a user | | UsersApi | createUser | POST /users | Create a user | | UsersApi | deleteUser | DELETE /users/{id} | Delete a user | | UsersApi | listUserChannels | GET /users/{id}/channels | List a user's channels | | UsersApi | listUserMessages | GET /users/{id}/messages | List a user's messages | | UsersApi | listUserNotifications | GET /users/{id}/notifications | List a user's notifications | | UsersApi | listUsers | GET /users | List users | | UsersApi | removeUserSecret | DELETE /users/{id}/secrets/{name} | Remove a user secret | | UsersApi | retrieveUser | GET /users/{id} | Retrieve a user | | UsersApi | retrieveUserSecret | GET /users/{id}/secrets/{name} | Retrieve a user secret | | UsersApi | setUserSecret | PUT /users/{id}/secrets/{name} | Set a user secret | | UsersApi | updateUser | PATCH /users/{id} | Update a user | | UsersApi | updateUserDisplayPicture | POST /users/{id}/display-picture | Update a user's display picture | | | | | |

Documentation for Models

• ApiError
• ApplicationFeatureSettingsProperties
• ApplicationJobResource
• ApplicationResource
• ApplicationSentSystemMessageNotificationData
• ApplicationSettingsProperties
• ApplicationSettingsResource
• AuthenticationError
• ChannelGenericEventResource
• ChannelImport
• ChannelInviteResource
• ChannelMembershipImport
• ChannelMembershipResource
• ChannelMessageMentionProperties
• ChannelProperties
• ChannelResource
• ChatFunctionChatRuntimeProperties
• ChatFunctionInvocationResource
• ChatFunctionResource
• ChatFunctionVersionResource
• ChatRuntimeDependencyProperties
• ChatRuntimeProperties
• ChatRuntimeResource
• ChatRuntimeScriptProperties
• ChatSessionResource
• ChatUserIdReference
• ChatUserImport
• ChatUserMentionedChannelNotificationData
• ChatUserMentionedChatUserNotificationData
• ChatUserMessageMentionProperties
• ChatUserMessageResource
• ChatUserPresenceProperties
• ChatUserProperties
• ChatUserRepliedToChatUserMessageNotificationData
• ChatUserResource
• ChatUserSentChatUserMessageNotificationData
• ChatUserSessionProperties
• ChatUserSessionResource
• ChatUserUsernameReference
• CountResource
• CreateChannelGenericEventResource
• CreateChannelInviteResource
• CreateChannelResource
• CreateChatFunctionResource
• CreateChatFunctionVersionResource
• CreateDelegatedReplyThreadKeystrokesResource
• CreateDirectChannelResource
• CreateExternalFileProperties
• CreateFileMessageResource
• CreateGroupChannelResource
• CreateMessageResource
• CreatePersonChatUserResource
• CreatePrivateChannelResource
• CreatePublicChannelResource
• CreateTextMessageResource
• CursorPageMetadata
• CursorPagedModelMessageResource
• CursorPagedModelMessageResourceEmbedded
• CursorPagedModelNotificationResource
• CursorPagedModelNotificationResourceEmbedded
• DirectChannelImport
• DirectChannelProperties
• DirectChannelResource
• EmojiProperties
• FileChatUserMessageProperties
• FileChatUserMessageResource
• FileImport
• FileMessageProperties
• FileProperties
• FileSystemMessageProperties
• FileSystemMessageResource
• GroupChannelImport
• GroupChannelProperties
• Link
• MessageImport
• MessageLinkPreviewImageProperties
• MessageLinkPreviewProperties
• MessageLinkProperties
• MessageMentionChannelProperties
• MessageMentionProperties
• MessageProperties
• MessageReactionsSummaryProperties
• MessageReadReceiptResource
• MessageReadReceiptSummaryResource
• MessageResource
• NotificationData
• NotificationResource
• PageMetadata
• Pageable
• PagedModelApplicationJobResource
• PagedModelApplicationJobResourceEmbedded
• PagedModelChannelInviteResource
• PagedModelChannelInviteResourceEmbedded
• PagedModelChannelMembershipResource
• PagedModelChannelMembershipResourceEmbedded
• PagedModelChannelResource
• PagedModelChannelResourceEmbedded
• PagedModelChatFunctionInvocationResource
• PagedModelChatFunctionInvocationResourceEmbedded
• PagedModelChatFunctionResource
• PagedModelChatFunctionResourceEmbedded
• PagedModelChatFunctionVersionResource
• PagedModelChatFunctionVersionResourceEmbedded
• PagedModelChatSessionResource
• PagedModelChatSessionResourceEmbedded
• PagedModelChatUserResource
• PagedModelChatUserResourceEmbedded
• PagedModelChatUserSessionResource
• PagedModelChatUserSessionResourceEmbedded
• PagedModelMessageReadReceiptResource
• PagedModelMessageReadReceiptResourceEmbedded
• PagedModelMessageReadReceiptSummaryResource
• PagedModelMessageReadReceiptSummaryResourceEmbedded
• PagedModelMessageResource
• PrivateChannelImport
• PrivateChannelProperties
• PrivateChannelResource
• PublicChannelImport
• PublicChannelProperties
• PublicChannelResource
• ReplyThreadKeystrokesResource
• ReplyThreadResource
• SecretResource
• SystemMessageResource
• TextChatUserMessageImport
• TextChatUserMessageProperties
• TextChatUserMessageResource
• TextMessageImport
• TextMessageProperties
• TextMessageResource
• TextSystemMessageImport
• TextSystemMessageProperties
• TextSystemMessageResource

Authorization

This client uses OAuth 2.0 – Client Credentials automatically.

• Flow: client_credentials
• Token URL (default): https://authorization.chatkitty.com/oauth/token
• Headers: Accept: application/vnd.chatkitty+json,*/*;q=0.8
• Token caching: Based on expires_in via axios-token-interceptor

Provide clientId and clientSecret to the ChatKitty constructor. Tokens are fetched and attached to requests automatically.

Authentication schemes defined for the API:

password_reset_token_authorization

• Type: API key
• API key parameter name: X-Token
• Location: HTTP header

application_authorization

• Type: OAuth

• Flow: application

• Authorization URL:

• Scopes:

  • create:*: Create application resources

  • read:*: Read application resources

  • update:*: Update application resources

  • delete:*: Delete application resources

Error Handling

Errors are standard Axios errors. Example:

try {
  // await kitty.<SomeApi>.<someOperation>(...);
} catch (e: any) {
  console.error('Request failed', {
    status: e?.response?.status,
    data: e?.response?.data,
  });
}

FAQ

Can I use this in the browser? Not recommended. The Client Credentials flow requires a client secret, which must not be exposed to end users.

How do I change the API base URL? Pass basePath when constructing ChatKitty.

How do I point to a different OAuth server? Pass authorizationBasePath when constructing ChatKitty.

Support

• Refer to the per-class endpoint docs listed above.
• Inspect Axios request/response with your own interceptors if needed.