@paywallex/node 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Paywallex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @paywallex/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK serveur officiel de l'API Paywallex `/v1`. Il sert à encaisser par Orange Money, MTN MoMo, Moov Money, Wave ou le solde Paywallex, à rembourser, à suivre les litiges et les abonnements, et à vérifier les webhooks signés.
+
+Node 18 ou plus récent, Bun ou Deno. Aucune dépendance.
+
+> Côté serveur uniquement. Ne mettez jamais une clé secrète `pwx_sk_…` dans un navigateur ou une application mobile.
+
+## Installation
+
+Installez le paquet :
+
+```sh
+npm install @paywallex/node
+```
+
+## Créer une session de paiement
+
+Le SDK ne lit pas `PAYWALLEX_KEY` tout seul. Passez votre clé explicitement à la création du client. Une clé `pwx_sk_test_…` vise le bac à sable, une clé `pwx_sk_live_…` vise la production.
+
+Créez une session, puis redirigez le client vers `session.url` :
+
+```ts
+import { Paywallex } from "@paywallex/node";
+
+const paywallex = new Paywallex({ apiKey: process.env.PAYWALLEX_KEY! });
+
+const session = await paywallex.checkoutSessions.create({
+  currency: "XOF",
+  line_items: [
+    { name: "Attiéké poisson", unit_amount: 2500, quantity: 2 },
+    { name: "Jus de bissap", unit_amount: 500 },
+  ],
+  success_url: "https://maboutique.ci/merci",
+  metadata: { order: "CMD-1042" },
+});
+// session.amount = 5500, session.url = page de paiement Paywallex
+```
+
+Les montants sont en XOF entiers : `2500` veut dire 2 500 F.
+
+## Vérifier un webhook
+
+Vérifiez la signature avant de traiter un événement. Le SDK compare en temps constant et refuse un horodatage de plus de 5 minutes.
+
+Passez-lui le corps brut de la requête, pas un objet déjà lu par votre framework :
+
+```ts
+import express from "express";
+import { Paywallex } from "@paywallex/node";
+
+const app = express();
+app.post("/webhooks/paywallex", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = Paywallex.constructEvent(req.body, req.get("Paywallex-Signature"), process.env.PAYWALLEX_WEBHOOK_SECRET!);
+    if (event.type === "checkout_session.completed") { /* livrer la commande */ }
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400);
+  }
+});
+```
+
+Les webhooks partent des plages `74.220.51.0/24` et `74.220.59.0/24` (liste à jour : `GET /api/developer/webhook-ips`). Ces plages sont partagées : la signature reste la seule preuve.
+
+## Les erreurs
+
+Chaque erreur est une `PaywallexError` avec un `code` stable. Testez le code, jamais le message :
+
+```ts
+import { PaywallexError } from "@paywallex/node";
+
+try {
+  await paywallex.refunds.create({ payment: "…", amount: 1000 });
+} catch (e) {
+  if (e instanceof PaywallexError && e.code === "refund_not_eligible") { /* … */ }
+  console.log(e.status, e.code, e.param, e.requestId);
+}
+```
+
+Passez `language: "en"` au client pour recevoir les messages en anglais.
+
+## Nouvelles tentatives et idempotence
+
+Le SDK réessaie 2 fois en cas de coupure réseau, de `429` ou d'erreur `5xx`, en respectant `Retry-After`. Chaque `POST` garde la même clé d'idempotence d'une tentative à l'autre : un paiement ou un remboursement n'est jamais doublé.
+
+Pour rejouer vous-même une requête sans risque, donnez votre propre clé :
+
+```ts
+await paywallex.refunds.create({ payment: "…" }, { idempotencyKey: "remboursement-CMD-1042" });
+```
+
+## Ce que couvre le SDK
+
+| Objet | Méthodes |
+| --- | --- |
+| `checkoutSessions` | `create`, `retrieve` |
+| `payments` | `list`, `retrieve`, `all` (toutes les pages) |
+| `refunds` | `create`, `list`, `retrieve`, `all` |
+| `disputes` | `list`, `retrieve`, `all`, `addEvidence` |
+| `files` | `upload` (justificatifs PDF, PNG, JPEG de 5 Mo au plus) |
+| `payouts`, `events`, `statements` | `list`, `retrieve` (`statements.csv`) |
+| `customers`, `paymentLinks`, `invoices`, `pots` | `list`, `create`, `retrieve`, `update`, `action` |
+| `plans`, `coupons`, `subscriptions` | création, lecture, `cancel`, `pause`, `resume`, `changePlan`, `manageLink` |
+| `webhookEndpoints` | `list`, `create`, `del`, `rotateSecret` |
+| client | `account()`, `balance()`, `networkStatus()` |
+
+Accepter un litige (rembourser) ou le contester se fait dans le portail Paywallex, jamais par l'API. Un abonnement ou une hausse de prix est toujours accepté par le client dans Paywallex.
+
+## Licence
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+export declare const VERSION = "1.0.0";
+/** Erreur de l'API : testez `code` (stable), jamais le message. */
+export declare class PaywallexError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    constructor(message: string, status: number, code: string, param?: string | null, requestId?: string | null);
+}
+export type PaywallexOptions = {
+    /** pwx_sk_test_… (bac à sable) ou pwx_sk_live_… (production), ou un jeton OAuth. */
+    apiKey: string;
+    /** https://api.paywallex.app par défaut. */
+    baseUrl?: string;
+    /** 30 s par défaut. */
+    timeoutMs?: number;
+    /** 2 nouvelles tentatives par défaut (réseau, 429, 5xx), toujours avec la même clé d'idempotence. */
+    maxRetries?: number;
+    /** "fr" (défaut) ou "en" : langue des messages d'erreur. */
+    language?: "fr" | "en";
+    /** Remplace fetch (tests, proxy). */
+    fetch?: typeof fetch;
+};
+export type RequestOptions = {
+    idempotencyKey?: string;
+    timeoutMs?: number;
+};
+export type Params = Record<string, unknown>;
+export type List<T> = {
+    object: "list";
+    data: T[];
+    has_more?: boolean;
+    [k: string]: unknown;
+};
+export type Obj = {
+    id: string;
+    object: string;
+    [k: string]: unknown;
+};
+export type LineItem = {
+    name: string;
+    unit_amount: number;
+    quantity?: number;
+};
+export type CheckoutSessionCreate = {
+    currency: "XOF";
+    amount?: number;
+    line_items?: LineItem[];
+    description?: string;
+    customer_email?: string;
+    customer_name?: string;
+    metadata?: Record<string, string>;
+    success_url?: string;
+    cancel_url?: string;
+    expires_at?: number;
+    payment_methods?: string[];
+    [k: string]: unknown;
+};
+export type CheckoutSession = Obj & {
+    url: string;
+    status: "open" | "complete" | "expired";
+    amount: number;
+    currency: string;
+    payment_id: string | null;
+};
+export type Payment = Obj & {
+    amount: number;
+    amount_charged: number;
+    fee: number;
+    net: number;
+    amount_refunded: number;
+    currency: string;
+    status: string;
+    method: string | null;
+    fee_details: {
+        paywallex: number;
+        network: number;
+        tax: number;
+    };
+};
+export type NetworkStatus = {
+    object: "network_status";
+    checked_at: number;
+    data: {
+        network: string;
+        status: "operational" | "degraded" | "unavailable";
+        success_rate_30m: number | null;
+        last_success_at: number | null;
+    }[];
+};
+export type WebhookEvent<T = Record<string, unknown>> = {
+    id: string;
+    type: string;
+    created: string | number;
+    environment: "sandbox" | "live";
+    data: T;
+    [k: string]: unknown;
+};
+export declare class Paywallex {
+    readonly checkoutSessions: {
+        create: (p: CheckoutSessionCreate, o?: RequestOptions) => Promise<CheckoutSession>;
+        retrieve: (id: string) => Promise<CheckoutSession>;
+    };
+    readonly payments: {
+        list: (p?: {
+            limit?: number;
+            starting_after?: string;
+            created?: string;
+        }) => Promise<List<Payment>>;
+        retrieve: (id: string) => Promise<Payment>;
+        /** Parcourt toutes les pages : for await (const p of paywallex.payments.all()) … */
+        all: (p?: {
+            limit?: number;
+        }) => AsyncGenerator<Payment, any, any>;
+    };
+    readonly refunds: {
+        create: (p: {
+            payment: string;
+            amount?: number;
+            reason?: string;
+        }, o?: RequestOptions) => Promise<Obj>;
+        list: (p?: {
+            payment?: string;
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+        all: (p?: {
+            payment?: string;
+            limit?: number;
+        }) => AsyncGenerator<Obj, any, any>;
+    };
+    readonly disputes: {
+        list: (p?: {
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+        all: (p?: {
+            limit?: number;
+        }) => AsyncGenerator<Obj, any, any>;
+        /** Ajoute un justificatif (texte + fichiers déposés avec files.upload). Accepter ou contester se fait dans le portail. */
+        addEvidence: (id: string, p: {
+            text: string;
+            files?: string[];
+        }, o?: RequestOptions) => Promise<Obj>;
+    };
+    readonly files: {
+        /** Dépose un PDF, PNG ou JPEG (5 Mo max) et renvoie son id, à passer dans disputes.addEvidence. */
+        upload: (p: {
+            name: string;
+            contentType: "application/pdf" | "image/png" | "image/jpeg";
+            data: Uint8Array | ArrayBuffer;
+        }) => Promise<{
+            id: string;
+            upload_url: string;
+        }>;
+    };
+    readonly payouts: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+    };
+    readonly events: {
+        list: (p?: {
+            type?: string;
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+    };
+    readonly customers: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        retrieve: (id: string) => Promise<Obj>;
+        update: (id: string, p: Params, o?: RequestOptions) => Promise<Obj>;
+        action: (id: string, action: string, p?: Params, o?: RequestOptions) => Promise<Obj>;
+    };
+    readonly paymentLinks: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        retrieve: (id: string) => Promise<Obj>;
+        update: (id: string, p: Params, o?: RequestOptions) => Promise<Obj>;
+        action: (id: string, action: string, p?: Params, o?: RequestOptions) => Promise<Obj>;
+    };
+    readonly invoices: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        retrieve: (id: string) => Promise<Obj>;
+        update: (id: string, p: Params, o?: RequestOptions) => Promise<Obj>;
+        action: (id: string, action: string, p?: Params, o?: RequestOptions) => Promise<Obj>;
+    };
+    readonly pots: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        retrieve: (id: string) => Promise<Obj>;
+        update: (id: string, p: Params, o?: RequestOptions) => Promise<Obj>;
+        action: (id: string, action: string, p?: Params, o?: RequestOptions) => Promise<Obj>;
+    };
+    readonly statements: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+        csv: (id: string) => Promise<string>;
+    };
+    readonly plans: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        retrieve: (id: string) => Promise<Obj>;
+    };
+    readonly coupons: {
+        list: (p?: Params) => Promise<List<Obj>>;
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        archive: (id: string) => Promise<Obj>;
+    };
+    readonly subscriptions: {
+        create: (p: Params, o?: RequestOptions) => Promise<Obj>;
+        list: (p?: Params) => Promise<List<Obj>>;
+        retrieve: (id: string) => Promise<Obj>;
+        cancel: (id: string, p?: Params) => Promise<Obj>;
+        pause: (id: string, p?: Params) => Promise<Obj>;
+        resume: (id: string, p?: Params) => Promise<Obj>;
+        /** Une hausse doit être acceptée par l'abonné dans Paywallex. */
+        changePlan: (id: string, p: {
+            plan: string;
+            proration?: "next_period" | "immediate";
+        }) => Promise<Obj>;
+        manageLink: (id: string) => Promise<Obj & {
+            url: string;
+        }>;
+    };
+    readonly webhookEndpoints: {
+        list: () => Promise<List<Obj>>;
+        create: (p: {
+            url: string;
+            events?: string[];
+        }, o?: RequestOptions) => Promise<Obj & {
+            secret: string;
+        }>;
+        del: (id: string) => Promise<Obj>;
+        rotateSecret: (id: string) => Promise<Obj & {
+            secret: string;
+        }>;
+    };
+    readonly webhooks: {
+        constructEvent: typeof Paywallex.constructEvent;
+    };
+    private base;
+    private opts;
+    constructor(options: PaywallexOptions | string);
+    account(): Promise<Obj>;
+    balance(): Promise<Obj>;
+    /** Réseaux Mobile Money du pays : masquez ceux qui sont « unavailable » avant le paiement. */
+    networkStatus(): Promise<NetworkStatus>;
+    /**
+     * Vérifie la signature Paywallex-Signature (t=…,v1=…) et renvoie l'événement.
+     * Passez le corps BRUT de la requête (chaîne ou Buffer), jamais un objet déjà lu.
+     */
+    static constructEvent<T = Record<string, unknown>>(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, toleranceSeconds?: number): WebhookEvent<T>;
+    paginate<T extends {
+        id: string;
+    }>(path: string, params?: Params): AsyncGenerator<T>;
+    get<T>(path: string, params?: Params): Promise<T>;
+    post<T>(path: string, body: unknown, o?: RequestOptions): Promise<T>;
+    private raw;
+    private headers;
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, o?: RequestOptions): Promise<T>;
+}
+export default Paywallex;

