@sonicus-sdk/core

⚠️ BETA VERSION - USE WITH CAUTION ⚠️

This package is currently in beta. All APIs are subject to change without notice. Breaking changes may occur in any release until version 1.0.0.

Overview

@sonicus-sdk/core is a real-time communication SDK that provides WebSocket-based functionality for:

• Presence management
• Channel-based messaging
• Chat functionality with reactions and typing indicators
• Cursor position sharing
• Automatic reconnection handling

Important Notice

• This is a pre-release version
• APIs are unstable and may change
• Breaking changes are expected
• Not recommended for production use
• Use at your own risk

Installation

npm install @sonicus-sdk/core@beta

Basic Usage

import { SonicusClient } from '@sonicus-sdk/core';

// Define your presence status type
type UserPresence = {
  status: 'online' | 'offline' | 'away';
  timestamp: string;
};

// Create a WebSocket handler
const wsHandler = {
  onMessage: (message) => {
    console.log('Received message:', message);
  },
  onError: (event) => {
    console.error('WebSocket error:', event);
  },
  onClose: (event) => {
    console.log('WebSocket closed:', event);
  },
  onOpen: (event) => {
    console.log('WebSocket connected:', event);
  },
};

// Initialize the client
const client = new SonicusClient<UserPresence>({
  authUrl: '/api/sonicus/jwt/issue',
  wsUrl: 'wss://sonicus-platform.fly.dev',
}, wsHandler);

// Initialize the connection
await client.init();

Features

Presence Management

• Track user presence status
• Update presence information
• Monitor group presence

Channel Communication

• Join/leave channels
• Send/receive messages
• Broadcast messages to channel members

Chat Functionality

• Join/leave chat rooms
• Send messages with reactions
• Typing indicators
• Message reactions

Cursor Position Sharing

• Share cursor positions in real-time
• Track multiple users' cursor positions
• Join/leave cursor sharing groups

Configuration Options

interface SonicusConfig {
  authUrl?: string;              // Default: '/api/sonicus/jwt/issue'
  refreshUrl?: string;           // Default: '/api/sonicus/jwt/refresh'
  authMethod?: 'GET' | 'POST' | 'PUT';
  headers?: Record<string, string>;
  wsUrl?: string;                // Default: 'wss://sonicus-platform.fly.dev'
  reconnectInterval?: number;    // Default: 5000ms
  maxReconnectAttempts?: number; // Default: 5
  defaultPresenceStatus?: T;     // Custom presence status type
}

Connection States

The client maintains the following connection states:

• connecting: Initial connection attempt
• connected: Successfully connected
• disconnected: Not connected
• reconnecting: Attempting to reconnect after disconnection

Documentation

Documentation is subject to change. Please refer to the latest version for the most up-to-date information.

Contributing

While this package is in beta, we welcome feedback and bug reports. Please open an issue if you encounter any problems.

License

[License information will be added before final release]