@zackbart/connecta 0.35.0 → 0.36.1

package/dist/providers/_shared/rest/tools.js

@@ -1,592 +0,0 @@
-// Connecta's generic REST connector over one vendor's pinned operation index.
-//
-// `restTools(vendor)` returns four tools named `<vendor>_api_search`,
-// `_api_details`, `_api_read`, and `_api_write`. The first two read the index
-// and send nothing. `_api_read` sends GET, plus the vendor's reviewed
-// read-only POSTs; classification is per tool name, so that rule is enforced
-// here in the handler, not inferred. `_api_write` sends every other method and
-// is always destructive, with `method` and `path` top-level arguments so a
-// host's approval prompt shows them.
-//
-// Every call is matched to an operation and checked against its contract
-// before transport (unknown path → nearest operations; unknown or missing
-// parameters → `validation.issues`), then the vendor's reviewed refusals run,
-// then the vendor frames the request. Every vendor answers in one envelope:
-// `{ status, data, page?: { hasMore, next?, param? } }`, with an optional
-// `select` projection and no default projection. A write is dispatched once
-// (INV-9): nothing here retries it or replays it against another
-// implementation.
-//
-// A vendor adopts this module with configuration only: its transport, its
-// failure mapper, and optional `scope` (defaults and pins), `encode` (body
-// and query framing), `page` (cursor extraction), `refuse` (argument-dependent refusals),
-// `readPosts`, and an idempotency header. Every vendor ships a reviewed
-// value-safety table (`valueSafety`, `value-safety.ts` here): its refusals run
-// in the generic tools before any request, and its redaction runs on every
-// successful body in `callRest`, after `result` and before cursors and
-// `select`. Optional hooks cover the rest: `path` (fill default ids before
-// matching), `admit` (an awaited check in `callRest`, which every tool passes,
-// such as an account pin), `result` (unwrap a vendor envelope), a reviewed
-// `headers` allowlist, and `textBodies`. Named tools reuse `restCall` and
-// `callRest` to share the same validation-free request path.
-import { callClassification } from "../../../call-classification.js";
-import { providerFailureMessage } from "../../../write-outcome.js";
-import { guardedFetch, } from "../../../connectors/guarded-fetch.js";
-import { IDEMPOTENCY_KEY_MAX_LENGTH, recordRecovery } from "../../../call-recovery.js";
-import { providerRequests } from "../../../provider-call.js";
-import { ConnectorCallError, keyResendAdvice, unavailableCallError } from "../../../errors.js";
-import { encodeForAgent, redactBeforeCut } from "../../../sent-secrets.js";
-const READ = { readOnlyHint: true };
-const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
-const MAX_SELECT = 50;
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function invalid(message) {
-    throw new ConnectorCallError("invalid_args", message);
-}
-/** A header value as fetch sends it: leading and trailing HTTP whitespace removed. */
-function sentValue(value) {
-    return value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "");
-}
-/**
- * Why fetch would not send `value` as a header value the vendor receives:
- * blank once trimmed, or a byte fetch rejects (CR, LF, NUL, any other control
- * character but tab, DEL, or a code point past Latin-1). Undici refuses the
- * whole request for any of them; workerd at least for CR, LF and NUL.
- */
-function unsendableKey(value) {
-    const sent = sentValue(value);
-    if (sent === "")
-        return "is blank; pass a key with at least one non-whitespace character";
-    if (!/^[\t\x20-\x7e\x80-\xff]*$/.test(sent))
-        return "contains a character an HTTP header cannot carry (a control character, or one past Latin-1); pass a printable key";
-    return undefined;
-}
-/**
- * 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 function restTransport(options) {
-    const { timeoutMs, ...rest } = options;
-    return guardedFetch({
-        ...rest,
-        fetch: (url, init) => {
-            const cap = AbortSignal.timeout(timeoutMs);
-            return fetch(url, { ...init, signal: init.signal ? AbortSignal.any([init.signal, cap]) : cap });
-        },
-    });
-}
-/** Match a call to its operation and apply the vendor's defaults and pins. */
-export function restCall(vendor, method, path, input = {}) {
-    const concrete = vendor.path ? vendor.path(path) : path;
-    const { op, params } = vendor.index.resolve(method, concrete);
-    const call = {
-        method: op.method,
-        path: concrete,
-        op,
-        params,
-        query: input.query ?? {},
-        body: input.body,
-        ...(input.headers ? { headers: input.headers } : {}),
-    };
-    return vendor.scope ? vendor.scope(call) : call;
-}
-function defaultFraming(vendor, call) {
-    const query = {};
-    for (const [name, value] of Object.entries(call.query)) {
-        if (value === undefined)
-            continue;
-        const scalar = (item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean";
-        if (scalar(value) || (Array.isArray(value) && value.every(scalar)))
-            query[name] = value;
-        else
-            invalid(`${vendor.title} query parameter ${name} takes a string, number, boolean, or a list of them.`);
-    }
-    return {
-        query,
-        ...(call.headers ? { headers: { ...call.headers } } : {}),
-        ...(call.body !== undefined ? { body: call.body } : {}),
-    };
-}
-async function failureBody(response) {
-    try {
-        const parsed = await response.jsonResult();
-        return "value" in parsed ? parsed.value : undefined;
-    }
-    catch {
-        // An unreadable or oversized error body still has a status to map.
-        return undefined;
-    }
-}
-async function successBody(vendor, response, ctx) {
-    const type = (response.headers.get("content-type") ?? "").toLowerCase();
-    try {
-        if (/\b(?:x-ndjson|jsonl|stream\+json)\b/.test(type)) {
-            return (await response.text())
-                .split("\n")
-                .filter((line) => line.trim() !== "")
-                .map((line) => {
-                try {
-                    return JSON.parse(line);
-                }
-                catch {
-                    return { line };
-                }
-            });
-        }
-        if (/\bjson\b|\+json\b/.test(type)) {
-            // Read, then parse: a read that times out must not pass for malformed JSON.
-            const body = await response.text();
-            if (body.trim() === "")
-                return null;
-            try {
-                return JSON.parse(body);
-            }
-            catch {
-                throw new ConnectorCallError("connector_call_failed", `${vendor.title} returned malformed JSON.`, {
-                    retryable: false,
-                });
-            }
-        }
-        if (type === "" || /^text\/|\bxml\b|\bcsv\b/.test(type)) {
-            const text = await response.text();
-            return text === "" ? null : text;
-        }
-        const bytes = await response.bytes();
-        // Checked before encoding: no later pass reads through base64 a field does not declare.
-        return bytes.length === 0 ? null : { contentType: type, bytes: bytes.length, base64: encodeForAgent(ctx, bytes) };
-    }
-    catch (error) {
-        if (error instanceof ConnectorCallError)
-            throw error;
-        if (ctx.signal?.aborted === true && error === ctx.signal.reason)
-            throw error;
-        if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
-            throw new ConnectorCallError("unavailable", `${vendor.title} did not finish its response within the read cap.`, {
-                details: { code: "timeout" },
-            });
-        }
-        // The request was sent and the status arrived; only the body was lost. Told
-        // in Connecta's words (the runtime's can quote the transport), never raw.
-        // `callRest` decides whether that is safe to repeat.
-        throw unavailableCallError(error, undefined, `${vendor.title} answered, but its response could not be read.`);
-    }
-}
-/**
- * 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 async function callRest(vendor, call, ctx, visibleHeaders = {}) {
-    const send = vendor.transport(call.op.server);
-    if (typeof send === "string")
-        invalid(send);
-    await vendor.admit?.(call, ctx);
-    const framing = vendor.encode ? vendor.encode(call) : defaultFraming(vendor, call);
-    const header = vendor.idempotencyHeader?.toLowerCase();
-    const idempotencyKey = header === undefined
-        ? undefined
-        : Object.entries(visibleHeaders).find(([name, value]) => name.toLowerCase() === header && unsendableKey(value) === undefined)?.[1];
-    const request = {
-        method: call.method,
-        classification: call.method === "GET" ||
-            call.method === "HEAD" ||
-            (vendor.readPosts ?? []).some(([method, path]) => method === call.method && path === call.op.path)
-            ? "read"
-            : "write",
-        // Only a key the vendor receives proves the write repeatable.
-        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
-        path: call.path,
-        ...(framing.query ? { query: framing.query } : {}),
-        ...(framing.headers ? { headers: framing.headers } : {}),
-        visibleHeaders,
-        ...(framing.rawBody !== undefined
-            ? { rawBody: framing.rawBody }
-            : framing.body !== undefined
-                ? { body: framing.body }
-                : {}),
-    };
-    const write = (callClassification(ctx) ?? request.classification) === "write";
-    return await send(request, ctx, async (response) => {
-        // Mappers cut the vendor's prose short, so it is redacted whole first.
-        if (!response.ok)
-            throw vendor.failure(response.status, response.headers, redactBeforeCut(ctx, await failureBody(response)), call, write);
-        // HEAD answers with headers alone; they are its data.
-        const body = call.method === "HEAD" ? headerData(response.headers) : await successBody(vendor, response, ctx);
-        // Order: unwrap the vendor's envelope, then redact (every success, HEAD
-        // header data and named tools included), then cursors (and, in the
-        // tools, `select`). Cursors read the envelope when the vendor unwraps
-        // one, and the redacted body otherwise.
-        const unwrapped = vendor.result && call.method !== "HEAD" ? vendor.result(body, call, response, ctx) : body;
-        const data = vendor.valueSafety.redact(unwrapped, call.method, call.op.path);
-        const page = vendor.page?.(vendor.result ? body : data, call);
-        return { status: response.status, data, ...(page ? { page } : {}) };
-    });
-}
-/** A HEAD response's headers as data, without cookies. */
-function headerData(headers) {
-    const out = {};
-    headers.forEach((value, name) => {
-        if (name !== "set-cookie")
-            out[name] = value;
-    });
-    return out;
-}
-/** Keep only the named dot paths; a path through an array applies to each item. */
-function project(value, paths) {
-    const root = new Map();
-    for (const path of paths) {
-        let node = root;
-        const parts = path.split(".");
-        for (const [index, part] of parts.entries()) {
-            const existing = node.get(part);
-            // A shorter path already keeps this whole subtree.
-            if (existing === true)
-                break;
-            if (index === parts.length - 1) {
-                node.set(part, true);
-                break;
-            }
-            const next = existing ?? new Map();
-            node.set(part, next);
-            node = next;
-        }
-    }
-    const pick = (current, tree) => {
-        if (Array.isArray(current))
-            return current.map((item) => pick(item, tree));
-        if (!isRecord(current))
-            return current;
-        const out = {};
-        for (const [key, child] of tree) {
-            if (!Object.hasOwn(current, key))
-                continue;
-            out[key] = child === true ? current[key] : pick(current[key], child);
-        }
-        return out;
-    };
-    return pick(value, root);
-}
-function selected(args, result) {
-    const select = args["select"];
-    if (!Array.isArray(select) || select.length === 0)
-        return result;
-    return { ...result, data: project(result.data, select) };
-}
-function pathSchema(example = "/v1/customers/cus_123") {
-    return {
-        type: "string",
-        minLength: 2,
-        maxLength: 2048,
-        description: `Concrete path from search with ids filled in, e.g. ${example}. No query string.`,
-    };
-}
-const QUERY = {
-    type: "object",
-    description: "Query parameters as JSON, named as details lists them.",
-};
-const SELECT = {
-    type: "array",
-    maxItems: MAX_SELECT,
-    items: { type: "string", minLength: 1, maxLength: 200 },
-    description: "Dot paths to keep from data, e.g. data.id; a path through a list applies to each item.",
-};
-const PAGE = {
-    type: "object",
-    description: "Present on lists: pass next as the param query parameter (a body field when in is body) for the next page. hasMore without next: no cursor exists.",
-    properties: {
-        hasMore: { type: "boolean" },
-        next: { type: "string" },
-        param: { type: "string" },
-        in: { type: "string", enum: ["query", "body"] },
-        path: { type: "string", description: "GET this path for the next page, when it differs from this call's." },
-    },
-    required: ["hasMore"],
-};
-function envelope(extra = {}) {
-    return {
-        type: "object",
-        properties: {
-            status: { type: "integer", description: "HTTP status." },
-            data: {
-                description: "Response body: JSON, text, NDJSON rows, { contentType, bytes, base64 }, or HEAD's headers.",
-            },
-            page: PAGE,
-            ...extra,
-        },
-        required: ["status", "data"],
-    };
-}
-function closed(properties, required) {
-    return { type: "object", properties, required, additionalProperties: false };
-}
-/** The four generic tools over one vendor's index. */
-export function restTools(vendor) {
-    const { index, title } = vendor;
-    const tool = (kind) => `${vendor.vendor}_api_${kind}`;
-    const PATH = pathSchema(vendor.pathExample);
-    const headerNames = Object.keys(vendor.headers ?? {});
-    const HEADERS = headerNames.length
-        ? {
-            headers: {
-                type: "object",
-                description: "Optional request headers this vendor's operations read; nothing else is accepted.",
-                properties: Object.fromEntries(Object.entries(vendor.headers).map(([name, description]) => [
-                    name,
-                    { type: "string", minLength: 1, maxLength: 200, description },
-                ])),
-                additionalProperties: false,
-            },
-        }
-        : {};
-    const headersOf = (args) => isRecord(args["headers"]) ? { headers: args["headers"] } : {};
-    const readPosts = vendor.readPosts ?? [];
-    for (const [method, path] of readPosts) {
-        // A reviewed exception the index no longer carries is a stale review.
-        if (!index.operation(method, path)) {
-            throw new Error(`${title} reviewed read-only ${method} ${path} is not in the pinned API index.`);
-        }
-    }
-    const reads = (op) => op.method === "GET" ||
-        op.method === "HEAD" ||
-        readPosts.some(([method, path]) => method === op.method && path === op.path);
-    const writeMethods = index.methods.filter((method) => method !== "GET" && method !== "HEAD");
-    // The methods an idempotency key is sent with: never DELETE (see the handler).
-    const keyed = vendor.idempotencyHeader ? writeMethods.filter((method) => method !== "DELETE") : [];
-    const keyedText = keyed.join(" or ");
-    const head = index.methods.includes("HEAD");
-    const readMethods = [...new Set(["GET", ...(head ? ["HEAD"] : []), ...readPosts.map(([method]) => method)])];
-    const routeOf = (op) => (reads(op) ? tool("read") : tool("write"));
-    // An unreachable host and a reviewed refusal are answered before argument
-    // checks: no corrected argument would make either call go through.
-    const guard = (call) => {
-        const send = vendor.transport(call.op.server);
-        if (typeof send === "string")
-            invalid(send);
-        const refusal = vendor.valueSafety.refusal(call.method, call.op.path) ?? vendor.refuse?.(call);
-        if (refusal)
-            invalid(refusal);
-    };
-    return [
-        {
-            name: tool("search"),
-            description: `Find ${title} API operations by keyword or path in the pinned API index. Returns method, path, and summary; reads no account data.`,
-            annotations: READ,
-            inputSchema: closed({
-                query: {
-                    type: "string",
-                    minLength: 1,
-                    maxLength: 200,
-                    description: "Keywords or a path, e.g. refund charge.",
-                },
-                method: { type: "string", enum: [...index.methods], description: "Only operations with this method." },
-                limit: { type: "integer", minimum: 1, maximum: 50, description: "Most operations to return; default 10." },
-            }, ["query"]),
-            outputSchema: {
-                type: "object",
-                properties: {
-                    operations: {
-                        type: "array",
-                        items: {
-                            type: "object",
-                            properties: {
-                                method: { type: "string" },
-                                path: { type: "string" },
-                                summary: { type: "string" },
-                                tool: { type: "string", description: "The tool that calls it." },
-                            },
-                            required: ["method", "path", "tool"],
-                        },
-                    },
-                    revision: { type: "string", description: "Pinned index revision." },
-                },
-                required: ["operations", "revision"],
-            },
-            handler: (args) => ({
-                operations: index
-                    .search(String(args["query"]), {
-                    ...(typeof args["method"] === "string" ? { method: args["method"] } : {}),
-                    limit: typeof args["limit"] === "number" ? args["limit"] : 10,
-                })
-                    .map((op) => ({
-                    method: op.method,
-                    path: op.path,
-                    operationId: op.operationId,
-                    summary: op.summary,
-                    tag: op.tag,
-                    tool: routeOf(op),
-                })),
-                revision: index.revision,
-            }),
-        },
-        {
-            name: tool("details"),
-            description: `Read one ${title} API operation's request contract: path, query, and body parameters with types, enums, and required names. Reads no account data.`,
-            annotations: READ,
-            inputSchema: closed({
-                method: { type: "string", enum: [...index.methods], description: "The operation's HTTP method." },
-                path: { ...PATH, description: "The path template from search, or a concrete path." },
-                param: { type: "string", minLength: 1, maxLength: 200, description: "Return only this parameter." },
-            }, ["method", "path"]),
-            outputSchema: {
-                type: "object",
-                properties: {
-                    method: { type: "string" },
-                    path: { type: "string" },
-                    tool: { type: "string", description: "The tool that calls it." },
-                    parameters: { type: "array", description: "Path and query parameters." },
-                    body: {
-                        type: "object",
-                        description: "Body content type and schema; truncated: true marks unexpanded levels.",
-                    },
-                    revision: { type: "string" },
-                },
-                required: ["method", "path", "tool", "parameters", "revision"],
-            },
-            handler: (args) => {
-                const method = String(args["method"]);
-                const path = String(args["path"]);
-                const op = index.operation(method, path) ?? index.resolve(method, path).op;
-                return {
-                    ...index.contract(op, typeof args["param"] === "string" ? args["param"] : undefined),
-                    tool: routeOf(op),
-                    revision: index.revision,
-                };
-            },
-        },
-        {
-            name: tool("read"),
-            description: `Call a ${title} API GET${head ? " or HEAD" : ""} operation${readPosts.length ? ", or a reviewed read-only POST" : ""}. ` +
-                "Arguments are checked against the pinned index before anything is sent.",
-            annotations: READ,
-            inputSchema: closed({
-                path: PATH,
-                ...(readMethods.length > 1
-                    ? {
-                        method: {
-                            type: "string",
-                            enum: readMethods,
-                            description: "GET by default; another method only for an operation search routes here.",
-                        },
-                    }
-                    : {}),
-                ...(readPosts.length
-                    ? {
-                        body: {
-                            type: vendor.textBodies ? ["object", "string"] : "object",
-                            description: `Body for a reviewed read-only POST${vendor.textBodies ? "; a string for a text-framed operation" : ""}.`,
-                        },
-                    }
-                    : {}),
-                query: QUERY,
-                ...HEADERS,
-                select: SELECT,
-            }, ["path"]),
-            outputSchema: envelope(),
-            handler: async (args, ctx) => {
-                const method = (typeof args["method"] === "string" ? args["method"] : "GET");
-                const call = restCall(vendor, method, String(args["path"]), {
-                    query: isRecord(args["query"]) ? args["query"] : {},
-                    body: args["body"],
-                    ...headersOf(args),
-                });
-                if (!reads(call.op)) {
-                    invalid(`${call.method} ${call.op.path} is not a reviewed read; call it with ${tool("write")}.`);
-                }
-                if ((call.method === "GET" || call.method === "HEAD") && call.body !== undefined) {
-                    invalid(`A ${call.method} operation takes query, not body.`);
-                }
-                guard(call);
-                index.check(call.op, call.query, call.body);
-                return selected(args, await callRest(vendor, call, ctx));
-            },
-        },
-        {
-            name: tool("write"),
-            description: `Call a ${title} API write (${writeMethods.join(", ")}); method and path are stated for approval. ` +
-                `Checked against the pinned index first.${keyed.length ? ` Pass idempotencyKey to retry a ${keyedText} safely${keyed.length < writeMethods.length ? "; a DELETE sends no key" : ""}.` : ""}`,
-            annotations: DESTRUCTIVE,
-            inputSchema: closed({
-                method: { type: "string", enum: writeMethods, description: "The operation's HTTP method." },
-                path: PATH,
-                query: QUERY,
-                body: {
-                    type: vendor.textBodies ? ["object", "array", "string"] : ["object", "array"],
-                    description: `Request body as JSON${vendor.bodyHint ? `; ${vendor.bodyHint}` : ""}.`,
-                },
-                ...HEADERS,
-                ...(vendor.idempotencyHeader
-                    ? {
-                        idempotencyKey: {
-                            type: "string",
-                            minLength: 1,
-                            maxLength: IDEMPOTENCY_KEY_MAX_LENGTH,
-                            description: `Reuse to retry this exact ${keyedText}; one is generated and returned when omitted.`,
-                        },
-                    }
-                    : {}),
-                select: SELECT,
-            }, ["method", "path"]),
-            outputSchema: envelope(vendor.idempotencyHeader
-                ? {
-                    idempotencyKey: {
-                        type: "string",
-                        description: "The key sent; reuse it, with the same arguments, while the vendor retains it.",
-                    },
-                }
-                : {}),
-            handler: async (args, ctx) => {
-                const call = restCall(vendor, args["method"], String(args["path"]), {
-                    query: isRecord(args["query"]) ? args["query"] : {},
-                    body: args["body"],
-                    ...headersOf(args),
-                });
-                if (call.method === "GET" || call.method === "HEAD") {
-                    invalid(`${call.method} operations are reads; call them with ${tool("read")}.`);
-                }
-                guard(call);
-                const framing = index.bodyType(call.op);
-                if (framing && /^multipart\/|octet-stream/.test(framing)) {
-                    invalid(`${call.method} ${call.op.path} takes a ${framing} upload, which ${tool("write")} does not send.` +
-                        (vendor.upload ? ` ${vendor.upload}` : ""));
-                }
-                index.check(call.op, call.query, call.body);
-                const header = vendor.idempotencyHeader && call.method !== "DELETE" ? vendor.idempotencyHeader : undefined;
-                const given = typeof args["idempotencyKey"] === "string" ? args["idempotencyKey"] : undefined;
-                // A blank key reaches the vendor empty, and one fetch cannot carry
-                // never leaves: neither proves that a retry cannot repeat the write.
-                const unsendable = given === undefined ? undefined : unsendableKey(given);
-                if (unsendable)
-                    invalid(`idempotencyKey ${unsendable}, or omit it.`);
-                const key = header ? (given ?? crypto.randomUUID()) : undefined;
-                // Recorded before dispatch: if the invocation deadline interrupts this
-                // call, no failure of ours arrives, and the invocation returns the key
-                // from here with write_outcome_unknown.
-                if (key)
-                    recordRecovery(ctx, { idempotencyKey: key });
-                try {
-                    const result = await callRest(vendor, call, ctx, header && key ? { [header]: key } : {});
-                    return { ...selected(args, result), ...(key ? { idempotencyKey: key } : {}) };
-                }
-                catch (error) {
-                    // A generated key exists nowhere else, so a failure must carry it:
-                    // only that key lets the caller check or retry this exact write.
-                    // The key stays in the message as a diagnostic; the advice to
-                    // reuse it is a segment the invocation composes only where the key
-                    // protects the whole logical call (keyResendAdvice), and exists
-                    // only once the ledger shows a dispatched request carrying it.
-                    if (!key || given || !(error instanceof ConnectorCallError))
-                        throw error;
-                    const failure = providerFailureMessage(error, `${error.message} ${header}: ${key}.`);
-                    if (!providerRequests(ctx)?.some((request) => request.dispatched && request.key === key))
-                        throw failure;
-                    throw keyResendAdvice(failure, key, " Reusing it with the exact original arguments retries this write without repeating it only while " +
-                        "the vendor retains the key; after that, look the object up before retrying.");
-                }
-            },
-        },
-    ];
-}