SDK overview

@e-bon/sdk is the official TypeScript client for the e-bon REST API and events WebSocket. It is the same library used internally by the e-bon Portal and is the recommended way to talk to https://api.e-bon.ro from any TypeScript or modern JavaScript runtime (Node 22+, Deno, Bun, modern browsers).

What the SDK gives you on top of raw fetch:

• A typed EBonClient with one accessor per resource (devices, commands, receipts, …).
• Automatic auth header handling — pass an API key or a JWT once and forget about it.
• A real EBonApiError exception with status, code, details and retryAfter so you can branch on the error envelope without parsing JSON yourself.
• A FiscalError exception for fiscal command failures, with a precomputed retryable flag.
• An EventSubscriber that wraps the events WebSocket with auto-reconnect and typed event payloads.

The SDK is a thin, faithful mapping over the documented HTTP API. Everything it does is also possible with curl — see the API overview for the wire-level reference.

Install

pnpm add @e-bon/sdk

The package is also installable with npm install @e-bon/sdk or yarn add @e-bon/sdk. It has a single runtime dependency (@e-bon/types) and ships with TypeScript declarations.

Instantiate the client

EBonClient is the single entry point. It takes an EBonClientOptions object with one of two auth modes — never both at once.

With an API key (POS partners, server integrations)

import { EBonClient } from '@e-bon/sdk';

const client = new EBonClient({
  baseUrl: 'https://api.e-bon.ro',
  apiKey: 'ebon_live_<orgId>_<32-hex>',
});

The SDK sends the key as X-API-Key on every request. This is the mode you want for any unattended backend.

With a JWT (portal sessions, the mobile app)

import { EBonClient } from '@e-bon/sdk';

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

The SDK sends the token as Authorization: Bearer <token>. After a refresh, push the new access token into the same client without re-creating it:

client.setToken('eyJ...new-access-token');

Configure other options

If you pass neither apiKey nor token, every request will fail with 401 UNAUTHORIZED. If baseUrl is missing the constructor throws synchronously.

Access resources

EBonClient exposes ten typed resource accessors. Each one wraps a slice of /api/v1/* and returns plain TypeScript objects backed by the types in @e-bon/types.

Every accessor is constructed once when you instantiate EBonClient; they are stable references you can safely store on a long-lived object.

Handle errors

Every HTTP call routes through the same handler and surfaces errors as one of two concrete classes:

• EBonApiError — wraps any non-2xx HTTP response. Carries status, code (matches the HTTP error catalogue), message, details and, on 429, retryAfter (seconds).
• FiscalError — surfaced when a fiscal command fails on the printer. Carries code (ErrorCode enum), message, retryable, commandId and deviceId.

The retryable flag on FiscalError is precomputed from the RETRYABLE_ERRORS set in @e-bon/types, so you can branch directly:

import { FiscalError, isRetryable } from '@e-bon/sdk';

try {
  await client.commands.send({ deviceId, type: 'print_receipt', payload });
} catch (err) {
  if (err instanceof FiscalError && err.retryable) {
    // Safe to re-send with the same Idempotency-Key
  } else {
    throw err;
  }
}

The full catalogue of error codes, the retry pattern and the EBonApiError shape live on the Errors page.

Subscribe to real-time events

EBonClient carries a small events accessor that hands you an EventSubscriber connected to the events WebSocket using the same credentials as the HTTP client:

const events = client.events.subscribe();
events.on('receipt.created', (data) => console.log('receipt', data.receiptId));
events.on('command.failed', (data) => console.error('failed', data.fiscalError));
events.close();

The subscriber reconnects automatically with exponential backoff. The full event catalogue, payload types and reconnect semantics are documented on the Events page.

Where to next

• Getting started — install, get an API key, instantiate the client and issue your first receipt.
• Events — EventSubscriber, the typed EventMap and auto-reconnect.
• Errors — FiscalError, EBonApiError and the recommended retry pattern.
• API overview — the wire-level REST reference the SDK is built on.
• Receipts, Commands, Devices — per-resource HTTP references with request and response schemas.