fareql 0.1.1 → 0.1.2

package/README.md

@@ -1,34 +1,46 @@
-# FareQL
+<h1 align="center">FareQL</h1>
 
-[![npm](https://img.shields.io/npm/v/fareql)](https://www.npmjs.com/package/fareql)
-[![ci](https://github.com/Bruce039/fareql/actions/workflows/ci.yml/badge.svg)](https://github.com/Bruce039/fareql/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/fareql)](https://github.com/Bruce039/fareql/blob/main/LICENSE)
+<p align="center">
+  <b>Every GraphQL query pays its own fare.</b><br>
+  Price each operation by what it selects and charge for it over <a href="https://mpp.dev">MPP</a> (HTTP 402).
+</p>
 
-Charge for GraphQL operations over [MPP](https://mpp.dev) (HTTP 402), priced by what each operation selects.
+<p align="center">
+  <a href="https://www.npmjs.com/package/fareql"><img src="https://img.shields.io/npm/v/fareql?color=ffcb3d&labelColor=24211b" alt="npm"></a>
+  <a href="https://github.com/Bruce039/fareql/actions/workflows/ci.yml"><img src="https://github.com/Bruce039/fareql/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
+  <a href="https://github.com/Bruce039/fareql/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/fareql?color=1f9d74&labelColor=24211b" alt="license"></a>
+  <img src="https://img.shields.io/badge/graphql-16%20%7C%2017-e535ab?labelColor=24211b" alt="graphql 16 | 17">
+</p>
 
-A GraphQL API is one endpoint, so a flat price per route doesn't fit it: `{ hello }` and `{ users(first: 100) { edges { node { email } } } }` hit the same URL. FareQL works out the fare of every operation from your schema and charges it through [`mppx`](https://github.com/wevm/mppx) with Tempo, Stripe or any other MPP method.
+<p align="center">
+  <a href="https://fareql.pages.dev"><b>Live demo</b></a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#pricing-rules">Pricing rules</a> ·
+  <a href="#security-model">Security</a>
+</p>
 
-- **Schema-driven prices.** `@price(amount: "0.001")` on fields and types, multiplied through lists, Relay connections and `@listSize`.
-- **One Challenge per operation**, bound to the exact document and variables. A Credential paid for a cheap query can't be replayed on an expensive one; mppx enforces this through the Challenge's HMAC.
-- **Charged after validation, right before execution.** Persisted queries and depth limits are already applied when FareQL charges, so nobody pays for an operation the server then refuses.
-- **Fails closed.** If FareQL can't read or price an operation, the operation doesn't run.
-- **Ready for GraphQL clients.** The 402 keeps mppx's `WWW-Authenticate` Challenge and adds a GraphQL `errors` entry with the price and its breakdown.
-- Works with **GraphQL Yoga**, **Apollo Server 4/5** and **any Fetch-API handler**, on graphql 16 and 17.
+> **Try it in the browser at [fareql.pages.dev](https://fareql.pages.dev).** Type a query and the meter quotes it live. Pay with a demo method and you get the data and a receipt. No money moves.
+> Shortcuts: [pay for a search](https://fareql.pages.dev/#ride=2&pay) · [slide a page size](https://fareql.pages.dev/#ride=7) · [try to ride for free](https://fareql.pages.dev/#dodge=0)
 
-```bash
-npm install fareql mppx graphql
-```
+## Why FareQL
 
-## How it works
+A GraphQL API is one endpoint, so a flat price per route doesn't fit it: `{ hello }` and `{ users(first: 100) { edges { node { email } } } }` hit the same URL. FareQL works out the fare of every operation from your schema and charges it through [`mppx`](https://github.com/wevm/mppx) with Tempo, Stripe or any other MPP method. Clients (apps, scripts, AI agents) pay per question. They don't need an account, an API key or a plan, and the money goes straight to your address.
 
-1. You mark what costs money in your schema: `@price(amount: "0.001")`.
-2. A client sends a query. FareQL prices it from what it selects. Free operations run as usual.
-3. A priced operation gets `402 Payment Required` with an MPP Challenge for that exact operation, plus the price and its breakdown.
-4. The client (an app, the `mppx` CLI, an AI agent) pays, for example in stablecoins on Tempo, and resends the query with the Credential. FareQL verifies it through mppx, runs the operation, and returns the data with a `Payment-Receipt`.
+| | |
+|---|---|
+| **Schema-driven prices** | `@price(amount: "0.001")` on fields and types, multiplied through lists, Relay connections and `@listSize` |
+| **One Challenge per operation** | Bound to the exact document and variables. A Credential for a cheap query can't pay for an expensive one |
+| **Charged after validation** | Persisted queries and depth limits run first, so nobody pays for an operation the server refuses |
+| **Fails closed** | If FareQL can't read or price an operation, the operation doesn't run |
+| **Red-teamed** | About 100 attack tests: parser differentials, cache bypasses, fragment bombs, scope collisions |
+| **Works where you are** | GraphQL Yoga, Apollo Server 4/5 and any Fetch handler (Hono, Next.js, Workers), on graphql 16 and 17 |
 
-Payments go straight to your own address. There is no account, API key or subscription for the client to set up.
+## Quick start
 
-## GraphQL Yoga
+```bash
+npm install fareql mppx graphql
+```
 
 ```ts
 import { createSchema, createYoga } from 'graphql-yoga'
@@ -60,11 +72,25 @@ const yoga = createYoga({
 
 `{ hello }` is free. `{ search(query: "mpp", first: 2) { snippet } }` costs `2 × (0.0005 + 0.0002) = 0.0014`.
 
-Register `useFareql` after plugins that change what runs (APQ, persisted operations, validation rules). It hooks into execution, so it always prices the final document. A backstop before each response charges results that never reached execution, so a response cache (`useResponseCache`) or a plugin that short-circuits cannot serve a priced result for free.
+## How it works
+
+1. **You price your schema.** Put `@price(amount: "0.001")` on whatever costs money.
+2. **A client asks.** FareQL prices the operation from what it selects. Free operations run as usual.
+3. **It gets a quote.** A priced operation answers `402 Payment Required` with an MPP Challenge for that exact operation, plus the price and its breakdown.
+4. **It pays and asks again.** The client (an app, the `mppx` CLI, an AI agent) pays, for example in stablecoins on Tempo, and resends the query with the Credential.
+5. **It gets the answer.** FareQL verifies the Credential through mppx, runs the operation and returns the data with a `Payment-Receipt`.
+
+## Use it with your server
 
-Yoga-only options: `getRequest(context)` supplies the HTTP request for transports that have none (graphql-ws); without it, priced operations over such transports are refused. `maxSubscriptionEvents` (default 100) is how many events one payment buys on a priced subscription; the stream then ends with `PAYMENT_EXHAUSTED`.
+### GraphQL Yoga
 
-## Apollo Server
+Shown in [Quick start](#quick-start). Register `useFareql` after plugins that change what runs (APQ, persisted operations, validation rules). It hooks into execution, so it always prices the final document. A backstop before each response charges results that never reached execution, so a response cache or a plugin that short-circuits can't serve a priced result for free.
+
+Yoga-only options:
+- `getRequest(context)` supplies the HTTP request for transports that have none, such as graphql-ws. Without it, priced operations over those transports are refused.
+- `maxSubscriptionEvents` (default 100) is how many events one payment buys on a priced subscription.
+
+### Apollo Server
 
 ```ts
 import { ApolloServer } from '@apollo/server'
@@ -77,9 +103,9 @@ const server = new ApolloServer({
 })
 ```
 
-The plugin charges in `didResolveOperation`, after Apollo has parsed, validated and resolved the operation, APQ included, and before Apollo's response cache can answer. In an HTTP batch only one priced operation can be paid. Operations you run in-process with `server.executeOperation()` have no HTTP request and are not charged.
+The plugin charges in `didResolveOperation`. By then Apollo has parsed, validated and resolved the operation (APQ included), and its response cache hasn't answered yet. In an HTTP batch only one priced operation can be paid. Operations run in-process with `server.executeOperation()` have no HTTP request and are not charged.
 
-## Any Fetch handler (Hono, Next.js, graphql-http, Cloudflare Workers)
+### Any Fetch handler (Hono, Next.js, graphql-http, Cloudflare Workers)
 
 ```ts
 import { withPayment } from 'fareql'
@@ -87,19 +113,19 @@ import { withPayment } from 'fareql'
 export const POST = withPayment((req) => handler(req), { schema, charge: (o) => mppx.charge(o) })
 ```
 
-`withPayment` reads the request itself, so it is strict about anything the wrapped handler could read differently:
+`withPayment` reads the request itself, so it refuses anything the wrapped handler could read differently:
 
-- It accepts GET and `application/json` POST by default. Enable `application/graphql`, `application/graphql+json`, form-urlencoded or multipart uploads with `encodings: [...]`, and only if your handler accepts them, so a client is never charged for a body the handler then refuses.
-- It refuses the following with 4xx before anything is charged:
-  - URL fragments (`#`), duplicate or unknown parameters, and GraphQL parameters in the URL of a POST;
+- It accepts GET and `application/json` POST by default. Enable `application/graphql`, `application/graphql+json`, form-urlencoded or multipart uploads with `encodings: [...]`, but only if your handler accepts them too.
+- It refuses the following with a 4xx before anything is charged:
+  - URL fragments, duplicate or unknown parameters, and GraphQL parameters in a POST URL;
   - non-object `variables`, and `query` sent together with `documentId`;
   - bodies on other methods, and mutations over GET.
-- `maxBodyBytes` (default 1 MB), `maxQueryLength` (100 000), `maxTokens` (15 000) and `maxBatchSize` (10) bound the work.
-- `validationRules` adds your server's extra rules (depth limits and so on), so operations they reject are refused before payment.
-- It speaks APQ: a hash it hasn't seen gets `PersistedQueryNotFound`, the client resends the full query, and that query is priced. For trusted documents (`documentId`), pass `resolveDocument`.
-- Batches are refused unless you set `batching: true`; then the whole batch is charged in one payment, and `maxPrice` applies to the total.
+- `maxBodyBytes` (1 MB), `maxQueryLength` (100 000), `maxTokens` (15 000) and `maxBatchSize` (10) bound the work.
+- `validationRules` adds your server's extra rules, so operations they would reject are refused before payment.
+- APQ works without a hash store in the gate: a hash-only request gets `PersistedQueryNotFound` and the full query the client resends is priced, so nobody pays for a hash the handler doesn't know. To price hashes or trusted documents (`documentId`) from your own store, pass `resolveDocument`.
+- Batches are refused unless you set `batching: true`. With it, the whole batch is charged in one payment and `maxPrice` applies to the total.
 
-For full control, `createPaymentGate(options)(request)` returns `free`, `payment-required` (with the 402 `response`), `paid` (with `withReceipt`) or `rejected` (with the response to send).
+For full control, `createPaymentGate(options)(request)` returns one of `free`, `payment-required`, `paid` or `rejected`.
 
 ## Pricing rules
 
@@ -107,27 +133,31 @@ For full control, `createPaymentGate(options)(request)` returns `free`, `payment
 |---|---|
 | Field `@price` | Charged once per resolved instance of the field |
 | Type `@price` | Applies to every field returning that type, unless the field has its own |
-| Field selected several times | Charged once per response key, as the executor resolves it (fragments merged, repeated spreads ignored) |
-| Lists | Children × list size, read from `first`, `last`, `limit`, `take`, `top`, `pageSize` or `perPage` (also one level inside an input object, e.g. `page: { limit }`); otherwise `defaultListSize` (10). Capped at `maxListSize` (100). `null` or an unbounded number counts as `maxListSize`; a negative size is refused (`INVALID_LIST_SIZE`) |
+| Field selected several times | Charged once per response key, as the executor resolves it |
+| Lists | Children × list size from `first`, `last`, `limit`, `take`, `top`, `pageSize` or `perPage` (also inside an input object, e.g. `page: { limit }`), otherwise `defaultListSize` (10). Capped at `maxListSize` (100). `null` or unbounded counts as `maxListSize`; negative sizes are refused |
 | Nested lists | `[[Cell]]`: each inner level multiplies by `defaultListSize` |
-| Connections and page wrappers | A non-list field given a size (`users(first: 50)`) passes it to the lists it selects (`edges`, `nodes`, `items`…). Restrict with `connections: { sizedFields }` or turn off with `false` |
-| `@listSize` | As in the IBM GraphQL Cost Directives draft: `slicingArguments`, `sizedFields`, `assumedSize`, `requireOneSlicingArgument` (default true) |
-| Interfaces and unions | Each possible runtime type is priced and the most expensive one is charged. Branches are never added together. `@price` on an interface field or interface type applies to the types implementing it |
-| Code-first schemas | `extensions: { price: '0.001' }` or `extensions: { directives: { price: { amount: '0.001' } } }` work like the directive |
+| Connections and page wrappers | A non-list field given a size (`users(first: 50)`) passes it to the lists it selects (`edges`, `nodes`, `items`…). Restrict with `connections: { sizedFields }`, or turn it off with `false` |
+| `@listSize` | As in the IBM GraphQL Cost Directives draft: `slicingArguments`, `sizedFields`, `assumedSize`, `requireOneSlicingArgument` |
+| Interfaces and unions | Every possible runtime type is priced and the most expensive one is charged. A `@price` on an interface field or type applies to its implementations |
+| Code-first schemas | `extensions: { price: '0.001' }` or `extensions: { directives: { price: { amount: '0.001' } } }` |
 | Fragments, `@skip`, `@include` | Followed and evaluated with the request variables |
 | `__typename`, introspection | Free |
-| `maxPrice` | Operations above it get `PRICE_LIMIT_EXCEEDED` before any Challenge is issued |
-| `maxFieldVisits`, `maxDepth` | Operations too complex to price get `TOO_COMPLEX` (defaults 10 000 selections, 100 levels) |
-| No price anywhere | A schema without any `@price` (lost directives, an introspection copy) is refused with `NO_PRICES` instead of making everything free |
+| `maxPrice` | Operations above it get `PRICE_LIMIT_EXCEEDED` before any Challenge |
+| `maxFieldVisits`, `maxDepth` | Operations too complex to price get `TOO_COMPLEX` (10 000 selections, 100 levels) |
+| No price anywhere | A schema with no `@price` at all (e.g. one that lost its directives) is refused with `NO_PRICES` instead of making everything free |
+
+Other options:
+- `decimals` (default 6) must match your payment method's token.
+- `defaultFieldPrice`, `listSizeArguments`, `connections`.
+- `fieldPrice(ctx)` prices fields in code.
 
-Other options: `decimals` (default 6, which must match your payment method's token), `defaultFieldPrice`, `listSizeArguments`, `connections` (`false` or `{ sizedFields }`), and `fieldPrice(ctx)` to price fields in code. `priceOperation()` is exported for quotes and tests. The breakdown lists at most 100 items (`breakdownTruncated: true` when there are more).
+`priceOperation()` is exported for quotes and tests.
 
 ## What clients get
 
 ```http
 HTTP/1.1 402 Payment Required
 WWW-Authenticate: Payment id="…", realm="api.example.com", method="tempo", intent="charge", request="…"
-Cache-Control: no-store
 Content-Type: application/json; charset=utf-8
 
 {
@@ -137,7 +167,6 @@ Content-Type: application/json; charset=utf-8
       "code": "PAYMENT_REQUIRED",
       "price": {
         "amount": "0.0014",
-        "decimals": 6,
         "breakdown": [
           { "path": "search", "unitAmount": "0.0005", "count": "2", "amount": "0.001" },
           { "path": "search.snippet", "unitAmount": "0.0002", "count": "2", "amount": "0.0004" }
@@ -156,17 +185,20 @@ npx mppx https://api.example.com/graphql -X POST -H 'content-type: application/j
   -d '{"query":"{ search(query: \"mpp\", first: 2) { snippet } }"}'
 ```
 
-In code, `mppx/client` wraps `fetch` so 402s are paid and retried automatically, and MPP-aware agents do the same. The paid response carries `Payment-Receipt` and `Cache-Control: private` (or `private, no-store`), so no shared cache or CDN stores paid content. Set `exposePrice: false` to leave the price out of every error body.
+In code, `mppx/client` wraps `fetch`, so 402s are paid and retried automatically. The paid response carries a `Payment-Receipt` and `Cache-Control: private`, so shared caches never store paid content. Set `exposePrice: false` to keep prices out of error bodies.
 
 ## Security model
 
-- **Binding.** Each Challenge's `scope` is a hash of the printed document, the operation name and the declared variables. mppx keeps it in the HMAC-protected Challenge and refuses a Credential whose scope differs. A payment for one operation never unlocks another.
-- **Price what runs.** Yoga and Apollo are charged after the server's own parsing, validation and persisted-document lookup. `withPayment` refuses requests a handler could parse differently.
-- **Fail closed.** Unreadable, unpriceable, over-limit or ambiguous requests are answered with an error and never executed. Batches can't hold more than one paid operation per Credential.
-- **Bounded work.** Pricing is linear in the document, like graphql-js field collection. Token, length, depth, selection, body and batch limits keep it cheap.
-- **Tested by attack.** [`test/attacks-*.test.ts`](https://github.com/Bruce039/fareql/tree/main/test) hold the red-team suites: pricing tricks, parser differentials, cache and plugin-order bypasses, scope collisions and DoS. Each test asserts the secure behaviour.
+- **Binding.** Each Challenge's `scope` is a hash of the printed document, the operation name and the declared variables. mppx keeps it in the HMAC-protected Challenge and refuses a Credential whose scope differs.
+- **Price what runs.** Yoga and Apollo charge after the server's own parsing, validation and persisted-document lookup. `withPayment` refuses requests a handler could parse differently.
+- **Fail closed.** Unreadable, unpriceable, over-limit or ambiguous requests are answered with an error and never run.
+- **Bounded work.** Pricing is linear in the document, like graphql-js field collection. Token, length, depth, body and batch limits keep it cheap.
+- **Tested by attack.** [`test/attacks-*.test.ts`](https://github.com/Bruce039/fareql/tree/main/test) hold the red-team suites. Each test asserts the secure behaviour.
 
-## Shared options
+## Reference
+
+<details>
+<summary><b>Shared options</b></summary>
 
 | Option | |
 |---|---|
@@ -175,31 +207,28 @@ In code, `mppx/client` wraps `fetch` so 402s are paid and retried automatically,
 | `describe(op, price)` | Challenge description. Default: `GraphQL <operation name>` |
 | `exposePrice` | Include the price breakdown in 402 bodies. Default: `true` |
 
-## Notes
+</details>
+
+<details>
+<summary><b>Notes and limits</b></summary>
 
-- Payment settles before execution, so a resolver error after payment is not refunded. Keep priced resolvers reliable, or price them lower.
+- Payment settles before execution, so a resolver error after payment is not refunded. Keep priced resolvers reliable.
 - Subscriptions are charged once, when they start, for up to `maxSubscriptionEvents` events. Metered streams over MPP sessions are planned.
-- Set `maxListSize` to your server's real page cap. A larger requested size is clamped, so a server that returns more items than `maxListSize` is under-charged.
-- With Yoga, priced operations can't share a batch, because one request carries one Credential. Free operations in a batch work as usual.
-- In production, give `tempo.charge()` a shared `store` so a Credential can't be replayed across instances. This is an mppx setting.
+- Set `maxListSize` to your server's real page cap. If the server returns more items than `maxListSize`, the client is under-charged, because larger requested sizes are clamped.
+- In production, give `tempo.charge()` a shared `store` so a Credential can't be replayed across instances.
 
-## Examples
+</details>
 
-- [`examples/yoga-tempo`](https://github.com/Bruce039/fareql/blob/main/examples/yoga-tempo/server.ts): GraphQL Yoga on Tempo's Moderato testnet
-- [`examples/apollo-tempo`](https://github.com/Bruce039/fareql/blob/main/examples/apollo-tempo/server.ts): Apollo Server with a priced Relay-style connection
-- [`examples/playground`](https://github.com/Bruce039/fareql/blob/main/examples/playground/server.ts): a local page that walks through quote → Challenge → Credential → Receipt. It uses a settlement-free demo method by default (`npx tsx examples/playground/server.ts`, then open http://localhost:4000), and real Moderato Challenges when `RECIPIENT` and `MPP_SECRET_KEY` are set
+## Examples
 
-```bash
-MPP_SECRET_KEY=$(openssl rand -hex 32) RECIPIENT=0x… npx tsx examples/yoga-tempo/server.ts
-npx mppx account create && npx mppx account fund
-npx mppx http://localhost:4000/graphql -X POST -H 'content-type: application/json' \
-  -d '{"query":"{ search(query: \"tempo\", first: 3) { title snippet } }"}'
-```
+- [`examples/playground`](https://github.com/Bruce039/fareql/tree/main/examples/playground): the [live demo](https://fareql.pages.dev). Run it locally with `npx tsx examples/playground/server.ts`; set `RECIPIENT` and `MPP_SECRET_KEY` for real Moderato testnet Challenges.
+- [`examples/yoga-tempo`](https://github.com/Bruce039/fareql/blob/main/examples/yoga-tempo/server.ts): a minimal GraphQL Yoga server on Moderato.
+- [`examples/apollo-tempo`](https://github.com/Bruce039/fareql/blob/main/examples/apollo-tempo/server.ts): Apollo Server with a priced Relay-style connection.
 
 ## Development
 
 ```bash
-npm test          # vitest: pricing, gate, Yoga, Apollo, and real mppx client ↔ server loops
+npm test                                  # pricing, gate, Yoga, Apollo, attacks, real mppx loops
 npm run build && node scripts/smoke.mjs   # the built package over real HTTP in plain Node
 ```
 

package/dist/apollo.js

@@ -47,16 +47,18 @@ export function fareqlApolloPlugin(options) {
                     if (!http)
                         return;
                     const input = { document: rc.document, operationName: rc.operationName ?? rc.request.operationName, variables: rc.request.variables };
-                    let units;
+                    let price;
                     try {
-                        units = priceOperation({ schema: rc.schema, ...input }, options.pricing).units;
+                        price = priceOperation({ schema: rc.schema, ...input }, options.pricing);
                     }
                     catch (e) {
-                        if (e instanceof PricingError)
-                            throw fail(e.message, pricingErrorBody(e, exposePrice).extensions, 400);
+                        if (e instanceof PricingError) {
+                            const body = pricingErrorBody(e, exposePrice);
+                            throw fail(body.message, body.extensions, 400);
+                        }
                         throw e;
                     }
-                    if (units === 0n)
+                    if (price.units === 0n)
                         return;
                     // Counted synchronously, before any await, so parallel batch pieces cannot race past it.
                     const n = (pricedPieces.get(http.headers) ?? 0) + 1;
@@ -64,7 +66,7 @@ export function fareqlApolloPlugin(options) {
                     if (n > 1) {
                         throw fail('Priced operations cannot be batched; send them one per request', { code: 'BATCHING_NOT_SUPPORTED' }, 400);
                     }
-                    const outcome = await chargeOperations(toFetchRequest(http, options.url), rc.schema, [input], options);
+                    const outcome = await chargeOperations(toFetchRequest(http, options.url), rc.schema, [input], options, [price]);
                     switch (outcome.status) {
                         case 'free':
                             return;

package/dist/core.d.ts

@@ -75,7 +75,9 @@ export declare function operationScope(operations: readonly OperationInput[]): P
  * Apollo) goes through here. The price is recomputed from the retried request, so a Credential
  * for a cheaper operation never pays for a more expensive one.
  */
-export declare function chargeOperations(request: Request, schema: GraphQLSchema, operations: readonly OperationInput[], options: FareOptions): Promise<ChargeOutcome>;
+export declare function chargeOperations(request: Request, schema: GraphQLSchema, operations: readonly OperationInput[], options: FareOptions, 
+/** Prices already computed for `operations` (same order), to avoid pricing them twice. */
+precomputed?: readonly OperationPrice[]): Promise<ChargeOutcome>;
 export type GraphQLErrorBody = {
     message: string;
     extensions: Record<string, unknown>;

package/dist/core.js

@@ -77,12 +77,16 @@ function sumPrices(prices, decimals) {
  * Apollo) goes through here. The price is recomputed from the retried request, so a Credential
  * for a cheaper operation never pays for a more expensive one.
  */
-export async function chargeOperations(request, schema, operations, options) {
+export async function chargeOperations(request, schema, operations, options, 
+/** Prices already computed for `operations` (same order), to avoid pricing them twice. */
+precomputed) {
     const decimals = options.pricing?.decimals ?? 6;
     let price;
     let info;
     try {
-        const prices = operations.map((o) => priceOperation({ schema, ...o }, options.pricing));
+        const prices = precomputed && precomputed.length === operations.length
+            ? precomputed
+            : operations.map((o) => priceOperation({ schema, ...o }, options.pricing));
         price = sumPrices(prices, decimals);
         const max = options.pricing?.maxPrice;
         if (max !== undefined && price.units > parseUnits(max, decimals))
@@ -173,7 +177,8 @@ export function receiptHeaders(withReceipt) {
 const CACHEABLE_QUERY_LENGTH = 32_768;
 /** Small LRU of parse + validate results. Only short queries are cached, so memory stays bounded. */
 export function createDocumentCache(limits = {}, max = 1000) {
-    const entries = new Map();
+    // Validation depends on the schema, so results are cached per schema (Yoga can swap schemas).
+    const bySchema = new WeakMap();
     const maxQueryLength = limits.maxQueryLength ?? 100_000;
     const maxTokens = limits.maxTokens ?? 15_000;
     const rules = limits.validationRules ? [...specifiedRules, ...limits.validationRules] : undefined;
@@ -182,6 +187,11 @@ export function createDocumentCache(limits = {}, max = 1000) {
             if (query.length > maxQueryLength) {
                 return { errors: [new GraphQLErrorClass(`Query is longer than ${maxQueryLength} characters`)] };
             }
+            let entries = bySchema.get(schema);
+            if (!entries) {
+                entries = new Map();
+                bySchema.set(schema, entries);
+            }
             const hit = entries.get(query);
             if (hit) {
                 entries.delete(query);
@@ -205,7 +215,7 @@ export function createDocumentCache(limits = {}, max = 1000) {
             return result;
         },
         clear() {
-            entries.clear();
+            // WeakMap entries go away with their schema; nothing to do eagerly.
         },
     };
 }

package/dist/fetch.d.ts

@@ -39,7 +39,8 @@ export type GateOptions = FareOptions & ReadOptions & DocumentLimits & {
     maxBatchSize?: number;
     /**
      * Looks up persisted documents (trusted documents, `documentId`, or APQ hashes your server
-     * stores itself). Without it, APQ still works: FareQL keeps its own hash → query cache.
+     * stores itself). Without it, hash-only APQ requests get PersistedQueryNotFound and the client
+     * resends the full query, which is then priced.
      */
     resolveDocument?: (params: GraphQLParams) => string | undefined | Promise<string | undefined>;
 };

package/dist/fetch.js

@@ -91,14 +91,40 @@ function checkParams(value) {
 function normalize(value) {
     return Array.isArray(value) ? value.map(checkParams) : checkParams(value);
 }
-async function readBody(request, maxBytes) {
+const tooLarge = (maxBytes) => bad(`Request body is larger than ${maxBytes} bytes`, 413, 'PAYLOAD_TOO_LARGE');
+/** Reads a clone of the body as bytes, stopping as soon as it passes `maxBytes` (chunked bodies included). */
+async function readBytes(request, maxBytes) {
     const declared = Number(request.headers.get('content-length') ?? 'NaN');
     if (declared > maxBytes)
-        throw bad(`Request body is larger than ${maxBytes} bytes`, 413, 'PAYLOAD_TOO_LARGE');
-    const text = await request.clone().text();
-    if (text.length > maxBytes)
-        throw bad(`Request body is larger than ${maxBytes} bytes`, 413, 'PAYLOAD_TOO_LARGE');
-    return text;
+        throw tooLarge(maxBytes);
+    const body = request.clone().body;
+    if (!body)
+        return new Uint8Array(new ArrayBuffer(0));
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            // Not awaited: cancelling one branch of a teed body can wait on the other branch.
+            reader.cancel().catch(() => { });
+            throw tooLarge(maxBytes);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(new ArrayBuffer(size));
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+async function readBody(request, maxBytes) {
+    return new TextDecoder().decode(await readBytes(request, maxBytes));
 }
 /**
  * Reads GraphQL-over-HTTP params without consuming the request body. It refuses anything that
@@ -140,12 +166,10 @@ export async function readGraphQLParams(request, options = {}) {
         return fromSearchParams(new URLSearchParams(await readBody(request, maxBytes))) ?? checkParams({});
     }
     if (accepts('multipart/form-data')) {
-        const declared = Number(request.headers.get('content-length') ?? 'NaN');
-        if (declared > maxBytes)
-            throw bad(`Request body is larger than ${maxBytes} bytes`, 413, 'PAYLOAD_TOO_LARGE');
+        const bytes = await readBytes(request, maxBytes);
         let form;
         try {
-            form = await request.clone().formData();
+            form = await new Response(bytes, { headers: { 'content-type': request.headers.get('content-type') ?? '' } }).formData();
         }
         catch (e) {
             throw bad(`Invalid multipart body: ${e.message}`);
@@ -180,14 +204,12 @@ function apqHash(params) {
     const pq = params.extensions?.persistedQuery;
     return typeof pq?.sha256Hash === 'string' ? pq.sha256Hash : undefined;
 }
-const APQ_CACHEABLE_LENGTH = 32_768;
 /**
  * Creates a framework-agnostic payment gate. Call it with each request before executing
  * GraphQL. It fails closed: anything it cannot read or price is answered, never executed.
  */
 export function createPaymentGate(options) {
     const documents = createDocumentCache(options);
-    const apq = new Map();
     const exposePrice = options.exposePrice ?? true;
     const maxBatchSize = options.maxBatchSize ?? 10;
     const queryOf = async (params) => {
@@ -198,19 +220,16 @@ export function createPaymentGate(options) {
                 if ((await sha256Hex(params.query)) !== hash) {
                     return rejectWith(400, 'PERSISTED_QUERY_HASH_MISMATCH', 'persistedQuery.sha256Hash does not match the query');
                 }
-                if (params.query.length <= APQ_CACHEABLE_LENGTH) {
-                    apq.set(hash, params.query);
-                    if (apq.size > 1000)
-                        apq.delete(apq.keys().next().value);
-                }
             }
             return params.query;
         }
-        const resolved = (await options.resolveDocument?.(params)) ?? (hash !== undefined ? apq.get(hash) : undefined);
+        const resolved = await options.resolveDocument?.(params);
         if (resolved)
             return resolved;
         if (hash !== undefined) {
-            // Same reply as Apollo/Yoga: APQ clients resend the full query, which is then priced.
+            // Same reply as Apollo/Yoga: APQ clients resend the full query, which is then priced. The gate
+            // keeps no hash store of its own: the wrapped handler might not know the hash, and the client
+            // would pay for an operation that never runs.
             return reject(200, [{ message: 'PersistedQueryNotFound', extensions: { code: 'PERSISTED_QUERY_NOT_FOUND' } }], new RequestError('PersistedQueryNotFound', 200, 'PERSISTED_QUERY_NOT_FOUND'));
         }
         if (params.documentId) {

package/dist/yoga.js

@@ -68,15 +68,16 @@ export function useFareql(options) {
         const schema = options.schema ?? args.schema;
         const input = { document: args.document, operationName: args.operationName, variables: args.variableValues };
         const request = options.getRequest?.(args.contextValue) ?? args.contextValue.request;
-        let units;
+        let price;
         try {
-            units = priceOperation({ schema, ...input }, options.pricing).units;
+            price = priceOperation({ schema, ...input }, options.pricing);
         }
         catch (e) {
             if (e instanceof PricingError)
                 return { stop: reject(e), paid: false };
             throw e;
         }
+        const units = price.units;
         if (!request) {
             // No HTTP request to carry a Credential (e.g. graphql-ws): fail closed for priced operations.
             if (units === 0n)
@@ -94,7 +95,7 @@ export function useFareql(options) {
             // One request carries one Credential, so priced operations cannot share a batch.
             return { stop: failure('Priced operations cannot be batched; send them one per request', { code: 'BATCHING_NOT_SUPPORTED' }, 400), paid: false };
         }
-        const outcome = await chargeOperations(forPayment(request), schema, [input], options);
+        const outcome = await chargeOperations(forPayment(request), schema, [input], options, [price]);
         const stop = settle(request, outcome);
         if (!stop)
             allowed.set(request, (allowed.get(request) ?? 0) + 1);
@@ -125,7 +126,8 @@ export function useFareql(options) {
         onRequestParse({ request }) {
             return {
                 onRequestParseDone({ requestParserResult }) {
-                    if (Array.isArray(requestParserResult) && requestParserResult.length > 1)
+                    // Any array is a batch, even with one operation: Yoga answers it with an array.
+                    if (Array.isArray(requestParserResult))
                         batches.add(request);
                 },
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fareql",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Charge for GraphQL operations over MPP (HTTP 402), priced by what each operation selects. Plugins for GraphQL Yoga and Apollo Server, plus a wrapper for any Fetch handler.",
   "type": "module",
   "license": "MIT",