@paywallex/node 1.1.0 → 1.2.0

package/README.md

@@ -39,6 +39,15 @@ 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.
@@ -117,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.1.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,42 @@ 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;
@@ -247,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.1.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.1.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",