boondmanager-mcp-server 2.15.2 → 2.17.0

package/dist/services/logger.js

@@ -1,10 +1,12 @@
 import pino from "pino";
+import { readString } from "../config/env.js";
 import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
 /**
  * Redaction paths for the structured logger. Defence-in-depth: nothing in the
  * codebase currently logs auth material, but if a request/error object that
  * carries credentials is ever passed to the logger, these paths censor it
- * before it reaches stdout / a log aggregator. Covers the BoondManager JWT
+ * before it reaches stderr / a log aggregator. Covers the BoondManager JWT
  * header, OAuth Bearer headers, and raw access tokens at one level of nesting.
  */
 export const REDACT_PATHS = [
@@ -20,42 +22,101 @@ export const REDACT_PATHS = [
     "accessToken",
     "*.accessToken",
 ];
+/**
+ * File descriptor every log line is written to: **stderr, on every transport**.
+ *
+ * On the stdio transport stdout *is* the JSON-RPC channel — anything that is
+ * not an MCP message corrupts the stream and the client drops the connection.
+ * Pino defaults to fd 1, and so does the pino-pretty transport when no
+ * `destination` is given, which is exactly how the "Access policy active"
+ * line, the update notice and the dictionary-override warnings used to land in
+ * the middle of the protocol (issue #225). stderr is what Claude Desktop
+ * captures into its log viewer, and it is equally fine for the HTTP transport,
+ * so there is one destination rather than one per transport.
+ */
+export const LOG_DESTINATION_FD = 2;
+const VALID_LEVELS = ["trace", "debug", "info", "warn", "error", "fatal"];
 /**
  * Read the log level from env, falling back to 'info' for production-friendly
  * defaults. DEBUG / trace logs are useful during development but too noisy
  * in production. Pino's level hierarchy: trace < debug < info < warn < error < fatal.
  */
-function resolveLogLevel() {
-    const raw = process.env.LOG_LEVEL?.toLowerCase();
-    const valid = ["trace", "debug", "info", "warn", "error", "fatal"];
-    if (raw && valid.includes(raw))
+export function resolveLogLevel(env = process.env) {
+    const raw = readString("LOG_LEVEL", env)?.trim().toLowerCase();
+    if (raw && VALID_LEVELS.includes(raw))
         return raw;
     return "info";
 }
+/** Human-readable (pretty) output in dev, JSON in prod. Override via LOG_FORMAT. */
+export function usePrettyOutput(env = process.env) {
+    return readString("LOG_FORMAT", env)?.trim() !== "json" && readString("NODE_ENV", env)?.trim() !== "production";
+}
+/**
+ * `pino-pretty` is a **devDependency** (issue #246): it only serves the
+ * human-readable output of a development shell, and the `.mcpb` bundle and
+ * the Docker image are built with `--omit=dev`. Pino loads a transport by
+ * module name in a worker thread and throws at logger creation when the
+ * target is missing, so the pretty branch is taken only when the module
+ * resolves — otherwise the logger silently falls back to JSON on stderr,
+ * which is the production shape anyway.
+ */
+export function isPrettyTransportAvailable() {
+    try {
+        createRequire(import.meta.url).resolve("pino-pretty");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The two shapes the logger can take, as data — so a test can assert where each
+ * one writes without spawning a process. Pino refuses a stream argument when
+ * `transport` is set (the transport runs in a worker thread), which is why the
+ * destination travels inside the pino-pretty options on one branch and as a
+ * `pino.destination()` on the other.
+ */
+export function resolveLoggerConfig(env = process.env, prettyAvailable = isPrettyTransportAvailable()) {
+    const base = {
+        level: resolveLogLevel(env),
+        redact: { paths: REDACT_PATHS, censor: "[Redacted]" },
+    };
+    if (usePrettyOutput(env) && prettyAvailable) {
+        return {
+            format: "pretty",
+            options: {
+                ...base,
+                transport: {
+                    target: "pino-pretty",
+                    options: {
+                        colorize: true,
+                        translateTime: "SYS:standard",
+                        ignore: "pid,hostname",
+                        destination: LOG_DESTINATION_FD,
+                    },
+                },
+            },
+        };
+    }
+    return { format: "json", options: base, destinationFd: LOG_DESTINATION_FD };
+}
+export function createLogger(env = process.env) {
+    const config = resolveLoggerConfig(env);
+    if (config.format === "pretty")
+        return pino(config.options);
+    return pino(config.options, pino.destination(config.destinationFd));
+}
 /**
  * Centralized structured logger. Use this instead of console.log/error for
  * all application logging — it provides timestamps, levels, and JSON output
- * (when LOG_FORMAT=json) that plays nicely with log aggregators.
+ * (when LOG_FORMAT=json) that plays nicely with log aggregators. It always
+ * writes to stderr (see `LOG_DESTINATION_FD`).
  *
  * Example:
  *   logger.info({ sessionId: "abc", userId: 123 }, "Session initialized");
  *   logger.error({ err, endpoint: "/mcp" }, "HTTP transport error");
  */
-export const logger = pino({
-    level: resolveLogLevel(),
-    redact: { paths: REDACT_PATHS, censor: "[Redacted]" },
-    // Human-readable (pretty) output in dev, JSON in prod. Override via LOG_FORMAT.
-    transport: process.env.LOG_FORMAT === "json" || process.env.NODE_ENV === "production"
-        ? undefined
-        : {
-            target: "pino-pretty",
-            options: {
-                colorize: true,
-                translateTime: "SYS:standard",
-                ignore: "pid,hostname",
-            },
-        },
-});
+export const logger = createLogger();
 /**
  * Generate a short correlation ID (8 hex chars) for tracing a single request
  * through the stack (HTTP handler → tool call → API request). Attach it to

package/dist/services/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;IACvB,2BAA2B;IAC3B,2BAA2B;IAC3B,sCAAsC;IACtC,0CAA0C;IAC1C,aAAa;IACb,eAAe;CAChB,CAAC;AAEF;;;;GAIG;AACH,SAAS,eAAe;IACtB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,CAAC;IACjD,MAAM,KAAK,GAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACjF,IAAI,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAiB,CAAC;QAAE,OAAO,GAAiB,CAAC;IACvE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,eAAe,EAAE;IACxB,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE;IACrD,gFAAgF;IAChF,SAAS,EACP,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QACxE,CAAC,CAAC,SAAS;QACX,CAAC,CAAC;YACE,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE;gBACP,QAAQ,EAAE,IAAI;gBACd,aAAa,EAAE,cAAc;gBAC7B,MAAM,EAAE,cAAc;aACvB;SACF;CACR,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,qEAAqE;IACrE,wEAAwE;IACxE,uDAAuD;IACvD,OAAO,UAAU,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"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"}

package/dist/services/oauth.d.ts

@@ -32,6 +32,18 @@ export interface OAuthRequestContext {
  * on env-var credentials.
  */
 export declare const oauthContext: AsyncLocalStorage<OAuthRequestContext>;
+/**
+ * Identity of the caller, as far as this process can tell — the key every
+ * per-user structure is partitioned on (dictionary cache #226, rate-limit
+ * buckets and session ownership #232).
+ *
+ * - OAuth (HTTP transport): the request's Bearer token, hashed so the raw
+ *   credential never sits in a long-lived structure. Two users of the same
+ *   tenant get two identities — the price of not decoding an opaque token.
+ * - Everything else (stdio, HTTP static auth): the credentials are process
+ *   wide, so a single constant identity is exact.
+ */
+export declare function currentAuthIdentity(): string;
 /**
  * Extract a Bearer token from an HTTP `Authorization` header.
  * Returns `null` for missing, malformed, or non-Bearer auth schemes.

package/dist/services/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/services/oauth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,wCAA+C,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAevF;AAED,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAE1E,MAAM,WAAW,gCAAgC;IAC/C,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,gCAAgC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU9G;AAQD;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAIlD"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/services/oauth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,wCAA+C,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAevF;AAED,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAE1E,MAAM,WAAW,gCAAgC;IAC/C,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,gCAAgC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU9G;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAIlD"}

package/dist/services/oauth.js

@@ -1,4 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { readString, readUrl } from "../config/env.js";
+import { createHash } from "node:crypto";
 /**
  * Per-request context, populated by the HTTP transport before dispatching
  * to the MCP SDK and read by `oauthContextAuth` (boond-client) when an API
@@ -6,6 +8,23 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * on env-var credentials.
  */
 export const oauthContext = new AsyncLocalStorage();
+/**
+ * Identity of the caller, as far as this process can tell — the key every
+ * per-user structure is partitioned on (dictionary cache #226, rate-limit
+ * buckets and session ownership #232).
+ *
+ * - OAuth (HTTP transport): the request's Bearer token, hashed so the raw
+ *   credential never sits in a long-lived structure. Two users of the same
+ *   tenant get two identities — the price of not decoding an opaque token.
+ * - Everything else (stdio, HTTP static auth): the credentials are process
+ *   wide, so a single constant identity is exact.
+ */
+export function currentAuthIdentity() {
+    const ctx = oauthContext.getStore();
+    if (!ctx)
+        return "env";
+    return `oauth:${createHash("sha256").update(ctx.accessToken).digest("hex")}`;
+}
 /**
  * Extract a Bearer token from an HTTP `Authorization` header.
  * Returns `null` for missing, malformed, or non-Bearer auth schemes.
@@ -57,26 +76,20 @@ export function buildProtectedResourceMetadata(opts) {
     }
     return doc;
 }
-function envOrUndefined(key) {
-    const v = process.env[key];
-    if (!v || v.startsWith("${"))
-        return undefined;
-    return v;
-}
 /**
  * Resolve the authorization server URL surfaced in the discovery metadata.
  * Configurable so dedicated BoondManager instances (custom hostnames) can
  * advertise the right issuer.
  */
 export function resolveAuthorizationServer() {
-    return envOrUndefined("BOOND_OAUTH_AUTHORIZATION_SERVER") ?? DEFAULT_AUTHORIZATION_SERVER;
+    return readUrl("BOOND_OAUTH_AUTHORIZATION_SERVER") ?? DEFAULT_AUTHORIZATION_SERVER;
 }
 /**
  * Optional scope list advertised in the discovery metadata. Lets the MCP
  * client request appropriate scopes when initiating the OAuth flow.
  */
 export function resolveAdvertisedScopes() {
-    const raw = envOrUndefined("BOOND_OAUTH_SCOPES");
+    const raw = readString("BOOND_OAUTH_SCOPES");
     if (!raw)
         return [];
     return raw.split(/[\s,]+/).filter((s) => s.length > 0);

package/dist/services/oauth.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../../src/services/oauth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA8BrD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAuB,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAqC;IACtE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,yEAAyE;IACzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAChE,yEAAyE;IACzE,qEAAqE;IACrE,kEAAkE;IAClE,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,GAAG,KAAK,IAAI,CAAC,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAChE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED,gEAAgE;AAChE,MAAM,CAAC,MAAM,4BAA4B,GAAG,6BAA6B,CAAC;AAW1E;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAsC;IACnF,MAAM,GAAG,GAA4B;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,qBAAqB,EAAE,IAAI,CAAC,oBAAoB;QAChD,wBAAwB,EAAE,CAAC,QAAQ,CAAC;KACrC,CAAC;IACF,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,cAAc,CAAC,kCAAkC,CAAC,IAAI,4BAA4B,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,GAAG,GAAG,cAAc,CAAC,oBAAoB,CAAC,CAAC;IACjD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../../src/services/oauth.ts"],"names":[],"mappings":"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"}

package/dist/services/rate-limiter.d.ts

@@ -26,8 +26,15 @@ export declare class TokenBucket {
     private lastRefill;
     private chain;
     constructor(capacity: number, refillPerSec: number, clock?: Clock);
-    /** Wait until a token is available, then consume it. */
-    acquire(): Promise<void>;
+    /**
+     * Wait until a token is available, then consume it.
+     *
+     * `signal` (issue #231): a caller that has been cancelled must not sit in
+     * the queue — the promise rejects with the signal's reason at once if it
+     * has already fired, or as soon as it fires while waiting for a refill.
+     * The chain is not poisoned: the next acquirer proceeds normally.
+     */
+    acquire(signal?: AbortSignal): Promise<void>;
     /**
      * Number of currently-available tokens (after refill). Visible for tests
      * and observability; do not use for control flow.

package/dist/services/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/services/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,SAAS,EAAE,KAIvB,CAAC;AAEF,qBAAa,WAAW;aAMJ,QAAQ,EAAE,MAAM;aAChB,YAAY,EAAE,MAAM;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAoC;gBAG/B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACnB,KAAK,GAAE,KAAiB;IAQ3C,wDAAwD;IACxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASxB;;;OAGG;IACH,IAAI,IAAI,MAAM;YAKA,OAAO;IAWrB,OAAO,CAAC,MAAM;CAOf"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/services/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,SAAS,EAAE,KAGvB,CAAC;AAEF,qBAAa,WAAW;aAMJ,QAAQ,EAAE,MAAM;aAChB,YAAY,EAAE,MAAM;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAoC;gBAG/B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACnB,KAAK,GAAE,KAAiB;IAQ3C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5C;;;OAGG;IACH,IAAI,IAAI,MAAM;YAKA,OAAO;IAYrB,OAAO,CAAC,MAAM;CAOf"}

package/dist/services/rate-limiter.js

@@ -13,9 +13,10 @@
  *     the same token. The chain forces consume() to run one at a time, so the
  *     in-memory token count is always consistent.
  */
+import { abortPromise } from "./request-context.js";
 export const realClock = {
     now: () => Date.now(),
-    sleep: (ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)),
+    sleep: (ms) => (ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms))),
 };
 export class TokenBucket {
     capacity;
@@ -35,9 +36,18 @@ export class TokenBucket {
         this.tokens = capacity;
         this.lastRefill = clock.now();
     }
-    /** Wait until a token is available, then consume it. */
-    acquire() {
-        const next = this.chain.then(() => this.consume());
+    /**
+     * Wait until a token is available, then consume it.
+     *
+     * `signal` (issue #231): a caller that has been cancelled must not sit in
+     * the queue — the promise rejects with the signal's reason at once if it
+     * has already fired, or as soon as it fires while waiting for a refill.
+     * The chain is not poisoned: the next acquirer proceeds normally.
+     */
+    acquire(signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new Error("aborted"));
+        const next = this.chain.then(() => this.consume(signal));
         // Swallow the rejection on the chain itself so a single failing consume
         // (which shouldn't happen, but be defensive) does not poison every later
         // acquire. Callers still see their own promise resolve/reject normally.
@@ -52,12 +62,14 @@ export class TokenBucket {
         this.refill();
         return this.tokens;
     }
-    async consume() {
+    async consume(signal) {
         this.refill();
         while (this.tokens < 1) {
+            if (signal?.aborted)
+                throw signal.reason ?? new Error("aborted");
             const deficit = 1 - this.tokens;
             const waitMs = Math.max(1, Math.ceil((deficit / this.refillPerSec) * 1000));
-            await this.clock.sleep(waitMs);
+            await (signal ? Promise.race([this.clock.sleep(waitMs), abortPromise(signal)]) : this.clock.sleep(waitMs));
             this.refill();
         }
         this.tokens -= 1;

package/dist/services/rate-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/services/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CACZ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;CAClF,CAAC;AAEF,MAAM,OAAO,WAAW;IAMJ;IACA;IACC;IAPX,MAAM,CAAS;IACf,UAAU,CAAS;IACnB,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEjD,YACkB,QAAgB,EAChB,YAAoB,EACnB,QAAe,SAAS;QAFzB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,iBAAY,GAAZ,YAAY,CAAQ;QACnB,UAAK,GAAL,KAAK,CAAmB;QAEzC,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QAC1E,IAAI,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAClF,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;IAChC,CAAC;IAED,wDAAwD;IACxD,OAAO;QACL,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACnD,wEAAwE;QACxE,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;YAC5E,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACnB,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/D,IAAI,UAAU,KAAK,CAAC;YAAE,OAAO;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QACpF,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;CACF"}
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/services/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/services/request-context.d.ts

@@ -0,0 +1,47 @@
+export interface RequestContext {
+    /** Fires on `notifications/cancelled` or when the transport closes. */
+    signal?: AbortSignal;
+    /** Correlation id shared by every log line and forwarded as `X-Request-Id`. */
+    corrId?: string;
+    /** W3C `traceparent` header received from the client, forwarded verbatim. */
+    traceparent?: string;
+}
+/** Run `fn` with `context` as the current request's context (replaces any enclosing one). */
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+/** The context of the request being handled, if a handler is on the stack. */
+export declare function currentRequestContext(): RequestContext | undefined;
+/** Run `fn` with `signal` as the current request's cancellation signal; the rest of the context is kept. */
+export declare function runWithRequestSignal<T>(signal: AbortSignal | undefined, fn: () => T): T;
+/** Run `fn` with no cancellation signal, for work whose result other requests share. Correlation is kept. */
+export declare function withoutRequestSignal<T>(fn: () => T): T;
+/** The signal of the request being handled, if a handler is on the stack. */
+export declare function currentRequestSignal(): AbortSignal | undefined;
+/** The correlation id of the request being handled, if any. */
+export declare function currentCorrId(): string | undefined;
+/** Narrowing for the SDK's `extra`, typed `unknown` at every call site. */
+export declare function requestSignalFrom(extra: unknown): AbortSignal | undefined;
+/** Parse a `traceparent` value; `undefined` when absent or malformed. */
+export declare function parseTraceparent(value: unknown): {
+    header: string;
+    traceId: string;
+} | undefined;
+/** The `traceparent` the client put in the request's `_meta` (SEP-414), if valid. */
+export declare function traceparentFrom(extra: unknown): {
+    header: string;
+    traceId: string;
+} | undefined;
+/**
+ * Raised when the client cancelled the request. `name` is `AbortError` so it
+ * reads like every other abort in Node; the message names the endpoint the
+ * cancellation interrupted, which is what a log line needs.
+ */
+export declare class RequestCancelledError extends Error {
+    readonly method: string;
+    readonly path: string;
+    constructor(method: string, path: string, cause?: unknown);
+}
+/** Throw `RequestCancelledError` if `signal` has fired. Cheap — call it before every unit of work. */
+export declare function throwIfCancelled(signal: AbortSignal | undefined, method: string, path: string): void;
+/** A promise that rejects with the signal's reason the moment it fires (never resolves). */
+export declare function abortPromise(signal: AbortSignal): Promise<never>;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/services/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/services/request-context.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEhF;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAElE;AAED,4GAA4G;AAC5G,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAIvF;AAED,6GAA6G;AAC7G,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,WAAW,GAAG,SAAS,CAE9D;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAIzE;AAQD,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMhG;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK/F;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAS1D;AAED,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEpG;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAIhE"}

package/dist/services/request-context.js

@@ -0,0 +1,112 @@
+/**
+ * Per-request context: cancellation (issue #231) and correlation (issue #236).
+ *
+ * The SDK hands every handler an `extra.signal` — an `AbortSignal` fired by
+ * `notifications/cancelled` or by the transport closing. Before #231 nothing
+ * forwarded it: a chunked `/actions` search (up to 5 sequential calls), a
+ * reporting query of tens of seconds or a 5 MiB download ran to completion
+ * after the client had given up, spending rate-limit tokens and BoondManager
+ * quota on a result nobody would read.
+ *
+ * Rather than threading `signal` / `corrId` arguments through ~180 handler
+ * signatures, the context travels in an `AsyncLocalStorage`:
+ * `instrumentHandlers()` (`tools/registration-decorators.ts`) runs each handler
+ * inside `runWithRequestContext`, and `send()` (`http/transport.ts`) reads it
+ * back — the same pattern as the OAuth token (`oauthContext`). Work that is
+ * *shared* between requests (the dictionary cache's in-flight load, #226) opts
+ * out of cancellation with `withoutRequestSignal`: one caller cancelling must
+ * not fail the load every other caller is waiting on.
+ *
+ * `corrId` is the correlation id every log line of the request carries and
+ * that `send()` forwards to BoondManager as `X-Request-Id`. It is, in order:
+ * the W3C `trace-id` of a `_meta.traceparent` the client sent (SEP-414), the
+ * id the HTTP transport generated for the connection, or a fresh one (stdio).
+ * `traceparent` is forwarded verbatim when present. **`baggage` is never read
+ * and never logged** — it may carry end-user identifiers.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+/** Run `fn` with `context` as the current request's context (replaces any enclosing one). */
+export function runWithRequestContext(context, fn) {
+    return storage.run(context, fn);
+}
+/** The context of the request being handled, if a handler is on the stack. */
+export function currentRequestContext() {
+    return storage.getStore();
+}
+/** Run `fn` with `signal` as the current request's cancellation signal; the rest of the context is kept. */
+export function runWithRequestSignal(signal, fn) {
+    // Drop the enclosing signal rather than storing `undefined` under the key.
+    const { signal: _enclosing, ...rest } = storage.getStore() ?? {};
+    return storage.run(signal ? { ...rest, signal } : rest, fn);
+}
+/** Run `fn` with no cancellation signal, for work whose result other requests share. Correlation is kept. */
+export function withoutRequestSignal(fn) {
+    return runWithRequestSignal(undefined, fn);
+}
+/** The signal of the request being handled, if a handler is on the stack. */
+export function currentRequestSignal() {
+    return storage.getStore()?.signal;
+}
+/** The correlation id of the request being handled, if any. */
+export function currentCorrId() {
+    return storage.getStore()?.corrId;
+}
+/** Narrowing for the SDK's `extra`, typed `unknown` at every call site. */
+export function requestSignalFrom(extra) {
+    if (typeof extra !== "object" || extra === null)
+        return undefined;
+    const signal = extra.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
+/**
+ * W3C Trace Context `traceparent`: `version-traceid-parentid-flags`, lower-case
+ * hex, trace-id not all zeros. Anything else is ignored rather than trusted.
+ */
+const TRACEPARENT_RE = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** Parse a `traceparent` value; `undefined` when absent or malformed. */
+export function parseTraceparent(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = TRACEPARENT_RE.exec(value.trim());
+    const traceId = match?.[1];
+    if (!match || !traceId || /^0+$/.test(traceId))
+        return undefined;
+    return { header: match[0], traceId };
+}
+/** The `traceparent` the client put in the request's `_meta` (SEP-414), if valid. */
+export function traceparentFrom(extra) {
+    if (typeof extra !== "object" || extra === null)
+        return undefined;
+    const meta = extra._meta;
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    return parseTraceparent(meta.traceparent);
+}
+/**
+ * Raised when the client cancelled the request. `name` is `AbortError` so it
+ * reads like every other abort in Node; the message names the endpoint the
+ * cancellation interrupted, which is what a log line needs.
+ */
+export class RequestCancelledError extends Error {
+    method;
+    path;
+    constructor(method, path, cause) {
+        super(`BoondManager API request cancelled by the client (notifications/cancelled or transport closed).\nEndpoint: ${method} ${path}`, cause === undefined ? undefined : { cause });
+        this.name = "AbortError";
+        this.method = method;
+        this.path = path;
+    }
+}
+/** Throw `RequestCancelledError` if `signal` has fired. Cheap — call it before every unit of work. */
+export function throwIfCancelled(signal, method, path) {
+    if (signal?.aborted)
+        throw new RequestCancelledError(method, path, signal.reason);
+}
+/** A promise that rejects with the signal's reason the moment it fires (never resolves). */
+export function abortPromise(signal) {
+    return new Promise((_, reject) => {
+        signal.addEventListener("abort", () => reject(signal.reason ?? new Error("aborted")), { once: true });
+    });
+}
+//# sourceMappingURL=request-context.js.map

package/dist/services/request-context.js.map

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

package/dist/services/search.d.ts

@@ -0,0 +1,26 @@
+import type { JsonApiResponse, SearchParams } from "../types.js";
+import { type QueryValue } from "./http/transport.js";
+import type { ProgressReporter } from "./progress.js";
+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>;
+//# sourceMappingURL=search.d.ts.map

package/dist/services/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/services/search.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAwBjF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,UAAU,CAAC,EAAE,gBAAgB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA4C1B"}

package/dist/services/search.js

@@ -0,0 +1,98 @@
+/**
+ * Collection search: query building from a tool's params and the per-route
+ * `maxResults` ceiling with transparent chunking (see `ROUTE_MAX_RESULTS`).
+ */
+import { DEFAULT_MAX_RESULTS, DEFAULT_PAGE_SIZE, ROUTE_MAX_RESULTS } from "../constants.js";
+import { apiRequest } from "./http/transport.js";
+export function buildSearchQuery(params) {
+    const query = {};
+    if (params.keywords)
+        query["keywords"] = params.keywords;
+    if (params.page !== undefined)
+        query["page"] = params.page;
+    if (params.pageSize !== undefined)
+        query["maxResults"] = params.pageSize;
+    // Forward any additional filter params (strings, numbers, or arrays).
+    // `fields` is a client-side projection consumed by formatListResponse,
+    // never a BoondManager query parameter.
+    for (const [key, value] of Object.entries(params)) {
+        if (["keywords", "page", "pageSize", "fields"].includes(key))
+            continue;
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            // Pass arrays through so apiRequest emits repeated bracket notation
+            query[key] = value;
+        }
+        else if (typeof value === "string" || typeof value === "number") {
+            query[key] = value;
+        }
+        else {
+            query[key] = String(value);
+        }
+    }
+    return query;
+}
+/**
+ * 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 async function apiSearch(path, query, onProgress) {
+    const cap = ROUTE_MAX_RESULTS[path] ?? DEFAULT_MAX_RESULTS;
+    const requested = typeof query["maxResults"] === "number" ? query["maxResults"] : DEFAULT_PAGE_SIZE;
+    const page = typeof query["page"] === "number" ? query["page"] : 1;
+    // Fast path: one call, maxResults left exactly as the caller built it.
+    if (requested <= cap) {
+        return apiRequest(path, "GET", undefined, query);
+    }
+    // Chunked path: fetch `requested` records starting at the absolute offset
+    // implied by (page, requested), in BoondManager pages of `cap` records.
+    const startRow = (page - 1) * requested;
+    const firstBoondPage = Math.floor(startRow / cap) + 1;
+    const offsetInFirstChunk = startRow % cap;
+    const needed = offsetInFirstChunk + requested;
+    const collected = [];
+    let meta;
+    // Upper bound of the loop, and the `total` advertised to the client. It stays
+    // constant across the notifications of one call, as the spec requires.
+    const totalChunks = Math.ceil(needed / cap);
+    let fetchedChunks = 0;
+    for (let i = 0; collected.length < needed; i++) {
+        const chunkQuery = { ...query, page: firstBoondPage + i, maxResults: cap };
+        const response = await apiRequest(path, "GET", undefined, chunkQuery);
+        if (meta === undefined)
+            meta = response.meta;
+        const chunk = Array.isArray(response.data) ? response.data : response.data ? [response.data] : [];
+        collected.push(...chunk);
+        fetchedChunks = i + 1;
+        onProgress?.(fetchedChunks, totalChunks, `Récupération ${path} — page ${fetchedChunks}/${totalChunks}`);
+        // A short page means there is no more data on the server — stop early.
+        if (chunk.length < cap)
+            break;
+    }
+    const data = collected.slice(offsetInFirstChunk, offsetInFirstChunk + requested);
+    // Early stop (result set exhausted): close the bar rather than leaving the
+    // client at 2/5 forever. Skipped when the last page already reported `total`,
+    // which would repeat a value instead of increasing it.
+    if (fetchedChunks < totalChunks) {
+        onProgress?.(totalChunks, totalChunks, `Récupération ${path} — terminé (${data.length} résultat(s))`);
+    }
+    return meta !== undefined ? { data, meta } : { data };
+}
+//# sourceMappingURL=search.js.map