Node SDK

@xaalis/node (in apps/sdk-node) wraps the API for Node 20+ servers. Zero runtime dependencies; types are generated from openapi.json. Not on npm yet — use it from the monorepo.

import { Xaalis, XaalisAPIError, constructEvent, formatXof } from "@xaalis/node";

const xaalis = new Xaalis(process.env.XAALIS_SECRET_KEY!, { baseUrl: "http://localhost:4000" });

const payment = await xaalis.payments.create(
  { amount: 15000, description: "Commande #1042", client_reference: "order_1042", success_url: "https://shop.example/merci" },
  { idempotencyKey: "payment:order_1042" },
);
console.log(formatXof(payment.amount), payment.checkout_url);

API	Methods
payments	create, retrieve, list, listAll (async iterator over every page)
payouts	create, retrieve, list, listAll
balance	retrieve
account	retrieve, update({ webhook_url })
webhookDeliveries	list
testHelpers	simulatePayment(id, "succeeded" | "failed") — test keys only
constructEvent(raw, header, secret)	verify and parse a webhook

What it does for you

• Idempotency: every create sends an Idempotency-Key (random unless you pass one) and reuses it on each retry.
• Retries: network errors, 429 and 5xx, with exponential backoff and Retry-After — only when replaying is safe (reads, PATCH, or creates carrying their key). Default 2 retries, 30 s timeout per attempt.
• Errors: XaalisAPIError (status, code, message), XaalisConnectionError, XaalisSignatureError.
• Safety: throws if imported in a browser; refuses a live key over http://.

try {
  await xaalis.payouts.create({ amount: 5000, provider: "wave", recipient: { phone: "+221770000001" } });
} catch (err) {
  if (err instanceof XaalisAPIError && err.code === "insufficient_funds") {
    /* show "balance too low" */
  } else throw err;
}

Examples: apps/sdk-node/examples/ (checkout, webhook server, payout). After the API contract changes: yarn workspace @xaalis/node gen.