@bbradar/mcp 0.2.3 → 0.2.6

package/dist/bbradarClient.js

@@ -1,7 +1,75 @@
 import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { TtlCache } from "./cache.js";
 import { stableStringify } from "./json.js";
 import { encodeProgramIdPath } from "./url.js";
+function publicPayload(payload) {
+    const { cacheAllowed: _cacheAllowed, ...publicFields } = payload;
+    return publicFields;
+}
+function subscribeToRequest(promise, requestId, signal, shared) {
+    if (shared)
+        shared.consumers += 1;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", cancel);
+            if (shared)
+                shared.consumers -= 1;
+            callback();
+        };
+        const cancel = () => finish(() => {
+            if (shared?.consumers === 0)
+                shared.controller.abort(signal?.reason);
+            reject(new BBRadarApiError({ message: "BBRadar API request was cancelled or exceeded its tool deadline.", requestId, status: 408 }));
+        });
+        signal?.addEventListener("abort", cancel, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+        if (signal?.aborted)
+            cancel();
+    });
+}
+function waitForRequestSlot(queue, deadline, requestId, signal) {
+    if (queue.length >= MAX_QUEUED_REQUESTS) {
+        throw new BBRadarApiError({ message: "BBRadar API request queue is full.", requestId, status: 503 });
+    }
+    if (deadline <= Date.now() || signal?.aborted) {
+        throw new BBRadarApiError({ message: "BBRadar API request timed out or was cancelled while queued.", requestId, status: 408 });
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const remove = () => {
+            const index = queue.indexOf(grant);
+            if (index >= 0)
+                queue.splice(index, 1);
+        };
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+        };
+        const grant = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const cancel = () => {
+            if (settled)
+                return;
+            settled = true;
+            remove();
+            cleanup();
+            reject(new BBRadarApiError({ message: "BBRadar API request timed out or was cancelled while queued.", requestId, status: 408 }));
+        };
+        const timer = setTimeout(cancel, Math.max(1, deadline - Date.now()));
+        signal?.addEventListener("abort", cancel, { once: true });
+        queue.push(grant);
+    });
+}
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60_000;
 const MAX_UPSTREAM_RATE_LIMIT_DELAY_MS = 10 * 60_000;
 const CHANGE_FEED_CONCURRENCY_LIMIT = 2;
@@ -13,6 +81,8 @@ const MAX_REQUEST_BODY_BYTES = 64 * 1024;
 const DEFAULT_PROGRAM_SWR_MS = 5 * 60_000;
 const DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 3;
 const DEFAULT_CIRCUIT_COOLDOWN_MS = 30_000;
