feat(typescript): add support for x402:upto + revisit playground

[lgalabru]

No description provided.

[greptile-apps]

Greptile Summary

This PR adds x402:upto (usage-based metered payment) support to the TypeScript SDK — a new X402Upto adapter, a Charge meter, and GateKind extensions for usage, subscription, and session gates — alongside a revamped playground. The settle-memoization and concurrent-replay guard issues from previous review rounds are addressed.

• x402-upto.ts: New Charge meter class (clamps, floors negatives) and X402Upto engine (verifyOpen / settle) with in-flight channel dedup via inFlightUptoChannels.
• gate.ts / pricing.ts: Added GateKind enum and usage(), subscription(), session() factory helpers; Gate.create now validates kind-specific constraints at boot time.
• paykit.ts: Two settle-failure paths for usage gates remain inconsistently guarded: runBufferedSettle (Express) discards the buffered handler response and returns a 402 on settle error, while the fetch success path has no guard around withSettlement() throwing — both behave differently from the Hono path that swallows settle failures and preserves the handler response.

Confidence Score: 4/5

Safe to merge with caution — two settle-failure paths in paykit.ts behave inconsistently across frameworks for usage gates.

The new X402Upto adapter, Charge meter, and gate validation are solid. The concurrency and double-settlement issues from earlier rounds are fixed. However, when the on-chain settle call fails transiently in the Express path, the buffered handler response is thrown away and the client receives an empty 402 — the opposite of what happened. The fetch success path has the same gap: withSettlement() can propagate a settle exception and lose the response. Both paths affect only usage (upto) gates but the consequences are visible to end users.

typescript/packages/pay-kit/src/paykit.ts — specifically the runBufferedSettle catch block (lines 808–821) and the fetch withSettlement call (line 626).

Important Files Changed

Filename	Overview
typescript/packages/pay-kit/src/adapters/x402-upto.ts	New usage-based x402 upto adapter: Charge meter, verifyOpen, and settle with memoization and in-flight dedup. Logic looks sound.
typescript/packages/pay-kit/src/paykit.ts	Core orchestration extended for usage/subscription/session gates. Two settle-failure paths — Express runBufferedSettle discards the handler response and sends a misleading 402; fetch success path is unguarded against withSettlement throwing.
typescript/packages/pay-kit/src/gate.ts	Added GateKind, SessionConfig, SubscriptionConfig, FeeSpec; validation rules for usage/subscription/session gates. Clean.
typescript/packages/pay-kit/src/pricing.ts	Added usage(), subscription(), session() helper factories plus PricingDef type; createPricing updated to handle bare Price values. No issues.
typescript/packages/pay-kit/src/config.ts	x402 added to accepted protocols; challengeBindingSecret now optional when MPP is not in accept; html flag added to MppOptions. Clean.
typescript/packages/pay-kit/src/tests/usage.test.ts	New test file covering gate validation and challenge shape for usage gates. Settle-failure paths are not tested.
.github/workflows/npm-publish.yml	Added publish-pay-kit job; vendored x402 tarballs are used for frozen install. No issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    REQ[Incoming Request] --> RP[requirePayment]
    RP --> KIND{Gate Kind}

    KIND -- fixed --> RF[requireFixed]
    KIND -- usage --> RU[requireUsage]
    KIND -- session --> RS[requireSession]
    KIND -- subscription --> RF

    RF -- no credential --> D402[PaymentDenied 402]
    RF -- valid --> VS[verifyAndSettle]
    VS --> FG[granted: settle = resolved headers]

    RU -- no header --> U402[PaymentDenied 402]
    RU -- has header --> VO[upto.verifyOpen - escrows ceiling on-chain]
    VO --> DEDUP{channelId in-flight?}
    DEDUP -- yes --> U402
    DEDUP -- no --> METER[new Charge meter + settlePromise memoized]
    METER --> UG[granted: settle = upto.settle + cleanup]

    RS --> SE[sessionEngine.handler]
    SE -- 402 --> D402
    SE -- open --> SG[granted: settle = receipt headers]

    FG & UG & SG --> FW{Framework}
    FW -- fetch --> FH[handler runs then withSettlement response]
    FW -- hono --> HH[next then finally settle best-effort]
    FW -- express --> EH[runBufferedSettle buffer settle replay]

    FH -. settle throws .-> FERR[exception propagates]
    EH -. settle throws .-> EERR[402 sent buffer discarded]
    HH -. settle throws .-> HOK[swallowed response preserved]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    REQ[Incoming Request] --> RP[requirePayment]
    RP --> KIND{Gate Kind}

    KIND -- fixed --> RF[requireFixed]
    KIND -- usage --> RU[requireUsage]
    KIND -- session --> RS[requireSession]
    KIND -- subscription --> RF

    RF -- no credential --> D402[PaymentDenied 402]
    RF -- valid --> VS[verifyAndSettle]
    VS --> FG[granted: settle = resolved headers]

    RU -- no header --> U402[PaymentDenied 402]
    RU -- has header --> VO[upto.verifyOpen - escrows ceiling on-chain]
    VO --> DEDUP{channelId in-flight?}
    DEDUP -- yes --> U402
    DEDUP -- no --> METER[new Charge meter + settlePromise memoized]
    METER --> UG[granted: settle = upto.settle + cleanup]

    RS --> SE[sessionEngine.handler]
    SE -- 402 --> D402
    SE -- open --> SG[granted: settle = receipt headers]

    FG & UG & SG --> FW{Framework}
    FW -- fetch --> FH[handler runs then withSettlement response]
    FW -- hono --> HH[next then finally settle best-effort]
    FW -- express --> EH[runBufferedSettle buffer settle replay]

    FH -. settle throws .-> FERR[exception propagates]
    EH -. settle throws .-> EERR[402 sent buffer discarded]
    HH -. settle throws .-> HOK[swallowed response preserved]

