@managoat/fountain-sdk 1.25.0

package/dist/generated/openapi.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=openapi.js.map

package/dist/generated/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../src/generated/openapi.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/http.d.ts

@@ -0,0 +1,37 @@
+import type { ResolvedConfig } from "./config.ts";
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Per-request timeout. Defaults to the client's. `0` disables it. */
+    timeoutMs?: number;
+    accept?: string;
+}
+/**
+ * The product token this client sends. Deliberately not the package name: a
+ * scope reads as a second token in a User-Agent (`@managoat/…/0.1.1`), and
+ * this string is already what Fountain's request logs are keyed on. The
+ * version half is asserted against `package.json` by a test.
+ */
+export declare const USER_AGENT = "fountain-sdk-js/1.25.0";
+export declare class HttpClient {
+    readonly config: ResolvedConfig;
+    private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
+    constructor(config: ResolvedConfig, opts?: {
+        fetch?: FetchLike;
+        timeoutMs?: number;
+    });
+    get baseUrl(): string;
+    url(path: string, query?: RequestOptions["query"]): string;
+    headers(extra?: Record<string, string>): Record<string, string>;
+    /** Send a request and return the parsed body. Non-2xx throws. */
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /** Send a request and return the `Response` — for SSE and image bytes. */
+    raw(method: string, path: string, opts?: RequestOptions): Promise<Response>;
+    /** `{data: T}` is the envelope every collection and show action uses. */
+    data<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    list<T>(path: string, opts?: RequestOptions): Promise<T[]>;
+}

package/dist/http.js

