fareql 0.0.0-stage → 0.1.0

package/dist/fetch.d.ts

@@ -0,0 +1,81 @@
+import type { GraphQLSchema } from 'graphql';
+import { type DocumentLimits, type FareOptions } from './core.js';
+import { type OperationPrice } from './price.js';
+export type GraphQLParams = {
+    query?: string | null;
+    operationName?: string | null;
+    variables?: Record<string, unknown> | null;
+    extensions?: Record<string, unknown> | null;
+    /** GraphQL-over-HTTP persisted document identifier. */
+    documentId?: string | null;
+};
+/** Request bodies the gate reads besides `application/json`. Enable only what your handler accepts. */
+export type Encoding = 'application/graphql+json' | 'application/graphql' | 'application/x-www-form-urlencoded' | 'multipart/form-data';
+export type ReadOptions = {
+    /** Extra body encodings to accept. Default: none (GET and `application/json` only). */
+    encodings?: readonly Encoding[];
+    /** Largest request body read, in bytes. Default: 1 MB. */
+    maxBodyBytes?: number;
+};
+export declare class RequestError extends Error {
+    readonly status: number;
+    readonly code: string;
+    name: string;
+    constructor(message: string, status: number, code: string);
+}
+/**
+ * Reads GraphQL-over-HTTP params without consuming the request body. It refuses anything that
+ * a handler could read differently (URL fragments, duplicate or unknown parameters, GraphQL
+ * parameters in the URL of a POST, bodies on other methods), so what is priced is what runs.
+ * Returns undefined when the request carries no GraphQL operation (e.g. a GraphiQL page).
+ * Throws {@link RequestError} for anything it will not price.
+ */
+export declare function readGraphQLParams(request: Request, options?: ReadOptions): Promise<GraphQLParams | GraphQLParams[] | undefined>;
+export type GateOptions = FareOptions & ReadOptions & DocumentLimits & {
+    schema: GraphQLSchema;
+    /** Accept JSON arrays of operations and charge their total in one payment. Default: false. */
+    batching?: boolean;
+    /** Most operations in one batch. Default: 10. */
+    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.
+     */
+    resolveDocument?: (params: GraphQLParams) => string | undefined | Promise<string | undefined>;
+};
+export type GateResult = 
+/** Nothing to charge (price 0, or not a GraphQL request). Run the handler. */
+{
+    status: 'free';
+    price?: OperationPrice;
+}
+/** Return `response` (402 with the MPP Challenge). */
+ | {
+    status: 'payment-required';
+    response: Response;
+    price: OperationPrice;
+}
+/** Paid. Run the handler and pass its response through `withReceipt`. */
+ | {
+    status: 'paid';
+    price: OperationPrice;
+    withReceipt: (response: Response) => Response;
+}
+/** Must not run (unreadable, invalid, unpriceable or over the price limit). Return `response`. */
+ | {
+    status: 'rejected';
+    response: Response;
+    error: Error;
+};
+/**
+ * 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 declare function createPaymentGate(options: GateOptions): (request: Request) => Promise<GateResult>;
+/**
+ * Wraps any Fetch-API GraphQL handler (graphql-http, Apollo's fetch integrations, a Hono or
+ * Next.js route). Free operations pass through; priced ones get a 402 Challenge, or run and
+ * receive a Payment-Receipt. For GraphQL Yoga and Apollo Server, prefer their plugins: they
+ * price after the server's own validation.
+ */
+export declare function withPayment(handler: (request: Request) => Response | Promise<Response>, options: GateOptions): (request: Request) => Promise<Response>;

package/dist/fetch.js

