Developers
API referenceBusiness sign in

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

Shell
npm install @qoene/delivery

Node.js 20 or newer, no dependencies. Works in Next.js (Node and Edge runtimes), Bun and Deno. ESM and CommonJS.

Set up

TypeScript
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',
});
Client options
OptionDefaultMeaning
apiKeyrequiredYour secret key. The constructor refuses to run in a browser.
baseUrlhttps://api.qoenedelivery.com/v1Another environment or a local server
timeoutMs30000Per attempt
maxRetries2Automatic retries on network errors, 408, 429 and 5xx, only when repeating is safe
maxRetryDelayMs20000Longer Retry-After waits throw QoeneRateLimitError instead
fetchglobal fetchInject for tests or proxies
appInfononeAdded 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

TypeScript
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

TypeScript
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

app/api/qoene/webhook/route.ts (Next.js)
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

TypeScript
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.