Evenimente

Conținutul complet care locuia aici este acum împărțit în noua secțiune Realtime:

• Prezentare generală Realtime — ce este @e-bon/realtime și în ce diferă de SDK-ul REST.
• 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.

Clasa EventSubscriber a fost înlocuită de RealtimeClient din @e-bon/realtime. API-ul de listeneri (on / off / once) și numele evenimentelor sunt neschimbate — doar calea de import și constructorul diferă.

Mesaje de ieșire (dispozitive)

De la redesign-ul alpha, RealtimeClient expune și o mică suprafață de ieșire, astfel încât un dispozitiv să poată răspunde la comenzile primite și să trimită actualizări de stare pe aceeași conexiune (vezi Scheme realtime):

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

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

// Trimitere generică — orice cadru dispozitiv→server validat de `clientToServerMessageSchema`.
rt.send({
  type: 'status',
  clientMessageId: makeId(),
  deviceStatus: { online: true },
});

// Wrappere de conveniență pentru cele două forme de răspuns.
rt.sendCommandResult({
  commandId: 'cmd_abc',
  clientMessageId: makeId(),
  result: { fiscalId: 'F-100', success: true },
});

rt.sendCommandError({
  commandId: 'cmd_abc',
  clientMessageId: makeId(),
  error: { message: 'imprimanta offline', code: 'E_DEVICE' },
});

Contractul de idempotență clientMessageId

Fiecare cadru dispozitiv→server trebuie să includă un clientMessageId. Serverul îl folosește pentru deduplicarea reîncercărilor în cazul livrării at-least-once — trimiterea aceluiași (commandId, clientMessageId) de două ori este sigură și produce un singur rezultat observat. Generează un id nou pentru fiecare încercare de răspuns (un sufix scurt aleatoriu concatenat cu un timestamp este suficient; câmpul este doar un șir opac, non-vid).

Semantica de livrare (alpha)

Dacă socket-ul subiacent nu este OPEN atunci când apelezi send / sendCommandResult / sendCommandError, cadrul este eliminat și se emite un console.warn — nu există coadă internă de ieșire în această versiune. Apelanții care au nevoie de răspunsuri durabile ar trebui să retrimită după următorul eveniment connected (sau să se bazeze pe cursorul at-least-once: serverul va redistribui comanda fără răspuns în următoarea sesiune).