@paywallex/node 1.0.0 → 1.2.0

package/README.md

@@ -39,6 +39,31 @@ const session = await paywallex.checkoutSessions.create({
 
 Les montants sont en XOF entiers : `2500` veut dire 2 500 F.
 
+### Facturation à l'usage
+
+```ts
+const plan = await paywallex.plans.create({ name: "Formule SMS", amount: 2000, currency: "XOF", interval: "monthly",
+  usage: { mode: "metered", unit: "SMS", unit_amount: 5, cap: 10000 } });
+await paywallex.subscriptions.reportUsage(subscriptionId, { quantity: 120 }, { idempotencyKey: "sms-2026-10-25" });
+// 402 usage_cap_reached : l'abonné doit relever son plafond dans Paywallex.
+```
+
+### Paiements partagés (plateformes)
+
+Indiquez la part de chaque vendeur par son @identifiant : elle part sur son solde dès que l'argent de la vente est disponible chez vous. Vous gardez le reste, frais Paywallex déduits.
+
+```ts
+const session = await paywallex.checkoutSessions.create({
+  currency: "XOF",
+  amount: 20000,
+  splits: [
+    { destination: "@chezpapa", amount: 15000, description: "Commande 1042" },
+    { destination: "@livraison-rapide", amount: 2000 },
+  ],
+});
+// session.splits[0].status : "pending", puis "paid" (événement payment_split.paid)
+```
+
 ## 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.
@@ -87,7 +112,7 @@ Le SDK réessaie 2 fois en cas de coupure réseau, de `429` ou d'erreur `5xx`, e
 Pour rejouer vous-même une requête sans risque, donnez votre propre clé :
 
 ```ts
-await paywallex.refunds.create({ payment: "…" }, { idempotencyKey: "remboursement-CMD-1042" });
+await paywallex.refunds.create({ payment: "…" }, { idempotencyKey: `remboursement-${order.id}` });
 ```
 
 ## Ce que couvre le SDK
@@ -101,7 +126,7 @@ await paywallex.refunds.create({ payment: "…" }, { idempotencyKey: "remboursem
 | `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` |
+| `plans`, `coupons`, `subscriptions` | création, lecture, `cancel`, `pause`, `resume`, `changePlan`, `manageLink`, `reportUsage`, `usage` |
 | `webhookEndpoints` | `list`, `create`, `del`, `rotateSecret` |
 | client | `account()`, `balance()`, `networkStatus()` |
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.2.0";
 /** Erreur de l'API : testez `code` (stable), jamais le message. */
 export declare class PaywallexError extends Error {
     readonly status: number;
@@ -42,6 +42,60 @@ export type LineItem = {
     unit_amount: number;
     quantity?: number;
 };
+/** DV7 : facturation à l'usage d'une offre (metered : fin de période + plafond ; credits : packs prépayés). */
+export type UsagePlan = {
+    mode: "metered";
+    unit: string;
+    unit_amount: number;
+    cap: number;
+} | {
+    mode: "credits";
+    unit: string;
+    pack_units: number;
+    pack_amount: number;
+};
+export type UsageSummary = {
+    mode: "metered" | "credits";
+    unit: string;
+    currency: string;
+    unit_amount: number | null;
+    cap: number | null;
+    unbilled_amount: number | null;
+    unbilled_quantity: number | null;
+    credits_remaining: number | null;
+    pack: {
+        units: number;
+        amount: number;
+    } | null;
+};
+export type UsageRecord = Obj & {
+    subscription: string;
+    mode: "metered" | "credits";
+    quantity: number;
+    amount: number;
+    description: string | null;
+    status: "unbilled" | "billed" | "credited" | "waived";
+    period: number;
+    usage?: UsageSummary | null;
+};
+/** DV7 : part d'un vendeur (paiements partagés). La plateforme garde le reste, frais Paywallex déduits. */
+export type SplitInput = {
+    destination: string;
+    amount: number;
+    description?: string;
+};
+export type PaymentSplit = Obj & {
+    destination: string;
+    destination_name: string | null;
+    amount: number;
+    currency: string;
+    description: string | null;
+    status: "pending" | "paid" | "failed" | "canceled";
+    amount_paid: number;
+    amount_reversed: number;
+    failure_reason: string | null;
+    paid_at: number | null;
+};
 export type CheckoutSessionCreate = {
     currency: "XOF";
     amount?: number;
@@ -54,6 +108,7 @@ export type CheckoutSessionCreate = {
     cancel_url?: string;
     expires_at?: number;
     payment_methods?: string[];
+    splits?: SplitInput[];
     [k: string]: unknown;
 };
 export type CheckoutSession = Obj & {
@@ -62,8 +117,10 @@ export type CheckoutSession = Obj & {
     amount: number;
     currency: string;
     payment_id: string | null;
+    splits?: PaymentSplit[];
 };
 export type Payment = Obj & {
+    splits?: PaymentSplit[];
     amount: number;
     amount_charged: number;
     fee: number;
@@ -226,6 +283,15 @@ export declare class Paywallex {
         manageLink: (id: string) => Promise<Obj & {
             url: string;
         }>;
+        reportUsage: (id: string, p: {
+            quantity: number;
+            description?: string;
+        }, o?: RequestOptions) => Promise<UsageRecord>;
+        usage: (id: string, p?: {
+            limit?: number;
+        }) => Promise<List<UsageRecord> & {
+            usage: UsageSummary | null;
+        }>;
     };
     readonly webhookEndpoints: {
         list: () => Promise<List<Obj>>;

package/dist/index.js

@@ -2,7 +2,7 @@
 // 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";
+export const VERSION = "1.2.0";
 /** Erreur de l'API : testez `code` (stable), jamais le message. */
 export class PaywallexError extends Error {
     status;
@@ -134,6 +134,9 @@ export class Paywallex {
             /** 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`, {}),
+            // DV7 : facturation à l'usage. 402 usage_cap_reached / usage_credits_exhausted si l'abonné doit agir dans Paywallex.
+            reportUsage: (id, p, o) => r.post(`/v1/subscriptions/${enc(id)}/usage`, p, o),
+            usage: (id, p) => r.get(`/v1/subscriptions/${enc(id)}/usage`, p),
         };
         this.webhookEndpoints = {
             list: () => r.get("/v1/webhook_endpoints"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paywallex/node",
-  "version": "1.0.0",
+  "version": "1.2.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",