npm package: @realtmz/sdk
Description: The official Realtmz WebSocket SDK for real-time applications.
Author: Realtmz Team
Latest version: 1.0.2

# @realtmz/sdk

The official Realtmz WebSocket SDK for real-time applications.

## Installation

```bash
npm install @realtmz/sdk
```

## Quick Start

```typescript
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

```typescript
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:**
```typescript
// 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

```typescript
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:**
```typescript
// 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:**
```typescript
// 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)

```typescript
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:

```typescript
// 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:

```typescript
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

```typescript
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

```typescript
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

```typescript
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