fareql 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruce0X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# FareQL
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Charge for GraphQL operations over [MPP](https://mpp.dev) (HTTP 402), priced by what each operation selects.
+
+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.
+
+- **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.
+
+```bash
+npm install fareql mppx graphql
+```
+
+## GraphQL Yoga
+
+```ts
+import { createSchema, createYoga } from 'graphql-yoga'
+import { Mppx, tempo } from 'mppx/server'
+import { fareDirectiveTypeDefs } from 'fareql'
+import { useFareql } from 'fareql/yoga'
+
+const mppx = Mppx.create({
+  methods: [tempo.charge({ currency: '0x…' /* TIP-20 token */, recipient: '0x…' })],
+})
+
+const yoga = createYoga({
+  schema: createSchema({
+    typeDefs: /* GraphQL */ `
+      ${fareDirectiveTypeDefs}
+      type Query {
+        hello: String
+        weather(city: String!): Forecast @price(amount: "0.001")
+        search(query: String!, first: Int = 5): [Hit!]! @price(amount: "0.0005")
+      }
+      type Forecast { temperature: Float }
+      type Hit { title: String, snippet: String @price(amount: "0.0002") }
+    `,
+    resolvers,
+  }),
+  plugins: [useFareql({ charge: (o) => mppx.charge(o), pricing: { maxPrice: '1' } })],
+})
+```
+
+`{ 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.
+
+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`.
+
+## Apollo Server
+
+```ts
+import { ApolloServer } from '@apollo/server'
+import { fareqlApolloPlugin } from 'fareql/apollo'
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  plugins: [fareqlApolloPlugin({ charge: (o) => mppx.charge(o) })],
+})
+```
+
+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.
+
+## Any Fetch handler (Hono, Next.js, graphql-http, Cloudflare Workers)
+
+```ts
+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:
+
+- 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;
+  - 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.
+
+For full control, `createPaymentGate(options)(request)` returns `free`, `payment-required` (with the 402 `response`), `paid` (with `withReceipt`) or `rejected` (with the response to send).
+
+## Pricing rules
+
+| Rule | Behaviour |
+|---|---|
+| 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`) |
+| 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 |
+| 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 |
+
+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).
+
+## 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
+
+{
+  "errors": [{
+    "message": "Payment required: this operation costs 0.0014",
+    "extensions": {
+      "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" }
+        ]
+      }
+    }
+  }]
+}
+```
+
+Any MPP client (`mppx`'s fetch wrapper, `npx mppx`, agents) pays and retries. 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.
+
+## 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` hold the red-team suites: pricing tricks, parser differentials, cache and plugin-order bypasses, scope collisions and DoS. Each test asserts the secure behaviour.
+
+## Shared options
+
+| Option | |
+|---|---|
+| `charge` | `(o) => mppx.charge(o)`, or `(o) => mppx.tempo.charge(o)` when several methods are configured. Receives `{ amount, scope, description }` |
+| `pricing` | See [Pricing rules](#pricing-rules) |
+| `describe(op, price)` | Challenge description. Default: `GraphQL <operation name>` |
+| `exposePrice` | Include the price breakdown in 402 bodies. Default: `true` |
+
+## Notes
+
+- Payment settles before execution, so a resolver error after payment is not refunded. Keep priced resolvers reliable, or price them lower.
+- 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.
+
+## Examples
+
+- [`examples/yoga-tempo`](examples/yoga-tempo/server.ts): GraphQL Yoga on Tempo's Moderato testnet
+- [`examples/apollo-tempo`](examples/apollo-tempo/server.ts): Apollo Server with a priced Relay-style connection
+- [`examples/playground`](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
+
+```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 } }"}'
+```
+
+## Development
+
+```bash
+npm test          # vitest: pricing, gate, Yoga, Apollo, and real mppx client ↔ server loops
+npm run build && node scripts/smoke.mjs   # the built package over real HTTP in plain Node
+```
+
+## License
+
+MIT

package/dist/apollo.d.ts

@@ -0,0 +1,19 @@
+import { type ApolloServerPlugin, type BaseContext, type HTTPGraphQLRequest } from '@apollo/server';
+import { type FareOptions } from './core.js';
+export type FareqlApolloOptions = FareOptions & {
+    /**
+     * URL of the GraphQL endpoint, used to build the Fetch `Request` mppx sees. Apollo does not
+     * expose the path. Default: `http://<Host header>/graphql<search>`.
+     */
+    url?: string | ((http: HTTPGraphQLRequest) => string);
+};
+/**
+ * Apollo Server 4/5 plugin. Prices each operation after Apollo has parsed, validated and
+ * resolved it (persisted queries included), before execution. Priced operations answer with the
+ * MPP Challenge (402 + `WWW-Authenticate`); paid ones carry `Payment-Receipt`.
+ *
+ * In an HTTP batch only the first priced operation can be paid (one request carries one
+ * Credential); further priced operations in the same batch are refused.
+ * Operations run in-process with `server.executeOperation()` have no HTTP request and are not charged.
+ */
+export declare function fareqlApolloPlugin<TContext extends BaseContext = BaseContext>(options: FareqlApolloOptions): ApolloServerPlugin<TContext>;

package/dist/apollo.js

@@ -0,0 +1,100 @@
+import { HeaderMap } from '@apollo/server';
+import { GraphQLError } from 'graphql';
+import { chargeOperations, paymentError, pricingErrorBody, receiptHeaders } from './core.js';
+import { PricingError, priceOperation } from './price.js';
+function toFetchRequest(http, url) {
+    const headers = new Headers();
+    for (const [key, value] of http.headers)
+        headers.set(key, value);
+    const href = typeof url === 'function'
+        ? url(http)
+        : url
+            ? `${url}${http.search}`
+            : `http://${http.headers.get('host') ?? 'localhost'}/graphql${http.search}`;
+    try {
+        return new Request(href, { method: http.method, headers });
+    }
+    catch {
+        // A Host header that is not a valid authority: the Challenge realm falls back to localhost
+        // (configure `realm` in Mppx.create to make it independent of the Host header).
+        return new Request(`http://localhost/graphql${http.search.startsWith('?') ? http.search : ''}`, { method: http.method, headers });
+    }
+}
+const fail = (message, extensions, status, headers) => {
+    // Typed loosely: GraphQL Yoga augments GraphQLErrorExtensions with its own `http` shape.
+    const ext = { ...extensions, http: { status, headers: headers ?? new HeaderMap() } };
+    return new GraphQLError(message, { extensions: ext });
+};
+/**
+ * Apollo Server 4/5 plugin. Prices each operation after Apollo has parsed, validated and
+ * resolved it (persisted queries included), before execution. Priced operations answer with the
+ * MPP Challenge (402 + `WWW-Authenticate`); paid ones carry `Payment-Receipt`.
+ *
+ * In an HTTP batch only the first priced operation can be paid (one request carries one
+ * Credential); further priced operations in the same batch are refused.
+ * Operations run in-process with `server.executeOperation()` have no HTTP request and are not charged.
+ */
+export function fareqlApolloPlugin(options) {
+    const exposePrice = options.exposePrice ?? true;
+    // Pieces of one HTTP batch share the same headers object; count the priced ones per request.
+    const pricedPieces = new WeakMap();
+    return {
+        async requestDidStart() {
+            let receipt;
+            return {
+                async didResolveOperation(rc) {
+                    const http = rc.request.http;
+                    if (!http)
+                        return;
+                    const input = { document: rc.document, operationName: rc.operationName ?? rc.request.operationName, variables: rc.request.variables };
+                    let units;
+                    try {
+                        units = priceOperation({ schema: rc.schema, ...input }, options.pricing).units;
+                    }
+                    catch (e) {
+                        if (e instanceof PricingError)
+                            throw fail(e.message, pricingErrorBody(e, exposePrice).extensions, 400);
+                        throw e;
+                    }
+                    if (units === 0n)
+                        return;
+                    // Counted synchronously, before any await, so parallel batch pieces cannot race past it.
+                    const n = (pricedPieces.get(http.headers) ?? 0) + 1;
+                    pricedPieces.set(http.headers, n);
+                    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);
+                    switch (outcome.status) {
+                        case 'free':
+                            return;
+                        case 'rejected': {
+                            const body = pricingErrorBody(outcome.error, exposePrice);
+                            throw fail(body.message, body.extensions, 400);
+                        }
+                        case 'payment-required': {
+                            const headers = new HeaderMap();
+                            outcome.challenge.headers.forEach((value, key) => {
+                                if (key !== 'content-type' && key !== 'content-length')
+                                    headers.set(key, value);
+                            });
+                            const body = paymentError(outcome.challenge.status, outcome.price, exposePrice);
+                            throw fail(body.message, body.extensions, outcome.challenge.status, headers);
+                        }
+                        case 'paid':
+                            receipt = receiptHeaders(outcome.withReceipt);
+                    }
+                },
+                async willSendResponse(rc) {
+                    if (!receipt)
+                        return;
+                    receipt.forEach((value, key) => rc.response.http.headers.set(key, value));
+                    // Paid content belongs to the payer: never let a shared cache or CDN store it.
+                    const cc = rc.response.http.headers.get('cache-control') ?? '';
+                    if (!/\b(private|no-store)\b/i.test(cc))
+                        rc.response.http.headers.set('cache-control', 'private, no-store');
+                },
+            };
+        },
+    };
+}

package/dist/core.d.ts

@@ -0,0 +1,119 @@
+import { type DocumentNode, type GraphQLError, type GraphQLSchema, type OperationTypeNode, type ValidationRule } from 'graphql';
+import { type OperationPrice, type PricingOptions, PricingError } from './price.js';
+/** Options passed to the charge factory; maps 1:1 onto `mppx.charge({ ... })`. */
+export type ChargeOptions = {
+    /** Price in token units, e.g. "0.0014". */
+    amount: string;
+    /** Binds the Challenge to this exact operation, so its Credential cannot pay for another one. */
+    scope: string;
+    description?: string;
+};
+/** What an mppx route handler returns (`await mppx.charge(options)(request)`). */
+export type ChargeResult = {
+    status: 402;
+    challenge: Response;
+} | {
+    status: 200;
+    withReceipt: (response: Response) => Response;
+};
+/**
+ * Creates a charge handler for one priced operation. With mppx this is
+ * `(o) => mppx.charge(o)`, or `(o) => mppx.tempo.charge(o)` with several methods.
+ */
+export type ChargeFactory = (options: ChargeOptions) => (request: Request) => Promise<ChargeResult>;
+export type OperationInput = {
+    document: DocumentNode;
+    operationName?: string | null;
+    variables?: Record<string, unknown> | null;
+};
+export type OperationInfo = {
+    operationName: string | undefined;
+    operationType: OperationTypeNode;
+};
+export type FareOptions = {
+    charge: ChargeFactory;
+    pricing?: PricingOptions;
+    /** Challenge description. Default: `GraphQL <operation name or type>`. */
+    describe?: (operation: OperationInfo, price: OperationPrice) => string | undefined;
+    /** Include the price and its breakdown in 402 bodies. Default: true. */
+    exposePrice?: boolean;
+};
+export type ChargeOutcome = 
+/** Nothing to charge. Execute normally. */
+{
+    status: 'free';
+    price: OperationPrice;
+}
+/** Send `challenge` (an MPP 402) to the client. */
+ | {
+    status: 'payment-required';
+    price: OperationPrice;
+    scope: string;
+    challenge: Response;
+}
+/** Paid. Execute, then pass the response through `withReceipt`. */
+ | {
+    status: 'paid';
+    price: OperationPrice;
+    scope: string;
+    withReceipt: (response: Response) => Response;
+}
+/** The operation could not be priced; it must not run. */
+ | {
+    status: 'rejected';
+    error: PricingError;
+};
+declare function sha256Hex(text: string): Promise<string>;
+export { sha256Hex };
+/**
+ * Scope binding a Challenge to a set of operations: `graphql:<sha256 of document, operation name and variables>`.
+ * mppx stores it in the Challenge's HMAC-protected metadata and refuses Credentials whose scope differs.
+ */
+export declare function operationScope(operations: readonly OperationInput[]): Promise<string>;
+/**
+ * Prices one or more operations and charges for them through mppx. Every adapter (Fetch, Yoga,
+ * 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 type GraphQLErrorBody = {
+    message: string;
+    extensions: Record<string, unknown>;
+};
+export declare function priceExtension(price: OperationPrice): {
+    breakdownTruncated?: boolean | undefined;
+    amount: string;
+    decimals: number;
+    breakdown: import("./price.js").PriceBreakdownItem[];
+};
+export declare function paymentError(status: number, price: OperationPrice, exposePrice: boolean): GraphQLErrorBody;
+export declare function pricingErrorBody(error: PricingError, exposePrice?: boolean): GraphQLErrorBody;
+/**
+ * Turns mppx's 402 into a response GraphQL clients understand: same status and headers
+ * (WWW-Authenticate carries the Challenge), and a body with both the problem details mppx
+ * wrote and a GraphQL `errors` array. HTML paywalls are passed through untouched.
+ */
+export declare function graphqlChallenge(challenge: Response, price: OperationPrice, exposePrice: boolean): Promise<Response>;
+export declare function jsonResponse(status: number, errors: readonly GraphQLErrorBody[], headers?: HeadersInit): Response;
+/** Copies the headers mppx adds for a receipt onto an existing response. */
+export declare function receiptHeaders(withReceipt: (response: Response) => Response): Headers;
+export type ParsedDocument = {
+    document: DocumentNode;
+    errors?: undefined;
+} | {
+    document?: undefined;
+    errors: readonly GraphQLError[];
+};
+export type DocumentLimits = {
+    /** Longest query text accepted, in characters. Default: 100000. */
+    maxQueryLength?: number;
+    /** Most lexical tokens a document may have (graphql-js `maxTokens`). Default: 15000. */
+    maxTokens?: number;
+    /** Extra validation rules your server applies, so their failures are refused before payment. */
+    validationRules?: readonly ValidationRule[];
+};
+/** Small LRU of parse + validate results. Only short queries are cached, so memory stays bounded. */
+export declare function createDocumentCache(limits?: DocumentLimits, max?: number): {
+    get(schema: GraphQLSchema, query: string): ParsedDocument;
+    clear(): void;
+};

package/dist/core.js

@@ -0,0 +1,211 @@
+import { GraphQLError as GraphQLErrorClass, parse, print, specifiedRules, validate, } from 'graphql';
+import { PriceLimitError, PricingError, formatUnits, parseUnits, priceOperation, selectOperation, } from './price.js';
+const MAX_VARIABLE_DEPTH = 64;
+/**
+ * Canonical, unambiguous encoding of variable values: sorted keys, tagged files, no
+ * non-finite numbers, bounded depth. Equal inputs give equal strings and different
+ * inputs can never collide.
+ */
+function canonical(value, depth = 0) {
+    if (depth > MAX_VARIABLE_DEPTH)
+        throw new PricingError('Variables are nested too deeply', 'TOO_COMPLEX');
+    if (value === undefined)
+        return { $undefined: true };
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new PricingError('Variables must not contain non-finite numbers', 'INVALID_VARIABLES');
+        return value;
+    }
+    if (typeof value === 'bigint')
+        return { $bigint: value.toString() };
+    if (Array.isArray(value))
+        return value.map((v) => canonical(v, depth + 1));
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        // Uploaded files: bound by name, type and size (the content does not change the price).
+        const f = value;
+        return { $blob: [f.name ?? '', f.type, f.size] };
+    }
+    if (typeof value === 'object') {
+        const o = value;
+        return { $object: Object.keys(o).sort().map((k) => [k, canonical(o[k], depth + 1)]) };
+    }
+    throw new PricingError(`Unsupported variable value of type ${typeof value}`, 'INVALID_VARIABLES');
+}
+async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+export { sha256Hex };
+/** Only the variables the operation declares can change what runs. */
+function declaredVariables(o) {
+    const vars = o.variables ?? {};
+    const op = selectOperation(o.document, o.operationName);
+    const out = {};
+    for (const d of op.variableDefinitions ?? []) {
+        const name = d.variable.name.value;
+        if (Object.hasOwn(vars, name))
+            out[name] = vars[name];
+    }
+    return out;
+}
+/**
+ * Scope binding a Challenge to a set of operations: `graphql:<sha256 of document, operation name and variables>`.
+ * mppx stores it in the Challenge's HMAC-protected metadata and refuses Credentials whose scope differs.
+ */
+export async function operationScope(operations) {
+    const material = JSON.stringify(operations.map((o) => [print(o.document), o.operationName ?? null, canonical(declaredVariables(o))]));
+    return `graphql:${(await sha256Hex(material)).slice(0, 32)}`;
+}
+function sumPrices(prices, decimals) {
+    if (prices.length === 1)
+        return prices[0];
+    const units = prices.reduce((s, p) => s + p.units, 0n);
+    return {
+        amount: formatUnits(units, decimals),
+        units,
+        decimals,
+        breakdown: prices.flatMap((p, i) => p.breakdown.map((b) => ({ ...b, path: `${i}:${b.path}` }))).slice(0, 100),
+        ...(prices.some((p) => p.breakdownTruncated) || prices.reduce((n, p) => n + p.breakdown.length, 0) > 100
+            ? { breakdownTruncated: true }
+            : {}),
+    };
+}
+/**
+ * Prices one or more operations and charges for them through mppx. Every adapter (Fetch, Yoga,
+ * 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) {
+    const decimals = options.pricing?.decimals ?? 6;
+    let price;
+    let info;
+    try {
+        const prices = 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))
+            throw new PriceLimitError(price.amount, max);
+        const first = operations[0];
+        const op = first ? selectOperation(first.document, first.operationName) : undefined;
+        info = { operationName: operations.length === 1 ? op?.name?.value : undefined, operationType: op?.operation ?? 'query' };
+    }
+    catch (error) {
+        if (error instanceof PricingError)
+            return { status: 'rejected', error };
+        throw error;
+    }
+    if (price.units === 0n)
+        return { status: 'free', price };
+    let scope;
+    try {
+        scope = await operationScope(operations);
+    }
+    catch (error) {
+        if (error instanceof PricingError)
+            return { status: 'rejected', error };
+        throw error;
+    }
+    const description = options.describe?.(info, price) ??
+        (operations.length > 1 ? `GraphQL batch of ${operations.length} operations` : `GraphQL ${info.operationName ?? info.operationType}`);
+    const result = await options.charge({ amount: price.amount, scope, description })(request);
+    if (result.status === 402)
+        return { status: 'payment-required', price, scope, challenge: result.challenge };
+    return { status: 'paid', price, scope, withReceipt: result.withReceipt };
+}
+export function priceExtension(price) {
+    return {
+        amount: price.amount,
+        decimals: price.decimals,
+        breakdown: price.breakdown,
+        ...(price.breakdownTruncated ? { breakdownTruncated: true } : {}),
+    };
+}
+export function paymentError(status, price, exposePrice) {
+    const code = status === 402 ? 'PAYMENT_REQUIRED' : status === 401 ? 'UNAUTHENTICATED' : 'FORBIDDEN';
+    return {
+        message: status === 402 ? `Payment required: this operation costs ${price.amount}` : 'Payment was not accepted for this operation',
+        extensions: exposePrice ? { code, price: priceExtension(price) } : { code },
+    };
+}
+export function pricingErrorBody(error, exposePrice = true) {
+    if (!exposePrice && error.code === 'PRICE_LIMIT_EXCEEDED') {
+        return { message: 'Operation exceeds the maximum price', extensions: { code: error.code } };
+    }
+    return { message: error.message, extensions: { code: error.code } };
+}
+/**
+ * Turns mppx's 402 into a response GraphQL clients understand: same status and headers
+ * (WWW-Authenticate carries the Challenge), and a body with both the problem details mppx
+ * wrote and a GraphQL `errors` array. HTML paywalls are passed through untouched.
+ */
+export async function graphqlChallenge(challenge, price, exposePrice) {
+    const type = challenge.headers.get('content-type') ?? '';
+    if (type.includes('text/html') || challenge.status === 200)
+        return challenge;
+    let problem = {};
+    if (type.includes('json')) {
+        try {
+            const parsed = (await challenge.clone().json());
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                problem = parsed;
+        }
+        catch {
+            // keep an empty problem object
+        }
+    }
+    const headers = new Headers(challenge.headers);
+    headers.set('content-type', 'application/json; charset=utf-8');
+    headers.delete('content-length');
+    const body = { ...problem, errors: [paymentError(challenge.status, price, exposePrice)] };
+    return new Response(JSON.stringify(body), { status: challenge.status, statusText: challenge.statusText, headers });
+}
+export function jsonResponse(status, errors, headers) {
+    const h = new Headers(headers);
+    h.set('content-type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify({ errors }), { status, headers: h });
+}
+/** Copies the headers mppx adds for a receipt onto an existing response. */
+export function receiptHeaders(withReceipt) {
+    return withReceipt(new Response(null)).headers;
+}
+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();
+    const maxQueryLength = limits.maxQueryLength ?? 100_000;
+    const maxTokens = limits.maxTokens ?? 15_000;
+    const rules = limits.validationRules ? [...specifiedRules, ...limits.validationRules] : undefined;
+    return {
+        get(schema, query) {
+            if (query.length > maxQueryLength) {
+                return { errors: [new GraphQLErrorClass(`Query is longer than ${maxQueryLength} characters`)] };
+            }
+            const hit = entries.get(query);
+            if (hit) {
+                entries.delete(query);
+                entries.set(query, hit);
+                return hit;
+            }
+            let result;
+            try {
+                const document = parse(query, { maxTokens });
+                const errors = validate(schema, document, rules);
+                result = errors.length > 0 ? { errors } : { document };
+            }
+            catch (error) {
+                result = { errors: [error instanceof GraphQLErrorClass ? error : new GraphQLErrorClass(String(error.message))] };
+            }
+            if (query.length <= CACHEABLE_QUERY_LENGTH) {
+                entries.set(query, result);
+                if (entries.size > max)
+                    entries.delete(entries.keys().next().value);
+            }
+            return result;
+        },
+        clear() {
+            entries.clear();
+        },
+    };
+}