Pornire rapidă

Această pagină te duce de la pnpm add la un listener live în sub un minut. Dacă încă nu ai o cheie API, Ghidul rapid pentru dezvoltatori trece prin crearea unei organizații și copierea uneia.

Instalare

pnpm add @e-bon/realtime

npm install @e-bon/realtime și yarn add @e-bon/realtime funcționează la fel. Pachetul are o singură dependență de runtime pe @e-bon/types și vine cu declarații TypeScript incluse.

Instanțierea clientului

RealtimeClient primește un baseUrl și un obiect RealtimeClientOptions cu unul din două moduri de autentificare — niciodată ambele în același timp. Constructorul se conectează imediat; nu există o metodă connect().

Cu o cheie API (parteneri POS, integrări de server)

import { RealtimeClient } from '@e-bon/realtime';

const realtime = new RealtimeClient('https://api.e-bon.ro', {
  apiKey: process.env.EBON_API_KEY!,
});

Clientul rescrie https:// → wss://, adaugă /ws și trimite cheia API ca parametru de query apiKey.

Cu un JWT (sesiuni Portal, aplicația mobilă)

import { RealtimeClient } from '@e-bon/realtime';

const realtime = new RealtimeClient('https://api.e-bon.ro', {
  token: 'eyJ...',
});

Token-ul este trimis ca parametru de query token și are prioritate față de apiKey când sunt setate amândouă.

Opțiuni

Dacă nu pasezi nici apiKey, nici token, gateway-ul va respinge handshake-ul WebSocket cu un 401.

Înregistrează primul listener

on / off / once sunt tipate prin uniunea EventName derivată din EventMap, deci payload-ul listener-ului este inferat pentru tine:

import { RealtimeClient, type ReceiptCreatedEvent } from '@e-bon/realtime';

const realtime = new RealtimeClient('https://api.e-bon.ro', {
  apiKey: process.env.EBON_API_KEY!,
});

realtime.on('connected', () => console.log('realtime: live'));
realtime.on('disconnected', () => console.warn('realtime: se reconectează…'));

realtime.on('receipt.created', (event: ReceiptCreatedEvent) => {
  console.log(`bon ${event.receiptId} pe dispozitivul ${event.deviceId} = ${event.total}`);
});

realtime.on('command.failed', (event) => {
  // event.fiscalError este o instanță reală FiscalError — o poți arunca direct.
  console.error(event.fiscalError);
});

// Mai târziu, la oprire:
process.on('SIGTERM', () => realtime.close());

Erorile aruncate dintr-un listener sunt înghițite — un throw într-un listener nu va opri ceilalți listeneri să ruleze și nu va distruge bucla WebSocket.

Unde mergi mai departe

• Evenimente — catalogul complet al evenimentelor pe care te poți abona.
• Reconectare și ciclu de viață — programul de backoff, suspend / resume și hook-ul CursorStore.
• Scheme — cadrele de protocol dacă îți construiești un client custom.