SDKs

Herald has two categories of SDKs: WebSocket clients for real-time connections in browsers and mobile apps, and HTTP admin clients for server-side management. Admin SDKs are codegen-managed from the OpenAPI spec.

WebSocket SDKs

These run in the browser or mobile app. They handle connection management, reconnect with catch-up, deduplication, and optional ack mode.

Package	Description
`herald-sdk-typescript`	Core WebSocket client. Auto-reconnect, sequence-based catch-up, deduplication.
`herald-chat-sdk-typescript`	Chat extensions. Edit, delete, reactions, read cursors, typing, blocking.
`herald-presence-sdk-typescript`	Presence extensions. Manual overrides, expiry, presence clearing.
`herald-chat-core`	Framework-agnostic chat state machine. Messages, members, presence, typing, cursors.
`herald-chat-react`	React hooks and headless components built on `herald-chat-core`.

Browser example

import { HeraldClient } from "herald-sdk-typescript";

const client = new HeraldClient({
  url: "wss://herald.skeptik.io/ws",
  key: "YOUR_KEY",
  token: "SIGNED_TOKEN",
  userId: "alice",
  streams: ["stream_1"],
});

client.on("event.new", (event) => {
  console.log(event.body);
});

client.connect();

React example

import { useHeraldChat } from "herald-chat-react";

function ChatRoom({ streamId }: { streamId: string }) {
  const { messages, sendMessage } = useHeraldChat(streamId);

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.body.text}</div>
      ))}
    </div>
  );
}

Admin SDKs

These run on your backend for stream management, member operations, event injection, and token generation.

Language	Package	Install
TypeScript	`herald-admin-typescript`	`npm install herald-admin-typescript`
Go	`herald-admin-go`	`go get github.com/skeptik-io/herald-admin-go`
Python	`herald-admin-python`	`pip install herald-admin-python`
Ruby	`herald-admin-ruby`	`gem install herald-admin-ruby`
PHP	`herald-admin-php`	`composer require skeptik-io/herald-admin-php`
C#	`herald-admin-csharp`	`dotnet add package HeraldAdmin`

Server-side example

import { HeraldAdmin } from "herald-admin-typescript";

const herald = new HeraldAdmin({
  baseUrl: "https://herald.skeptik.io",
  key: "YOUR_KEY",
  secret: "YOUR_SECRET",
});

// Create a stream
const stream = await herald.streams.create({
  name: "general",
  meta: { topic: "General discussion" },
});

// Add a member
await herald.members.add(stream.id, {
  userId: "alice",
  role: "member",
});

// Generate a connection token
const token = await herald.tokens.create({
  userId: "alice",
  streams: [stream.id],
  ttl: 3600,
});