@debriefer/sources 1.0.1

package/dist/web-search/base.js

@@ -0,0 +1,251 @@
+/**
+ * Abstract base class for web search sources using the template method pattern.
+ *
+ * Subclasses only implement `performSearch()` — the base class handles the
+ * full pipeline: search → score/rank links → fetch pages → extract content →
+ * sanitize → combine with attribution.
+ *
+ * Used by Google, Bing, Brave, and DuckDuckGo search sources.
+ */
+import { BaseResearchSource, } from "@debriefer/core";
+import { fetchPage } from "../shared/fetch-page.js";
+import { extractArticleContent } from "../shared/readability-extract.js";
+import { sanitizeSourceText } from "../shared/sanitize-text.js";
+// ============================================================================
+// WebSearchBase
+// ============================================================================
+/**
+ * Abstract base class for web search sources.
+ *
+ * Implements the template method pattern: subclasses provide `performSearch()`
+ * and this class handles the rest of the pipeline (scoring, fetching,
+ * extracting, sanitizing, combining).
+ */
+export class WebSearchBase extends BaseResearchSource {
+    maxLinksToFollow;
+    minContentLength;
+    domainScores;
+    boostKeywords;
+    penaltyKeywords;
+    blockedDomains;
+    maxLinkCost;
+    linkSelector;
+    customFetchPage;
+    constructor(options = {}) {
+        super(options);
+        this.maxLinksToFollow = options.maxLinksToFollow ?? 3;
+        this.minContentLength = options.minContentLength ?? 200;
+        this.domainScores = options.domainScores ?? {};
+        this.boostKeywords = options.boostKeywords ?? [];
+        this.penaltyKeywords = options.penaltyKeywords ?? [];
+        this.blockedDomains = options.blockedDomains ?? [];
+        this.maxLinkCost = options.maxLinkCost;
+        this.linkSelector = options.linkSelector;
+        this.customFetchPage = options.fetchPage;
+    }
+    /**
+     * Full search pipeline: search → score → fetch → extract → combine.
+     *
+     * @param subject - The research subject
+     * @param signal - Abort signal for cancellation
+     * @returns RawFinding with combined text, or null if no content extracted
+     */
+    async fetchResult(subject, signal) {
+        // 1. Build query and perform search
+        const query = this.buildQuery(subject);
+        const searchResults = await this.performSearch(query, signal);
+        if (searchResults.length === 0) {
+            return null;
+        }
+        // 2. Filter blocked domains
+        const filtered = searchResults.filter((r) => !this.isDomainBlocked(r.url));
+        if (filtered.length === 0) {
+            return null;
+        }
+        // 3. Score & rank links
+        const ranked = this.scoreAndRank(filtered);
+        // 4. Apply custom link selector if provided, then take top N
+        let selectedResults = ranked.map((r) => r.result);
+        if (this.linkSelector) {
+            selectedResults = await this.linkSelector(selectedResults, subject);
+        }
+        const linksToFollow = selectedResults.slice(0, this.maxLinksToFollow);
+        // 5. Fetch and extract content from each page
+        const extractedPages = [];
+        let linksAttempted = 0;
+        let linkCostUsd = 0;
+        for (const result of linksToFollow) {
+            if (signal.aborted)
+                break;
+            if (this.maxLinkCost !== undefined && linkCostUsd >= this.maxLinkCost)
+                break;
+            linksAttempted++;
+            // Use custom fetch if provided, otherwise default pipeline
+            if (this.customFetchPage) {
+                const text = await this.customFetchPage(result.url, signal);
+                if (text && text.length >= this.minContentLength) {
+                    extractedPages.push({
+                        url: result.url,
+                        title: result.title ?? result.url,
+                        text,
+                    });
+                    linkCostUsd += this.estimatedCostPerQuery;
+                }
+                continue;
+            }
+            const pageResult = await fetchPage({ url: result.url, signal });
+            if (pageResult.fetchMethod === "none" || !pageResult.content) {
+                continue;
+            }
+            // Use the actual fetched URL (may be archive.org URL if fallback was used)
+            const actualUrl = pageResult.url || result.url;
+            const extracted = extractArticleContent(pageResult.content, actualUrl);
+            if (!extracted) {
+                continue;
+            }
+            // 6. Filter by minimum content length
+            if (extracted.text.length < this.minContentLength) {
+                continue;
+            }
+            extractedPages.push({
+                url: actualUrl,
+                title: extracted.title ?? result.title ?? result.url,
+                text: extracted.text,
+            });
+            linkCostUsd += this.estimatedCostPerQuery;
+        }
+        if (extractedPages.length === 0) {
+            return null;
+        }
+        // 7. Sanitize each page's text
+        const sanitizedPages = extractedPages.map((page) => ({
+            ...page,
+            text: sanitizeSourceText(page.text),
+        }));
+        // 8. Combine texts with source attribution
+        const combinedText = sanitizedPages
+            .map((page) => `${page.title}\n${page.text}`)
+            .join("\n\n---\n\n");
+        // 9. Return RawFinding
+        return {
+            text: combinedText,
+            confidence: -1,
+            costUsd: this.estimatedCostPerQuery + linkCostUsd,
+            url: extractedPages[0].url,
+            metadata: {
+                searchEngine: this.name,
+                linksFollowed: linksAttempted,
+                pagesExtracted: extractedPages.length,
+                urls: extractedPages.map((p) => p.url),
+            },
+        };
+    }
+    /**
+     * Score and rank search results by relevance.
+     *
+     * Scoring:
+     * - Base: 50 - index (preserves search engine ordering)
+     * - + domainScores[domain] if hostname matches
+     * - + boost for each boostKeyword found in title+snippet
+     * - - penalty for each penaltyKeyword found in title+snippet
+     */
+    scoreAndRank(results) {
+        const scored = results.map((result, index) => {
+            let score = 50 - index;
+            // Domain score bonus
+            let hostname = null;
+            try {
+                hostname = new URL(result.url).hostname;
+            }
+            catch {
+                // Invalid URL — skip domain scoring
+            }
+            for (const [domain, domainScore] of Object.entries(this.domainScores)) {
+                if (!hostname)
+                    break;
+                if (this.hostnameMatchesDomain(hostname, domain)) {
+                    score += domainScore;
+                    break;
+                }
+            }
+            // Boost keywords
+            const combined = `${result.title} ${result.snippet}`.toLowerCase();
+            for (const { keyword, boost } of this.boostKeywords) {
+                if (combined.includes(keyword.toLowerCase())) {
+                    score += boost;
+                }
+            }
+            // Penalty keywords
+            for (const { keyword, penalty } of this.penaltyKeywords) {
+                if (combined.includes(keyword.toLowerCase())) {
+                    score -= penalty;
+                }
+            }
+            return { result, score };
+        });
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        return scored;
+    }
+    /**
+     * Check whether a URL should be excluded (blocked domain or unsafe URL).
+     * Blocks: non-http(s) schemes, localhost, private IP ranges, and user-specified domains.
+     */
+    isDomainBlocked(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return true; // Unparseable URLs are blocked
+        }
+        // Only allow http and https
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return true;
+        }
+        // Block localhost, private IPs, and link-local addresses (SSRF prevention)
+        // Normalize IPv4-mapped IPv6 (e.g., ::ffff:127.0.0.1) to plain IPv4
+        let hostname = parsed.hostname;
+        const mappedMatch = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(hostname);
+        if (mappedMatch) {
+            hostname = mappedMatch[1];
+        }
+        if (hostname === "localhost" ||
+            hostname.startsWith("127.") || // 127.0.0.0/8 loopback
+            hostname === "::1" || // IPv6 loopback
+            hostname === "[::1]" || // IPv6 loopback (bracketed form)
+            hostname.startsWith("10.") || // RFC 1918
+            hostname.startsWith("192.168.") || // RFC 1918
+            hostname.startsWith("169.254.") || // Link-local / cloud metadata (169.254.169.254)
+            hostname === "0.0.0.0" ||
+            hostname.endsWith(".local") ||
+            (hostname.includes(":") && hostname.startsWith("fc")) || // IPv6 unique local (fc00::/7)
+            (hostname.includes(":") && hostname.startsWith("fd")) || // IPv6 unique local (fc00::/7)
+            (hostname.includes(":") && hostname.startsWith("fe80")) || // IPv6 link-local (fe80::/10)
+            this.isPrivate172(hostname)) {
+            return true;
+        }
+        return this.blockedDomains.some((domain) => this.hostnameMatchesDomain(hostname, domain));
+    }
+    /**
+     * Check if a hostname matches a domain (exact or subdomain match).
+     * Normalizes domain to lowercase since URL.hostname is always lowercase.
+     *
+     * "www.example.com" matches "example.com"
+     * "sub.example.com" matches "example.com"
+     * "example.com" matches "example.com"
+     * "notexample.com" does NOT match "example.com"
+     */
+    hostnameMatchesDomain(hostname, domain) {
+        const d = domain.toLowerCase();
+        return hostname === d || hostname.endsWith("." + d);
+    }
+    /** Check if hostname is in the 172.16.0.0–172.31.255.255 private range (RFC 1918). */
+    isPrivate172(hostname) {
+        if (!hostname.startsWith("172."))
+            return false;
+        const secondOctet = parseInt(hostname.split(".")[1], 10);
+        return secondOctet >= 16 && secondOctet <= 31;
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/web-search/base.js.map

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

package/dist/web-search/bing.d.ts

@@ -0,0 +1,21 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase, type WebSearchOptions, type WebSearchResult } from "./base.js";
+export interface BingSearchOptions extends WebSearchOptions {
+    apiKey?: string;
+    maxResults?: number;
+}
+export declare class BingSearchSource extends WebSearchBase {
+    readonly name = "Bing Search";
+    readonly type = "bing-search";
+    readonly reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    readonly domain = "api.bing.microsoft.com";
+    readonly isFree = false;
+    readonly estimatedCostPerQuery = 0.003;
+    private apiKey;
+    private maxResults;
+    constructor(options?: BingSearchOptions);
+    isAvailable(): boolean;
+    protected performSearch(query: string, signal: AbortSignal): Promise<WebSearchResult[]>;
+}
+export declare function bingSearch(options?: BingSearchOptions): BingSearchSource;
+//# sourceMappingURL=bing.d.ts.map

