@zackbart/connecta 0.30.0 → 0.32.0

package/dist/providers/_shared/rest/operation-index.js

@@ -0,0 +1,527 @@
+// The pinned operation index a REST connector validates against before it
+// sends anything. `scripts/generate-openapi.mjs` compiles a vendor's OpenAPI
+// document into `OpenApiData` (search rows plus request-side details as one
+// lazily parsed JSON string); this module reads it. Nothing here does I/O.
+//
+// The index is the contract: a path no operation matches is refused with the
+// nearest operations, and query or body names the operation does not declare
+// are refused with the accepted names, because a guessed argument is the most
+// common way an agent wastes a call. Drift between the pin and the vendor is
+// caught by `providers:check` and refreshed by `providers:spec`.
+import { ConnectorCallError } from "../../../errors.js";
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+const MAX_ISSUES = 20;
+function words(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalid(message, issues, repair) {
+    throw new ConnectorCallError("invalid_args", message, {
+        ...(issues ? { validation: { issues } } : {}),
+        ...(repair ? { repair } : {}),
+    });
+}
+function typesOf(node) {
+    return node.t === undefined ? [] : typeof node.t === "string" ? [node.t] : node.t;
+}
+/** Edit distance, for naming the parameter a misspelling meant. */
+function distance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** The accepted names, bounded and led by the likeliest intended one; repair details carry the full list. */
+function oneOf(names, given) {
+    const close = given === undefined
+        ? undefined
+        : names
+            .map((name) => ({ name, cost: distance(given.toLowerCase(), name.toLowerCase()) }))
+            .filter(({ cost }) => cost <= Math.max(2, Math.floor(given.length / 3)))
+            .sort((a, b) => a.cost - b.cost)[0]?.name;
+    const shown = names.slice(0, 12).join(", ");
+    const list = names.length > 12 ? `one of ${shown}, … (${names.length} in all)` : `one of ${shown}`;
+    return close ? `${close}? ${list}` : list;
+}
+function valueType(value) {
+    return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+/**
+ * Split a caller's path into segments, refusing anything that could resolve
+ * somewhere other than the operation it was validated as: dot segments in any
+ * spelling (the URL parser treats `%2e%2e` as `..`), encoded separators,
+ * empty segments, control characters, and unfilled `{placeholders}`.
+ */
+function segmentsOf(path, title, search, slashes) {
+    if (typeof path !== "string" || !path.startsWith("/")) {
+        invalid(`A ${title} path begins with "/" and names one API operation, such as one ${search} returned.`);
+    }
+    if (/[?#]/.test(path))
+        invalid(`A ${title} path carries no query or fragment; put query parameters in query.`);
+    const segments = path.slice(1).split("/");
+    for (const [index, segment] of segments.entries()) {
+        if (segment === "")
+            invalid(`A ${title} path has no empty segments or trailing slash.`);
+        if (/[{}]/.test(segment)) {
+            invalid(`The ${title} path still contains a {placeholder}; substitute the real id from an earlier result.`);
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            return invalid(`A ${title} path segment is not valid percent-encoding.`);
+        }
+        const control = [...decoded].some((character) => character.charCodeAt(0) < 0x20 || character === "\u007f");
+        // An encoded "/" is held for the match to decide (see `resolve`): only a
+        // last segment filling a reviewed slash parameter may carry one, and none
+        // of its pieces may be empty or a dot segment.
+        const slashed = slashes !== undefined &&
+            decoded.includes("/") &&
+            decoded.split("/").every((piece) => piece !== "" && piece !== "." && piece !== "..");
+        if (slashed)
+            slashes.add(index);
+        if (decoded === "." ||
+            decoded === ".." ||
+            decoded.includes("\\") ||
+            (decoded.includes("/") && !slashed) ||
+            control) {
+            invalid(`A ${title} path segment may not be a dot segment, an encoded separator, or a control character.`);
+        }
+    }
+    return segments;
+}
+/** The read side of one vendor's pinned index. */
+export class OperationIndex {
+    version;
+    revision;
+    ops;
+    /** The methods any operation uses, in a stable order. */
+    methods;
+    #data;
+    #title;
+    #vendor;
+    #segments;
+    #slashParams;
+    #details;
+    #words;
+    /**
+     * `vendor` is the tool-name prefix; `title` the display name in refusals.
+     * `slashParams` names path parameters whose values may carry an encoded
+     * "/" (`%2F`), such as an object key, and only as the path's last segment.
+     */
+    constructor(data, names) {
+        const { title } = names;
+        this.#slashParams = new Set(names.slashParams ?? []);
+        this.#data = data;
+        this.#title = title;
+        this.#vendor = names.vendor;
+        this.version = data.version;
+        this.revision = data.revision;
+        this.ops = data.ops.map(([method, path, operationId, summary, tag, server], row) => {
+            if (!METHODS.has(method))
+                throw new Error(`${title} operation index row ${row} has unsupported method ${method}.`);
+            return Object.freeze({
+                method: method,
+                path,
+                operationId,
+                summary,
+                tag: data.tags[tag] ?? "",
+                server: server === undefined ? undefined : data.servers[server],
+                row,
+            });
+        });
+        this.#segments = this.ops.map((op) => op.path.slice(1).split("/"));
+        this.methods = [...METHODS].filter((method) => this.ops.some((op) => op.method === method));
+    }
+    /** The operation with this exact method and path template, if any. */
+    operation(method, template) {
+        return this.ops.find((op) => op.method === method && op.path === template);
+    }
+    /**
+     * Match a concrete call to its operation. Literal segments outrank
+     * parameters, as OpenAPI requires (`/v1/customers/search` before
+     * `/v1/customers/{customer}`); the most specific template that fits decides,
+     * and a method it does not define is refused rather than retried against a
+     * looser template.
+     */
+    resolve(method, path) {
+        const slashes = this.#slashParams.size > 0 ? new Set() : undefined;
+        const segments = segmentsOf(path, this.#title, this.#vendorTool("search"), slashes);
+        let best = { score: -1, rows: [] };
+        this.#segments.forEach((template, row) => {
+            if (template.length !== segments.length)
+                return;
+            let score = 0;
+            for (const [index, part] of template.entries()) {
+                if (part.startsWith("{"))
+                    continue;
+                if (part !== segments[index])
+                    return;
+                score += 1;
+            }
+            if (score > best.score)
+                best = { score, rows: [row] };
+            else if (score === best.score)
+                best.rows.push(row);
+        });
+        if (best.rows.length === 0) {
+            invalid(`${this.#title} has no ${path} operation in the pinned API index (${this.revision}). ` +
+                `Nearest: ${this.nearest(method, segments).join("; ")}. Find operations with ${this.#vendorTool("search")}.`);
+        }
+        const templates = new Set(best.rows.map((row) => this.ops[row].path));
+        const op = best.rows.map((row) => this.ops[row]).find((candidate) => candidate.method === method);
+        if (!op) {
+            const allowed = [...new Set(best.rows.map((row) => this.ops[row].method))].join(", ");
+            invalid(`${this.#title} ${[...templates].join(" or ")} accepts ${allowed}, not ${method}.`);
+        }
+        const template = this.#segments[op.row];
+        for (const index of slashes ?? []) {
+            const part = template[index];
+            if (index !== template.length - 1 || !part.startsWith("{") || !this.#slashParams.has(part.slice(1, -1))) {
+                invalid(`A ${this.#title} path segment may not be a dot segment, an encoded separator, or a control character.`);
+            }
+        }
+        const params = {};
+        template.forEach((part, index) => {
+            if (part.startsWith("{"))
+                params[part.slice(1, -1)] = segments[index];
+        });
+        return { op, params };
+    }
+    /** Up to five operations whose paths most resemble a missed one. */
+    nearest(method, segments) {
+        // Shared leading characters, so `customer` sits next to `customers`.
+        const likeness = (a, b) => {
+            let same = 0;
+            while (same < a.length && same < b.length && a[same] === b[same])
+                same += 1;
+            return same / Math.max(a.length, b.length, 1);
+        };
+        const scored = this.ops.map((op) => {
+            const template = this.#segments[op.row];
+            let score = 0;
+            for (let index = 0; index < Math.min(template.length, segments.length); index += 1) {
+                const part = template[index];
+                score += part.startsWith("{") ? 0.6 : likeness(part, segments[index]) * 2;
+            }
+            score -= Math.abs(template.length - segments.length) * 0.75;
+            if (op.method === method)
+                score += 0.25;
+            return { op, score };
+        });
+        return scored
+            .sort((a, b) => b.score - a.score || a.op.path.length - b.op.path.length)
+            .slice(0, 5)
+            .map(({ op }) => `${op.method} ${op.path}`);
+    }
+    /**
+     * Rank operations for a free-text query: every query word must appear in
+     * the path, summary, operationId, or tag (plural-insensitive, prefixes of
+     * three letters count), and path matches weigh most. A query that starts
+     * with "/" also matches the templates that fit it.
+     */
+    search(query, options) {
+        this.#words ??= this.ops.map((op) => ({
+            path: new Set(op.path
+                .split("/")
+                .filter((part) => !part.startsWith("{"))
+                .flatMap(words)
+                .concat(words(op.tag))),
+            summary: new Set(words(op.summary)),
+            id: new Set(words(op.operationId)),
+        }));
+        const terms = [...new Set(words(query))];
+        const candidates = this.ops.filter((op) => options.method === undefined || op.method === options.method);
+        const fits = new Set();
+        if (query.trim().startsWith("/")) {
+            const path = query.trim().split(/\s/)[0];
+            for (const op of candidates) {
+                try {
+                    if (this.resolve(op.method, path).op.row === op.row)
+                        fits.add(op.row);
+                }
+                catch {
+                    // Not this template.
+                }
+            }
+        }
+        const match = (set, term) => {
+            if (set.has(term))
+                return 2;
+            for (const word of set) {
+                if (word === `${term}s` || term === `${word}s` || word === `${term}es` || term === `${word}es`)
+                    return 2;
+                if (term.length >= 3 && word.startsWith(term))
+                    return 1;
+            }
+            return 0;
+        };
+        const ranked = candidates.flatMap((op) => {
+            const indexed = this.#words[op.row];
+            let score = fits.has(op.row) ? 100 : 0;
+            let matched = 0;
+            for (const term of terms) {
+                const path = match(indexed.path, term);
+                const summary = match(indexed.summary, term);
+                const id = match(indexed.id, term);
+                if (path + summary + id > 0)
+                    matched += 1;
+                score += path * 3 + summary * 1.5 + id;
+            }
+            if (!fits.has(op.row) && (terms.length === 0 || matched < terms.length))
+                return [];
+            return [{ op, score }];
+        });
+        return ranked
+            .sort((a, b) => b.score - a.score ||
+            a.op.path.split("/").length - b.op.path.split("/").length ||
+            a.op.path.localeCompare(b.op.path))
+            .slice(0, options.limit)
+            .map(({ op }) => op);
+    }
+    /** Whether the operation takes a body, and in which framing. */
+    bodyType(op) {
+        const row = this.#row(op);
+        return row && row[1] !== 0 ? row[1][0] : undefined;
+    }
+    /** The operation's request contract as JSON Schema, optionally one parameter only. */
+    contract(op, only) {
+        const row = this.#row(op);
+        const declared = row ? row[0] : [];
+        // A generator may omit plain-string path parameters (`pathParams:
+        // "typed"`); the template still names them, so the contract does too.
+        const implied = this.#segments[op.row].filter((part) => part.startsWith("{") && !declared.some(([name, at]) => at === "path" && name === part.slice(1, -1)))
+            .map((part) => [part.slice(1, -1), "path", 1, { t: "string" }]);
+        const parameters = [...implied, ...declared]
+            .filter(([name]) => only === undefined || name === only)
+            .map(([name, at, required, schema, description]) => ({
+            name,
+            in: at,
+            required: required === 1,
+            ...(description ? { description } : {}),
+            schema: this.#schema(schema),
+        }));
+        let body;
+        if (row && row[1] !== 0) {
+            const [contentType, schema] = row[1];
+            const node = this.#deref(schema);
+            if (only !== undefined && node.p?.[only] !== undefined) {
+                body = {
+                    contentType,
+                    schema: {
+                        type: "object",
+                        properties: { [only]: this.#schema(node.p[only]) },
+                        ...(node.r?.includes(only) ? { required: [only] } : {}),
+                    },
+                };
+            }
+            else if (only === undefined) {
+                body = { contentType, ...(row[1][2] === 1 ? { required: true } : {}), schema: this.#schema(schema) };
+            }
+        }
+        if (only !== undefined && parameters.length === 0 && body === undefined) {
+            invalid(`${op.method} ${op.path} has no parameter named ${only}.`);
+        }
+        return {
+            method: op.method,
+            path: op.path,
+            operationId: op.operationId,
+            summary: op.summary,
+            ...(op.server ? { server: op.server } : {}),
+            parameters,
+            ...(body ? { body } : {}),
+        };
+    }
+    /**
+     * Check query and body names, required members, enums, and object/array
+     * shapes against the operation, to the depth the index carries. Scalars are
+     * not type-policed beyond that: vendors coerce form strings, and a wrong
+     * number is the vendor's to explain. `null` and `""` pass anywhere, since
+     * they are how form APIs unset a field.
+     */
+    check(op, query, body) {
+        const row = this.#row(op);
+        const issues = [];
+        const repair = [];
+        const declared = (row ? row[0] : []).filter(([, at]) => at === "query");
+        const accepted = declared.map(([name]) => name);
+        for (const [name, value] of Object.entries(query)) {
+            if (value === undefined)
+                continue;
+            const param = declared.find(([key]) => key === name);
+            if (!param) {
+                issues.push({
+                    path: `/query/${name}`,
+                    code: "additionalProperties",
+                    expected: accepted.length ? oneOf(accepted, name) : "no query parameters",
+                });
+                repair.push({ path: `/query/${name}`, receivedType: valueType(value), acceptedKeys: accepted });
+                continue;
+            }
+            this.#check(param[3], value, `/query/${name}`, issues, repair);
+        }
+        for (const [name, , required] of declared) {
+            if (required === 1 && query[name] === undefined) {
+                issues.push({ path: `/query/${name}`, code: "required", expected: "a value" });
+            }
+        }
+        const bodyRow = row && row[1] !== 0 ? row[1] : undefined;
+        if (body !== undefined) {
+            if (!bodyRow) {
+                issues.push({ path: "/body", code: "false", expected: "no body for this operation" });
+            }
+            else {
+                this.#check(bodyRow[1], body, "/body", issues, repair);
+            }
+        }
+        else if (bodyRow?.[2] === 1) {
+            // An optional body may be omitted whole; a required one may not.
+            issues.push({ path: "/body", code: "required", expected: `a ${bodyRow[0]} body` });
+        }
+        if (issues.length > 0) {
+            const shown = issues
+                .slice(0, 5)
+                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .join("; ");
+            invalid(`Not sent: the arguments do not match ${op.method} ${op.path} in the pinned API index: ${shown}` +
+                `${issues.length > 5 ? `; ${issues.length - 5} more` : ""}. Read ${this.#vendorTool("details")} for the contract.`, issues.slice(0, MAX_ISSUES), repair.length ? { issues: repair.slice(0, 5) } : undefined);
+        }
+    }
+    #vendorTool(kind) {
+        return `${this.#vendor}_api_${kind}`;
+    }
+    #row(op) {
+        this.#details ??= JSON.parse(this.#data.details);
+        const row = this.#details.o[op.row];
+        return row === 0 ? undefined : row;
+    }
+    #deref(node) {
+        let current = node;
+        for (let hops = 0; current.$ !== undefined && hops < 32; hops += 1) {
+            current = this.#details.d[current.$] ?? {};
+        }
+        return current;
+    }
+    #schema(node) {
+        const resolved = this.#deref(node);
+        const out = {};
+        if (resolved.t !== undefined)
+            out["type"] = resolved.t;
+        if (resolved.d !== undefined)
+            out["description"] = resolved.d;
+        if (resolved.e !== undefined)
+            out["enum"] = resolved.e;
+        if (resolved.f !== undefined)
+            out["format"] = resolved.f;
+        if (resolved.n === 1)
+            out["nullable"] = true;
+        if (resolved.a)
+            out["anyOf"] = resolved.a.map((branch) => this.#schema(branch));
+        if (resolved.p) {
+            out["properties"] = Object.fromEntries(Object.entries(resolved.p).map(([key, value]) => [key, this.#schema(value)]));
+        }
+        if (resolved.r)
+            out["required"] = resolved.r;
+        if (resolved.i)
+            out["items"] = this.#schema(resolved.i);
+        if (resolved.m)
+            out["additionalProperties"] = this.#schema(resolved.m);
+        if (resolved.x === 1)
+            out["truncated"] = true;
+        return out;
+    }
+    #check(node, value, at, issues, repair) {
+        if (issues.length >= MAX_ISSUES)
+            return;
+        const schema = this.#deref(node);
+        if (schema.x === 1)
+            return;
+        // Conflicting composed constraints (disjoint enums or types) admit nothing,
+        // not even the null or "" that otherwise unsets a field.
+        if (schema.e?.length === 0) {
+            issues.push({ path: at, code: "enum", expected: "no value: this field's combined constraints admit none" });
+            return;
+        }
+        if (value === null || value === "")
+            return;
+        if (schema.a) {
+            let fewest;
+            for (const branch of schema.a) {
+                const attempt = { issues: [], repair: [] };
+                this.#check(branch, value, at, attempt.issues, attempt.repair);
+                if (attempt.issues.length === 0)
+                    return;
+                if (!fewest || attempt.issues.length < fewest.issues.length)
+                    fewest = attempt;
+            }
+            if (fewest) {
+                issues.push(...fewest.issues);
+                repair.push(...fewest.repair);
+            }
+            return;
+        }
+        const types = typesOf(schema);
+        if (schema.e && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
+            if (!schema.e.some((option) => option === value || String(option) === String(value))) {
+                issues.push({ path: at, code: "enum", expected: oneOf(schema.e.map(String)) });
+            }
+            return;
+        }
+        if (schema.p || types.includes("object")) {
+            if (!isRecord(value)) {
+                if (types.length === 0 || types.includes("object")) {
+                    issues.push({ path: at, code: "type", expected: "object" });
+                }
+                return;
+            }
+            const properties = schema.p ?? {};
+            const accepted = Object.keys(properties);
+            for (const [key, item] of Object.entries(value)) {
+                if (item === undefined)
+                    continue;
+                const child = properties[key];
+                if (child)
+                    this.#check(child, item, `${at}/${key}`, issues, repair);
+                else if (schema.m)
+                    this.#check(schema.m, item, `${at}/${key}`, issues, repair);
+                else if (schema.p) {
+                    issues.push({
+                        path: `${at}/${key}`,
+                        code: "additionalProperties",
+                        expected: accepted.length ? oneOf(accepted, key) : "no properties",
+                    });
+                    repair.push({ path: `${at}/${key}`, receivedType: valueType(item), acceptedKeys: accepted });
+                }
+            }
+            for (const key of schema.r ?? []) {
+                if (value[key] === undefined)
+                    issues.push({ path: `${at}/${key}`, code: "required", expected: "a value" });
+            }
+            return;
+        }
+        if (schema.i || types.includes("array")) {
+            if (!Array.isArray(value)) {
+                issues.push({ path: at, code: "type", expected: "array" });
+                return;
+            }
+            if (schema.i)
+                value.forEach((item, index) => this.#check(schema.i, item, `${at}/${index}`, issues, repair));
+            return;
+        }
+        if (types.length > 0 && (isRecord(value) || Array.isArray(value))) {
+            issues.push({ path: at, code: "type", expected: types.join(" or ") });
+        }
+    }
+}

package/dist/providers/_shared/rest/tools.d.ts

@@ -0,0 +1,141 @@
+import type { ApiTool } from "../../../connectors/api-connector.js";
+import { type GuardedFetchOptions, type GuardedRequest, type GuardedTransport } from "../../../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../../../errors.js";
+import type { ConnectorContext } from "../../../types.js";
+import type { Operation, OperationIndex, RestMethod } from "./operation-index.js";
+import type { ValueSafety } from "./value-safety.js";
+/** One call matched to its operation, after the vendor's defaults and pins. */
+export interface RestCall {
+    readonly method: RestMethod;
+    /** The concrete path the caller named. */
+    readonly path: string;
+    readonly op: Operation;
+    /** Path parameter values by template name. */
+    readonly params: Readonly<Record<string, string>>;
+    readonly query: Readonly<Record<string, unknown>>;
+    readonly body: unknown;
+    /** Request headers from the vendor's reviewed `headers` allowlist. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** How the vendor frames one call on the wire. */
+export interface RestFraming {
+    query?: GuardedRequest["query"];
+    /** A JSON body; exclusive with `rawBody`. */
+    body?: unknown;
+    /** A pre-framed body, such as a form-encoded string, with its own `Content-Type` header. */
+    rawBody?: BodyInit;
+    headers?: Record<string, string | undefined>;
+}
+/**
+ * The cursor for the next page: pass `next` back as `param`, a query
+ * parameter unless `in` says the operation takes it in its body (Notion's
+ * read-only POST queries do). `path` names a different GET that continues
+ * the list, when the first page came from a call that created it (Notion's
+ * view queries). `hasMore` without `next` means the operation has no cursor.
+ */
+export interface RestPage {
+    hasMore: boolean;
+    next?: string;
+    param?: string;
+    in?: "query" | "body";
+    path?: string;
+}
+export interface RestResult {
+    status: number;
+    data: unknown;
+    page?: RestPage;
+}
+/** A reviewed POST that only reads: `[method, path template, reason]`. */
+export type RestReadPost = readonly [method: RestMethod, path: string, reason: string];
+export interface RestVendor {
+    /** Lowercase tool-name prefix: `${vendor}_api_search` and so on. */
+    readonly vendor: string;
+    /** Display name in descriptions and refusals. */
+    readonly title: string;
+    readonly index: OperationIndex;
+    /**
+     * The transport for an operation's server (`undefined` is the default
+     * origin), or a refusal that says where to go instead.
+     */
+    transport(server: string | undefined): GuardedTransport | string;
+    /** Map a failed response to what the caller does next (H11); `call` lets a vendor withhold text for secret families. */
+    failure(status: number, headers: Headers, body: unknown, call?: RestCall): ConnectorCallError;
+    /** Reviewed POSTs that only read; `_api_read` admits exactly these. */
+    readonly readPosts?: readonly RestReadPost[];
+    /**
+     * The vendor's reviewed value-safety table: `refuse` verdicts are refused
+     * by the generic tools before any request, and every successful body is
+     * redacted (decision 0005, "Value safety"). Failure mappers ask it which
+     * operations withhold vendor error text.
+     */
+    readonly valueSafety: ValueSafety;
+    /** Reviewed refusals that depend on arguments: return the reason to refuse, before any request. */
+    refuse?(call: RestCall): string | undefined;
+    /** Rewrite a caller's path before it is matched, such as filling configured default ids. */
+    path?(path: string): string;
+    /** Apply configured defaults and enforce pins; throw to refuse. */
+    scope?(call: RestCall): RestCall;
+    /**
+     * Admit one prepared call before it is sent; throw to refuse. Runs in
+     * `callRest`, so generic and named tools alike pass through it, and may
+     * await, as a pin check that resolves which account owns a zone does.
+     */
+    admit?(call: RestCall, ctx: ConnectorContext): void | Promise<void>;
+    /**
+     * Map a successful body into the envelope's `data`, such as unwrapping a
+     * vendor envelope; throw to fail a success-status body that reports an
+     * error. `page` still reads the body as it arrived.
+     */
+    result?(body: unknown, call: RestCall, response: {
+        status: number;
+        headers: Headers;
+    }): unknown;
+    /** Request headers the generic tools accept, by name, with what each does; the vendor validates values. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Whether the generic tools accept a string body, for operations framed as text. */
+    readonly textBodies?: boolean;
+    /** A concrete path in this vendor's API, for the path argument's description. */
+    readonly pathExample?: string;
+    /** Frame the request. Defaults to scalar query values and a JSON body. */
+    encode?(call: RestCall): RestFraming;
+    /** Read the next-page cursor from a successful body. */
+    page?(data: unknown, call: RestCall): RestPage | undefined;
+    /** A header write tools fill with a caller key or a generated one, and return. */
+    readonly idempotencyHeader?: string;
+    /** Where multipart or binary uploads go instead of `_api_write`. */
+    readonly upload?: string;
+    /** One clause on how `_api_write` frames bodies, for its schema. */
+    readonly bodyHint?: string;
+}
+/**
+ * A guarded transport whose requests, response bodies included, end after
+ * `timeoutMs`: a stream the vendor never closes cannot hold a call open past
+ * it. The request's own signal still cancels first.
+ */
+export declare function restTransport(options: Omit<GuardedFetchOptions, "fetch"> & {
+    timeoutMs: number;
+}): GuardedTransport;
+/** Match a call to its operation and apply the vendor's defaults and pins. */
+export declare function restCall(vendor: RestVendor, method: RestMethod, path: string, input?: {
+    query?: Readonly<Record<string, unknown>>;
+    body?: unknown;
+    headers?: Readonly<Record<string, string>>;
+}): RestCall;
+/**
+ * A request that is not safe to repeat (a write without an idempotency key)
+ * must never be advertised as retryable after it may have reached the vendor
+ * (INV-9). Definite answers pass through: refusals and 4xx verdicts, a failure
+ * proven to precede any connection, and timeouts, which the invocation layer
+ * already reports as `write_outcome_unknown`. Exported so a named write tool
+ * with its own transport (an upload) applies the same rule.
+ */
+export declare function unknownOutcome(vendor: RestVendor, error: unknown, responded: boolean): unknown;
+/**
+ * Send one prepared call and read it into the envelope. No validation and no
+ * refusal tables run here: the generic tools do both first, and named tools
+ * build their calls from fixed operations. `visibleHeaders` carry values the
+ * result returns to the caller, such as an idempotency key.
+ */
+export declare function callRest(vendor: RestVendor, call: RestCall, ctx: ConnectorContext, visibleHeaders?: Record<string, string>): Promise<RestResult>;
+/** The four generic tools over one vendor's index. */
+export declare function restTools(vendor: RestVendor): ApiTool[];