@zackbart/connecta 0.24.4 → 0.26.0

package/dist/catalog-service.d.ts

@@ -1,263 +0,0 @@
-import type { CallErrorDetails } from "./errors.js";
-import type { ConnectorOperationOptions, RegistryView } from "./registry.js";
-import type { DeferredWork } from "./connector-scope.js";
-import type { Connector, ToolDef } from "./types.js";
-export declare const DEFAULT_SEARCH_LIMIT = 8;
-export declare const MAX_SEARCH_LIMIT = 100;
-export declare const MAX_DESCRIBE_ADDRESSES = 100;
-export declare const MAX_DISCOVERY_RESULT_BYTES = 256000;
-/**
- * The discovery route a routing failure should send a caller back through. Same
- * catalog logic serves both the top-level `search_tools` path and the
- * in-program `connecta.search` path, so callers pass the route they own.
- */
-export type SearchRoute = "search_tools" | "connecta.search";
-export declare class DiscoveryPolicyError extends Error {
-    readonly code: "invalid_args" | "result_too_large";
-    constructor(code: "invalid_args" | "result_too_large", message: string);
-}
-/** Serialize once and count the exact bytes the MCP adapter would emit. */
-export declare function boundedDiscoveryText(value: unknown, hint: string): string;
-export interface CatalogSearchArgs {
-    query?: string;
-    connector?: string;
-    /**
-     * Result classification only; never changes which tools exist or what may
-     * execute. Omitted and "all" preserve the complete configured catalog.
-     */
-    safety?: "readOnly" | "approvalRequired" | "all";
-    limit?: number;
-    offset?: number;
-    fullDescriptions?: boolean;
-    includeSchemas?: "compact" | "json";
-    /** Code-mode helper metadata; never exposed by the public search_tools schema. */
-    includeSchemaKeys?: boolean;
-}
-export interface CatalogDescribeArgs {
-    address?: unknown;
-    addresses?: unknown;
-    format?: "compact" | "json";
-    fullDescriptions?: boolean;
-}
-interface CatalogSearchEntry {
-    connector: Connector;
-    guide?: string;
-    guideSummary?: string;
-    tool: {
-        name: string;
-        address: string;
-        description?: string;
-        inputSchema?: unknown;
-        outputSchema?: unknown;
-        outputSchemaSource?: "observed";
-        inputSchemaTruncated?: true;
-        outputSchemaTruncated?: true;
-        inputKeys?: string[];
-        requiredInputKeys?: string[];
-        outputKeys?: string[];
-        annotations?: ToolDef["annotations"];
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-    };
-}
-type GuideRequiredReason = "connector_required" | "approval_required" | "schema_truncated";
-/**
- * The classified-failure subset a scoped search may echo: enough to tell a
- * transient outage from one an operator must clear, and nothing more. Kept as
- * its own type rather than `CallErrorDetails` so widening the call-path
- * classifier cannot widen this discovery-surface field by accident.
- */
-interface CatalogFailureDetail {
-    code: string;
-    message: string;
-    retryable: boolean;
-    retryAfterMs?: number;
-}
-interface CatalogDescriptionFailureDetail extends CatalogFailureDetail {
-    nextAction?: NonNullable<CallErrorDetails["nextAction"]>;
-    /** Nearby canonical addresses, ranked deterministically by tool name. */
-    suggestions?: string[];
-}
-export interface CatalogSearchPage {
-    entries: CatalogSearchEntry[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    nextOffset?: number;
-    matchMode?: "partial";
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-}
-export interface CatalogDescription {
-    address: string;
-    name?: string;
-    description?: string;
-    guide?: string;
-    guideSummary?: string;
-    guideRequired?: true;
-    guideRequiredReasons?: GuideRequiredReason[];
-    inputSchema?: unknown;
-    outputSchema?: unknown;
-    outputSchemaSource?: "observed";
-    inputSchemaTruncated?: true;
-    outputSchemaTruncated?: true;
-    annotations?: ToolDef["annotations"];
-    error?: string;
-    errorDetails?: CatalogDescriptionFailureDetail;
-}
-export interface ResolvedCatalogTool {
-    connector: Connector;
-    toolName: string;
-    definition: ToolDef;
-}
-export type CatalogResolution = {
-    ok: true;
-    resolved: ResolvedCatalogTool;
-    catalogMs: number;
-} | {
-    ok: false;
-    error: CallErrorDetails;
-    catalogMs: number;
-    connector?: Connector;
-    toolName?: string;
-    cause?: unknown;
-};
-/**
- * Request-local catalog operations shared by MCP meta-tools and code mode.
- * Successful catalogs may be reused inside this request; failures are not
- * retained, and the service itself never escapes its request adapter.
- */
-export declare class CatalogService {
-    private readonly registry;
-    readonly baseUrl: string;
-    readonly requestScope: object;
-    private readonly probeTimeoutMs;
-    private readonly concurrency;
-    private readonly searchRoute;
-    private readonly readOptions;
-    private readonly loaded;
-    private readonly loading;
-    constructor(registry: RegistryView, baseUrl: string, options?: {
-        requestScope?: object | undefined;
-        probeTimeoutMs?: number | undefined;
-        concurrency?: number | undefined;
-        /** The discovery route recovery records name. Default `search_tools`. */
-        searchRoute?: SearchRoute | undefined;
-        /** Runtime-owned tail for stale-while-revalidate catalog reads. */
-        defer?: DeferredWork | undefined;
-    });
-    /**
-     * Send a caller back to discovery through the surface it can actually reach.
-     * Both variants carry the same scoping arguments because `connecta.search`
-     * takes the same ones `search_tools` does; only the key naming the callable
-     * differs, the way the ambiguous-alias record already names a function.
-     *
-     * Not private: `InvocationService` builds the same class of record when a
-     * call fails schema validation, and it is this catalog's route that decides
-     * which key that record carries. Duplicating the branch there would let the
-     * two drift.
-     */
-    searchRecovery(args: {
-        query: string;
-        connector?: string;
-    }, purpose: string): NonNullable<CallErrorDetails["nextAction"]>;
-    loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
-    private loadForDiscovery;
-    private outputSchema;
-    private unknownAddressFailure;
-    private catalogLoadFailure;
-    private unknownToolFailure;
-    resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;
-    search(args: CatalogSearchArgs): Promise<CatalogSearchPage>;
-    describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]>;
-}
-export declare function groupedSearchResult(page: CatalogSearchPage): {
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-    matchMode?: "partial";
-    nextOffset?: number;
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    connectors: {
-        id: string;
-        title?: string;
-        guide?: string;
-        guideSummary?: string;
-        tools: CatalogSearchEntry["tool"][];
-    }[];
-};
-export declare function flatSearchResult(page: CatalogSearchPage): {
-    queryAnalysis?: {
-        representedTerms: string[];
-        otherResultTerms: string[];
-        unmatchedTerms: string[];
-        truncated?: true;
-        connectorScope?: string;
-        unknownConnector?: true;
-        unavailableConnectorCount?: number;
-        /** Bounded typed failure for an explicitly scoped unavailable catalog. */
-        catalogError?: CatalogFailureDetail;
-        guide?: string;
-        guideSummary?: string;
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-        guidance?: string;
-    };
-    matchMode?: "partial";
-    nextOffset?: number;
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
-    tools: {
-        guideSummary?: string;
-        guide?: string;
-        connectorTitle?: string;
-        name: string;
-        address: string;
-        description?: string;
-        inputSchema?: unknown;
-        outputSchema?: unknown;
-        outputSchemaSource?: "observed";
-        inputSchemaTruncated?: true;
-        outputSchemaTruncated?: true;
-        inputKeys?: string[];
-        requiredInputKeys?: string[];
-        outputKeys?: string[];
-        annotations?: ToolDef["annotations"];
-        guideRequired?: true;
-        guideRequiredReasons?: GuideRequiredReason[];
-    }[];
-};
-export {};

