SDK TypeScript

@hela/sdk est un client TypeScript léger, sans dépendance, qui fonctionne dans Node 18+, Deno, Bun et les runtimes edge. Il encapsule l'authentification, la pagination, les réessais et la vérification des webhooks.

Installation

npm install @hela/sdk

Un client

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

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

Lire

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();

// Les collections à curseur s'itèrent sans se soucier des pages :
for await (const event of hela.events.iterate({ type: "invoice.paid" })) {
  console.log(event.id, event.data.number);
}

Écrire

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 });

Le SDK envoie l'en-tête Idempotency-Key si vous le donnez, et réessaie de lui-même les 429 et 5xx avec un délai croissant (trois fois par défaut).

L'argent

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

toMajor(12500, "USD"); // 125
toMajor(20000, "CDF"); // 20000 — pas de décimales
toMinor(125, "USD");   // 12500

Les réponses restent en unité mineure : convertissez à l'affichage, jamais au stockage.

Vérifier un 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();
});

Erreurs

Toute réponse non-2xx lève une HelaError qui porte status, code (le code stable, par exemple field-required:walletId) et requestId.

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

Types

Les types sont générés depuis le schéma OpenAPI du serveur et publiés avec le paquet. Pour une version du serveur plus récente que le SDK, régénérez-les :

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

Code source

Le SDK vit dans le dépôt Hela, sous packages/sdk. Licence MIT.