tupay 0.5.2

package/README.md

@@ -0,0 +1,358 @@
+# tupay
+
+SDK Node officiel de **Tupay** — encaissement en XPF pour la Polynésie française.
+
+Zéro dépendance runtime. TypeScript natif. ESM et CommonJS.
+
+```bash
+npm install tupay
+```
+
+Node 18 ou plus (le SDK s'appuie sur le `fetch` global).
+
+> **Historique du nom.** Ce paquet s'est appelé `@tupay/node` avant sa
+> première publication. Le scope `@tupay` n'était pas disponible sur npm,
+> et un scope de repli se serait lu comme une coquille. Le nom publié
+> est donc `tupay`, sans scope.
+>
+> Les versions `0.5.0` et `0.5.1` ont été taguées mais jamais publiées :
+> la première a échoué à la construction, la seconde sur un jeton qui
+> exigeait un code d'authentification qu'aucune chaîne d'intégration ne
+> peut fournir. Ni l'une ni l'autre n'existe sur npm, et c'est
+> volontaire. Republier un numéro déjà tagué serait pire qu'un trou dans
+> la numérotation.
+
+---
+
+## Démarrer
+
+```ts
+import { Tupay } from 'tupay'
+
+const tupay = new Tupay(process.env.TUPAY_SECRET_KEY!)
+
+const link = await tupay.paymentLinks.create({
+  amountXpf: 4500,                       // entier XPF — pas de centimes
+  description: 'Location paddle 2 h',
+  returnUrl: 'https://ma-boutique.pf/merci',
+  metadata: { commande: 'A-1234' },
+})
+
+console.log(link.url) // → https://api.tupay.pf/pay/k3f9zq2xw1
+```
+
+En CommonJS :
+
+```js
+const { Tupay } = require('tupay')
+```
+
+---
+
+## Les montants sont en XPF entiers
+
+Le franc pacifique n'a pas de centimes. `amountXpf: 4500` vaut **4 500 XPF**, pas 45.
+
+Ne divisez jamais par 100. `amountEurCents` existe uniquement pour la réconciliation bancaire — il ne sert pas à l'affichage client.
+
+---
+
+## Mode test
+
+Le mode découle du **préfixe de la clé**, sans configuration :
+
+```ts
+new Tupay('tpk_test_…').livemode  // false — aucun argent ne bouge
+new Tupay('tpk_live_…').livemode  // true
+```
+
+Les deux mondes sont étanches : une clé de test ne voit ni ne rembourse une transaction réelle.
+
+Le bac à sable ne résout pas les paiements tout seul — **vous** décidez de l'issue, ce qui vous permet de tester vos chemins d'échec :
+
+```ts
+const intent = await tupay.paymentIntents.create({ amountXpf: 4500, merchantId })
+
+await tupay.testHelpers.simulatePayment(intent.transactionId, 'succeeded')
+// → votre endpoint de webhook reçoit un payment.succeeded signé
+```
+
+`simulatePayment` lève **localement** si le client a été construit avec une clé live — aucune requête ne part.
+
+Pour tester un échec dès la création :
+
+```ts
+import { TestHelpers } from 'tupay'
+
+TestHelpers.magicAmounts.cardDeclined      // 402 → card_declined
+TestHelpers.magicAmounts.insufficientFunds // 403 → insufficient_funds
+TestHelpers.magicAmounts.rateLimited       // 429 → rate_limited
+```
+
+---
+
+## Webhooks
+
+### Vérifier la signature
+
+```ts
+import express from 'express'
+import { Tupay, TupaySignatureVerificationError } from 'tupay'
+
+const tupay = new Tupay(process.env.TUPAY_SECRET_KEY!)
+const app = express()
+
+app.post(
+  '/tupay/webhook',
+  express.raw({ type: 'application/json' }),   // ⚠️ corps BRUT, obligatoire
+  (req, res) => {
+    let event
+    try {
+      event = tupay.webhooks.constructEvent(
+        req.body,
+        req.get('tupay-signature'),
+        process.env.TUPAY_WEBHOOK_SECRET!,
+      )
+    } catch (err) {
+      if (err instanceof TupaySignatureVerificationError) {
+        return res.status(400).send('signature invalide')
+      }
+      throw err
+    }
+
+    res.sendStatus(200)          // acquittez vite (< 10 s)
+    void traiter(event)          // puis traitez
+  },
+)
+```
+
+**Le piège n°1 :** passer un objet déjà parsé puis re-sérialisé. Le HMAC porte sur les octets exacts envoyés ; un espace d'écart le casse. Un test du SDK couvre précisément ce scénario.
+
+| Framework | Comment obtenir le corps brut |
+|---|---|
+| Express | `express.raw({ type: 'application/json' })` |
+| Next.js (App Router) | `await request.text()` |
+| Fastify | `config: { rawBody: true }` |
+| Hono | `await c.req.text()` |
+
+### Les quatre règles de réception
+
+1. **Répondez 2xx en moins de 10 s.** Au-delà, la livraison est comptée en échec.
+2. **Dédupliquez sur `event.id`.** Une livraison peut se répéter — c'est le prix d'une livraison garantie.
+3. **Ne vous fiez pas à l'ordre.** `event.data.object.updatedAt` tranche.
+4. **Filtrez sur `event.livemode`** si le même endpoint sert vos deux environnements.
+
+### Déboguer une intégration
+
+```ts
+const { data } = await tupay.webhookEndpoints.listDeliveries(endpointId, {
+  status: 'failed',
+})
+
+for (const d of data) {
+  console.log(d.eventType, d.responseStatus, d.lastError, '→ retry', d.nextRetryAt)
+}
+```
+
+Reprises automatiques : 1 min → 5 min → 30 min → 2 h → 6 h → 24 h, soit 7 tentatives sur ~34 h.
+
+### L'historique des événements
+
+Les événements existent indépendamment de leurs livraisons : même sans
+endpoint déclaré, votre activité laisse une trace complète.
+
+```ts
+// Ce qui s'est passé, du plus récent au plus ancien.
+const { data, has_more } = await tupay.events.list({ limit: 20 })
+
+// Un événement précis — le geste courant quand un webhook vous
+// intrigue : vous tenez son id, vous voulez revoir l'objet émis.
+const event = await tupay.events.retrieve('evt_9f8c1a2b3d4e5f60')
+```
+
+**Rejouer.** Votre serveur était en panne à 3 h du matin :
+
+```ts
+for await (const event of tupay.events.autoPagingEach({
+  type: 'payment.succeeded',
+})) {
+  const { deliveries } = await tupay.events.resend(event.id)
+  console.log(event.id, '→', deliveries, 'livraison(s)')
+}
+```
+
+Le rejeu **crée** une livraison, il ne modifie pas l'ancienne — celle-ci
+reste une pièce d'audit. Votre gestionnaire recevra donc l'événement une
+fois de plus **avec le même `id`** : c'est exactement pourquoi la règle 2
+ci-dessus existe.
+
+La pagination des événements se fait par **curseur**
+(`startingAfter: 'evt_…'`), comme les cinq autres collections. Un
+`offset` glisserait dès qu'un événement naît pendant le parcours, et
+vous en sauteriez sans le voir.
+
+`apres` reste accepté comme alias de `startingAfter` : le SDK le
+traduit avant d'émettre. Il est déprécié, supporté au minimum douze
+mois.
+
+---
+
+## Remboursements
+
+```ts
+// Total du reliquat
+await tupay.refunds.create({ transactionId })
+
+// Partiel
+await tupay.refunds.create({ transactionId, amountXpf: 1500, reason: 'Article retourné' })
+```
+
+Les remboursements partiels **s'accumulent**. Après 1 500 XPF remboursés sur 4 500 :
+
+```ts
+tx.status              // 'succeeded'  ← inchangé
+tx.refundedAmountXpf   // 1500         ← c'est ce champ qui fait foi
+```
+
+> Ne testez pas `status === 'refunded'` pour savoir si un remboursement a eu lieu. `status` ne bascule qu'au remboursement intégral.
+
+---
+
+## Idempotence et reprises
+
+Le SDK génère une clé d'idempotence (UUID v4) sur `paymentIntents.create` et `refunds.create`. Une reprise après timeout ne débitera jamais deux fois.
+
+Fournissez la vôtre pour qu'un retry applicatif ultérieur retombe sur le même résultat :
+
+```ts
+await tupay.paymentIntents.create({
+  amountXpf: 4500,
+  merchantId,
+  idempotencyKey: `commande-${orderId}`,
+})
+```
+
+**Politique de reprise :** le SDK retente sur 429, 5xx et pannes réseau, avec backoff exponentiel et gigue (`Retry-After` respecté). Il ne retente **que** les GET et les écritures porteuses d'une clé d'idempotence — `paymentLinks.create` n'est donc jamais rejoué, une reprise créerait un second lien.
+
+```ts
+new Tupay(key, { maxRetries: 0, timeout: 5000 })
+```
+
+---
+
+## Erreurs
+
+Toutes héritent de `TupayError`. Testez `err.code` (code machine stable), pas `err.message` (français, destiné à un humain, peut changer).
+
+```ts
+import { TupayValidationError, TupayRateLimitError, TupayError } from 'tupay'
+
+try {
+  await tupay.paymentIntents.create({ amountXpf: 50, merchantId })
+} catch (err) {
+  if (err instanceof TupayValidationError) console.error(err.code, err.message)
+  else if (err instanceof TupayRateLimitError) await attendre()
+  else if (err instanceof TupayError) console.error(err.code, err.requestId)
+  else throw err
+}
+```
+
+| Classe | HTTP | Quand |
+|---|---|---|
+| `TupayValidationError` | 400 / 422 | Corps invalide |
+| `TupayAuthenticationError` | 401 | Clé absente, invalide ou révoquée |
+| `TupayPermissionError` | 403 | Interdit ici — dont `livemode_mismatch` |
+| `TupayNotFoundError` | 404 | Inexistant ou hors de votre périmètre |
+| `TupayConflictError` | 409 | Déjà remboursé, limite atteinte |
+| `TupayRateLimitError` | 429 | 100 req/min dépassées |
+| `TupayBaasError` | 502 | Le prestataire bancaire a refusé |
+| `TupayApiError` | 5xx | Incident côté Tupay |
+| `TupayConnectionError` | — | Réseau, DNS, TLS ou timeout |
+| `TupaySignatureVerificationError` | — | Webhook non vérifiable |
+
+---
+
+## Pagination
+
+Les six collections se paginent **de la même façon** : `limit`,
+`startingAfter`, `endingBefore`.
+
+```ts
+const page = await tupay.transactions.list({ status: 'succeeded', limit: 50 })
+// { data: Transaction[], has_more: boolean, hasMore: boolean }
+
+// Page suivante : on repart du dernier élément lu.
+const dernier = page.data[page.data.length - 1]
+const suite = await tupay.transactions.list({
+  status: 'succeeded',
+  limit: 50,
+  startingAfter: dernier.id,
+})
+
+// Ou tout parcourir sans tenir de curseur soi-même :
+let total = 0
+for await (const tx of tupay.transactions.autoPagingEach({ status: 'succeeded' })) {
+  total += tx.amountXpf
+}
+```
+
+**`has_more` est la clé canonique.** `hasMore` porte la même valeur et
+reste rempli, y compris face à une API qui ne rend encore que l'une des
+deux : le SDK lit `has_more` avec repli sur `hasMore`. `hasMore` est
+déprécié et disparaîtra dans une version datée future ; lisez
+`has_more`.
+
+**`offset` est déprécié.** Il reste accepté au minimum douze mois, avec
+exactement le comportement qu'il a toujours eu, et n'est jamais envoyé
+par défaut. Un décalage nomme une position dans un classement qui
+bouge : dès qu'une ligne naît pendant votre parcours, tout ce qui suit
+glisse d'un cran. Le mêler à un curseur dans le même appel est refusé
+par un `400`.
+
+**Un curseur qui ne se résout pas rend `400 invalid_cursor`**, jamais
+une page vide. C'est la seule erreur de pagination dont la reprise
+n'est pas de retenter le même appel : il faut recommencer le parcours
+depuis le début.
+
+---
+
+## Référence
+
+| Ressource | Méthodes |
+|---|---|
+| `paymentIntents` | `create` |
+| `paymentLinks` | `create`, `retrieve`, `list`, `activate`, `deactivate` |
+| `transactions` | `retrieve`, `list`, `autoPagingEach` |
+| `refunds` | `create`, `list` |
+| `webhookEndpoints` | `create`, `retrieve`, `list`, `update`, `del`, `listDeliveries` |
+| `merchants` | `me` |
+| `events` | `list`, `retrieve`, `resend`, `autoPagingEach` |
+| `testHelpers` | `simulatePayment`, `magicAmounts` |
+| `webhooks` | `constructEvent` |
+
+### Options du client
+
+```ts
+new Tupay(apiKey, {
+  baseUrl: 'http://localhost:3000', // pour pointer un environnement local
+  timeout: 20_000,                  // ms, par tentative
+  maxRetries: 2,                    // reprises après la tentative initiale
+  headers: { 'x-trace-id': '…' },
+  fetch: monFetch,                  // injectable pour les tests
+})
+```
+
+---
+
+## Développement
+
+```bash
+npm install
+npm test          # 43 tests
+npm run typecheck
+npm run build     # dist/esm + dist/cjs
+```
+
+## Licence
+
+MIT

package/dist/cjs/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cœur HTTP du SDK : authentification, idempotence, reprises, erreurs.
+ *
+ * Aucune dépendance runtime — `fetch` global (Node 18+) et `node:crypto`.
+ */
+export interface TupayOptions {
+    /** Défaut : l’hôte de production Tupay. Surchargez pour pointer un environnement local. */
+    baseUrl?: string;
+    /** Timeout par tentative, en millisecondes. Défaut 20 000. */
+    timeout?: number;
+    /** Nombre de reprises après la tentative initiale. Défaut 2. */
+    maxRetries?: number;
+    /** En-têtes ajoutés à chaque requête (traçage, proxy d'entreprise…). */
+    headers?: Record<string, string>;
+    /**
+     * Version d'API à demander, au format `AAAA-MM-JJ`.
+     *
+     * Facultative : sans elle, la version figée à la création de la clé
+     * s'applique, et les formes de réponse restent stables dans le temps.
+     * La préciser sert à coder explicitement contre une version donnée —
+     * une valeur inconnue est refusée par un `400`, jamais silencieusement
+     * ignorée.
+     */
+    apiVersion?: string;
+    /** Injectable pour les tests. Défaut : `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Clé d'idempotence. Sa présence rend la requête rejouable en toute
+     * sécurité : c'est elle qui autorise le SDK à retenter un POST.
+     */
+    idempotencyKey?: string;
+}
+export declare class TupayClient {
+    #private;
+    /** `true` si la clé est une `tpk_live_`. Déduit du préfixe, sans appel réseau. */
+    readonly livemode: boolean;
+    constructor(apiKey: string, options?: TupayOptions);
+    /** Génère une clé d'idempotence. Exposé pour que l'appelant puisse la réutiliser. */
+    static idempotencyKey(): string;
+    request<T>(options: RequestOptions): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAsBD,qBAAa,WAAW;;IAQtB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;gBAEd,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;IAkCtD,qFAAqF;IACrF,MAAM,CAAC,cAAc,IAAI,MAAM;IAIzB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAmHtD"}

package/dist/cjs/client.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Cœur HTTP du SDK : authentification, idempotence, reprises, erreurs.
+ *
+ * Aucune dépendance runtime — `fetch` global (Node 18+) et `node:crypto`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TupayClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors.js");
+/**
+ * Hôte de production.
+ *
+ * ⚠️ `api.tupay.pf` ne résout pas — le domaine n'est pas enregistré. Un
+ * SDK publié avec cette valeur échouerait en erreur DNS au tout premier
+ * appel, ce qui est la pire première impression possible. On pointe donc
+ * l'hôte qui répond réellement aujourd'hui.
+ *
+ * Le jour où `api.tupay.pf` existe, changer cette constante est un
+ * changement de comportement pour quiconque s'est reposé sur le défaut :
+ * il devra donc sortir en version MAJEURE, avec les deux hôtes servis en
+ * parallèle le temps de la transition.
+ */
+const DEFAULT_BASE_URL = 'https://tupay.apps.lepetittahitien.dev';
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_RETRIES = 2;
+/** Statuts qui méritent une reprise : surcharge passagère ou incident serveur. */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+class TupayClient {
+    #apiKey;
+    #baseUrl;
+    #timeout;
+    #maxRetries;
+    #headers;
+    #fetch;
+    /** `true` si la clé est une `tpk_live_`. Déduit du préfixe, sans appel réseau. */
+    livemode;
+    constructor(apiKey, options = {}) {
+        if (!apiKey) {
+            throw new errors_js_1.TupayError('Clé API manquante. Passez-la au constructeur : new Tupay(process.env.TUPAY_SECRET_KEY).', { code: 'missing_api_key' });
+        }
+        if (!apiKey.startsWith('tpk_live_') && !apiKey.startsWith('tpk_test_')) {
+            throw new errors_js_1.TupayError('Clé API invalide : elle doit commencer par tpk_live_ ou tpk_test_.', { code: 'invalid_api_key' });
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new errors_js_1.TupayError('fetch global introuvable. Node 18+ est requis, ou passez une implémentation via l’option `fetch`.', { code: 'fetch_unavailable' });
+        }
+        this.#apiKey = apiKey;
+        this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.#headers = {
+            ...(options.apiVersion ? { 'tupay-version': options.apiVersion } : {}),
+            ...(options.headers ?? {}),
+        };
+        this.#fetch = fetchImpl;
+        this.livemode = apiKey.startsWith('tpk_live_');
+    }
+    /** Génère une clé d'idempotence. Exposé pour que l'appelant puisse la réutiliser. */
+    static idempotencyKey() {
+        return (0, node_crypto_1.randomUUID)();
+    }
+    async request(options) {
+        const url = this.#buildUrl(options.path, options.query);
+        const headers = {
+            authorization: `Bearer ${this.#apiKey}`,
+            accept: 'application/json',
+            'user-agent': 'tupay-node',
+            ...this.#headers,
+        };
+        if (options.body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        if (options.idempotencyKey) {
+            headers['idempotency-key'] = options.idempotencyKey;
+        }
+        // Une requête n'est rejouable que si elle est sûre à répéter :
+        // lecture pure, ou écriture protégée par une clé d'idempotence.
+        // Sans ça, une reprise sur timeout créerait un doublon.
+        const retryable = options.method === 'GET' || options.idempotencyKey !== undefined;
+        const attempts = retryable ? this.#maxRetries + 1 : 1;
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                const response = await this.#fetch(url, {
+                    method: options.method,
+                    headers,
+                    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                    signal: AbortSignal.timeout(this.#timeout),
+                });
+                const requestId = response.headers.get('x-request-id') ?? undefined;
+                if (response.ok) {
+                    if (response.status === 204)
+                        return undefined;
+                    const text = await response.text();
+                    if (!text)
+                        return undefined;
+                    return JSON.parse(text);
+                }
+                const body = await this.#safeJson(response);
+                const error = (0, errors_js_1.errorFromResponse)(response.status, body, requestId);
+                if (attempt < attempts && RETRYABLE_STATUSES.has(response.status)) {
+                    lastError = error;
+                    await this.#sleep(this.#backoffMs(attempt, response));
+                    continue;
+                }
+                throw error;
+            }
+            catch (err) {
+                // Erreur API déjà typée : la logique de reprise a été appliquée
+                // dans le `try` (on n'arrive ici qu'une fois les essais épuisés,
+                // ou sur un statut non rejouable).
+                if (err instanceof errors_js_1.TupayError)
+                    throw err;
+                // Panne réseau, DNS, TLS ou timeout — aucune réponse reçue.
+                const connectionError = new errors_js_1.TupayConnectionError(err instanceof Error && err.name === 'TimeoutError'
+                    ? `La requête a dépassé le délai de ${this.#timeout} ms.`
+                    : `Impossible de joindre l'API Tupay : ${err instanceof Error ? err.message : String(err)}`, err);
+                if (attempt >= attempts)
+                    throw connectionError;
+                lastError = connectionError;
+                await this.#sleep(this.#backoffMs(attempt));
+            }
+        }
+        throw lastError ?? new errors_js_1.TupayError('Requête échouée.', { code: 'server_error' });
+    }
+    #buildUrl(path, query) {
+        const url = new URL(`${this.#baseUrl}/api/v1${path}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+    /**
+     * Backoff exponentiel avec gigue, pour ne pas faire repartir tous les
+     * clients en même temps après un incident. Respecte `Retry-After`
+     * quand le serveur l'envoie.
+     */
+    #backoffMs(attempt, response) {
+        const retryAfter = response?.headers.get('retry-after');
+        if (retryAfter) {
+            const seconds = Number.parseInt(retryAfter, 10);
+            if (Number.isFinite(seconds) && seconds >= 0) {
+                return Math.min(seconds * 1000, 20_000);
+            }
+        }
+        const base = Math.min(500 * 2 ** (attempt - 1), 8_000);
+        return base + Math.random() * 250;
+    }
+    async #safeJson(response) {
+        try {
+            return (await response.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    #sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.TupayClient = TupayClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Hiérarchie d'erreurs du SDK.
+ *
+ * Toutes héritent de `TupayError` : un `catch (err)` unique suffit, et
+ * `err instanceof TupayRateLimitError` permet d'affiner si besoin.
+ *
+ * `code` est le code machine renvoyé par l'API (`validation_error`,
+ * `livemode_mismatch`, …). C'est lui qu'il faut tester — le `message`
+ * est en français, destiné à un humain, et peut changer sans préavis.
+ */
+export interface TupayErrorOptions {
+    code: string;
+    statusCode?: number;
+    requestId?: string;
+    cause?: unknown;
+}
+export declare class TupayError extends Error {
+    /** Code machine stable renvoyé par l'API. */
+    readonly code: string;
+    /** Statut HTTP, absent si l'erreur est survenue avant toute réponse. */
+    readonly statusCode?: number;
+    /** Identifiant de requête, à citer au support. */
+    readonly requestId?: string;
+    constructor(message: string, options: TupayErrorOptions);
+}
+/** 401 — clé absente, invalide ou révoquée. */
+export declare class TupayAuthenticationError extends TupayError {
+}
+/** 403 — opération interdite dans ce contexte (dont `livemode_mismatch`). */
+export declare class TupayPermissionError extends TupayError {
+}
+/** 404 — ressource inexistante ou hors du périmètre de la clé. */
+export declare class TupayNotFoundError extends TupayError {
+}
+/** 400 / 422 — corps de requête invalide. */
+export declare class TupayValidationError extends TupayError {
+}
+/** 409 — état incompatible (déjà remboursé, limite atteinte). */
+export declare class TupayConflictError extends TupayError {
+}
+/** 429 — 100 req/min par marchand dépassées. */
+export declare class TupayRateLimitError extends TupayError {
+}
+/** 5xx — incident côté Tupay. */
+export declare class TupayApiError extends TupayError {
+}
+/** 502 — le prestataire bancaire a refusé l'opération. */
+export declare class TupayBaasError extends TupayError {
+}
+/** Panne réseau, DNS, TLS ou dépassement du timeout. Aucune réponse reçue. */
+export declare class TupayConnectionError extends TupayError {
+    constructor(message: string, cause?: unknown);
+}
+/** La signature d'un webhook n'a pas pu être vérifiée. */
+export declare class TupaySignatureVerificationError extends TupayError {
+    constructor(message: string);
+}
+/**
+ * Construit l'erreur typée correspondant à une réponse HTTP.
+ * Le mapping suit le catalogue documenté dans `docs/api-integration.md`.
+ */
+export declare function errorFromResponse(status: number, body: {
+    error?: string;
+    message?: string;
+} | null, requestId?: string): TupayError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qBAAa,UAAW,SAAQ,KAAK;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;gBAEf,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;CAOxD;AAED,+CAA+C;AAC/C,qBAAa,wBAAyB,SAAQ,UAAU;CAAG;AAE3D,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,UAAU;CAAG;AAEvD,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD,6CAA6C;AAC7C,qBAAa,oBAAqB,SAAQ,UAAU;CAAG;AAEvD,iEAAiE;AACjE,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD,gDAAgD;AAChD,qBAAa,mBAAoB,SAAQ,UAAU;CAAG;AAEtD,iCAAiC;AACjC,qBAAa,aAAc,SAAQ,UAAU;CAAG;AAEhD,0DAA0D;AAC1D,qBAAa,cAAe,SAAQ,UAAU;CAAG;AAEjD,8EAA8E;AAC9E,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,0DAA0D;AAC1D,qBAAa,+BAAgC,SAAQ,UAAU;gBACjD,OAAO,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EACjD,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU,CAwBZ"}