package/dist/web-search/bing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing.d.ts","sourceRoot":"","sources":["../../src/web-search/bing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAItF,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,QAAQ,CAAC,IAAI,iBAAgB;IAC7B,QAAQ,CAAC,IAAI,iBAAgB;IAC7B,QAAQ,CAAC,eAAe,qCAAoC;IAC5D,QAAQ,CAAC,MAAM,4BAA2B;IAC1C,QAAQ,CAAC,MAAM,SAAQ;IACvB,QAAQ,CAAC,qBAAqB,SAAQ;IAEtC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAQ;gBAEd,OAAO,GAAE,iBAAsB;IAMlC,WAAW,IAAI,OAAO;cAIf,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAoC9F;AAED,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAExE"}

package/dist/web-search/bing.js

@@ -0,0 +1,53 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase } from "./base.js";
+const BING_SEARCH_URL = "https://api.bing.microsoft.com/v7.0/search";
+export class BingSearchSource extends WebSearchBase {
+    name = "Bing Search";
+    type = "bing-search";
+    reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    domain = "api.bing.microsoft.com";
+    isFree = false;
+    estimatedCostPerQuery = 0.003;
+    apiKey;
+    maxResults;
+    constructor(options = {}) {
+        super({ rateLimitMs: 500, ...options });
+        this.apiKey = options.apiKey ?? process.env.BING_SEARCH_API_KEY;
+        this.maxResults = options.maxResults ?? 20;
+    }
+    isAvailable() {
+        return Boolean(this.apiKey);
+    }
+    async performSearch(query, signal) {
+        if (!this.apiKey)
+            return [];
+        const url = `${BING_SEARCH_URL}?q=${encodeURIComponent(query)}&count=${this.maxResults}&mkt=en-US&responseFilter=Webpages,News`;
+        const response = await fetch(url, {
+            headers: { "Ocp-Apim-Subscription-Key": this.apiKey },
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Bing Search error: HTTP ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        const results = [];
+        const seenUrls = new Set();
+        for (const item of data.webPages?.value ?? []) {
+            if (seenUrls.has(item.url))
+                continue;
+            seenUrls.add(item.url);
+            results.push({ url: item.url, title: item.name, snippet: item.snippet });
+        }
+        for (const item of data.news?.value ?? []) {
+            if (seenUrls.has(item.url))
+                continue;
+            seenUrls.add(item.url);
+            results.push({ url: item.url, title: item.name, snippet: item.description });
+        }
+        return results;
+    }
+}
+export function bingSearch(options) {
+    return new BingSearchSource(options);
+}
+//# sourceMappingURL=bing.js.map

package/dist/web-search/bing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing.js","sourceRoot":"","sources":["../../src/web-search/bing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAA+C,MAAM,WAAW,CAAA;AAEtF,MAAM,eAAe,GAAG,4CAA4C,CAAA;AAOpE,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IACxC,IAAI,GAAG,aAAa,CAAA;IACpB,IAAI,GAAG,aAAa,CAAA;IACpB,eAAe,GAAG,eAAe,CAAC,iBAAiB,CAAA;IACnD,MAAM,GAAG,wBAAwB,CAAA;IACjC,MAAM,GAAG,KAAK,CAAA;IACd,qBAAqB,GAAG,KAAK,CAAA;IAE9B,MAAM,CAAoB;IAC1B,UAAU,CAAQ;IAE1B,YAAY,UAA6B,EAAE;QACzC,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAA;QAC/D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAA;IAC5C,CAAC;IAEQ,WAAW;QAClB,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC7B,CAAC;IAES,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,MAAmB;QAC9D,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,CAAA;QAE3B,MAAM,GAAG,GAAG,GAAG,eAAe,MAAM,kBAAkB,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,UAAU,yCAAyC,CAAA;QAE/H,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE,EAAE,2BAA2B,EAAE,IAAI,CAAC,MAAM,EAAE;YACrD,MAAM;SACP,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;QACtF,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAGlC,CAAA;QAED,MAAM,OAAO,GAAsB,EAAE,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;QAElC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YAC9C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,SAAQ;YACpC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;QAC1E,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YAC1C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,SAAQ;YACpC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;QAC9E,CAAC;QAED,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAA2B;IACpD,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAA;AACtC,CAAC"}

package/dist/web-search/brave.d.ts

@@ -0,0 +1,21 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase, type WebSearchOptions, type WebSearchResult } from "./base.js";
+export interface BraveSearchOptions extends WebSearchOptions {
+    apiKey?: string;
+    maxResults?: number;
+}
+export declare class BraveSearchSource extends WebSearchBase {
+    readonly name = "Brave Search";
+    readonly type = "brave-search";
+    readonly reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    readonly domain = "api.search.brave.com";
+    readonly isFree = false;
+    readonly estimatedCostPerQuery = 0.005;
+    private apiKey;
+    private maxResults;
+    constructor(options?: BraveSearchOptions);
+    isAvailable(): boolean;
+    protected performSearch(query: string, signal: AbortSignal): Promise<WebSearchResult[]>;
+}
+export declare function braveSearch(options?: BraveSearchOptions): BraveSearchSource;
+//# sourceMappingURL=brave.d.ts.map

package/dist/web-search/brave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.d.ts","sourceRoot":"","sources":["../../src/web-search/brave.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAItF,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,kBAAiB;IAC9B,QAAQ,CAAC,IAAI,kBAAiB;IAC9B,QAAQ,CAAC,eAAe,qCAAoC;IAC5D,QAAQ,CAAC,MAAM,0BAAyB;IACxC,QAAQ,CAAC,MAAM,SAAQ;IACvB,QAAQ,CAAC,qBAAqB,SAAQ;IAEtC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAQ;gBAEd,OAAO,GAAE,kBAAuB;IAMnC,WAAW,IAAI,OAAO;cAIf,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAuC9F;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CAE3E"}

package/dist/web-search/brave.js

@@ -0,0 +1,56 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase } from "./base.js";
+const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
+export class BraveSearchSource extends WebSearchBase {
+    name = "Brave Search";
+    type = "brave-search";
+    reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    domain = "api.search.brave.com";
+    isFree = false;
+    estimatedCostPerQuery = 0.005;
+    apiKey;
+    maxResults;
+    constructor(options = {}) {
+        super({ rateLimitMs: 500, ...options });
+        this.apiKey = options.apiKey ?? process.env.BRAVE_SEARCH_API_KEY;
+        this.maxResults = options.maxResults ?? 20;
+    }
+    isAvailable() {
+        return Boolean(this.apiKey);
+    }
+    async performSearch(query, signal) {
+        if (!this.apiKey)
+            return [];
+        const url = `${BRAVE_SEARCH_URL}?q=${encodeURIComponent(query)}&count=${this.maxResults}&search_lang=en`;
+        const response = await fetch(url, {
+            headers: {
+                "X-Subscription-Token": this.apiKey,
+                Accept: "application/json",
+            },
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Brave Search error: HTTP ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        const results = [];
+        const seenUrls = new Set();
+        for (const item of data.web?.results ?? []) {
+            if (seenUrls.has(item.url))
+                continue;
+            seenUrls.add(item.url);
+            results.push({ url: item.url, title: item.title, snippet: item.description });
+        }
+        for (const item of data.news?.results ?? []) {
+            if (seenUrls.has(item.url))
+                continue;
+            seenUrls.add(item.url);
+            results.push({ url: item.url, title: item.title, snippet: item.description });
+        }
+        return results;
+    }
+}
+export function braveSearch(options) {
+    return new BraveSearchSource(options);
+}
+//# sourceMappingURL=brave.js.map

package/dist/web-search/brave.js.map

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

package/dist/web-search/duckduckgo.d.ts

@@ -0,0 +1,15 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase, type WebSearchOptions, type WebSearchResult } from "./base.js";
+export type DuckDuckGoSourceOptions = WebSearchOptions;
+export declare class DuckDuckGoSearchSource extends WebSearchBase {
+    readonly name = "DuckDuckGo";
+    readonly type = "duckduckgo-search";
+    readonly reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    readonly domain = "html.duckduckgo.com";
+    readonly isFree = true;
+    readonly estimatedCostPerQuery = 0;
+    constructor(options?: DuckDuckGoSourceOptions);
+    protected performSearch(query: string, signal: AbortSignal): Promise<WebSearchResult[]>;
+}
+export declare function duckduckgoSearch(options?: DuckDuckGoSourceOptions): DuckDuckGoSearchSource;
+//# sourceMappingURL=duckduckgo.d.ts.map

package/dist/web-search/duckduckgo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo.d.ts","sourceRoot":"","sources":["../../src/web-search/duckduckgo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAGtF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAA;AAEtD,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,IAAI,gBAAe;IAC5B,QAAQ,CAAC,IAAI,uBAAsB;IACnC,QAAQ,CAAC,eAAe,qCAAoC;IAC5D,QAAQ,CAAC,MAAM,yBAAwB;IACvC,QAAQ,CAAC,MAAM,QAAO;IACtB,QAAQ,CAAC,qBAAqB,KAAI;gBAEtB,OAAO,GAAE,uBAA4B;cAIjC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAG9F;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,sBAAsB,CAE1F"}

package/dist/web-search/duckduckgo.js

@@ -0,0 +1,21 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase } from "./base.js";
+import { searchDuckDuckGo } from "../shared/duckduckgo-search.js";
+export class DuckDuckGoSearchSource extends WebSearchBase {
+    name = "DuckDuckGo";
+    type = "duckduckgo-search";
+    reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    domain = "html.duckduckgo.com";
+    isFree = true;
+    estimatedCostPerQuery = 0;
+    constructor(options = {}) {
+        super({ rateLimitMs: 1000, ...options });
+    }
+    async performSearch(query, signal) {
+        return searchDuckDuckGo({ query, signal });
+    }
+}
+export function duckduckgoSearch(options) {
+    return new DuckDuckGoSearchSource(options);
+}
+//# sourceMappingURL=duckduckgo.js.map

