Realtime overview

@e-bon/realtime is the official WebSocket client for the e-bon events channel (wss://api.e-bon.ro/ws). It is the package the e-bon Portal and the E-BON Android app both build on, and is the recommended way to receive live updates from any TypeScript or modern JavaScript runtime (Node 22+, Deno, Bun, modern browsers).

It is intentionally a separate package from @e-bon/sdk. The SDK is REST-only; everything live — receipts being printed, commands finishing, devices going offline, alerts changing — flows over the realtime channel instead. The two packages share @e-bon/types but have no other coupling, so you can pull in just the one you need.

What @e-bon/realtime gives you on top of a raw WebSocket:

• A typed RealtimeClient with on / off / once listeners, a close() method, and suspend() / resume() controls.
• Automatic reconnect with exponential backoff (1s → 30s, capped).
• Strict zod validation on the wire-protocol frames — malformed messages are dropped with a console.warn and never reach your listeners.
• A CursorStore hook so future at-least-once delivery (E-1b / E-10) can plug a persistence layer in without changing your code.
• Eight partner-facing event payload types, all derived from zod schemas exported by @e-bon/realtime.

The client uses the runtime's native WebSocket — no polyfill is bundled. On Node it requires Node 22 or newer.

When to reach for it

If you cannot keep a long-lived connection open (cron-driven jobs, edge functions with short execution windows), prefer webhooks over the realtime client.

Where to next

• Getting started — install @e-bon/realtime, instantiate RealtimeClient and register your first listener.
• Events — the eight partner-facing event payloads and the EventMap / EventName types.
• Reconnect and lifecycle — backoff schedule, close, suspend / resume, and the CursorStore hook.
• Schemas — server→device and device→server wire frames, plus the clientMessageId boundary.
• SDK overview — the REST companion package.