Official SDK

SDK JavaScript officiel

Le SDK publie le contrat public en code exploitable pour vos backends Node, workers et intégrations internes. Il suit le même schéma que l'API publique et évite la dérive manuelle de payloads.

Ouvrir le quickstart Télécharger OpenAPI

Ce qu'il couvre

→Client typé aligné sur le contrat OpenAPI 3.1 partagé.

→Support des headers Authorization, Idempotency-Key et X-Request-Id.

→sendSms(...) suit le contrat asynchrone 202 Accepted avec queued: true et status: accepted.

→listContacts(...) et createContact(...) pour la gestion des contacts.

→Helpers de validation de signature pour les webhooks CUTUMA.

→Compatible Node.js 18+ pour les backends, workers et jobs planifiés.

Installation

Téléchargement

# Copier le module ESM dans votre projet
curl -O https://cutuma.com/sdk/cutuma-client.mjs

# Placez cutuma-client.mjs dans lib/ ou vendor/

send-sms.mjs

import crypto from 'node:crypto';
import { CutumaClient } from './cutuma-client.mjs';

const client = new CutumaClient({
  baseUrl: process.env.CUTUMA_BASE_URL ?? 'https://cutuma.com/api/v1',
  apiKey: process.env.CUTUMA_API_KEY ?? '',
});

const result = await client.sendSms(
  {
    to: '+243810000000',
    message: 'Votre code est 482019',
    senderName: 'CUTUMA',
    clientReference: 'welcome-001',
  },
  {
    idempotencyKey: crypto.randomUUID(),
    requestId: 'sdk-page-send-001',
  }
);

console.log({
  queued: result.data.queued,
  status: result.data.status,
  providerMessageId: result.data.provider.messageId,
  remainingQuota: result.data.remainingQuota,
});

Quand l'utiliser

•Backends Node.js qui orchestrent envoi SMS et gestion des contacts.
•Workers ou crons qui doivent relancer une mutation idempotente.
•Serveurs webhook qui doivent vérifier la signature CUTUMA.

Contrat sendSms

Comportement asynchrone

Une réponse 202 Accepted signifie que le message est accepté et mis en file côté CUTUMA. Ne demandez pas un 200 OK strict ni un identifiant fournisseur immédiat : provider.messageId peut être assigné après dispatch worker ; la preuve de livraison arrive ensuite via DLR ou webhook.

Acceptez les réponses 2xx conformes au contrat.
Passez toujours un Idempotency-Key sur les envois critiques.
Corrélez via X-Request-Id et clientReference.

Méthodes disponibles

sendSms(payload, options) POST /v1/sms/send — envoi idempotent, réponse 202.

listContacts({ limit }) GET /v1/contacts — liste paginée des contacts.

createContact(payload, options) POST /v1/contacts — création d'un contact.

getAccount() GET /v1/account — quota et profil organisation.

getHealth() GET /v1/health — contrôle de santé public.

Helpers webhook

import {
  assertWebhookSignature,
  extractCutumaWebhookHeaders,
} from './cutuma-client.mjs';

function handleWebhook(rawBody, headers) {
  const webhookHeaders = extractCutumaWebhookHeaders(headers);

  if (!webhookHeaders.timestamp || !webhookHeaders.signature) {
    throw new Error('Missing CUTUMA webhook headers.');
  }

  assertWebhookSignature({
    signingSecret: process.env.CUTUMA_WEBHOOK_SECRET ?? '',
    timestamp: webhookHeaders.timestamp,
    signature: webhookHeaders.signature,
    payload: rawBody,
  });

  return JSON.parse(rawBody);
}

Prochaine étape

Exemples curl, codes d'erreur et référence complète.

Télécharger le SDK Exemples complets Codes d'erreur