@zackbart/connecta 0.24.4 → 0.25.0

package/dist/operator-ui/view.d.ts

@@ -1,188 +0,0 @@
-import type { CatalogDriftReport } from "../types.js";
-import type { CredentialManagementCapability, UiConnector, UiData } from "./model.js";
-/**
- * Everything the operator app knows, and every rule for changing it, with no
- * DOM in sight. The components render this and nothing else, so the questions
- * that matter — what a page shows while it loads, what an identity change
- * erases, whether a value may become an href — are answered by functions a test
- * can call directly rather than by reading rendered markup back out of a
- * browser.
- */
-export type OperatorPage = "connections" | "activity";
-export declare const OPERATOR_PAGES: readonly OperatorPage[];
-export declare const PAGE_META: Readonly<Record<OperatorPage, {
-    path: string;
-    label: string;
-}>>;
-export declare function pageForPath(path: string): OperatorPage;
-export interface UiActivityActor {
-    kind?: string;
-    id?: string;
-    namespace?: string;
-    label?: string;
-}
-export interface UiActivityEvent {
-    occurredAt: string;
-    actor?: UiActivityActor;
-    connectorId: string;
-    toolName: string;
-    address: string;
-    source: string;
-    outcome: string;
-    durationMs: number;
-    attempts: number;
-    errorCode?: string;
-    friction?: string;
-}
-/** A message with the tone that decides its live region: status or alert. */
-export interface Notice {
-    message: string;
-    tone: "info" | "error";
-}
-export declare function info(message: string): Notice;
-export declare function failure(message: string): Notice;
-/**
- * A remote collection's four states, named once so every page spells them the
- * same way. `idle` is "nobody has asked yet" and is what makes a re-entered
- * page fetch again after an identity change.
- */
-type LoadPhase = "idle" | "loading" | "ready" | "error";
-export interface OperatorState {
-    page: OperatorPage;
-    /**
-     * Bumped by every identity change. Async work captures it before awaiting and
-     * throws its result away if the operator is no longer the one who asked —
-     * the fence that keeps one identity's data off another identity's screen.
-     */
-    generation: number;
-    /** `loading` until the first /ui/data answer decides gated or ready. */
-    session: "loading" | "gated" | "ready";
-    gate: Notice | null;
-    /** True while a signed-in operator's /ui/data is in flight. */
-    refreshing: boolean;
-    /**
-     * Element id the next render should focus. A rebuilt page has no stable node
-     * to hand focus to from an event handler, so the request travels through
-     * state and the shell spends it once the new markup exists.
-     */
-    pendingFocus: string | null;
-    data: UiData | null;
-    connectorFilter: string;
-    oauthNotice: Notice | null;
-    /** Connector id whose OAuth mutation is in flight. */
-    oauthBusy: string | null;
-    credentialNotice: Notice | null;
-    /** Connector id whose credential form is open. */
-    credentialEditing: string | null;
-    /** Connector id whose credential mutation is in flight. */
-    credentialBusy: string | null;
-    activityPhase: LoadPhase;
-    activityNotice: Notice | null;
-    activityEvents: UiActivityEvent[];
-    activityCursor: string | null;
-    activitySearch: string;
-}
-export declare function initialState(page: OperatorPage): OperatorState;
-/**
- * Drop to the gate and forget the previous operator. Bumping the generation is
- * what makes the drop stick: work already in flight for the old identity
- * resolves into a state that no longer accepts it.
- */
-export declare function resetIdentity(state: OperatorState, gate?: Notice | null): OperatorState;
-/**
- * Leaving a page closes what should not survive it: a one-time secret, a half
- * typed credential, and the notices that answered the page just left.
- */
-export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
-export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
-export declare function connectorStatusLabel(status: string): string;
-export declare function toolCountLabel(count: number): string;
-/** The tone a status carries wherever it is rendered as a badge or a tile. */
-export type Tone = "ok" | "warn" | "danger" | "neutral";
-export declare function connectorStatusTone(status: string): Tone;
-/**
- * The deployment in four numbers, so the page answers "is anything wrong"
- * above the list instead of only inside it. `attention` is what an operator
- * can act on now; `unavailable` is what they cannot. A connector still loading
- * its catalog counts only toward `total`, since calling it connected or failed
- * would be a guess either way.
- */
-export interface ConnectorSummary {
-    total: number;
-    connected: number;
-    attention: number;
-    unavailable: number;
-    tools: number;
-    /** Connectors whose last observed catalog refresh differed from the manifest. */
-    drifting: number;
-}
-export declare function summarizeConnectors(connectors: readonly UiConnector[]): ConnectorSummary;
-/**
- * The one line above the list. Connected and tool counts are always present;
- * the two counts an operator may have to act on appear only when they are not
- * zero, so a healthy deployment stays short.
- */
-export declare function connectorSummaryParts(summary: ConnectorSummary): Array<{
-    text: string;
-    tone: Tone;
-}>;
-/** Who owns this connector's downstream credentials, in two words. */
-export declare function authScopeLabel(scope: UiConnector["authScope"]): string;
-/**
- * What this identity may do with a connector, in one line. Being able to use it
- * is implied by seeing it at all, so the sentence covers authentication, which
- * is the part that differs between operators.
- */
-export declare function permissionLabel(connector: UiConnector): string;
-/**
- * Hosted-provider catalog drift, as an operator reads it
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
- *
- * - `unavailable` — no refresh has been observed in this runtime, so there is
- *   nothing to report. Deliberately not `clean`: "we have not looked" and "we
- *   looked and it matches" are different answers, and only one of them is a
- *   reason to stop worrying.
- * - `clean` — a refresh happened and every category counted zero.
- * - `warning` — a refresh happened and at least one category did not.
- */
-export type DriftState = "clean" | "warning" | "unavailable";
-export declare function driftTotal(drift?: CatalogDriftReport): number;
-export declare function driftState(drift?: CatalogDriftReport): DriftState;
-/** Every category with its count, so a clean report still shows its zeros. */
-export declare function driftCounts(drift?: CatalogDriftReport): Array<{
-    key: string;
-    label: string;
-    count: number;
-}>;
-/** One line naming the state and when it was observed. Never what drifted. */
-export declare function driftSummary(drift?: CatalogDriftReport): string;
-/**
- * Only http/https may become a clickable href — the browser half of the gate
- * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
- * downstream that gets a `javascript:` URL past one of them still meets the
- * other, and the caller renders inert text instead of a link.
- */
-export declare function safeHttpHref(url: string | undefined): string | null;
-/** Locale timestamp, or "" for anything that is not a readable date. */
-export declare function formatDate(value?: string): string;
-export declare function actorLabel(actor?: UiActivityActor): string;
-/**
- * The stable id behind a friendly label, shown only when a label or namespace
- * could otherwise make two different people look like one.
- */
-export declare function actorStableId(actor?: UiActivityActor): string | null;
-export declare function filterActivity(events: UiActivityEvent[], query: string): UiActivityEvent[];
-/** Counts only. What the deployment ran, never what it sent or received. */
-export declare function activitySummary(events: UiActivityEvent[]): string;
-export declare function activityOutcomeClass(outcome: string): string;
-/** The one-line detail under an address: source, retries, and friction. */
-export declare function activityDetail(event: UiActivityEvent): string;
-export declare function credentialStateLabel(credential: {
-    configured: boolean;
-    fields?: unknown[];
-    lastFour?: string;
-    updatedAt?: string;
-}): string;
-/** Gate copy for each browser-auth shape, so the sign-in state is never a blank page. */
-export declare function gateCopy(kind: string, signedIn: boolean): string;
-export {};