@@ -0,0 +1,291 @@
+import { chargeOperations, createDocumentCache, graphqlChallenge, jsonResponse, pricingErrorBody, sha256Hex, } from './core.js';
+import { PricingError, selectOperation } from './price.js';
+export class RequestError extends Error {
+    status;
+    code;
+    name = 'RequestError';
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const PARAM_KEYS = ['query', 'operationName', 'variables', 'extensions', 'documentId'];
+const bad = (message, status = 400, code = 'BAD_REQUEST') => new RequestError(message, status, code);
+/** Content-type match as GraphQL Yoga does it: first entry of a list, case-sensitive, parameters allowed. */
+function contentTypeIs(request, expected) {
+    const t = (request.headers.get('content-type') ?? '').split(',')[0]?.trim() ?? '';
+    return t === expected || t.startsWith(`${expected};`);
+}
+function parseJson(text, what) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw bad(`${what} is not valid JSON`);
+    }
+}
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(typeof Blob !== 'undefined' && v instanceof Blob);
+function hasGraphQLParams(p) {
+    return PARAM_KEYS.some((k) => p.has(k));
+}
+function fromSearchParams(p) {
+    if (!hasGraphQLParams(p))
+        return undefined;
+    for (const k of PARAM_KEYS)
+        if (p.getAll(k).length > 1)
+            throw bad(`Parameter "${k}" is given more than once`);
+    const variables = p.get('variables');
+    const extensions = p.get('extensions');
+    // Empty values count as absent, as in GraphQL Yoga.
+    return checkParams({
+        query: p.get('query') || null,
+        operationName: p.get('operationName') || null,
+        variables: variables ? parseJson(variables, 'variables') : null,
+        extensions: extensions ? parseJson(extensions, 'extensions') : null,
+        documentId: p.get('documentId') || null,
+    });
+}
+function setPath(target, path, value) {
+    const keys = path.split('.');
+    let cur = target;
+    for (const [i, key] of keys.entries()) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            return;
+        if (i === keys.length - 1)
+            cur[key] = value;
+        else {
+            if (typeof cur[key] !== 'object' || cur[key] === null)
+                cur[key] = {};
+            cur = cur[key];
+        }
+    }
+}
+/** Checks one set of params the way GraphQL Yoga does, so the gate never prices what the server would refuse. */
+function checkParams(value) {
+    if (!isPlainObject(value))
+        throw bad('GraphQL params must be an object');
+    for (const key of Object.keys(value)) {
+        if (!PARAM_KEYS.includes(key))
+            throw bad(`Unexpected parameter "${key}"`);
+    }
+    const { query, operationName, variables, extensions, documentId } = value;
+    if (query != null && typeof query !== 'string')
+        throw bad('"query" must be a string');
+    if (operationName != null && (typeof operationName !== 'string' || operationName === '')) {
+        throw bad('"operationName" must be a non-empty string');
+    }
+    if (variables != null && !isPlainObject(variables))
+        throw bad('"variables" must be an object');
+    if (extensions != null && !isPlainObject(extensions))
+        throw bad('"extensions" must be an object');
+    if (documentId != null && typeof documentId !== 'string')
+        throw bad('"documentId" must be a string');
+    if (documentId != null && query != null)
+        throw bad('Send either "query" or "documentId", not both');
+    if (documentId != null && extensions?.persistedQuery !== undefined) {
+        throw bad('Send either "documentId" or extensions.persistedQuery, not both');
+    }
+    return value;
+}
+function normalize(value) {
+    return Array.isArray(value) ? value.map(checkParams) : checkParams(value);
+}
+async function readBody(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;
+}
+/**
+ * Reads GraphQL-over-HTTP params without consuming the request body. It refuses anything that
+ * a handler could read differently (URL fragments, duplicate or unknown parameters, GraphQL
+ * parameters in the URL of a POST, bodies on other methods), so what is priced is what runs.
+ * Returns undefined when the request carries no GraphQL operation (e.g. a GraphiQL page).
+ * Throws {@link RequestError} for anything it will not price.
+ */
+export async function readGraphQLParams(request, options = {}) {
+    const encodings = options.encodings ?? [];
+    const maxBytes = options.maxBodyBytes ?? 1_000_000;
+    // URL parsers disagree about "#": URL drops it, GraphQL Yoga keeps what follows "?".
+    if (request.url.includes('#'))
+        throw bad('URL must not contain "#"');
+    const search = new URL(request.url).searchParams;
+    if (request.method === 'GET')
+        return fromSearchParams(search);
+    if (request.method === 'HEAD') {
+        if (hasGraphQLParams(search))
+            throw bad('Use GET or POST for GraphQL operations', 405, 'METHOD_NOT_ALLOWED');
+        return undefined;
+    }
+    if (request.method !== 'POST') {
+        if (request.body !== null || hasGraphQLParams(search))
+            throw bad(`Method ${request.method} is not allowed`, 405, 'METHOD_NOT_ALLOWED');
+        return undefined; // e.g. CORS preflight
+    }
+    if (hasGraphQLParams(search))
+        throw bad('A POST request must carry its GraphQL parameters in the body');
+    if (request.body === null)
+        throw bad('Missing request body');
+    const accepts = (type) => encodings.includes(type) && contentTypeIs(request, type);
+    if (contentTypeIs(request, 'application/json') || accepts('application/graphql+json')) {
+        return normalize(parseJson(await readBody(request, maxBytes), 'Request body'));
+    }
+    if (accepts('application/graphql'))
+        return { query: await readBody(request, maxBytes) };
+    if (accepts('application/x-www-form-urlencoded')) {
+        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');
+        let form;
+        try {
+            form = await request.clone().formData();
+        }
+        catch (e) {
+            throw bad(`Invalid multipart body: ${e.message}`);
+        }
+        if (form.getAll('operations').length !== 1 || form.getAll('map').length > 1) {
+            throw bad('Multipart body needs exactly one "operations" field and at most one "map" field');
+        }
+        const ops = form.get('operations');
+        if (typeof ops !== 'string')
+            throw bad('Multipart field "operations" must be a string');
+        const operations = parseJson(ops, 'Multipart field "operations"');
+        const map = form.get('map');
+        if (typeof map === 'string') {
+            for (const [file, paths] of Object.entries(parseJson(map, 'Multipart field "map"'))) {
+                for (const path of Array.isArray(paths) ? paths : [])
+                    if (typeof path === 'string')
+                        setPath(operations, path, form.get(file));
+            }
+        }
+        return normalize(operations);
+    }
+    throw bad('Unsupported content type for this endpoint', 415, 'UNSUPPORTED_MEDIA_TYPE');
+}
+const reject = (status, errors, error, headers) => ({
+    status: 'rejected',
+    response: jsonResponse(status, errors, headers),
+    error,
+});
+const rejectWith = (status, code, message, headers) => reject(status, [{ message, extensions: { code } }], new RequestError(message, status, code), headers);
+/** Hash of an Automatic Persisted Query, if the params carry one. */
+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) => {
+        const hash = apqHash(params);
+        if (typeof params.query === 'string' && params.query.length > 0) {
+            if (hash !== undefined) {
+                // Exact comparison, as Yoga and Apollo do: the hash names exactly this text.
+                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);
+        if (resolved)
+            return resolved;
+        if (hash !== undefined) {
+            // Same reply as Apollo/Yoga: APQ clients resend the full query, which is then priced.
+            return reject(200, [{ message: 'PersistedQueryNotFound', extensions: { code: 'PERSISTED_QUERY_NOT_FOUND' } }], new RequestError('PersistedQueryNotFound', 200, 'PERSISTED_QUERY_NOT_FOUND'));
+        }
+        if (params.documentId) {
+            return rejectWith(400, 'PERSISTED_DOCUMENT_NOT_FOUND', 'Unknown persisted document; pass resolveDocument to price persisted documents');
+        }
+        return rejectWith(400, 'BAD_REQUEST', 'Must provide a query string');
+    };
+    return async (request) => {
+        let read;
+        try {
+            read = await readGraphQLParams(request, options);
+        }
+        catch (error) {
+            const e = error instanceof RequestError ? error : new RequestError('Unreadable request', 400, 'BAD_REQUEST');
+            return reject(e.status, [{ message: e.message, extensions: { code: e.code } }], e, e.status === 405 ? { allow: 'GET, POST' } : undefined);
+        }
+        if (read === undefined)
+            return { status: 'free' };
+        if (Array.isArray(read) && !options.batching) {
+            return rejectWith(400, 'BATCHING_NOT_SUPPORTED', 'Batched requests are not accepted; send one operation per request');
+        }
+        const list = Array.isArray(read) ? read : [read];
+        if (list.length === 0)
+            return rejectWith(400, 'BAD_REQUEST', 'Empty batch');
+        if (list.length > maxBatchSize)
+            return rejectWith(400, 'BATCH_TOO_LARGE', `A batch may hold at most ${maxBatchSize} operations`);
+        const operations = [];
+        for (const params of list) {
+            const query = await queryOf(params);
+            if (typeof query !== 'string')
+                return query;
+            const parsed = documents.get(options.schema, query);
+            if (parsed.errors) {
+                return reject(400, parsed.errors.map((e) => ({ message: e.message, extensions: { code: 'GRAPHQL_VALIDATION_FAILED' } })), new RequestError(parsed.errors[0]?.message ?? 'Invalid document', 400, 'GRAPHQL_VALIDATION_FAILED'));
+            }
+            try {
+                const op = selectOperation(parsed.document, params.operationName);
+                if (request.method !== 'POST' && op.operation !== 'query') {
+                    return rejectWith(405, 'METHOD_NOT_ALLOWED', `Can only perform a ${op.operation} operation from a POST request`, { allow: 'POST' });
+                }
+            }
+            catch (error) {
+                if (error instanceof PricingError)
+                    return reject(400, [pricingErrorBody(error, exposePrice)], error);
+                throw error;
+            }
+            operations.push({ document: parsed.document, operationName: params.operationName, variables: params.variables });
+        }
+        const outcome = await chargeOperations(request, options.schema, operations, options);
+        switch (outcome.status) {
+            case 'free':
+                return { status: 'free', price: outcome.price };
+            case 'rejected':
+                return reject(400, [pricingErrorBody(outcome.error, exposePrice)], outcome.error);
+            case 'payment-required':
+                return { status: 'payment-required', price: outcome.price, response: await graphqlChallenge(outcome.challenge, outcome.price, exposePrice) };
+            case 'paid':
+                return { status: 'paid', price: outcome.price, withReceipt: outcome.withReceipt };
+        }
+    };
+}
+/**
+ * Wraps any Fetch-API GraphQL handler (graphql-http, Apollo's fetch integrations, a Hono or
+ * Next.js route). Free operations pass through; priced ones get a 402 Challenge, or run and
+ * receive a Payment-Receipt. For GraphQL Yoga and Apollo Server, prefer their plugins: they
+ * price after the server's own validation.
+ */
+export function withPayment(handler, options) {
+    const gate = createPaymentGate(options);
+    return async (request) => {
+        const r = await gate(request);
+        if (r.status === 'free')
+            return handler(request);
+        if (r.status === 'paid')
+            return r.withReceipt(await handler(request));
+        return r.response;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { priceOperation, selectOperation, parseUnits, formatUnits, fareDirectiveTypeDefs, PricingError, PriceLimitError, type PricingOptions, type PricingErrorCode, type OperationPrice, type PriceBreakdownItem, type FieldPriceContext, type PriceInput, } from './price.js';
+export { chargeOperations, operationScope, type ChargeFactory, type ChargeOptions, type ChargeResult, type ChargeOutcome, type FareOptions, type OperationInfo, type OperationInput, } from './core.js';
+export { createPaymentGate, withPayment, readGraphQLParams, RequestError, type GateOptions, type GateResult, type GraphQLParams, } from './fetch.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { priceOperation, selectOperation, parseUnits, formatUnits, fareDirectiveTypeDefs, PricingError, PriceLimitError, } from './price.js';
+export { chargeOperations, operationScope, } from './core.js';
+export { createPaymentGate, withPayment, readGraphQLParams, RequestError, } from './fetch.js';

package/dist/price.d.ts

@@ -0,0 +1,103 @@
+import { type DocumentNode, type GraphQLField, type GraphQLObjectType, type GraphQLSchema, type OperationDefinitionNode } from 'graphql';
+/**
+ * SDL for the directives FareQL reads. Add it to your type definitions.
+ *
+ * `@listSize` follows the IBM GraphQL Cost Directives draft, so schemas that already
+ * use it for complexity analysis price connections correctly without changes.
+ * Code-first schemas can set the same values in `extensions`
+ * (`{ price: '0.001' }` or `{ directives: { price: { amount: '0.001' } } }`).
+ */
+export declare const fareDirectiveTypeDefs = "\n  \"\"\"\n  Price of resolving this field, or of any field returning this type, in token units (e.g. \"0.001\").\n  \"\"\"\n  directive @price(amount: String!) on FIELD_DEFINITION | OBJECT | INTERFACE\n\n  \"\"\"\n  How many items a list or connection field returns, for pricing.\n  \"\"\"\n  directive @listSize(\n    assumedSize: Int\n    slicingArguments: [String!]\n    sizedFields: [String!]\n    requireOneSlicingArgument: Boolean = true\n  ) on FIELD_DEFINITION\n";
+export type FieldPriceContext = {
+    /** The concrete object type the field is resolved on. */
+    parentType: GraphQLObjectType;
+    field: GraphQLField<unknown, unknown>;
+    /** Argument values with variables and defaults applied. */
+    args: Record<string, unknown>;
+    /** Response path, using aliases. */
+    path: readonly string[];
+};
+export type PricingOptions = {
+    /** Token decimals used for exact arithmetic. Default: 6 (the TIP-20 stablecoins on Tempo). */
+    decimals?: number;
+    /** Price of a field that has no `@price` and whose type has none. Default: "0". */
+    defaultFieldPrice?: string;
+    /**
+     * Argument names read as a list length, also one level deep inside input objects
+     * (`page: { limit: 50 }`). Default: first, last, limit, take, top, pageSize, perPage.
+     */
+    listSizeArguments?: readonly string[];
+    /** List length assumed when no size argument is given, and for inner levels of nested lists. Default: 10. */
+    defaultListSize?: number;
+    /**
+     * Upper bound for a list size. Larger sizes, `null` and non-finite sizes are charged at this
+     * value. Set it to your server's real page cap. Default: 100.
+     */
+    maxListSize?: number;
+    /**
+     * Pagination wrappers: a non-list field given a size argument (`users(first: 50)`) passes it to
+     * the list fields it selects (`edges`, `nodes`, `items`…). `sizedFields` limits it to those
+     * names; `false` turns it off. `@listSize(sizedFields:)` always applies. Default: all list children.
+     */
+    connections?: false | {
+        sizedFields?: readonly string[];
+    };
+    /** Reject operations (and batches) priced above this amount (token units). */
+    maxPrice?: string;
+    /** Reject operations that need more than this many selection visits to price. Default: 10000. */
+    maxFieldVisits?: number;
+    /** Reject operations nested deeper than this. Default: 100. */
+    maxDepth?: number;
+    /** Price a field in code. Return undefined to fall back to `@price`. */
+    fieldPrice?: (ctx: FieldPriceContext) => string | undefined;
+};
+export type PriceBreakdownItem = {
+    /** Response path of the priced field, e.g. "search.snippet" (shortened when very long). */
+    path: string;
+    /** Price of one instance, in token units. */
+    unitAmount: string;
+    /** How many instances the operation can resolve. */
+    count: string;
+    /** unitAmount × count, in token units. */
+    amount: string;
+};
+export type OperationPrice = {
+    /** Total price in token units as a decimal string, e.g. "0.0125". */
+    amount: string;
+    /** Total price in base units (10^-decimals). */
+    units: bigint;
+    decimals: number;
+    /** Priced fields that make up the total (at most 100; see `breakdownTruncated`). */
+    breakdown: PriceBreakdownItem[];
+    /** True when more priced fields exist than `breakdown` lists. */
+    breakdownTruncated?: boolean;
+};
+export type PricingErrorCode = 'INVALID_PRICE' | 'INVALID_LIST_SIZE' | 'UNKNOWN_FIELD' | 'UNKNOWN_FRAGMENT' | 'UNKNOWN_OPERATION' | 'INVALID_VARIABLES' | 'SLICING_ARGUMENT_REQUIRED' | 'TOO_COMPLEX' | 'PRICE_LIMIT_EXCEEDED' | 'NO_PRICES';
+export declare class PricingError extends Error {
+    readonly code: PricingErrorCode;
+    name: string;
+    constructor(message: string, code: PricingErrorCode);
+}
+export declare class PriceLimitError extends PricingError {
+    readonly amount: string;
+    readonly maxPrice: string;
+    name: string;
+    constructor(amount: string, maxPrice: string);
+}
+/** Parses a decimal token amount ("0.001") into base units at `decimals`. */
+export declare function parseUnits(value: string, decimals: number): bigint;
+/** Formats base units as a decimal token amount without trailing zeros. */
+export declare function formatUnits(units: bigint, decimals: number): string;
+export type PriceInput = {
+    schema: GraphQLSchema;
+    document: DocumentNode;
+    operationName?: string | null;
+    variables?: Record<string, unknown> | null;
+};
+/** Selects the operation the request will execute, following GraphQL's rules. */
+export declare function selectOperation(document: DocumentNode, operationName?: string | null): OperationDefinitionNode;
+/**
+ * Computes the price of the operation a GraphQL request will run. Pure and deterministic:
+ * the same schema, document and variables always give the same price.
+ */
+export declare function priceOperation(input: PriceInput, options?: PricingOptions): OperationPrice;