opencandle 0.1.1 → 0.3.0

package/dist/providers/exa-search.js

@@ -0,0 +1,276 @@
+import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { rateLimiter } from "../infra/rate-limiter.js";
+import { getConfig } from "../config.js";
+import { ProviderCredentialError } from "./provider-credential-error.js";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const EXA_API_URL = "https://api.exa.ai/search";
+const TIMEOUT_MS = 5_000;
+const SNIPPET_MAX_CHARS = 300;
+const CONTEXT_MAX_CHARS = 1_000;
+let requestIdCounter = 0;
+// ---------------------------------------------------------------------------
+// Freshness helpers
+// ---------------------------------------------------------------------------
+function freshnessToMs(freshness) {
+    switch (freshness) {
+        case "hours": return 60 * 60 * 1000;
+        case "day": return 24 * 60 * 60 * 1000;
+        case "week": return 7 * 24 * 60 * 60 * 1000;
+        case "month": return 30 * 24 * 60 * 60 * 1000;
+    }
+}
+function enrichQueryForMcp(query, freshness) {
+    switch (freshness) {
+        case "hours": return `${query} past hour`;
+        case "day": return `${query} past 24 hours`;
+        case "week": return `${query} past week`;
+        case "month": return `${query} past month`;
+    }
+}
+function startPublishedDate(freshness) {
+    return new Date(Date.now() - freshnessToMs(freshness)).toISOString();
+}
+function extractJsonRpcPayload(body, contentType) {
+    // Path 1: plain JSON response
+    if (contentType.includes("application/json")) {
+        return JSON.parse(body);
+    }
+    // Path 2: SSE — scan all data: lines for valid JSON-RPC
+    const dataLines = body.split("\n").filter((line) => line.startsWith("data:"));
+    for (const line of dataLines) {
+        const payload = line.slice(5).trim();
+        if (!payload)
+            continue;
+        try {
+            const candidate = JSON.parse(payload);
+            if (candidate?.result || candidate?.error)
+                return candidate;
+        }
+        catch {
+            // not valid JSON, try next line
+        }
+    }
+    // Path 3: fallback — try parsing entire body
+    try {
+        const candidate = JSON.parse(body);
+        if (candidate?.result || candidate?.error)
+            return candidate;
+    }
+    catch {
+        // not valid JSON
+    }
+    throw new Error("Exa MCP returned empty content");
+}
+function parseMcpResultBlocks(text) {
+    const blocks = text.split(/\n---\n/).filter((b) => b.trim().length > 0);
+    const results = [];
+    for (const block of blocks) {
+        const title = block.match(/^Title: (.+)/m)?.[1]?.trim() ?? "";
+        const url = block.match(/^URL: (.+)/m)?.[1]?.trim() ?? "";
+        if (!url)
+            continue;
+        const published = block.match(/^Published: (.+)/m)?.[1]?.trim() ?? null;
+        // Extract highlights/text content after the header fields
+        let content = "";
+        const hlMatch = block.match(/^Highlights:\n?/m);
+        if (hlMatch?.index != null) {
+            content = block.slice(hlMatch.index + hlMatch[0].length).trim();
+        }
+        const snippet = content.slice(0, SNIPPET_MAX_CHARS);
+        results.push({ title, url, published, snippet });
+    }
+    return results;
+}
+function mapApiResults(results) {
+    return results
+        .filter((r) => r.url)
+        .map((r) => ({
+        title: r.title ?? "",
+        url: r.url,
+        published: r.publishedDate ?? null,
+        snippet: (r.highlights?.join(" ") || r.text || "").slice(0, SNIPPET_MAX_CHARS),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Freshness post-filter
+// ---------------------------------------------------------------------------
+function filterByFreshness(results, freshness) {
+    const cutoff = Date.now() - freshnessToMs(freshness);
+    return results.filter((r) => {
+        if (!r.published)
+            return true; // benefit of the doubt
+        const pubTime = new Date(r.published).getTime();
+        return !isNaN(pubTime) && pubTime >= cutoff;
+    });
+}
+// ---------------------------------------------------------------------------
+// Common helpers
+// ---------------------------------------------------------------------------
+function extractDomain(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return url;
+    }
+}
+function toWebSearchResults(parsed, category) {
+    return parsed.map((r) => ({
+        title: r.title,
+        url: r.url,
+        snippet: r.snippet,
+        source: extractDomain(r.url),
+        published: r.published,
+        category,
+    }));
+}
+function exaCacheKey(query, opts) {
+    return `web:exa:${query}:${opts.category}:${opts.freshness}:${opts.limit}`;
+}
+// ---------------------------------------------------------------------------
+// MCP path
+// ---------------------------------------------------------------------------
+async function exaMcpSearch(query, opts) {
+    const enrichedQuery = enrichQueryForMcp(query, opts.freshness);
+    const response = await fetch(EXA_MCP_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: ++requestIdCounter,
+            method: "tools/call",
+            params: {
+                name: "web_search_exa",
+                arguments: {
+                    query: enrichedQuery,
+                    numResults: opts.limit,
+                    livecrawl: "fallback",
+                    type: "auto",
+                    contextMaxCharacters: CONTEXT_MAX_CHARS,
+                },
+            },
+        }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    // Anti-abuse handling
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!response.ok) {
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("retry-after");
+            throw new Error(`Exa MCP rate limited (429)${retryAfter ? ` — retry after ${retryAfter}s` : ""}`);
+        }
+        if (response.status === 403) {
+            throw new Error("Exa MCP blocked (403) — possible IP-based blocking");
+        }
+        throw new Error(`Exa MCP HTTP ${response.status} ${response.statusText}`);
+    }
+    if (contentType.includes("text/html")) {
+        throw new Error("Exa MCP returned HTML instead of JSON-RPC (possible challenge page)");
+    }
+    const body = await response.text();
+    const payload = extractJsonRpcPayload(body, contentType);
+    if (payload.error) {
+        throw new Error(payload.error.message ?? `Exa MCP error: code ${payload.error.code}`);
+    }
+    const text = payload.result?.content?.find((item) => item.type === "text" && typeof item.text === "string")?.text;
+    if (!text || text.trim().length === 0) {
+        // Legitimate zero results
+        return {
+            query,
+            results: [],
+            resultCount: 0,
+            fetchedAt: new Date().toISOString(),
+            provider: "exa",
+        };
+    }
+    const parsed = parseMcpResultBlocks(text);
+    const filtered = filterByFreshness(parsed, opts.freshness);
+    const results = toWebSearchResults(filtered, opts.category);
+    return {
+        query,
+        results: results.slice(0, opts.limit),
+        resultCount: Math.min(results.length, opts.limit),
+        fetchedAt: new Date().toISOString(),
+        provider: "exa",
+    };
+}
+// ---------------------------------------------------------------------------
+// Direct API path
+// ---------------------------------------------------------------------------
+async function exaApiSearch(query, opts, apiKey) {
+    const response = await fetch(EXA_API_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            query,
+            type: "auto",
+            numResults: opts.limit,
+            startPublishedDate: startPublishedDate(opts.freshness),
+            contents: {
+                text: { maxCharacters: CONTEXT_MAX_CHARS },
+                highlights: true,
+            },
+        }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderCredentialError("exa", "stale", response.status);
+        }
+        const body = await response.text().catch(() => "");
+        throw new Error(`Exa API HTTP ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const data = (await response.json());
+    const parsed = mapApiResults(data.results ?? []);
+    const filtered = filterByFreshness(parsed, opts.freshness);
+    const results = toWebSearchResults(filtered, opts.category);
+    return {
+        query,
+        results: results.slice(0, opts.limit),
+        resultCount: Math.min(results.length, opts.limit),
+        fetchedAt: new Date().toISOString(),
+        provider: "exa",
+    };
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export async function exaSearch(query, opts) {
+    const key = exaCacheKey(query, opts);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    try {
+        await rateLimiter.acquire("exa");
+        const config = getConfig();
+        const envelope = config.exaApiKey
+            ? await exaApiSearch(query, opts, config.exaApiKey)
+            : await exaMcpSearch(query, opts);
+        cache.set(key, envelope, TTL.WEB_SEARCH);
+        return envelope;
+    }
+    catch (error) {
+        // Re-throw abort errors immediately
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        if (error instanceof DOMException && error.name === "TimeoutError")
+            throw error;
+        // Re-throw credential errors so the tool layer can convert them to the
+        // tagged content block. Stale cache must not mask a real auth failure.
+        if (error instanceof ProviderCredentialError)
+            throw error;
+        const stale = cache.getStale(key, STALE_LIMIT.WEB_SEARCH);
+        if (stale)
+            return stale.value;
+        throw error;
+    }
+}
+// Exported for testing
+export { parseMcpResultBlocks, extractJsonRpcPayload, enrichQueryForMcp, filterByFreshness, mapApiResults, };
+//# sourceMappingURL=exa-search.js.map

package/dist/providers/exa-search.js.map

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

package/dist/providers/fear-greed.js

@@ -1,5 +1,5 @@
 import { httpGet } from "../infra/http-client.js";
-import { cache, TTL } from "../infra/cache.js";
+import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
 // alternative.me provides a free crypto Fear & Greed index
 // CNN endpoint (production.dataviz.cnn.io) blocks automated requests (HTTP 418)
 const ENDPOINT = "https://api.alternative.me/fng/?limit=3";
@@ -8,19 +8,27 @@ export async function getFearGreedIndex() {
     const cached = cache.get(cacheKey);
     if (cached)
         return cached;
-    const data = await httpGet(ENDPOINT);
-    const entries = data.data;
-    const current = entries[0];
-    const value = parseInt(current.value, 10);
-    const result = {
-        value,
-        label: current.value_classification,
-        timestamp: Date.now(),
-        previousClose: entries[1] ? parseInt(entries[1].value, 10) : value,
-        weekAgo: null,
-        monthAgo: null,
-    };
-    cache.set(cacheKey, result, TTL.SENTIMENT);
-    return result;
+    try {
+        const data = await httpGet(ENDPOINT);
+        const entries = data.data;
+        const current = entries[0];
+        const value = parseInt(current.value, 10);
+        const result = {
+            value,
+            label: current.value_classification,
+            timestamp: Date.now(),
+            previousClose: entries[1] ? parseInt(entries[1].value, 10) : value,
+            weekAgo: null,
+            monthAgo: null,
+        };
+        cache.set(cacheKey, result, TTL.SENTIMENT);
+        return result;
+    }
+    catch (error) {
+        const stale = cache.getStale(cacheKey, STALE_LIMIT.SENTIMENT);
+        if (stale)
+            return stale.value;
+        throw error;
+    }
 }
 //# sourceMappingURL=fear-greed.js.map

package/dist/providers/fear-greed.js.map

@@ -1 +1 @@
-{"version":3,"file":"fear-greed.js","sourceRoot":"","sources":["../../src/providers/fear-greed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAG/C,2DAA2D;AAC3D,gFAAgF;AAChF,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,QAAQ,GAAG,iBAAiB,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAgB,QAAQ,CAAC,CAAC;IAClD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,MAAM,OAAO,CAA2B,QAAQ,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE1C,MAAM,MAAM,GAAkB;QAC5B,KAAK;QACL,KAAK,EAAE,OAAO,CAAC,oBAAoB;QACnC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK;QAClE,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,IAAI;KACf,CAAC;IAEF,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"fear-greed.js","sourceRoot":"","sources":["../../src/providers/fear-greed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG5D,2DAA2D;AAC3D,gFAAgF;AAChF,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,QAAQ,GAAG,iBAAiB,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAgB,QAAQ,CAAC,CAAC;IAClD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAA2B,QAAQ,CAAC,CAAC;QAE/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE1C,MAAM,MAAM,GAAkB;YAC5B,KAAK;YACL,KAAK,EAAE,OAAO,CAAC,oBAAoB;YACnC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK;YAClE,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;SACf,CAAC;QAEF,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAgB,QAAQ,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;QAC7E,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QAC9B,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/providers/finnhub.d.ts

@@ -0,0 +1,17 @@
+export interface FinnhubArticle {
+    headline: string;
+    summary: string;
+    source: string;
+    datetime: number;
+    url: string;
+    related: string;
+    id: number;
+    category: string;
+    image: string;
+}
+export declare function finnhubDateRange(freshness: "hours" | "day" | "week" | "month"): {
+    from: string;
+    to: string;
+};
+export declare function filterByRelevance(articles: FinnhubArticle[], symbol: string, limit?: number): FinnhubArticle[];
+export declare function getCompanyNews(symbol: string, from: string, to: string, apiKey: string): Promise<FinnhubArticle[]>;

package/dist/providers/finnhub.js

@@ -0,0 +1,94 @@
+import { httpGet, HttpError } from "../infra/http-client.js";
+import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { rateLimiter } from "../infra/rate-limiter.js";
+import { ProviderCredentialError } from "./provider-credential-error.js";
+const FINNHUB_BASE = "https://finnhub.io/api/v1";
+// Ticker → company name mapping for relevance filtering
+const TICKER_NAMES = {
+    AAPL: "apple",
+    MSFT: "microsoft",
+    GOOGL: "google",
+    GOOG: "google",
+    AMZN: "amazon",
+    META: "meta",
+    TSLA: "tesla",
+    NVDA: "nvidia",
+    TSM: "tsmc",
+    BABA: "alibaba",
+    NFLX: "netflix",
+    AMD: "amd",
+    INTC: "intel",
+    CRM: "salesforce",
+    ORCL: "oracle",
+};
+export function finnhubDateRange(freshness) {
+    const now = new Date();
+    const to = formatDate(now);
+    switch (freshness) {
+        case "hours":
+            return { from: to, to };
+        case "day": {
+            const d = new Date(now);
+            d.setDate(d.getDate() - 1);
+            return { from: formatDate(d), to };
+        }
+        case "week": {
+            const d = new Date(now);
+            d.setDate(d.getDate() - 7);
+            return { from: formatDate(d), to };
+        }
+        case "month": {
+            const d = new Date(now);
+            d.setDate(d.getDate() - 30);
+            return { from: formatDate(d), to };
+        }
+    }
+}
+function formatDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+function cacheKey(symbol, from, to) {
+    return `finnhub:news:${symbol}:${from}:${to}`;
+}
+export function filterByRelevance(articles, symbol, limit = 20) {
+    const symLower = symbol.toLowerCase();
+    const companyName = TICKER_NAMES[symbol.toUpperCase()];
+    const filtered = articles.filter((a) => {
+        const hl = a.headline.toLowerCase();
+        const sm = a.summary.toLowerCase();
+        if (hl.includes(symLower) || sm.includes(symLower))
+            return true;
+        if (companyName && (hl.includes(companyName) || sm.includes(companyName)))
+            return true;
+        return false;
+    });
+    // Most recent first, capped
+    return filtered
+        .sort((a, b) => b.datetime - a.datetime)
+        .slice(0, limit);
+}
+export async function getCompanyNews(symbol, from, to, apiKey) {
+    const key = cacheKey(symbol, from, to);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    try {
+        await rateLimiter.acquire("finnhub");
+        const url = `${FINNHUB_BASE}/company-news?symbol=${encodeURIComponent(symbol)}&from=${from}&to=${to}&token=${apiKey}`;
+        const data = await httpGet(url);
+        const articles = Array.isArray(data) ? data : [];
+        const filtered = filterByRelevance(articles, symbol);
+        cache.set(key, filtered, TTL.FINNHUB_NEWS);
+        return filtered;
+    }
+    catch (error) {
+        if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+            throw new ProviderCredentialError("finnhub", "stale", error.status);
+        }
+        const stale = cache.getStale(key, STALE_LIMIT.FINNHUB_NEWS);
+        if (stale)
+            return stale.value;
+        throw error;
+    }
+}
+//# sourceMappingURL=finnhub.js.map

package/dist/providers/finnhub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finnhub.js","sourceRoot":"","sources":["../../src/providers/finnhub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,MAAM,YAAY,GAAG,2BAA2B,CAAC;AAcjD,wDAAwD;AACxD,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,QAAQ;IACd,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,OAAO;IACb,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,SAA6C;IAC5E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAE3B,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;QAC1B,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;QACrC,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;QACrC,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YAC5B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,CAAO;IACzB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc,EAAE,IAAY,EAAE,EAAU;IACxD,OAAO,gBAAgB,MAAM,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,QAA0B,EAC1B,MAAc,EACd,KAAK,GAAG,EAAE;IAEV,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACtC,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAEvD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACrC,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAChE,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACvF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,4BAA4B;IAC5B,OAAO,QAAQ;SACZ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;SACvC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,IAAY,EACZ,EAAU,EACV,MAAc;IAEd,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAmB,GAAG,CAAC,CAAC;IAChD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAErC,MAAM,GAAG,GAAG,GAAG,YAAY,wBAAwB,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,OAAO,EAAE,UAAU,MAAM,EAAE,CAAC;QACtH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAmB,GAAG,CAAC,CAAC;QAElD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAErD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;YACjF,MAAM,IAAI,uBAAuB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAmB,GAAG,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;QAC9E,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QAC9B,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/providers/fred.js

@@ -1,37 +1,57 @@
-import { httpGet } from "../infra/http-client.js";
-import { cache, TTL } from "../infra/cache.js";
+import { httpGet, HttpError } from "../infra/http-client.js";
+import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
+import { ProviderCredentialError } from "./provider-credential-error.js";
 const BASE_URL = "https://api.stlouisfed.org/fred";
 export async function getSeries(seriesId, apiKey, limit = 60) {
     const cacheKey = `fred:series:${seriesId}:${limit}`;
     const cached = cache.get(cacheKey);
     if (cached)
         return cached;
-    await rateLimiter.acquire("fred");
-    // Fetch series metadata and observations in parallel
-    const metaUrl = `${BASE_URL}/series?series_id=${seriesId}&api_key=${apiKey}&file_type=json`;
-    const obsUrl = `${BASE_URL}/series/observations?series_id=${seriesId}&api_key=${apiKey}&file_type=json&sort_order=desc&limit=${limit}`;
-    const [metaData, obsData] = await Promise.all([
-        httpGet(metaUrl),
-        httpGet(obsUrl),
-    ]);
-    const meta = metaData.seriess[0];
-    const observations = obsData.observations
-        .filter((o) => o.value !== ".")
-        .map((o) => ({
-        date: o.date,
-        value: parseFloat(o.value),
-    }))
-        .reverse(); // chronological order
-    const result = {
-        id: meta.id,
-        title: meta.title,
-        observations,
-        units: meta.units,
-        frequency: meta.frequency,
-        lastUpdated: meta.last_updated,
-    };
-    cache.set(cacheKey, result, TTL.MACRO);
-    return result;
+    try {
+        await rateLimiter.acquire("fred");
+        // Fetch series metadata and observations in parallel
+        const metaUrl = `${BASE_URL}/series?series_id=${seriesId}&api_key=${apiKey}&file_type=json`;
+        const obsUrl = `${BASE_URL}/series/observations?series_id=${seriesId}&api_key=${apiKey}&file_type=json&sort_order=desc&limit=${limit}`;
+        const [metaData, obsData] = await Promise.all([
+            httpGet(metaUrl),
+            httpGet(obsUrl),
+        ]);
+        const meta = metaData.seriess[0];
+        const observations = obsData.observations
+            .filter((o) => o.value !== ".")
+            .map((o) => ({
+            date: o.date,
+            value: parseFloat(o.value),
+        }))
+            .reverse(); // chronological order
+        const result = {
+            id: meta.id,
+            title: meta.title,
+            observations,
+            units: meta.units,
+            frequency: meta.frequency,
+            lastUpdated: meta.last_updated,
+        };
+        cache.set(cacheKey, result, TTL.MACRO);
+        return result;
+    }
+    catch (error) {
+        // FRED historically returns 400 with a body like "Bad Request. The value
+        // for variable api_key is not registered..." when the key is invalid. A
+        // separate 400 can also indicate a bad series_id, which is NOT a credential
+        // problem. We only reclassify as credential-related on 401/403 here to
+        // avoid surfacing a `/connect` prompt when the user's real mistake is a
+        // typo in a series id. Bad-FRED-key users will still see the raw error
+        // message in v1; a body-string check can be added later if this becomes a
+        // reported friction.
+        if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+            throw new ProviderCredentialError("fred", "stale", error.status);
+        }
+        const stale = cache.getStale(cacheKey, STALE_LIMIT.MACRO);
+        if (stale)
+            return stale.value;
+        throw error;
+    }
 }
 //# sourceMappingURL=fred.js.map

package/dist/providers/fred.js.map

@@ -1 +1 @@
-{"version":3,"file":"fred.js","sourceRoot":"","sources":["../../src/providers/fred.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,MAAM,QAAQ,GAAG,iCAAiC,CAAC;AAmBnD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,MAAc,EACd,QAAgB,EAAE;IAElB,MAAM,QAAQ,GAAG,eAAe,QAAQ,IAAI,KAAK,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAa,QAAQ,CAAC,CAAC;IAC/C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAElC,qDAAqD;IACrD,MAAM,OAAO,GAAG,GAAG,QAAQ,qBAAqB,QAAQ,YAAY,MAAM,iBAAiB,CAAC;IAC5F,MAAM,MAAM,GAAG,GAAG,QAAQ,kCAAkC,QAAQ,YAAY,MAAM,yCAAyC,KAAK,EAAE,CAAC;IAEvI,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC5C,OAAO,CAAqB,OAAO,CAAC;QACpC,OAAO,CAA2B,MAAM,CAAC;KAC1C,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,YAAY,GAAsB,OAAO,CAAC,YAAY;SACzD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;KAC3B,CAAC,CAAC;SACF,OAAO,EAAE,CAAC,CAAC,sBAAsB;IAEpC,MAAM,MAAM,GAAe;QACzB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY;QACZ,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW,EAAE,IAAI,CAAC,YAAY;KAC/B,CAAC;IAEF,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"fred.js","sourceRoot":"","sources":["../../src/providers/fred.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGzE,MAAM,QAAQ,GAAG,iCAAiC,CAAC;AAmBnD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,MAAc,EACd,QAAgB,EAAE;IAElB,MAAM,QAAQ,GAAG,eAAe,QAAQ,IAAI,KAAK,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAa,QAAQ,CAAC,CAAC;IAC/C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAElC,qDAAqD;QACrD,MAAM,OAAO,GAAG,GAAG,QAAQ,qBAAqB,QAAQ,YAAY,MAAM,iBAAiB,CAAC;QAC5F,MAAM,MAAM,GAAG,GAAG,QAAQ,kCAAkC,QAAQ,YAAY,MAAM,yCAAyC,KAAK,EAAE,CAAC;QAEvI,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC5C,OAAO,CAAqB,OAAO,CAAC;YACpC,OAAO,CAA2B,MAAM,CAAC;SAC1C,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,YAAY,GAAsB,OAAO,CAAC,YAAY;aACzD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;SAC3B,CAAC,CAAC;aACF,OAAO,EAAE,CAAC,CAAC,sBAAsB;QAEpC,MAAM,MAAM,GAAe;YACzB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,YAAY;YACZ,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,YAAY;SAC/B,CAAC;QAEF,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,wEAAwE;QACxE,4EAA4E;QAC5E,uEAAuE;QACvE,wEAAwE;QACxE,uEAAuE;QACvE,0EAA0E;QAC1E,qBAAqB;QACrB,IAAI,KAAK,YAAY,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;YACjF,MAAM,IAAI,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAa,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QAC9B,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/providers/index.d.ts

@@ -5,3 +5,5 @@ export { getCryptoPrice, getCryptoHistory } from "./coingecko.js";
 export { getSubredditPosts, scoreSentiment } from "./reddit.js";
 export { searchFilings, type SECFiling } from "./sec-edgar.js";
 export { getFearGreedIndex } from "./fear-greed.js";
+export { searchWeb, ddgSearch, braveSearch, normalizeFinancialQuery } from "./web-search.js";
+export type { WebSearchOpts } from "./web-search.js";

package/dist/providers/index.js

@@ -5,4 +5,5 @@ export { getCryptoPrice, getCryptoHistory } from "./coingecko.js";
 export { getSubredditPosts, scoreSentiment } from "./reddit.js";
 export { searchFilings } from "./sec-edgar.js";
 export { getFearGreedIndex } from "./fear-greed.js";
+export { searchWeb, ddgSearch, braveSearch, normalizeFinancialQuery } from "./web-search.js";
 //# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChI,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChI,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/providers/provider-credential-error.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderId } from "../onboarding/providers.js";
+export declare class ProviderCredentialError extends Error {
+    readonly provider: ProviderId;
+    readonly reason: "missing" | "stale";
+    readonly httpStatus?: number | undefined;
+    readonly name = "ProviderCredentialError";
+    constructor(provider: ProviderId, reason: "missing" | "stale", httpStatus?: number | undefined);
+}

package/dist/providers/provider-credential-error.js

@@ -0,0 +1,22 @@
+// Typed error thrown by providers when they detect a missing or stale credential.
+//
+// Providers remain pure fetchers that throw on failure — this class is the
+// structured hand-off to the tool layer, where `withCredentialCheck` catches
+// the error and emits a tagged tool-result content string.
+//
+// Keep this module dependency-free (aside from the ProviderId type) so it can
+// be imported from anywhere without pulling in config loading or registry
+// side effects.
+export class ProviderCredentialError extends Error {
+    provider;
+    reason;
+    httpStatus;
+    name = "ProviderCredentialError";
+    constructor(provider, reason, httpStatus) {
+        super(`credential_required:${provider}:${reason}`);
+        this.provider = provider;
+        this.reason = reason;
+        this.httpStatus = httpStatus;
+    }
+}
+//# sourceMappingURL=provider-credential-error.js.map

package/dist/providers/provider-credential-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credential-error.js","sourceRoot":"","sources":["../../src/providers/provider-credential-error.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,2DAA2D;AAC3D,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gBAAgB;AAIhB,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAIrC;IACA;IACA;IALF,IAAI,GAAG,yBAAyB,CAAC;IAE1C,YACW,QAAoB,EACpB,MAA2B,EAC3B,UAAmB;QAE5B,KAAK,CAAC,uBAAuB,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;QAJ1C,aAAQ,GAAR,QAAQ,CAAY;QACpB,WAAM,GAAN,MAAM,CAAqB;QAC3B,eAAU,GAAV,UAAU,CAAS;IAG9B,CAAC;CACF"}

package/dist/providers/reddit.d.ts

@@ -1,5 +1,13 @@
 import type { RedditSentimentResult } from "../types/sentiment.js";
 export declare function getSubredditPosts(subreddit: string, limit?: number): Promise<RedditSentimentResult>;
+export interface RedditComment {
+    id: string;
+    body: string;
+    author: string;
+    score: number;
+    permalink: string;
+}
+export declare function getPostComments(subreddit: string, postId: string, limit?: number): Promise<RedditComment[]>;
 export declare function scoreSentiment(posts: Array<{
     title: string;
 }>): {