boondmanager-mcp-server 2.15.2 → 2.17.0

package/dist/services/http/download.js

@@ -0,0 +1,160 @@
+import { send } from "./transport.js";
+/**
+ * Parse the filename out of a `Content-Disposition` header. Handles the
+ * common `filename="…"`/`filename=…` forms and the RFC 5987
+ * `filename*=UTF-8''…` form. Returns undefined when absent. Exported for
+ * unit testing.
+ */
+export function parseContentDispositionFilename(header) {
+    if (!header)
+        return undefined;
+    const star = header.match(/filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/);
+    if (star) {
+        try {
+            return decodeURIComponent((star[1] ?? "").trim());
+        }
+        catch {
+            // fall through to the plain form
+        }
+    }
+    const plain = header.match(/filename\s*=\s*"([^"]+)"/) ?? header.match(/filename\s*=\s*([^;]+)/);
+    const name = plain?.[1]?.trim();
+    return name === undefined ? undefined : repairUtf8Filename(name);
+}
+/**
+ * BoondManager writes the plain `filename="…"` form with UTF-8 bytes (often
+ * NFD: `e` + combining acute), and `fetch` decodes header bytes as Latin-1 as
+ * the spec says — so "Frédéric" arrives as "FreÌdeÌric" (observed live on
+ * 2026-09-26, issue #311). Re-decode those bytes as UTF-8 when that yields a
+ * clean string, and normalise to NFC so the name compares like a normal one.
+ */
+export function repairUtf8Filename(name) {
+    if (!/[\u0080-\u00ff]/.test(name))
+        return name;
+    const decoded = Buffer.from(name, "latin1").toString("utf8");
+    if (decoded.includes("\ufffd"))
+        return name.normalize("NFC");
+    return decoded.normalize("NFC");
+}
+/** Human-readable byte count for progress messages (same units as the tool output). */
+function formatBytes(bytes) {
+    return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} Mo` : `${Math.round(bytes / 1024)} Ko`;
+}
+/** Progress steps emitted while streaming a download (≈ every 10 %). */
+const DOWNLOAD_PROGRESS_STEPS = 10;
+/**
+ * Thrown by `apiDownload` when the payload exceeds `maxBytes` — before the
+ * body is read when the response announces its size, otherwise the moment the
+ * running total crosses the cap (the stream is cancelled, nothing more is
+ * buffered). `bytes` is the announced size in the first case and a lower
+ * bound (bytes received so far) in the second; `announced` tells which.
+ */
+export class DownloadTooLargeError extends Error {
+    bytes;
+    maxBytes;
+    announced;
+    constructor(path, bytes, maxBytes, announced) {
+        super(`Document exceeds the ${formatBytes(maxBytes)} limit (${announced ? "announced size" : "more than"} ${formatBytes(bytes)}).\nEndpoint: GET ${path}`);
+        this.name = "DownloadTooLargeError";
+        this.bytes = bytes;
+        this.maxBytes = maxBytes;
+        this.announced = announced;
+    }
+}
+/**
+ * Read a download body chunk by chunk, enforcing `maxBytes` as the bytes
+ * arrive and reporting progress as it goes.
+ *
+ * Streaming is the single path (#235): the cap has to be applied *while*
+ * reading, or a 200 MB file is fully buffered before it is refused. Progress
+ * is only an observer on top of it — emitted when someone is listening and the
+ * response announced a `Content-Length` (without a total there is nothing
+ * meaningful to report). A response without a readable stream falls back to
+ * `arrayBuffer()` and is checked afterwards.
+ */
+async function readDownloadBody(response, path, maxBytes, onProgress) {
+    const contentLength = Number(response.headers.get("content-length"));
+    const totalBytes = Number.isFinite(contentLength) && contentLength > 0 ? contentLength : undefined;
+    const body = response.body;
+    if (!body) {
+        const buffered = Buffer.from(await response.arrayBuffer());
+        if (buffered.byteLength > maxBytes)
+            throw new DownloadTooLargeError(path, buffered.byteLength, maxBytes, true);
+        return buffered;
+    }
+    const reporting = onProgress?.enabled === true && totalBytes !== undefined;
+    const reader = body.getReader();
+    const step = totalBytes !== undefined ? Math.max(1, Math.floor(totalBytes / DOWNLOAD_PROGRESS_STEPS)) : Infinity;
+    const chunks = [];
+    let received = 0;
+    let reported = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        received += value.byteLength;
+        if (received > maxBytes) {
+            // Stop pulling: what is already in `chunks` is dropped with this frame.
+            await reader.cancel().catch(() => undefined);
+            throw new DownloadTooLargeError(path, received, maxBytes, false);
+        }
+        chunks.push(value);
+        // Throttled to ~10 notifications: a 5 MiB file arrives in ~80 network
+        // chunks, and one notification each would be its own kind of flood.
+        if (reporting && received - reported >= step) {
+            reported = received;
+            onProgress(received, totalBytes, `Téléchargement — ${formatBytes(received)} / ${formatBytes(totalBytes)}`);
+        }
+    }
+    if (reporting && received > reported) {
+        onProgress(received, totalBytes, `Téléchargement terminé — ${formatBytes(received)}`);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Download a binary payload (documents, justificatifs…) from the BoondManager
+ * API. Same pipeline as `apiRequest` (`send()`: auth, path guard, rate limit,
+ * timeout, retry policy for a GET), but the body is streamed raw instead of
+ * being parsed as JSON:API.
+ *
+ * `onProgress` reports bytes received when the client asked for progress and
+ * the response carries a `Content-Length`; otherwise nothing is emitted.
+ *
+ * `options.maxBytes` bounds memory: a `Content-Length` above it is refused
+ * before a single body byte is read, and a body without one is cancelled the
+ * moment it crosses the cap (`DownloadTooLargeError` either way).
+ */
+export async function apiDownload(path, onProgress, options = {}) {
+    const maxBytes = options.maxBytes ?? Infinity;
+    const response = await send(path, { method: "GET", headers: { Accept: "*/*" } });
+    const contentType = response.headers.get("content-type")?.split(";")[0]?.trim() || "application/octet-stream";
+    const filename = parseContentDispositionFilename(response.headers.get("content-disposition"));
+    // BoondManager only answers 404 on an unknown document when the request asks
+    // for JSON. With the `Accept: */*` this function sends, it serves the
+    // application shell instead — HTTP 200, `text/html`, ~9 KB — which the caller
+    // would happily surface as the document's text content. A truncated id then
+    // looks like a corrupted file rather than a wrong id, so refuse the shell
+    // here. An HTML *document* is still downloadable: a real file download
+    // carries a `Content-Disposition` filename, the shell doesn't.
+    if (contentType === "text/html" && !filename) {
+        throw new Error([
+            "BoondManager returned an HTML page instead of a document (HTTP 200, text/html).",
+            `Endpoint: GET ${path}`,
+            "Hint: The document id is most likely wrong or truncated. Entity relations expose suffixed ids " +
+                "(e.g. `123_resume`, `123_file`) — pass the id verbatim, suffix included. BoondManager serves its " +
+                "application shell for an unknown /documents/<id> instead of a 404.",
+        ].join("\n"));
+    }
+    // Announced size over the cap: refuse without reading the body. The
+    // 30 s timeout used to be the only bound on a 200 MB document (#235).
+    const announced = Number(response.headers.get("content-length"));
+    if (Number.isFinite(announced) && announced > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new DownloadTooLargeError(path, announced, maxBytes, true);
+    }
+    const data = await readDownloadBody(response, path, maxBytes, onProgress);
+    return { data, contentType, ...(filename !== undefined ? { filename } : {}) };
+}
+//# sourceMappingURL=download.js.map

package/dist/services/http/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../../src/services/http/download.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAAC,MAAqB;IACnE,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACvE,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,OAAO,kBAAkB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACjG,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAChC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAQD,uFAAuF;AACvF,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;AAC5G,CAAC;AAED,wEAAwE;AACxE,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,KAAK,CAAS;IACd,QAAQ,CAAS;IACjB,SAAS,CAAU;IAC5B,YAAY,IAAY,EAAE,KAAa,EAAE,QAAgB,EAAE,SAAkB;QAC3E,KAAK,CACH,wBAAwB,WAAW,CAAC,QAAQ,CAAC,WAAW,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,WAAW,IAAI,WAAW,CAAC,KAAK,CAAC,qBAAqB,IAAI,EAAE,CACpJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAQD;;;;;;;;;;GAUG;AACH,KAAK,UAAU,gBAAgB,CAC7B,QAAkB,EAClB,IAAY,EACZ,QAAgB,EAChB,UAA6B;IAE7B,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACrE,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IACnG,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,IAAI,QAAQ,CAAC,UAAU,GAAG,QAAQ;YAAE,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC/G,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,EAAE,OAAO,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,CAAC;IAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjH,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,SAAS,CAAC;QACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,MAAM;QAChB,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC;QAC7B,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;YACxB,wEAAwE;YACxE,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7C,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,sEAAsE;QACtE,oEAAoE;QACpE,IAAI,SAAS,IAAI,QAAQ,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC;YAC7C,QAAQ,GAAG,QAAQ,CAAC;YACpB,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,oBAAoB,WAAW,CAAC,QAAQ,CAAC,MAAM,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IAED,IAAI,SAAS,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;QACrC,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,4BAA4B,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,UAA6B,EAC7B,UAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAEjF,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,0BAA0B,CAAC;IAC9G,MAAM,QAAQ,GAAG,+BAA+B,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAE9F,6EAA6E;IAC7E,sEAAsE;IACtE,8EAA8E;IAC9E,4EAA4E;IAC5E,0EAA0E;IAC1E,uEAAuE;IACvE,+DAA+D;IAC/D,IAAI,WAAW,KAAK,WAAW,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb;YACE,iFAAiF;YACjF,iBAAiB,IAAI,EAAE;YACvB,gGAAgG;gBAC9F,mGAAmG;gBACnG,oEAAoE;SACvE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,sEAAsE;IACtE,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACjE,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;QACvD,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC1E,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAChF,CAAC"}

package/dist/services/http/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pull the human-readable bits out of a BoondManager error body.
+ *
+ * Boond returns JSON:API errors of the form:
+ *   { "errors": [ { "status": "422", "code": "422", "detail": "...", "title": "..." } ] }
+ *
+ * Surfacing `detail` (and `title` when present) gives the model a focused
+ * message like `422 - password mismatch` instead of the full ~500-char body
+ * dump that previously made it hard for the LLM to reason about the failure.
+ *
+ * Exported for unit testing.
+ */
+export declare function parseBoondErrorBody(body: string): string | null;
+/**
+ * What a caller can do about a BoondManager 401, which depends on who holds
+ * the credentials (issue #234). Under the HTTP OAuth transport the token
+ * belongs to the MCP client, and the only remedy is a new authorization —
+ * there is no CLI to re-run (the historical hint named one that is no longer
+ * shipped). With env credentials it is the operator's configuration.
+ */
+export declare function hintForUnauthorized(): string;
+/**
+ * A non-2xx answer from BoondManager, with the status kept as data so callers
+ * (the HTTP transport's token validation, #234) can branch on it instead of
+ * parsing the message. The message is unchanged from the plain `Error` this
+ * replaces — `formatApiError()` output.
+ */
+export declare class BoondApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(message: string, status: number, method: string, path: string);
+}
+/** Build the Error message for a non-2xx HTTP response. Exported for testing. */
+export declare function formatApiError(status: number, statusText: string, method: string, path: string, body: string): string;
+/** The error every helper raises when an attempt never completed within `BOOND_HTTP_TIMEOUT_MS`. */
+export declare function timeoutError(timeoutMs: number, method: string, path: string, cause: unknown): Error;
+/**
+ * A 2xx whose body is not JSON. Before #239 this surfaced as a bare
+ * `SyntaxError: Unexpected token '<'` with no endpoint — indistinguishable
+ * from a bug in the server — although it almost always means the request hit
+ * the application shell or a WAF page rather than the API.
+ */
+export declare function nonJsonResponseError(status: number, method: string, path: string, cause: unknown): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/services/http/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/services/http/errors.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiC/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAS5C;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAO1E;AAyDD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA0BrH;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,CASnG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,CASxG"}

