@sweepconsole/node 0.1.1 → 0.2.1

package/README.md

@@ -91,7 +91,7 @@ app.post("/subscribe/usdc", async (req, res) => {
     email: req.user.email,
     maxAmount: usdc("15.00"),              // the CEILING, not the price
     interval: "monthly",
-    chains: ["base", "arbitrum", "optimism"],
+    chains: ["base", "arbitrum", "optimism"],  // what to OFFER — they pick
     expiresAt: new Date("2027-01-01"),
     returnUrl: "https://shop.example.com/thanks",
   });
@@ -101,6 +101,11 @@ app.post("/subscribe/usdc", async (req, res) => {
 });
 ```
 
+The payer chooses which of those chains to sign, so `chains` is a maximum rather
+than a promise. What they actually granted comes back as `mandate.grantedChains`,
+and on the `mandate.authorized` event as `chain_ids`. Charge against those — a
+mandate offered on three chains is often live on one.
+
 **2 — react to what happens**
 
 ```ts

package/dist/client.js

@@ -247,6 +247,7 @@ function toMandate(raw) {
         interval: raw.interval,
         periodDuration: raw.period_duration,
         chains: raw.chains ?? [],
+        grantedChains: raw.granted_chains ?? [],
         testMode: !!raw.test_mode,
         expiresAt: date(raw.expires_at),
         authorizationUrl: raw.authorization_url ?? null,

package/dist/types.d.ts

@@ -33,7 +33,22 @@ export interface Mandate {
     currency: "USDC";
     interval: Interval;
     periodDuration: number;
+    /**
+     * The chains you OFFERED when you created the mandate.
+     *
+     * Not what the payer granted. The authorization page lets them choose which
+     * of these to sign, so a mandate offered on three chains can be live on one
+     * — and this still reads three. Charge against `grantedChains`.
+     */
     chains: string[];
+    /**
+     * The chains the payer actually signed, and what a charge can draw from.
+     *
+     * Empty while the mandate is pending. It shrinks if they later disable a
+     * chain in their own wallet, which is the same set `grant.revoked` reports
+     * as `remaining_chains`.
+     */
+    grantedChains: string[];
     testMode: boolean;
     /** When the authorization stops being redeemable. */
     expiresAt: Date;
@@ -78,6 +93,12 @@ export interface CreateMandateParams {
     /** The ceiling per interval — NOT the price. Give it headroom. */
     maxAmount: Usdc;
     interval: Interval;
+    /**
+     * The chains to OFFER the payer. They choose which to sign, so this is a
+     * maximum, not a promise — read `grantedChains` back to see what you got.
+     * More chains means more ways for a charge to succeed, so offer all you
+     * support unless you have a reason not to.
+     */
     chains: Chain[];
     expiresAt: Date;
     returnUrl?: string;
@@ -172,7 +193,7 @@ export interface RetrievedSession {
     expiresAt: Date;
     createdAt: Date;
 }
-export type WebhookEventType = "checkout.session.completed" | "subscription.created" | "subscription.renewed" | "subscription.past_due" | "subscription.cancelled" | "payment.succeeded" | "payment.failed" | "mandate.authorized" | "mandate.revoked" | "mandate.expiring" | "mandate.expired" | "charge.succeeded" | "charge.failed";
+export type WebhookEventType = "checkout.session.completed" | "subscription.created" | "subscription.renewed" | "subscription.past_due" | "subscription.cancelled" | "payment.succeeded" | "payment.failed" | "mandate.authorized" | "mandate.revoked" | "grant.revoked" | "grant.added" | "mandate.expiring" | "mandate.expired" | "charge.succeeded" | "charge.failed";
 /**
  * What each event carries.
  *
@@ -299,6 +320,12 @@ export interface WebhookPayloads {
          */
         wallet_reused: boolean;
     };
+    /**
+     * The authorization is FINISHED — nothing left to charge on any chain.
+     *
+     * One chain leaving a live mandate is `grant.revoked`, not this. Acting on
+     * the wrong one cuts off a customer who is still paying you.
+     */
     "mandate.revoked": {
         mandate_id: string;
         external_ref: string;
@@ -312,6 +339,44 @@ export interface WebhookPayloads {
          * guaranteed is that Sweep Console will not redeem it again.
          */
         on_chain: boolean;
+        /** Always empty here — the authorization is over. */
+        remaining_chains: string[];
+        /** Always false here. Branch on this rather than on the event name. */
+        mandate_still_active: boolean;
+    };
+    /**
+     * A payer withdrew ONE chain's permission in their own wallet.
+     *
+     * The authorization survives on the rest, so this is not a reason to stop
+     * serving. A wallet-side withdrawal is invisible to Sweep until the daily
+     * reconciliation looks, so this arrives then rather than the moment they act.
+     */
+    "grant.revoked": {
+        mandate_id: string;
+        chain_id: number;
+        grant_id: string | null;
+        subscription_id: string | null;
+        reason: string;
+        /** What is still chargeable. Empty would make this a mandate.revoked. */
+        remaining_chains: string[];
+        /** True here, by definition. */
+        mandate_still_active: boolean;
+    };
+    /**
+     * A payer authorized an EXTRA chain on a live mandate.
+     *
+     * The mirror of `grant.revoked` — more ways for a charge to succeed, and
+     * nothing to stop. Not sent during the first authorization, where
+     * `mandate.authorized` already carries every chain in `chain_ids`.
+     */
+    "grant.added": {
+        mandate_id: string;
+        chain_id: number;
+        grant_id: string | null;
+        /** The whole chargeable set after the change, not just the new chain. */
+        granted_chains: string[];
+        /** True here, by definition. */
+        mandate_still_active: boolean;
     };
     "mandate.expiring": {
         mandate_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweepconsole/node",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Node/TypeScript client for the Sweep Console payment rail — charge a USDC wallet from your own app",
   "license": "MIT",
   "type": "module",