@bbradar/mcp 0.2.5 → 0.3.0

package/dist/bbradarClient.js

@@ -1,7 +1,76 @@
 import { randomUUID } from "node:crypto";
+import { requiresActivityQuery } from "./activityContract.js";
+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;
@@ -14,6 +83,7 @@ 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;
@@ -23,6 +93,7 @@ export class BBRadarApiError extends Error {
     cached;
     coalesced;
     cacheExpiresAt;
+    cacheAllowed;
     constructor(params) {
         super(params.message, { cause: params.cause });
         this.name = "BBRadarApiError";
@@ -34,6 +105,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 {
@@ -41,6 +113,8 @@ export class BBRadarClient {
     cache;
     negativeCache;
     inFlight = new Map();
+    sharedRequests = new Map();
+    requestContext = new AsyncLocalStorage();
     endpointMetrics = new Map();
     requestQueue = [];
     endpointRequestQueues = new Map();
@@ -57,6 +131,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);
@@ -265,9 +357,46 @@ export class BBRadarClient {
     getOpportunities(level, query) {
         return this.request({
             path: `/pro/opportunities/${encodeURIComponent(level)}`,
-            query
+            query,
+            ...snapshotAwareReadControls(query, {}, true, this.config.requestTimeoutMs)
         });
     }
+    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 });
+    }
+    getActivityCapabilities(query = {}) {
+        return this.request({ path: "/pro/activity/capabilities", query, cache: false });
+    }
+    getActivitySnapshot() {
+        return this.request({ path: "/pro/activity/snapshot", cache: false });
+    }
+    getActivityRankings(query) {
+        return this.request({ path: "/pro/activity/rankings", query, cache: false });
+    }
+    getActivityChangeDetail(eventId, query) {
+        return this.request({ path: `/pro/activity/events/${encodeURIComponent(eventId)}`, query, cache: false });
+    }
+    getProgramPayouts(programId, query = {}) {
+        return this.request({ path: `/pro/payouts/programs/${encodeProgramIdPath(programId)}`, query, 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",
@@ -278,8 +407,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,
@@ -299,7 +453,7 @@ export class BBRadarClient {
                     this.refreshInBackground(options, method, url, requestKey);
                 }
                 return {
-                    ...cached.value,
+                    ...publicPayload(cached.value),
                     requestId,
                     cached: true,
                     stale: cached.stale,
@@ -320,11 +474,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
@@ -335,27 +489,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, {
@@ -367,14 +514,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");
@@ -387,13 +541,23 @@ export class BBRadarClient {
                 });
             }
         }
-        return this.withRequestSlot(options.path, async () => {
-            const rateLimitBucket = rateLimitEndpointGroup(options.path);
-            this.assertCircuitClosed(requestId, rateLimitBucket);
+        return this.withRequestSlot(options.path, options.query, async () => {
+            const rateLimitBucket = rateLimitEndpointGroup(options.path, options.query);
+            const circuitBucket = activityCircuitBucket(options.path, options.query) ?? rateLimitBucket;
+            if (options.signal?.aborted)
+                throw new BBRadarApiError({ message: "BBRadar API request was cancelled.", requestId, status: 408 });
+            this.assertCircuitClosed(requestId, circuitBucket);
             this.reserveUpstreamRequest(requestId, rateLimitBucket);
             const startedAt = Date.now();
             const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 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 {
@@ -407,7 +571,8 @@ export class BBRadarClient {
                 }
                 const response = await fetch(url, init);
                 status = response.status;
-                this.observeCircuitResponse(rateLimitBucket, response.status);
+                const noStore = /(?:^|,)\s*(?:no-store|no-cache|private)\b/i.test(response.headers.get("cache-control") ?? "");
+                this.observeCircuitResponse(circuitBucket, response.status);
                 this.observeUpstreamRateLimit(rateLimitBucket, response.headers, response.status);
                 const upstreamRequestId = extractRequestId(response.headers);
                 const data = await parseResponseBody(response);
@@ -418,7 +583,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;
@@ -428,7 +594,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;
@@ -440,7 +608,13 @@ export class BBRadarClient {
                 if (error instanceof BBRadarApiError) {
                     throw error;
                 }
-                this.observeCircuitFailure(rateLimitBucket);
+                if (options.signal?.aborted) {
+                    const timedOut = options.signal.reason instanceof Error && options.signal.reason.name === "TimeoutError";
+                    if (timedOut)
+                        this.observeCircuitFailure(circuitBucket);
+                    throw new BBRadarApiError({ message: timedOut ? "BBRadar API tool deadline exceeded." : "BBRadar API request was cancelled.", requestId, status: 408 });
+                }
+                this.observeCircuitFailure(circuitBucket);
                 throw new BBRadarApiError({
                     message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
                     requestId,
@@ -449,9 +623,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)) {
@@ -461,7 +636,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)
@@ -471,21 +651,21 @@ export class BBRadarClient {
             }
         });
     }
-    async withRequestSlot(path, callback) {
-        const endpointGroup = concurrencyEndpointGroup(path);
+    async withRequestSlot(path, query, callback, deadline, requestId, signal) {
+        const endpointGroup = concurrencyEndpointGroup(path, query);
         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;
@@ -503,14 +683,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);
@@ -800,7 +978,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;
@@ -905,6 +1085,20 @@ 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\/activity\/events\/.+/.test(path))
+        return "/pro/activity/events/:event_id";
+    if (/^\/pro\/payouts\/programs\/.+/.test(path))
+        return "/pro/payouts/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";
     }
@@ -916,8 +1110,26 @@ function metricEndpoint(path) {
     }
     return path;
 }
-function rateLimitEndpointGroup(path) {
-    if (path === "/pro/targets/changes") {
+// The API admits Activity-filtered catalog reads in its heavy "changes" group,
+// sharing that quota and in-flight limit with the change feeds.
+function isActivityCatalogRead(path, query = {}) {
+    return (path === "/pro/programs" || path.startsWith("/pro/opportunities/")) && requiresActivityQuery(query);
+}
+function activityCircuitBucket(path, query = {}) {
+    const activityCatalog = isActivityCatalogRead(path, query);
+    // Chronological feeds can exceed their own projection budget while complete
+    // rankings remain healthy. Keep this a finite group, never a caller-keyed map.
+    if ((path === "/pro/activity/rankings" && (query.tab === "status" || query.tab === "all_changes"))
+        || path.startsWith("/pro/activity/events/")
+        || (activityCatalog && query.status_change !== undefined && query.status_change !== null)) {
+        return "activity_chronological";
+    }
+    if (/^\/pro\/(?:activity|payouts)\//.test(path))
+        return "activity_reads";
+    return activityCatalog ? "activity_catalog" : undefined;
+}
+function rateLimitEndpointGroup(path, query) {
+    if (path === "/pro/targets/changes" || /^\/pro\/(?:history|activity|analytics|payouts)\//.test(path) || isActivityCatalogRead(path, query)) {
         return "change_feeds";
     }
     if (path === "/pro/repositories/changes") {
@@ -940,8 +1152,9 @@ function rateLimitEndpointGroup(path) {
     }
     return "other";
 }
-function concurrencyEndpointGroup(path) {
-    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes") {
+function concurrencyEndpointGroup(path, query) {
+    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes" || /^\/pro\/(?:history|activity|analytics|payouts)\//.test(path)
+        || isActivityCatalogRead(path, query)) {
         return "change_feeds";
     }
     if (path === "/pro/targets/export") {
@@ -1073,6 +1286,7 @@ function cloneApiError(error, requestId, coalesced = error instanceof BBRadarApi
         cached: error.cached,
         coalesced,
         cacheExpiresAt: error.cacheExpiresAt,
+        cacheAllowed: error.cacheAllowed,
         cause: error
     });
 }