Start
Node.js SDK
@qoene/delivery is the official Node.js/TypeScript client. Types are generated from the OpenAPI document, so every request and response is typed.
Install
npm install @qoene/deliveryNode.js 20 or newer, no dependencies. Works in Next.js (Node and Edge runtimes), Bun and Deno. ESM and CommonJS.
Set up
import { QoeneDelivery } from '@qoene/delivery';
export const qoene = new QoeneDelivery({
apiKey: process.env.QOENE_API_KEY!, // qd_test_… or qd_live_…
// baseUrl: 'https://api-staging.qoenedelivery.com/v1',
appInfo: 'my-shop/1.0',
});| Option | Default | Meaning |
|---|---|---|
apiKey | required | Your secret key. The constructor refuses to run in a browser. |
baseUrl | https://api.qoenedelivery.com/v1 | Another environment or a local server |
timeoutMs | 30000 | Per attempt |
maxRetries | 2 | Automatic retries on network errors, 408, 429 and 5xx, only when repeating is safe |
maxRetryDelayMs | 20000 | Longer Retry-After waits throw QoeneRateLimitError instead |
fetch | global fetch | Inject for tests or proxies |
appInfo | none | Added to the User-Agent |
Methods
Every operation has a method; the API reference shows it in the Node.js tab of each endpoint. Each returns the response's data, fully typed, and takes a final { idempotencyKey, signal, timeoutMs, maxRetries } argument. qoene.call(operationId, { path, query, body }) calls any operation by its OpenAPI ID.
Idempotency
import { idempotencyKey } from '@qoene/delivery';
await qoene.shipments.create(booking, { idempotencyKey: idempotencyKey('order', order.id, 'book') });Without a key the SDK makes a random one and reuses it for its own retries. Pass a key derived from your order so a retry after a crash finds the original booking. See Idempotency.
Pagination
for await (const shipment of qoene.shipments.listAll({ milestone: 'READY_FOR_PICKUP' })) {
await remindBuyer(shipment);
}
// Or one page at a time:
const page = await qoene.orders.list({ status: 'FAILED', limit: 50 });
const next = page.nextCursor ? await qoene.orders.list({ status: 'FAILED', limit: 50, cursor: page.nextCursor }) : null;Errors
Failures throw a subclass of QoeneError by status (see Errors) with status, code, details, reason, operationId and requestId.
Webhooks
import { verifyWebhook, isOrderEvent, QoeneWebhookSignatureError } from '@qoene/delivery';
export async function POST(request: Request) {
const payload = await request.text(); // raw body
try {
const event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.QOENE_WEBHOOK_SECRET! });
if (await markEventProcessed(event.id)) { // false if already seen
if (isOrderEvent(event)) await updateOrder(event.data.order);
else await refreshShipment(event);
}
return new Response('ok');
} catch (error) {
if (error instanceof QoeneWebhookSignatureError) return new Response('invalid signature', { status: 400 });
throw error;
}
}Money helpers
import { parseMinor, formatGhs } from '@qoene/delivery';
parseMinor(quote.total_minor); // 2500 (number, even if the API sent "2500")
formatGhs(quote.total_minor); // "GH₵ 25.00"Versions
The SDK follows semantic versioning and is regenerated whenever the API document changes. See the changelog.