SDK Node.js

Le SDK @sanghosdk/js est le client officiel Sangho pour Node.js 18+. Il supporte les modes ESM et CommonJS. C’est un client serveur — il n’expose pas de widget de paiement pour le navigateur ; côté client, redirigez simplement vers l’URL de checkout renvoyée par l’API (voir Redirection Checkout).

Installation

bash

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

Modules disponibles

accountappsaddressespaymentIntentscheckoutSessionstransactionsrefundspaymentLinkscustomerspaymentMethodsproductsinvoicesreceiptssubscriptionswebhookssecuritypartnersterminalsandbox

Node.js & Edge

Le SDK est entièrement typé. Les interfaces sont exportées directement — importez PaymentIntent, Customer, ListResponse, etc. depuis @sanghosdk/js sans configuration supplémentaire.

L'installation est-elle claire ?

Initialisation

javascript

import Sangho from '@sanghosdk/js';
// Clé directe (déconseillé en production)
const sangho = new Sangho('sk_prod_xxxxxxxxxxxx');
// Depuis variable d'environnement (recommandé)
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY!);
// Options avancées
const sangho = new Sangho('sk_prod_xxxx', {
  baseURL: 'https://api.sangho.ga/v1/',
  timeout: 30_000,
  maxRetries: 3,
});

Gestion des erreurs

Toutes les erreurs levées par le SDK héritent de SanghoError, qui expose type (catégorie, ex. VALIDATION_ERROR) et code (code métier précis, ex. AMOUNT_TOO_SMALL — voir la liste complète). Utilisez instanceof pour différencier les cas métier.

Pagination

Les endpoints de liste retournent un objet ListResponse<T> avec les champs count, next, previous et data. Utilisez les paramètres page et page_size pour naviguer.

Retry automatique

Le SDK retente automatiquement les erreurs 429 (rate limit, en respectant le délai Retry-After) et 5xx, ainsi que les pannes réseau, avec un backoff exponentiel. Les erreurs 4xx restantes (400, 401, 403, 404, 409, 422) ne sont jamais retentées — ce sont des problèmes de requête à corriger, pas des incidents temporaires. Configurez maxRetries à l’initialisation (défaut : 3).

Les exemples sont-ils suffisants ?

Gestion des erreurs

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);       // Catégorie — 'VALIDATION_ERROR'
    console.error(err.code);       // Code métier précis — 'AMOUNT_TOO_SMALL'
    console.error(err.message);    // Message lisible
    console.error(err.statusCode); // Code HTTP (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 de résultats
console.log(page1.data);  // Tableau de la page courante
// Page suivante
if (page1.next) {
  const page2 = await sangho.transactions.list({
    status: 'completed',
    page: 2,
    page_size: 20,
  });
}