Kaia API JavaScript SDK

A comprehensive JavaScript SDK for integrating with the Kaia AI Chat API. This SDK provides a complete solution for building AI-powered chat applications with support for multiple authentication methods, chat management, and session handling.

Features

• 🤖 AI Chat Integration - Seamless integration with Kaia's AI assistants
• 🔐 Multiple Authentication Methods - Email/password, Google OAuth, JWT tokens
• 💬 Advanced Chat Management - Create, switch, and manage multiple chat sessions
• 🔄 Real-time Updates - Event-driven architecture for live UI updates
• 💾 Session Management - Automatic session persistence and restoration
• 🎯 Recommended Content - Personalized content recommendations primarily designed for conversation starter cards
• 🛠️ CLI Example - Command-line interface example for testing and development

Quick Start

Installation

npm install @kaia-team/kaia-api-js

Basic Usage

import { KaiaApi } from '@kaia-team/kaia-api-js';

// Initialize the API
const kaiaApi = new KaiaApi({
  host: 'https://api.kaia.team',        // API backend host
  configId: 'your-config-id',
  baseUrl: 'https://kaia.team'          // Frontend host for assets/components
});

// Initialize and start chatting
await kaiaApi.initialize();

// Send a message
const chatManager = kaiaApi.getChatManager();
chatManager.sendMessage({
  key: 'user-msg-1',
  role: 'user',
  content: 'Hello, how can you help me?',
  images: []
});

// Get personalized recommendations (primarily for conversation starter cards)
const apiClient = kaiaApi.getApiClient();
if (apiClient) {
  const recommendations = await apiClient.getRecommendedContent(6);
  console.log('Recommended content:', recommendations);
}

Documentation

• Getting Started Guide - Quick setup and basic integration
• Authentication Guide - User authentication and session management
• Chat Management Guide - Managing chats and conversations
• UI Integration Guide - Building chat interfaces
• CLI Usage Guide - Command-line interface usage
• API Reference - Complete API documentation
• Advanced Usage - Advanced features and customization

Configuration

Basic Configuration

const config = {
  baseUrl: 'https://api.kaia.team',        // API base URL
  configId: 'your-config-id',              // Your configuration ID
  host: 'https://kaia.team',               // Host domain
  qrcode: true,                            // Enable QR code functionality
  defaultOpen: false                       // Widget opens by default
};

Customer Instance Configuration

For customer-specific instances, use subdomains of kaia.team:

const config = {
  baseUrl: 'https://api.clients.kaia.team',
  configId: 'client-specific-config',
  host: 'https://clients.kaia.team'
};

Authentication Methods

1. Anonymous Chatting

// No authentication required - start chatting immediately
await kaiaApi.initialize();

2. Email/Password Login

const userInfo = await kaiaApi.login('[email protected]', 'password123');

3. Google OAuth

const userInfo = await kaiaApi.loginWithGoogle(googleAuthResponse);

4. JWT Token Authentication

await kaiaApi.authenticateUser('your-jwt-token');

Chat Management

Creating and Managing Chats

// Create a new chat
await kaiaApi.createNewChat();

// Switch to existing chat
await kaiaApi.switchChatHistory('chat-ulid');

// Load chat histories
const histories = await kaiaApi.loadHistories();

Sending Messages

const chatManager = kaiaApi.getChatManager();

// Send a message
chatManager.sendMessage({
  key: 'user-msg-1',
  role: 'user',
  content: 'Hello, how are you?',
  images: []
});

UI Integration

The SDK provides the data structures and event system needed to build chat interfaces. Message content can be either:

• Plain text strings - Simple text messages
• Structured JSON - Rich content with blocks (markdown, images, tiles)

The SDK includes TypeScript interfaces for all message types and content blocks. See the UI Integration Guide for implementation guidance.

CLI Example

The SDK includes a CLI example for testing and development:

# Navigate to CLI example
cd examples/cli
npm install
npm start

# Or use the CLI programmatically
import { KaiaCLI } from './examples/cli/src/cli';
const cli = new KaiaCLI();
await cli.start();

See the CLI Usage Guide for complete CLI example documentation.

Event System

The SDK uses an event-driven architecture for real-time updates:

// Listen for events
kaiaApi.addEventListener('user_authenticated', (event, data) => {
  console.log('User logged in:', data.userInfo.username);
});

kaiaApi.addEventListener('message_received', (event, data) => {
  console.log('New message:', data.message.content);
});

Backend Requirements

Required Backend Setup

1. API Endpoints - Ensure your backend implements the required Kaia API endpoints
2. Authentication - Configure authentication providers (email, Google OAuth, JWT)
3. Configuration - Set up your configuration ID and assistant definitions
4. CORS - Configure CORS settings for your domain

Environment Variables

KAIA_BASE_URL=https://api.kaia.team
KAIA_CONFIG_ID=your-config-id
KAIA_HOST=https://kaia.team

Examples

React Integration

import React, { useEffect, useState } from 'react';
import { KaiaApi, MessageType } from '@kaia-team/kaia-api-js';

function ChatInterface() {
  const [kaiaApi] = useState(() => new KaiaApi(config));
  const [messages, setMessages] = useState<MessageType[]>([]);
  
  useEffect(() => {
    kaiaApi.initialize().then(() => {
      const chatManager = kaiaApi.getChatManager();
      
      // Listen for new messages
      chatManager.addEventListener('message_added', (event, data) => {
        setMessages(prev => [...prev, data.message]);
      });
    });
  }, [kaiaApi]);
  
  const handleSendMessage = (content: string) => {
    const chatManager = kaiaApi.getChatManager();
    chatManager.sendMessage({
      key: `user-${Date.now()}`,
      role: 'user',
      content,
      images: []
    });
  };

  return (
    <div>
      {/* Your chat UI components */}
    </div>
  );
}

Node.js Integration

import { KaiaApi } from '@kaia-team/kaia-api-js';

const kaiaApi = new KaiaApi(config);
await kaiaApi.initialize();

// Use in your Node.js application
const chatManager = kaiaApi.getChatManager();
chatManager.sendMessage({
  key: 'node-msg-1',
  role: 'user',
  content: 'Hello from Node.js!',
  images: []
});

TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

import { 
  KaiaApi, 
  KaiaApiConfig, 
  MessageType, 
  UserInfo 
} from '@kaia-team/kaia-api-js';

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Changelog

See CHANGELOG.md for version history and updates.