@sweepconsole/node 0.1.0 → 0.2.0

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

@@ -72,8 +72,9 @@ export class Sweep {
         catch {
             const looksLikeHtml = /^\s*<(!doctype|html)/i.test(text);
             throw new SweepError(looksLikeHtml
-                ? `Expected JSON from ${res.url} but got an HTML page. This usually means baseUrl points at the ` +
-                    `website rather than the API — check the API base URL in your Sweep portal.`
+                ? `Expected JSON from ${res.url} but got an HTML page. Either baseUrl points at the website ` +
+                    `rather than the API — api.sweepconsole.xyz, not www — or something between you and the API ` +
+                    `answered instead of it.`
                 : `Expected JSON from ${res.url} but got ${res.headers.get("content-type") ?? "an unknown type"}.`, { code: "invalid_response", status: res.status });
         }
     }
@@ -105,6 +106,13 @@ export class Sweep {
                 });
                 if (res.ok)
                     return (await this.parse(res));
+                const blocked = edgeBlock(res);
+                if (blocked) {
+                    throw new SweepError(`Blocked before reaching the Sweep API: ${res.status} from a proxy in front of ` +
+                        `${res.url}, answering HTML rather than JSON. Server-to-server requests trip bot ` +
+                        `protection tuned for browsers, so this is infrastructure rather than your code. ` +
+                        `Quote this trace id to support: ${blocked.trace}`, { code: "blocked_upstream", status: res.status, reference: blocked.trace });
+                }
                 // 5xx and 429 may succeed on a retry; a 4xx is a decision, not a blip.
                 if ((res.status >= 500 || res.status === 429) && attempt < this.maxRetries) {
                     lastError = errorFrom(res.status, await safeJson(res));
@@ -239,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,
@@ -271,6 +280,32 @@ function toCharge(raw) {
 function safeJson(res) {
     return res.json().catch(() => null);
 }
+/**
+ * A proxy in front of the API refused the request before it got there.
+ *
+ * Server-to-server calls are what this catches. A request from a datacenter
+ * carries no browser fingerprint, so bot protection tuned for browsers treats
+ * it as exactly the thing it is looking for and answers a challenge page —
+ * HTML, with a 403, and a trace id of its own.
+ *
+ * Worth separating from every other 403, because nothing about the caller's
+ * code is wrong and no amount of re-reading their API key will help. The trace
+ * id is the one piece of information support actually needs.
+ */
+function edgeBlock(res) {
+    if (res.status !== 403 && res.status !== 503)
+        return null;
+    const trace = res.headers.get("cf-ray") ??
+        res.headers.get("x-amz-cf-id") ??
+        res.headers.get("x-akamai-request-id");
+    if (!trace)
+        return null;
+    // Our own 403s are JSON. An HTML body means something else answered.
+    const type = res.headers.get("content-type") ?? "";
+    if (type.includes("json"))
+        return null;
+    return { trace };
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }

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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sweepconsole/node",
-  "version": "0.1.0",
-  "description": "Node/TypeScript client for the Sweep Console payment rail \u2014 charge a USDC wallet from your own app",
+  "version": "0.2.0",
+  "description": "Node/TypeScript client for the Sweep Console payment rail — charge a USDC wallet from your own app",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",