@usesotto/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { FetchLike, SottoClient, CatalogResource } from '@sotto/purchase-client';
+
+type CliConfig = Readonly<{
+    apiOrigin?: string;
+    token?: string;
+    walletUrl?: string;
+}>;
+type Env = Readonly<Record<string, string | undefined>>;
+declare function configPath(env: Env): string;
+/** Malformed config fails closed: the CLI treats it as absent and says so. */
+declare function readConfig(env: Env): CliConfig;
+/**
+ * Persists the config with owner-only permissions: 0700 directory, 0600
+ * file — the session token never becomes group- or world-readable, and an
+ * existing looser mode is tightened on every write.
+ */
+declare function writeConfig(env: Env, config: CliConfig): string;
+declare function deleteConfig(env: Env): void;
+type ResolvedSettings = Readonly<{
+    apiOrigin: string | undefined;
+    token: string | undefined;
+    walletUrl: string | undefined;
+    tokenSource: "env" | "config" | "absent";
+}>;
+/** Environment overrides config; explicit flags override both. */
+declare function resolveSettings(env: Env, flags?: Readonly<{
+    apiOrigin?: string;
+}>): ResolvedSettings;
+declare function isValidToken(candidate: string): boolean;
+
+/**
+ * One exit code per distinct terminal fact, so scripts can branch on the
+ * paired settlement/delivery outcome without parsing copy. Ambiguous
+ * outcomes (8) must never be auto-retried — the CLI prints reconcile
+ * guidance instead of spending twice.
+ */
+declare const EXIT: Readonly<{
+    /** Read succeeded, or the purchase settled AND delivered. */
+    readonly ok: 0;
+    /** Transport failure, API failure, or an unexpected error. */
+    readonly failure: 1;
+    /** The command line itself was invalid. */
+    readonly usage: 2;
+    /** No usable owner session (token absent, expired, or revoked). */
+    readonly auth: 3;
+    /** The human wallet rejected this exact prepared call. */
+    readonly walletRejected: 4;
+    /** The wallet cannot sign this prepared transaction shape. */
+    readonly walletUnsupported: 5;
+    /** Canton rejected the settlement; no value moved. */
+    readonly settlementRejected: 6;
+    /** The execute-before deadline passed without a terminal journal event. */
+    readonly expired: 7;
+    /** Settled but not delivered, or otherwise ambiguous — reconcile, never retry. */
+    readonly ambiguous: 8;
+}>;
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+/**
+ * Terminal output helpers bound to DESIGN.md §6: truncation keeps hint +
+ * tail for party IDs and first-8 + last-4 for update IDs, amounts always
+ * carry the asset, and `--json` returns the full untruncated values.
+ * NO_COLOR or a non-TTY stream turns every escape sequence off.
+ */
+type Io = Readonly<{
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    env: Readonly<Record<string, string | undefined>>;
+    isTTY: boolean;
+}>;
+
+/**
+ * Minimal MCP stdio server: newline-delimited JSON-RPC 2.0. Implemented by
+ * hand so the published CLI carries zero runtime dependencies; stdout
+ * carries JSON-RPC frames only, and every log goes to stderr.
+ */
+declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+type JsonRpcId = string | number | null;
+type JsonRpcMessage = Readonly<{
+    jsonrpc: "2.0";
+    id?: JsonRpcId;
+    method?: string;
+    params?: Readonly<Record<string, unknown>>;
+    result?: unknown;
+    error?: unknown;
+}>;
+type MethodHandler = (params: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+type McpServerDefinition = Readonly<{
+    serverInfo: Readonly<{
+        name: string;
+        version: string;
+    }>;
+    methods: Readonly<Record<string, MethodHandler>>;
+}>;
+declare class JsonRpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+declare function parseMessage(line: string): JsonRpcMessage | undefined;
+/**
+ * Handles one incoming message. Returns the serialized response frame, or
+ * undefined for notifications (which never get a response).
+ */
+declare function handleMessage(definition: McpServerDefinition, message: JsonRpcMessage): Promise<string | undefined>;
+type StreamLike = Readonly<{
+    input: AsyncIterable<string | Uint8Array>;
+    write: (frame: string) => void;
+    logError: (line: string) => void;
+}>;
+/** Reads newline-delimited frames until the input ends. */
+declare function serveJsonRpc(definition: McpServerDefinition, streams: StreamLike): Promise<void>;
+
+type RunOptions = Readonly<{
+    io: Io;
+    env: Env;
+    fetchImpl?: FetchLike;
+    mcpStreams?: StreamLike;
+}>;
+/** Parses argv, dispatches one command, and maps every error to an exit code. */
+declare function run(argv: readonly string[], options: RunOptions): Promise<ExitCode>;
+
+/** Kept in lockstep with package.json; scripts/verify-package.mjs asserts it. */
+declare const CLI_VERSION = "0.1.0";
+
+declare class CliUsageError extends Error {
+}
+declare class CliAuthError extends Error {
+}
+type ClientContext = Readonly<{
+    client: SottoClient;
+    settings: ResolvedSettings;
+}>;
+/**
+ * Builds the shared purchasing-core client from resolved settings. Every
+ * CLI command and MCP tool goes through this one construction — there is
+ * no second HTTP path and no signing capability anywhere behind it.
+ */
+declare function buildClient(env: Env, flags?: Readonly<{
+    apiOrigin?: string;
+}>, fetchImpl?: FetchLike): ClientContext;
+type SearchFilters = Readonly<{
+    query?: string;
+    method?: string;
+    maxPriceAtomic?: bigint;
+}>;
+/** Case-insensitive text match over the verified catalog's own fields. */
+declare function filterResources(resources: readonly CatalogResource[], filters: SearchFilters): readonly CatalogResource[];
+/**
+ * Resolves a listing ID or a canonical resource URL to its verified
+ * catalog listing — the `sotto try <resource-url>` path. A URL matches
+ * when origin and route equal a published resource exactly.
+ */
+declare function resolveResource(client: SottoClient, reference: string, signal?: AbortSignal): Promise<CatalogResource>;
+declare function parseMaxPrice(raw: string | undefined): bigint | undefined;
+
+type ToolDefinition = Readonly<{
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    annotations: Readonly<Record<string, unknown>>;
+}>;
+type ToolResult = Readonly<{
+    content: readonly Readonly<{
+        type: "text";
+        text: string;
+    }>[];
+    isError?: boolean;
+}>;
+declare const TOOL_DEFINITIONS: readonly ToolDefinition[];
+/** Executes one tool call against the shared purchasing core. */
+declare function callTool(client: SottoClient, name: string, args: Readonly<Record<string, unknown>>): Promise<ToolResult>;
+
+/**
+ * `sotto mcp serve` — the buyer MCP server over stdio. Auth is the same
+ * stored session token (or SOTTO_SESSION_TOKEN) the CLI uses; there is no
+ * key material anywhere in this process and no generic signing tool in
+ * the tool list. Stdout stays pure JSON-RPC; diagnostics go to stderr.
+ */
+declare function buildMcpDefinition(env: Env, fetchImpl?: FetchLike): McpServerDefinition;
+declare function serveMcp(env: Env, streams: StreamLike): Promise<void>;
+
+export { CLI_VERSION, CliAuthError, type CliConfig, CliUsageError, type ClientContext, EXIT, type Env, type ExitCode, JsonRpcError, type JsonRpcMessage, MCP_PROTOCOL_VERSION, type McpServerDefinition, type ResolvedSettings, type RunOptions, type SearchFilters, type StreamLike, TOOL_DEFINITIONS, type ToolDefinition, type ToolResult, buildClient, buildMcpDefinition, callTool, configPath, deleteConfig, filterResources, handleMessage, isValidToken, parseMaxPrice, parseMessage, readConfig, resolveResource, resolveSettings, run, serveJsonRpc, serveMcp, writeConfig };