@kammcs/buildit-mcp 0.0.0-stage → 0.2.0

package/dist/api/client.js

@@ -0,0 +1,382 @@
+/**
+ * A small fetch wrapper for the buildIt.Social agent API.
+ *
+ * - Every call sends `Authorization: Bearer <token>`, a fresh `X-Request-Id`
+ *   (also logged, so a call can be traced across the two systems),
+ *   `X-Buildit-Client` (the MCP client's name and version when known, and
+ *   this server's) and, when made on behalf of a tool, `X-Buildit-Tool`.
+ * - The API's error envelope `{error: {code, message, hint, details}}`
+ *   becomes an ApiError.
+ * - A 429 is retried once after `retry_after`, when that wait is within the
+ *   cap; a longer wait comes back to the agent as an error to act on. A 429
+ *   that gives no wait (a limit in front of the API hides Retry-After) means
+ *   a minute, as the contract says.
+ * - get_meta and get_me (the contract's discovery operations) carry no
+ *   RateLimit-* headers; nothing here reads those headers.
+ * - Each attempt has a timeout.
+ *
+ * The client holds the token of one caller and is created per caller (once
+ * in stdio mode, per HTTP request in HTTP mode). It never logs the token,
+ * request bodies, query strings or response bodies, and it logs an
+ * operation's path template (/v1/items/{key}) rather than the filled-in path,
+ * which can carry names.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { silentLogger } from '../log.js';
+import { SERVER_NAME, SERVER_VERSION } from '../version.js';
+import { MeResponseSchema, MetaResponseSchema, } from './generated/schemas.js';
+/**
+ * The API's error envelope, read tolerantly. The contract lists each code
+ * with its own details, but v1 may add codes, so any code is accepted here
+ * and the details are kept as they come.
+ */
+const ErrorEnvelopeSchema = z.object({
+    error: z.looseObject({
+        code: z.string(),
+        message: z.string().optional(),
+        hint: z.string().optional(),
+        details: z.unknown().optional(),
+    }),
+});
+/** Codes produced by this client rather than by the API. */
+export const LOCAL_ERROR_CODES = {
+    timeout: 'timeout',
+    network: 'network_error',
+    invalidResponse: 'invalid_response',
+};
+export class ApiError extends Error {
+    name = 'ApiError';
+    /** A stable code from the API (for example `transition_not_allowed`) or a local one. */
+    code;
+    /** The HTTP status, or 0 when no response arrived. */
+    status;
+    details;
+    /** The API's one-line next step for this code, when it sent one. */
+    hint;
+    requestId;
+    /** Seconds to wait before retrying, when the API said so. */
+    retryAfterSeconds;
+    /** Extra guidance a tool adds for its own arguments (shown after the details). */
+    note;
+    constructor(init) {
+        super(init.message);
+        this.code = init.code;
+        this.status = init.status;
+        this.details = init.details;
+        this.hint = init.hint;
+        this.requestId = init.requestId;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.note = init.note;
+    }
+    /** The same error with a tool's note added. */
+    withNote(note) {
+        return new ApiError({
+            code: this.code,
+            message: this.message,
+            status: this.status,
+            requestId: this.requestId,
+            details: this.details,
+            hint: this.hint,
+            retryAfterSeconds: this.retryAfterSeconds,
+            note: this.note ? [this.note, note].join('\n') : note,
+        });
+    }
+}
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_RETRY_AFTER_MS = 10_000;
+/**
+ * The wait for a 429 that gives none: a limit in front of the API answers
+ * without the error envelope and, behind the gateway, without Retry-After.
+ * The contract says to retry after a minute then. Above the default cap, so
+ * it goes back to the agent instead of being waited out.
+ */
+export const DEFAULT_RATE_LIMIT_WAIT_SECONDS = 60;
+const USER_AGENT = `${SERVER_NAME}/${SERVER_VERSION}`;
+const MAX_CLIENT_HEADER = 200;
+/** One `name/version` product token, reduced to visible ASCII without spaces or slashes. */
+function productToken(name, version) {
+    // "!" to "~" is the visible ASCII range; anything else (spaces too) becomes "_".
+    const clean = (s, max) => s
+        .replace(/[^!-~]+/g, '_')
+        .replace(/\//g, '_')
+        .slice(0, max);
+    const n = clean(name, 60) || 'unknown';
+    return version ? `${n}/${clean(version, 30)}` : n;
+}
+/**
+ * The X-Buildit-Client value: "client/version buildit-mcp/version", or just
+ * this server's token when the client didn't say who it is.
+ */
+export function clientHeader(client) {
+    const server = productToken(SERVER_NAME, SERVER_VERSION);
+    if (!client || client.name.trim() === '')
+        return server;
+    return `${productToken(client.name, client.version)} ${server}`.slice(0, MAX_CLIENT_HEADER);
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function toSeconds(value) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** retry_after from the error details, the body, or the Retry-After header (seconds or a date). */
+function readRetryAfter(body, headers) {
+    const root = asRecord(body);
+    const error = asRecord(root?.error);
+    const details = asRecord(error?.details);
+    const fromBody = toSeconds(details?.retry_after) ??
+        toSeconds(error?.retry_after) ??
+        toSeconds(root?.retry_after);
+    if (fromBody !== undefined)
+        return fromBody;
+    const header = headers.get('retry-after');
+    if (header === null)
+        return undefined;
+    const seconds = toSeconds(header.trim());
+    if (seconds !== undefined)
+        return seconds;
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, (date - Date.now()) / 1000);
+}
+export class ApiClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    timeoutMs;
+    maxRetryAfterMs;
+    logger;
+    sleep;
+    onError;
+    /**
+     * What the API said of itself in the last /v1/meta this client read (stdio
+     * reads it at startup; whoami reads it too): its version and, from API
+     * 1.1.0, the operations it serves. Undefined until then. It describes the
+     * deployment, not the caller.
+     */
+    served;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetryAfterMs = options.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS;
+        this.logger = options.logger ?? silentLogger;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.onError = options.onError;
+    }
+    /** GET /v1/meta */
+    async getMeta(options = {}) {
+        const meta = await this.requestParsed('GET', '/v1/meta', MetaResponseSchema, {
+            operation: 'get_meta',
+            ...options,
+        });
+        this.served = {
+            apiVersion: meta.api_version,
+            operations: meta.operations ? new Set(meta.operations) : undefined,
+        };
+        return meta;
+    }
+    /** GET /v1/me */
+    async getMe(options = {}) {
+        return this.requestParsed('GET', '/v1/me', MeResponseSchema, {
+            operation: 'get_me',
+            ...options,
+        });
+    }
+    /** A request whose JSON response is validated with `schema`. */
+    async requestParsed(method, path, schema, options = {}) {
+        const { body, requestId } = await this.send(method, path, options);
+        const parsed = schema.safeParse(body);
+        if (!parsed.success) {
+            throw new ApiError({
+                code: LOCAL_ERROR_CODES.invalidResponse,
+                message: `The API's response to ${method} ${path} did not have the expected shape. The server and the API may be out of step; check for a newer buildit-mcp.`,
+                status: 200,
+                requestId,
+                details: { issues: parsed.error.issues.slice(0, 5).map((i) => i.path.join('.')) },
+            });
+        }
+        return parsed.data;
+    }
+    /** A request whose JSON response (or undefined for 204) is returned as is. */
+    async request(method, path, options = {}) {
+        return (await this.send(method, path, options)).body;
+    }
+    buildUrl(path, query) {
+        const url = new URL(this.baseUrl + (path.startsWith('/') ? path : `/${path}`));
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    url.searchParams.append(key, v);
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    async send(method, path, options) {
+        try {
+            return await this.sendOnce(method, path, options);
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                try {
+                    this.onError?.(err);
+                }
+                catch {
+                    // A listener's failure must not hide the API's error.
+                }
+            }
+            throw err;
+        }
+    }
+    async sendOnce(method, path, options) {
+        const url = this.buildUrl(path, options.query);
+        let retried = false;
+        for (;;) {
+            const requestId = randomUUID();
+            const started = Date.now();
+            const logFields = {
+                request_id: requestId,
+                method,
+                ...(options.operation ? { operation: options.operation } : {}),
+                path: options.pathTemplate ?? path,
+                ...(options.tool ? { tool: options.tool } : {}),
+            };
+            const headers = {
+                Authorization: `Bearer ${this.token}`,
+                Accept: 'application/json',
+                'User-Agent': USER_AGENT,
+                'X-Request-Id': requestId,
+                'X-Buildit-Client': clientHeader(options.client),
+            };
+            if (options.tool)
+                headers['X-Buildit-Tool'] = options.tool;
+            let payload;
+            if (options.body !== undefined) {
+                headers['Content-Type'] = 'application/json';
+                payload = JSON.stringify(options.body);
+            }
+            const timeout = AbortSignal.timeout(this.timeoutMs);
+            const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    ...(payload === undefined ? {} : { body: payload }),
+                    signal,
+                    redirect: 'error',
+                });
+            }
+            catch (err) {
+                const timedOut = timeout.aborted;
+                const aborted = options.signal?.aborted === true;
+                this.logger.warn('api call failed', {
+                    ...logFields,
+                    error: timedOut ? 'timeout' : aborted ? 'aborted' : 'network_error',
+                    duration_ms: Date.now() - started,
+                });
+                if (aborted && !timedOut)
+                    throw err;
+                throw new ApiError({
+                    code: timedOut ? LOCAL_ERROR_CODES.timeout : LOCAL_ERROR_CODES.network,
+                    message: timedOut
+                        ? `The buildIt.Social API did not answer within ${Math.round(this.timeoutMs / 1000)} s. Try again shortly.`
+                        : 'Could not reach the buildIt.Social API. Check the network and BUILDIT_API_URL, then try again.',
+                    status: 0,
+                    requestId,
+                });
+            }
+            const text = await response.text().catch(() => '');
+            let body = undefined;
+            let jsonOk = true;
+            if (text.length > 0) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    jsonOk = false;
+                }
+            }
+            this.logger.info('api call', {
+                ...logFields,
+                status: response.status,
+                duration_ms: Date.now() - started,
+            });
+            if (response.status === 429 && !retried) {
+                const retryAfter = readRetryAfter(body, response.headers) ?? DEFAULT_RATE_LIMIT_WAIT_SECONDS;
+                const waitMs = Math.ceil(retryAfter * 1000);
+                if (waitMs <= this.maxRetryAfterMs) {
+                    retried = true;
+                    this.logger.info('rate limited; retrying once', { ...logFields, wait_ms: waitMs });
+                    await this.sleep(waitMs);
+                    continue;
+                }
+            }
+            if (response.ok) {
+                if (!jsonOk) {
+                    throw new ApiError({
+                        code: LOCAL_ERROR_CODES.invalidResponse,
+                        message: `The API's response to ${method} ${path} was not JSON.`,
+                        status: response.status,
+                        requestId,
+                    });
+                }
+                return { body, requestId };
+            }
+            throw this.toApiError(response, body, requestId);
+        }
+    }
+    toApiError(response, body, requestId) {
+        const retryAfterSeconds = response.status === 429
+            ? (readRetryAfter(body, response.headers) ?? DEFAULT_RATE_LIMIT_WAIT_SECONDS)
+            : undefined;
+        const envelope = ErrorEnvelopeSchema.safeParse(body);
+        if (envelope.success) {
+            const { code, message, hint, details } = envelope.data.error;
+            return new ApiError({
+                code,
+                message: message ?? `The API refused the request (${code}).`,
+                status: response.status,
+                requestId,
+                details,
+                hint,
+                retryAfterSeconds,
+            });
+        }
+        if (response.status === 429) {
+            // A limit in front of the API (per address) answers without the error
+            // envelope: it is still a rate limit, with the header's wait, else a minute.
+            const root = asRecord(body);
+            const said = typeof root?.message === 'string' ? root.message.trim().slice(0, 300) : '';
+            return new ApiError({
+                code: 'rate_limited',
+                message: said
+                    ? `Too many requests: ${said}`
+                    : 'Too many requests to the buildIt.Social API.',
+                status: 429,
+                requestId,
+                details: {},
+                retryAfterSeconds,
+            });
+        }
+        return new ApiError({
+            code: `http_${response.status}`,
+            message: `The API answered HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`,
+            status: response.status,
+            requestId,
+            retryAfterSeconds,
+        });
+    }
+}