Types Reference

Complete TypeScript type definitions and interfaces for the Erebus Core SDK. Use this reference for type-safe development and IDE autocompletion.

Core Client Types

`ErebusOptions`

Configuration options for the PubSub client constructor:

interface ErebusOptions {
  wsUrl: string; // WebSocket URL
  httpBaseUrl?: string; // HTTP base URL for history API
  tokenProvider: (channel: string) => Promise<string>; // Token provider function
  heartbeatMs?: number; // Heartbeat interval (default: 25000)
  log?: Logger; // Optional logging function
  debug?: boolean; // Enable debug logging
  connectionTimeoutMs?: number; // Connection timeout
  subscriptionTimeoutMs?: number; // Subscription timeout
}

type Logger = (
  level: "info" | "warn" | "error",
  msg: string,
  meta?: unknown,
) => void;

Usage Example:

const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub,
  authBaseUrl: "https://your-auth.com",
  wsBaseUrl: "wss://gateway.erebus.sh",
  heartbeatMs: 30000,
  debug: process.env.NODE_ENV === "development",
  log: (level, msg, meta) => console[level](msg, meta),
} as ErebusOptions);

`MessageBody`

Structure of received messages:

interface MessageBody {
  id: string; // Unique message ID (ULID)
  topic: string; // Topic name
  senderId: string; // Sender's client ID
  seq: string; // Sequence number (ULID)
  sentAt: Date; // Server timestamp
  payload: string; // Message content
  clientMsgId?: string; // Optional client correlation ID
  clientPublishTs?: number; // Client publish timestamp
}

Usage Example:

await client.subscribe("chat", (msg: MessageBody) => {
  console.log(`[${msg.seq}] ${msg.senderId}: ${msg.payload}`);
  console.log(`Sent at: ${msg.sentAt.toISOString()}`);
});

Callback Types

`AckResponse` and `AckCallback`

Types for acknowledgement handling:

type AckCallback = (response: AckResponse) => void;

type AckResponse = AckSuccess | AckError;

type AckSuccess = {
  success: true;
  ack: AckPacketType;
  seq: string;
  serverMsgId: string;
  topic: string;
};

type AckError = {
  success: false;
  ack: AckPacketType;
  error: {
    code: string;
    message: string;
  };
  topic: string;
};

Usage Example:

const ackHandler: AckCallback = (response) => {
  if (response.success) {
    console.log("Message delivered with seq:", response.seq);
  } else {
    console.error("Delivery failed:", response.error.message);
  }
};

await client.publishWithAck("topic", "message", ackHandler);

`SubscriptionCallback` and Response

Types for subscription acknowledgements:

type SubscriptionCallback = (response: SubscriptionResponse) => void;

type SubscriptionResponse = SubscriptionSuccess | SubscriptionError;

type SubscriptionSuccess = {
  success: true;
  ack: AckPacketType;
  topic: string;
  status: "subscribed" | "unsubscribed";
  path: "subscribe" | "unsubscribe";
};

type SubscriptionError = {
  success: false;
  ack?: AckPacketType;
  error: {
    code: string;
    message: string;
  };
  topic: string;
  path: "subscribe" | "unsubscribe";
};

Usage Example:

const subscriptionHandler: SubscriptionCallback = (response) => {
  if (response.success) {
    console.log(`Successfully ${response.status} to ${response.topic}`);
  } else {
    console.error(`Subscription failed: ${response.error.message}`);
  }
};

client.subscribeWithCallback("topic", messageHandler, subscriptionHandler);

Subscription Types

`SubscribeOptions`

Options for subscription behavior:

interface SubscribeOptions {
  streamOldMessages?: boolean; // Deliver missed messages (default: false)
}

Usage Example:

await client.subscribe(
  "chat",
  (msg) => console.log(msg),
  { streamOldMessages: true }, // Catch up on missed messages
);

Message Handler Types