@@ -0,0 +1,129 @@
+import { AuthError, ConnectionError, FountainError, errorForStatus } from "./errors.js";
+/**
+ * The product token this client sends. Deliberately not the package name: a
+ * scope reads as a second token in a User-Agent (`@managoat/…/0.1.1`), and
+ * this string is already what Fountain's request logs are keyed on. The
+ * version half is asserted against `package.json` by a test.
+ */
+export const USER_AGENT = "fountain-sdk-js/1.25.0";
+/**
+ * The thin layer everything else is built on: one bearer token, JSON in and
+ * out, and errors that say which call failed. `Fountain#api` exposes it
+ * directly so a caller is never blocked by a verb this SDK did not wrap.
+ */
+/** A page in a browser: `document` exists. Workers have none, and no page origin to preflight for. */
+function isBrowser() {
+    return typeof globalThis.document !== "undefined";
+}
+export class HttpClient {
+    config;
+    fetchImpl;
+    defaultTimeoutMs;
+    constructor(config, opts = {}) {
+        this.config = config;
+        this.fetchImpl = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.defaultTimeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    get baseUrl() {
+        return this.config.baseUrl;
+    }
+    url(path, query) {
+        const url = new URL(path.startsWith("http") ? path : this.config.baseUrl + path);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+    headers(extra) {
+        if (!this.config.apiKey) {
+            throw new AuthError("No Fountain API key. Pass `apiKey`, set FOUNTAIN_API_KEY, or run `fountain auth login`.");
+        }
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            Accept: "application/json",
+            ...extra,
+        };
+        // A browser already has a user agent, and setting one is worse than
+        // useless there: Chrome drops it as a forbidden header, Firefox sends it —
+        // which makes every call a CORS preflight asking for `user-agent`, and a
+        // server whose allow-list does not name it refuses the request outright
+        // ("CORS Missing Allow Header"). Only a non-browser runtime gets the token.
+        if (!isBrowser())
+            headers["User-Agent"] = USER_AGENT;
+        // Attribute conversations started from inside a sandbox to their parent.
+        if (this.config.parentConversationId) {
+            headers["X-Fountain-Parent-Conversation-Id"] = this.config.parentConversationId;
+        }
+        return headers;
+    }
+    /** Send a request and return the parsed body. Non-2xx throws. */
+    async request(method, path, opts = {}) {
+        const response = await this.raw(method, path, opts);
+        const text = await response.text();
+        const parsed = text ? safeJson(text) : null;
+        if (!response.ok) {
+            throw errorForStatus(response.status, parsed, method, this.url(path, opts.query), response.headers);
+        }
+        return parsed;
+    }
+    /** Send a request and return the `Response` — for SSE and image bytes. */
+    async raw(method, path, opts = {}) {
+        const url = this.url(path, opts.query);
+        const headers = this.headers(opts.headers);
+        if (opts.accept)
+            headers.Accept = opts.accept;
+        let body;
+        if (opts.body !== undefined) {
+            body = JSON.stringify(opts.body);
+            headers["Content-Type"] = "application/json";
+        }
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        const signal = withTimeout(opts.signal, timeoutMs);
+        try {
+            return await this.fetchImpl(url, { method, headers, body, signal });
+        }
+        catch (cause) {
+            if (opts.signal?.aborted) {
+                throw new FountainError(`${method} ${url} was aborted`, { cause });
+            }
+            throw new ConnectionError(`${method} ${url} failed: ${describe(cause)}. ` +
+                "If this is a browser, check the base URL and that API_CORS_ORIGINS on the " +
+                "Fountain server includes this origin.", { cause });
+        }
+    }
+    /** `{data: T}` is the envelope every collection and show action uses. */
+    async data(method, path, opts = {}) {
+        const out = await this.request(method, path, opts);
+        return (out?.data ?? null);
+    }
+    async list(path, opts = {}) {
+        return (await this.data("GET", path, opts)) ?? [];
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function describe(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    return String(cause);
+}
+/**
+ * Compose the caller's signal with a deadline. `AbortSignal.any` keeps the
+ * caller's abort reason intact, which is what makes `run({ signal })` report
+ * "aborted" rather than "timed out".
+ */
+function withTimeout(signal, timeoutMs) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return signal;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { Fountain, type FountainOptions, type RunConfig } from "./client.ts";
+export { Run, type RunOptions } from "./run.ts";
+export { Conversation, type SendOptions } from "./conversation.ts";
+export { HttpClient, type FetchLike, type RequestOptions } from "./http.ts";
+export { Agents, ConnectionProviders, Connections, Environments, Vaults } from "./resources.ts";
+export { Team, TeamSchedules, type MessageOptions } from "./team.ts";
+export { resolveConfig, conversationUrl, DEFAULT_BASE_URL, DEFAULT_APP_URL, type ConfigOptions, type ResolvedConfig, } from "./config.ts";
+export { streamEvents, streamPath, parseSse, type StreamOptions, type SseMessage } from "./sse.ts";
+export { TurnFollower } from "./turn.ts";
+export { FountainError, AuthError, SubscriptionRequiredError, NotFoundError, ValidationError, RateLimitError, ConversationBusyError, NotReadyError, QuotaExceededError, ConnectionError, TimeoutError, ResolutionError, type FountainErrorCode, } from "./errors.ts";
+export type * from "./schemas.ts";
+export type { Agent, AgentInput, Block, ConversationRecord, ConversationStatus, Environment, EnvironmentInput, LogEvent, NamedResource, PermissionOption, PermissionRequest, Stream, TeamEvent, Repository, Runtime, RunEvent, RunResult, SandboxDiff, SandboxEntry, SandboxFile, SandboxListing, SandboxProvider, SandboxRecord, Secret, SkillInput, Turn, TurnState, Vault, VaultInput, VaultSecretMetadataPatch, } from "./types.ts";
+import { Fountain } from "./client.ts";
+export default Fountain;

package/dist/index.js

@@ -0,0 +1,13 @@
+export { Fountain } from "./client.js";
+export { Run } from "./run.js";
+export { Conversation } from "./conversation.js";
+export { HttpClient } from "./http.js";
+export { Agents, ConnectionProviders, Connections, Environments, Vaults } from "./resources.js";
+export { Team, TeamSchedules } from "./team.js";
+export { resolveConfig, conversationUrl, DEFAULT_BASE_URL, DEFAULT_APP_URL, } from "./config.js";
+export { streamEvents, streamPath, parseSse } from "./sse.js";
+export { TurnFollower } from "./turn.js";
+export { FountainError, AuthError, SubscriptionRequiredError, NotFoundError, ValidationError, RateLimitError, ConversationBusyError, NotReadyError, QuotaExceededError, ConnectionError, TimeoutError, ResolutionError, } from "./errors.js";
+import { Fountain } from "./client.js";
+export default Fountain;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAwC,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,GAAG,EAAmB,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,YAAY,EAAoB,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAuC,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,IAAI,EAAE,aAAa,EAAuB,MAAM,WAAW,CAAC;AACrE,OAAO,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,eAAe,GAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAuC,MAAM,UAAU,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,aAAa,EACb,SAAS,EACT,yBAAyB,EACzB,aAAa,EACb,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,eAAe,GAEhB,MAAM,aAAa,CAAC;AAmCrB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,eAAe,QAAQ,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+export * from "./index.ts";
+export { default } from "./index.ts";

package/dist/node.js

@@ -0,0 +1,21 @@
+/**
+ * The Node entry point.
+ *
+ * Everything the SDK does works in a browser, and `src/index.ts` is what a
+ * bundler gets. The one thing that cannot work there is reading
+ * `~/.fountain/credentials`, so that lives here: importing `@managoat/fountain-sdk`
+ * under Node resolves to this module, which installs the reader and then
+ * re-exports the same API.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { parseCredentials, setCredentialsReader } from "./config.js";
+setCredentialsReader((profile) => {
+    const override = (process.env.FOUNTAIN_CREDENTIALS_FILE ?? "").trim();
+    const path = override || join(homedir(), ".fountain", "credentials");
+    return parseCredentials(readFileSync(path, "utf8"), profile);
+});
+export * from "./index.js";
+export { default } from "./index.js";
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAErE,oBAAoB,CAAC,CAAC,OAAO,EAAE,EAAE;IAC/B,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,IAAI,GAAG,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IACrE,OAAO,gBAAgB,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC,CAAC,CAAC;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A push source that many consumers can read as an async iterable.
+ *
+ * Everything a run produces goes through one of these. Late subscribers get
+ * the whole history first, which is what lets `await run` and
+ * `for await (run)` be the same run: the promise path is just another
+ * consumer, and it does not race the streaming one for events.
+ */
+export declare class Broadcast<T> {
+    private readonly buffer;
+    private readonly waiters;
+    private closed;
+    private failure;
+    push(value: T): void;
+    close(error?: unknown): void;
+    private wake;
+    private wait;
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+}
+/** A promise whose settlement is triggered from elsewhere. */
+export declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: unknown) => void;
+};

package/dist/queue.js

@@ -0,0 +1,64 @@
+/**
+ * A push source that many consumers can read as an async iterable.
+ *
+ * Everything a run produces goes through one of these. Late subscribers get
+ * the whole history first, which is what lets `await run` and
+ * `for await (run)` be the same run: the promise path is just another
+ * consumer, and it does not race the streaming one for events.
+ */
+export class Broadcast {
+    buffer = [];
+    waiters = new Set();
+    closed = false;
+    failure = null;
+    push(value) {
+        if (this.closed)
+            return;
+        this.buffer.push(value);
+        this.wake();
+    }
+    close(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (error !== undefined)
+            this.failure = error;
+        this.wake();
+    }
+    wake() {
+        for (const waiter of [...this.waiters])
+            waiter();
+        this.waiters.clear();
+    }
+    wait() {
+        return new Promise((resolve) => this.waiters.add(resolve));
+    }
+    async *[Symbol.asyncIterator]() {
+        let index = 0;
+        while (true) {
+            while (index < this.buffer.length) {
+                yield this.buffer[index++];
+            }
+            if (this.closed) {
+                if (this.failure !== null)
+                    throw this.failure;
+                return;
+            }
+            await this.wait();
+        }
+    }
+}
+/** A promise whose settlement is triggered from elsewhere. */
+export function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // Nobody may have attached a handler yet; the Run surfaces this failure on
+    // whichever path the caller actually awaits.
+    promise.catch(() => { });
+    return { promise, resolve, reject };
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,SAAS;IACH,MAAM,GAAQ,EAAE,CAAC;IACjB,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IACzC,MAAM,GAAG,KAAK,CAAC;IACf,OAAO,GAAY,IAAI,CAAC;IAEhC,IAAI,CAAC,KAAQ;QACX,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAe;QACnB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAEO,IAAI;QACV,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,IAAI;QACV,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,EAAE,CAAC;YACZ,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAM,CAAC;YAClC,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;oBAAE,MAAM,IAAI,CAAC,OAAO,CAAC;gBAC9C,OAAO;YACT,CAAC;YACD,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IAKtB,IAAI,OAA4B,CAAC;IACjC,IAAI,MAAiC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC1C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,2EAA2E;IAC3E,6CAA6C;IAC7C,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACxB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,29 @@
+import type { HttpClient } from "./http.ts";
+export interface Named {
+    id: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Turns `{ agent: "reposage" }` into an id.
+ *
+ * Names, not ids, are the point: a script that reads `vault: "github-bot"` says
+ * what it does, and a UUID in a README kills the demo. Resolution is exact
+ * (case-insensitive) first, then a unique prefix, and a miss lists what the
+ * account actually has — the error a caller can act on without opening the
+ * console.
+ */
+export declare class Resolver {
+    private readonly cache;
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Drop every memoized listing. */
+    clear(): void;
+    /** Drop one memoized listing — after a create, rename or delete. */
+    forget(path: string): void;
+    list(path: string): Promise<Named[]>;
+    resolve(path: string, what: string, nameOrId: string): Promise<Named>;
+    resolveId(path: string, what: string, nameOrId?: string | null): Promise<string | undefined>;
+    /** The cached listing if we already have one; never fetches. */
+    private peek;
+}

package/dist/resolve.js

@@ -0,0 +1,89 @@
+import { ResolutionError } from "./errors.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Turns `{ agent: "reposage" }` into an id.
+ *
+ * Names, not ids, are the point: a script that reads `vault: "github-bot"` says
+ * what it does, and a UUID in a README kills the demo. Resolution is exact
+ * (case-insensitive) first, then a unique prefix, and a miss lists what the
+ * account actually has — the error a caller can act on without opening the
+ * console.
+ */
+export class Resolver {
+    cache = new Map();
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Drop every memoized listing. */
+    clear() {
+        this.cache.clear();
+    }
+    /** Drop one memoized listing — after a create, rename or delete. */
+    forget(path) {
+        this.cache.delete(path);
+    }
+    list(path) {
+        let pending = this.cache.get(path);
+        if (!pending) {
+            pending = this.http.list(path).catch((error) => {
+                // A failed listing must not be remembered as an empty account.
+                this.cache.delete(path);
+                throw error;
+            });
+            this.cache.set(path, pending);
+        }
+        return pending;
+    }
+    async resolve(path, what, nameOrId) {
+        const wanted = (nameOrId ?? "").trim();
+        if (!wanted)
+            throw new ResolutionError(`${what} is required (a name or id)`);
+        // An id needs no listing — and an account with hundreds of agents should
+        // not pay for one on every call.
+        if (UUID.test(wanted)) {
+            const known = (await this.peek(path))?.find((item) => item.id === wanted);
+            return known ?? { id: wanted };
+        }
+        const items = await this.list(path);
+        const byId = items.find((item) => item.id === wanted);
+        if (byId)
+            return byId;
+        const lower = wanted.toLowerCase();
+        const exact = items.filter((item) => (item.name ?? "").toLowerCase() === lower);
+        if (exact.length === 1)
+            return exact[0];
+        if (exact.length > 1) {
+            throw new ResolutionError(`More than one ${what} is named ${JSON.stringify(wanted)}. Use the id: ` +
+                exact.map((item) => item.id).join(", "));
+        }
+        const prefix = items.filter((item) => (item.name ?? "").toLowerCase().startsWith(lower));
+        if (prefix.length === 1)
+            return prefix[0];
+        if (prefix.length > 1) {
+            throw new ResolutionError(`${JSON.stringify(wanted)} matches more than one ${what}: ` +
+                prefix.map((item) => item.name ?? item.id).join(", "));
+        }
+        throw new ResolutionError(`No ${what} named ${JSON.stringify(wanted)}. On this account: ${describe(items)}`);
+    }
+    async resolveId(path, what, nameOrId) {
+        if (!nameOrId)
+            return undefined;
+        return (await this.resolve(path, what, nameOrId)).id;
+    }
+    /** The cached listing if we already have one; never fetches. */
+    async peek(path) {
+        const pending = this.cache.get(path);
+        if (!pending)
+            return null;
+        return pending.catch(() => null);
+    }
+}
+function describe(items) {
+    const names = items
+        .map((item) => item.name ?? item.id)
+        .filter(Boolean)
+        .sort();
+    return names.length ? names.join(", ") : "(none)";
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,126 @@
+import type { HttpClient } from "./http.ts";
+import type { Resolver } from "./resolve.ts";
+import type { Agent, AgentInput, AgentPatch, Connection, ConnectionProvider, ConnectionProviderInput, ConnectionProviderPatch, Environment, EnvironmentInput, EnvironmentPatch, Secret, Vault, VaultInput, VaultPatch, VaultSecret, VaultSecretMetadataPatch } from "./types.ts";
+/**
+ * Payloads here use the API's own key names (`environment_id`, `mcp_servers`,
+ * `allowed_vault_ids`) rather than camelCase. That is a choice, not an
+ * oversight: an agent definition is the same object in the REST API, in a
+ * `fountain.yml` manifest and here, so one definition reads identically in all
+ * three and the API reference doubles as the SDK reference. Options that
+ * control the SDK's own behaviour — `timeoutMs`, `signal` — are camelCase,
+ * because those are not data.
+ */
+/**
+ * List, read, define, change and delete one kind of thing.
+ *
+ * `Patch` is its own parameter rather than `Partial<Input>`: the API's update
+ * schemas are not simply every create field made optional, and the generated
+ * ones say so exactly.
+ */
+declare class Collection<T extends {
+    id: string;
+}, Input, Patch> {
+    protected readonly http: HttpClient;
+    protected readonly resolver: Resolver;
+    protected readonly path: string;
+    protected readonly what: string;
+    constructor(http: HttpClient, resolver: Resolver, path: string, what: string);
+    /** Everything on the account. */
+    list(search?: string): Promise<T[]>;
+    /** One of them, by name or id. */
+    get(nameOrId: string): Promise<T>;
+    /** Define a new one. */
+    create(input: Input): Promise<T>;
+    /** Change one. Only the fields you pass are touched. */
+    update(nameOrId: string, patch: Patch): Promise<T>;
+    /** Delete one. */
+    delete(nameOrId: string): Promise<void>;
+}
+/**
+ * Secrets on an environment or a vault.
+ *
+ * Values are write-only: `list` returns keys, never what they are worth. That
+ * is the whole point — the SDK can put a credential into a sandbox and can
+ * never read it back out.
+ */
+declare class Secrets {
+    protected readonly http: HttpClient;
+    private readonly resolver;
+    private readonly parentPath;
+    private readonly what;
+    constructor(http: HttpClient, resolver: Resolver, parentPath: string, what: string);
+    /** The keys stored here. Never the values. */
+    list(parent: string): Promise<Secret[]>;
+    /** Store a secret, or replace one with the same key. */
+    set(parent: string, key: string, value: string): Promise<Secret>;
+    /** Store several at once. */
+    setAll(parent: string, secrets: Record<string, string>): Promise<Secret[]>;
+    /** Remove one, by key. */
+    delete(parent: string, key: string): Promise<void>;
+    protected parentId(nameOrId: string): Promise<string>;
+}
+/** Vault metadata can change without reading or replacing its secret value. */
+declare class VaultSecrets extends Secrets {
+    update(parent: string, key: string, patch: VaultSecretMetadataPatch): Promise<VaultSecret>;
+}
+/** The agents on this account. */
+export declare class Agents extends Collection<Agent, AgentInput, AgentPatch> {
+    constructor(http: HttpClient, resolver: Resolver);
+}
+/** The environments on this account, and their secrets. */
+export declare class Environments extends Collection<Environment, EnvironmentInput, EnvironmentPatch> {
+    readonly secrets: Secrets;
+    constructor(http: HttpClient, resolver: Resolver);
+}
+/**
+ * The provider accounts this tenant has signed in to, whose credentials
+ * Fountain holds (#1178). Connecting one is a browser round trip — send the
+ * account owner to `connect_url` from `providers()` — so there is no `create`
+ * here. An agent uses one by naming it in `mcp_servers`:
+ * `{ gmail: { connection: "<id>" } }`. Only for accounts the egress broker is
+ * on for; elsewhere every call is a `NotFoundError` (`connections_not_enabled`).
+ */
+export declare class Connections {
+    private readonly http;
+    /** Where connections get their tokens: Google, plus the tenant's own providers (#1186). */
+    readonly providers: ConnectionProviders;
+    constructor(http: HttpClient);
+    /** Every connection on the account, active or revoked. Never a token. */
+    list(): Promise<Connection[]>;
+    /** One connection by id. Unenveloped, as the server answers `show`. */
+    get(id: string): Promise<Connection>;
+    /** Revoke at the provider and delete. Agents that name it get `connection revoked`. */
+    delete(id: string): Promise<void>;
+}
+/**
+ * Connection providers (#1186): the platform provider (Google, id `google`),
+ * the tenant's own OAuth apps (`kind: "oauth2"`) and the remote MCP servers
+ * whose authorization Fountain discovered (`kind: "mcp"`). The client secret
+ * is write-only. Only for accounts the egress broker is on for.
+ */
+export declare class ConnectionProviders {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Google first, then the tenant's own. */
+    list(): Promise<ConnectionProvider[]>;
+    /** One provider; `"google"` is the platform provider. */
+    get(id: string): Promise<ConnectionProvider>;
+    /**
+     * Define a provider. `kind: "oauth2"` takes the tenant's app registration;
+     * `kind: "mcp"` takes `mcp_url` and Fountain discovers the authorization
+     * server and registers a client where it can.
+     */
+    create(input: ConnectionProviderInput): Promise<ConnectionProvider>;
+    /** Edit a tenant provider. A blank `client_secret` keeps the stored one. */
+    update(id: string, patch: ConnectionProviderPatch): Promise<ConnectionProvider>;
+    /** Delete a tenant provider and every connection on it. */
+    delete(id: string): Promise<void>;
+    /** Run MCP discovery again on an `mcp` provider. */
+    discover(id: string): Promise<ConnectionProvider>;
+}
+/** The vaults on this account, and their secrets. */
+export declare class Vaults extends Collection<Vault, VaultInput, VaultPatch> {
+    readonly secrets: VaultSecrets;
+    constructor(http: HttpClient, resolver: Resolver);
+}
+export {};