@sanghosdk/js 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+Tous les changements notables sont documentés ici.
+
+Format basé sur [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/).
+Ce projet respecte le [Semantic Versioning](https://semver.org/lang/fr/).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- `sangho.account.retrieve()` — `GET /account`, introspection de l'app liée à la clé secrète.
+- `sangho.sandbox.reset()` — `POST /reset`, purge des données sandbox (clé test uniquement).
+- Les erreurs `SanghoError` (et sous-classes) exposent désormais `.type` (catégorie large, une des 9 valeurs `SanghoErrorType`, ex : `VALIDATION_ERROR`) EN PLUS de `.code` qui devient le code métier précis renvoyé par le backend (ex : `AMOUNT_TOO_SMALL`, `CURRENCY_NOT_IN_PLAN`) — voir `README.md#gestion-des-erreurs`.
+- Les erreurs `429` et `5xx` sont désormais réellement retryées avec backoff exponentiel (respectant `maxRetries`) ; un `429` respecte en priorité le délai `retry_after` renvoyé par le serveur. Les `4xx` restants (400/401/403/404/409/422) ne sont jamais retryés.
+
+### Changed
+
+- **Breaking** : `ListResponse<T>` expose désormais `data: T[]` au lieu de `results: T[]`, conformément à la pagination réelle de l'API. Tout code utilisant `.results` sur une liste doit passer à `.data`.
+- **Breaking** : `CurrencyCode` n'est plus restreint à `"XAF" | "XOF"` — le type couvre désormais l'ensemble des codes ISO 4217 actifs standards (`ISO_4217_CURRENCIES` dans `types/common.ts`). Cela reflète uniquement la validité ISO 4217 du code, pas ce qu'un marchand a le droit d'utiliser : chaque plan Sangho entitle un sous-ensemble de devises, et le backend rejette à l'exécution toute devise hors plan (`SanghoError` avec `.code === "CURRENCY_NOT_IN_PLAN"`, ou `"INVALID_CURRENCY"` si le code n'est pas un ISO 4217 reconnu).
+- **Breaking** : `SanghoError.code` ne vaut plus une des 10 catégories basses (`"authentication_error"`, `"api_error"`, ...) — c'est maintenant le code métier précis du backend (`raw.code`), typé `string` (catalogue ouvert, côté backend). La catégorie large vit désormais dans le nouveau champ `.type` (`SanghoErrorType`, 9 valeurs UPPERCASE). Le type `SanghoErrorCode` a été retiré ; utiliser `SanghoErrorType`.
+- **Breaking** : renommage du package `sangho` → `@sanghosdk`.
+- `checkoutSessions.retrieve()` n'exige plus une clé secrète — le backend autorise explicitement la clé publique sur cette action (page de confirmation navigateur).
+- `security.*` appelle désormais les bonnes routes (`/security/me/`, `/security/update_me/`) et existe réellement à l'exécution en tant que `sangho.security` (elle n'existait pas auparavant malgré son typage).
+
+### Deprecated
+
+### Removed
+
+- Suppression des fichiers de test `tests/unit/payouts.test.ts` et `tests/unit/sandbox.test.ts` : ils testaient un module « Payouts » qui n'existe ni dans le SDK ni comme endpoint public de l'API.
+
+### Fixed
+
+- `SanghoNotFoundError` ne construit plus un message dupliqué/incohérent sur les 404 — elle relaie désormais tel quel le message renvoyé par le backend.
+- `SanghoRateLimitError` lit correctement `retry_after` (au lieu de `retry_later`, qui n'existe pas côté backend).
+- La comparaison du code d'erreur `public_key_not_allowed` est désormais insensible à la casse (le backend envoie parfois `PUBLIC_KEY_NOT_ALLOWED`).
+- Revert d'une régression non publiée qui rendait `success_url` optionnel sur `checkoutSessions.create()` alors que le backend l'exige toujours.
+
+### Security
+
+- Retrait des clés API committées en clair et de `NODE_TLS_REJECT_UNAUTHORIZED=0` dans `tests/playground.ts`.
+- `SanghoOptions.baseURL` refuse désormais un protocole non-HTTPS (sauf `localhost`/`127.0.0.1`), pour éviter d'envoyer une clé API en clair par erreur de configuration.
+
+---
+
+## [1.0.0] - 2026-04-01
+
+### Added
+
+- Version initiale du SDK
+- Support de toutes les ressources : apps, customers, products, paymentIntents,
+  checkoutSessions, invoices, transactions, refunds, subscriptions,
+  paymentMethods, webhooks, paymentLinks, addresses, partners
+- Gestion complète des erreurs (auth, validation, rate limit, réseau)
+- Pagination via ListResponse

package/README.md

@@ -0,0 +1,366 @@
+# @sanghosdk/js — SDK JavaScript / TypeScript officiel
+
+SDK officiel de [Sangho](https://sangho.ga), la plateforme de paiement B2B pour l'Afrique francophone.
+
+[![npm](https://img.shields.io/npm/v/@sanghosdk/js)](https://www.npmjs.com/package/@sanghosdk/js)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)
+[![Docs](https://img.shields.io/badge/docs-docs.sangho.ga-navy)](https://docs.sangho.ga)
+
+---
+
+## Installation
+
+```bash
+npm install @sanghosdk/js
+# ou
+pnpm add @sanghosdk/js
+# ou
+yarn add @sanghosdk/js
+```
+
+> Ce SDK est un client **serveur** (Node.js ≥ 18). Il n'y a pas de build navigateur/CDN —
+> pour le paiement côté client, redirigez vers l'URL de checkout hébergée retournée par l'API
+> (`session.url` / `intent.url`), comme documenté ci-dessous.
+
+---
+
+## Clés API
+
+| Préfixe       | Environnement | Usage                          |
+|---------------|---------------|--------------------------------|
+| `sk_prod_`    | Production    | Serveur uniquement             |
+| `sk_test_`    | Sandbox       | Serveur uniquement (tests)     |
+| `pk_prod_`    | Production    | Navigateur (checkout public)   |
+| `pk_test_`    | Sandbox       | Navigateur (checkout tests)    |
+
+> ⚠️ **Ne jamais exposer `sk_prod_` ou `sk_test_` dans du code client (navigateur, app mobile).**
+
+---
+
+## Démarrage rapide
+
+```typescript
+import { Sangho } from "@sanghosdk/js"
+
+// Initialisation (côté serveur — clé secrète)
+const sangho = new Sangho("sk_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")
+
+// Créer un client
+const customer = await sangho.customers.create({
+  email: "jean.ondo@example.ga",
+  name: "Jean Ondo",
+  phone: "+24107000001",
+  currency: "XAF",
+})
+
+// Créer un PaymentIntent
+const intent = await sangho.paymentIntents.create({
+  amount: 50_000,    // 500.00 XAF (en centimes)
+  currency: "XAF",
+  customer: customer.id,
+  description: "Commande #1234",
+})
+
+// Confirmer le paiement
+const confirmed = await sangho.paymentIntents.confirm(intent.id, {
+  payment_method: "meth_xxx",
+})
+
+console.log(confirmed.status) // "succeeded" | "requires_action" | ...
+```
+
+---
+
+## Modules disponibles
+
+### Customers
+
+```typescript
+// Créer
+const customer = await sangho.customers.create({ email, name, phone, currency })
+
+// Récupérer
+const customer = await sangho.customers.retrieve("cust_xxx")
+
+// Mettre à jour
+const customer = await sangho.customers.update("cust_xxx", { phone: "+24107000002" })
+
+// Supprimer
+await sangho.customers.delete("cust_xxx")
+
+// Lister (avec filtres)
+const { data, count } = await sangho.customers.list({
+  page: 1,
+  page_size: 20,
+  status: "active",
+  currency: "XAF",
+})
+
+// Transactions d'un client
+const txns = await sangho.customers.listTransactions("cust_xxx")
+
+// Modes de paiement d'un client
+const methods = await sangho.customers.listPaymentMethods("cust_xxx")
+```
+
+### Products
+
+```typescript
+const product = await sangho.products.create({
+  name: "Abonnement Premium",
+  type: "subscription",
+  unit_amount: 15_000,
+  currency: "XAF",
+})
+
+await sangho.products.update(product.id, { name: "Abonnement Premium+" })
+
+await sangho.products.delete("prod_xxx") // archive côté backend (soft delete)
+```
+
+### Payment Intents
+
+```typescript
+// Créer et confirmer en une étape
+const intent = await sangho.paymentIntents.create({
+  amount: 10_000,
+  currency: "XAF",
+  customer: "cust_xxx",
+  confirm: true,
+  payment_method: "meth_xxx",
+})
+
+// Capture manuelle
+await sangho.paymentIntents.capture("pi_xxx", { amount_to_capture: 8_000 })
+
+// Annuler
+await sangho.paymentIntents.cancel("pi_xxx", {
+  cancellation_reason: "requested_by_customer",
+})
+```
+
+### Transactions
+
+```typescript
+// Lecture seule
+const txn = await sangho.transactions.retrieve("trans_xxx")
+
+const { data } = await sangho.transactions.list({
+  status: "succeeded",
+  currency: "XAF",
+  created_after: "2024-01-01T00:00:00Z",
+  min_amount: 1_000,
+})
+```
+
+### Refunds
+
+```typescript
+// Remboursement partiel
+const refund = await sangho.refunds.create({
+  transaction: "trans_xxx",
+  amount: 5_000,
+  reason: "requested_by_customer",
+})
+
+await sangho.refunds.cancel("refd_xxx")
+```
+
+### Invoices
+
+```typescript
+const invoice = await sangho.invoices.create({
+  customer: "cust_xxx",
+  currency: "XAF",
+  line_items: [
+    { description: "Consultation", quantity: 2, unit_amount: 25_000 },
+    { description: "Frais de déplacement", quantity: 1, unit_amount: 10_000 },
+  ],
+  tax_rate: 18, // 18% TVA
+  due_date: "2024-12-31",
+})
+
+await sangho.invoices.send(invoice.id)
+
+// Télécharger le PDF
+const { url } = await sangho.invoices.getPdfUrl(invoice.id)
+```
+
+### Payment Links
+
+```typescript
+const link = await sangho.paymentLinks.create({
+  currency: "XAF",
+  line_items: [{ product: "prod_xxx", quantity: 1 }],
+  success_url: "https://monsite.com/merci",
+  usage_limit: 100,
+})
+
+console.log(link.url) // https://checkout.sangho.ga/pay/link_xxx
+```
+
+### Checkout Sessions
+
+```typescript
+const session = await sangho.checkoutSessions.create({
+  mode: "payment",
+  currency: "XAF",
+  line_items: [{ product: "prod_xxx", quantity: 1 }],
+  success_url: "https://monsite.com/success",
+  cancel_url: "https://monsite.com/cancel",
+  expires_in: 3600, // 1 heure
+})
+
+// Rediriger le client vers session.url
+```
+
+### Subscriptions
+
+```typescript
+const sub = await sangho.subscriptions.create({
+  customer: "cust_xxx",
+  currency: "XAF",
+  unit_amount: 15_000,
+  interval: "month",
+  trial_period_days: 14,
+})
+
+await sangho.subscriptions.pause("sub_xxx")
+await sangho.subscriptions.resume("sub_xxx")
+await sangho.subscriptions.cancel("sub_xxx", { cancel_at_period_end: true })
+```
+
+### Webhooks
+
+```typescript
+const webhook = await sangho.webhooks.create({
+  url: "https://monserveur.com/webhooks/sangho",
+  events: [
+    "payment_intent.succeeded",
+    "payment_intent.payment_failed",
+    "customer.created",
+    "invoice.paid",
+  ],
+})
+
+// Régénérer le secret
+const { secret } = await sangho.webhooks.rollSecret(webhook.id)
+
+// Voir les livraisons
+const deliveries = await sangho.webhooks.listDeliveries(webhook.id, {
+  status: "failed",
+})
+
+// Rejouer une livraison
+await sangho.webhooks.retryDelivery(webhook.id, "wdl_xxx")
+```
+
+### Vérification des signatures webhook
+
+```typescript
+import { Sangho } from "@sanghosdk/js"
+
+// Express
+app.post(
+  "/webhooks/sangho",
+  express.raw({ type: "application/json" }),
+  async (req, res) => {
+    try {
+      const event = await Sangho.constructEvent(
+        req.body,
+        req.headers["sangho-signature"] as string,
+        process.env.SANGHO_WEBHOOK_SECRET!
+      )
+
+      switch (event.type) {
+        case "payment_intent.succeeded":
+          await handleSuccessfulPayment(event.data)
+          break
+        case "invoice.paid":
+          await markInvoicePaid(event.data)
+          break
+      }
+
+      res.json({ received: true })
+    } catch (err) {
+      res.status(400).send(`Webhook error: ${err.message}`)
+    }
+  }
+)
+```
+
+---
+
+## Gestion des erreurs
+
+```typescript
+import {
+  Sangho,
+  SanghoAuthError,
+  SanghoValidationError,
+  SanghoNotFoundError,
+  SanghoRateLimitError,
+} from "@sanghosdk/js"
+
+try {
+  const customer = await sangho.customers.create({ email: "invalid" })
+} catch (err) {
+  if (err instanceof SanghoValidationError) {
+    console.error("Erreurs de validation:", err.fieldErrors)
+    // { email: ["Enter a valid email address."] }
+  } else if (err instanceof SanghoAuthError) {
+    console.error("Clé API invalide ou expirée")
+  } else if (err instanceof SanghoNotFoundError) {
+    console.error("Ressource introuvable")
+  } else if (err instanceof SanghoRateLimitError) {
+    console.error(`Limite de taux dépassée. Réessayez dans ${err.retryAfter}s`)
+  } else if (err instanceof SanghoError) {
+    console.error(err.type);       // Catégorie — ex. 'VALIDATION_ERROR'
+    console.error(err.code);       // Code métier précis — ex. 'AMOUNT_TOO_SMALL'
+    console.error(err.statusCode); // Code HTTP
+  } else {
+    throw err
+  }
+}
+```
+
+---
+
+## Options avancées
+
+```typescript
+const sangho = new Sangho("sk_test_xxx", {
+  timeout: 10_000,      // Timeout en ms (défaut : 30 000)
+  maxRetries: 5,        // Nombre de retries auto (défaut : 3)
+  baseURL: "https://api.staging.sangho.ga/v1",  // URL custom (staging)
+})
+```
+
+---
+
+## Sécurité
+
+- La clé API est transmise uniquement via le header `Authorization: Bearer`
+- Chaque requête POST génère automatiquement une `Idempotency-Key` unique (UUID v4)
+- Les retries auto n'ont lieu que pour les erreurs `429` et `5xx` (jamais `4xx`), en respectant `Retry-After` pour les `429`
+- La vérification de signature webhook utilise HMAC-SHA256 avec protection anti-replay (5 min)
+- Les clés publiques (`pk_`) sont rejetées côté SDK si utilisées pour des opérations réservées aux clés secrètes (`sk_`)
+
+---
+
+## Compatibilité
+
+Ce SDK est un client **serveur** — il n'y a pas de build navigateur/UMD ni de CDN.
+
+| Environnement | Support |
+|---|---|
+| Node.js ≥ 18 | ✅ natif (ESM + CJS) |
+| Deno | ✅ via `npm:` |
+| Bun | ✅ |
+| TypeScript ≥ 5.0 | ✅ types complets |
+
+---
+
+## Licence
+
+MIT © [Sangho](https://sangho.ga)