// Basic message handler
type MessageHandler = (message: MessageBody) => void;

// Handler with metadata (used internally)
type Handler = (
  payload: MessageBody,
  meta: { topic: string; seq: string; ts: number },
) => void;

Presence Types

`Presence` and `PresenceHandler`

Presence event structure:

interface Presence {
  clientId: string; // Client that changed status
  topic: string; // Topic name
  status: "online" | "offline"; // Presence status
  timestamp: number; // Event timestamp
  subscribers?: string[]; // Optional: list of current subscribers
}

type PresenceHandler = (presence: Presence) => void;

Usage Example:

const presenceHandler: PresenceHandler = (presence) => {
  console.log(
    `${presence.clientId} is ${presence.status} on ${presence.topic}`,
  );
  updateUserList(presence.clientId, presence.status);
};

await client.onPresence("chat", presenceHandler);

History Types

`HistoryResponse` and Options

interface HistoryResponse {
  items: MessageBody[]; // Array of messages
  nextCursor: string | null; // Cursor for next page (null = no more)
}

interface HistoryOptions {
  cursor?: string; // ULID cursor for pagination
  limit?: number; // Messages per page (1-1000, default: 50)
  direction?: "forward" | "backward"; // Sort order (default: "backward")
}

Usage Example:

const history: HistoryResponse = await client.getHistory("chat", {
  limit: 100,
  direction: "backward",
} as HistoryOptions);

console.log(`Fetched ${history.items.length} messages`);
if (history.nextCursor) {
  console.log("More messages available");
}

History Iterator Types

type HistoryIterator = () => Promise<{
  items: MessageBody[];
  hasMore: boolean;
} | null>;

Usage Example:

const iterator: HistoryIterator = client.createHistoryIterator("chat", {
  limit: 50,
});

const batch = await iterator();
if (batch && batch.hasMore) {
  console.log("More batches available");
}

State and Connection Types

Connection States

type ConnectionState = "idle" | "connecting" | "open" | "error" | "closed";
type SubscriptionStatus = "subscribed" | "unsubscribed" | "pending";

Usage Example:

function checkConnectionState(client: ErebusPubSubClient) {
  if (client.isConnected) {
    console.log("Client is connected and ready");
  }

  // Monitor state changes
  setInterval(() => {
    console.log("Connected:", client.isConnected);
    console.log("Readable:", client.isReadable);
    console.log("Writable:", client.isWritable);
  }, 5000);
}

Pending Operation Types

type PendingPublish = {
  requestId: string;
  clientMsgId: string;
  topic: string;
  callback: AckCallback;
  timestamp: number;
  timeoutId?: NodeJS.Timeout;
};

type PendingSubscription = {
  requestId: string;
  clientMsgId?: string;
  topic: string;
  path: "subscribe" | "unsubscribe";
  callback: SubscriptionCallback;
  timestamp: number;
  timeoutId?: NodeJS.Timeout;
};

Enums

`ErebusClientState`

enum ErebusClientState {
  PubSub = 0, // Select PubSub client
}

Usage Example:

const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub, // Type-safe client selection
  authBaseUrl: "https://auth.example.com",
});

`Access`

enum Access {
  ReadWrite = "rw", // Full read/write access
  Read = "r", // Read-only access
  Write = "w", // Write-only access
}

Usage Example:

import { Access } from "@erebus-sh/sdk/service";

session.allow("chat:*", Access.ReadWrite); // Full access to chat topics
session.allow("announcements", Access.Read); // Read-only access to announcements

Generic Types

Schema Types (for Typed Facade)

type SchemaMap = Record<string, z.ZodType>;

type Topic<S extends SchemaMap> = Extract<keyof S, string>;

type Payload<S extends SchemaMap, K extends Topic<S>> = z.infer<S[K]>;

type TypedMessage<P> = Omit<MessageBody, "payload"> & { payload: P };

