@zackbart/connecta 0.34.0 → 0.35.0

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[];

package/dist/providers/_shared/rest/value-safety.d.ts

@@ -1,201 +0,0 @@
-import type { Operation, OperationIndex } from "./operation-index.js";
-/** What a removed secret reads as. */
-export declare const REDACTED = "[redacted]";
-/** Credential vocabulary over normalized names, matched anywhere; mirrors `scripts/value-safety.mjs`. */
-export declare const CREDENTIAL_WORDS: string[];
-/** Credential vocabulary matched at the end of a normalized name; mirrors the script. */
-export declare const CREDENTIAL_SUFFIX: RegExp;
-/** Suffixes of metadata about a credential (ids, prefixes, last four, counts, expiry, scopes); mirrors the script. */
-export declare const METADATA_SUFFIXES: string[];
-/** Exact metadata names that contain a credential word; mirrors the script. */
-export declare const METADATA_NAMES: string[];
-export type ValueSafetyVerdict = {
-    readonly verdict: "refuse";
-    readonly reason: string;
-} | {
-    readonly verdict: "redact";
-    readonly reason: string;
-    /**
-     * Reviewed field paths into the data a tool returns: `a.b` (a list on
-     * the way is traversed item by item), `[]` for list items, `{}` or `*`
-     * for every value of a map, `@keys` for a map keyed by secrets (keys
-     * become placeholders), `[?env]` for list items whose `type` names an
-     * environment variable, `[?credential]` for list items labelled with a
-     * credential name, `[?header]` for header, cookie, or query rules. A
-     * `url:` prefix sanitizes a URL; an `origin:` prefix (or `#url` suffix)
-     * keeps only its scheme and host. Every other value at a path becomes
-     * `[redacted]`.
-     */
-    readonly paths: readonly string[];
-    /** Reviewed metadata paths the key-name heuristic leaves (children are still checked). */
-    readonly keep?: readonly string[];
-    /** See the `safe` verdict. */
-    readonly errors?: "vendor";
-} | {
-    readonly verdict: "safe";
-    readonly reason: string;
-    /** Reviewed metadata paths the key-name heuristic leaves (children are still checked). */
-    readonly keep?: readonly string[];
-    /**
-     * The error policy. By default a reviewed operation's failures carry the
-     * vendor's codes and statuses but never its text, which may echo a
-     * stored secret. `vendor` is a reviewed exception for operations whose
-     * errors cannot: the vendor's text passes (and still meets the
-     * sent-secrets matcher).
-     */
-    readonly errors?: "vendor";
-};
-/** One field name reviewed for a whole vendor whose objects repeat across operations (Stripe's). */
-interface FieldReview {
-    readonly verdict: "redact" | "keep";
-    readonly reason: string;
-}
-/**
- * A reviewed rule for one resource type, applied to every object whose
- * discriminator names it wherever a response embeds it: the top level, a list,
- * a search result, an expansion, an event's `data.object`. Operation verdicts
- * review what an operation returns by shape; resource rules are the backstop
- * for what expansions can put anywhere.
- */
-/**
- * When an object is provably unbound (a guest Checkout Session), stated as
- * data so `providers:spec` can hold it to the pinned schema: every binding
- * field the schema has must be listed, in `bindings` or, with a reason, in
- * `unbound`.
- */
-interface GuestCondition {
-    /**
-     * Fields that bind the object to an identity or its saved methods. Each
-     * must be absent, null, empty, or one of the listed values that bind
-     * nothing (`customer_creation: "if_required"`).
-     */
-    readonly bindings: Readonly<Record<string, readonly string[]>>;
-    /** Identity-named fields that bind nothing (guest prefill or collected details), with the reason. */
-    readonly unbound: Readonly<Record<string, string>>;
-    /** Fields whose value must be one of these (a Checkout Session's `mode: "payment"`). */
-    readonly requires?: Readonly<Record<string, readonly string[]>>;
-}
-interface ResourceRule {
-    readonly reason: string;
-    /** Reviewed paths relative to the object, in the operation path language. */
-    readonly paths?: readonly string[];
-    /**
-     * Fields whose string is a payer-facing URL the resource exists to hand out
-     * (a guest Checkout page), returned without URL sanitizing: its fragment is
-     * opaque state the page needs. With `guest`, only while the object is
-     * provably a guest's; otherwise its `withheld` paths go.
-     */
-    readonly verbatim?: readonly string[];
-    readonly guest?: GuestCondition;
-    readonly withheld?: readonly string[];
-}
-interface ResourceRules {
-    /** The field that names an object's type (Stripe's `object`). */
-    readonly key: string;
-    /** Sibling fields holding a partial copy of a discriminated object (an event's `previous_attributes`). */
-    readonly partials?: readonly string[];
-    readonly rules: Readonly<Record<string, ResourceRule>>;
-}
-export interface ValueSafetyTable {
-    /** Display name in refusals. */
-    readonly title: string;
-    /** Global signing names plus generic credential names only on these reviewed response paths. */
-    readonly embeddedUrls?: {
-        readonly operations?: Readonly<Record<string, readonly string[]>>;
-        /** Discriminated resources, wherever lists, expansions, or events embed them. */
-        readonly resources?: {
-            readonly key: string;
-            readonly partials?: readonly string[];
-            readonly paths: Readonly<Record<string, readonly string[]>>;
-        };
-    };
-    /** The reviewed verdict for every flagged operation, keyed `METHOD /path template`. */
-    readonly operations: Readonly<Record<string, ValueSafetyVerdict>>;
-    /**
-     * Field names reviewed once for the vendor: `redact` wherever the name
-     * appears, `keep` as metadata the heuristic leaves wherever it appears
-     * (children are still checked). Keyed by the exact field name.
-     */
-    readonly fields?: Readonly<Record<string, FieldReview>>;
-    /** Operations whose whole body is environment variables: every value field goes, `key` or not. */
-    readonly envBodies?: RegExp;
-    /** Keys whose string-list values are permission scopes (action names under a resource), never secrets. */
-    readonly scopeMaps?: readonly string[];
-    /** Rules for resource types wherever they appear, for vendors whose objects carry a type discriminator. */
-    readonly resources?: ResourceRules;
-}
-export declare const refuse: (reason: string) => ValueSafetyVerdict;
-export declare const redact: (reason: string, paths: readonly string[], keep?: readonly string[]) => ValueSafetyVerdict;
-export declare const safe: (reason: string, keep?: readonly string[]) => ValueSafetyVerdict;
-/** A verdict whose failures keep the vendor's text: reviewed, for operations whose errors echo no stored secret. */
-export declare const vendorErrors: (verdict: ValueSafetyVerdict) => ValueSafetyVerdict;
-/** Paths under each prefix; a `url:` or `origin:` directive stays in front. */
-export declare function under(prefixes: readonly string[], paths: readonly string[]): string[];
-/**
- * Whether a key names a credential: a credential word anywhere in a name
- * that is not metadata (Vercel's former rule), or a credential suffix
- * (Cloudflare's).
- */
-export declare function credentialName(name: string): boolean;
-/** Where a vendor stores the files it signs. */
-export interface FileHosts {
-    /** Hosts matched whole or as a parent domain: `file.notion.so` covers `img.file.notion.so`. */
-    readonly domains: readonly string[];
-    /** S3 buckets, virtual-hosted or as the first path segment on an S3 endpoint. Never all of S3. */
-    readonly buckets: readonly string[];
-}
-/**
- * `text` with every pre-signed link withheld: at one of `hosts` (Notion's
- * file storage, say), its whole query and fragment; anywhere, a signing
- * parameter's value. Everything else comes back byte for byte.
- */
-export declare function withholdSignedLinks(text: string, hosts: FileHosts): string;
-/**
- * Reviewed REST text policy: only credential-bearing URL queries/fragments
- * change. Ordinary links, including external proxies, retain their bytes.
- * Literal AWS/Google signing names are withheld anywhere, as in #818.
- */
-export declare function withholdEmbeddedUrls(text: string): string;
-/** Every string inside a JSON value through `withholdSignedLinks`; unchanged values keep their identity. */
-export declare function withholdSignedLinksIn(value: unknown, hosts: FileHosts, depth?: number): unknown;
-/** Apply the reviewed text policy to a selected value or vendor error body. */
-export declare function withholdEmbeddedUrlsIn(value: unknown): unknown;
-/**
- * Whether a request value carries a link whose query or
- * fragment holds the exact `[redacted]` placeholder, plain or encoded: a
- * withheld read copied into a write, which would store the placeholder.
- * Only the link's own destination is read: a Markdown link ends at its
- * closing `)`, so `[f](…?a=1)[redacted]` is ordinary text after it.
- * The word alone (`unredacted`) or the placeholder away from a file link is
- * a person's text. When `hosts` is supplied, require its actual authority
- * to match that policy, preserving Notion's external-proxy boundary.
- */
-export declare function carriesWithheldLink(value: unknown, hosts?: FileHosts): boolean;
-/** Refuse a withheld destination copied into customer data, before any dispatch. */
-export declare function refuseWithheldLinks(value: unknown, title: string): void;
-/** Upload admission inspects actual bytes, including base64-decoded files and multipart blobs. */
-export declare function refuseWithheldUpload(body: BodyInit, title: string): Promise<void>;
-/** Only for documented JSON fields the vendor decodes as base64, never arbitrary strings. */
-export declare function refuseWithheldBase64(value: unknown, title: string, maxDecodedBytes?: number): Promise<void>;
-/** Whether every segment of a reviewed path is in the path language; the harness checks each table. */
-export declare function validPath(raw: string): boolean;
-/** What a vendor's tools ask of its reviewed table. */
-export interface ValueSafety {
-    readonly table: ValueSafetyTable;
-    /** The reviewed verdict for an operation, if it was flagged. */
-    verdict(method: string, template: string): ValueSafetyVerdict | undefined;
-    /** The refusal for a `refuse` verdict, before anything is sent. */
-    refusal(method: string, template: string): string | undefined;
-    /** One success body made value-safe: reviewed paths, environment bodies, resource rules, then the heuristic. */
-    redact(data: unknown, method: string, template: string): unknown;
-    /**
-     * Whether a failure's vendor text is withheld: any reviewed operation
-     * unless its verdict says `errors: "vendor"`, or an unreviewed one whose
-     * request accepts a credential-named field (an error may echo what was
-     * submitted). Codes and statuses still route.
-     */
-    withholdsErrors(op: Operation): boolean;
-}
-/** A vendor's value-safety mechanism over its reviewed table and pinned index. */
-export declare function valueSafety(table: ValueSafetyTable, index: () => OperationIndex): ValueSafety;
-export {};

