@profullstack/x402-gateway 0.4.0 → 0.6.0

package/index.d.ts

@@ -149,9 +149,24 @@ export interface RobotsOptions {
   comments?: string[];
 }
 
+/** What the caller spent against an allowance, as `spend()` reports it. */
+export interface QuotaUsage {
+  count: number;
+  remaining: number;
+  resetSeconds: number;
+  overLimit: boolean;
+}
+
+/** The allowance a 402 should quote, when the caller kept the count itself. */
+export interface SellContext {
+  usage?: QuotaUsage | null;
+  /** Defaults to the gateway's own `freeQuota`. */
+  quota?: { requests: number; windowSeconds: number } | null;
+}
+
 export interface Gateway {
   handle: Handle;
-  sell: (request: Request) => Promise<Response>;
+  sell: (request: Request, context?: SellContext) => Promise<Response>;
   enabled: boolean;
   options: Required<Omit<GatewayOptions, 'onSale' | 'fetch' | 'page' | 'isPaidAgent'>> & {
     onSale: GatewayOptions['onSale'] | null;
@@ -161,6 +176,14 @@ export interface Gateway {
   };
   robotsTxt: (extra?: RobotsOptions) => string;
   page: () => string;
+  /** The pass this request presents, from the gateway's header or a bearer token. */
+  passFrom: (request: Request) => string | null;
+  /** Whether that token is a live pass this gateway minted. */
+  verifyPass: (token: string | null) => Promise<boolean>;
+  /** The x402 offer this gateway would make, without answering a request. */
+  offer: (days?: number) => Offer;
+  /** The full 402 body around that offer: the offer plus the pass terms. */
+  receipt: (days?: number, extra?: Record<string, unknown>) => Offer & Record<string, unknown>;
 }
 
 export function createGateway(options: GatewayOptions): Gateway;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/x402-gateway",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Sell crawl access to AI training crawlers by the day over x402, settled by CoinPay. One middleware: 402 with an offer, a sales page with CLI instructions, signed passes, and a robots.txt that keeps search crawlers welcome.",
   "keywords": [
@@ -20,22 +20,52 @@
     "middleware",
     "paywall"
   ],
-  "repository": { "type": "git", "url": "git+https://github.com/profullstack/x402-gateway.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/x402-gateway.git"
+  },
   "homepage": "https://github.com/profullstack/x402-gateway#readme",
-  "bugs": { "url": "https://github.com/profullstack/x402-gateway/issues" },
+  "bugs": {
+    "url": "https://github.com/profullstack/x402-gateway/issues"
+  },
   "license": "MIT",
   "author": "Profullstack, LLC",
   "exports": {
-    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
-    "./hono": { "types": "./index.d.ts", "import": "./src/hono.js" },
-    "./next": { "types": "./index.d.ts", "import": "./src/next.js" },
-    "./robots": { "types": "./index.d.ts", "import": "./src/robots.js" },
-    "./agents": { "types": "./index.d.ts", "import": "./src/agents.js" },
-    "./edge": { "types": "./index.d.ts", "import": "./src/edge.js" }
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./hono": {
+      "types": "./index.d.ts",
+      "import": "./src/hono.js"
+    },
+    "./next": {
+      "types": "./index.d.ts",
+      "import": "./src/next.js"
+    },
+    "./robots": {
+      "types": "./index.d.ts",
+      "import": "./src/robots.js"
+    },
+    "./agents": {
+      "types": "./index.d.ts",
+      "import": "./src/agents.js"
+    },
+    "./edge": {
+      "types": "./index.d.ts",
+      "import": "./src/edge.js"
+    }
   },
   "types": "./index.d.ts",
-  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=20.11" },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
   "sideEffects": false,
   "scripts": {
     "test": "node --test"

package/src/index.js

@@ -127,11 +127,11 @@ export function createGateway(options = {}) {
       headers: { 'content-type': 'text/html; charset=utf-8', ...noStore, ...headers },
     });
 
