@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/_shared/request-token.js

@@ -1,83 +0,0 @@
-/** In-memory tokens and credential-bound login flights shared only inside one request. */
-import { ConnectorCallError } from "../../errors.js";
-const LOGIN_TIMEOUT_MS = 15_000;
-const MAX_CACHED_TOKENS = 512;
-/** Each provider instance owns its cache, so no credential crosses an API origin. */
-export function requestTokenCache(source) {
-    const tokens = new Map();
-    const requests = new WeakMap();
-    function start(auth, ctx) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(new ConnectorCallError("unavailable", "Machine identity login timed out.")), LOGIN_TIMEOUT_MS);
-        const flight = { controller, waiters: 0, settled: false, promise: Promise.resolve("") };
-        flight.promise = auth
-            .mint({ ...ctx, signal: controller.signal })
-            .then((minted) => {
-            // An abandoned login must not seed a token after cancellation.
-            controller.signal.throwIfAborted();
-            tokens.delete(auth.key);
-            tokens.set(auth.key, minted);
-            while (tokens.size > MAX_CACHED_TOKENS)
-                tokens.delete(tokens.keys().next().value);
-            return minted.accessToken;
-        })
-            .finally(() => {
-            flight.settled = true;
-            clearTimeout(timer);
-        });
-        // All waiters may cancel before the transport observes its abort.
-        void flight.promise.catch(() => { });
-        return flight;
-    }
-    async function follow(flight, signal) {
-        signal?.throwIfAborted();
-        flight.waiters++;
-        let onAbort;
-        try {
-            const aborted = new Promise((_, reject) => {
-                if (!signal)
-                    return;
-                onAbort = () => reject(signal.reason);
-                signal.addEventListener("abort", onAbort, { once: true });
-            });
-            return await Promise.race([flight.promise, aborted]);
-        }
-        finally {
-            if (onAbort)
-                signal?.removeEventListener("abort", onAbort);
-            flight.waiters--;
-            if (!flight.settled && flight.waiters === 0)
-                flight.controller.abort();
-        }
-    }
-    return {
-        async token(ctx, rejected) {
-            ctx.signal?.throwIfAborted();
-            const auth = await source(ctx);
-            ctx.signal?.throwIfAborted();
-            const cached = tokens.get(auth.key);
-            if (cached && cached.accessToken !== rejected && cached.expiresAt > Date.now())
-                return cached.accessToken;
-            const scope = ctx.requestScope ?? ctx;
-            let perCredential = requests.get(scope);
-            if (!perCredential) {
-                perCredential = new Map();
-                requests.set(scope, perCredential);
-            }
-            let request = perCredential.get(auth.key);
-            if (!request) {
-                request = {};
-                perCredential.set(auth.key, request);
-            }
-            if (rejected !== undefined) {
-                // Keep the recovery outcome for the request, including failures. Later
-                // 401s can never turn this into a fresh-login loop.
-                request.recovery ??= start(auth, ctx);
-                return await follow(request.recovery, ctx.signal);
-            }
-            if (!request.initial || request.initial.settled || request.initial.controller.signal.aborted)
-                request.initial = start(auth, ctx);
-            return await follow(request.initial, ctx.signal);
-        },
-    };
-}

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

@@ -1,41 +0,0 @@
-// Auth selects the implementation (decisions/0005): a `"dual"` provider sends
-// OAuth to the vendor's hosted MCP server and a key to Connecta's own REST
-// connector. The choice is made once, at construction, from `auth.type`; one
-// connector id is one implementation, and a failure on one is never replayed
-// against the other (INV-9).
-import { remoteMcp } from "../../../connectors/remote-mcp.js";
-/**
- * A provider `create` that dispatches on `options.auth.type`. Pair it with
- * `variants(["auth", "type"], …)` options, which refuse a missing or unknown
- * type, and options the selected case does not accept, before this runs.
- */
-export function byAuth(cases) {
-    return (id, options, provider) => {
-        const type = options.auth?.type;
-        const create = typeof type === "string" && Object.hasOwn(cases, type) ? cases[type] : undefined;
-        if (!create) {
-            throw new Error(`auth.type must be one of ${Object.keys(cases)
-                .map((name) => JSON.stringify(name))
-                .join(", ")}.`);
-        }
-        return create(id, options, provider);
-    };
-}
-/**
- * The vendor's hosted MCP server, OAuth only: no bearer token, header, or
- * operator credential reaches a hosted endpoint. The provider's reviewed
- * classification classifies its catalog.
- */
-export function hostedOAuth(id, provider, options) {
-    return remoteMcp(id, {
-        url: options.url,
-        ...provider.connectorOptions,
-        title: options.title,
-        description: options.description,
-        auth: { type: "oauth" },
-        requireHttps: true,
-        classify: provider.classify,
-        ...(options.callAdmission ? { callAdmission: options.callAdmission } : {}),
-        usageGuide: options.usageGuide,
-    });
-}

