@zackbart/connecta 0.15.1 → 0.16.0

package/dist/catalog-drift.js

@@ -0,0 +1,251 @@
+// Web-API only, like the rest of the core: a manifest comparison that ran on
+// Node but not on Workers would leave half the deployments unable to tell a
+// stale allowlist from a current one.
+import { boundedEchoText } from "./errors.js";
+/**
+ * Byte budget for the one string a drift report carries. An ISO timestamp is
+ * 24 bytes; anything near this bound is a plugin sending something else.
+ */
+const MAX_OBSERVED_AT_BYTES = 64;
+/** A count, or 0 when the seam returned something that is not one. */
+function boundedCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.trunc(value))
+        : 0;
+}
+/**
+ * Rebuild a drift report as four counts and a bounded timestamp.
+ *
+ * `Connector.catalogDrift()` sits on the open plugin seam, and what it returns
+ * lands in the body of unauthenticated `/health` and on connector status.
+ * TypeScript constrains neither an extra enumerable property nor the length of
+ * `observedAt` at runtime, so "counts and nothing else" is *made* true here —
+ * at the boundary where third-party output becomes a response — rather than
+ * trusted. The activity path reconstructs its five fields for the same reason.
+ */
+export function boundedCatalogDrift(report) {
+    if (!report || typeof report !== "object")
+        return undefined;
+    return {
+        observedAt: boundedEchoText(typeof report.observedAt === "string" ? report.observedAt : "", MAX_OBSERVED_AT_BYTES),
+        unclassifiedTools: boundedCount(report.unclassifiedTools),
+        unservedTools: boundedCount(report.unservedTools),
+        annotationConflicts: boundedCount(report.annotationConflicts),
+        schemaChanges: boundedCount(report.schemaChanges),
+    };
+}
+const encoder = new TextEncoder();
+/** Deterministic JSON: object keys sorted, so key order is not a schema change. */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value === null || typeof value !== "object")
+        return value;
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item)]));
+}
+/**
+ * Digest the schemas of one downstream tool.
+ *
+ * Canonical rather than literal, unlike the catalog fingerprint in
+ * `src/catalog-fingerprint.ts`: that one is deliberately conservative because a
+ * spurious cache write is cheap, while a spurious drift finding spends a
+ * maintainer's attention on a downstream that reordered its JSON keys.
+ * Description and annotations are excluded — a reworded description is P1's
+ * business, and an annotation change is already its own drift category.
+ */
+export async function vettedSchemaDigest(tool) {
+    const bytes = encoder.encode(JSON.stringify(canonicalize({
+        inputSchema: tool.inputSchema ?? null,
+        outputSchema: tool.outputSchema ?? null,
+    })));
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return `sha256:${[...digest]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+/**
+ * Build a provider's manifest from the lists it already maintains.
+ *
+ * Throws when a name is classified twice, because a tool that is both a read
+ * and a write is a review mistake that must not boot: the annotation the
+ * connector would apply depends on which branch runs first, and "safe by
+ * default" cannot be decided by ordering.
+ */
+export function vettedCatalog(input) {
+    const tools = new Map();
+    const digestFor = (name) => input.schemaDigests?.[name];
+    for (const name of input.reads) {
+        const digest = digestFor(name);
+        tools.set(name, {
+            verdict: "read-only",
+            ...(digest !== undefined ? { schemaDigest: digest } : {}),
+        });
+    }
+    for (const [name, verdict] of input.writes) {
+        if (tools.has(name)) {
+            throw new Error(`vettedCatalog() classified "${name}" as both a read and a write.`);
+        }
+        const digest = digestFor(name);
+        tools.set(name, {
+            verdict,
+            ...(digest !== undefined ? { schemaDigest: digest } : {}),
+        });
+    }
+    for (const name of Object.keys(input.schemaDigests ?? {})) {
+        if (!tools.has(name)) {
+            throw new Error(`vettedCatalog() recorded a schema digest for unclassified tool "${name}".`);
+        }
+    }
+    return { version: 1, tools };
+}
+/**
+ * Fill in downstream silence; keep reviewed destructive tools fail-closed.
+ *
+ * Silence is what a vetted classification is for, and an explicit downstream
+ * annotation otherwise wins in both directions. `destructiveHint: true` or
+ * `readOnlyHint: false` on a classified read is the downstream telling us this
+ * release's allowlist is stale; `readOnlyHint: true` on a name no release has
+ * classified says the same thing from the other side. The single place a
+ * vetted verdict still overrides the downstream is a name this release
+ * reviewed and filed destructive: there connecta knows what the tool does, and
+ * a claim to the contrary is a downstream bug rather than news
+ * ([#310](https://github.com/zackbart/connecta/issues/310),
+ * [#315](https://github.com/zackbart/connecta/issues/315)).
+ */
+function applyVettedSafety(catalog, definition) {
+    const downstream = definition.annotations ?? {};
+    const record = catalog.tools.get(definition.name);
+    if (record?.verdict === "read-only") {
+        if (downstream.destructiveHint === true ||
+            downstream.readOnlyHint === false) {
+            return definition;
+        }
+        return {
+            ...definition,
+            annotations: {
+                ...downstream,
+                readOnlyHint: true,
+                destructiveHint: downstream.destructiveHint ?? false,
+            },
+        };
+    }
+    if (record?.verdict === "destructive") {
+        return {
+            ...definition,
+            annotations: {
+                ...downstream,
+                readOnlyHint: false,
+                destructiveHint: true,
+            },
+        };
+    }
+    // Maintained additive creates and tools this release has never seen land
+    // here alike. Fill-in only: a silent tool is not read-only, so drift still
+    // fails closed onto `call_destructive_tool`, and neither population gets a
+    // `destructiveHint` it has not earned. A tool that arrives explicitly
+    // read-only keeps that annotation — on a name no release has reviewed, the
+    // downstream's own word is the only evidence there is, and rewriting it
+    // would be an overrule rather than a fill-in.
+    return {
+        ...definition,
+        annotations: {
+            ...downstream,
+            readOnlyHint: downstream.readOnlyHint ?? false,
+        },
+    };
+}
+/**
+ * Whether the downstream's own annotation contradicts what a release reviewed.
+ *
+ * Only an *explicit* contradiction counts. Silence is the ordinary case the
+ * classification exists to fill, and an unclassified tool is already counted
+ * as an addition rather than twice.
+ */
+function contradicts(record, definition) {
+    const downstream = definition.annotations ?? {};
+    if (record.verdict === "read-only") {
+        return (downstream.readOnlyHint === false || downstream.destructiveHint === true);
+    }
+    return downstream.readOnlyHint === true;
+}
+/**
+ * Compare a live catalog with the manifest and count what moved.
+ *
+ * Counts only, and by construction: there is nowhere here to put a tool name,
+ * a schema, or a downstream string, so no later surface has to remember to
+ * strip one. Reads nothing but the tools it was handed — the caller already
+ * fetched them to serve a request, and this function never fetches anything.
+ */
+export async function detectCatalogDrift(catalog, tools) {
+    let unclassifiedTools = 0;
+    let annotationConflicts = 0;
+    let schemaChanges = 0;
+    const served = new Set();
+    for (const definition of tools) {
+        served.add(definition.name);
+        const record = catalog.tools.get(definition.name);
+        if (!record) {
+            unclassifiedTools += 1;
+            continue;
+        }
+        if (contradicts(record, definition))
+            annotationConflicts += 1;
+        // A manifest that recorded no digest for this tool cannot have an opinion
+        // about its schema, so it does not pay for a hash either.
+        if (record.schemaDigest !== undefined &&
+            record.schemaDigest !== (await vettedSchemaDigest(definition))) {
+            schemaChanges += 1;
+        }
+    }
+    let unservedTools = 0;
+    for (const name of catalog.tools.keys()) {
+        if (!served.has(name))
+            unservedTools += 1;
+    }
+    return {
+        unclassifiedTools,
+        unservedTools,
+        annotationConflicts,
+        schemaChanges,
+    };
+}
+/**
+ * Wrap a hosted-MCP connector in its vetted manifest: the classification the
+ * catalog is normalized with, and the drift check that rides the same listing.
+ *
+ * The check happens where the tools are already in hand and still unmodified —
+ * after the downstream answered, before the classification is applied. It adds
+ * no request of its own, which is the whole boundary: connecta watches a
+ * contract while it is serving a refresh the deployment asked for, and never
+ * initiates one to go looking ([#179](https://github.com/zackbart/connecta/issues/179),
+ * [#343](https://github.com/zackbart/connecta/issues/343)).
+ */
+export function withVettedCatalog(connector, catalog) {
+    let observed;
+    return {
+        ...connector,
+        async listTools(ctx) {
+            const downstream = await connector.listTools(ctx);
+            try {
+                observed = {
+                    observedAt: new Date().toISOString(),
+                    ...(await detectCatalogDrift(catalog, downstream)),
+                };
+            }
+            catch (error) {
+                // A drift check is a report about a catalog, never a condition for
+                // serving one. Keep the last good observation rather than replacing it
+                // with a lie, and let the refresh through.
+                ctx.logger.warn(`[connecta] connector "${connector.id}" catalog drift check failed: ` +
+                    (error instanceof Error ? error.message : String(error)));
+            }
+            return downstream.map((definition) => applyVettedSafety(catalog, definition));
+        },
+        catalogDrift() {
+            return observed;
+        },
+    };
+}

package/dist/catalog-fingerprint.d.ts

@@ -17,4 +17,3 @@ export declare function fingerprintSerializedCatalog(serializedTools: string): P
  * any serialized field must change the digest.
  */
 export declare function snapshotCatalog(tools: ToolDef[]): Promise<CatalogSnapshot>;
-//# sourceMappingURL=catalog-fingerprint.d.ts.map

package/dist/catalog-fingerprint.js

@@ -31,4 +31,3 @@ export async function snapshotCatalog(tools) {
         serializedBytes: bytes,
     };
 }
-//# sourceMappingURL=catalog-fingerprint.js.map

package/dist/catalog-limits.d.ts

@@ -7,4 +7,3 @@ export declare const MAX_CATALOG_TOOLS = 100000;
 export declare const MAX_SERIALIZED_CATALOG_BYTES: number;
 /** Persisted values stay comfortably below platform per-value limits. */
 export declare const MAX_CATALOG_CHUNK_BYTES: number;
-//# sourceMappingURL=catalog-limits.d.ts.map

package/dist/catalog-limits.js

@@ -7,4 +7,3 @@ export const MAX_CATALOG_TOOLS = 100_000;
 export const MAX_SERIALIZED_CATALOG_BYTES = 32 * 1024 * 1024;
 /** Persisted values stay comfortably below platform per-value limits. */
 export const MAX_CATALOG_CHUNK_BYTES = 1024 * 1024;
-//# sourceMappingURL=catalog-limits.js.map

package/dist/catalog-service.d.ts

@@ -247,4 +247,3 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
     hasMore: boolean;
 };
 export {};
-//# sourceMappingURL=catalog-service.d.ts.map

package/dist/catalog-service.js

@@ -786,4 +786,3 @@ export function flatSearchResult(page) {
         ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
     };
 }
-//# sourceMappingURL=catalog-service.js.map

package/dist/catalog.d.ts

@@ -72,4 +72,3 @@ export interface SchemaObjectKeys {
  * fields.
  */
 export declare function schemaObjectKeys(schema: JsonSchema | undefined): SchemaObjectKeys | undefined;
-//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -636,4 +636,3 @@ function objectKeys(schema, defs, seen, depth) {
     }
     return undefined;
 }
-//# sourceMappingURL=catalog.js.map

package/dist/concurrency.d.ts

@@ -1,4 +1,3 @@
 export declare function resolveDiscoveryConcurrency(value: number | undefined): number;
 /** Run `fn` over `items` with at most `limit` operations in flight. */
 export declare function mapSettledWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]>;
-//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.js

@@ -28,4 +28,3 @@ export async function mapSettledWithConcurrency(items, limit, fn) {
     await Promise.all(workers);
     return settled;
 }
-//# sourceMappingURL=concurrency.js.map

package/dist/connector-scope.d.ts

@@ -13,4 +13,3 @@ export type DeferredWork = (promise: Promise<unknown>) => void;
  * again after this returns.
  */
 export declare function closeConnectorScope(connector: Connector, ctx: ConnectorContext, defer?: DeferredWork): Promise<void>;
-//# sourceMappingURL=connector-scope.d.ts.map

package/dist/connector-scope.js

@@ -52,4 +52,3 @@ export async function closeConnectorScope(connector, ctx, defer) {
         // The scope is over whether or not the connector managed to clean it up.
     }
 }
-//# sourceMappingURL=connector-scope.js.map

package/dist/connectors/api.d.ts

@@ -1,16 +1,30 @@
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorCredentialConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, CredentialTestResult, JsonSchema, ToolAnnotations } from "../types.js";
 export interface ApiTool {
     name: string;
-    description?: string;
-    /** A plain JSON Schema object describing the tool input. */
+    /**
+     * Required, non-empty. Discovery has nothing else to go on: a nameless
+     * capability costs the agent a guess, and a guess costs a wrong call.
+     */
+    description: string;
+    /**
+     * A plain JSON Schema object describing the tool input. Optional, but what
+     * you supply must be a schema the validator can compile — `api()` refuses to
+     * construct otherwise.
+     */
     inputSchema?: JsonSchema;
     /** A plain JSON Schema object describing the tool's structured output. */
     outputSchema?: JsonSchema;
     /**
-     * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
-     * admits the tool to call_tool and execute_code.
+     * Standard MCP-style behavior hints, with an explicit `readOnlyHint`
+     * required: `true` declares a read and admits the tool to call_tool and
+     * execute_code, `false` declares work that must cross
+     * `call_destructive_tool` where a host can ask a human. Connecta never
+     * infers the classification from a name, a description, a schema, or the
+     * other annotations.
      */
-    annotations?: ToolAnnotations;
+    annotations: ToolAnnotations & {
+        readOnlyHint: boolean;
+    };
     handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
 }
 export interface ApiOptions {
@@ -47,16 +61,6 @@ export interface ApiOptions {
      * on loose coercion.
      */
     validateArgs?: boolean;
-    /**
-     * Fail-closed on a tool whose `inputSchema` the validator cannot evaluate
-     * (default false). The default surfaces such a schema as a one-time warning
-     * and then passes the raw arguments through, so a broken schema never breaks
-     * an otherwise working tool. Set true to instead reject those calls with a
-     * non-retryable `invalid_args` ConnectorCallError, so a schema that cannot be
-     * enforced never silently admits unvalidated input. Only consulted when
-     * `validateArgs` is not false.
-     */
-    strictValidation?: boolean;
     tools: ApiTool[];
 }
 /**
@@ -64,11 +68,15 @@ export interface ApiOptions {
  * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
  * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
  *
- * Arguments are validated against `inputSchema` before the handler runs
- * (disable with `validateArgs: false`). Remote MCP inputs are also validated,
- * but in the shared invocation path against the request-local downstream
- * catalog. These API-only controls stay here because hand-written handlers may
- * deliberately accept loose coercion or choose fail-closed schema handling.
+ * Every tool declares a description and an explicit `annotations.readOnlyHint`,
+ * and any `inputSchema` it carries must compile — a tool that fails the
+ * contract throws here rather than reaching a catalog. Arguments are then
+ * validated against `inputSchema` before the handler runs (disable with
+ * `validateArgs: false`, which opts out of enforcement, not out of the schema
+ * being real), and a schema that only reveals itself as unenforceable on first
+ * use — an unresolvable `$ref`, say — fails the call rather than passing raw
+ * arguments through. Remote MCP inputs are also validated, but in the shared
+ * invocation path against the request-local downstream catalog, where a
+ * downstream's schema is its own affair and stays fail-open.
  */
 export declare function api(id: string, opts: ApiOptions): Connector;
-//# sourceMappingURL=api.d.ts.map

package/dist/connectors/api.js

@@ -1,34 +1,58 @@
-import { precompileValidator, validateToolInput } from "../validate.js";
+import { compileValidator, validateToolInput } from "../validate.js";
+/**
+ * Enforce the construction contract for one hand-written tool.
+ *
+ * Everything here is something only the author can supply and no runtime can
+ * guess: what the tool does, and whether calling it needs a human's blessing.
+ * Guessing either one is how a deployment boots into the wrong shape, so this
+ * throws instead. Note what it does *not* do — it never reads a name, verb, or
+ * HTTP method to infer a safety class. An unclassified tool is a bug in the
+ * deployment, not a puzzle for connecta to solve.
+ */
+function checkToolContract(id, tool) {
+    const address = `${id}.${tool.name}`;
+    if (typeof tool.description !== "string" || tool.description.trim() === "") {
+        throw new Error(`api() tool "${address}" needs a non-empty description — it is what an ` +
+            "agent reads to choose the tool (convention: imperative one-liner, " +
+            'e.g. "Send an email via Resend").');
+    }
+    if (typeof tool.annotations?.readOnlyHint !== "boolean") {
+        throw new Error(`api() tool "${address}" needs an explicit annotations.readOnlyHint: ` +
+            "true for a read, false for work that must cross " +
+            "call_destructive_tool. Connecta never infers the classification " +
+            "from a tool name, description, schema, or other annotations.");
+    }
+    if (tool.inputSchema)
+        compileValidator(tool.inputSchema, { address });
+}
 /**
  * A connector defined entirely in code: static tool defs + fetch handlers.
  * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
  * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
  *
- * Arguments are validated against `inputSchema` before the handler runs
- * (disable with `validateArgs: false`). Remote MCP inputs are also validated,
- * but in the shared invocation path against the request-local downstream
- * catalog. These API-only controls stay here because hand-written handlers may
- * deliberately accept loose coercion or choose fail-closed schema handling.
+ * Every tool declares a description and an explicit `annotations.readOnlyHint`,
+ * and any `inputSchema` it carries must compile — a tool that fails the
+ * contract throws here rather than reaching a catalog. Arguments are then
+ * validated against `inputSchema` before the handler runs (disable with
+ * `validateArgs: false`, which opts out of enforcement, not out of the schema
+ * being real), and a schema that only reveals itself as unenforceable on first
+ * use — an unresolvable `$ref`, say — fails the call rather than passing raw
+ * arguments through. Remote MCP inputs are also validated, but in the shared
+ * invocation path against the request-local downstream catalog, where a
+ * downstream's schema is its own affair and stays fail-open.
  */
 export function api(id, opts) {
+    for (const t of opts.tools)
+        checkToolContract(id, t);
     const defs = opts.tools.map((t) => ({
         name: t.name,
-        ...(t.description !== undefined ? { description: t.description } : {}),
+        description: t.description,
         ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
         ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
-        ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
+        annotations: t.annotations,
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
-    const strictValidation = opts.strictValidation ?? false;
-    if (validateArgs) {
-        // Compile each schema now so a validator-hostile inputSchema surfaces once
-        // here rather than silently on its first call. Warning-only; never throws.
-        for (const t of opts.tools) {
-            if (t.inputSchema)
-                precompileValidator(t.inputSchema, { address: `${id}.${t.name}` });
-        }
-    }
     return {
         id,
         ...(opts.title !== undefined ? { title: opts.title } : {}),
@@ -64,7 +88,10 @@ export function api(id, opts) {
                 const invalid = validateToolInput(tool.inputSchema, input, {
                     address: `${id}.${name}`,
                     logger: ctx.logger,
-                    failClosed: strictValidation,
+                    // Always: the schema compiled at construction, so anything that
+                    // fails here is a schema that cannot be enforced, and a surface we
+                    // wrote ourselves does not get to admit unvalidated input quietly.
+                    failClosed: true,
                 });
                 if (invalid)
                     throw invalid;
@@ -77,4 +104,3 @@ export function api(id, opts) {
         },
     };
 }
-//# sourceMappingURL=api.js.map

package/dist/connectors/guarded-fetch.d.ts

@@ -0,0 +1,106 @@
+import type { ConnectorContext } from "../types.js";
+/** The methods a hand-written provider surface actually uses. */
+type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface GuardedRequest {
+    method: GuardedMethod;
+    /**
+     * Provider-relative path beginning with one `/`, resolved against the base
+     * URL's own path. Never an absolute URL, and never carrying `?` or `#` —
+     * query parameters go in `query`, where they are encoded rather than parsed.
+     */
+    path: string;
+    /** Search parameters; `undefined` values are dropped, others stringified. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Per-request headers. `undefined` values are dropped, and a header that
+     * collides with an authentication header is refused rather than allowed to
+     * shadow it.
+     */
+    headers?: Record<string, string | undefined>;
+    /** JSON request body. Serialized here, with the `Content-Type` to match. */
+    body?: unknown;
+    /**
+     * A pre-framed body — `FormData`, text, bytes. Mutually exclusive with
+     * `body`, and no `Content-Type` is supplied: multipart needs `fetch` to pick
+     * the boundary, and anything else knows its own type.
+     */
+    rawBody?: BodyInit;
+}
+/**
+ * One downstream response, read under the connector's byte ceiling.
+ *
+ * The accessors are the whole read surface — there is no escape to the
+ * underlying `Response`, because an unbounded `.text()` on it is exactly the
+ * mistake this type exists to remove. `status`, `ok`, and `headers` are the
+ * raw facts a provider mapper needs to make its own classification.
+ */
+interface GuardedResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: Headers;
+    /** The body as bytes. */
+    bytes(): Promise<Uint8Array>;
+    /** The body decoded as UTF-8. */
+    text(): Promise<string>;
+    /** The body parsed as JSON; `undefined` for an empty body, throws on junk. */
+    json(): Promise<unknown>;
+}
+/**
+ * Turn one response into the provider's own result, or throw the provider's
+ * own typed failure. This is where status codes acquire meaning, and it is
+ * always the provider's code.
+ */
+type GuardedResponseMapper<T> = (response: GuardedResponse, ctx: ConnectorContext) => T | Promise<T>;
+export interface GuardedFetchOptions {
+    /**
+     * Provider name as it appears in normalized failure prose — "Cloudflare",
+     * "Notion". Used for messages only; it is never parsed.
+     */
+    provider: string;
+    /**
+     * Absolute base URL. Its origin and path prefix are the confinement: every
+     * request resolves beneath it or is refused.
+     */
+    baseUrl: string;
+    /**
+     * Headers proving the caller's identity, resolved once per request. Throwing
+     * a typed `auth_required` from here is the documented way to report a
+     * missing credential — the helper has no opinion about what a credential is.
+     */
+    authenticate: (ctx: ConnectorContext) => Record<string, string> | Promise<Record<string, string>>;
+    /** Constant headers sent with every request — `Accept`, an API version. */
+    headers?: Record<string, string>;
+    /**
+     * Ceiling on the response body, in bytes. Required, because a default here
+     * would be the helper guessing on a provider's behalf: what counts as an
+     * absurd response is a fact about the API, not about HTTP.
+     */
+    maxResponseBytes: number;
+}
+/** Send one guarded request and map its response with provider knowledge. */
+export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
+/**
+ * Build the guarded transport one hand-written connector sends every request
+ * through.
+ *
+ * ```ts
+ * const send = guardedFetch({
+ *   provider: "Billing",
+ *   baseUrl: "https://billing.internal.example/v1",
+ *   maxResponseBytes: 4 * 1024 * 1024,
+ *   headers: { Accept: "application/json" },
+ *   authenticate: async (ctx) => {
+ *     const token = await ctx.credential?.get();
+ *     if (!token) throw new ConnectorCallError("auth_required", "…");
+ *     return { Authorization: `Bearer ${token}` };
+ *   },
+ * });
+ *
+ * const invoice = await send({ method: "GET", path: `/invoices/${id}` }, ctx, (response) => {
+ *   if (!response.ok) throw billingFailure(response.status);
+ *   return response.json();
+ * });
+ * ```
+ */
+export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
+export {};