@thenavidm/slipway 0.1.0

package/dist/openapi.js

@@ -0,0 +1,549 @@
+/**
+ * Tools from an OpenAPI document.
+ *
+ * An API that publishes OpenAPI already says what every operation takes. This
+ * turns each operation into a tool with that input, the risk its HTTP method
+ * implies, and its tags as toolsets, so a large API becomes a server and a CLI
+ * without a hand-written tool per endpoint. The tools join the same list as
+ * hand-written ones and go through the same guard.
+ *
+ * A generated tool is only as trustworthy as the document it came from, so a
+ * document can be pinned by hash: a changed document refuses to build until
+ * someone has looked at what changed and updated the pin.
+ */
+import { UsageError, httpError } from "./errors.js";
+import { CONTROL_NAMES, jsonSchema } from "./schema.js";
+import { defineTool } from "./tool.js";
+import { sha256, stableJson } from "./util.js";
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+const READS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+/** Headers the transport sets itself, which a tool never takes as arguments. */
+const TRANSPORT_HEADERS = new Set(["authorization", "content-type", "accept", "content-length", "user-agent", "host", "cookie"]);
+/** Formats the validator understands. Any other format is left out, since an unknown one prints a warning every time the schema loads. */
+const KNOWN_FORMATS = new Set([
+    "int32", "int64", "float", "double", "byte", "binary", "password", "date", "date-time", "time", "duration", "uuid", "email",
+    "uri", "uri-reference", "uri-template", "url", "hostname", "ipv4", "ipv6", "regex", "json-pointer", "relative-json-pointer",
+]);
+const PROPERTY = /^[A-Za-z0-9_.-]{1,64}$/;
+/** Names an API's own arguments cannot take: Slipway's controls, and the property that carries a body that is not spread. */
+const RESERVED = new Set([...CONTROL_NAMES, "body"]);
+const MAX_DEPTH = 40;
+/**
+ * How many references deep an object schema is expanded. Large APIs refer
+ * from object to object to object, and expanding every path in full grows
+ * without bound. Below this depth an object is described rather than spelled
+ * out, and the API itself checks it.
+ */
+const MAX_REF_DEPTH = 3;
+const MAX_DESCRIPTION = 1_000;
+/** The hash to pin a document by: the same for the same content, however its keys were ordered. */
+export function openapiHash(document) {
+    return sha256(stableJson(document));
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pointer(document, ref) {
+    if (!ref.startsWith("#/")) {
+        throw new UsageError(`Only references inside the document are supported, not '${ref}'. Bundle the document into one file first.`);
+    }
+    let node = document;
+    for (const raw of ref.slice(2).split("/")) {
+        const part = decodeURIComponent(raw).replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!isRecord(node) && !Array.isArray(node))
+            return undefined;
+        node = node[part];
+    }
+    if (node === undefined)
+        throw new UsageError(`The reference '${ref}' points at nothing in the document.`);
+    return node;
+}
+/** A schema small enough to inline at any depth: a plain value, a list of choices. */
+function isSmall(node) {
+    if (!isRecord(node))
+        return true;
+    if (node.$ref !== undefined || node.properties !== undefined || node.items !== undefined || node.allOf || node.anyOf || node.oneOf || isRecord(node.additionalProperties))
+        return false;
+    return true;
+}
+/**
+ * Inline `$ref`s. A schema that refers to itself, such as a tree of comments,
+ * is cut at the second visit, and an object more than a few references deep
+ * is described rather than spelled out, so a large API's schemas stay a size
+ * a model can read. Results are memoized per reference and depth, since large
+ * documents refer to the same schemas thousands of times.
+ */
+function resolver(document) {
+    const memo = new Map();
+    const resolve = (node, seen = [], depth = 0) => {
+        if (depth > MAX_DEPTH)
+            return {};
+        if (Array.isArray(node))
+            return node.map((item) => resolve(item, seen, depth + 1));
+        if (!isRecord(node))
+            return node;
+        if (typeof node.$ref === "string") {
+            const ref = node.$ref;
+            const { $ref: _ref, ...siblings } = node;
+            const name = ref.split("/").pop();
+            const raw = pointer(document, ref);
+            const extra = resolve(siblings, seen, depth + 1);
+            if (seen.includes(ref) || (seen.length >= MAX_REF_DEPTH && !isSmall(raw))) {
+                const about = isRecord(raw) && typeof raw.description === "string" ? ` ${clip(raw.description, 200)}` : "";
+                return { ...extra, description: extra.description ?? `A ${name}, not spelled out here: the API checks its fields.${about}` };
+            }
+            const key = `${ref}\0${seen.length}`;
+            if (!memo.has(key))
+                memo.set(key, resolve(raw, [...seen, ref], depth + 1));
+            const target = memo.get(key);
+            return isRecord(target) ? { ...target, ...extra } : target;
+        }
+        return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, resolve(value, seen, depth + 1)]));
+    };
+    return resolve;
+}
+/**
+ * An OpenAPI schema as JSON Schema 2020-12: `nullable` becomes a null type,
+ * 3.0's boolean exclusive bounds become numbers, `example` becomes
+ * `examples`, and keys that only mean something to OpenAPI are dropped.
+ * Properties the server sets itself (`readOnly`) leave a request's input.
+ */
+export function toJsonSchema(node, forInput) {
+    if (Array.isArray(node))
+        return node.map((item) => toJsonSchema(item, forInput));
+    if (!isRecord(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith("x-") || ["discriminator", "xml", "externalDocs", "nullable", "example", "$id", "$schema", "$anchor", "deprecated"].includes(key))
+            continue;
+        if (key === "format" && (typeof value !== "string" || !KNOWN_FORMATS.has(value)))
+            continue;
+        if (key === "exclusiveMinimum" && typeof value === "boolean") {
+            if (value && typeof node.minimum === "number")
+                out.exclusiveMinimum = node.minimum;
+            continue;
+        }
+        if (key === "exclusiveMaximum" && typeof value === "boolean") {
+            if (value && typeof node.maximum === "number")
+                out.exclusiveMaximum = node.maximum;
+            continue;
+        }
+        if ((key === "minimum" && node.exclusiveMinimum === true) || (key === "maximum" && node.exclusiveMaximum === true))
+            continue;
+        if (key === "properties" && isRecord(value)) {
+            const properties = {};
+            for (const [name, schema] of Object.entries(value)) {
+                if (forInput && isRecord(schema) && schema.readOnly === true)
+                    continue;
+                properties[name] = toJsonSchema(schema, forInput);
+            }
+            out.properties = properties;
+            continue;
+        }
+        // Values are data, not schemas, so they pass through untouched.
+        out[key] = ["default", "const", "enum", "examples"].includes(key) ? value : isRecord(value) || Array.isArray(value) ? toJsonSchema(value, forInput) : value;
+    }
+    if (forInput && Array.isArray(out.required) && isRecord(out.properties)) {
+        const kept = out.required.filter((name) => typeof name === "string" && name in out.properties);
+        if (kept.length)
+            out.required = kept;
+        else
+            delete out.required;
+    }
+    if (node.example !== undefined && out.examples === undefined)
+        out.examples = [toJsonSchema(node.example, false)];
+    if (node.nullable === true) {
+        if (typeof out.type === "string")
+            out.type = [out.type, "null"];
+        else if (Array.isArray(out.type) && !out.type.includes("null"))
+            out.type = [...out.type, "null"];
+        else if (Array.isArray(out.enum) && !out.enum.includes(null))
+            out.enum = [...out.enum, null];
+        else if (out.type === undefined)
+            return { anyOf: [out, { type: "null" }] };
+    }
+    return out;
+}
+/**
+ * operationId as a tool name: listPets and pets.list become list_pets and
+ * pets_list. A name past the 64 characters clients allow keeps its start and
+ * ends in a short hash of the id, so two long ids that begin alike stay
+ * two names, and the same id always gets the same one.
+ */
+export function toolName(id) {
+    const snake = id
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/_+/g, "_");
+    const name = /^[a-z]/.test(snake) ? snake : `op_${snake}`;
+    if (name.length <= 64)
+        return name;
+    return `${name.slice(0, 55).replace(/_+$/, "")}_${sha256(id).slice(0, 8)}`;
+}
+function slug(tag) {
+    return tag.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function words(id) {
+    const spaced = id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_.-]+/g, " ").trim().toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function clip(text, max) {
+    const clean = text.trim();
+    return clean.length <= max ? clean : `${clean.slice(0, max - 1).trimEnd()}…`;
+}
+/** The media type a body is sent as: JSON first, then a form. Anything else cannot be built from arguments. */
+function bodyType(content) {
+    const types = Object.keys(content);
+    return (types.find((type) => /^application\/json\b/i.test(type)) ??
+        types.find((type) => /\+json\b/i.test(type)) ??
+        types.find((type) => /^application\/x-www-form-urlencoded\b/i.test(type)));
+}
+/** Every operation in a document, as tools would see it, and the ones that cannot become tools, with why. */
+export function readOperations(document, options = {}) {
+    if (!isRecord(document))
+        throw new UsageError("An OpenAPI document is a JSON object.");
+    if (typeof document.swagger === "string")
+        throw new UsageError("This is a Swagger 2.0 document. Convert it to OpenAPI 3 first.");
+    if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi))
+        throw new UsageError("This is not an OpenAPI 3 document: it has no openapi: 3.x field.");
+    const paths = isRecord(document.paths) ? document.paths : {};
+    const operations = [];
+    const skipped = [];
+    const resolve = resolver(document);
+    for (const [path, rawItem] of Object.entries(paths)) {
+        // Only what a tool's input needs is resolved: parameters and the body, and responses only for typed output.
+        const item = (isRecord(rawItem) && typeof rawItem.$ref === "string" ? pointer(document, rawItem.$ref) : rawItem);
+        if (!isRecord(item))
+            continue;
+        const shared = Array.isArray(item.parameters) ? resolve(item.parameters) : [];
+        for (const method of METHODS) {
+            const rawOp = item[method];
+            if (!isRecord(rawOp))
+                continue;
+            const op = {
+                ...rawOp,
+                ...(rawOp.parameters ? { parameters: resolve(rawOp.parameters) } : {}),
+                ...(rawOp.requestBody ? { requestBody: resolve(rawOp.requestBody) } : {}),
+                ...(options.typedOutput && rawOp.responses ? { responses: resolve(rawOp.responses) } : {}),
+            };
+            const verb = method.toUpperCase();
+            const operationId = typeof op.operationId === "string" && op.operationId ? op.operationId : `${method}_${path}`;
+            const skip = (reason) => skipped.push({ method: verb, path, ...(typeof op.operationId === "string" ? { operationId: op.operationId } : {}), reason });
+            // An operation's own parameter replaces a path-level one with the same name and location.
+            const own = Array.isArray(op.parameters) ? op.parameters : [];
+            const merged = [...shared.filter((p) => !own.some((o) => o.name === p.name && o.in === p.in)), ...own].filter(isRecord);
+            const properties = {};
+            const required = [];
+            const parameters = [];
+            let problem;
+            for (const parameter of merged) {
+                const location = parameter.in;
+                const name = String(parameter.name ?? "");
+                if (location === "cookie")
+                    continue;
+                if (location === "header" && TRANSPORT_HEADERS.has(name.toLowerCase()))
+                    continue;
+                if (location !== "path" && location !== "query" && location !== "header")
+                    continue;
+                let property = name;
+                if (!PROPERTY.test(property) || property in properties || RESERVED.has(property))
+                    property = `${location}_${name}`.replace(/[^A-Za-z0-9_.-]+/g, "_").slice(0, 64);
+                if (!PROPERTY.test(property) || property in properties) {
+                    problem = `parameter '${name}' cannot become an argument name`;
+                    break;
+                }
+                const schema = toJsonSchema(isRecord(parameter.schema) ? parameter.schema : { type: "string" }, true);
+                const description = typeof parameter.description === "string" ? parameter.description : schema.description;
+                properties[property] = { ...schema, ...(description ? { description: clip(String(description), MAX_DESCRIPTION) } : {}) };
+                const isRequired = location === "path" || parameter.required === true;
+                if (isRequired)
+                    required.push(property);
+                const style = typeof parameter.style === "string" ? parameter.style : location === "query" ? "form" : "simple";
+                const explode = typeof parameter.explode === "boolean" ? parameter.explode : style === "form";
+                parameters.push({ name, in: location, required: isRequired, property, style, explode });
+            }
+            if (problem) {
+                skip(problem);
+                continue;
+            }
+            let body;
+            const requestBody = isRecord(op.requestBody) ? op.requestBody : undefined;
+            if (requestBody && isRecord(requestBody.content)) {
+                const contentType = bodyType(requestBody.content);
+                if (!contentType) {
+                    skip(`its body is ${Object.keys(requestBody.content).join(" or ")}, which arguments cannot carry`);
+                    continue;
+                }
+                const media = requestBody.content[contentType];
+                const schema = toJsonSchema(isRecord(media?.schema) ? media.schema : { type: "object" }, true);
+                const bodyRequired = requestBody.required === true;
+                const own = isRecord(schema.properties) ? schema.properties : undefined;
+                // Spread a plain object's fields into the input, so a model writes { name, tag } rather than
+                // { body: { name, tag } }. A field whose name is taken, by a parameter or by Slipway, is renamed body_<field>.
+                const fields = {};
+                const plain = own !== undefined && (schema.type === "object" || schema.type === undefined) && !schema.allOf && !schema.anyOf && !schema.oneOf && !isRecord(schema.additionalProperties);
+                let spreadable = plain;
+                for (const field of plain ? Object.keys(own) : []) {
+                    let property = field;
+                    if (!PROPERTY.test(property) || property in properties || RESERVED.has(property))
+                        property = `body_${field}`;
+                    if (!PROPERTY.test(property) || property in properties || property in fields) {
+                        spreadable = false;
+                        break;
+                    }
+                    fields[property] = field;
+                }
+                if (spreadable) {
+                    for (const [property, field] of Object.entries(fields))
+                        properties[property] = own[field];
+                    if (bodyRequired && Array.isArray(schema.required)) {
+                        for (const [property, field] of Object.entries(fields))
+                            if (schema.required.includes(field))
+                                required.push(property);
+                    }
+                    body = { contentType, required: bodyRequired, spread: true, fields };
+                }
+                else {
+                    if ("body" in properties) {
+                        skip("a parameter is already named body");
+                        continue;
+                    }
+                    properties.body = { ...schema, description: clip(String(schema.description ?? requestBody.description ?? "The request body."), MAX_DESCRIPTION) };
+                    if (bodyRequired)
+                        required.push("body");
+                    body = { contentType, required: bodyRequired, spread: false, fields: { body: "body" } };
+                }
+            }
+            let output;
+            if (options.typedOutput && isRecord(op.responses)) {
+                const success = Object.entries(op.responses).find(([status]) => /^2(\d\d|XX)$/i.test(status));
+                const content = success && isRecord(success[1]) && isRecord(success[1].content) ? success[1].content : undefined;
+                const type = content ? Object.keys(content).find((name) => /json/i.test(name)) : undefined;
+                const schema = type && isRecord(content[type]) ? content[type].schema : undefined;
+                if (isRecord(schema))
+                    output = toJsonSchema(schema, false);
+            }
+            operations.push({
+                operationId,
+                method: verb,
+                path,
+                ...(typeof op.summary === "string" ? { summary: op.summary } : {}),
+                ...(typeof op.description === "string" ? { description: op.description } : {}),
+                tags: Array.isArray(op.tags) ? op.tags.filter((tag) => typeof tag === "string") : [],
+                deprecated: op.deprecated === true,
+                parameters,
+                ...(body ? { body } : {}),
+                input: { type: "object", properties, ...(required.length ? { required: [...new Set(required)] } : {}), additionalProperties: false },
+                ...(output ? { output } : {}),
+            });
+        }
+    }
+    return { operations, skipped };
+}
+/** Split a tool's arguments back into what goes in the path, the query, the headers and the body. */
+export function splitInput(operation, args) {
+    const input = { path: {}, query: {}, headers: {} };
+    for (const parameter of operation.parameters) {
+        const value = args[parameter.property];
+        if (value === undefined)
+            continue;
+        if (parameter.in === "header")
+            input.headers[parameter.name] = simple(value, parameter.explode);
+        else
+            input[parameter.in][parameter.name] = value;
+    }
+    if (operation.body) {
+        if (operation.body.spread) {
+            const body = {};
+            for (const [property, field] of Object.entries(operation.body.fields))
+                if (args[property] !== undefined)
+                    body[field] = args[property];
+            if (Object.keys(body).length || operation.body.required)
+                input.body = body;
+        }
+        else if (args.body !== undefined)
+            input.body = args.body;
+    }
+    return input;
+}
+/** Build a tool for every operation in an OpenAPI 3 document. Throws on a pinned document that changed. */
+export function fromOpenAPI(document, options) {
+    if (options.pin) {
+        const actual = openapiHash(document);
+        if (actual !== options.pin.sha256) {
+            throw new Error(`The OpenAPI document changed since it was pinned: expected sha256 ${options.pin.sha256}, got ${actual}. Review what changed, then update pin.sha256.`);
+        }
+    }
+    const { operations } = readOperations(document, { typedOutput: options.typedOutput === true });
+    const include = options.include;
+    const chosen = operations.filter((operation) => include === undefined ? true : typeof include === "function" ? include(operation) : include.includes(operation.operationId));
+    if (Array.isArray(include)) {
+        const missing = include.filter((id) => !operations.some((operation) => operation.operationId === id));
+        if (missing.length)
+            throw new Error(`No operations in the document with these ids: ${missing.join(", ")}.`);
+    }
+    const byName = new Map();
+    const tools = chosen.map((operation) => {
+        const name = options.names?.[operation.operationId] ?? toolName(`${options.prefix ?? ""}${options.prefix ? "_" : ""}${operation.operationId}`);
+        const clash = byName.get(name);
+        if (clash) {
+            throw new Error(`Operations ${clash.operationId} and ${operation.operationId} both become the tool ${name}. Name one of them with options.names.`);
+        }
+        byName.set(name, operation);
+        const risk = options.risk?.[operation.operationId] ?? (READS.has(operation.method) ? "read" : operation.method === "DELETE" ? "destructive" : "write");
+        const summary = operation.summary?.trim();
+        const about = [operation.deprecated ? "Deprecated." : "", summary ?? "", operation.description && operation.description.trim() !== summary ? operation.description : ""]
+            .filter(Boolean)
+            .join(" ");
+        return defineTool({
+            name,
+            title: clip(summary || words(operation.operationId), 60),
+            description: clip(about || `${operation.method} ${operation.path}`, MAX_DESCRIPTION),
+            input: jsonSchema(operation.input),
+            ...(operation.output ? { output: jsonSchema(operation.output) } : {}),
+            risk,
+            tags: [...new Set(operation.tags.map(slug).filter((tag) => /^[a-z0-9][a-z0-9-]*$/.test(tag)))],
+            summary: (args) => {
+                const shown = operation.parameters.filter((parameter) => parameter.in === "path").map((parameter) => String(args[parameter.property]));
+                return `${operation.method} ${operation.path}${shown.length ? ` (${shown.join(", ")})` : ""}`;
+            },
+            handler: (args, ctx) => options.execute(operation, splitInput(operation, args), ctx),
+        });
+    });
+    return tools;
+}
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/**
+ * A query parameter written the way its document says. OpenAPI's default,
+ * form with explode, repeats a key for each list item and spreads an object's
+ * fields into parameters of their own; deepObject writes `key[field]`.
+ */
+function appendQuery(params, parameter, value) {
+    if (value === undefined || value === null)
+        return;
+    const key = parameter.name;
+    if (Array.isArray(value)) {
+        if (parameter.explode)
+            for (const item of value)
+                params.append(key, String(item));
+        else
+            params.append(key, value.map(String).join(parameter.style === "spaceDelimited" ? " " : parameter.style === "pipeDelimited" ? "|" : ","));
+    }
+    else if (typeof value === "object") {
+        const entries = Object.entries(value).filter(([, inner]) => inner !== undefined && inner !== null);
+        if (parameter.style === "deepObject")
+            for (const [field, inner] of entries)
+                params.append(`${key}[${field}]`, typeof inner === "object" ? JSON.stringify(inner) : String(inner));
+        else if (parameter.explode)
+            for (const [field, inner] of entries)
+                params.append(field, String(inner));
+        else
+            params.append(key, entries.flatMap(([field, inner]) => [field, String(inner)]).join(","));
+    }
+    else
+        params.append(key, String(value));
+}
+/** A path or header value in OpenAPI's simple style: lists and objects joined with commas. */
+function simple(value, explode) {
+    if (Array.isArray(value))
+        return value.map(String).join(",");
+    if (value !== null && typeof value === "object") {
+        return Object.entries(value).map(([field, inner]) => (explode ? `${field}=${String(inner)}` : `${field},${String(inner)}`)).join(",");
+    }
+    return String(value);
+}
+/** A form body, with nested objects and lists in the bracket style form APIs read: `metadata[plan]=pro`, `items[0][price]=...`. */
+export function formEncode(body) {
+    const params = new URLSearchParams();
+    const visit = (prefix, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (Array.isArray(value))
+            value.forEach((item, i) => visit(`${prefix}[${i}]`, item));
+        else if (typeof value === "object")
+            for (const [key, inner] of Object.entries(value))
+                visit(prefix ? `${prefix}[${key}]` : key, inner);
+        else
+            params.append(prefix, String(value));
+    };
+    visit("", body);
+    return params.toString();
+}
+/** What an API said went wrong, from the fields error bodies usually carry. */
+function errorMessage(data) {
+    if (typeof data === "string")
+        return data.trim().slice(0, 500) || undefined;
+    if (!isRecord(data))
+        return undefined;
+    const error = data.error;
+    const candidates = [
+        data.message,
+        isRecord(error) ? error.message : error,
+        data.detail,
+        data.title,
+        Array.isArray(data.errors) && isRecord(data.errors[0]) ? data.errors[0].message : undefined,
+    ];
+    const found = candidates.find((candidate) => typeof candidate === "string" && candidate.trim());
+    return found ? String(found).slice(0, 500) : undefined;
+}
+/**
+ * Calls the API over HTTP. Errors come back as Slipway errors with the API's
+ * own message and status, so a model can act on a 404 or a 429 like any other.
+ */
+export function httpExecutor(options) {
+    return async (operation, input, ctx) => {
+        const base = typeof options.baseUrl === "function" ? options.baseUrl(ctx) : options.baseUrl;
+        const root = new URL(base);
+        if (root.protocol !== "https:" && !(root.protocol === "http:" && LOOPBACK.has(root.hostname))) {
+            throw new UsageError(`Refusing to call ${root.origin}: only https, or http to this machine, carries credentials safely.`);
+        }
+        const byName = new Map(operation.parameters.map((parameter) => [`${parameter.in}:${parameter.name}`, parameter]));
+        const path = operation.path.replace(/\{([^}]+)\}/g, (_match, name) => {
+            const value = input.path[name];
+            if (value === undefined || value === null || value === "")
+                throw new UsageError(`${operation.operationId} needs the path parameter ${name}.`);
+            return simple(value, byName.get(`path:${name}`)?.explode ?? false).split(",").map(encodeURIComponent).join(",");
+        });
+        const url = new URL(`${root.href.replace(/\/+$/, "")}${path}`);
+        for (const [name, value] of Object.entries(input.query)) {
+            appendQuery(url.searchParams, byName.get(`query:${name}`) ?? { name, in: "query", required: false, property: name, style: "form", explode: true }, value);
+        }
+        const headers = new Headers({ accept: "application/json" });
+        for (const [key, value] of Object.entries(input.headers))
+            headers.set(key, value);
+        for (const [key, value] of Object.entries((await options.headers?.(ctx)) ?? {}))
+            if (value !== undefined)
+                headers.set(key, value);
+        let body;
+        if (input.body !== undefined) {
+            const form = /x-www-form-urlencoded/i.test(operation.body?.contentType ?? "");
+            body = form ? formEncode(input.body) : JSON.stringify(input.body);
+            headers.set("content-type", form ? "application/x-www-form-urlencoded" : "application/json");
+        }
+        const response = await (options.fetch ?? fetch)(url, { method: operation.method, headers, ...(body === undefined ? {} : { body }), signal: ctx.signal });
+        const text = await response.text();
+        let data = text;
+        if (/json/i.test(response.headers.get("content-type") ?? "") || /^[[{]/.test(text.trim())) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!response.ok) {
+            const retry = Number(response.headers.get("retry-after"));
+            throw httpError(response.status, errorMessage(data) ?? `${operation.method} ${operation.path} failed: ${response.status} ${response.statusText}`.trim(), {
+                details: data,
+                ...(Number.isFinite(retry) && retry > 0 ? { retryAfterSeconds: retry } : {}),
+            });
+        }
+        if (text.trim() === "")
+            return { ok: true, status: response.status };
+        return data;
+    };
+}

