@zackbart/connecta 0.18.3 → 0.19.0

package/dist/catalog.js

@@ -123,9 +123,6 @@ function indexFor(tools) {
     }
     return index;
 }
-function documentsFor(tools) {
-    return indexFor(tools).documents;
-}
 /**
  * Whole-token equality is the ordinary lexical match. A deliberately narrow
  * inflection check retains useful singular/plural and past-tense recall
@@ -293,7 +290,7 @@ export function rankTools(tools, query, mode = "all", statistics = lexicalCorpus
     const exactNamePhrase = normalized(exactNameQuery);
     const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
     const ranked = [];
-    documentsFor(tools).forEach((doc, order) => {
+    indexFor(tools).documents.forEach((doc, order) => {
         const scored = scoreDocument(doc, phrase, terms, mode, statistics);
         if (scored !== null) {
             ranked.push({
@@ -425,6 +422,9 @@ function renderSchema(schema, defs, seen, depth, options) {
         return JSON.stringify(schema);
     }
     const s = schema;
+    const constrain = (rendered) => options.renderConstraints
+        ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
+        : rendered;
     // allOf composes rather than replaces: it is checked before every other
     // keyword, and renders the schema's own shape alongside its members instead
     // of returning early. A schema carrying both allOf and properties (the usual
@@ -457,9 +457,7 @@ function renderSchema(schema, defs, seen, depth, options) {
         seen.add(name);
         const rendered = renderSchema(target, defs, seen, depth, options);
         seen.delete(name);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     const union = (s.oneOf ?? s.anyOf);
     if (Array.isArray(union)) {
@@ -467,15 +465,11 @@ function renderSchema(schema, defs, seen, depth, options) {
             .map((u) => renderSchema(u, defs, seen, depth + 1, options))
             .join(" | ") ||
             "unknown";
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
         const rendered = renderEnum(s.enum, options.enumByteLimit, options.onEnumTruncated);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     // Checked before type/properties so a discriminator like
     // { type: "string", const: "emoji" } renders as "emoji" rather than string.
@@ -483,9 +477,7 @@ function renderSchema(schema, defs, seen, depth, options) {
     // `const: undefined` must fall through to the regular type rendering.
     if (s.const !== undefined) {
         const rendered = JSON.stringify(s.const);
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     const type = s.type;
     if (type === "array" || s.items) {
@@ -519,15 +511,11 @@ function renderSchema(schema, defs, seen, depth, options) {
             .join(", ")} }`;
     }
     if (typeof type === "string") {
-        return options.renderConstraints
-            ? renderConstraints(type, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : type;
+        return constrain(type);
     }
     if (Array.isArray(type)) {
         const rendered = type.join(" | ");
-        return options.renderConstraints
-            ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-            : rendered;
+        return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
         return renderConstraints("unknown", s, options.constraintByteLimit, options.onConstraintTruncated);
@@ -535,15 +523,18 @@ function renderSchema(schema, defs, seen, depth, options) {
     return JSON.stringify(schema);
 }
 const compactSchemas = new WeakMap();
+function defsOf(schema) {
+    return {
+        ...schema.$defs,
+        ...schema.definitions,
+    };
+}
 /** Render and cache a compact TypeScript-like representation of JSON Schema. */
 export function compactSchema(schema) {
     const cached = compactSchemas.get(schema);
     if (cached)
         return cached;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    const defs = defsOf(schema);
     let rendered;
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
@@ -603,24 +594,24 @@ export function compactDiscoverySchema(schema) {
     const cached = compactDiscoverySchemas.get(schema);
     if (cached)
         return cached;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    const defs = defsOf(schema);
     let rendered;
     let enumTruncated = false;
     let constraintTruncated = false;
+    const base = {
+        propertyDescriptions: false,
+        requiredFirst: true,
+        enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
+        onEnumTruncated: () => {
+            enumTruncated = true;
+        },
+    };
     try {
         rendered = renderSchema(schema, defs, new Set(), 0, {
-            propertyDescriptions: false,
-            requiredFirst: true,
+            ...base,
             // Three near-cap enums spend about three quarters of the complete shape
             // budget, leaving the final quarter for surrounding syntax before the
             // unchanged global fallback applies. Whole values keep this UTF-8 safe.
-            enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-            onEnumTruncated: () => {
-                enumTruncated = true;
-            },
             renderConstraints: true,
             constraintByteLimit: MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
             onConstraintTruncated: () => {
@@ -635,12 +626,7 @@ export function compactDiscoverySchema(schema) {
         MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
         try {
             rendered = renderSchema(schema, defs, new Set(), 0, {
-                propertyDescriptions: false,
-                requiredFirst: true,
-                enumByteLimit: MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-                onEnumTruncated: () => {
-                    enumTruncated = true;
-                },
+                ...base,
                 renderConstraints: false,
             });
             constraintTruncated = true;
@@ -683,10 +669,7 @@ export function compactDiscoverySchema(schema) {
 export function schemaObjectKeys(schema) {
     if (!schema)
         return undefined;
-    const defs = {
-        ...schema.$defs,
-        ...schema.definitions,
-    };
+    const defs = defsOf(schema);
     try {
         return objectKeys(schema, defs, new Set(), 0);
     }

package/dist/connector-scope.js

@@ -1,3 +1,4 @@
+import { sleep } from "./timeout.js";
 /** Enough for local transport abort/close without letting cleanup own latency. */
 const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
 /**
@@ -11,13 +12,7 @@ const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
 const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
 /** Resolve when `work` settles or `budgetMs` expires; never reject. */
 function waitAtMost(work, budgetMs) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, budgetMs);
-        work.then(() => {
-            clearTimeout(timer);
-            resolve();
-        });
-    });
+    return Promise.race([work, sleep(budgetMs)]).then(() => { });
 }
 /**
  * Tell a connector that a scope owned by the core has ended.

package/dist/connectors/api.d.ts

@@ -1,4 +1,7 @@
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorCredentialConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, CredentialTestResult, JsonSchema, ToolAnnotations } from "../types.js";
+export declare function defined<T extends object>(value: T): {
+    [K in keyof T]?: Exclude<T[K], undefined>;
+};
 export interface ApiTool {
     name: string;
     /**
@@ -63,20 +66,5 @@ export interface ApiOptions {
     validateArgs?: boolean;
     tools: ApiTool[];
 }
-/**
- * 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.
- *
- * 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.
- */
+/** A static connector; see provider conventions' two construction-time checks. */
 export declare function api(id: string, opts: ApiOptions): Connector;

package/dist/connectors/api.js

@@ -1,14 +1,8 @@
 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.
- */
+export function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+/** Enforce provider conventions' two construction-time checks. */
 function checkToolContract(id, tool) {
     const address = `${id}.${tool.name}`;
     if (typeof tool.description !== "string" || tool.description.trim() === "") {
@@ -25,55 +19,34 @@ function checkToolContract(id, tool) {
     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.
- *
- * 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.
- */
+/** A static connector; see provider conventions' two construction-time checks. */
 export function api(id, opts) {
     for (const t of opts.tools)
         checkToolContract(id, t);
     const defs = opts.tools.map((t) => ({
         name: t.name,
         description: t.description,
-        ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
-        ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
+        ...defined({
+            inputSchema: t.inputSchema,
+            outputSchema: t.outputSchema,
+        }),
         annotations: t.annotations,
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
     return {
         id,
-        ...(opts.title !== undefined ? { title: opts.title } : {}),
+        ...defined({ title: opts.title }),
         kind: "api",
-        ...(opts.description !== undefined
-            ? { description: opts.description }
-            : {}),
-        ...(opts.maxResultBytes !== undefined
-            ? { maxResultBytes: opts.maxResultBytes }
-            : {}),
-        ...(opts.callAdmission !== undefined
-            ? { callAdmission: opts.callAdmission }
-            : {}),
-        ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
-        ...(opts.credential !== undefined ? { credential: opts.credential } : {}),
-        ...(opts.testCredential !== undefined
-            ? { testCredential: opts.testCredential }
-            : {}),
-        ...(opts.testCredentials !== undefined
-            ? { testCredentials: opts.testCredentials }
-            : {}),
+        ...defined({
+            description: opts.description,
+            maxResultBytes: opts.maxResultBytes,
+            callAdmission: opts.callAdmission,
+            usageGuide: opts.usageGuide,
+            credential: opts.credential,
+            testCredential: opts.testCredential,
+            testCredentials: opts.testCredentials,
+        }),
         staticTools: defs,
         async listTools() {
             return defs;

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

@@ -44,7 +44,15 @@ interface GuardedResponse {
     text(): Promise<string>;
     /** The body parsed as JSON; `undefined` for an empty body, throws on junk. */
     json(): Promise<unknown>;
+    /** Parse JSON while distinguishing malformed content from transport failure. */
+    jsonResult(): Promise<{
+        value: unknown;
+    } | {
+        parseError: unknown;
+    }>;
 }
+/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+export declare function retryAfterMs(headers: Headers): number | undefined;
 /**
  * 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
@@ -79,28 +87,6 @@ export interface GuardedFetchOptions {
 }
 /** 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();
- * });
- * ```
- */
+/** Build the guarded transport described in documentation/connectors.md. */
 export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
 export {};

package/dist/connectors/guarded-fetch.js

@@ -1,26 +1,15 @@
-/**
- * The mechanical half of a hand-written connector's HTTP transport.
- *
- * Every `api()` surface that speaks HTTP re-derives the same handful of safety
- * properties: the request lands inside the base URL and nowhere else, the
- * credential rides exactly one origin, an unreachable provider becomes a typed
- * failure instead of a raw `TypeError`, and the response is read with a
- * ceiling on it. Cloudflare and Notion each grew a private copy of that
- * machinery, subtly different in ways neither author intended, and a third
- * author would have grown a third.
- *
- * What this deliberately does not own is *meaning*. It never reads a status
- * code, never decides a 403 is recoverable, and never invents an
- * authentication scheme: `authenticate` supplies the headers, and the caller's
- * mapper reads the response. That split is not fastidiousness — Notion's 403
- * (a capability the integration was never granted, which re-authorizing cannot
- * fix) and Cloudflare's 403 (a token scope) want opposite next moves, and no
- * shared helper can tell them apart without provider knowledge it has no
- * business holding.
- *
- * Web APIs only: this is reachable from the root entry and stays that way.
- */
+/** See documentation/connectors.md#the-guarded-fetch-transport. Web APIs only. */
 import { ConnectorCallError } from "../errors.js";
+/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+export function retryAfterMs(headers) {
+    const raw = headers.get("retry-after");
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw.trim());
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return Math.trunc(seconds * 1000);
+}
 /** Statuses that instruct a client to re-send somewhere else. Never followed. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 /** Statuses the HTTP spec defines as carrying no body at all. */
@@ -128,30 +117,18 @@ async function drain(provider, stream, limit) {
     }
     return body;
 }
-/**
- * Wrap a `Response` in the bounded read surface.
- *
- * Three paths, for one honest reason. A status the spec says carries no body
- * is answered as empty without touching the response at all. Otherwise, when
- * the runtime hands back a readable body — every real response on Node and on
- * Workers — the ceiling is enforced *while* reading, so an oversized payload
- * is abandoned rather than buffered. When it does not, there is nothing to
- * meter mid-flight: `bytes()` and `text()` read the body whole and check the
- * ceiling against what came back, and `json()` — with no bytes of its own to
- * count — takes the stand-in at its word. That last path is the weaker
- * guarantee and says so, but a real `fetch` Response with a body always
- * streams, so it is not a path a provider takes in production; it is what a
- * hand-built test double gets.
- */
+/** See documentation/connectors.md#the-guarded-fetch-transport. */
 function boundedResponse(provider, response, limit) {
     if (BODILESS_STATUSES.has(response.status)) {
+        const emptyJson = async () => undefined;
         return {
             status: response.status,
             ok: response.ok,
             headers: response.headers,
             bytes: async () => new Uint8Array(),
             text: async () => "",
-            json: async () => undefined,
+            json: emptyJson,
+            jsonResult: () => jsonResult(emptyJson),
         };
     }
     const stream = readableBody(response);
@@ -167,6 +144,15 @@ function boundedResponse(provider, response, limit) {
             });
         return read;
     };
+    const json = async () => {
+        // No stream means no bytes to count: a stand-in that answers `json()`
+        // directly is taken at its word, which is the one accessor on the one
+        // path where the ceiling cannot be applied.
+        if (!stream)
+            return await response.json();
+        const body = decoder.decode(await bytes());
+        return body.trim() === "" ? undefined : JSON.parse(body);
+    };
     return {
         status: response.status,
         ok: response.ok,
@@ -181,40 +167,21 @@ function boundedResponse(provider, response, limit) {
                 throw oversized(provider, limit, `${size} bytes`);
             return body;
         },
-        async json() {
-            // No stream means no bytes to count: a stand-in that answers `json()`
-            // directly is taken at its word, which is the one accessor on the one
-            // path where the ceiling cannot be applied.
-            if (!stream)
-                return await response.json();
-            const body = decoder.decode(await bytes());
-            return body.trim() === "" ? undefined : JSON.parse(body);
-        },
+        json,
+        jsonResult: () => jsonResult(json),
     };
 }
-/**
- * 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();
- * });
- * ```
- */
+async function jsonResult(read) {
+    try {
+        return { value: await read() };
+    }
+    catch (cause) {
+        if (cause instanceof ConnectorCallError)
+            throw cause;
+        return { parseError: cause };
+    }
+}
+/** Build the guarded transport described in documentation/connectors.md. */
 export function guardedFetch(options) {
     const { provider, maxResponseBytes: limit } = options;
     if (!Number.isInteger(limit) || limit < 1) {
@@ -257,12 +224,7 @@ export function guardedFetch(options) {
                     : request.rawBody !== undefined
                         ? { body: request.rawBody }
                         : {}),
-                // Never follow a redirect. A 3xx is an instruction to re-send the
-                // connector's credential to whatever origin the Location names, and a
-                // confinement a redirect can undo was never a confinement. There is no
-                // ambient credential to omit besides that — neither runtime's `fetch`
-                // keeps a cookie jar — so the headers `authenticate` returned are the
-                // only authority the request carries.
+                // Rationale: documentation/connectors.md#the-guarded-fetch-transport.
                 redirect: "manual",
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             });