SDK Documentation
TypeScript/JavaScript SDK for Yappa RT — a production-grade, multi-tenant WebSocket messaging engine.
Introduction
Yappa SDK is the official client for Yappa RT, a horizontally scalable WebSocket server built with Rust (Axum/Tokio). It provides real-time messaging with complete tenant isolation, JWT authentication, and cross-node message delivery via Redis pub/sub.
Multi-Tenant
Complete isolation with configurable user limits per tenant.
Scale-Out
Stateless servers with Redis pub/sub for cross-node routing.
JWT Auth
HS256 tokens strictly binding tenant_id and user_id claims.
System Architecture
Messages flow through multiple layers to ensure delivery across nodes:
┌─────────────────────┐
│ Load Balancer │
└──────────┬──────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ WS Node │ │ WS Node │ │ WS Node │
│ (Rust) │ │ (Rust) │ │ (Rust) │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└─────────────────────┼─────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
▼ ▼ ▼
┌────────┐ ┌────────────┐ ┌────────────┐
│ Redis │ │ Kafka │ │ PostgreSQL │
└────────┘ └────────────┘ └────────────┘
Quick Start
import { RealtimeClient } from '@yappa-rs/yappa-sdk';// 1. Initialize with your JWT tokenconst client = new RealtimeClient({url: 'wss://your-server.com/ws',token: 'eyJhbGciOiJIUzI1NiIs...',authMode: 'query'});// 2. Listen for messagesclient.on('message', (msg) => {console.log(\[${msg.channel_type}\] ${msg.sender_id}: ${msg.payload.text});});// 3. Connectawait client.connect();// 4. Send a direct messageclient.sendDM('bob_123', 'Hello Bob!');Connection Flow
When you call client.connect(), the following sequence occurs sequentially:
1. WebSocket Upgrade Request
Opens WebSocket to
/ws endpoint with JWT in Authorization header or query string.2. JWT Validation
Validates HS256 signature, extracts
tenant_id and user_id from claims.3. Tenant Limit Check
Atomically checks if tenant is under
MAX_USERS_PER_TENANT limit via Redis Lua script.Type Definitions
ServerMessage
interface ServerMessage {type: string; // "chat" or "group_join"message_id: string; // UUID v4tenant_id: string;channel_type: ChannelType;channel_id: string; // recipient user_id or group_idsender_id: string;timestamp: number; // Unix secondsconversation_id: string; // UUID (DM: derived from participants, Group: group_id)payload: {text: string;meta: Record<string, unknown>;};}ChannelType
type ChannelType = "DM" | "GROUP";