Reference

SDK reference: Node.js

Harbour Connect for Node.js and TypeScript: the client, the services, webhooks and errors.

Harbour Connect for Node.js has no dependencies: it uses the built-in fetch and node:crypto. It ships as an ES module with TypeScript declarations, and require() works on Node.js 20.19 and newer. The contract is the PHP SDK's: integer kobo, an idempotency key on every create, at most two safe retries, typed errors, and the same webhook check, tested against the same shared vectors.

Install

Terminal
npm install @nordaxiz/harbour-connect
Terminal
# until the package is on the npm registry
git clone https://github.com/Nordaxiz-Technology-Limited/nordaxiz-harbour-connect.git
npm install ./nordaxiz-harbour-connect/node

Node.js 20.19 or newer. The source is in the node/ folder of the Harbour Connect repository, MIT licensed.

The client

JavaScript
import { Harbour } from '@nordaxiz/harbour-connect';     // or: const { Harbour } = require(...)

const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY, {
  webhookSecret: process.env.HARBOUR_WEBHOOK_SECRET,   // for harbour.webhooks
  apiBase: 'https://api.harbour.africa',               // HTTPS, except localhost
  timeoutMs: 30_000,                                   // 1000 to 300000
  maxRetries: 2,                                       // 0 to 2
  webhookTolerance: 300,                               // seconds either side
});

harbour.mode;        // "live" | "test", from the key
harbour.isTestMode;
harbour.maskedKey;   // hb_sk_live_****abcd, for logs and support tickets

Create one client and share it. An unknown option throws InvalidArgumentError, so a typo never passes silently. The key lives in a private field: console.log, util.inspect and JSON.stringify only ever show the masked form. A public key (hb_pk_) is refused, with a pointer to harbour.js.

Services

JavaScript
// charges
await harbour.charges.create({ amountKobo, customer, reference, description, returnUrl, provider, metadata, idempotencyKey });
await harbour.charges.verify('HB-88413');
await harbour.charges.findByMerchantReference('order-1043');     // or null

// refunds: each one waits for an Owner's approval
await harbour.refunds.create({ reference: 'HB-88413', amountKobo: 2_500_000, reason: 'Two metres short' });
await harbour.refunds.retrieve('rf_…');

// payment links
await harbour.paymentLinks.create({ amountKobo: 1_500_000, description: 'Aso-ebi, 12 yards', expiresInDays: 7 });
await harbour.paymentLinks.retrieve('pl_…');

// the ledger
const page = await harbour.transactions.list({ status: 'succeeded', from: '2026-09-01', limit: 50 });
page.data; page.nextCursor; page.hasMore; await page.nextPage();
for await (const txn of harbour.transactions.all({ provider: 'paystack' })) { /* every page, lazily */ }
await harbour.transactions.retrieve('HB-88413');

Options are camelCase; the objects that come back are the API's own, in snake_case (checkout.checkout_url, txn.amount_kobo), exactly as in the API reference. Amounts must be whole numbers of kobo: 1200.5 or "1200" is refused before anything is sent. Money.toKobo("120,000.50") converts a naira string.

Webhooks

Verify against the raw body. Parsing the JSON first changes the bytes and the signature fails. constructEvent takes the body as a Buffer or string and either the header value or the whole headers object (Express, Fetch Headers):

JavaScript Express
import express from 'express';
import { Event, SignatureVerificationError } from '@nordaxiz/harbour-connect';

// before app.use(express.json()): this route needs the raw bytes
app.post('/webhooks/harbour', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = harbour.webhooks.constructEvent(req.body, req.headers);
  } catch (e) {
    if (e instanceof SignatureVerificationError) return res.sendStatus(400);
    throw e;
  }
  if (event.type === Event.CHARGE_SUCCEEDED) fulfil(event.transaction());   // de-duplicate on event.id
  res.sendStatus(200);
});
JavaScript Next.js route handler
// app/api/webhooks/harbour/route.js
export const runtime = 'nodejs';

export async function POST(request) {
  const raw = await request.text();                      // never request.json() before verifying
  const event = harbour.webhooks.constructEvent(raw, request.headers);
  // …
  return new Response(null, { status: 200 });
}

A NestJS controller is in the repository's node/examples. A failed check throws SignatureVerificationError with kind set to malformed, mismatch or tolerance; answer 400. See Webhooks for retries and de-duplication.

Errors and retries

JavaScript
import { HarbourError, ValidationError, RateLimitError, ApiConnectionError } from '@nordaxiz/harbour-connect';

try {
  await harbour.charges.create({ amountKobo: 12_000_000, customer: 'funke@example.ng' });
} catch (e) {
  if (e instanceof ValidationError) console.log(e.fields);          // { amount_kobo: "…" }
  else if (e instanceof RateLimitError) console.log(e.retryAfter);   // seconds
  else if (e instanceof ApiConnectionError) { /* no answer: safe to retry with the same idempotencyKey */ }
  else if (e instanceof HarbourError) console.log(e.status, e.code, e.message);
}

Every error extends HarbourError with status and code: AuthenticationError (401), PermissionError (403), NotFoundError (404), IdempotencyConflictError (409), ValidationError (422), RateLimitError (429), ApiConnectionError (no answer) and InvalidArgumentError (caught before sending). Network errors, 429 and 5xx are retried at most twice with jittered backoff, only for GETs and creates that carry an idempotency key, which every create does. See Idempotency.

Versioning

  • The package is @nordaxiz/harbour-connect, version 0.1.0. Below 1.0.0 a minor version may break things: pin with ~0.1 and read the changelog before moving.
  • The version travels as User-Agent: harbour-connect-node/<version>.
  • Every call goes to the API's /v1, whichever SDK version you run.