package/dist/index.js

@@ -0,0 +1,225 @@
+// @paywallex/node : SDK serveur officiel de l'API Paywallex /v1 (Node 18+, Bun, Deno).
+// Côté serveur uniquement : ne mettez jamais une clé secrète pwx_sk_… dans un navigateur ou une app mobile.
+// Référence : https://api.paywallex.app/api/developer/openapi-v1.json. Signé : Superagent (DV3, 24 oct. 2026).
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+export const VERSION = "1.0.0";
+/** Erreur de l'API : testez `code` (stable), jamais le message. */
+export class PaywallexError extends Error {
+    status;
+    code;
+    param;
+    requestId;
+    constructor(message, status, code, param = null, requestId = null) {
+        super(message);
+        this.name = "PaywallexError";
+        this.status = status;
+        this.code = code;
+        this.param = param;
+        this.requestId = requestId;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const enc = encodeURIComponent;
+function query(params) {
+    if (!params)
+        return "";
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== null)
+            q.set(k, String(v));
+    const s = q.toString();
+    return s ? `?${s}` : "";
+}
+export class Paywallex {
+    checkoutSessions;
+    payments;
+    refunds;
+    disputes;
+    files;
+    payouts;
+    events;
+    customers;
+    paymentLinks;
+    invoices;
+    pots;
+    statements;
+    plans;
+    coupons;
+    subscriptions;
+    webhookEndpoints;
+    webhooks;
+    base;
+    opts;
+    constructor(options) {
+        const o = typeof options === "string" ? { apiKey: options } : options;
+        if (!o?.apiKey)
+            throw new PaywallexError("apiKey manquante : passez votre clé secrète pwx_sk_… explicitement.", 0, "configuration_error");
+        let base = o.baseUrl ?? "https://api.paywallex.app";
+        while (base.endsWith("/"))
+            base = base.slice(0, -1);
+        this.base = base;
+        this.opts = { apiKey: o.apiKey, timeoutMs: o.timeoutMs ?? 30000, maxRetries: o.maxRetries ?? 2, language: o.language ?? "fr", fetch: o.fetch ?? globalThis.fetch };
+        const r = this;
+        const crud = (path, actions = []) => ({
+            list: (p) => r.get(`/v1/${path}`, p),
+            create: (p, o) => r.post(`/v1/${path}`, p, o),
+            retrieve: (id) => r.get(`/v1/${path}/${enc(id)}`),
+            update: (id, p, o) => r.post(`/v1/${path}/${enc(id)}`, p, o),
+            action: (id, action, p = {}, o) => {
+                if (!actions.includes(action))
+                    throw new PaywallexError(`Action inconnue : ${action}. Possibles : ${actions.join(", ")}.`, 0, "configuration_error");
+                return r.post(`/v1/${path}/${enc(id)}/${action}`, p, o);
+            },
+        });
+        this.checkoutSessions = {
+            create: (p, o) => r.post("/v1/checkout_sessions", p, o),
+            retrieve: (id) => r.get(`/v1/checkout_sessions/${enc(id)}`),
+        };
+        this.payments = {
+            list: (p) => r.get("/v1/payments", p),
+            retrieve: (id) => r.get(`/v1/payments/${enc(id)}`),
+            /** Parcourt toutes les pages : for await (const p of paywallex.payments.all()) … */
+            all: (p) => r.paginate("/v1/payments", p),
+        };
+        this.refunds = {
+            create: (p, o) => r.post("/v1/refunds", p, o),
+            list: (p) => r.get("/v1/refunds", p),
+            retrieve: (id) => r.get(`/v1/refunds/${enc(id)}`),
+            all: (p) => r.paginate("/v1/refunds", p),
+        };
+        this.disputes = {
+            list: (p) => r.get("/v1/disputes", p),
+            retrieve: (id) => r.get(`/v1/disputes/${enc(id)}`),
+            all: (p) => r.paginate("/v1/disputes", p),
+            /** Ajoute un justificatif (texte + fichiers déposés avec files.upload). Accepter ou contester se fait dans le portail. */
+            addEvidence: (id, p, o) => r.post(`/v1/disputes/${enc(id)}/evidence`, p, o),
+        };
+        this.files = {
+            /** Dépose un PDF, PNG ou JPEG (5 Mo max) et renvoie son id, à passer dans disputes.addEvidence. */
+            upload: async (p) => {
+                const bytes = p.data instanceof Uint8Array ? p.data : new Uint8Array(p.data);
+                const f = await r.post("/v1/files", { name: p.name, content_type: p.contentType, size: bytes.byteLength });
+                const put = await r.opts.fetch(f.upload_url, { method: "PUT", headers: { "Content-Type": p.contentType }, body: bytes,
+                    signal: AbortSignal.timeout(r.opts.timeoutMs) });
+                if (!put.ok)
+                    throw new PaywallexError(`Dépôt du fichier refusé (${put.status}).`, put.status, "file_upload_failed");
+                return f;
+            },
+        };
+        this.payouts = { list: (p) => r.get("/v1/payouts", p), retrieve: (id) => r.get(`/v1/payouts/${enc(id)}`) };
+        this.events = {
+            list: (p) => r.get("/v1/events", p),
+            retrieve: (id) => r.get(`/v1/events/${enc(id)}`),
+        };
+        this.customers = crud("customers", ["archive"]);
+        this.paymentLinks = crud("payment_links", ["cancel"]);
+        this.invoices = crud("invoices", ["issue", "cancel"]);
+        this.pots = crud("pots", ["close", "cancel"]);
+        this.statements = {
+            list: (p) => r.get("/v1/statements", p),
+            retrieve: (id) => r.get(`/v1/statements/${enc(id)}`),
+            csv: (id) => r.raw("GET", `/v1/statements/${enc(id)}/csv`).then((res) => res.text()),
+        };
+        this.plans = { list: (p) => r.get("/v1/plans", p), create: (p, o) => r.post("/v1/plans", p, o),
+            retrieve: (id) => r.get(`/v1/plans/${enc(id)}`) };
+        this.coupons = { list: (p) => r.get("/v1/coupons", p), create: (p, o) => r.post("/v1/coupons", p, o),
+            archive: (id) => r.post(`/v1/coupons/${enc(id)}/archive`, {}) };
+        this.subscriptions = {
+            create: (p, o) => r.post("/v1/subscriptions", p, o),
+            list: (p) => r.get("/v1/subscriptions", p),
+            retrieve: (id) => r.get(`/v1/subscriptions/${enc(id)}`),
+            cancel: (id, p = {}) => r.post(`/v1/subscriptions/${enc(id)}/cancel`, p),
+            pause: (id, p = {}) => r.post(`/v1/subscriptions/${enc(id)}/pause`, p),
+            resume: (id, p = {}) => r.post(`/v1/subscriptions/${enc(id)}/resume`, p),
+            /** Une hausse doit être acceptée par l'abonné dans Paywallex. */
+            changePlan: (id, p) => r.post(`/v1/subscriptions/${enc(id)}/change_plan`, p),
+            manageLink: (id) => r.post(`/v1/subscriptions/${enc(id)}/manage_link`, {}),
+        };
+        this.webhookEndpoints = {
+            list: () => r.get("/v1/webhook_endpoints"),
+            create: (p, o) => r.post("/v1/webhook_endpoints", p, o),
+            del: (id) => r.request("DELETE", `/v1/webhook_endpoints/${enc(id)}`),
+            rotateSecret: (id) => r.post(`/v1/webhook_endpoints/${enc(id)}/rotate_secret`, {}),
+        };
+        this.webhooks = { constructEvent: Paywallex.constructEvent };
+    }
+    account() { return this.get("/v1/account"); }
+    balance() { return this.get("/v1/balance"); }
+    /** Réseaux Mobile Money du pays : masquez ceux qui sont « unavailable » avant le paiement. */
+    networkStatus() { return this.get("/v1/network_status"); }
+    /**
+     * Vérifie la signature Paywallex-Signature (t=…,v1=…) et renvoie l'événement.
+     * Passez le corps BRUT de la requête (chaîne ou Buffer), jamais un objet déjà lu.
+     */
+    static constructEvent(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+        const m = /^t=([0-9]+),v1=([a-f0-9]{64})$/.exec((signatureHeader ?? "").trim());
+        if (!m)
+            throw new PaywallexError("Signature absente ou mal formée.", 400, "invalid_signature");
+        if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSeconds)
+            throw new PaywallexError("Signature expirée.", 400, "signature_expired");
+        const body = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+        const expected = createHmac("sha256", secret).update(`${m[1]}.${body}`).digest();
+        const given = Buffer.from(m[2], "hex");
+        if (given.length !== expected.length || !timingSafeEqual(given, expected))
+            throw new PaywallexError("Signature invalide.", 400, "invalid_signature");
+        return JSON.parse(body);
+    }
+    async *paginate(path, params = {}) {
+        let after;
+        for (let page = 0; page < 10000; page++) {
+            const list = await this.get(path, { ...params, ...(after ? { starting_after: after } : {}) });
+            for (const item of list.data)
+                yield item;
+            if (!list.has_more || !list.data.length)
+                return;
+            after = list.data[list.data.length - 1].id;
+        }
+    }
+    get(path, params) { return this.request("GET", path + query(params)); }
+    post(path, body, o) { return this.request("POST", path, body, o); }
+    raw(method, path) {
+        return this.opts.fetch(this.base + path, { method, headers: this.headers(), signal: AbortSignal.timeout(this.opts.timeoutMs) });
+    }
+    headers(extra = {}) {
+        return { Authorization: `Bearer ${this.opts.apiKey}`, "Accept-Language": this.opts.language, "User-Agent": `paywallex-node/${VERSION}`, "Paywallex-Sdk": `node/${VERSION}`, ...extra };
+    }
+    async request(method, path, body, o = {}) {
+        // Une seule clé d'idempotence pour toutes les tentatives : un POST rejoué n'est jamais doublé.
+        const idem = method === "POST" ? (o.idempotencyKey ?? randomUUID()) : undefined;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.opts.fetch(this.base + path, {
+                    method, signal: AbortSignal.timeout(o.timeoutMs ?? this.opts.timeoutMs),
+                    headers: this.headers({ ...(body !== undefined ? { "Content-Type": "application/json" } : {}), ...(idem ? { "Idempotency-Key": idem } : {}) }),
+                    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                });
+            }
+            catch (e) {
+                if (attempt < this.opts.maxRetries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                throw new PaywallexError(`Paywallex injoignable : ${e instanceof Error ? e.message : String(e)}`, 0, "network_error");
+            }
+            const text = await res.text();
+            let data = {};
+            try {
+                data = text ? JSON.parse(text) : {};
+            }
+            catch {
+                data = {};
+            }
+            if (res.ok)
+                return data;
+            if ((res.status === 429 || res.status >= 500) && attempt < this.opts.maxRetries) {
+                const ra = Number(res.headers.get("Retry-After"));
+                await sleep(Number.isFinite(ra) && ra > 0 ? Math.min(ra, 30) * 1000 : 500 * 2 ** attempt);
+                continue;
+            }
+            const e = data.error;
+            throw new PaywallexError(e?.message ?? `Requête refusée (${res.status}).`, res.status, e?.code ?? "unknown_error", e?.param ?? null, e?.request_id ?? res.headers.get("Request-Id"));
+        }
+    }
+}
+export default Paywallex;

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@paywallex/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "SDK serveur officiel de l'API Paywallex /v1 : sessions de paiement Mobile Money, remboursements, litiges, abonnements, webhooks signés.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "license": "MIT",
+  "homepage": "https://paywallex.app/developpeurs",
+  "repository": { "type": "git", "url": "git+https://github.com/Paywallex/paywallex-kit.git", "directory": "sdk/node" },
+  "keywords": ["paywallex", "paiement", "mobile money", "orange money", "mtn momo", "moov money", "wave", "xof", "afrique de l'ouest", "api"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  }
+}