package/dist/providers/basecamp/index.d.ts

@@ -1,43 +0,0 @@
-import type { ConnectorCallAdmissionPolicy } from "../../types.js";
-/**
- * Basecamp's one hosted MCP endpoint, streamable HTTP.
- *
- * Live but undocumented: as of 2026-10-05 37signals has announced no MCP
- * server, and basecamp.com/agents (where the endpoint's own 401 body points)
- * describes the CLI and SDKs without naming it. What the server does publish is
- * its OAuth discovery — protected-resource metadata naming
- * `https://app.basecamp.com` as the authorization server — and that is what
- * this provider is written against, beside a captured live `tools/list`.
- */
-export declare const BASECAMP_MCP_ENDPOINT = "https://mcp.basecamp.com/mcp";
-export interface BasecampOptions {
-    /** Human-readable display name; defaults to "Basecamp". */
-    title?: string;
-    /**
-     * Downstream auth ownership. Defaults to one shared deployment grant. With
-     * `"personal"` each principal authorizes separately and may pick a
-     * different Basecamp account at consent, which the guide says.
-     */
-    authScope?: "shared" | "personal";
-    /** Which Basecamp account this is and what decisions it answers. */
-    purpose: string;
-    /** Optional external CIMD URL. Defaults to this deployment's public HTTPS document. */
-    clientMetadataUrl?: string;
-    /** Account-specific conventions appended to the maintained provider guide. */
-    instructions?: string;
-    /** Connector-specific inline result limit; omit to inherit the deployment. */
-    maxResultBytes?: number;
-    /**
-     * Optional per-runtime policy. There is no default: Basecamp's API documents
-     * several dynamically adjusted limits (GET versus POST, per second, hour,
-     * and day) and quotes only "currently 50 requests per 10 second period per
-     * IP address" for scale — metered at the IP that calls the API, which is
-     * Basecamp's own MCP server rather than this runtime. A per-runtime counter
-     * approximates none of that, so the operator picks (P12).
-     */
-    callAdmission?: ConnectorCallAdmissionPolicy;
-}
-/** A maintained Basecamp hosted-MCP connection. */
-export declare const basecamp: import("../../provider.js").ProviderFactory<BasecampOptions>;
-/** @deprecated Read `basecamp.definition.classify` instead. Kept for existing imports. */
-export declare const BASECAMP_VETTED_CATALOG: import("../../catalog-drift.js").VettedCatalog;