package/dist/result-shapes.d.ts

@@ -1,13 +0,0 @@
-import type { JsonSchema, ToolDef } from "./types.js";
-/**
- * Passive, process-local output-shape learning. Provider declarations always
- * win; observations are an open, optional-field routing aid and never a
- * replacement contract.
- */
-export declare class ObservedOutputSchemas {
-    private readonly entries;
-    private cacheKey;
-    private set;
-    get(connectorId: string, definition: ToolDef): JsonSchema | undefined;
-    observe(connectorId: string, definition: ToolDef, value: unknown): void;
-}

package/dist/retired-toolkits.d.ts

@@ -1,2 +0,0 @@
-/** Fail loudly when JavaScript callers pass the retired audience-scoping keys. */
-export declare function assertNoRetiredToolkitOptions(source: string, options: object): void;

package/dist/routes/activity.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeActivity(context: RouteContext): Promise<Response | null>;

package/dist/routes/credentials.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeCredentials(context: RouteContext): Promise<Response | null>;

package/dist/routes/mcp.d.ts

@@ -1,10 +0,0 @@
-import { type RouteContext, type ServerOptions } from "./shared.js";
-export declare const MCP_CORS_HEADERS: {
-    "Access-Control-Allow-Origin": string;
-    "Access-Control-Allow-Methods": string;
-    "Access-Control-Allow-Headers": string;
-};
-export declare function createMcpRoute(opts: ServerOptions): {
-    handle(context: RouteContext): Promise<Response | null>;
-    rejectOrigin(request: Request): Response | null;
-};

