@bbradar/mcp 0.1.20 → 0.2.0

package/dist/bbradarClient.js

@@ -3,9 +3,16 @@ import { TtlCache } from "./cache.js";
 import { stableStringify } from "./json.js";
 import { encodeProgramIdPath } from "./url.js";
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60_000;
-const TARGET_CHANGES_CONCURRENCY_LIMIT = 3;
+const MAX_UPSTREAM_RATE_LIMIT_DELAY_MS = 10 * 60_000;
+const CHANGE_FEED_CONCURRENCY_LIMIT = 2;
+const TARGET_EXPORT_CONCURRENCY_LIMIT = 2;
 const UPSTREAM_KEY_IP_REQUEST_LIMIT = 60;
 const UPSTREAM_KEY_IP_WINDOW_MS = 60_000;
+const MAX_RESPONSE_BODY_BYTES = 16 * 1024 * 1024;
+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;
 export class BBRadarApiError extends Error {
     requestId;
     upstreamRequestId;
@@ -38,12 +45,15 @@ export class BBRadarClient {
     endpointRequestQueues = new Map();
     endpointActiveRequests = new Map();
     upstreamRateLimits = new Map();
+    circuitBreakers = new Map();
     upstreamRequestTimestampsMs = [];
     activeRequests = 0;
     globalBlockedUntilMs;
+    capabilityNegotiation;
+    capabilityState = { status: "not_started" };
     constructor(config) {
         this.config = config;
-        this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs);
+        this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs, config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS);
         this.negativeCache = new TtlCache(config.cacheMaxEntries, config.negativeCacheTtlMs);
     }
     diagnostics() {
@@ -60,16 +70,23 @@ export class BBRadarClient {
                 enabled: this.config.negativeCacheTtlMs > 0 && this.config.cacheMaxEntries > 0,
                 ...this.negativeCache.stats()
             },
+            capability_negotiation: this.capabilitySnapshot(),
+            circuit_breakers: this.circuitBreakerDiagnostics(),
             in_flight_requests: this.inFlight.size,
             request_concurrency: {
                 limit: this.config.maxConcurrentRequests,
                 active: this.activeRequests,
                 queued: this.requestQueue.length,
                 endpoint_limits: {
-                    target_changes: {
-                        limit: TARGET_CHANGES_CONCURRENCY_LIMIT,
-                        active: this.endpointActiveRequests.get("target_changes") ?? 0,
-                        queued: this.endpointRequestQueues.get("target_changes")?.length ?? 0
+                    change_feeds: {
+                        limit: CHANGE_FEED_CONCURRENCY_LIMIT,
+                        active: this.endpointActiveRequests.get("change_feeds") ?? 0,
+                        queued: this.endpointRequestQueues.get("change_feeds")?.length ?? 0
+                    },
+                    target_export: {
+                        limit: TARGET_EXPORT_CONCURRENCY_LIMIT,
+                        active: this.endpointActiveRequests.get("target_export") ?? 0,
+                        queued: this.endpointRequestQueues.get("target_export")?.length ?? 0
                     }
                 }
             },
@@ -96,12 +113,15 @@ export class BBRadarClient {
     }
     async validateKey() {
         try {
-            await this.request({
-                path: "/pro/programs",
-                query: { page: 1, page_size: 1 },
-                cache: false,
-                coalesce: false
-            });
+            await this.negotiateCapabilities();
+            if (this.capabilityState.status === "legacy") {
+                await this.request({
+                    path: "/pro/programs",
+                    query: { page: 1, page_size: 1 },
+                    cache: false,
+                    coalesce: false
+                });
+            }
         }
         catch (error) {
             if (!(error instanceof BBRadarApiError)) {
@@ -122,26 +142,105 @@ export class BBRadarClient {
             throw error;
         }
     }
+    negotiateCapabilities() {
+        if (!this.capabilityNegotiation) {
+            this.capabilityNegotiation = this.fetchCapabilityContract();
+        }
+        return this.capabilityNegotiation;
+    }
+    capabilitySnapshot() {
+        return { ...this.capabilityState };
+    }
+    supportsEndpoint(endpoint) {
+        if (this.capabilityState.status !== "negotiated") {
+            return true;
+        }
+        const contract = asRecord(this.capabilityState.contract);
+        const endpoints = asRecord(contract?.endpoints);
+        return endpoints !== undefined && asRecord(endpoints[endpoint]) !== undefined;
+    }
+    endpointCapability(endpoint) {
+        if (this.capabilityState.status !== "negotiated") {
+            return undefined;
+        }
+        const contract = asRecord(this.capabilityState.contract);
+        return asRecord(asRecord(contract?.endpoints)?.[endpoint]);
+    }
+    endpointNumber(endpoint, field, fallback) {
+        const value = this.endpointCapability(endpoint)?.[field];
+        return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+    }
+    endpointStringArray(endpoint, field, fallback) {
+        const value = this.endpointCapability(endpoint)?.[field];
+        return Array.isArray(value) && value.every((entry) => typeof entry === "string")
+            ? [...value]
+            : [...fallback];
+    }
+    async fetchCapabilityContract() {
+        try {
+            const result = await this.getCapabilities({ cache: false, coalesce: false });
+            this.capabilityState = {
+                status: "negotiated",
+                negotiatedAt: result.fetchedAt,
+                contract: result.data
+            };
+        }
+        catch (error) {
+            if (error instanceof BBRadarApiError && (error.status === 404 || error.status === 405)) {
+                this.capabilityState = {
+                    status: "legacy",
+                    negotiatedAt: new Date().toISOString()
+                };
+                return;
+            }
+            this.capabilityState = {
+                status: "failed",
+                negotiatedAt: new Date().toISOString(),
+                error: error instanceof Error ? error.message : String(error)
+            };
+            throw error;
+        }
+    }
     listPrograms(query) {
         return this.request({
             path: "/pro/programs",
             query
         });
     }
+    getCapabilities(options = {}) {
+        return this.request({
+            path: "/pro/capabilities",
+            ...options
+        });
+    }
     getProgram(programId) {
         return this.request({
-            path: `/pro/programs/${encodeProgramIdPath(programId)}`
+            path: `/pro/programs/${encodeProgramIdPath(programId)}`,
+            staleWhileRevalidateMs: this.config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS
         });
     }
-    getProgramTargets(programId) {
+    getProgramTargets(programId, query = {}) {
         return this.request({
-            path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`
+            path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`,
+            query: {
+                page: 1,
+                page_size: this.endpointNumber("program_targets", "max_page_size", 500),
+                ...query
+            }
         });
     }
     getRecentChanges(query) {
         return this.request({
             path: "/pro/targets/changes",
-            query
+            query,
+            cache: query.after_id === undefined
+        });
+    }
+    getRepositoryChanges(query) {
+        return this.request({
+            path: "/pro/repositories/changes",
+            query,
+            cache: query.after_id === undefined
         });
     }
     searchTargets(query) {
@@ -181,12 +280,16 @@ export class BBRadarClient {
             this.config.cacheMaxEntries > 0;
         const coalesceable = method === "GET" && (options.coalesce ?? true);
         if (cacheable) {
-            const cached = this.cache.get(requestKey);
+            const cached = this.cache.getWithStale(requestKey, options.staleWhileRevalidateMs ?? 0);
             if (cached) {
+                if (cached.stale) {
+                    this.refreshInBackground(options, method, url, requestKey);
+                }
                 return {
                     ...cached.value,
                     requestId,
                     cached: true,
+                    stale: cached.stale,
                     cacheExpiresAt: new Date(cached.expiresAt).toISOString()
                 };
             }
@@ -259,8 +362,21 @@ export class BBRadarClient {
         }
     }
     async fetchFromApi(options, method, url, requestId) {
+        const serializedBody = options.body === undefined ? undefined : JSON.stringify(options.body);
+        if (serializedBody !== undefined) {
+            const bodyBytes = Buffer.byteLength(serializedBody, "utf8");
+            if (bodyBytes > MAX_REQUEST_BODY_BYTES) {
+                throw new BBRadarApiError({
+                    message: `BBRadar API request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`,
+                    requestId,
+                    status: 413,
+                    detail: { body_bytes: bodyBytes, max_body_bytes: MAX_REQUEST_BODY_BYTES }
+                });
+            }
+        }
         return this.withRequestSlot(options.path, async () => {
             const rateLimitBucket = rateLimitEndpointGroup(options.path);
+            this.assertCircuitClosed(requestId, rateLimitBucket);
             this.reserveUpstreamRequest(requestId, rateLimitBucket);
             const startedAt = Date.now();
             const controller = new AbortController();
@@ -273,15 +389,17 @@ export class BBRadarClient {
                     headers: this.headers(options.body),
                     signal: controller.signal
                 };
-                if (options.body !== undefined) {
-                    init.body = JSON.stringify(options.body);
+                if (serializedBody !== undefined) {
+                    init.body = serializedBody;
                 }
                 const response = await fetch(url, init);
                 status = response.status;
+                this.observeCircuitResponse(rateLimitBucket, response.status);
                 this.observeUpstreamRateLimit(rateLimitBucket, response.headers, response.status);
                 const upstreamRequestId = extractRequestId(response.headers);
                 const data = await parseResponseBody(response);
                 if (!response.ok) {
+                    this.observeUpstreamErrorBody(rateLimitBucket, response.status, data);
                     const params = {
                         message: formatApiErrorMessage(response.status, data),
                         requestId,
@@ -309,6 +427,7 @@ export class BBRadarClient {
                 if (error instanceof BBRadarApiError) {
                     throw error;
                 }
+                this.observeCircuitFailure(rateLimitBucket);
                 throw new BBRadarApiError({
                     message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
                     requestId,
@@ -321,8 +440,29 @@ export class BBRadarClient {
             }
         });
     }
+    refreshInBackground(options, method, url, requestKey) {
+        if (this.inFlight.has(requestKey)) {
+            return;
+        }
+        const refresh = this.fetchFromApi({ ...options, staleWhileRevalidateMs: 0 }, method, url, randomUUID());
+        this.inFlight.set(requestKey, refresh);
+        void refresh
+            .then((result) => {
+            this.cache.set(requestKey, result);
+            this.negativeCache.delete(requestKey);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.inFlight.get(requestKey) === refresh) {
+                this.inFlight.delete(requestKey);
+            }
+        });
+    }
     async withRequestSlot(path, callback) {
-        const endpointGroup = rateLimitEndpointGroup(path);
+        const endpointGroup = concurrencyEndpointGroup(path);
+        if (endpointGroup === undefined) {
+            return this.withGlobalRequestSlot(callback);
+        }
         const endpointLimit = endpointConcurrencyLimit(endpointGroup);
         if (endpointLimit === undefined) {
             return this.withGlobalRequestSlot(callback);
@@ -450,10 +590,12 @@ export class BBRadarClient {
         }
         state.observedAtMs = now;
         state.lastStatus = status;
-        if (status === 429) {
+        if (status === 429 || ((status === 423 || status === 503) && retryAtMs !== undefined)) {
             const advertisedBlockUntil = Math.max(retryAtMs ?? 0, resetAtMs && resetAtMs > now ? resetAtMs : 0);
             const blockedUntil = advertisedBlockUntil > now ? advertisedBlockUntil : now + DEFAULT_RATE_LIMIT_COOLDOWN_MS;
-            state.remaining = 0;
+            if (status === 429) {
+                state.remaining = 0;
+            }
             state.blockedUntilMs = blockedUntil;
             this.globalBlockedUntilMs = Math.max(this.globalBlockedUntilMs ?? 0, blockedUntil);
             return;
@@ -466,6 +608,25 @@ export class BBRadarClient {
             state.blockedUntilMs = undefined;
         }
     }
+    observeUpstreamErrorBody(bucket, status, data) {
+        if (status !== 423) {
+            return;
+        }
+        const payload = asRecord(data);
+        const detail = asRecord(payload?.detail);
+        const rawLockedUntil = payload?.locked_until ?? detail?.locked_until;
+        if (typeof rawLockedUntil !== "string") {
+            return;
+        }
+        const parsed = Date.parse(rawLockedUntil);
+        if (!Number.isFinite(parsed) || parsed <= Date.now()) {
+            return;
+        }
+        const blockedUntil = Math.min(parsed, Date.now() + MAX_UPSTREAM_RATE_LIMIT_DELAY_MS);
+        const state = this.rateLimitState(bucket);
+        state.blockedUntilMs = Math.max(state.blockedUntilMs ?? 0, blockedUntil);
+        this.globalBlockedUntilMs = Math.max(this.globalBlockedUntilMs ?? 0, blockedUntil);
+    }
     rateLimitState(bucket) {
         const state = this.upstreamRateLimits.get(bucket) ?? {};
         this.upstreamRateLimits.set(bucket, state);
@@ -558,6 +719,73 @@ export class BBRadarClient {
             ]))
         };
     }
+    assertCircuitClosed(requestId, bucket) {
+        const state = this.circuitBreakers.get(bucket);
+        const now = Date.now();
+        if (!state?.openUntilMs || state.openUntilMs <= now) {
+            if (state?.openUntilMs !== undefined) {
+                state.openUntilMs = undefined;
+            }
+            return;
+        }
+        throw new BBRadarApiError({
+            message: `BBRadar ${bucket} circuit is temporarily open; no upstream request was sent.`,
+            requestId,
+            status: 503,
+            detail: {
+                source: "circuit_breaker",
+                bucket,
+                consecutive_failures: state.consecutiveFailures,
+                retry_at: new Date(state.openUntilMs).toISOString()
+            }
+        });
+    }
+    observeCircuitResponse(bucket, status) {
+        if (status >= 200 && status < 400) {
+            const state = this.circuitBreakers.get(bucket);
+            if (state) {
+                state.consecutiveFailures = 0;
+                state.openUntilMs = undefined;
+                state.lastSuccessAtMs = Date.now();
+                state.lastStatus = status;
+            }
+            return;
+        }
+        if (status === 423 || status === 429 || status >= 500) {
+            this.observeCircuitFailure(bucket, status);
+        }
+    }
+    observeCircuitFailure(bucket, status) {
+        const state = this.circuitBreakers.get(bucket) ?? { consecutiveFailures: 0 };
+        state.consecutiveFailures += 1;
+        state.lastFailureAtMs = Date.now();
+        state.lastStatus = status;
+        if (state.consecutiveFailures >=
+            (this.config.circuitBreakerFailureThreshold ?? DEFAULT_CIRCUIT_FAILURE_THRESHOLD)) {
+            state.openUntilMs =
+                Date.now() +
+                    (this.config.circuitBreakerCooldownMs ?? DEFAULT_CIRCUIT_COOLDOWN_MS);
+        }
+        this.circuitBreakers.set(bucket, state);
+    }
+    circuitBreakerDiagnostics() {
+        const now = Date.now();
+        return {
+            failure_threshold: this.config.circuitBreakerFailureThreshold ?? DEFAULT_CIRCUIT_FAILURE_THRESHOLD,
+            cooldown_ms: this.config.circuitBreakerCooldownMs ?? DEFAULT_CIRCUIT_COOLDOWN_MS,
+            by_endpoint: Object.fromEntries([...this.circuitBreakers.entries()].map(([bucket, state]) => [
+                bucket,
+                {
+                    state: (state.openUntilMs ?? 0) > now ? "open" : state.consecutiveFailures > 0 ? "closed_degraded" : "closed",
+                    consecutive_failures: state.consecutiveFailures,
+                    open_until: toIsoString(state.openUntilMs),
+                    last_failure_at: toIsoString(state.lastFailureAtMs),
+                    last_success_at: toIsoString(state.lastSuccessAtMs),
+                    last_status: state.lastStatus
+                }
+            ]))
+        };
+    }
     buildUrl(path, query) {
         const url = new URL(`${this.config.apiBaseUrl}${path}`);
         for (const [key, value] of Object.entries(query ?? {})) {
@@ -628,15 +856,15 @@ function parseRateLimitReset(headers, now) {
     const numeric = Number(value.trim());
     if (Number.isFinite(numeric) && numeric >= 0) {
         if (numeric >= 1_000_000_000_000) {
-            return numeric;
+            return boundUpstreamRateLimitTimestamp(numeric, now);
         }
         if (numeric >= 1_000_000_000) {
-            return numeric * 1_000;
+            return boundUpstreamRateLimitTimestamp(numeric * 1_000, now);
         }
-        return now + numeric * 1_000;
+        return boundUpstreamRateLimitTimestamp(now + numeric * 1_000, now);
     }
     const timestamp = Date.parse(value);
-    return Number.isFinite(timestamp) ? timestamp : undefined;
+    return boundUpstreamRateLimitTimestamp(timestamp, now);
 }
 function parseRetryAfter(headers, now) {
     const value = headers.get("retry-after");
@@ -645,13 +873,23 @@ function parseRetryAfter(headers, now) {
     }
     const seconds = Number(value.trim());
     if (Number.isFinite(seconds) && seconds >= 0) {
-        return now + seconds * 1_000;
+        return boundUpstreamRateLimitTimestamp(now + seconds * 1_000, now);
     }
     const timestamp = Date.parse(value);
-    return Number.isFinite(timestamp) ? timestamp : undefined;
+    return boundUpstreamRateLimitTimestamp(timestamp, now);
+}
+function boundUpstreamRateLimitTimestamp(timestamp, now) {
+    if (!Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    return Math.min(timestamp, now + MAX_UPSTREAM_RATE_LIMIT_DELAY_MS);
 }
 function toIsoString(timestamp) {
-    return timestamp === undefined || !Number.isFinite(timestamp) ? undefined : new Date(timestamp).toISOString();
+    if (timestamp === undefined || !Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    const date = new Date(timestamp);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
 }
 function metricEndpoint(path) {
     if (/^\/pro\/programs\/.+\/targets$/.test(path)) {
@@ -667,36 +905,65 @@ function metricEndpoint(path) {
 }
 function rateLimitEndpointGroup(path) {
     if (path === "/pro/targets/changes") {
-        return "target_changes";
+        return "change_feeds";
+    }
+    if (path === "/pro/repositories/changes") {
+        return "change_feeds";
     }
     if (/^\/pro\/programs\/.+\/targets$/.test(path)) {
-        return "program_targets";
+        return "target_operations";
     }
-    if (path === "/pro/programs" ||
+    if (path === "/pro/capabilities" ||
+        path === "/pro/programs" ||
         /^\/pro\/programs\/.+/.test(path) ||
         /^\/pro\/opportunities\/[^/]+$/.test(path)) {
         return "programs_and_opportunities";
     }
     if (path === "/pro/targets/search") {
-        return "target_search";
+        return "target_operations";
     }
     if (path === "/pro/targets/export") {
-        return "target_export";
+        return "target_operations";
     }
     return "other";
 }
+function concurrencyEndpointGroup(path) {
+    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes") {
+        return "change_feeds";
+    }
+    if (path === "/pro/targets/export") {
+        return "target_export";
+    }
+    return undefined;
+}
 function endpointConcurrencyLimit(endpointGroup) {
-    return endpointGroup === "target_changes" ? TARGET_CHANGES_CONCURRENCY_LIMIT : undefined;
+    if (endpointGroup === "change_feeds") {
+        return CHANGE_FEED_CONCURRENCY_LIMIT;
+    }
+    if (endpointGroup === "target_export") {
+        return TARGET_EXPORT_CONCURRENCY_LIMIT;
+    }
+    return undefined;
 }
 function isNegativeCacheStatus(status) {
     return status === 404 || status === 405;
 }
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 async function parseResponseBody(response) {
     if (response.status === 204) {
         return null;
     }
     const contentType = response.headers.get("content-type") ?? "";
-    const text = await response.text();
+    const advertisedLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(advertisedLength) && advertisedLength > MAX_RESPONSE_BODY_BYTES) {
+        await response.body?.cancel();
+        throw new Error("BBRadar API response exceeded the MCP response-size limit.");
+    }
+    const text = await readBoundedResponseText(response, MAX_RESPONSE_BODY_BYTES);
     if (text.length === 0) {
         return null;
     }
@@ -710,6 +977,34 @@ async function parseResponseBody(response) {
     }
     return text;
 }
+async function readBoundedResponseText(response, maxBytes) {
+    if (!response.body) {
+        return "";
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let totalBytes = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                await reader.cancel();
+                throw new Error("BBRadar API response exceeded the MCP response-size limit.");
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+        return text;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 function extractRequestId(headers) {
     return (headers.get("x-request-id") ??
         headers.get("x-correlation-id") ??