fareql 0.0.0-stage → 0.1.0

package/dist/yoga.js

@@ -0,0 +1,205 @@
+import { GraphQLError } from 'graphql';
+import { chargeOperations, createDocumentCache, paymentError, pricingErrorBody, receiptHeaders, } from './core.js';
+import { PricingError, priceOperation } from './price.js';
+const failure = (message, extensions, status, headers) => ({
+    errors: [new GraphQLError(message, { extensions: { ...extensions, http: headers ? { status, headers } : { status } } })],
+});
+const isAsyncIterable = (v) => typeof v === 'object' && v !== null && Symbol.asyncIterator in v;
+const hasData = (r) => isAsyncIterable(r) || (typeof r === 'object' && r !== null && r.data != null);
+async function* limitEvents(source, max) {
+    if (max <= 0)
+        return;
+    let n = 0;
+    for await (const event of source) {
+        yield event;
+        if (++n >= max) {
+            yield {
+                errors: [new GraphQLError('The events paid for are used up; subscribe again to continue', { extensions: { code: 'PAYMENT_EXHAUSTED' } })],
+            };
+            return; // leaving the loop closes the source iterator
+        }
+    }
+}
+/**
+ * GraphQL Yoga plugin. It charges right before execution, after Yoga and every other plugin have
+ * parsed, validated and restored the document (APQ, persisted operations, depth limits…), so
+ * what is priced is exactly what runs, and nobody pays for an operation a later check rejects.
+ * A backstop before the response is sent charges results that skipped execution (response
+ * caches, other plugins' shortcuts), so a cached priced result is never served unpaid.
+ *
+ * Priced operations answer with the MPP Challenge status (402) and `WWW-Authenticate` header
+ * until the client retries with a valid Credential; the paid response carries `Payment-Receipt`.
+ */
+export function useFareql(options) {
+    const receipts = new WeakMap();
+    const batches = new WeakSet();
+    const allowed = new WeakMap(); // operations of a request that passed the gate
+    const paramsOf = new WeakMap();
+    const documents = createDocumentCache(options);
+    const exposePrice = options.exposePrice ?? true;
+    const maxEvents = options.maxSubscriptionEvents ?? 100;
+    let servedSchema;
+    const reject = (e) => failure(pricingErrorBody(e, exposePrice).message, pricingErrorBody(e, exposePrice).extensions, 400);
+    /** Turns a charge outcome into a result to stop with (or undefined to go on). */
+    const settle = (request, outcome) => {
+        switch (outcome.status) {
+            case 'free':
+                return undefined;
+            case 'rejected':
+                return reject(outcome.error);
+            case 'payment-required': {
+                const headers = {};
+                outcome.challenge.headers.forEach((value, key) => {
+                    if (key !== 'content-type' && key !== 'content-length')
+                        headers[key] = value;
+                });
+                const body = paymentError(outcome.challenge.status, outcome.price, exposePrice);
+                return failure(body.message, body.extensions, outcome.challenge.status, headers);
+            }
+            case 'paid':
+                receipts.set(request, receiptHeaders(outcome.withReceipt));
+                return undefined;
+        }
+    };
+    // Yoga has consumed the body by the time we charge; give mppx a body-less copy it can clone.
+    const forPayment = (request) => new Request(request.url, { method: request.method, headers: request.headers });
+    /** Charges one operation. Returns a result to stop with, or undefined to let it run. */
+    const gate = async (args) => {
+        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;
+        try {
+            units = priceOperation({ schema, ...input }, options.pricing).units;
+        }
+        catch (e) {
+            if (e instanceof PricingError)
+                return { stop: reject(e), paid: false };
+            throw e;
+        }
+        if (!request) {
+            // No HTTP request to carry a Credential (e.g. graphql-ws): fail closed for priced operations.
+            if (units === 0n)
+                return { paid: false };
+            return {
+                stop: failure('Priced operations need an HTTP request; pass getRequest to charge over this transport', { code: 'PAYMENT_TRANSPORT_UNSUPPORTED' }, 402),
+                paid: false,
+            };
+        }
+        if (units === 0n) {
+            allowed.set(request, (allowed.get(request) ?? 0) + 1);
+            return { paid: false };
+        }
+        if (batches.has(request)) {
+            // 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 stop = settle(request, outcome);
+        if (!stop)
+            allowed.set(request, (allowed.get(request) ?? 0) + 1);
+        return { stop, paid: outcome.status === 'paid' };
+    };
+    /** Price of params that never reached execution, from their query text. */
+    const priceParams = (schema, p) => {
+        if (typeof p.query !== 'string' || p.query.length === 0) {
+            return new PricingError('Result produced without a query FareQL could price; register useFareql after APQ/persisted-operation plugins', 'UNKNOWN_OPERATION');
+        }
+        const parsed = documents.get(schema, p.query);
+        if (parsed.errors)
+            return new PricingError(parsed.errors[0]?.message ?? 'Invalid document', 'UNKNOWN_OPERATION');
+        const input = { document: parsed.document, operationName: p.operationName, variables: p.variables };
+        try {
+            return { input, units: priceOperation({ schema, ...input }, options.pricing).units };
+        }
+        catch (e) {
+            if (e instanceof PricingError)
+                return e;
+            throw e;
+        }
+    };
+    return {
+        onSchemaChange({ schema }) {
+            servedSchema = schema;
+        },
+        onRequestParse({ request }) {
+            return {
+                onRequestParseDone({ requestParserResult }) {
+                    if (Array.isArray(requestParserResult) && requestParserResult.length > 1)
+                        batches.add(request);
+                },
+            };
+        },
+        onParams({ request, params }) {
+            const list = paramsOf.get(request) ?? [];
+            list.push(params);
+            paramsOf.set(request, list);
+        },
+        async onExecute({ args, setResultAndStopExecution }) {
+            const { stop } = await gate(args);
+            if (stop)
+                setResultAndStopExecution(stop);
+        },
+        async onSubscribe({ args, setResultAndStopExecution }) {
+            const { stop, paid } = await gate(args);
+            if (stop) {
+                setResultAndStopExecution(stop);
+                return;
+            }
+            if (!paid)
+                return;
+            return {
+                onSubscribeResult({ result, setResult }) {
+                    if (isAsyncIterable(result))
+                        setResult(limitEvents(result, maxEvents));
+                },
+            };
+        },
+        // Backstop: results that did not go through execution (response caches, plugins that
+        // short-circuit earlier) are priced here, before anything is sent.
+        async onResultProcess({ request, result, setResult }) {
+            const schema = options.schema ?? servedSchema;
+            const params = paramsOf.get(request) ?? [];
+            if (!schema)
+                return;
+            if (Array.isArray(result)) {
+                // Batches: priced operations are never allowed, whichever path produced them.
+                const next = result.map((r, i) => {
+                    if (!hasData(r))
+                        return r;
+                    const p = params[i];
+                    const priced = p ? priceParams(schema, p) : new PricingError('Unmatched batch result', 'UNKNOWN_OPERATION');
+                    if (priced instanceof PricingError)
+                        return reject(priced);
+                    return priced.units === 0n ? r : failure('Priced operations cannot be batched; send them one per request', { code: 'BATCHING_NOT_SUPPORTED' }, 400);
+                });
+                if (next.some((r, i) => r !== result[i]))
+                    setResult(next);
+                return;
+            }
+            if ((allowed.get(request) ?? 0) > 0 || !hasData(result))
+                return;
+            const p = params[0];
+            const priced = p ? priceParams(schema, p) : new PricingError('Result without GraphQL params', 'UNKNOWN_OPERATION');
+            if (priced instanceof PricingError)
+                return setResult(reject(priced));
+            if (priced.units === 0n || !priced.input)
+                return;
+            const outcome = await chargeOperations(forPayment(request), schema, [priced.input], options);
+            const stop = settle(request, outcome);
+            if (stop)
+                setResult(stop);
+        },
+        onResponse({ request, response }) {
+            const headers = receipts.get(request);
+            if (!headers)
+                return;
+            receipts.delete(request);
+            headers.forEach((value, key) => response.headers.set(key, value));
+            // Paid content belongs to the payer: never let a shared cache or CDN store it.
+            const cc = response.headers.get('cache-control') ?? '';
+            if (!/\b(private|no-store)\b/i.test(cc))
+                response.headers.set('cache-control', 'private, no-store');
+        },
+    };
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "fareql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+  "author": "Bruce0X (https://github.com/Bruce039)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bruce039/fareql.git"
+  },
+  "homepage": "https://github.com/Bruce039/fareql#readme",
+  "bugs": {
+    "url": "https://github.com/Bruce039/fareql/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./yoga": {
+      "types": "./dist/yoga.d.ts",
+      "import": "./dist/yoga.js"
+    },
+    "./apollo": {
+      "types": "./dist/apollo.d.ts",
+      "import": "./dist/apollo.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "mpp",
+    "mppx",
+    "graphql",
+    "http-402",
+    "payments",
+    "tempo",
+    "graphql-yoga",
+    "apollo-server",
+    "pay-per-query",
+    "monetization"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@apollo/server": "^4.0.0 || ^5.0.0",
+    "graphql": "^16.8.0 || ^17.0.0",
+    "graphql-yoga": "^5.0.0 || ^6.0.0",
+    "mppx": ">=0.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@apollo/server": {
+      "optional": true
+    },
+    "graphql-yoga": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apollo/server": "^5.5.1",
+    "@apollo/server-plugin-response-cache": "^5.0.0",
+    "@graphql-yoga/plugin-apq": "^4.0.1",
+    "@graphql-yoga/plugin-persisted-operations": "^4.0.1",
+    "@graphql-yoga/plugin-response-cache": "^4.0.1",
+    "@types/node": "^22.19.1",
+    "graphql": "^16.15.0",
+    "graphql-yoga": "^6.0.1",
+    "mppx": "^0.17.1",
+    "typescript": "^5.9.3",
+    "viem": "^2.57.16",
+    "vitest": "^5.1.0"
+  }
+}