Redpanda Realtime SDK

A TypeScript SDK for real-time messaging with Redpanda.

Installation

npm install @nicolaferraro/realtime-sdk

Usage

Basic Example

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

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

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:

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

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

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

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.