+const SNAPSHOT_START_MIN_TIMEOUT_MS = 60_000;
+const MAX_QUEUED_REQUESTS = 100;
 export class BBRadarApiError extends Error {
     requestId;
     upstreamRequestId;
@@ -22,6 +92,7 @@ export class BBRadarApiError extends Error {
     cached;
     coalesced;
     cacheExpiresAt;
+    cacheAllowed;
     constructor(params) {
         super(params.message, { cause: params.cause });
         this.name = "BBRadarApiError";
@@ -33,6 +104,7 @@ export class BBRadarApiError extends Error {
         this.cached = params.cached ?? false;
         this.coalesced = params.coalesced ?? false;
         this.cacheExpiresAt = params.cacheExpiresAt;
+        this.cacheAllowed = params.cacheAllowed ?? true;
     }
 }
 export class BBRadarClient {
@@ -40,6 +112,8 @@ export class BBRadarClient {
     cache;
     negativeCache;
     inFlight = new Map();
+    sharedRequests = new Map();
+    requestContext = new AsyncLocalStorage();
     endpointMetrics = new Map();
     requestQueue = [];
     endpointRequestQueues = new Map();
@@ -56,6 +130,24 @@ export class BBRadarClient {
         this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs, config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS);
         this.negativeCache = new TtlCache(config.cacheMaxEntries, config.negativeCacheTtlMs);
     }
+    async withRequestContext(signal, callback, snapshotStart = false) {
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal.reason);
+        const timeout = setTimeout(() => controller.abort(new DOMException("Tool deadline exceeded.", "TimeoutError")), snapshotStart
+            ? Math.max(this.config.requestTimeoutMs, SNAPSHOT_START_MIN_TIMEOUT_MS)
+            : this.config.requestTimeoutMs);
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        try {
+            return await this.requestContext.run(controller.signal, callback);
+        }
+        finally {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", onAbort);
+            controller.abort();
+        }
+    }
     diagnostics() {
         const endpointEntries = [...this.endpointMetrics.entries()];
         const totalRequests = endpointEntries.reduce((total, [, metric]) => total + metric.requests, 0);
@@ -176,6 +268,16 @@ export class BBRadarClient {
             ? [...value]
             : [...fallback];
     }
+    supportsStableSnapshot(endpoint) {
+        if (this.capabilityState.status !== "negotiated") {
+            return false;
+        }
+        const contract = asRecord(this.capabilityState.contract);
+        const behavior = asRecord(contract?.behavior);
+        const stableSnapshots = asRecord(behavior?.stable_snapshots);
+        const endpoints = stableSnapshots?.endpoints;
+        return Array.isArray(endpoints) && endpoints.includes(endpoint);
+    }
     async fetchCapabilityContract() {
         try {
             const result = await this.getCapabilities({ cache: false, coalesce: false });
@@ -201,10 +303,11 @@ export class BBRadarClient {
             throw error;
         }
     }
-    listPrograms(query) {
+    listPrograms(query, controls = {}) {
         return this.request({
             path: "/pro/programs",
-            query
+            query,
+            ...snapshotAwareReadControls(query, controls, true, this.config.requestTimeoutMs)
         });
     }
     getCapabilities(options = {}) {
@@ -229,24 +332,25 @@ export class BBRadarClient {
             }
         });
     }
-    getRecentChanges(query) {
+    getRecentChanges(query, controls = {}) {
         return this.request({
             path: "/pro/targets/changes",
             query,
-            cache: query.after_id === undefined
+            ...snapshotAwareReadControls(query, controls, query.after_id === undefined, this.config.requestTimeoutMs)
         });
     }
-    getRepositoryChanges(query) {
+    getRepositoryChanges(query, controls = {}) {
         return this.request({
             path: "/pro/repositories/changes",
             query,
-            cache: query.after_id === undefined
+            ...snapshotAwareReadControls(query, controls, query.after_id === undefined, this.config.requestTimeoutMs)
         });
     }
-    searchTargets(query) {
+    searchTargets(query, controls = {}) {
         return this.request({
             path: "/pro/targets/search",
-            query
+            query,
+            ...snapshotAwareReadControls(query, controls, true, this.config.requestTimeoutMs)
         });
     }
     getOpportunities(level, query) {
@@ -255,6 +359,27 @@ export class BBRadarClient {
             query
         });
     }
+    getHistoryChanges(query) {
+        return this.request({ path: "/pro/history/changes", query, cache: false });
+    }
+    getHistoryChangeDetail(changeId, query) {
+        return this.request({ path: `/pro/history/changes/${encodeURIComponent(changeId)}`, query, cache: false });
+    }
+    getProgramHistory(programId, query) {
+        return this.request({ path: `/pro/history/programs/${encodeProgramIdPath(programId)}`, query, cache: false });
+    }
+    getProgramActivity(programId) {
+        return this.request({ path: `/pro/activity/programs/${encodeProgramIdPath(programId)}`, cache: false });
+    }
+    getAnalyticsPlatformSeries(platform, query) {
+        return this.request({ path: `/pro/analytics/platforms/${encodeURIComponent(platform)}/series`, query, cache: false });
+    }
+    getAnalyticsProgramActivity(query) {
+        return this.request({ path: "/pro/analytics/programs/activity", query, cache: false });
+    }
+    getAnalyticsProgramDetail(programId, query) {
+        return this.request({ path: `/pro/analytics/programs/${encodeProgramIdPath(programId)}`, query, cache: false });
+    }
     exportTargets(body) {
         return this.request({
             method: "POST",
@@ -265,8 +390,33 @@ export class BBRadarClient {
         });
     }
     async request(options) {
+        const contextSignal = this.requestContext.getStore();
+        if (!options.signal || !contextSignal || options.signal === contextSignal) {
+            return this.requestWithSignal(options, options.signal ?? contextSignal);
+        }
+        // AbortSignal.any is unavailable on the earliest supported Node 20 releases.
+        // Remove both listeners after this caller settles, even for coalesced reads.
+        const controller = new AbortController();
+        const signals = [options.signal, contextSignal];
+        const listeners = signals.map((signal) => {
+            const abort = () => controller.abort(signal.reason);
+            signal.addEventListener("abort", abort, { once: true });
+            if (signal.aborted)
+                abort();
+            return abort;
+        });
+        try {
+            return await this.requestWithSignal(options, controller.signal);
+        }
+        finally {
+            signals.forEach((signal, index) => signal.removeEventListener("abort", listeners[index]));
+        }
+    }
+    async requestWithSignal(options, signal) {
         const method = options.method ?? "GET";
         const requestId = randomUUID();
+        if (signal?.aborted)
+            throw new BBRadarApiError({ message: "BBRadar API request was cancelled or exceeded its tool deadline.", requestId, status: 408 });
         const url = this.buildUrl(options.path, options.query);
         const requestKey = stableStringify({
             method,
@@ -286,7 +436,7 @@ export class BBRadarClient {
                     this.refreshInBackground(options, method, url, requestKey);
                 }
                 return {
-                    ...cached.value,
+                    ...publicPayload(cached.value),
                     requestId,
                     cached: true,
                     stale: cached.stale,
@@ -307,11 +457,11 @@ export class BBRadarClient {
         }
         if (coalesceable) {
             const pending = this.inFlight.get(requestKey);
-            if (pending) {
+            if (pending && !this.sharedRequests.get(requestKey)?.controller.signal.aborted) {
                 try {
-                    const result = (await pending);
+                    const result = (await subscribeToRequest(pending, requestId, signal, this.sharedRequests.get(requestKey)));
                     return {
-                        ...result,
+                        ...publicPayload(result),
                         requestId,
                         cached: false,
                         coalesced: true
@@ -322,27 +472,20 @@ export class BBRadarClient {
                 }
             }
         }
-        const request = this.fetchFromApi(options, method, url, requestId);
-        if (coalesceable) {
-            this.inFlight.set(requestKey, request);
-        }
-        try {
-            const result = await request;
-            if (cacheable) {
+        const shared = coalesceable ? { controller: new AbortController(), consumers: 0 } : undefined;
+        const requestOptions = { ...options, ...(shared ? { signal: shared.controller.signal } : signal ? { signal } : {}) };
+        const request = this.fetchFromApi(requestOptions, method, url, requestId).then((result) => {
+            if (cacheable && result.cacheAllowed !== false) {
                 this.cache.set(requestKey, result);
             }
             if (negativeCacheable) {
                 this.negativeCache.delete(requestKey);
             }
-            return {
-                ...result,
-                requestId,
-                cached: false
-            };
-        }
-        catch (error) {
+            return result;
+        }).catch((error) => {
             if (negativeCacheable &&
                 error instanceof BBRadarApiError &&
+                error.cacheAllowed &&
                 error.status !== undefined &&
                 isNegativeCacheStatus(error.status)) {
                 this.negativeCache.set(requestKey, {
@@ -354,14 +497,21 @@ export class BBRadarClient {
                 });
             }
             throw error;
-        }
-        finally {
-            if (coalesceable) {
+        }).finally(() => {
+            if (coalesceable && this.inFlight.get(requestKey) === request) {
                 this.inFlight.delete(requestKey);
+                this.sharedRequests.delete(requestKey);
             }
+        });
+        if (coalesceable) {
+            this.inFlight.set(requestKey, request);
+            this.sharedRequests.set(requestKey, shared);
         }
+        const result = await subscribeToRequest(request, requestId, signal, shared);
+        return { ...publicPayload(result), requestId, cached: false };
     }
     async fetchFromApi(options, method, url, requestId) {
+        const deadline = Date.now() + (options.timeoutMs ?? this.config.requestTimeoutMs);
         const serializedBody = options.body === undefined ? undefined : JSON.stringify(options.body);
         if (serializedBody !== undefined) {
             const bodyBytes = Buffer.byteLength(serializedBody, "utf8");
@@ -376,11 +526,20 @@ export class BBRadarClient {
         }
         return this.withRequestSlot(options.path, async () => {
             const rateLimitBucket = rateLimitEndpointGroup(options.path);
+            if (options.signal?.aborted)
+                throw new BBRadarApiError({ message: "BBRadar API request was cancelled.", requestId, status: 408 });
             this.assertCircuitClosed(requestId, rateLimitBucket);
             this.reserveUpstreamRequest(requestId, rateLimitBucket);
             const startedAt = Date.now();
             const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0)
+                throw new BBRadarApiError({ message: "BBRadar API request timed out while queued.", requestId, status: 408 });
+            const timeout = setTimeout(() => controller.abort(), remainingMs);
+            const onAbort = () => controller.abort();
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (options.signal?.aborted)
+                controller.abort();
             let status;
             let failed = true;
             try {
@@ -394,6 +553,7 @@ export class BBRadarClient {
                 }
                 const response = await fetch(url, init);
                 status = response.status;
+                const noStore = /(?:^|,)\s*(?:no-store|no-cache|private)\b/i.test(response.headers.get("cache-control") ?? "");
                 this.observeCircuitResponse(rateLimitBucket, response.status);
                 this.observeUpstreamRateLimit(rateLimitBucket, response.headers, response.status);
                 const upstreamRequestId = extractRequestId(response.headers);
@@ -405,7 +565,8 @@ export class BBRadarClient {
                         requestId,
                         status: response.status,
                         detail: extractObjectField(data, "detail"),
-                        errors: extractObjectField(data, "errors")
+                        errors: extractObjectField(data, "errors"),
+                        cacheAllowed: !noStore
                     };
                     if (upstreamRequestId) {
                         params.upstreamRequestId = upstreamRequestId;
@@ -415,7 +576,9 @@ export class BBRadarClient {
                 const result = {
                     data: data,
                     status: response.status,
-                    fetchedAt: new Date().toISOString()
+                    fetchedAt: new Date().toISOString(),
+                    noStore,
+                    cacheAllowed: !noStore
                 };
                 if (upstreamRequestId) {
                     result.upstreamRequestId = upstreamRequestId;
@@ -427,6 +590,12 @@ export class BBRadarClient {
                 if (error instanceof BBRadarApiError) {
                     throw error;
                 }
+                if (options.signal?.aborted) {
+                    const timedOut = options.signal.reason instanceof Error && options.signal.reason.name === "TimeoutError";
+                    if (timedOut)
+                        this.observeCircuitFailure(rateLimitBucket);
+                    throw new BBRadarApiError({ message: timedOut ? "BBRadar API tool deadline exceeded." : "BBRadar API request was cancelled.", requestId, status: 408 });
+                }
                 this.observeCircuitFailure(rateLimitBucket);
                 throw new BBRadarApiError({
                     message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
@@ -436,9 +605,10 @@ export class BBRadarClient {
             }
             finally {
                 clearTimeout(timeout);
+                options.signal?.removeEventListener("abort", onAbort);
                 this.recordEndpointMetric(options.path, Date.now() - startedAt, status, failed);
             }
-        });
+        }, deadline, requestId, options.signal);
     }
     refreshInBackground(options, method, url, requestKey) {
         if (this.inFlight.has(requestKey)) {
@@ -448,7 +618,12 @@ export class BBRadarClient {
         this.inFlight.set(requestKey, refresh);
         void refresh
             .then((result) => {
-            this.cache.set(requestKey, result);
+            if (result.cacheAllowed !== false) {
+                this.cache.set(requestKey, result);
+            }
+            else {
+                this.cache.delete(requestKey);
+            }
             this.negativeCache.delete(requestKey);
         })
             .catch(() => undefined)
@@ -458,21 +633,21 @@ export class BBRadarClient {
             }
         });
     }
-    async withRequestSlot(path, callback) {
+    async withRequestSlot(path, callback, deadline, requestId, signal) {
         const endpointGroup = concurrencyEndpointGroup(path);
         if (endpointGroup === undefined) {
-            return this.withGlobalRequestSlot(callback);
+            return this.withGlobalRequestSlot(callback, deadline, requestId, signal);
         }
         const endpointLimit = endpointConcurrencyLimit(endpointGroup);
         if (endpointLimit === undefined) {
-            return this.withGlobalRequestSlot(callback);
+            return this.withGlobalRequestSlot(callback, deadline, requestId, signal);
         }
-        return this.withEndpointRequestSlot(endpointGroup, endpointLimit, () => this.withGlobalRequestSlot(callback));
+        return this.withEndpointRequestSlot(endpointGroup, endpointLimit, () => this.withGlobalRequestSlot(callback, deadline, requestId, signal), deadline, requestId, signal);
     }
-    async withGlobalRequestSlot(callback) {
+    async withGlobalRequestSlot(callback, deadline, requestId, signal) {
         const limit = Math.max(1, this.config.maxConcurrentRequests);
         if (this.activeRequests >= limit) {
-            await new Promise((resolve) => this.requestQueue.push(resolve));
+            await waitForRequestSlot(this.requestQueue, deadline, requestId, signal);
         }
         else {
             this.activeRequests += 1;
@@ -490,14 +665,12 @@ export class BBRadarClient {
             }
         }
     }
-    async withEndpointRequestSlot(endpointGroup, limit, callback) {
+    async withEndpointRequestSlot(endpointGroup, limit, callback, deadline, requestId, signal) {
         const active = this.endpointActiveRequests.get(endpointGroup) ?? 0;
         if (active >= limit) {
             const queue = this.endpointRequestQueues.get(endpointGroup) ?? [];
-            await new Promise((resolve) => {
-                queue.push(resolve);
-                this.endpointRequestQueues.set(endpointGroup, queue);
-            });
+            this.endpointRequestQueues.set(endpointGroup, queue);
+            await waitForRequestSlot(queue, deadline, requestId, signal);
         }
         else {
             this.endpointActiveRequests.set(endpointGroup, active + 1);
@@ -787,7 +960,9 @@ export class BBRadarClient {
         };
     }
     buildUrl(path, query) {
-        const url = new URL(`${this.config.apiBaseUrl}${path}`);
+        const base = this.config.apiBaseUrl.replace(/\/+$/, "");
+        const prefix = /\/v1$/i.test(base) ? base : `${base}/v1`;
+        const url = new URL(`${prefix}${path}`);
         for (const [key, value] of Object.entries(query ?? {})) {
             if (value === undefined || value === null) {
                 continue;
@@ -892,6 +1067,16 @@ function toIsoString(timestamp) {
     return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
 }
 function metricEndpoint(path) {
+    if (/^\/pro\/history\/changes\/.+/.test(path))
+        return "/pro/history/changes/:change_id";
+    if (/^\/pro\/history\/programs\/.+/.test(path))
+        return "/pro/history/programs/:program_id";
+    if (/^\/pro\/activity\/programs\/.+/.test(path))
+        return "/pro/activity/programs/:program_id";
+    if (/^\/pro\/analytics\/platforms\/.+\/series$/.test(path))
+        return "/pro/analytics/platforms/:platform/series";
+    if (/^\/pro\/analytics\/programs\/.+/.test(path) && path !== "/pro/analytics/programs/activity")
+        return "/pro/analytics/programs/:program_id";
     if (/^\/pro\/programs\/.+\/targets$/.test(path)) {
         return "/pro/programs/:program_id/targets";
     }
@@ -904,7 +1089,7 @@ function metricEndpoint(path) {
     return path;
 }
 function rateLimitEndpointGroup(path) {
-    if (path === "/pro/targets/changes") {
+    if (path === "/pro/targets/changes" || /^\/pro\/(?:history|activity|analytics)\//.test(path)) {
         return "change_feeds";
     }
     if (path === "/pro/repositories/changes") {
@@ -928,7 +1113,7 @@ function rateLimitEndpointGroup(path) {
     return "other";
 }
 function concurrencyEndpointGroup(path) {
-    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes") {
+    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes" || /^\/pro\/(?:history|activity|analytics)\//.test(path)) {
         return "change_feeds";
     }
     if (path === "/pro/targets/export") {
@@ -945,6 +1130,25 @@ function endpointConcurrencyLimit(endpointGroup) {
     }
     return undefined;
 }
+function snapshotAwareReadControls(query, controls, defaultCache, defaultTimeoutMs) {
+    const snapshot = typeof query.snapshot === "string" ? query.snapshot : undefined;
+    const result = {
+        // Snapshot responses are explicitly `Cache-Control: no-store`. Keeping
+        // them out of the local TTL cache also prevents an expired token from
+        // being replayed after its five-minute API lifetime.
+        cache: controls.cache ?? (defaultCache && snapshot === undefined),
+        // Two concurrent `snapshot=start` calls must create independent views.
+        // Reusing an already-issued token can still coalesce identical live work.
+        coalesce: controls.coalesce ?? snapshot !== "start"
+    };
+    const timeoutMs = controls.timeoutMs ?? (snapshot === "start"
+        ? Math.max(defaultTimeoutMs, SNAPSHOT_START_MIN_TIMEOUT_MS)
+        : undefined);
+    if (timeoutMs !== undefined) {
+        result.timeoutMs = timeoutMs;
+    }
+    return result;
+}
 function isNegativeCacheStatus(status) {
     return status === 404 || status === 405;
 }
@@ -1041,6 +1245,7 @@ function cloneApiError(error, requestId, coalesced = error instanceof BBRadarApi
         cached: error.cached,
         coalesced,
         cacheExpiresAt: error.cacheExpiresAt,
+        cacheAllowed: error.cacheAllowed,
         cause: error
     });
 }