fix(proxy): invoke onPayment after confirmed settlement (rebase of #325)

src/payment-preauth.test.ts

@@ -84,7 +84,10 @@ function fakeGateway() {
         ctl.rejectNextPaid = false;
         return challenge402(); // underpayment rejected
       }
-      return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "payment-response": "settled" },
+      });
     }
     return challenge402();
   });
@@ -97,6 +100,57 @@ function body(maxTokens = 10) {
 }
 
 describe("payment pre-auth — per-request pricing safety", () => {
+  it("notifies once after the normal 402 then accepted paid retry", async () => {
+    const gw = fakeGateway();
+    const onPayment = vi.fn();
+    const pay = createPayFetchWithPreAuth(gw.fn, testClient(), undefined, {
+      estimateAmount: () => "1000",
+      onPayment,
+    });
+
+    await pay(URL, { method: "POST", body: body() });
+
+    expect(onPayment).toHaveBeenCalledOnce();
+    expect(onPayment).toHaveBeenCalledWith({
+      model: "test/model",
+      amount: "1000",
+      network: "eip155:8453",
+    });
+  });
+
+  it("notifies once for an accepted cached pre-auth and never for a rejected one", async () => {
+    const gw = fakeGateway();
+    const onPayment = vi.fn();
+    const pay = createPayFetchWithPreAuth(gw.fn, testClient(), undefined, {
+      estimateAmount: () => "1000",
+      onPayment,
+    });
+
+    await pay(URL, { method: "POST", body: body() });
+    onPayment.mockClear();
+    await pay(URL, { method: "POST", body: body() });
+    expect(onPayment).toHaveBeenCalledOnce();
+
+    onPayment.mockClear();
+    gw.ctl.rejectNextPaid = true;
+    await pay(URL, { method: "POST", body: body() });
+    expect(onPayment).toHaveBeenCalledOnce();
+  });
+
+  it("does not let an observer failure turn a settled response into a retry", async () => {
+    const gw = fakeGateway();
+    const pay = createPayFetchWithPreAuth(gw.fn, testClient(), undefined, {
+      estimateAmount: () => "1000",
+      onPayment: () => {
+        throw new Error("observer failed");
+      },
+    });
+
+    const res = await pay(URL, { method: "POST", body: body() });
+    expect(res.status).toBe(200);
+    expect(gw.calls.map((call) => call.paid)).toEqual([false, true]);
+  });
+
   it("reuses pre-auth when the estimate proves the cache still covers it (no extra 402)", async () => {
     const est = vi.fn(() => "1000"); // every request estimated equal
     const gw = fakeGateway();

src/payment-preauth.ts

@@ -47,11 +47,17 @@ const DEFAULT_TTL_MS = 3_600_000; // 1 hour
 
 type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
+export type PaymentNotification = { model: string; amount: string; network: string };
+
 export function createPayFetchWithPreAuth(
   baseFetch: FetchFn,
   client: x402Client,
   ttlMs = DEFAULT_TTL_MS,
-  options?: { skipPreAuth?: boolean; estimateAmount?: EstimateFn },
+  options?: {
+    skipPreAuth?: boolean;
+    estimateAmount?: EstimateFn;
+    onPayment?: (info: PaymentNotification) => void;
+  },
 ): FetchFn {
   const httpClient = new x402HTTPClient(client);
   const cache = new Map<string, CachedEntry>();
@@ -92,6 +98,28 @@ export function createPayFetchWithPreAuth(
     }
     const cacheKey = `${urlPath}:${requestModel}`;
 
+    const notifyAcceptedPayment = (
+      response: Response,
+      payload: { accepted: { amount: string; network: string } },
+    ): void => {
+      const settled =
+        response.headers.has("payment-response") || response.headers.has("x-payment-response");
+      if (!settled || !options?.onPayment) return;
+      try {
+        options.onPayment({
+          model: requestModel,
+          amount: payload.accepted.amount,
+          network: payload.accepted.network,
+        });
+      } catch (error) {
+        // The observer runs after settlement. Its failure must not turn a paid
+        // response into a retryable request and risk a second charge.
+        console.error(
+          `[ClawRouter] onPayment callback failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    };
+
     // Up-front estimate of what THIS request will cost (USDC micro-units), used
     // both to gate pre-auth reuse and to record what a new cache entry covers.
     const estimateMicros = (): number | undefined => {
@@ -132,6 +160,7 @@ export function createPayFetchWithPreAuth(
         paymentInFlight = true;
         const response = await baseFetch(preAuthRequest);
         if (response.status !== 402) {
+          notifyAcceptedPayment(response, payload);
           return response; // Pre-auth worked — saved ~200ms
         }
         // Rejected despite our estimate (server priced it higher than we did).
@@ -200,6 +229,8 @@ export function createPayFetchWithPreAuth(
     for (const [key, value] of Object.entries(paymentHeaders)) {
       clonedRequest.headers.set(key, value);
     }
-    return baseFetch(clonedRequest);
+    const paidResponse = await baseFetch(clonedRequest);
+    notifyAcceptedPayment(paidResponse, payload);
+    return paidResponse;
   };
 }

src/proxy.ts

@@ -2560,6 +2560,10 @@ export async function startProxy(options: ProxyOptions): Promise<ProxyHandle> {
           // payment still covers the (possibly larger) request — BlockRun prices per
           // token, so one model can cost different amounts across requests.
           estimateAmount,
+          // Only the wallet rail settles per call. The API-key rail is billed
+          // server-side against account credit, so there is no per-request
+          // settlement for an observer to report.
+          onPayment: options.onPayment,
         });
 
   // Create balance monitor for pre-request checks (lazy import to avoid loading @solana/kit on Base chain)