-  const pageCtx = (days = 1, usage = null) => ({
-    quota: o.freeQuota
+  const pageCtx = (days = 1, usage = null, quota = o.freeQuota) => ({
+    quota: quota
       ? {
-          requests: o.freeQuota.requests,
-          windowSeconds: o.freeQuota.windowSeconds,
+          requests: quota.requests,
+          windowSeconds: quota.windowSeconds,
           used: usage?.count ?? null,
           resetSeconds: usage?.resetSeconds ?? null,
           exceeded: Boolean(usage?.overLimit),
@@ -177,7 +177,15 @@ export function createGateway(options = {}) {
     // Present when the free allowance is what stopped this request, rather than
     // the crawler lists. It changes what the 402 says, not what it costs.
     const usage = context.usage ?? null;
-    const rateHeaders = usage ? quotaHeaders(o.freeQuota, usage) : {};
+    /*
+     * The allowance the caller was measured against. Defaults to this
+     * gateway's own, but a caller that keeps its own counter -- an app-wide
+     * throttle metering every route, not just the crawler lists -- hands its
+     * own in, so the 402 quotes the limit that actually stopped the request
+     * rather than one the gateway happens to hold.
+     */
+    const quota = context.quota ?? o.freeQuota;
+    const rateHeaders = usage && quota ? quotaHeaders(quota, usage) : {};
 
     if (proofHeader) {
       if (!enabled) return json(receipt(asked, { error: 'Payments are not switched on here.' }), 402);
@@ -272,22 +280,22 @@ export function createGateway(options = {}) {
     }
 
     if (wantsHtml(request.headers.get('accept'))) {
-      return html(o.page(pageCtx(asked, usage)), 402, rateHeaders);
+      return html(o.page(pageCtx(asked, usage, quota)), 402, rateHeaders);
     }
 
-    if (usage) {
+    if (usage && quota) {
       // Say what ran out, when it comes back, and what a pass costs, in that
       // order. A caller reading this is deciding between waiting, rotating
       // addresses, and paying, and the numbers are the argument.
       return json(
         receipt(asked, {
           error:
-            `Free allowance used: ${o.freeQuota.requests} requests per ` +
-            `${o.freeQuota.windowSeconds}s. It resets in ${usage.resetSeconds}s. ` +
+            `Free allowance used: ${quota.requests} requests per ` +
+            `${quota.windowSeconds}s. It resets in ${usage.resetSeconds}s. ` +
             `A pass removes the limit for ${price} a day.`,
           quota: {
-            requests: o.freeQuota.requests,
-            windowSeconds: o.freeQuota.windowSeconds,
+            requests: quota.requests,
+            windowSeconds: quota.windowSeconds,
             used: usage.count,
             resetSeconds: usage.resetSeconds,
           },
@@ -367,6 +375,33 @@ export function createGateway(options = {}) {
     sell,
     enabled,
     options: o,
+    /**
+     * The pass a request presents, and whether it is one this gateway minted
+     * and still honours.
+     *
+     * Exposed because the pass has to be honoured by everything that could
+     * refuse a request, not only by `handle`. An app-wide throttle that meters
+     * every route has to skip whoever already paid, and recomputing the
+     * signing-secret fallback (`secret || coinpay.apiKey`) on its side is
+     * exactly the kind of duplicate rule that drifts and starts charging
+     * paying crawlers twice.
+     */
+    passFrom,
+    verifyPass: async (token) => Boolean(token && (await readPass(token, { secret }))),
+    /**
+     * The x402 offer this gateway would make, and the full receipt body around
+     * it, without answering a request.
+     *
+     * A site with its own refusal -- a tiered limiter whose 429 body says which
+     * rung the caller is on and what the next one costs -- wants to keep that
+     * body and add a machine-readable offer to it, so an x402 client can pay
+     * on the spot instead of being told in prose to go and fetch /crawl. The
+     * alternative is every such site rebuilding payTo, price, currency and
+     * network from its own copy of the config, which is how two of them end up
+     * quoting different numbers.
+     */
+    offer,
+    receipt,
     /** robots.txt with this gateway's lists and sales path. */
     robotsTxt: (extra = {}) =>
       robotsTxt({ siteUrl: o.siteUrl, path: o.path, training: o.training, retrieval: o.retrieval, ...extra }),