Erebus SDK

The Erebus SDK gives you everything you need to build real-time apps on top of Erebus pub/sub.
It provides a type-safe and raw Core Client and a type-safe React Client with hooks for subscription, publishing, and presence.

Installation

npm install @erebus-sh/sdk

Packages

Currently shipped as a single package:

@erebus-sh/sdk/client – low-level client APIs
@erebus-sh/sdk/react – React hooks on top of the core (Experimental/Unstable)
@erebus-sh/sdk/server – Server-side SDK for building Erebus servers
@erebus-sh/sdk/service – Helpers for server-side authorization and sessions But it's also available on:
@erebus-sh/sdk – All packages in one exported in a barrel file (will change in the future)

Core APIs

The Core Client provides stable, type-safe APIs for interacting with Erebus pub/sub and messaging infrastructure. Key features include:

Core Features

Real-time messaging: Publish and subscribe to topics with guaranteed message ordering
Presence tracking: Automatic presence events when clients join/leave topics
Message history: Fetch historical messages with cursor-based pagination
Type safety: Full TypeScript support with schema validation facade
Connection management: Automatic reconnection with exponential backoff
Acknowledgments: MQTT-style ACK system with QoS 1 support

Advanced Capabilities

ULID sequences: Lexicographically sortable message ordering for replay and catch-up
Schema facade: Runtime validation with Zod schemas for type-safe messaging
Error handling: Comprehensive error types and recovery patterns
State management: Connection state monitoring and lifecycle events
Flexible subscriptions: Multiple subscription patterns with options and callbacks

Documentation Sections

Complete API Reference - All methods, types, and examples
Message History - Pagination, cursors, and advanced patterns
Schema Facade - Type-safe messaging with validation
Quick Reference - Common patterns and cheat sheet

import { ErebusClient, ErebusClientState } from '@erebus-sh/sdk'

const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub,
  authBaseUrl: 'http://localhost:4919',
  wsBaseUrl: 'ws://localhost:8787',
})

client.joinChannel('chats')
await client.connect()

await client.subscribe('test_123', (msg) => {
  console.log('Received:', msg.payload, 'from', msg.senderId)
})

await client.onPresence('test_123', (presence) => {
  console.log('Presence:', presence)
})

await client.publishWithAck(
  'test_123',
  'Hello Erebus 👋',
  (ack) => {
    console.log('Message acknowledged:', ack.success ? 'Success' : `Failed: ${ack.error?.message}`)
  },
  3000
)

For a full end-to-end example (including a Bun-based auth server using createGenericAdapter and webhooks), see the Core Client APIs page.

React Package (Experimental)

The React package (@erebus-sh/sdk/react) is experimental and its API will change. It provides React hooks for subscription, publishing, and presence, built on top of the core client.

SDK Reference