Realtime

Evenimente

Payload-urile de evenimente partenere servite pe canalul realtime, plus tipurile EventMap / EventName.

Evenimente

Canalul realtime livrează unsprezece payload-uri de evenimente partenere plus trei evenimente locale de ciclu de viață. Cheile din tabelul de mai jos sunt exact șirurile pe care le pasezi lui on / off / once; coloana de payload este forma tipată a celui de-al doilea argument.

Șir eveniment	Tip payload	Se declanșează când
`device.status`	`DeviceStatusEvent`	Statusul de conexiune al unui dispozitiv se schimbă (online / offline / busy).
`device.claimed`	`DeviceClaimedEvent`	Un controler (instanță a aplicației mobile E-BON) revendică un dispozitiv.
`device.released`	`DeviceReleasedEvent`	Un controler eliberează un dispozitiv — acesta devine neatribuit și doar-cloud.
`device.deleted`	`DeviceDeletedEvent`	Un admin de organizație șterge rândul dispozitivului; identitatea este păstrată.
`device.alert`	`DeviceAlertEvent`	Setul de alerte derivate al unui dispozitiv se schimbă (ex. hârtie terminată, offline, raport Z scadent). Un array `alerts` gol înseamnă că totul e în regulă.
`receipt.created`	`ReceiptCreatedEvent`	Un bon fiscal este stocat pe platformă.
`command.completed`	`CommandCompletedEvent`	O comandă fiscală se termină cu succes la imprimantă.
`command.failed`	`CommandFailedEvent`	O comandă fiscală eșuează pe dispozitiv. Payload-ul include un `fiscalError` precalculat.
`command.timeout`	`CommandTimeoutEvent`	O comandă în așteptare expiră înainte ca dispozitivul să răspundă.
`app.connected`	`AppConnectedEvent`	O instanță a aplicației mobile E-BON își deschide WebSocket-ul către server.
`app.disconnected`	`AppDisconnectedEvent`	O instanță a aplicației mobile E-BON se deconectează.
`connected`	`undefined`	Socket-ul realtime tocmai s-a (re)deschis — doar ciclu de viață local.
`disconnected`	`undefined`	Socket-ul realtime tocmai a căzut — doar ciclu de viață local.
`error`	`Error`	Socket-ul realtime a emis o eroare — doar ciclu de viață local.

Tipurile de payload exportate sunt: DeviceStatusEvent, DeviceClaimedEvent, DeviceReleasedEvent, DeviceDeletedEvent, DeviceAlertEvent, ReceiptCreatedEvent, CommandCompletedEvent, CommandFailedEvent, CommandTimeoutEvent, AppConnectedEvent și AppDisconnectedEvent. Toate pot fi importate ca tipuri din @e-bon/realtime. command.timeout este un eveniment propriu pe fir — abonează-te la el pentru a distinge „imprimanta nu a răspuns" de command.failed („imprimanta a refuzat"), sau tratează-le pe ambele prin același listener dacă distincția nu contează pentru tine.

Formele payload-urilor

Fiecare payload este derivat dintr-o schemă zod exportată de pachetul @e-bon/realtime — schemele sunt sursa unică de adevăr, iar tipurile TypeScript sunt inferate din ele.

`DeviceStatusEvent`

{
  deviceId: string;
  status: DeviceStatus; // 'online' | 'offline' | 'busy' | …
  timestamp: string;    // ISO-8601
}

`DeviceClaimedEvent`

{
  deviceId: string;
  controllerId: string;
  controllerName: string;
  timestamp: string;
}

`DeviceAlertEvent`

{
  deviceId: string;
  alerts: DeviceAlert[];
}

`ReceiptCreatedEvent`

{
  receiptId: string;
  deviceId: string;
  total: number;
  timestamp: string;
}

`CommandCompletedEvent`

{
  commandId: string;
  deviceId: string;
  type: CommandType;
  result: unknown;
  timestamp: string;
}

`CommandFailedEvent`

{
  commandId: string;
  deviceId: string;
  type: CommandType;
  error: string;
  errorCode: ErrorCode;
  retryable: boolean;
  timestamp: string;
  /** Construit de client înainte de dispatch — instanță aruncabilă convenabilă. */
  fiscalError: FiscalError;
}

`CommandTimeoutEvent`

{
  id: string;
  deviceId: string;
  type: CommandType;
  error: string;
  errorCode: ErrorCode;
  retryable: boolean;
  timestamp: string;
}

`AppConnectedEvent` / `AppDisconnectedEvent`

{
  deviceId: string;
  timestamp: string;
}

Ascultă cu `on`, `off`, `once`

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('device.status', (data) => {
  // data: DeviceStatusEvent { deviceId, status, timestamp }
});

const handler = (data: ReceiptCreatedEvent) => { /* … */ };
realtime.on('receipt.created', handler);
realtime.off('receipt.created', handler); // elimină un listener anume

realtime.once('command.completed', (data) => {
  // se declanșează exact o dată și se dezînregistrează singur
});

Exemplu — reacționează la `receipt.created`

Un worker minim care oglindește fiecare bon fiscal într-un jurnal de audit local prin SDK-ul REST:

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

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

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', async (event: ReceiptCreatedEvent) => {
  // Aducem bonul fiscal complet acum că îi știm id-ul.
  const receipt = await client.receipts.get(event.receiptId);
  await auditLog.append({
    receiptId: receipt.id,
    deviceId: event.deviceId,
    total: event.total,
    timestamp: event.timestamp,
  });
});

process.on('SIGTERM', () => realtime.close());

Unde mergi mai departe

Reconectare și ciclu de viață — programul de backoff, close, suspend / resume, CursorStore.
Scheme — cadrele de protocol subiacente dacă îți construiești un client custom, plus API-ul dispozitiv→server send / sendCommandResult / sendCommandError.
SDK › Erori — forma FiscalError atașată payload-urilor command.failed.
API › Webhook-uri — apeluri HTTP de ieșire dacă nu poți menține un WebSocket cu durată lungă deschis.

Pornire rapidă

Instalează @e-bon/realtime, instanțiază RealtimeClient cu o cheie API sau JWT și înregistrează primul listener de evenimente.

Reconectare și ciclu de viață

Programul de auto-reconectare, controalele close / suspend / resume și hook-ul CursorStore pentru livrarea viitoare at-least-once.