Loading

_{Reviews (7): Last reviewed commit: "fix(pay-kit): re-render the html payment..." | Re-trigger Greptile}

[greptile-apps]

Synchronous next() throw skips settlement, leaving the upto channel open

If the downstream Express handler throws synchronously (instead of propagating through next(err)), the catch block calls restoreAndReplay() and re-invokes next(error) — but settle() is never reached. At this point verifyOpen has already broadcast the channel open on-chain (escrowing the ceiling), so skipping settlement leaves the channel in an unfinalized state without a refund. The comment on line 709 ("Settle even on a handler error") documents the intent to always finalize, but the synchronous-throw path violates it. A finally block wrapping the await ended → settle() sequence would ensure settlement is always attempted.

[lgalabru]

Fixed in 461cce8 — the synchronous-throw path now attempts result.settle() (best-effort; the meter is 0 so it refunds the escrowed ceiling) before forwarding the error via next(error), instead of returning early and leaking the open channel.

[greptile-apps]

Settlement skipped when Hono handler throws for usage gates

await next() is called without any error guard before result.settle(). If the downstream Hono handler rejects (throws asynchronously), execution exits the async function immediately and result.settle() is never reached. Because verifyOpen already broadcast the channel open on-chain — escrowing the ceiling — the upto channel stays open with the user's funds locked indefinitely. Wrapping the next() + settle sequence in a try/finally would guarantee settlement is always attempted, mirroring the intent documented in runBufferedSettle for the Express path.

[lgalabru]

Fixed in 461cce8 — wrapped await next() in try/finally so result.settle() always runs, finalizing the channel even when the Hono handler throws.

[greptile-apps]

Usage-gate channel left open when fetch handler throws

For a usage (upto) gate, requireUsage calls upto.verifyOpen() before returning, which broadcasts the channel open on-chain and escrows the ceiling. If handler then throws, result.withSettlement (and thus result.settle()) is never reached, leaving the channel open indefinitely with the payer's funds locked. The Express and Hono paths both protect against this in the same commit (Express via try/catch around next(), Hono via try/finally), but the fetch wrapper has no equivalent guard.

A try/finally around handler(...) would close the channel even on errors, matching the intent documented in runBufferedSettle:

let response: Response;
try {
    response = await handler(request, result.payment);
} catch (error) {
    // Best-effort: finalize the upto channel (meter is 0 → refunds the ceiling).
    try { await result.settle(); } catch { /* swallow; re-throw original error */ }
    throw error;
}
return await result.withSettlement(response);

[lgalabru]

Fixed in d7c50be — the fetch wrapper now wraps the handler in try/catch and finalizes the upto channel (best-effort result.settle()) before re-throwing, matching the express + hono paths.

[lgalabru]

Already addressed in d7c50be (the line numbers shifted with later commits). The fetch wrapper now wraps handler(...) in try/catch and best-effort result.settle()s before re-throwing — see the current code at this location.

[greptile-apps]

Settlement failure in finally block can propagate as an unhandled exception

For a usage (upto) gate, result.settle() makes an on-chain network call (upto.settle()) that can throw on a transient RPC failure. In the finally block, an uncaught exception from result.settle() has two bad outcomes:

• Success path: next() returned normally, the handler's response is ready, but the settle error now propagates out of the middleware — Hono returns a 500 instead of the handler's response, even though the request was served correctly.
• Error path: next() threw, the finally settle error replaces the original handler error, making the failure harder to diagnose.

For fixed and session gates settle() returns Promise.resolve(...) and cannot throw, so this is exclusive to upto gates. Wrapping the block in a try/catch (and logging or swallowing the settle error) would match the pattern used in the Express sync-throw path on lines 744–747.

[lgalabru]

Fixed in d7c50be — the hono finally now runs result.settle() inside its own try/catch, so a transient settle (RPC) failure is swallowed and cannot mask the handler response (success) or the original error (throw).

[lgalabru]

Already addressed in d7c50be. The hono finally now runs result.settle() inside its own try/catch, so a transient settle failure is swallowed and cannot mask the handler response or the original error.

[greptile-apps]

Settle failure discards valid handler response and returns an empty 402

When result.settle() throws after await ended (handler already ran, response buffered), the catch block sets bufferedCalls = [] and calls originalEnd() with res.statusCode = 402. This discards the buffered handler body entirely and tells the client "payment required" for a resource it already paid for and received — the inverse of what happened. A transient RPC error during settlement should not override a successful 200 handler response.

The Hono path explicitly swallows settle failures and preserves the handler outcome. The Express path should do the same: call restoreAndReplay() (without the settlement header) instead of discarding bufferedCalls.

[greptile-apps]

Settle failure on the handler-success path loses the response in the fetch wrapper

On the handler-error path (lines 615–624), result.settle() is called best-effort and any settle error is swallowed before re-throwing the original error. But on the handler-success path, result.withSettlement(response) calls settle() without any guard: if a transient RPC failure causes settle() to reject, the exception propagates out of the async function and the client receives a 500 (or an unhandled rejection) even though the handler produced a valid response. For usage (upto) gates this is a live failure path; fixed gates' settle() always resolves.

The fix is to wrap result.withSettlement(response) in a try/catch that returns response unchanged if settle fails — consistent with the Hono finally path that swallows settle errors to preserve the handler outcome.