TypeScript SDK

@hela/sdk is a light, dependency-free TypeScript client that runs in Node 18+, Deno, Bun and edge runtimes. It wraps authentication, pagination, retries and webhook verification.

Install

npm install @hela/sdk

A client

import { Hela } from "@hela/sdk";

const hela = new Hela({
  baseUrl: "https://api.example.com/v1",
  apiKey: process.env.HELA_KEY!,
  companyId: "4c1d…",
});

Read

const sales = await hela.sales.list({ from: "2026-09-01", to: "2026-09-30" });
const one = await hela.sales.get(sales[0].id);
const receivables = await hela.reports.receivables();

// Cursor collections iterate without caring about pages:
for await (const event of hela.events.iterate({ type: "invoice.paid" })) {
  console.log(event.id, event.data.number);
}

Write

const sale = await hela.sales.create(
  {
    businessUnitId: "…",
    partnerId: "…",
    lines: [{ itemId: "…", quantity: 2, unitPrice: 12.5 }],
  },
  { idempotencyKey: "web-order-1042" },
);

await hela.sales.recordPayment(sale.id, { walletId: "…", amount: 25 });

The SDK sends the Idempotency-Key header when you give one, and retries 429 and 5xx on its own with a growing delay (three times by default).

Money

import { toMajor, toMinor } from "@hela/sdk";

toMajor(12500, "USD"); // 125
toMajor(20000, "CDF"); // 20000 — no decimals
toMinor(125, "USD");   // 12500

Responses stay in minor units: convert for display, never for storage.

Verifying a webhook

import { verifyWebhook } from "@hela/sdk";

app.post("/hooks/hela", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhook(process.env.HELA_WEBHOOK_SECRET!, req.body.toString("utf8"), req.header("Hela-Signature") ?? "");
  if (!ok) return res.status(400).end();
  const event = JSON.parse(req.body.toString("utf8"));
  queue.push(event);
  res.status(200).end();
});

Errors

Any non-2xx response throws a HelaError carrying status, code (the stable code, e.g. field-required:walletId) and requestId.

try {
  await hela.sales.recordPayment(id, { walletId, amount: 999 });
} catch (error) {
  if (error instanceof HelaError && error.code === "amount-above-outstanding") {
    // …
  }
}

Types

Types are generated from the server's OpenAPI schema and published with the package. For a server newer than the SDK, regenerate them:

npx @hela/sdk generate https://api.example.com/v1/openapi.json > src/hela-types.ts

Source

The SDK lives in the Hela repository, under packages/sdk. MIT licence.