@tollvera/operator-sdk

The official SDK for Tollvera operators (parking garages, toll roads, EV chargers, fuel stations). Charge drivers automatically via license plate.

Install

npm install @tollvera/operator-sdk
# or
pnpm add @tollvera/operator-sdk

Quick start

import { Tollvera } from '@tollvera/operator-sdk';

const tollvera = new Tollvera({
  apiKey: process.env.TOLLVERA_API_KEY!, // keep server-side!
});

// Called by your ALPR camera / toll gantry when a plate is detected
async function onPlateDetected(plate: string) {
  try {
    const result = await tollvera.charge({
      plate,
      country: 'US',
      amountCents: 500,
      currency: 'USD',
      kind: 'parking',
      locationName: 'Downtown Garage - Level 2',
      operatorReference: `session-${Date.now()}`, // YOUR unique id
    });

    if (result.status === 'captured') {
      console.log(`Charged $5 — ${result.transactionId}`);
      openGate();
    }
  } catch (err) {
    if (err instanceof TollveraError && err.isDriverError) {
      // 402 → no payment method on file, or exceeded cap
      // 404 → plate not registered with Tollvera
      // → fall back to kiosk payment
      showKioskUI();
    } else {
      // 5xx → Tollvera is down. SDK already retried 3x.
      // → open the gate (safer than blocking a line of cars)
      logAndOpenGate();
    }
  }
}

API

new Tollvera(config)

interface TollveraConfig {
  apiKey: string;              // required
  baseUrl?: string;            // default: https://api.tollvera.com
  timeout?: number;            // default: 10000 ms
  maxRetries?: number;         // default: 2 (3 total attempts)
}

tollvera.charge(request)

interface ChargeRequest {
  plate: string;               // "ABC-1234" (will be normalized server-side)
  country: 'US' | 'RO' | 'DE' | 'FR' | 'GB' | 'IT' | 'ES' | 'NL' | ...;
  amountCents: number;         // 500 = $5.00
  currency: 'USD' | 'EUR' | 'RON' | 'GBP';
  kind: 'parking' | 'toll' | 'ev_charging' | 'fuel';
  locationName: string;        // Shown to driver in receipt
  locationLat?: number;
  locationLon?: number;
  operatorReference: string;   // YOUR unique ID — enables idempotency
  occurredAt?: string;         // ISO 8601, default: now
}

interface ChargeResult {
  transactionId: string;
  status: 'captured' | 'failed' | 'pending';
  authorizedAt: string | null;
  idempotentReplay?: boolean;  // true if same reference seen before
}

tollvera.health()

Health check — pings the backend. Returns { status, service, version }. Use for monitoring.

Idempotency

Every charge() call requires an operatorReference that's unique within YOUR operator account. If the same reference is sent twice:

• The driver is not charged twice
• Both calls return the same transactionId
• The second call has idempotentReplay: true

This means it's safe to retry on timeouts, network errors, or app crashes.

Example — use the parking session ID:

operatorReference: `parkomobility-session-${sessionId}`

Error handling

The SDK throws TollveraError with helpful flags:

import { TollveraError } from '@tollvera/operator-sdk';

try {
  await tollvera.charge(req);
} catch (err) {
  if (err instanceof TollveraError) {
    console.log(err.code);           // 'no_vehicle', 'cap_exceeded', 'card_declined', ...
    console.log(err.message);        // human-readable
    console.log(err.status);         // HTTP status
    console.log(err.requestId);      // for support tickets

    if (err.isDriverError)   { /* 402/404 — plate not registered or no card */ }
    if (err.isServerError)   { /* 5xx — Tollvera outage, we retried */ }
    if (err.isClientError)   { /* 4xx — your request was wrong */ }
  }
}

Transport

• Uses native fetch (Node 18+, Deno, Bun, Cloudflare Workers, browsers)
• Zero runtime dependencies
• Retries 5xx with exponential backoff (100ms → 400ms → 900ms)
• Respects AbortController for timeouts
• Automatic User-Agent: tollvera-operator-sdk/0.1.0

Platform compatibility

| Runtime | Supported | |---|---| | Node.js 18+ | ✅ | | Deno 1.28+ | ✅ | | Bun | ✅ | | Cloudflare Workers | ✅ | | Browsers | ⚠️ Don't — the API key must stay server-side | | React Native | ⚠️ Same reason |

Development

pnpm install
pnpm build       # creates dist/ with CJS + ESM + .d.ts
pnpm test        # runs vitest
pnpm typecheck

License

MIT © Tollvera