XiansAi TypeScript/JavaScript SDK

A comprehensive TypeScript SDK for real-time and synchronous communication with the XiansAi Server UserApi, 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
Server API Usage	UserApi endpoints this SDK calls (vs WebApi)	When wiring serverUrl or debugging HTTP/WS paths
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.

Runnable examples

Vite apps under example/ import the SDK from source for local testing against UserApi:

Example	Auth
example/api-key-chat	API key
example/oidc-jwt	OIDC → JWT (getJwtToken)

See example/README.md for how to run each one.

Learning Path

For Beginners

1. Read Overview to understand the architecture
2. Skim Server API Usage so serverUrl points at UserApi
3. Set up Authentication
4. Try Quick Start Examples
5. Explore individual SDK documentation as needed

For Experienced Developers

1. Review Overview and Server API Usage
2. Jump to relevant SDK documentation (REST, Socket, SSE)
3. Check Advanced Examples for complex patterns

For Integration Teams

1. Confirm Server API Usage (UserApi paths vs WebApi)
2. Review Authentication for security considerations
3. Study Message Types for data structures
4. 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.