boondmanager-mcp-server 2.15.2 → 2.17.0

package/dist/services/boond-client.d.ts

@@ -1,215 +1,31 @@
-import type { BoondAuthProvider, JsonApiResource, JsonApiResponse, SearchParams } from "../types.js";
-import type { ProgressReporter } from "./progress.js";
 /**
- * Auth provider for the HTTP transport: reads the Bearer token from the
- * per-request AsyncLocalStorage populated by the transport layer and
- * forwards it verbatim to BoondManager as `Authorization: Bearer …`.
- *
- * Errors out clearly if called outside a request context — which would
- * indicate that the transport layer forgot to wrap the request in
- * `oauthContext.run(...)`.
- */
-export declare const oauthContextAuth: BoondAuthProvider;
-/**
- * Build the BoondManager HS256 JWT. By default the payload is exactly
- * `{ userToken, clientToken }` (BoondManager's documented scheme). When
- * `expiresInSeconds` is provided, standard `iat`/`exp` claims are added so the
- * generated token is no longer replayable forever if it leaks — this requires
- * regenerating the token per request (see `jwtAuth`). Opt-in because not every
- * BoondManager deployment is known to honour `exp`.
- */
-export declare function buildJwt(userToken: string, clientToken: string, clientKey: string, options?: {
-    expiresInSeconds?: number;
-    nowSeconds?: number;
-}): string;
-export declare const JWT_HEADER_NAME = "X-Jwt-Client-Boondmanager";
-export declare function initClient(): void;
-/**
- * True when env-based credentials (JWT components, API token, or BasicAuth) are
- * configured. Used by the HTTP transport to decide whether static-auth mode is
- * possible without attempting a full `initClient()` call.
- */
-export declare function hasEnvCredentials(): boolean;
-/**
- * Install a custom auth provider — used by the HTTP transport bootstrap to
- * wire in an OAuth2 token source (where the access token is refreshed
- * transparently per request rather than baked in at startup).
- */
-export declare function initClientWithAuth(auth: BoondAuthProvider, baseUrl?: string): void;
-/** Test helper — reset the cached config so the next call re-initialises. */
-export declare function resetClientForTests(): void;
-export type QueryValue = string | number | Array<string | number> | undefined;
-/**
- * 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;
-/**
- * Resolve the per-request HTTP timeout in milliseconds.
- *
- * Reads BOOND_HTTP_TIMEOUT_MS at call time so tests / runtime overrides take
- * effect without restarting the process. Falls back to the default for
- * unset, non-numeric, or non-positive values.
- *
- * Exported for unit testing.
- */
-export declare function resolveTimeoutMs(): number;
-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;
-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;
-/**
- * Reset the cached rate limiter so the next request re-reads env vars.
- * Intended for tests that toggle `BOOND_HTTP_RATE_LIMIT_*` between cases.
- */
-export declare function resetRateLimiterForTests(): void;
-/** 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;
-/**
- * Defense-in-depth against path traversal / query injection through entity
- * ids interpolated into API paths at ~40 call sites. Even though the id
- * schemas are now numeric-only, a future tool could forget to validate, so we
- * assert here that the path is well-formed: it must start with `/`, carry no
- * query (`?`) or fragment (`#`) — those arrive via `queryParams`, never the
- * path — and contain no traversal (`..`) or percent/backslash escapes. Built
- * paths only ever combine static segments with numeric ids and hyphenated tab
- * names, so this rejects nothing legitimate. Exported for unit testing.
- */
-export declare function assertSafeApiPath(path: string): void;
-/**
- * Validates `path` and resolves it against `baseUrl`, returning the
- * constructed URL. Throws if the path is unsafe (see `assertSafeApiPath`) or
- * if the resolved URL escapes the configured API base origin/path. Centralises
- * the guard shared by apiRequest / apiDownload / apiUploadForm. Exported for
- * unit testing.
- */
-export declare function resolveApiUrl(baseUrl: string, path: string): URL;
-export declare function apiRequest(path: string, method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", body?: unknown, queryParams?: Record<string, QueryValue>): Promise<JsonApiResponse>;
-/**
- * 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 declare function parseContentDispositionFilename(header: string | null): string | undefined;
-export interface DownloadedDocument {
-    data: Buffer;
-    contentType: string;
-    filename?: string;
-}
-/**
- * Download a binary payload (documents, justificatifs…) from the BoondManager
- * API. Same auth/safety/rate-limit plumbing as `apiRequest`, but the body is
- * returned raw instead of being parsed as JSON:API. Single attempt: document
- * downloads are interactive one-offs, not worth a retry loop.
- *
- * `onProgress` reports bytes received when the client asked for progress and
- * the response carries a `Content-Length`; otherwise nothing is emitted.
- */
-export declare function apiDownload(path: string, onProgress?: ProgressReporter): Promise<DownloadedDocument>;
-/**
- * POST a multipart/form-data payload to the BoondManager API (document
- * upload). Form values are simple string fields — the file itself travels by
- * reference via the `fileUrl` field (Boond downloads it server-side), so the
- * MCP server never buffers file bytes.
- */
-export declare function apiUploadForm(path: string, fields: Record<string, string>): Promise<JsonApiResponse>;
-export declare function buildSearchQuery(params: SearchParams): Record<string, QueryValue>;
-/**
- * Search wrapper around `apiRequest` that enforces BoondManager's per-route
- * `maxResults` ceiling (see `ROUTE_MAX_RESULTS`). When the caller requests more
- * results than the route allows, the request is transparently split into
- * chunks of `cap` records and the pages are merged into a single JSON:API
- * response — the caller still receives the full page, but BoondManager never
- * sees `maxResults` above the cap (which overflows memory on `/actions`).
- *
- * Routes whose ceiling already covers the requested page size take the fast
- * path: a single `apiRequest`, byte-for-byte identical to calling it directly.
- * The chunk count is bounded by `ceil((offset + requested) / cap)`, so there is
- * no unbounded loop; the loop also stops early once a page comes back short
- * (end of the result set on the server).
- *
- * `onProgress` (optional, last position — no existing caller had to change) is
- * invoked **only on the chunked path**: one step per BoondManager page. The
- * fast path stays silent on purpose — a single API call has nothing to report
- * and a "1/1" notification would be pure noise. The reporter is a no-op unless
- * the client sent a `progressToken` (see `services/progress.ts`).
- */
-export declare function apiSearch(path: string, query: Record<string, QueryValue>, onProgress?: ProgressReporter): Promise<JsonApiResponse>;
-export declare function formatEntitySummary(entity: unknown): string;
-export declare function formatListResponse(response: JsonApiResponse, entityType: string, fields?: string[]): string;
-/**
- * Formate la réponse d'un endpoint d'onglet (ex: /resources/{id}/positionings).
- * Contrairement à formatDetailResponse, un tableau est restitué en entier :
- * certains onglets renvoient plusieurs entités (positionnements, contacts...)
- * et n'afficher que la première masquait les autres.
- */
-export declare function formatTabResponse(response: JsonApiResponse): string;
-/**
- * The canonical shape of a single entity as this server hands it to the model:
- * the JSON:API resource minus the envelope noise (`links`, `meta`).
- *
- * Extracted from `formatDetailResponse` so the entity resource templates
- * (`boond://candidate/{id}`) aggregate the *same* projection instead of
- * defining a second, drifting idea of what an entity looks like. They cannot
- * reuse `formatDetailResponse` itself: it renders one entity and truncates
- * mid-string at `CHARACTER_LIMIT`, which on pretty-printed JSON yields an
- * unparseable body — acceptable for a tool's text content, not for a resource
- * whose whole point is to be read as JSON.
- */
-export declare function projectEntity(entity: JsonApiResource): Pick<JsonApiResource, "id" | "type" | "attributes" | "relationships">;
-export declare function formatDetailResponse(response: JsonApiResponse): string;
+ * BoondManager client — public surface.
+ *
+ * This module is a barrel: the 38 tool files, the transports and the
+ * resources import from here, and the tests mock this path
+ * (`vi.mock("../services/boond-client.js", …)`). The implementation lives in
+ * one module per responsibility (issue #239):
+ *
+ *   http/auth.ts        who the request is sent as (JWT / static / OAuth), config
+ *   http/errors.ts      error envelope parsing, Cloudflare detection, hints, BoondApiError
+ *   http/retry.ts       retry policy: config, retryability, Retry-After, backoff
+ *   http/rate-limit.ts  per-identity token buckets
+ *   http/transport.ts   the single `send()` path + apiRequest / apiUploadForm
+ *   http/download.ts    apiDownload: streaming under a byte cap, progress, guards
+ *   search.ts           buildSearchQuery + apiSearch (per-route chunking)
+ *   format/*.ts         list / detail / tab rendering, summaries, HTML excerpts
+ *
+ * Add a new export here when a tool needs it; do not add implementation.
+ */
+export { oauthContextAuth, buildJwt, JWT_HEADER_NAME, initClient, hasEnvCredentials, initClientWithAuth, resetClientForTests, } from "./http/auth.js";
+export { parseBoondErrorBody, hintForUnauthorized, BoondApiError, formatApiError } from "./http/errors.js";
+export { type RetryConfig, resolveRetryConfig, isRetryable, parseRetryAfter, computeBackoffMs } from "./http/retry.js";
+export { type RateLimitConfig, resolveRateLimitConfig, MAX_RATE_LIMIT_BUCKETS, getRateLimiter, rateLimiterBucketCountForTests, resetRateLimiterForTests, } from "./http/rate-limit.js";
+export { type QueryValue, type HttpMethod, resolveTimeoutMs, assertSafeApiPath, resolveApiUrl, apiRequest, apiUploadForm, } from "./http/transport.js";
+export { parseContentDispositionFilename, type DownloadedDocument, DownloadTooLargeError, type DownloadOptions, apiDownload, } from "./http/download.js";
+export { buildSearchQuery, apiSearch } from "./search.js";
+export { formatEntitySummary } from "./format/summary.js";
+export { formatListResponse } from "./format/list.js";
+export { projectEntity, formatDetailResponse } from "./format/detail.js";
+export { formatTabResponse } from "./format/tab.js";
 //# sourceMappingURL=boond-client.d.ts.map

package/dist/services/boond-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boond-client.d.ts","sourceRoot":"","sources":["../../src/services/boond-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"boond-client.d.ts","sourceRoot":"","sources":["../../src/services/boond-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3G,OAAO,EAAE,KAAK,WAAW,EAAE,kBAAkB,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvH,OAAO,EACL,KAAK,eAAe,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,8BAA8B,EAC9B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,+BAA+B,EAC/B,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,KAAK,eAAe,EACpB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}