package/dist/catalog.d.ts

@@ -1,87 +0,0 @@
-import type { JsonSchema, ToolDef } from "./types.js";
-export declare const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1024;
-export declare function summarizeDescription(text: string | undefined, full: boolean): string | undefined;
-export declare function summarizeDiscoveryDescription(text: string | undefined, full: boolean): string | undefined;
-/** Distinct normalized terms in query order, shared by ranking and feedback. */
-export declare function lexicalQueryTerms(query: string): string[];
-/**
- * Remove conversational framing before the all-term/partial decision. If
- * every term is framing, retain the original query rather than turning a
- * search into an unfiltered catalog browse.
- */
-export declare function lexicalSearchQuery(query: string): string;
-export type LexicalMatchMode = "all" | "partial";
-export interface RankedTool {
-    tool: ToolDef;
-    score: number;
-    order: number;
-    exactName: boolean;
-    matchedTermCount: number;
-}
-/**
- * Whether one query term matches a whole token of arbitrary text, under the
- * same inflection rules the tool index uses.
- *
- * Connector identity — an `id` or a `title` — is deliberately not a document in
- * that index: making it one would move ranking for every query that already
- * matches tools. This lets a caller ask the index's question of a string that
- * never became a document, which is what the no-match analysis needs to tell
- * "nothing like this exists here" from "that word is a connector".
- */
-export declare function matchesLexicalTerm(text: string, term: string): boolean;
-export interface LexicalCorpusStatistics {
-    documentCount: number;
-    documentFrequency: ReadonlyMap<string, number>;
-    nameMatches: ReadonlyMap<string, ReadonlySet<ToolDef>>;
-    descriptionMatches: ReadonlyMap<string, ReadonlySet<ToolDef>>;
-}
-/**
- * Compute query-specific document frequencies across every available catalog.
- * The caller does this once per search and shares the result with each
- * connector rank, so ubiquitous words contribute less than discriminative
- * ones without making any action word a stopword.
- */
-export declare function lexicalCorpusStatistics(toolSets: ToolDef[][], query: string): LexicalCorpusStatistics;
-/**
- * Rank a connector's tools while caching its normalized plain-data index.
- * `exactNameQuery` may retain framing removed from the scoring query: those
- * words are weak term evidence, but remain part of a real tool-name phrase.
- */
-export declare function rankTools(tools: ToolDef[], query: string, mode?: LexicalMatchMode, statistics?: LexicalCorpusStatistics, exactNameQuery?: string): RankedTool[];
-/** Render and cache a compact TypeScript-like representation of JSON Schema. */
-export declare function compactSchema(schema: JsonSchema): string;
-/** Describe allows 8 KiB for property prose, with the same work cap as search. */
-export declare function compactDescriptionSchema(schema: JsonSchema): CompactDiscoverySchema;
-export interface CompactDiscoverySchema {
-    text: string;
-    truncated: boolean;
-}
-/**
- * Render the schema shape carried by search results.
- *
- * Search is a routing step, so repeated property prose does not earn its
- * context cost there. Required inputs render first, and the result has a hard
- * UTF-8 budget; exact JSON and the prose-rich compact rendering remain
- * available through the existing full retrieval paths.
- */
-export declare function compactDiscoverySchema(schema: JsonSchema): CompactDiscoverySchema;
-/** The property and required names a schema resolves to, or undefined. */
-export interface SchemaObjectKeys {
-    properties: string[];
-    required: string[];
-}
-/**
- * Walk a schema the way renderSchema does — composing `allOf` and resolving
- * `$ref` against the root's `$defs`/`definitions` — and collect the top-level
- * property names it would render. A shallow `Object.keys(schema.properties)`
- * disagrees with the rendered compact schema for exactly the shapes real
- * connectors emit (a top-level `$ref` to a `$defs` entry, or the OpenAPI
- * "extend this base" `allOf`), which is worse than no metadata at all: it
- * reports an empty field list for a tool that plainly has fields.
- *
- * Returns undefined when the schema is not an object shape at all — a union,
- * array, enum, or unresolvable `$ref`. Absent metadata tells a caller to read
- * the rendered schema instead; an empty array would claim the tool takes no
- * fields.
- */
-export declare function schemaObjectKeys(schema: JsonSchema | undefined): SchemaObjectKeys | undefined;