package/dist/providers/_shared/rest/operation-index.d.ts

@@ -1,133 +0,0 @@
-import type { JsonSchema } from "../../../types.js";
-export type RestMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
-/**
- * One request-side schema, compacted: `t` type, `e` enum, `f` format (only
- * `binary`), `n` nullable, `d` description, `a` anyOf/oneOf, `p` properties,
- * `r` required, `i` items, `m` additionalProperties, `x` truncated at the
- * generation depth (unvalidated below), `$` a shared subtree.
- */
-export interface SchemaNode {
-    readonly t?: string | readonly string[];
-    readonly e?: readonly unknown[];
-    readonly f?: string;
-    readonly n?: 1;
-    readonly d?: string;
-    readonly a?: readonly SchemaNode[];
-    readonly p?: Readonly<Record<string, SchemaNode>>;
-    readonly r?: readonly string[];
-    readonly i?: SchemaNode;
-    readonly m?: SchemaNode;
-    readonly x?: 1;
-    readonly $?: number;
-}
-/** `[method, path template, operationId, summary, tag index, server index?]` */
-type OperationRow = readonly [string, string, string, string, number, number?];
-/** What `scripts/generate-openapi.mjs` writes to `openapi.generated.ts`. */
-export interface OpenApiData {
-    /** The pinned document's URL. */
-    readonly source: string;
-    /** The pin: a tag, commit, or content hash. */
-    readonly revision: string;
-    /** `sha256:` digest of the pinned document's bytes. */
-    readonly digest: string;
-    /** The document's `info.version`; Stripe sends it as `Stripe-Version`. */
-    readonly version: string;
-    /** `[0]` is the default origin; later entries are per-operation servers. */
-    readonly servers: readonly string[];
-    readonly tags: readonly string[];
-    readonly ops: readonly OperationRow[];
-    /** JSON: `{ d: SchemaNode[], o: (0 | [params, body])[] }`, aligned with `ops`. */
-    readonly details: string;
-}
-export interface Operation {
-    readonly method: RestMethod;
-    /** The path template, e.g. `/v1/customers/{customer}`. */
-    readonly path: string;
-    readonly operationId: string;
-    readonly summary: string;
-    readonly tag: string;
-    /** A non-default origin this operation is served from, if any. */
-    readonly server: string | undefined;
-    /** Position in `OpenApiData.ops`. */
-    readonly row: number;
-}
-/** A concrete call matched to its operation. */
-export interface OperationMatch {
-    readonly op: Operation;
-    /** Path parameter values, exactly as the caller sent them. */
-    readonly params: Readonly<Record<string, string>>;
-}
-/** One operation's request contract, expanded to JSON Schema for an agent. */
-export interface OperationContract {
-    method: RestMethod;
-    path: string;
-    operationId: string;
-    summary: string;
-    server?: string;
-    parameters: {
-        name: string;
-        in: "path" | "query";
-        required: boolean;
-        description?: string;
-        schema: JsonSchema;
-    }[];
-    body?: {
-        contentType: string;
-        required?: true;
-        schema: JsonSchema;
-    };
-}
-/** The read side of one vendor's pinned index. */
-export declare class OperationIndex {
-    #private;
-    readonly version: string;
-    readonly revision: string;
-    readonly ops: readonly Operation[];
-    /** The methods any operation uses, in a stable order. */
-    readonly methods: readonly RestMethod[];
-    /**
-     * `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: OpenApiData, names: {
-        vendor: string;
-        title: string;
-        slashParams?: readonly string[];
-    });
-    /** The operation with this exact method and path template, if any. */
-    operation(method: string, template: string): Operation | undefined;
-    /**
-     * 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: string, path: string): OperationMatch;
-    /** Up to five operations whose paths most resemble a missed one. */
-    nearest(method: string, segments: readonly string[]): string[];
-    /**
-     * 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: string, options: {
-        method?: RestMethod;
-        limit: number;
-    }): Operation[];
-    /** Whether the operation takes a body, and in which framing. */
-    bodyType(op: Operation): string | undefined;
-    /** The operation's request contract as JSON Schema, optionally one parameter only. */
-    contract(op: Operation, only?: string): OperationContract;
-    /**
-     * 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: Operation, query: Readonly<Record<string, unknown>>, body: unknown): void;
-}
-export {};

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

@@ -1,141 +0,0 @@
-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[];