Prezentare generală Realtime

@e-bon/realtime este clientul WebSocket oficial pentru canalul de evenimente e-bon (wss://api.e-bon.ro/ws). Este pachetul pe care îl folosesc atât Portalul e-bon, cât și aplicația E-BON pentru Android, și este modul recomandat de a primi actualizări live din orice runtime TypeScript sau JavaScript modern (Node 22+, Deno, Bun, browsere moderne).

Este intenționat un pachet separat de @e-bon/sdk. SDK-ul este doar REST; tot ce e live — bonuri tipărite, comenzi finalizate, dispozitive ieșite offline, alerte care se schimbă — curge prin canalul realtime. Cele două pachete partajează @e-bon/types, dar nu au altă cuplare, deci poți instala doar cel de care ai nevoie.

Ce îți oferă @e-bon/realtime peste un WebSocket brut:

• Un RealtimeClient tipat cu listeneri on / off / once, o metodă close() și control prin suspend() / resume().
• Reconectare automată cu backoff exponențial (1s → 30s, plafonat).
• Validare zod strictă pe cadrele de protocol — mesajele incorecte sunt aruncate cu un console.warn și nu ajung niciodată la listenerii tăi.
• Un hook CursorStore pentru ca livrarea viitoare at-least-once (E-1b / E-10) să poată conecta un strat de persistență fără să schimbi codul tău.
• Opt tipuri de payload de evenimente partenere, toate derivate din scheme zod exportate de @e-bon/realtime.

Clientul folosește WebSocket-ul nativ al runtime-ului — nu este inclus niciun polyfill. Pe Node necesită Node 22 sau mai nou.

Când să-l folosești

Dacă nu poți menține o conexiune cu durată lungă (joburi pornite din cron, funcții edge cu ferestre scurte de execuție), preferă webhook-urile în locul clientului realtime.

Unde mergi mai departe

• Pornire rapidă — instalează @e-bon/realtime, instanțiază RealtimeClient și înregistrează primul listener.
• Evenimente — cele opt payload-uri de evenimente partenere și tipurile EventMap / EventName.
• Reconectare și ciclu de viață — programul de backoff, close, suspend / resume și hook-ul CursorStore.
• Scheme — cadrele server→dispozitiv și dispozitiv→server, plus granița clientMessageId.
• Prezentare generală SDK — pachetul companion REST.