package/dist/concurrency.d.ts

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

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

@@ -1,96 +0,0 @@
-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>;
-    /** Parse JSON while distinguishing malformed content from transport failure. */
-    jsonResult(): Promise<{
-        value: unknown;
-    } | {
-        parseError: unknown;
-    }>;
-}
-/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
-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
- * 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 transport a connector sends every request through. `maxResponseBytes`
- * is required rather than defaulted: what counts as an absurd response is a fact
- * about the API, not about HTTP.
- */
-export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
-export {};

package/dist/credential-rules.d.ts

@@ -1,85 +0,0 @@
-import type { Connector, ConnectorCredentialConfig } from "./types.js";
-/** Which hook a testable credential is checked with. */
-type CredentialTestMode = "single" | "multiple";
-/** Operator-safe explanation shared by every surface that detects shape drift. */
-export declare const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR = "Stored credential fields do not match this connector's current declaration. Replace the credential before using or testing this connector.";
-export type StoredCredentialShape = {
-    state: "missing";
-} | {
-    state: "valid";
-    mode: CredentialTestMode;
-    /**
-     * Stored keys the connector no longer declares, sorted. Harmless — the
-     * credential works — but worth telling an operator about, since nothing
-     * else in `/ui` can show a field the declaration has stopped naming.
-     */
-    undeclared: string[];
-} | {
-    state: "mismatch";
-    mode: CredentialTestMode;
-    message: typeof STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR;
-};
-/**
- * Compare a connector's current declaration with the keys in its stored
- * credential. Values are deliberately ignored: callers may pass decrypted
- * values or `/credentials`' masked field metadata and get the same answer.
- *
- * The test is CONTAINMENT, not equality: the stored key set is compatible when
- * it holds every field currently declared — the reserved `value` key for a
- * single-value declaration, every declared name for a named one. Anything the
- * declaration asks for and the vault does not have is `mismatch`, which is
- * precisely what a renamed field, a newly added field, or a swap between the
- * two shapes produces. The swap needs no special case: `value` is never one of
- * the declared names, so single→named and named→single each leave the declared
- * side unsatisfied. An empty stored map (reachable through a hand-written
- * plaintext) satisfies nothing and is a mismatch too.
- *
- * Extra keys are NOT drift. They are what *dropping* a field leaves behind, and
- * every accessor a connector actually uses — `ctx.credential.get("apiKey")`,
- * `getAll().apiKey` — keeps returning the right secret across that redeploy.
- * Calling it drift would order an operator to re-enter a working secret that
- * many providers will not reissue in readable form. The leftovers come back as
- * `undeclared` instead, for a surface to mention without blocking anything.
- */
-export declare function storedCredentialShape(config: ConnectorCredentialConfig, stored: Readonly<Record<string, unknown>> | null): StoredCredentialShape;
-/**
- * The one sentence describing leftover stored fields, so every surface words it
- * the same way. Names only — the values stay in the vault, and a field name from
- * a previous declaration is not a secret. Deliberately reassuring: nothing is
- * broken, and the only thing an operator gains by acting is that a connector
- * iterating `getAll()` stops seeing a field its code no longer knows about.
- */
-export declare function describeUndeclaredCredentialFields(fields: string[]): string;
-/** A declared credential shape whose only test hook cannot test it. */
-export interface CredentialTestMismatch {
-    /** The shape the connector declared. */
-    shape: CredentialTestMode;
-    /** The hook it implements, which that shape cannot use. */
-    hook: "testCredential" | "testCredentials";
-}
-export interface CredentialTestRule {
-    /** The hook to call, or null when this credential cannot be tested at all. */
-    mode: CredentialTestMode | null;
-    /** Set only when the sole implemented hook is the one the shape cannot use. */
-    mismatch?: CredentialTestMismatch;
-}
-/**
- * The one rule deciding whether a connector's credential can be tested — read
- * by /credentials' `testable` flag, by `POST /ui/credentials/<id>/test` when
- * it picks a hook, and by the construction-time mismatch warning, so those
- * three cannot drift apart.
- *
- * The declared credential *shape* selects the hook: named `credential.fields`
- * are tested as a set by `testCredentials`, a single-value `credential` by
- * `testCredential` on the vault's reserved `value` field. The other hook is
- * never substituted — it would be handed a shape the connector never declared —
- * so a connector implementing only the mismatched hook is not testable, and
- * says so at construction rather than under an operator's click.
- */
-export declare function credentialTestRule(connector: Pick<Connector, "credential" | "testCredential" | "testCredentials">): CredentialTestRule;
-/**
- * One clause naming a mismatch, shared by the startup warning and the test
- * route's 400 so an operator reads the same explanation in both places.
- */
-export declare function describeCredentialTestMismatch(mismatch: CredentialTestMismatch): string;
-export {};