package/dist/pages.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Following a list to its end.
+ *
+ * A cursor-paginated tool says where its cursor and its items are, so the CLI's
+ * `--all` and `data sync` can walk every page the same way, instead of each
+ * leaving the loop to a script or a model.
+ */
+import type { App, InvokeOptions } from "./app.js";
+import type { Tool } from "./tool.js";
+export declare function getPath(data: unknown, path: string): unknown;
+export type PagesRun = {
+    count: number;
+    pages: number;
+    next_cursor: unknown;
+    complete: boolean;
+};
+/**
+ * Call a tool page after page, handing each page's items to `onPage`, until the
+ * pages run out or `max` items arrived. A tool that does not page is called
+ * once. `complete` is true when the list ended, not the item limit.
+ */
+export declare function eachPage(app: App, tool: Tool, args: Record<string, unknown>, options: InvokeOptions, itemsPath: string, max: number, onPage: (items: unknown[]) => void | Promise<void>): Promise<PagesRun>;

package/dist/pages.js

@@ -0,0 +1,61 @@
+/**
+ * Following a list to its end.
+ *
+ * A cursor-paginated tool says where its cursor and its items are, so the CLI's
+ * `--all` and `data sync` can walk every page the same way, instead of each
+ * leaving the loop to a script or a model.
+ */
+import { EXIT, SlipwayError } from "./errors.js";
+import { isContentResult } from "./result.js";
+export function getPath(data, path) {
+    let current = data;
+    for (const part of path.split(".").filter(Boolean)) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** A hard ceiling, so an API that keeps returning a new cursor forever cannot spin forever. */
+const MAX_PAGES = 10_000;
+/**
+ * Call a tool page after page, handing each page's items to `onPage`, until the
+ * pages run out or `max` items arrived. A tool that does not page is called
+ * once. `complete` is true when the list ended, not the item limit.
+ */
+export async function eachPage(app, tool, args, options, itemsPath, max, onPage) {
+    const paginate = tool.paginate;
+    let count = 0;
+    let pages = 0;
+    let cursor = paginate ? args[paginate.cursorArg] : undefined;
+    for (;;) {
+        const pageArgs = { ...args };
+        if (paginate) {
+            if (cursor !== undefined && cursor !== null && cursor !== "")
+                pageArgs[paginate.cursorArg] = cursor;
+            else
+                delete pageArgs[paginate.cursorArg];
+            if (paginate.limitArg && paginate.maxLimit && pageArgs[paginate.limitArg] === undefined) {
+                pageArgs[paginate.limitArg] = Math.max(1, Math.min(paginate.maxLimit, max - count));
+            }
+        }
+        const value = await app.invoke(tool.name, pageArgs, options);
+        const data = isContentResult(value) ? value.data : value;
+        const page = getPath(data, itemsPath);
+        if (!Array.isArray(page))
+            throw new SlipwayError(`${tool.name} returned no list at '${itemsPath}'.`, "internal", EXIT.error);
+        const kept = page.slice(0, Math.max(0, max - count));
+        await onPage(kept);
+        count += kept.length;
+        pages++;
+        if (!paginate)
+            return { count, pages, next_cursor: null, complete: kept.length === page.length };
+        const next = getPath(data, paginate.nextCursor);
+        const ended = next === undefined || next === null || next === "" || next === cursor;
+        if (ended)
+            return { count, pages, next_cursor: null, complete: true };
+        cursor = next;
+        if (count >= max || pages >= MAX_PAGES)
+            return { count, pages, next_cursor: cursor ?? null, complete: false };
+    }
+}