package/dist/web-search/duckduckgo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo.js","sourceRoot":"","sources":["../../src/web-search/duckduckgo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAA+C,MAAM,WAAW,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAIjE,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IAC9C,IAAI,GAAG,YAAY,CAAA;IACnB,IAAI,GAAG,mBAAmB,CAAA;IAC1B,eAAe,GAAG,eAAe,CAAC,iBAAiB,CAAA;IACnD,MAAM,GAAG,qBAAqB,CAAA;IAC9B,MAAM,GAAG,IAAI,CAAA;IACb,qBAAqB,GAAG,CAAC,CAAA;IAElC,YAAY,UAAmC,EAAE;QAC/C,KAAK,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;IAC1C,CAAC;IAES,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,MAAmB;QAC9D,OAAO,gBAAgB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC5C,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAiC;IAChE,OAAO,IAAI,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC5C,CAAC"}

package/dist/web-search/google.d.ts

@@ -0,0 +1,24 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase, type WebSearchOptions, type WebSearchResult } from "./base.js";
+export interface GoogleSearchOptions extends WebSearchOptions {
+    apiKey?: string;
+    cx?: string;
+    /** Number of results (1–10, Google CSE limit). Default: 10. */
+    maxResults?: number;
+}
+export declare class GoogleSearchSource extends WebSearchBase {
+    readonly name = "Google Search";
+    readonly type = "google-search";
+    readonly reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    readonly domain = "www.googleapis.com";
+    readonly isFree = false;
+    readonly estimatedCostPerQuery = 0.005;
+    private apiKey;
+    private cx;
+    private maxResults;
+    constructor(options?: GoogleSearchOptions);
+    isAvailable(): boolean;
+    protected performSearch(query: string, signal: AbortSignal): Promise<WebSearchResult[]>;
+}
+export declare function googleSearch(options?: GoogleSearchOptions): GoogleSearchSource;
+//# sourceMappingURL=google.d.ts.map