type MessageFor<S extends SchemaMap, K extends Topic<S>> = TypedMessage<
  Payload<S, K>
>;

Usage Example:

import { z } from "zod";

const schemas = {
  chat: z.object({
    text: z.string(),
    username: z.string(),
  }),
  notification: z.object({
    title: z.string(),
    urgent: z.boolean(),
  }),
} as const;

type ChatSchema = typeof schemas;
type ChatTopic = Topic<ChatSchema>; // "chat" | "notification"
type ChatMessage = MessageFor<ChatSchema, "chat">; // Typed message with chat payload

Utility Types

Client Interface

interface IPubSubClient<TTopic, TPayload, TMessage> {
  connect(timeout?: number): Promise<void>;
  joinChannel(channel: string): void;
  close(): void;

  publish<K extends TTopic>(topic: K, payload: TPayload): Promise<string>;
  publishWithAck<K extends TTopic>(
    topic: K,
    payload: TPayload,
    onAck: AckCallback,
    timeoutMs?: number,
  ): Promise<string>;

  subscribe<K extends TTopic>(
    topic: K,
    handler: (message: TMessage) => void,
    options?: SubscribeOptions,
  ): Promise<void>;

  unsubscribe<K extends TTopic>(topic: K): void;

  onPresence<K extends TTopic>(
    topic: K,
    handler: PresenceHandler,
  ): Promise<void>;

  get isConnected(): boolean;
  get isReadable(): boolean;
  get isWritable(): boolean;
}

Error Types

interface ErebusError extends Error {
  code?: string;
  context?: Record<string, unknown>;
}

type ErrorCode =
  | "CONNECTION_ERROR"
  | "TIMEOUT"
  | "INVALID_TOPIC"
  | "NOT_CONNECTED"
  | "MALFORMED_ACK"
  | "SUBSCRIPTION_ERROR";

Type Guards

Utility functions for type checking:

// Check if response is successful
function isAckSuccess(response: AckResponse): response is AckSuccess {
  return response.success;
}

function isSubscriptionSuccess(
  response: SubscriptionResponse,
): response is SubscriptionSuccess {
  return response.success;
}

// Check connection state
function isConnected(client: ErebusPubSubClient): boolean {
  return client.isConnected && client.isReadable && client.isWritable;
}

Usage Example:

client.publishWithAck("topic", "message", (ack) => {
  if (isAckSuccess(ack)) {
    // TypeScript knows ack has seq, serverMsgId properties
    console.log("Success! Seq:", ack.seq);
  } else {
    // TypeScript knows ack has error property
    console.error("Failed:", ack.error.message);
  }
});

Advanced Type Patterns

Typed Message Handlers

// Create typed message handler
function createTypedHandler<T>(
  validator: (data: unknown) => data is T,
  handler: (payload: T, msg: MessageBody) => void,
): (msg: MessageBody) => void {
  return (msg) => {
    try {
      const parsed = JSON.parse(msg.payload);
      if (validator(parsed)) {
        handler(parsed, msg);
      } else {
        console.warn("Invalid message format:", parsed);
      }
    } catch (error) {
      console.error("Failed to parse message:", error);
    }
  };
}

// Usage
interface ChatMessage {
  text: string;
  username: string;
}

const isChatMessage = (data: unknown): data is ChatMessage => {
  return (
    typeof data === "object" &&
    data !== null &&
    "text" in data &&
    "username" in data
  );
};

const chatHandler = createTypedHandler(isChatMessage, (payload, msg) => {
  console.log(`${payload.username}: ${payload.text}`);
  console.log(`Sent at: ${msg.sentAt}`);
});

await client.subscribe("chat", chatHandler);

Next Steps

Getting Started - Basic API walkthrough
Messaging APIs - Publish and subscribe patterns
Connection Management - Connection lifecycle
Schema Facade - Type-safe messaging with validation

Types Reference

On this page