Node.js SDK

The @sanghosdk/js SDK is the official Sangho client for Node.js 18+. It supports both ESM and CommonJS and is optimized for server environments, Edge Functions, and serverless.

Installation

bash

# With NPM
npm install @sanghosdk/js
# With PNPM
pnpm add @sanghosdk/js
# With YARN
yarn add @sanghosdk/js

Available modules

accountappsaddressespaymentIntentscheckoutSessionstransactionsrefundspaymentLinkscustomerspaymentMethodsproductsinvoicesreceiptssubscriptionswebhookssecuritypartnersterminalsandbox

Node.js & Edge

The SDK is fully typed. Interfaces are exported directly — import PaymentIntent, Customer, ListResponse, etc. from @sanghosdk/js with no additional configuration.

Is the installation clear?

Initialization

javascript

import Sangho from '@sanghosdk/js';
// Direct key (not recommended in production)
const sangho = new Sangho('sk_prod_xxxxxxxxxxxx');
// From environment variable (recommended)
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY!);
// Advanced options
const sangho = new Sangho('sk_prod_xxxx', {
  baseURL: 'https://api.sangho.ga/v1/',
  timeout: 30_000,
  maxRetries: 3,
});

Error handling

All errors thrown by the SDK inherit from SanghoError, which exposes type (category, e.g. VALIDATION_ERROR) and code (precise business code, e.g. AMOUNT_TOO_SMALL — see the full list). Use instanceof to differentiate business cases.

Pagination

List endpoints return a ListResponse<T> object with fields count, next, previous, and data. Use the page and page_size parameters to navigate.

Automatic retry

The SDK automatically retries 429 (rate limit, honoring the server’s Retry-After) and 5xx errors, as well as genuine network failures, with exponential backoff. Remaining 4xx errors (400, 401, 403, 404, 409, 422) are never retried — they are request problems to fix, not transient incidents. Configure maxRetries at initialization (default: 3).

Are the examples sufficient?

Error handling

javascript

import Sangho, { SanghoError } from '@sanghosdk/js';
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY!);
try {
  const intent = await sangho.paymentIntents.create({
    amount: 5000,
    currency: 'XAF',
    payment_method_types: ['mobile_money'],
  });
  console.log(intent.id);
} catch (err) {
  if (err instanceof SanghoError) {
    console.error(err.type);       // Category — 'VALIDATION_ERROR'
    console.error(err.code);       // Precise business code — 'AMOUNT_TOO_SMALL'
    console.error(err.message);    // Human-readable message
    console.error(err.statusCode); // HTTP status code (400, 401, 422…)
  }
}

Pagination

javascript

// Page 1
const page1 = await sangho.transactions.list({
  status: 'completed',
  page: 1,
  page_size: 20,
});
console.log(page1.count); // Total results
console.log(page1.data);  // Current page array
// Next page
if (page1.next) {
  const page2 = await sangho.transactions.list({
    status: 'completed',
    page: 2,
    page_size: 20,
  });
}