package/dist/web-search/google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../src/web-search/google.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAItF,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,QAAQ,CAAC,IAAI,mBAAkB;IAC/B,QAAQ,CAAC,IAAI,mBAAkB;IAC/B,QAAQ,CAAC,eAAe,qCAAoC;IAC5D,QAAQ,CAAC,MAAM,wBAAuB;IACtC,QAAQ,CAAC,MAAM,SAAQ;IACvB,QAAQ,CAAC,qBAAqB,SAAQ;IAEtC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,UAAU,CAAQ;gBAEd,OAAO,GAAE,mBAAwB;IAOpC,WAAW,IAAI,OAAO;cAIf,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CA2B9F;AAED,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAE9E"}

package/dist/web-search/google.js

@@ -0,0 +1,48 @@
+import { ReliabilityTier } from "@debriefer/core";
+import { WebSearchBase } from "./base.js";
+const GOOGLE_CSE_URL = "https://www.googleapis.com/customsearch/v1";
+export class GoogleSearchSource extends WebSearchBase {
+    name = "Google Search";
+    type = "google-search";
+    reliabilityTier = ReliabilityTier.SEARCH_AGGREGATOR;
+    domain = "www.googleapis.com";
+    isFree = false;
+    estimatedCostPerQuery = 0.005;
+    apiKey;
+    cx;
+    maxResults;
+    constructor(options = {}) {
+        super({ rateLimitMs: 500, ...options });
+        this.apiKey = options.apiKey ?? process.env.GOOGLE_SEARCH_API_KEY;
+        this.cx = options.cx ?? process.env.GOOGLE_SEARCH_CX;
+        this.maxResults = Math.min(Math.max(options.maxResults ?? 10, 1), 10);
+    }
+    isAvailable() {
+        return Boolean(this.apiKey && this.cx);
+    }
+    async performSearch(query, signal) {
+        if (!this.apiKey || !this.cx)
+            return [];
+        const url = new URL(GOOGLE_CSE_URL);
+        url.searchParams.set("key", this.apiKey);
+        url.searchParams.set("cx", this.cx);
+        url.searchParams.set("q", query);
+        url.searchParams.set("num", String(this.maxResults));
+        const response = await fetch(url.toString(), { signal });
+        if (!response.ok) {
+            throw new Error(`Google CSE error: HTTP ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (!data.items || data.items.length === 0)
+            return [];
+        return data.items.map((item) => ({
+            url: item.link,
+            title: item.title,
+            snippet: item.snippet,
+        }));
+    }
+}
+export function googleSearch(options) {
+    return new GoogleSearchSource(options);
+}
+//# sourceMappingURL=google.js.map

package/dist/web-search/google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.js","sourceRoot":"","sources":["../../src/web-search/google.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAA+C,MAAM,WAAW,CAAA;AAEtF,MAAM,cAAc,GAAG,4CAA4C,CAAA;AASnE,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC1C,IAAI,GAAG,eAAe,CAAA;IACtB,IAAI,GAAG,eAAe,CAAA;IACtB,eAAe,GAAG,eAAe,CAAC,iBAAiB,CAAA;IACnD,MAAM,GAAG,oBAAoB,CAAA;IAC7B,MAAM,GAAG,KAAK,CAAA;IACd,qBAAqB,GAAG,KAAK,CAAA;IAE9B,MAAM,CAAoB;IAC1B,EAAE,CAAoB;IACtB,UAAU,CAAQ;IAE1B,YAAY,UAA+B,EAAE;QAC3C,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAA;QACjE,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;QACpD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACvE,CAAC;IAEQ,WAAW;QAClB,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC,CAAA;IACxC,CAAC;IAES,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,MAAmB;QAC9D,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,CAAA;QAEvC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAA;QACnC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QACxC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;QACnC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAChC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAA;QAEpD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAA;QAExD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;QACrF,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAElC,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAErD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC/B,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC,CAAA;IACL,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAA;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@debriefer/sources",
+  "version": "1.0.1",
+  "description": "Built-in research sources for debriefer: Wikipedia, Wikidata, web search, news, archives, and more",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "research",
+    "wikipedia",
+    "wikidata",
+    "web-scraping",
+    "news",
+    "archives",
+    "debriefer"
+  ],
+  "author": "Chris Henderson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenders/debriefer.git",
+    "directory": "packages/sources"
+  },
+  "homepage": "https://github.com/chenders/debriefer#readme",
+  "bugs": {
+    "url": "https://github.com/chenders/debriefer/issues"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6",
+    "@debriefer/core": ">=1.0.0",
+    "he": "^1",
+    "jsdom": "^28",
+    "wtf_wikipedia": "^10"
+  },
+  "optionalDependencies": {
+    "fingerprint-injector": "^2",
+    "playwright-core": "^1.50"
+  },
+  "devDependencies": {
+    "@types/he": "^1.2.3",
+    "@types/jsdom": "^28.0.0"
+  }
+}