@realtmz/sdk

The official Realtmz WebSocket SDK for real-time applications.

Installation

npm install @realtmz/sdk

Quick Start

import { Realtmz } from '@realtmz/sdk';

// Create instance and connect
const client = new Realtmz('your-token-here');
await client.connect();

// Subscribe to a topic and receive data
client.subscribe('notifications', (data) => {
  console.log('New notification:', data);
});

// Or use method chaining
client.subscribe('notifications')
  .on('message', (data) => {
    console.log('Notification received:', data);
  });

Features

• ✅ Auto Reconnect - Automatically reconnects when connection is lost
• ✅ Message Queue - Queues messages when disconnected and sends them when reconnected
• ✅ Auto Resubscribe - Automatically resubscribes to previous topics after reconnection
• ✅ Wildcard Support - Pattern matching for topics using * wildcard
• ✅ TypeScript - Full TypeScript support with type definitions
• ✅ Promise-based - Supports async/await

API Reference

Constructor

new Realtmz(token: string, options?: { endpoint?: string })

Parameters:

• token (string): Authentication token for connection
• options.endpoint (string, optional): WebSocket endpoint URL (default: wss://api.realtmz.com/v1/ws)

Example:

// Use default endpoint
const client = new Realtmz('your-token');

// Use custom endpoint
const client = new Realtmz('your-token', {
  endpoint: 'wss://custom-endpoint.com/ws'
});

Methods

connect(): Promise<void>

Connects to the WebSocket server and enables auto-reconnect

await client.connect();

subscribe(topic: string, callback?: EventHandler)

Subscribes to a topic to receive real-time data

Parameters:

• topic (string): The topic name to subscribe to
• callback (EventHandler, optional): Function called when new data arrives

Returns: Object with on() method for method chaining

Example:

// Method 1: Use callback
client.subscribe('notifications', (data) => {
  console.log(data);
});

// Method 2: Use method chaining
client.subscribe('notifications')
  .on('message', (data) => {
    console.log(data);
  });

// Method 3: Use on() separately
client.subscribe('notifications');
client.on('notifications', (data) => {
  console.log(data);
});

on(topic: string, callback: EventHandler)

Adds an event listener for a topic

Parameters:

• topic (string): Topic name or pattern (supports wildcard *)
• callback (EventHandler): Function called when new data arrives

Example:

// Subscribe to specific topic
client.on('notifications', (data) => {
  console.log('Notification:', data);
});

// Use wildcard pattern
client.on('user.*', (data) => {
  console.log('User event:', data);
});
// Matches 'user.created', 'user.updated', 'user.deleted', etc.

disconnect(): void

Disconnects and stops auto-reconnect (use when logging out or no longer need connection)

client.disconnect();

Advanced Usage

Auto Reconnect Configuration

The SDK automatically attempts to reconnect when the connection is lost using exponential backoff:

• Starts at 1 second
• Doubles on each retry attempt (1s, 2s, 4s, 8s, ...)
• Maximum delay of 30 seconds
• Includes jitter (random 0-1 second) to prevent thundering herd
• Maximum 10 retry attempts

Message Queue

When disconnected, messages are queued and automatically sent when the connection is restored.

Wildcard Pattern Matching

Supports wildcard pattern matching for topics:

// Subscribe to all topics starting with 'user.'
client.on('user.*', (data) => {
  console.log('User event:', data);
});

// Matches:
// - user.created
// - user.updated
// - user.deleted
// But does NOT match:
// - users.list
// - admin.user

Multiple Handlers

You can add multiple handlers for the same topic:

client.on('notifications', (data) => {
  console.log('Handler 1:', data);
});

client.on('notifications', (data) => {
  console.log('Handler 2:', data);
});

// Both handlers will be called when new data arrives

Examples

Basic Usage

import { Realtmz } from '@realtmz/sdk';

const client = new Realtmz('your-token-here');

try {
  await client.connect();
  console.log('Connected!');
  
  client.subscribe('notifications', (data) => {
    console.log('Notification:', data);
  });
} catch (error) {
  console.error('Connection failed:', error);
}

React Example

import { useEffect, useState } from 'react';
import { Realtmz } from '@realtmz/sdk';

function NotificationComponent() {
  const [notifications, setNotifications] = useState([]);

  useEffect(() => {
    const client = new Realtmz('your-token');
    
    client.connect().then(() => {
      client.subscribe('notifications', (data) => {
        setNotifications(prev => [...prev, data]);
      });
    });

    return () => {
      client.disconnect();
    };
  }, []);

  return (
    <div>
      {notifications.map((notif, i) => (
        <div key={i}>{notif.message}</div>
      ))}
    </div>
  );
}

Node.js Example

import { Realtmz } from '@realtmz/sdk';
import WebSocket from 'ws';

// For Node.js, you need a WebSocket polyfill
global.WebSocket = WebSocket;

const client = new Realtmz('your-token');

client.connect().then(() => {
  client.subscribe('events', (data) => {
    console.log('Event received:', data);
  });
});

License

MIT