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 Core Client 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/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.

SDK Reference