@50arms/platform-mcp 0.0.0-stage → 0.1.436

package/dist/http-client.js

@@ -0,0 +1,190 @@
+import { boardStampOf, takesBoardInBody } from "./route-board-scope.js";
+import { assertVersionFloorSatisfied, MCP_MIN_VERSION_HEADER, MCP_VERSION_HEADER, readOwnVersion } from "./version-floor.js";
+import { PLUGIN_BACKGROUND_HEADER } from "./session-options.js";
+/** `<basePath><path>` with the path's own query string cut off and its leading slash normalised (an empty or "/" path adds nothing). */
+function routePathOf(path, basePath = "/api/issues") {
+    const [rawPath] = path.split("?", 2);
+    if (rawPath === "" || rawPath === "/")
+        return basePath;
+    return `${basePath}${rawPath.startsWith("/") ? rawPath : `/${rawPath}`}`;
+}
+export class DashboardHttpClient {
+    config;
+    fetchImpl;
+    // DX-3597 — true once this instance has made ONE request, regardless of
+    // outcome. Drives the "first call OR any 4xx" version-floor check below.
+    hasCheckedVersionFloor = false;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * DX-4390 — the bearer this client stamps. A session signs in (or out) while the server runs, so
+     * the key is not fixed at construction; "" means signed out.
+     */
+    setToken(token) {
+        this.config.token = token;
+    }
+    /**
+     * DX-5076 - the ONE entry for a request this process makes on its own (the listener's health read, the key-permission read, the permission claim
+     * poll): it is never the agent acting, so it carries the background mark and ends no agent pause. A call the agent makes (`50arms_api`, a
+     * permission-request create) goes through `request` instead. No call site sets `background` by hand.
+     */
+    requestOwn(args) {
+        return this.request({ ...args, background: true });
+    }
+    async request(args) {
+        if (this.config.token === "") {
+            // DX-4390 — a caller reaches here only past the sign-in halt; a bearer-less call is a bug.
+            throw new Error("[platform-mcp] request attempted while signed out");
+        }
+        const url = this.buildUrl(args.method, args.path, args.query, args.board, args.basePath);
+        const headers = {
+            Authorization: `Bearer ${this.config.token}`,
+            Accept: "application/json",
+        };
+        // DX-1398 Hop 3 (outbound) — stamp the cross-process trace at the SAME
+        // single choke point that stamps Authorization, so every call (GET + every
+        // write) chains under the originating launch. Omitted when the dispatch
+        // carries no trace context (the dashboard then mints a fresh root).
+        if (this.config.traceparent) {
+            headers["traceparent"] = this.config.traceparent;
+        }
+        // DX-2683 — the working session's identity, stamped at the SAME single
+        // choke point as Authorization above, and for the same reason: it must
+        // ride EVERY call, not the plan calls. That is what lets the dashboard
+        // learn a session exists — and keep its last-active time current — purely
+        // from the card work the agent was already doing, with no cooperation
+        // from the agent and no per-tool parameter it could omit or falsify.
+        // Absent outside a Claude Code session; then nothing is stamped.
+        //
+        // NO TITLE HEADER (DX-2816, revised). This server has no way to read
+        // Claude's own session title — see `readSessionConfig` in `index.ts`.
+        // The title travels instead as `plan_connect`'s own `title` argument,
+        // straight in that call's body, because the AGENT (not this process) is
+        // the one thing able to read it.
+        if (this.config.session) {
+            headers["x-danx-session-id"] = this.config.session.id;
+        }
+        // DX-5897 - this server's own version rides every call: a route with a surface floor of its own (the agent-profile fetch) refuses a stale session by it.
+        headers[MCP_VERSION_HEADER] = readOwnVersion();
+        if (args.background === true) {
+            headers[PLUGIN_BACKGROUND_HEADER] = "1";
+        }
+        let payload;
+        if (args.rawBody !== undefined) {
+            if (args.body !== undefined)
+                throw new Error("[platform-mcp] a request sends `body` or `rawBody`, never both");
+            headers["Content-Type"] = args.rawBody.contentType;
+            payload = new Blob([args.rawBody.bytes]);
+        }
+        else if (args.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(this.withBodyBoard(args));
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: args.method,
+                headers,
+                body: payload,
+            });
+        }
+        catch (err) {
+            throw new Error(`[platform-mcp] network failure on ${args.method} ${url}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // DX-3597 — proactive on the first call this instance ever makes
+        // (regardless of outcome: a stale client can otherwise look fine for a
+        // while on routes whose shape didn't change), and on every subsequent
+        // 4xx (a response that might otherwise read as an ordinary caller
+        // error when it's really "you're running an old MCP"). Throws
+        // McpOutdatedError instead of returning below when this package is
+        // behind the floor — see version-floor.ts's own doc.
+        const isFirstCall = !this.hasCheckedVersionFloor;
+        this.hasCheckedVersionFloor = true;
+        if (isFirstCall || (res.status >= 400 && res.status < 500)) {
+            assertVersionFloorSatisfied(res.headers.get(MCP_MIN_VERSION_HEADER));
+        }
+        const text = await res.text();
+        let parsed = null;
+        if (text !== "") {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // Non-JSON response from a v2 route is a server-side fault —
+                // throw rather than fabricate an envelope.
+                throw new Error(`[platform-mcp] non-JSON response (status ${res.status}) from ${args.method} ${url}: ${text.slice(0, 200)}`);
+            }
+        }
+        if (res.status >= 500) {
+            throw new Error(`[platform-mcp] server error ${res.status} on ${args.method} ${url}: ${text.slice(0, 500)}`);
+        }
+        if (res.status >= 200 && res.status < 300) {
+            return { ok: true, status: res.status, body: parsed };
+        }
+        return { ok: false, status: res.status, body: parsed };
+    }
+    /**
+     * DX-5337 - the body of a request whose route reads the board from `body.board` (issue create/import): the board the caller wrote is kept;
+     * with none, the call's `board` argument or the dispatch's board is filled in. DX-3465 deleted the per-operation `issue_create` tool that
+     * put the dispatch's board in the body, and the create route does not read `?board=`, so a dispatched agent's create arrived with no board
+     * and was refused 400. A board-less server with no `board` argument fills nothing: the dashboard's own 400 names the missing board.
+     */
+    withBodyBoard(args) {
+        const body = args.body;
+        if (!takesBoardInBody(args.method, routePathOf(args.path, args.basePath)))
+            return body;
+        if (typeof body !== "object" || body === null || Array.isArray(body))
+            return body;
+        if (body.board !== undefined)
+            return body;
+        const board = args.board ?? this.config.board;
+        return board === undefined ? body : { ...body, board };
+    }
+    buildUrl(method, path, extraQuery, boardOverride, basePath = "/api/issues") {
+        const base = this.config.baseUrl.replace(/\/+$/, "");
+        const [, existingQs] = path.split("?", 2);
+        const params = new URLSearchParams(existingQs ?? "");
+        // DX-3750 / DX-4303 — only a route the dashboard takes `?board=` on gets the stamp; see `route-board-scope.ts`.
+        // DX-4542 — a route whose board is OPTIONAL (no board = the whole team) gets only the board the caller named: stamping the dispatch's
+        // board there would make the team-wide list impossible to ask for.
+        const routePath = routePathOf(path, basePath);
+        const stamp = boardStampOf(method, routePath);
+        // DX-5337: issue create/import take the board in the body only (`withBodyBoard`), so no `?board=` rides them: one path, never two.
+        const boardInQuery = !takesBoardInBody(method, routePath);
+        if (boardInQuery && stamp === "stamp") {
+            const board = boardOverride ?? this.config.board;
+            // DX-4592: a board-less server (the 50arms plugin's, no DANXBOT_BOARD_ID) stamps nothing when the call names no
+            // board. Whether the route NEEDS one is the dashboard's to say: a route that does (quality-gate and settings routes, the dispatch
+            // verbs) answers 400 naming `board`, while a card-id, plan or plan-session route takes its board from the card
+            // or the plan. Refusing here (DX-4555) wrongly stopped every plan route, `plan_connect` first.
+            if (board !== undefined)
+                params.set("board", String(board));
+        }
+        else if (boardInQuery && stamp === "named" && boardOverride !== undefined) {
+            params.set("board", String(boardOverride));
+        }
+        if (extraQuery) {
+            for (const [k, v] of Object.entries(extraQuery)) {
+                if (v === undefined || v === null)
+                    continue;
+                // DX-3465 — a field TREE (`fields`, a plain object) is the only
+                // query param the server parses as JSON
+                // (`src/resources/field-tree.ts`); every LIST-valued param it has
+                // (`ids` on `GET /api/issues/batch`, `status` on the boards list,
+                // `endpoints` on `GET /api/openapi`) splits on commas instead, never
+                // JSON. Arrays are `typeof "object"` too, so the array check must
+                // come BEFORE the plain-object branch. A plain scalar stringifies
+                // as before.
+                params.set(k, Array.isArray(v)
+                    ? v.map((item) => String(item)).join(",")
+                    : typeof v === "object"
+                        ? JSON.stringify(v)
+                        : String(v));
+            }
+        }
+        const query = params.toString();
+        return `${base}${routePath}${query === "" ? "" : `?${query}`}`;
+    }
+}