@obrier/plugboard 0.0.0-stage → 0.2.0

package/dist/lib/index.d.ts

@@ -0,0 +1,164 @@
+// Generated by dts-bundle-generator v9.5.1
+
+declare const TRANSPORTS: readonly [
+	"auto",
+	"direct",
+	"claude-code"
+];
+export type Transport = (typeof TRANSPORTS)[number];
+export type Via = Exclude<Transport, "auto">;
+export declare const EXIT: {
+	readonly OK: 0;
+	readonly UPSTREAM_ERROR: 1;
+	readonly TIMEOUT: 1;
+	readonly UNKNOWN: 1;
+	readonly VALIDATION_ERROR: 2;
+	readonly NOT_FOUND: 2;
+	readonly POLICY_DENIED: 3;
+	readonly AUTH_REQUIRED: 4;
+	readonly RATE_LIMITED: 5;
+	readonly WRITE_OUTCOME_UNKNOWN: 6;
+	readonly PARTIAL: 7;
+	readonly UNREACHABLE: 10;
+	readonly COST_GUARD: 10;
+};
+export type Code = keyof typeof EXIT;
+/** Every error Plugboard raises: a code (the CLI's exit codes name them), a message, and hints on what to do. */
+export declare class PlugboardError extends Error {
+	readonly code: Code;
+	readonly hints: string[];
+	name: string;
+	constructor(message: string, code: Code, hints?: string[]);
+	get exitCode(): number;
+}
+export type Plan = {
+	connector: string;
+	tool: string;
+	class: string;
+	destructive: boolean;
+	profile: string;
+	decision: string;
+	hash: string;
+	/** What the hash names: the args as sent, but for a parameter the write key fills (`keyFills`). */
+	payload: Record<string, unknown>;
+	/** A parameter the write key fills when the write is sent, whichever key that is: outside the payload and the hash. */
+	keyFills?: "idempotency_key";
+};
+/** A call: the shape of a batch line, `{ connector, tool, args }`, with the call's options beside it. */
+export type Call = {
+	/** A connector ID or a policy alias. */
+	connector: string;
+	/** The tool's name, the CLI's short name, or its kebab form. */
+	tool: string;
+	args?: Record<string, unknown>;
+	/** The policy profile that judges the call; the instance's by default. */
+	profile?: string;
+	/** The CLI's --deadline: 30 s by default. */
+	timeoutMs?: number;
+	/** Cancels the call: a read is dropped; a write cancelled after it was sent has an unknown outcome, as on a timeout. */
+	signal?: AbortSignal;
+	/** How the call reaches its connector; the narrowest setting wins: the call's, the instance's, PLUGBOARD_TRANSPORT, the policy's. */
+	transport?: Transport;
+};
+/** A read's result: the value as the CLI prints it, the MCP result as the connector sent it, and the path that served it. */
+export type Read = {
+	value: unknown;
+	raw: Record<string, unknown>;
+	via: Via;
+};
+/** What a write would send and whether the profile allows it, with the request it was planned from: plain JSON. */
+export type WritePlan = Plan & {
+	request: {
+		connector: string;
+		tool: string;
+		args: Record<string, unknown>;
+		profile: string;
+	};
+};
+export type WriteOptions = {
+	key: string;
+	/** The write profile it is sent under; the instance's by default. The plan's own profile is never trusted, as the
+	 * CLI's --as is the sender's: no hash covers it. */
+	profile?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	transport?: Transport;
+};
+/** Sent now, or already sent under this key before (nothing was called). */
+export type Written = {
+	sent: true;
+	key: string;
+	ref: string | null;
+	value: unknown;
+	raw: Record<string, unknown>;
+	via: Via;
+} | {
+	replayed: true;
+	key: string;
+	ref: string | null;
+	at?: string;
+};
+/** A batch line: a call, with an id to tell its result by (its input position by default). */
+export type BatchCall = Call & {
+	id?: unknown;
+};
+export type BatchOptions = {
+	/** Lines running at once: the policy's limits.concurrency (4) by default. */
+	concurrency?: number;
+	/** Lines running at once on one connector: the policy's limits.per_connector (2) by default. */
+	perConnector?: number;
+	/** Results in input order; completion order by default. */
+	ordered?: boolean;
+	/** Once spent, the lines not yet started fail with TIMEOUT, unsent. None by default. */
+	budgetMs?: number;
+};
+/** A line's result: a failure is a result too, never an exception. */
+export type BatchRead = {
+	id: unknown;
+	ok: true;
+	value: unknown;
+	raw: Record<string, unknown>;
+	via: Via;
+} | {
+	id: unknown;
+	ok: false;
+	error: PlugboardError;
+};
+export type PlugboardOptions = {
+	/** A policy file; PLUGBOARD_POLICY's, or the default location, otherwise. Read once, on first use. */
+	policy?: string;
+	/** The profile calls use unless they name one; PLUGBOARD_PROFILE, or "default", otherwise. */
+	profile?: string;
+	transport?: Transport;
+};
+export type Plugboard = {
+	/** One read. A write tool is refused: plan it and send it with write(). */
+	call(request: Call): Promise<Read>;
+	/** A write (or a read) as it would be sent, with the hash its approval names. */
+	plan(request: Omit<Call, "signal" | "timeoutMs" | "transport">): WritePlan;
+	/** Sends an approved plan once under this key. Nothing in the plan is trusted: its request is planned again and
+	 * sent only if the hash still matches. */
+	write(plan: WritePlan, options: WriteOptions): Promise<Written>;
+	/** Reads, as they arrive, results as they come: UNREACHABLE or COST_GUARD fails the lines still to come and ends
+	 * it; leaving the loop cancels the lines still running. A write tool is refused for its line. */
+	batch(lines: Iterable<BatchCall> | AsyncIterable<BatchCall>, options?: BatchOptions): AsyncGenerator<BatchRead, void, undefined>;
+	/** Closes the instance's sessions now, rather than when idle. */
+	close(): Promise<void>;
+};
+export declare function createPlugboard(options?: PlugboardOptions): Plugboard;
+/** One read, through the default instance (PLUGBOARD_POLICY, PLUGBOARD_PROFILE, PLUGBOARD_TRANSPORT). */
+export declare const call: Plugboard["call"];
+/** Plans a call through the default instance. */
+export declare const plan: Plugboard["plan"];
+/** Sends an approved plan through the default instance. */
+export declare const write: Plugboard["write"];
+/** A batch of reads through the default instance. */
+export declare const batch: Plugboard["batch"];
+/** Closes the default instance's sessions now, rather than when idle. */
+declare const close$1: () => Promise<void>;
+
+export {
+	close$1 as close,
+};
+
+export {};