npm package: @nicolaferraro/realtime-sdk
Description: Realtime SDK for Redpanda
Latest version: 0.1.0

# Redpanda Realtime SDK

A TypeScript SDK for real-time messaging with Redpanda.

## Installation

```bash
npm install @nicolaferraro/realtime-sdk
```

## Usage

### Basic Example

```typescript
import { Redpanda } from '@nicolaferraro/realtime-sdk';

// Create a client (default: http://localhost:8765)
const redpanda = new Redpanda();

// Or specify a custom URL
// const redpanda = new Redpanda('https://api.example.com');

// Get a channel
const channel = redpanda.channel('my-channel');

// Send data to the channel with a key
await channel.send('user-123', { message: 'Hello, World!' });

// Listen to events from the channel
const stopListening = await channel.listen((key, data) => {
  console.log('Key:', key);
  console.log('Data:', data);
});

// Stop listening when done
stopListening();
```

### Sending Events

```typescript
const channel = redpanda.channel('notifications');

// Send with a key
await channel.send('event-001', {
  event: 'user.login',
  userId: '123',
  timestamp: Date.now()
});
```

### Listening to Events

```typescript
const channel = redpanda.channel('events');

const stop = await channel.listen((key, data) => {
  console.log('Event key:', key);
  console.log('Event data:', data);
});

// Stop listening after 10 seconds
setTimeout(() => stop(), 10000);
```

### Resuming from a Specific Key

The SDK supports resuming streams from a specific key, useful for recovering from disconnections:

```typescript
const channel = redpanda.channel('events');

// Resume from the last processed key
const stop = await channel.listen(
  (key, data) => {
    console.log('Event:', key, data);
  },
  {
    lastKey: 'event-123', // Only receive events after this key
  }
);
```

The SDK automatically tracks the last received key and uses it for reconnection on failures.

### Custom Error Handling

```typescript
const channel = redpanda.channel('events');

const stop = await channel.listen(
  (key, data) => {
    console.log('Received:', key, data);
  },
  {
    onError: (error) => {
      // Custom error handling
      console.error('Channel error:', error);
      // The SDK will automatically retry with exponential backoff
    }
  }
);
```

## API

### `Redpanda`

The main client class.

#### Constructor

```typescript
new Redpanda(baseUrl?: string)
```

- `baseUrl` - Optional base URL (default: `http://localhost:8765`)

#### Methods

- `channel(name: string): RedpandaChannel` - Get a channel interface

### `RedpandaChannel`

Interface for interacting with a specific channel.

#### Methods

- `send(key: string, data: unknown): Promise<void>` - Send data to the channel with a key
- `listen(callback: (key: string, data: unknown) => void, options?: ListenOptions): Promise<() => void>` - Listen to events (returns a stop function)

#### ListenOptions

```typescript
interface ListenOptions {
  lastKey?: string;      // Resume from events after this key
  onError?: (error: Error) => void;  // Custom error handler (defaults to console.error)
}
```

## Features

### Automatic Reconnection

The SDK automatically reconnects with exponential backoff (10ms to 10s) when connections are lost.

### Stream Resumption

When reconnecting, the SDK automatically resumes from the last successfully received event, ensuring no events are missed.

### Data Serialization

All data is automatically serialized to JSON when sending and deserialized from JSON when receiving.