package/dist/services/http/errors.js

@@ -0,0 +1,188 @@
+/**
+ * Error shaping for BoondManager responses: JSON:API error envelope parsing,
+ * Cloudflare block detection, status-specific hints and the typed
+ * `BoondApiError`. Pure functions — nothing here touches the network.
+ */
+import { oauthContext } from "../oauth.js";
+/**
+ * Pull the human-readable bits out of a BoondManager error body.
+ *
+ * Boond returns JSON:API errors of the form:
+ *   { "errors": [ { "status": "422", "code": "422", "detail": "...", "title": "..." } ] }
+ *
+ * Surfacing `detail` (and `title` when present) gives the model a focused
+ * message like `422 - password mismatch` instead of the full ~500-char body
+ * dump that previously made it hard for the LLM to reason about the failure.
+ *
+ * Exported for unit testing.
+ */
+export function parseBoondErrorBody(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const errors = Array.isArray(parsed.errors) ? parsed.errors : [];
+        const messages = errors
+            .map((e) => {
+            const parts = [];
+            if (e.title && e.title !== e.detail)
+                parts.push(e.title);
+            if (e.detail)
+                parts.push(e.detail);
+            else if (e.code)
+                parts.push(`code ${e.code}`);
+            // Boond's JSON:API errors put the offending query/body field in
+            // source.parameter (or source.pointer). Surfacing it turns the
+            // otherwise-opaque "1017 - Missing required attribute" into
+            // "1017 - Missing required attribute (parameter: startMonth)".
+            const ref = e.source?.parameter ?? e.source?.pointer;
+            const head = parts.join(": ").trim();
+            if (!head)
+                return ref ? `parameter: ${ref}` : "";
+            return ref ? `${head} (parameter: ${ref})` : head;
+        })
+            .filter((m) => m.length > 0);
+        if (messages.length === 0)
+            return null;
+        return messages.join(" | ");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a caller can do about a BoondManager 401, which depends on who holds
+ * the credentials (issue #234). Under the HTTP OAuth transport the token
+ * belongs to the MCP client, and the only remedy is a new authorization —
+ * there is no CLI to re-run (the historical hint named one that is no longer
+ * shipped). With env credentials it is the operator's configuration.
+ */
+export function hintForUnauthorized() {
+    if (oauthContext.getStore()) {
+        return ("The BoondManager access token was rejected (expired or revoked). Re-authorize the connector from the MCP client. " +
+            'With MCP_HTTP_VALIDATE_TOKEN=true the server answers the next request with HTTP 401 + `error="invalid_token"`, ' +
+            "which makes spec-compliant clients restart the OAuth flow on their own; otherwise disconnect and reconnect the server in the client.");
+    }
+    return "Authentication failed. Verify BOOND_USER_TOKEN + BOOND_CLIENT_TOKEN + BOOND_CLIENT_KEY (or BOOND_API_TOKEN, or BOOND_USER + BOOND_PASSWORD).";
+}
+/**
+ * A non-2xx answer from BoondManager, with the status kept as data so callers
+ * (the HTTP transport's token validation, #234) can branch on it instead of
+ * parsing the message. The message is unchanged from the plain `Error` this
+ * replaces — `formatApiError()` output.
+ */
+export class BoondApiError extends Error {
+    status;
+    method;
+    path;
+    constructor(message, status, method, path) {
+        super(message);
+        this.name = "BoondApiError";
+        this.status = status;
+        this.method = method;
+        this.path = path;
+    }
+}
+/** Status-specific hint to help the LLM (or human) recover from common failures. */
+function hintForStatus(status) {
+    switch (status) {
+        case 400:
+            return "Check the request body or query parameters — likely a malformed field.";
+        case 401:
+            return hintForUnauthorized();
+        case 403:
+            return "Authenticated, but the user lacks permission for this endpoint or scope.";
+        case 404:
+            return "Endpoint or entity not found. Double-check the id and the API path.";
+        case 422:
+            return "Unprocessable: typically wrong credentials (the API returns 422 for password mismatch) or a query parameter the API rejects.";
+        case 429:
+            return "Rate-limited. Back off and retry after a few seconds.";
+        default:
+            if (status >= 500)
+                return "BoondManager-side error. Retrying after a short delay usually helps.";
+            return "Check your credentials and permissions for this endpoint.";
+    }
+}
+/**
+ * Detect whether the response body looks like a Cloudflare WAF challenge or
+ * block page rather than a BoondManager JSON:API response. When this is true,
+ * the upstream service is unreachable and the JSON:API hint above is
+ * misleading — the request never reached BoondManager.
+ */
+function containsCloudflareChallengeHost(htmlSnippet) {
+    const urlMatches = htmlSnippet.match(/https?:\/\/[^\s"'<>]+/gi) ?? [];
+    for (const rawUrl of urlMatches) {
+        try {
+            const hostname = new URL(rawUrl).hostname.toLowerCase();
+            if (hostname === "challenges.cloudflare.com" || hostname.endsWith(".challenges.cloudflare.com")) {
+                return true;
+            }
+        }
+        catch {
+            // Ignore unparsable URL fragments in HTML.
+        }
+    }
+    return false;
+}
+function looksLikeCloudflareBlock(body) {
+    if (!body)
+        return false;
+    const head = body.slice(0, 1000).toLowerCase();
+    if (!head.includes("<!doctype html") && !head.includes("<html"))
+        return false;
+    return (head.includes("cloudflare") ||
+        head.includes("attention required") ||
+        head.includes("just a moment") ||
+        head.includes("cf-ray") ||
+        containsCloudflareChallengeHost(head));
+}
+/** Build the Error message for a non-2xx HTTP response. Exported for testing. */
+export function formatApiError(status, statusText, method, path, body) {
+    const detail = parseBoondErrorBody(body);
+    const cloudflareBlocked = looksLikeCloudflareBlock(body);
+    const headline = cloudflareBlocked
+        ? `BoondManager API ${status} ${statusText} — request blocked by Cloudflare WAF before reaching the API`
+        : detail
+            ? `BoondManager API ${status} ${statusText}: ${detail}`
+            : `BoondManager API ${status} ${statusText}`;
+    const lines = [headline, `Endpoint: ${method} ${path}`];
+    // Only attach the raw body when we couldn't extract a structured detail
+    // and we don't already know it's a Cloudflare HTML page — in either case
+    // the raw HTML/error chunk just buries the useful message.
+    if (!detail && !cloudflareBlocked && body) {
+        const trimmed = body.length > 500 ? body.slice(0, 500) + "…" : body;
+        lines.push(`Body: ${trimmed}`);
+    }
+    if (cloudflareBlocked) {
+        lines.push("Hint: The BoondManager edge (Cloudflare) blocked this request. " +
+            "This often means the endpoint is restricted on this tenant, or you've made too many calls in a short window. " +
+            "Wait a few seconds and retry; if it persists, the endpoint is not enabled for this account.");
+    }
+    else {
+        lines.push(`Hint: ${hintForStatus(status)}`);
+    }
+    return lines.join("\n");
+}
+/** The error every helper raises when an attempt never completed within `BOOND_HTTP_TIMEOUT_MS`. */
+export function timeoutError(timeoutMs, method, path, cause) {
+    return new Error([
+        `BoondManager API request timed out after ${timeoutMs}ms`,
+        `Endpoint: ${method} ${path}`,
+        "Hint: Increase BOOND_HTTP_TIMEOUT_MS or check connectivity to the BoondManager API.",
+    ].join("\n"), { cause });
+}
+/**
+ * A 2xx whose body is not JSON. Before #239 this surfaced as a bare
+ * `SyntaxError: Unexpected token '<'` with no endpoint — indistinguishable
+ * from a bug in the server — although it almost always means the request hit
+ * the application shell or a WAF page rather than the API.
+ */
+export function nonJsonResponseError(status, method, path, cause) {
+    return new Error([
+        `BoondManager API answered HTTP ${status} with a body that is not JSON.`,
+        `Endpoint: ${method} ${path}`,
+        "Hint: The response is probably an HTML page (application shell, Cloudflare challenge). Check the path and the tenant's access to this endpoint.",
+    ].join("\n"), { cause });
+}
+//# sourceMappingURL=errors.js.map

package/dist/services/http/errors.js.map

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

package/dist/services/http/rate-limit.d.ts

@@ -0,0 +1,40 @@
+import { TokenBucket } from "../rate-limiter.js";
+export interface RateLimitConfig {
+    rps: number;
+    burst: number;
+}
+/**
+ * Read rate-limit env vars. `rps` of 0 (or non-numeric) disables rate
+ * limiting entirely. `burst` falls back to `rps * 2` when unset, mirroring
+ * the documented default behaviour. Exported for unit testing.
+ */
+export declare function resolveRateLimitConfig(): RateLimitConfig | null;
+/**
+ * Upper bound on live per-identity buckets. A bucket is a few numbers, so
+ * 500 idle users cost nothing measurable; the cap exists so an attacker
+ * cycling tokens cannot grow the map without bound. Eviction is LRU: an
+ * evicted identity simply starts again with a full bucket.
+ */
+export declare const MAX_RATE_LIMIT_BUCKETS = 500;
+/**
+ * The token bucket for the *current* caller (issue #232).
+ *
+ * One bucket per process was right for stdio (one user) and wrong for the
+ * HTTP OAuth transport, where every request may belong to a different user:
+ * a single client's burst throttled everyone else, and one buggy client
+ * could hold the whole deployment at the rate limit. Buckets are keyed by
+ * `currentAuthIdentity()` — `sha256(token)` in OAuth, the constant `env`
+ * identity on stdio / static auth, so those keep exactly one bucket.
+ *
+ * Note this is fairness *between* users of the same server, not a change to
+ * the ceiling BoondManager sees: `BOOND_HTTP_RATE_LIMIT_RPS` is per identity.
+ */
+export declare function getRateLimiter(): TokenBucket | null;
+/** Number of live per-identity buckets. Exposed for tests. */
+export declare function rateLimiterBucketCountForTests(): number;
+/**
+ * Reset the rate limiters so the next request re-reads env vars.
+ * Intended for tests that toggle `BOOND_HTTP_RATE_LIMIT_*` between cases.
+ */
+export declare function resetRateLimiterForTests(): void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/services/http/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/services/http/rate-limit.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CAa/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAO1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAqBnD;AAED,8DAA8D;AAC9D,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAI/C"}

package/dist/services/http/rate-limit.js

@@ -0,0 +1,92 @@
+/**
+ * Client-side rate limiting towards BoondManager: one token bucket per caller
+ * identity (issue #232), LRU-bounded. The bucket itself is `TokenBucket` in
+ * `services/rate-limiter.ts`; this module owns the configuration and the map.
+ */
+import { readString } from "../../config/env.js";
+import { DEFAULT_HTTP_RATE_LIMIT_BURST, DEFAULT_HTTP_RATE_LIMIT_RPS } from "../../constants.js";
+import { currentAuthIdentity } from "../oauth.js";
+import { TokenBucket } from "../rate-limiter.js";
+/**
+ * Read rate-limit env vars. `rps` of 0 (or non-numeric) disables rate
+ * limiting entirely. `burst` falls back to `rps * 2` when unset, mirroring
+ * the documented default behaviour. Exported for unit testing.
+ */
+export function resolveRateLimitConfig() {
+    const rpsRaw = readString("BOOND_HTTP_RATE_LIMIT_RPS");
+    const rps = rpsRaw === undefined ? DEFAULT_HTTP_RATE_LIMIT_RPS : Number(rpsRaw);
+    if (!Number.isFinite(rps) || rps <= 0)
+        return null;
+    const burstRaw = readString("BOOND_HTTP_RATE_LIMIT_BURST");
+    let burst;
+    if (burstRaw === undefined) {
+        burst = rpsRaw === undefined ? DEFAULT_HTTP_RATE_LIMIT_BURST : Math.max(1, Math.ceil(rps));
+    }
+    else {
+        const parsed = Number(burstRaw);
+        burst = Number.isFinite(parsed) && parsed >= 1 ? Math.floor(parsed) : Math.max(1, Math.ceil(rps));
+    }
+    return { rps, burst };
+}
+/**
+ * Upper bound on live per-identity buckets. A bucket is a few numbers, so
+ * 500 idle users cost nothing measurable; the cap exists so an attacker
+ * cycling tokens cannot grow the map without bound. Eviction is LRU: an
+ * evicted identity simply starts again with a full bucket.
+ */
+export const MAX_RATE_LIMIT_BUCKETS = 500;
+let rateLimitConfig = null;
+let rateLimitConfigResolved = false;
+/** Insertion-ordered map used as an LRU: a hit re-inserts, an insert past the cap evicts the oldest. */
+const rateLimiters = new Map();
+/**
+ * The token bucket for the *current* caller (issue #232).
+ *
+ * One bucket per process was right for stdio (one user) and wrong for the
+ * HTTP OAuth transport, where every request may belong to a different user:
+ * a single client's burst throttled everyone else, and one buggy client
+ * could hold the whole deployment at the rate limit. Buckets are keyed by
+ * `currentAuthIdentity()` — `sha256(token)` in OAuth, the constant `env`
+ * identity on stdio / static auth, so those keep exactly one bucket.
+ *
+ * Note this is fairness *between* users of the same server, not a change to
+ * the ceiling BoondManager sees: `BOOND_HTTP_RATE_LIMIT_RPS` is per identity.
+ */
+export function getRateLimiter() {
+    if (!rateLimitConfigResolved) {
+        rateLimitConfig = resolveRateLimitConfig();
+        rateLimitConfigResolved = true;
+    }
+    if (!rateLimitConfig)
+        return null;
+    const key = currentAuthIdentity();
+    const existing = rateLimiters.get(key);
+    if (existing) {
+        rateLimiters.delete(key);
+        rateLimiters.set(key, existing);
+        return existing;
+    }
+    const bucket = new TokenBucket(rateLimitConfig.burst, rateLimitConfig.rps);
+    rateLimiters.set(key, bucket);
+    while (rateLimiters.size > MAX_RATE_LIMIT_BUCKETS) {
+        const oldest = rateLimiters.keys().next().value;
+        if (oldest === undefined)
+            break;
+        rateLimiters.delete(oldest);
+    }
+    return bucket;
+}
+/** Number of live per-identity buckets. Exposed for tests. */
+export function rateLimiterBucketCountForTests() {
+    return rateLimiters.size;
+}
+/**
+ * Reset the rate limiters so the next request re-reads env vars.
+ * Intended for tests that toggle `BOOND_HTTP_RATE_LIMIT_*` between cases.
+ */
+export function resetRateLimiterForTests() {
+    rateLimiters.clear();
+    rateLimitConfig = null;
+    rateLimitConfigResolved = false;
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/services/http/rate-limit.js.map

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

package/dist/services/http/retry.d.ts

@@ -0,0 +1,46 @@
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+/** Resolve retry configuration from env, with safe fallbacks. Exported for tests. */
+export declare function resolveRetryConfig(): RetryConfig;
+/**
+ * Decide whether a failed attempt is worth retrying.
+ *
+ * Retry policy is intentionally conservative for non-idempotent verbs to avoid
+ * silently duplicating writes when the server's response was lost or delayed:
+ *   - 429 (Too Many Requests) is always retried — the server explicitly
+ *     rejected the request before processing it, so it is safe regardless of
+ *     verb.
+ *   - For GET only, 5xx responses, network failures, and timeouts are retried
+ *     because GET is idempotent.
+ *   - 4xx responses (other than 429) are never retried — the client must change
+ *     the request before another attempt makes sense.
+ *
+ * Exported for unit testing.
+ */
+export declare function isRetryable(method: string, status: number | undefined, isNetworkOrTimeout: boolean): boolean;
+/**
+ * Parse a `Retry-After` header value into milliseconds.
+ *
+ * Accepts either a non-negative number of seconds or an HTTP-date. Returns
+ * null when the value is absent or unparseable. Negative computed delays are
+ * clamped to 0. Exported for unit testing.
+ */
+export declare function parseRetryAfter(value: string | null, now?: number): number | null;
+/**
+ * Compute the next backoff delay using full jitter:
+ *   delay = random(0, min(maxMs, baseMs * 2^attempt))
+ *
+ * Full jitter (vs. exponential-only) reduces thundering-herd risk when many
+ * clients retry in lockstep. Exported for unit testing.
+ */
+export declare function computeBackoffMs(attempt: number, baseMs: number, maxMs: number, random?: () => number): number;
+/**
+ * Backoff sleep. With a `signal`, the wait ends the moment it fires — a
+ * cancelled caller does not sit out a 5 s `Retry-After` (issue #231); the
+ * rejection carries the signal's reason.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/services/http/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/services/http/retry.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,IAAI,WAAW,CAMhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,kBAAkB,EAAE,OAAO,GAAG,OAAO,CAM5G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAc7F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAIR;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrE"}