@debriefer/sources 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { htmlToText, htmlToTextClean, decodeHtmlEntities, looksLikeCode, stripCodeFromText, } from "./shared/html-utils.js";
+export { extractArticleContent } from "./shared/readability-extract.js";
+export type { ArticleExtractionResult } from "./shared/readability-extract.js";
+export { sanitizeSourceText } from "./shared/sanitize-text.js";
+export { splitSearchWords } from "./shared/search-utils.js";
+export { WikidataSource, wikidata, escapeSparql, isValidLabel, getValidLabel, filterValidLabels, } from "./structured/wikidata.js";
+export type { WikidataOptions, SparqlQueryBuilder, SparqlResultParser, SparqlBinding, SparqlResponse, } from "./structured/wikidata.js";
+export { WikipediaSource, wikipedia } from "./structured/wikipedia.js";
+export type { WikipediaOptions, WikipediaSection, SectionFilter, AsyncSectionFilter, } from "./structured/wikipedia.js";
+export { fetchPage } from "./shared/fetch-page.js";
+export type { FetchPageOptions, FetchPageResult } from "./shared/fetch-page.js";
+export { searchDuckDuckGo, isDuckDuckGoCaptcha, extractUrlsFromDuckDuckGoHtml, cleanDuckDuckGoUrl, } from "./shared/duckduckgo-search.js";
+export type { DuckDuckGoSearchOptions, SearchResult } from "./shared/duckduckgo-search.js";
+export { WebSearchBase } from "./web-search/base.js";
+export type { WebSearchOptions, LinkSelectionOptions, WebSearchResult } from "./web-search/base.js";
+export { GoogleSearchSource, googleSearch } from "./web-search/google.js";
+export type { GoogleSearchOptions } from "./web-search/google.js";
+export { BingSearchSource, bingSearch } from "./web-search/bing.js";
+export type { BingSearchOptions } from "./web-search/bing.js";
+export { BraveSearchSource, braveSearch } from "./web-search/brave.js";
+export type { BraveSearchOptions } from "./web-search/brave.js";
+export { DuckDuckGoSearchSource, duckduckgoSearch } from "./web-search/duckduckgo.js";
+export type { DuckDuckGoSourceOptions } from "./web-search/duckduckgo.js";
+export { SiteSearchSource, pickBestUrl } from "./news/site-search-source.js";
+export type { SiteSearchConfig } from "./news/site-search-source.js";
+export { apNews, bbcNews, reuters, npr, independent, telegraph, washingtonPost, laTimes, time, newYorker, pbs, britannica, rollingStone, smithsonian, nationalGeographic, historyCom, tcm, allMusic, people, biographyCom, legacy, } from "./news/sources.js";
+export { GuardianSource, guardian } from "./news/guardian.js";
+export type { GuardianOptions } from "./news/guardian.js";
+export { NYTimesSource, nytimes } from "./news/nytimes.js";
+export type { NYTimesOptions } from "./news/nytimes.js";
+export { GoogleBooksSource, googleBooks } from "./books/google-books.js";
+export type { GoogleBooksOptions } from "./books/google-books.js";
+export { OpenLibrarySource, openLibrary } from "./books/open-library.js";
+export type { OpenLibraryOptions } from "./books/open-library.js";
+export { ChroniclingAmericaSource, chroniclingAmerica } from "./archives/chronicling-america.js";
+export type { ChroniclingAmericaOptions } from "./archives/chronicling-america.js";
+export { TroveSource, trove } from "./archives/trove.js";
+export type { TroveOptions } from "./archives/trove.js";
+export { EuropeanaSource, europeana } from "./archives/europeana.js";
+export type { EuropeanaOptions } from "./archives/europeana.js";
+export { InternetArchiveSource, internetArchive } from "./archives/internet-archive.js";
+export type { InternetArchiveOptions } from "./archives/internet-archive.js";
+export { FindAGraveSource, findAGrave } from "./obituary/find-a-grave.js";
+export type { FindAGraveOptions } from "./obituary/find-a-grave.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,35 @@
+// Shared utilities — consumers may need these for custom sources
+export { htmlToText, htmlToTextClean, decodeHtmlEntities, looksLikeCode, stripCodeFromText, } from "./shared/html-utils.js";
+export { extractArticleContent } from "./shared/readability-extract.js";
+export { sanitizeSourceText } from "./shared/sanitize-text.js";
+export { splitSearchWords } from "./shared/search-utils.js";
+// Structured data sources
+export { WikidataSource, wikidata, escapeSparql, isValidLabel, getValidLabel, filterValidLabels, } from "./structured/wikidata.js";
+export { WikipediaSource, wikipedia } from "./structured/wikipedia.js";
+// Shared utilities — fetch and search
+export { fetchPage } from "./shared/fetch-page.js";
+export { searchDuckDuckGo, isDuckDuckGoCaptcha, extractUrlsFromDuckDuckGoHtml, cleanDuckDuckGoUrl, } from "./shared/duckduckgo-search.js";
+// Web search base (for building custom search sources)
+export { WebSearchBase } from "./web-search/base.js";
+// Web search sources
+export { GoogleSearchSource, googleSearch } from "./web-search/google.js";
+export { BingSearchSource, bingSearch } from "./web-search/bing.js";
+export { BraveSearchSource, braveSearch } from "./web-search/brave.js";
+export { DuckDuckGoSearchSource, duckduckgoSearch } from "./web-search/duckduckgo.js";
+// News sources — site-search based
+export { SiteSearchSource, pickBestUrl } from "./news/site-search-source.js";
+export { apNews, bbcNews, reuters, npr, independent, telegraph, washingtonPost, laTimes, time, newYorker, pbs, britannica, rollingStone, smithsonian, nationalGeographic, historyCom, tcm, allMusic, people, biographyCom, legacy, } from "./news/sources.js";
+// News sources — API based
+export { GuardianSource, guardian } from "./news/guardian.js";
+export { NYTimesSource, nytimes } from "./news/nytimes.js";
+// Book sources
+export { GoogleBooksSource, googleBooks } from "./books/google-books.js";
+export { OpenLibrarySource, openLibrary } from "./books/open-library.js";
+// Archive sources
+export { ChroniclingAmericaSource, chroniclingAmerica } from "./archives/chronicling-america.js";
+export { TroveSource, trove } from "./archives/trove.js";
+export { EuropeanaSource, europeana } from "./archives/europeana.js";
+export { InternetArchiveSource, internetArchive } from "./archives/internet-archive.js";
+// Obituary sources
+export { FindAGraveSource, findAGrave } from "./obituary/find-a-grave.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,EACL,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,GAClB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAEvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,0BAA0B;AAC1B,OAAO,EACL,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,0BAA0B,CAAA;AASjC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAQtE,sCAAsC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAElD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,+BAA+B,CAAA;AAGtC,uDAAuD;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGpD,qBAAqB;AACrB,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAEzE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEnE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEtE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAGrF,mCAAmC;AACnC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAE5E,OAAO,EACL,MAAM,EACN,OAAO,EACP,OAAO,EACP,GAAG,EACH,WAAW,EACX,SAAS,EACT,cAAc,EACd,OAAO,EACP,IAAI,EACJ,SAAS,EACT,GAAG,EACH,UAAU,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,GAAG,EACH,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,MAAM,GACP,MAAM,mBAAmB,CAAA;AAE1B,2BAA2B;AAC3B,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7D,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAG1D,eAAe;AACf,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAExE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAGxE,kBAAkB;AAClB,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAA;AAEhG,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAEpE,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAGvF,mBAAmB;AACnB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/news/guardian.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The Guardian API source.
+ *
+ * Queries the Guardian Content API for biographical/profile articles
+ * about a research subject. Picks the best article by matching
+ * biographical keywords in title, then body text, falling back to
+ * the first result.
+ *
+ * Requires a Guardian API key (https://open-platform.theguardian.com/).
+ */
+import { BaseResearchSource, ReliabilityTier, type BaseSourceOptions, type ResearchSubject, type RawFinding } from "@debriefer/core";
+export interface GuardianOptions extends BaseSourceOptions {
+    /** Guardian API key. Defaults to process.env.GUARDIAN_API_KEY. */
+    apiKey?: string;
+}
+/**
+ * Research source backed by the Guardian Content API.
+ *
+ * Searches for biographical/profile articles about a subject,
+ * picks the best match by keyword scoring, and returns the
+ * sanitized body text.
+ */
+export declare class GuardianSource extends BaseResearchSource<ResearchSubject> {
+    readonly name = "The Guardian";
+    readonly type = "guardian";
+    readonly reliabilityTier = ReliabilityTier.TIER_1_NEWS;
+    readonly domain = "content.guardianapis.com";
+    readonly isFree = true;
+    readonly estimatedCostPerQuery = 0;
+    private apiKey;
+    constructor(options?: GuardianOptions);
+    isAvailable(): boolean;
+    protected fetchResult(subject: ResearchSubject, signal: AbortSignal): Promise<RawFinding | null>;
+    /**
+     * Find the best article from Guardian search results.
+     *
+     * Priority:
+     * 1. Article with a bio keyword in the title
+     * 2. Article with a bio keyword in the body/standfirst
+     * 3. First result as fallback
+     */
+    private findBestArticle;
+}
+/**
+ * Create a Guardian API source instance.
+ *
+ * @param options - Guardian-specific options (apiKey, rateLimitMs, etc.)
+ * @returns A configured GuardianSource
+ */
+export declare function guardian(options?: GuardianOptions): GuardianSource;
+//# sourceMappingURL=guardian.d.ts.map

package/dist/news/guardian.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian.d.ts","sourceRoot":"","sources":["../../src/news/guardian.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAA;AA0BxB,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAyBD;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,kBAAkB,CAAC,eAAe,CAAC;IACrE,QAAQ,CAAC,IAAI,kBAAiB;IAC9B,QAAQ,CAAC,IAAI,cAAa;IAC1B,QAAQ,CAAC,eAAe,+BAA8B;IACtD,QAAQ,CAAC,MAAM,8BAA6B;IAC5C,QAAQ,CAAC,MAAM,QAAO;IACtB,QAAQ,CAAC,qBAAqB,KAAI;IAElC,OAAO,CAAC,MAAM,CAAoB;gBAEtB,OAAO,GAAE,eAAoB;IAKhC,WAAW,IAAI,OAAO;cAIf,WAAW,CACzB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA4C7B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;CAoBxB;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,CAElE"}

package/dist/news/guardian.js

@@ -0,0 +1,131 @@
+/**
+ * The Guardian API source.
+ *
+ * Queries the Guardian Content API for biographical/profile articles
+ * about a research subject. Picks the best article by matching
+ * biographical keywords in title, then body text, falling back to
+ * the first result.
+ *
+ * Requires a Guardian API key (https://open-platform.theguardian.com/).
+ */
+import { BaseResearchSource, ReliabilityTier, } from "@debriefer/core";
+import { sanitizeSourceText } from "../shared/sanitize-text.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const GUARDIAN_API_URL = "https://content.guardianapis.com/search";
+const BIO_KEYWORDS = [
+    "profile",
+    "interview",
+    "early life",
+    "childhood",
+    "biography",
+    "life story",
+    "portrait",
+    "who is",
+    "growing up",
+    "memoir",
+];
+// ============================================================================
+// GuardianSource
+// ============================================================================
+/**
+ * Research source backed by the Guardian Content API.
+ *
+ * Searches for biographical/profile articles about a subject,
+ * picks the best match by keyword scoring, and returns the
+ * sanitized body text.
+ */
+export class GuardianSource extends BaseResearchSource {
+    name = "The Guardian";
+    type = "guardian";
+    reliabilityTier = ReliabilityTier.TIER_1_NEWS;
+    domain = "content.guardianapis.com";
+    isFree = true;
+    estimatedCostPerQuery = 0;
+    apiKey;
+    constructor(options = {}) {
+        super({ rateLimitMs: 200, ...options });
+        this.apiKey = options.apiKey ?? process.env.GUARDIAN_API_KEY;
+    }
+    isAvailable() {
+        return Boolean(this.apiKey);
+    }
+    async fetchResult(subject, signal) {
+        if (!this.apiKey)
+            return null;
+        const query = `"${subject.name}" AND (profile OR interview OR "early life" OR childhood OR biography)`;
+        const url = new URL(GUARDIAN_API_URL);
+        url.searchParams.set("api-key", this.apiKey);
+        url.searchParams.set("q", query);
+        url.searchParams.set("show-fields", "bodyText,standfirst,trailText");
+        url.searchParams.set("page-size", "10");
+        url.searchParams.set("order-by", "relevance");
+        const response = await fetch(url.toString(), { signal });
+        if (!response.ok) {
+            throw new Error(`Guardian API error: HTTP ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (!data.response?.results?.length)
+            return null;
+        // Pick best article by biographical keyword matching
+        const article = this.findBestArticle(data.response.results);
+        if (!article)
+            return null;
+        const text = article.fields?.bodyText || article.fields?.standfirst || article.fields?.trailText;
+        if (!text || text.length < 200)
+            return null;
+        const sanitized = sanitizeSourceText(text);
+        if (sanitized.length < 200)
+            return null;
+        return {
+            text: sanitized,
+            confidence: -1,
+            costUsd: 0,
+            url: article.webUrl,
+            publication: "The Guardian",
+            metadata: {
+                title: article.webTitle,
+            },
+        };
+    }
+    /**
+     * Find the best article from Guardian search results.
+     *
+     * Priority:
+     * 1. Article with a bio keyword in the title
+     * 2. Article with a bio keyword in the body/standfirst
+     * 3. First result as fallback
+     */
+    findBestArticle(results) {
+        // First: match by title
+        for (const result of results) {
+            const title = result.webTitle.toLowerCase();
+            if (BIO_KEYWORDS.some((kw) => title.includes(kw))) {
+                return result;
+            }
+        }
+        // Second: match by body text
+        for (const result of results) {
+            const body = (result.fields?.bodyText || result.fields?.standfirst || "").toLowerCase();
+            if (BIO_KEYWORDS.some((kw) => body.includes(kw))) {
+                return result;
+            }
+        }
+        // Fallback: first result
+        return results[0];
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a Guardian API source instance.
+ *
+ * @param options - Guardian-specific options (apiKey, rateLimitMs, etc.)
+ * @returns A configured GuardianSource
+ */
+export function guardian(options) {
+    return new GuardianSource(options);
+}
+//# sourceMappingURL=guardian.js.map

package/dist/news/guardian.js.map

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

package/dist/news/nytimes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * New York Times Article Search API source.
+ *
+ * Uses the NYT Article Search API v2 to find biographical/profile articles.
+ * Unlike site-search sources that scrape full article text, the NYT API only
+ * returns partial content (lead_paragraph, abstract, snippet), so confidence
+ * is capped at 0.7 rather than delegating to base class keyword scoring.
+ */
+import { BaseResearchSource, ReliabilityTier, type BaseSourceOptions, type ResearchSubject, type RawFinding } from "@debriefer/core";
+export interface NYTimesOptions extends BaseSourceOptions {
+    apiKey?: string;
+}
+export declare class NYTimesSource extends BaseResearchSource<ResearchSubject> {
+    readonly name = "The New York Times";
+    readonly type = "nytimes";
+    readonly reliabilityTier = ReliabilityTier.TIER_1_NEWS;
+    readonly domain = "api.nytimes.com";
+    readonly isFree = true;
+    readonly estimatedCostPerQuery = 0;
+    private apiKey;
+    constructor(options?: NYTimesOptions);
+    isAvailable(): boolean;
+    protected fetchResult(subject: ResearchSubject, signal: AbortSignal): Promise<RawFinding | null>;
+    private findBestArticle;
+}
+export declare function nytimes(options?: NYTimesOptions): NYTimesSource;
+//# sourceMappingURL=nytimes.d.ts.map

package/dist/news/nytimes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nytimes.d.ts","sourceRoot":"","sources":["../../src/news/nytimes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAA;AAkBxB,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,aAAc,SAAQ,kBAAkB,CAAC,eAAe,CAAC;IACpE,QAAQ,CAAC,IAAI,wBAAuB;IACpC,QAAQ,CAAC,IAAI,aAAY;IACzB,QAAQ,CAAC,eAAe,+BAA8B;IACtD,QAAQ,CAAC,MAAM,qBAAoB;IACnC,QAAQ,CAAC,MAAM,QAAO;IACtB,QAAQ,CAAC,qBAAqB,KAAI;IAElC,OAAO,CAAC,MAAM,CAAoB;gBAEtB,OAAO,GAAE,cAAmB;IAK/B,WAAW,IAAI,OAAO;cAIf,WAAW,CACzB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA4D7B,OAAO,CAAC,eAAe;CA4BxB;AAED,wBAAgB,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAE/D"}

package/dist/news/nytimes.js

@@ -0,0 +1,104 @@
+/**
+ * New York Times Article Search API source.
+ *
+ * Uses the NYT Article Search API v2 to find biographical/profile articles.
+ * Unlike site-search sources that scrape full article text, the NYT API only
+ * returns partial content (lead_paragraph, abstract, snippet), so confidence
+ * is capped at 0.7 rather than delegating to base class keyword scoring.
+ */
+import { BaseResearchSource, ReliabilityTier, } from "@debriefer/core";
+import { sanitizeSourceText } from "../shared/sanitize-text.js";
+const NYT_API_URL = "https://api.nytimes.com/svc/search/v2/articlesearch.json";
+const BIO_KEYWORDS = [
+    "profile",
+    "interview",
+    "early life",
+    "childhood",
+    "biography",
+    "life of",
+    "portrait",
+    "who is",
+    "growing up",
+    "personal",
+];
+export class NYTimesSource extends BaseResearchSource {
+    name = "The New York Times";
+    type = "nytimes";
+    reliabilityTier = ReliabilityTier.TIER_1_NEWS;
+    domain = "api.nytimes.com";
+    isFree = true;
+    estimatedCostPerQuery = 0;
+    apiKey;
+    constructor(options = {}) {
+        super({ rateLimitMs: 6000, ...options });
+        this.apiKey = options.apiKey ?? process.env.NYTIMES_API_KEY;
+    }
+    isAvailable() {
+        return Boolean(this.apiKey);
+    }
+    async fetchResult(subject, signal) {
+        if (!this.apiKey)
+            return null;
+        const query = `"${subject.name}" (biography OR profile OR interview)`;
+        const url = new URL(NYT_API_URL);
+        url.searchParams.set("api-key", this.apiKey);
+        url.searchParams.set("q", query);
+        url.searchParams.set("sort", "relevance");
+        url.searchParams.set("fq", 'document_type:("article")');
+        const response = await fetch(url.toString(), { signal });
+        if (!response.ok) {
+            throw new Error(`NYT API error: HTTP ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (!data.response?.docs?.length)
+            return null;
+        // Filter out docs without URLs, then pick best article
+        const docsWithUrls = data.response.docs.filter((d) => d.web_url);
+        if (docsWithUrls.length === 0)
+            return null;
+        const doc = this.findBestArticle(docsWithUrls);
+        if (!doc)
+            return null;
+        // Combine available text fields (NYT API doesn't return full body)
+        const parts = [doc.lead_paragraph, doc.abstract, doc.snippet].filter(Boolean);
+        const text = parts.join("\n\n");
+        if (text.length < 100)
+            return null;
+        const sanitized = sanitizeSourceText(text);
+        if (sanitized.length < 100)
+            return null;
+        // Cap confidence at 0.7 — NYT API returns partial content only
+        return {
+            text: sanitized,
+            confidence: 0.7,
+            costUsd: 0,
+            url: doc.web_url,
+            publication: "The New York Times",
+            metadata: {
+                title: doc.headline?.main ?? "",
+            },
+        };
+    }
+    findBestArticle(docs) {
+        // First: match by headline
+        for (const doc of docs) {
+            const title = (doc.headline?.main ?? "").toLowerCase();
+            if (BIO_KEYWORDS.some((kw) => title.includes(kw))) {
+                return doc;
+            }
+        }
+        // Second: match by abstract/snippet
+        for (const doc of docs) {
+            const body = `${doc.abstract ?? ""} ${doc.snippet ?? ""}`.toLowerCase();
+            if (BIO_KEYWORDS.some((kw) => body.includes(kw))) {
+                return doc;
+            }
+        }
+        // Fallback: first result
+        return docs[0];
+    }
+}
+export function nytimes(options) {
+    return new NYTimesSource(options);
+}
+//# sourceMappingURL=nytimes.js.map

package/dist/news/nytimes.js.map

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

package/dist/news/site-search-source.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Configurable site-search source for news and reference sites.
+ *
+ * Uses DuckDuckGo `site:` search to find articles on a specific domain,
+ * picks the best URL based on path preferences, fetches the page,
+ * extracts article content, and returns a sanitized finding.
+ *
+ * This is the reusable base that 19+ news/reference source factories
+ * instantiate with different SiteSearchConfig values (AP, BBC, Reuters, etc.).
+ */
+import { BaseResearchSource, type BaseSourceOptions, type ResearchSubject, type RawFinding, type ReliabilityTier } from "@debriefer/core";
+import { type SearchResult } from "../shared/duckduckgo-search.js";
+/** Configuration for a site-search source. */
+export interface SiteSearchConfig {
+    /** Display name (e.g., "AP News"). */
+    name: string;
+    /** Source type identifier (e.g., "ap-news"). */
+    type: string;
+    /** Primary domain to search (e.g., "apnews.com"). */
+    domain: string;
+    /** Additional domains to search (e.g., ["bbc.co.uk"]). */
+    additionalDomains?: string[];
+    /** Reliability tier from the RSP scale. */
+    reliabilityTier: ReliabilityTier;
+    /** Rate limit delay in milliseconds. Default: 1500. */
+    rateLimitMs?: number;
+    /** URL paths to boost when selecting results (e.g., ["/article/"]). */
+    preferredPaths?: string[];
+    /** URL paths to penalize when selecting results (e.g., ["/gallery/"]). */
+    avoidPaths?: string[];
+    /** Additional query terms appended to the search (e.g., "biography OR profile"). */
+    queryTerms?: string;
+    /** Minimum extracted text length in characters. Default: 200. */
+    minContentLength?: number;
+}
+/**
+ * Pick the best URL from search results based on path preferences.
+ *
+ * Scoring:
+ * - +10 for each preferredPaths match found in the URL pathname
+ * - -10 for each avoidPaths match found in the URL pathname
+ * - Returns highest-scored URL, falling back to first result
+ * - Returns null for empty array
+ *
+ * @param results - Array of search results from DDG
+ * @param options - Optional path preference configuration
+ * @returns The best URL string, or null if no results
+ */
+export declare function pickBestUrl(results: SearchResult[], options?: {
+    preferredPaths?: string[];
+    avoidPaths?: string[];
+}): string | null;
+/**
+ * A configurable research source that searches a specific news/reference
+ * site via DuckDuckGo `site:` queries.
+ *
+ * All metadata (name, type, reliabilityTier, domain, isFree, estimatedCostPerQuery)
+ * is derived from the provided SiteSearchConfig.
+ */
+export declare class SiteSearchSource extends BaseResearchSource<ResearchSubject> {
+    readonly name: string;
+    readonly type: string;
+    readonly reliabilityTier: ReliabilityTier;
+    readonly domain: string;
+    readonly isFree = true;
+    readonly estimatedCostPerQuery = 0;
+    private readonly config;
+    constructor(config: SiteSearchConfig, options?: BaseSourceOptions);
+    /**
+     * Build search query for this subject.
+     *
+     * Format: `"subject name" queryTerms` (queryTerms omitted if empty).
+     */
+    buildQuery(subject: ResearchSubject): string;
+    /**
+     * Fetch a finding from this news/reference site.
+     *
+     * Pipeline:
+     * 1. Search DDG with `site:domain` filter
+     * 2. Pick best URL based on path preferences
+     * 3. Fetch the page
+     * 4. Extract article content via Readability
+     * 5. Check minimum content length
+     * 6. Sanitize text
+     * 7. Return RawFinding with metadata
+     */
+    protected fetchResult(subject: ResearchSubject, signal: AbortSignal): Promise<RawFinding | null>;
+}
+//# sourceMappingURL=site-search-source.d.ts.map

package/dist/news/site-search-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-search-source.d.ts","sourceRoot":"","sources":["../../src/news/site-search-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAA;AASpF,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,2CAA2C;IAC3C,eAAe,EAAE,eAAe,CAAA;IAChC,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7D,MAAM,GAAG,IAAI,CA8Cf;AAMD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB,CAAC,eAAe,CAAC;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,QAAO;IACtB,QAAQ,CAAC,qBAAqB,KAAI;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,iBAAiB;IASjE;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM;IAQ5C;;;;;;;;;;;OAWG;cACa,WAAW,CACzB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAuE9B"}