XiansAi TypeScript/JavaScript SDK

A comprehensive TypeScript SDK for real-time and synchronous communication with XiansAi Server, enabling AI-powered workflows and conversations in your applications.

Features

• 🔄 Real-time Communication: WebSocket-based chat with automatic reconnection
• 🌐 HTTP REST API: Synchronous messaging and conversation management
• 📡 Server-Sent Events: Live notifications and status updates
• 🔐 Multiple Authentication: API Key, JWT Token, or JWT Callback support
• 📝 TypeScript Support: Full type definitions and IntelliSense
• 🛡️ Error Handling: Comprehensive error handling and logging
• ⚡ Async/Await: Modern promise-based API

Quick Start

Installation

npm install @99xio/xians-sdk-typescript
# or
yarn add @99xio/xians-sdk-typescript

Basic Usage

import { SocketSDK, RestSDK, MessageType } from '@99xio/xians-sdk-typescript';

// Real-time chat with WebSocket
const socketSDK = new SocketSDK({
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key',
  serverUrl: 'https://your-server.com',
  eventHandlers: {
    onReceiveChat: (message) => console.log('Received:', message.text)
  }
});

await socketSDK.connect();
await socketSDK.subscribeToAgent('workflow-id', 'user-123');
await socketSDK.sendInboundMessage({
  participantId: 'user-123',
  workflowType: 'customer-support',
  text: 'Hello!'
}, MessageType.Chat);

// Synchronous conversation with REST
const restSDK = new RestSDK({
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key',
  serverUrl: 'https://your-server.com'
});

const result = await restSDK.converse({
  participantId: 'user-123',
  workflow: 'customer-support',
  type: 'Chat',
  text: 'What is my order status?',
  timeoutSeconds: 30
});

Documentation Index

📚 Getting Started (Read in Order)

| Document | Description | When to Read | |----------|-------------|--------------| | Overview | Architecture, concepts, and SDK comparison | Start here to understand the system | | Authentication | API keys vs JWT tokens, security setup | Before implementing auth | | Quick Start Examples | Practical examples for each SDK | When ready to code |

🔧 SDK Documentation

| SDK | Description | Best For | |-----|-------------|----------| | REST SDK | HTTP-based synchronous communication | Request/response, server-to-server | | Socket SDK | Real-time bidirectional WebSocket | Interactive chat, live collaboration | | SSE SDK | Server-sent events for live updates | Notifications, status monitoring |

📖 Reference Documentation

| Document | Content | |----------|---------| | Types Reference | Complete TypeScript types and interfaces | | Message Types | Chat, Data, and Handoff message structures | | Authentication Examples | Detailed auth implementation patterns | | Advanced Examples | Complex scenarios and best practices |

🛠️ Development & Contributing

| Document | Purpose | |----------|---------| | Contributing Guide | Development workflow, testing, and publishing instructions |

Choosing the Right SDK

| Need | REST SDK | Socket SDK | SSE SDK | |------|----------|------------|---------| | Fire-and-forget messages | ✅ Best | ✅ Good | ❌ No | | Synchronous conversations | ✅ Best | ✅ Good | ❌ No | | Real-time notifications | ❌ No | ✅ Best | ✅ Best | | Bidirectional communication | ❌ No | ✅ Best | ❌ No | | Live dashboards | ❌ No | ✅ Good | ✅ Best | | Server-to-server | ✅ Best | ✅ Good | ✅ Good | | Web applications | ✅ Good | ✅ Best | ✅ Good |

👉 Not sure? Start with the Overview to understand which SDK fits your use case.

Learning Path

For Beginners

1. Read Overview to understand the architecture
2. Set up Authentication
3. Try Quick Start Examples
4. Explore individual SDK documentation as needed

For Experienced Developers

1. Review Overview for architecture understanding
2. Jump to relevant SDK documentation (REST, Socket, SSE)
3. Check Advanced Examples for complex patterns

For Integration Teams

1. Review Authentication for security considerations
2. Study Message Types for data structures
3. Implement using Authentication Examples

Support

• 📖 Documentation: Complete guides in the docs folder
• 🐛 Issues: Report bugs and request features in our repository
• 💬 Community: Join our developer community for questions and discussion

License

This SDK is licensed under the MIT License. See the LICENSE file for details.