package/dist/routes/oauth-management.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeOAuthManagement(context: RouteContext): Promise<Response | null>;

package/dist/routes/oauth.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeOAuthCallback(context: RouteContext): Promise<Response | null>;

package/dist/routes/ui.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeUi(context: RouteContext): Promise<Response | null>;

package/dist/server.d.ts

@@ -1,9 +0,0 @@
-import { type RuntimeExecutionContext, type ServerOptions } from "./routes/shared.js";
-export type { ServerOptions } from "./routes/shared.js";
-/**
- * Build the Web-standard fetch handler.
- *
- * Route ordering is the contract: private mutation routes precede wildcard
- * OPTIONS, and the security wrapper is applied to every response, including 404s.
- */
-export declare function createFetchHandler(opts: ServerOptions): (request: Request, runtimeContext?: RuntimeExecutionContext) => Promise<Response>;

package/dist/skills.d.ts

@@ -1,44 +0,0 @@
-import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: \"usage\" }) only when these instructions and the tool description are insufficient or a run needs repair.";
-/** Shared Connecta routing guidance, byte-identical across deployments. */
-export declare const USAGE_SKILL: string;
-/** The always-loaded MCP `instructions` string. */
-export declare function instructionsFor(): string;
-/** True when at least one of `connectors` carries a usage guide. */
-export declare function hasConnectorGuides(connectors: readonly Connector[]): boolean;
-/** The skill name that fetches `connector`'s guide. */
-export declare function connectorSkillName(connectorId: string): string;
-/** The connector's guide, or undefined when it declares none (or a blank one). */
-export declare function connectorGuide(connector: Connector): string | undefined;
-/** Discovery budget for one connector-guide summary, including an ellipsis. */
-export declare const GUIDE_SUMMARY_LENGTH = 120;
-/** Normalize authored and derived summaries under one construction contract. */
-export declare function normalizeGuideSummary(summary: string): string | undefined;
-/** Bounded, decision-useful discovery summary for a connector guide. */
-export declare function connectorGuideSummary(connector: Connector): string | undefined;
-/** Whether correct use always depends on conventions outside the tool schema. */
-export declare function connectorGuideRequired(connector: Connector): boolean;
-export interface SkillListing {
-    name: string;
-    description: string;
-}
-/**
- * Every fetchable skill: the built-in guides plus one entry per connector that
- * carries a usage guide. Derived from the connector list passed in — the single
- * place guide visibility is decided.
- */
-export declare function listSkills(connectors: readonly Connector[]): SkillListing[];
-export type SkillLookup = {
-    found: true;
-    content: string;
-} | {
-    found: false;
-    message: string;
-};
-/**
- * Resolve one skill name. Built-in names match exactly; connector guides are
- * reachable only through the `connector:` prefix. Every miss — unknown name,
- * unknown connector, connector without a guide — is an explicit error, never a
- * silent fallback to the generic guide.
- */
-export declare function resolveSkill(name: string, connectors: readonly Connector[]): SkillLookup;

package/dist/timeout.d.ts

@@ -1,21 +0,0 @@
-/**
- * Generous default bound for a single downstream probe/catalog call. High enough
- * to trip only on a pathological hang, not a realistically slow probe.
- */
-export declare const DEFAULT_PROBE_TIMEOUT_MS = 30000;
-/** A finite, positive integer number of milliseconds, or undefined. */
-export declare function normalizeTimeoutMs(value: number | undefined): number | undefined;
-/** Resolve after `ms`, or false when the caller aborts first. */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<boolean>;
-export interface DeadlineOptions {
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    timeoutError: Error;
-}
-export declare function withDeadline<T>(operation: (signal: AbortSignal) => Promise<T>, options: DeadlineOptions): Promise<T>;
-/**
- * Give one operation a caller-facing deadline and the matching cancellation
- * signal. The timeout rejects with the stable, labelled error while aborting
- * any in-flight work that honors the signal.
- */
-export declare function withAbortableTimeout<T>(operation: (signal: AbortSignal) => Promise<T>, ms: number, label: string): Promise<T>;

package/dist/tool-safety.d.ts

@@ -1,9 +0,0 @@
-import type { ToolDef } from "./types.js";
-/**
- * The one fail-closed classification shared by discovery and invocation.
- *
- * A tool is read-only only when it says so without also saying it is
- * destructive. Missing, false, and contradictory annotations all require the
- * approval-visible call path.
- */
-export declare function isExplicitlyReadOnly(definition: ToolDef): boolean;