@dpopsuev/web-spider 0.10.4

package/dist/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAwBtE"}

package/dist/views.js

@@ -0,0 +1,39 @@
+/**
+ * View transformations — business logic that converts a SpideredPage into
+ * one of the available view shapes. Separated from types.ts which is pure
+ * data-shape definitions.
+ */
+/**
+ * Downgrade a full SpideredPage to a LeanPage.
+ *
+ * Pass a PageGraph as the second argument to populate `inboundCount` —
+ * the number of other spidered pages that link to this one. Agents can
+ * use this as a lightweight authority signal when ranking results from
+ * a crawl without running a full PageRank pass.
+ */
+export function toLean(page, graph) {
+    return {
+        view: "lean",
+        url: page.url,
+        domain: page.domain,
+        ...(page.canonicalUrl !== undefined ? { canonicalUrl: page.canonicalUrl } : {}),
+        title: page.title,
+        ...(page.description ? { description: page.description } : {}),
+        ...(page.author ? { author: page.author } : {}),
+        ...(page.publishedAt ? { publishedAt: page.publishedAt } : {}),
+        lang: page.lang,
+        tags: page.tags,
+        wordCount: page.wordCount,
+        readingTimeMinutes: page.readingTimeMinutes,
+        chunkCount: page.chunks.length,
+        headings: page.headings.map((h) => `${"#".repeat(h.level)} ${h.text}`),
+        links: page.links
+            .filter((l) => l.rel === "body")
+            .slice(0, 10)
+            .map((l) => ({ href: l.href, text: l.text })),
+        ...(graph !== undefined
+            ? { inboundCount: graph.inbound(page.url).length }
+            : {}),
+    };
+}
+//# sourceMappingURL=views.js.map

package/dist/web-search.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Web search API integration — Brave Search and Tavily.
+ *
+ * Both return a normalised WebSearchResult[].
+ * API keys are read from environment variables by default:
+ *   BRAVE_SEARCH_API_KEY
+ *   TAVILY_API_KEY
+ */
+export type { WebSearchResult } from "./ports.js";
+import type { ISearchEngine, SearchQuery, WebSearchResult } from "./ports.js";
+export interface BraveSearchOptions {
+    /** API key. Defaults to process.env.BRAVE_SEARCH_API_KEY. */
+    apiKey?: string;
+    /** Number of results (1–20). Default 10. */
+    numResults?: number;
+    /** ISO 3166-1 alpha-2 country code for localised results, e.g. "US". */
+    country?: string;
+    /**
+     * Freshness filter. Maps SearchQuery.timeRange to Brave's parameter:
+     *   "pd" = past day, "pw" = past week, "pm" = past month, "py" = past year.
+     * Pass directly when bypassing the adapter, or set timeRange on SearchQuery.
+     */
+    freshness?: "pd" | "pw" | "pm" | "py";
+}
+export interface TavilySearchOptions {
+    /** API key. Defaults to process.env.TAVILY_API_KEY. */
+    apiKey?: string;
+    /** Number of results. Default 5. */
+    numResults?: number;
+    /** "basic" (1 credit) or "advanced" (2 credits). Default "basic". */
+    depth?: "basic" | "advanced";
+    /** Restrict results to content published within this window. */
+    timeRange?: "day" | "week" | "month" | "year";
+    /** Topic mode: "news" prioritises fresh news articles. */
+    topic?: "news" | "general";
+}
+export type SearchEngine = "brave" | "tavily" | "exa" | "ddg";
+export interface ExaSearchOptions {
+    /** API key. Defaults to process.env.EXA_API_KEY. */
+    apiKey?: string;
+    /** Number of results. Default 10. */
+    numResults?: number;
+    /**
+     * Search type.
+     * "auto"   — Exa decides keyword vs neural (default).
+     * "neural" — embedding-based semantic search.
+     * "keyword" — traditional keyword search.
+     */
+    type?: "auto" | "neural" | "keyword";
+}
+/**
+ * Search the web via the Exa Search API (neural/semantic retrieval).
+ * https://exa.ai/docs/reference/search
+ *
+ * Returns highlights inline per result — richer snippets without extra round-trips.
+ */
+export declare function exaSearch(query: string, opts?: ExaSearchOptions): Promise<WebSearchResult[]>;
+/**
+ * Search the web via the Brave Search API.
+ * https://api.search.brave.com/app/documentation/web-search
+ */
+export declare function braveSearch(query: string, opts?: BraveSearchOptions): Promise<WebSearchResult[]>;
+/**
+ * Search the web via the Tavily API.
+ * https://docs.tavily.com/docs/rest-api/api-reference
+ */
+export declare function tavilySearch(query: string, opts?: TavilySearchOptions): Promise<WebSearchResult[]>;
+export interface DdgSearchOptions {
+    /**
+     * Maximum results to return. DDG doesn't support a server-side count param;
+     * this slices the client-side result list. Default: 10.
+     */
+    numResults?: number;
+}
+/**
+ * Search via the DuckDuckGo Instant Answer API.
+ * https://duckduckgo.com/api
+ *
+ * No API key required. Returns structured instant answers (Abstract,
+ * Results, RelatedTopics) mapped to WebSearchResult[].
+ *
+ * Limitation: not a full web index — best for well-known entities and
+ * unambiguous queries. Returns empty when DDG has no instant answer.
+ */
+export declare function ddgSearch(query: string, opts?: DdgSearchOptions): Promise<WebSearchResult[]>;
+/**
+ * Search using whichever engine is explicitly requested or has an API key
+ * available. Falls through to the DDG Instant Answer API as a zero-cost
+ * last resort — no key required.
+ *
+ * Prefer {@link defaultSearchEngine} + {@link FallbackSearchEngine} when
+ * you need composable retry / fallback behaviour.
+ */
+export declare function webSearch(query: string, opts?: {
+    engine?: SearchEngine;
+    numResults?: number;
+    timeRange?: "day" | "week" | "month" | "year";
+    topic?: "news" | "general";
+}): Promise<WebSearchResult[]>;
+/**
+ * A factory that creates an ISearchEngine from an optional API key.
+ * key is undefined for keyless engines (e.g. DDG).
+ */
+type EngineFactory = (key: string | undefined) => ISearchEngine;
+/**
+ * Register a search engine under a name.
+ *
+ * Call this to add a new engine without touching any existing code:
+ * @example
+ * registerSearchEngine("my-engine", (key) => new MyEngine(key!))
+ */
+export declare function registerSearchEngine(name: string, factory: EngineFactory): void;
+/**
+ * Resolve a registered engine by name, passing the provided API key.
+ * Throws a descriptive error for unknown names or missing required keys.
+ */
+export declare function resolveSearchEngine(name: string, key?: string | undefined): ISearchEngine;
+/** Brave Search adapter implementing ISearchEngine. */
+export declare class BraveSearchEngine implements ISearchEngine {
+    private readonly apiKey;
+    private readonly country?;
+    constructor(apiKey: string, country?: string | undefined);
+    search(req: SearchQuery): Promise<WebSearchResult[]>;
+}
+/** Tavily adapter implementing ISearchEngine. */
+export declare class TavilySearchEngine implements ISearchEngine {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    search(req: SearchQuery): Promise<WebSearchResult[]>;
+}
+/** Exa adapter implementing ISearchEngine. */
+export declare class ExaSearchEngine implements ISearchEngine {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    search(req: SearchQuery): Promise<WebSearchResult[]>;
+}
+/** DuckDuckGo Instant Answer adapter — no API key required. */
+export declare class DdgSearchEngine implements ISearchEngine {
+    search(req: SearchQuery): Promise<WebSearchResult[]>;
+}
+export interface FallbackSearchEngineOptions {
+    /**
+     * Treat an empty result set as a failure and try the next engine.
+     * Default: true.
+     */
+    fallbackOnEmpty?: boolean;
+    /**
+     * Swallow a thrown error and try the next engine instead of propagating.
+     * Default: true.
+     */
+    fallbackOnError?: boolean;
+}
+/**
+ * A composite ISearchEngine that tries each engine in order, falling back
+ * to the next when the current one returns empty results or throws.
+ *
+ * Because it implements ISearchEngine itself it is fully composable —
+ * nest FallbackSearchEngines, wrap them in caches, inject stubs in tests.
+ *
+ * @example
+ * // Tavily with DDG as zero-cost fallback
+ * const engine = new FallbackSearchEngine([
+ *   new TavilySearchEngine(process.env.TAVILY_API_KEY),
+ *   new DdgSearchEngine(),
+ * ]);
+ */
+export declare class FallbackSearchEngine implements ISearchEngine {
+    private readonly engines;
+    private readonly fallbackOnEmpty;
+    private readonly fallbackOnError;
+    constructor(engines: ISearchEngine[], opts?: FallbackSearchEngineOptions);
+    search(req: SearchQuery): Promise<WebSearchResult[]>;
+}
+/**
+ * Build a FallbackSearchEngine chain from environment variables.
+ *
+ * Priority order for keyed engines: Brave → Tavily → Exa.
+ * DuckDuckGo is always appended as the zero-cost last resort.
+ *
+ * The returned engine implements ISearchEngine — swap it for any stub
+ * in tests without touching call sites.
+ */
+export declare function defaultSearchEngine(): ISearchEngine;
+//# sourceMappingURL=web-search.d.ts.map

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

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

package/dist/web-search.js

@@ -0,0 +1,399 @@
+/**
+ * Web search API integration — Brave Search and Tavily.
+ *
+ * Both return a normalised WebSearchResult[].
+ * API keys are read from environment variables by default:
+ *   BRAVE_SEARCH_API_KEY
+ *   TAVILY_API_KEY
+ */
+/**
+ * Search the web via the Exa Search API (neural/semantic retrieval).
+ * https://exa.ai/docs/reference/search
+ *
+ * Returns highlights inline per result — richer snippets without extra round-trips.
+ */
+export async function exaSearch(query, opts = {}) {
+    const apiKey = opts.apiKey ?? process.env["EXA_API_KEY"];
+    if (!apiKey)
+        throw new Error("Exa API key required — set EXA_API_KEY or pass opts.apiKey");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15_000);
+    let res;
+    try {
+        res = await fetch("https://api.exa.ai/search", {
+            method: "POST",
+            signal: controller.signal,
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+            },
+            body: JSON.stringify({
+                query,
+                numResults: opts.numResults ?? 10,
+                type: opts.type ?? "auto",
+                contents: {
+                    highlights: { numSentences: 2, highlightsPerUrl: 3 },
+                },
+            }),
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok)
+        throw new Error(`Exa API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.results ?? []).map((r) => ({
+        url: r.url,
+        title: r.title,
+        snippet: r.highlights?.join(" … ") ?? "",
+        ...(r.publishedDate ? { publishedAt: r.publishedDate } : {}),
+    }));
+}
+/**
+ * Search the web via the Brave Search API.
+ * https://api.search.brave.com/app/documentation/web-search
+ */
+export async function braveSearch(query, opts = {}) {
+    const apiKey = opts.apiKey ?? process.env["BRAVE_SEARCH_API_KEY"];
+    if (!apiKey)
+        throw new Error("Brave Search API key required — set BRAVE_SEARCH_API_KEY or pass opts.apiKey");
+    const params = new URLSearchParams({
+        q: query,
+        count: String(Math.min(opts.numResults ?? 10, 20)),
+    });
+    if (opts.country)
+        params.set("country", opts.country);
+    if (opts.freshness)
+        params.set("freshness", opts.freshness);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    let res;
+    try {
+        res = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
+            signal: controller.signal,
+            headers: {
+                Accept: "application/json",
+                "Accept-Encoding": "gzip",
+                "X-Subscription-Token": apiKey,
+            },
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok)
+        throw new Error(`Brave Search API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.web?.results ?? []).map((r) => ({
+        url: r.url,
+        title: r.title,
+        snippet: r.description ?? "",
+        ...(r.age ? { publishedAt: r.age } : {}),
+    }));
+}
+/**
+ * Search the web via the Tavily API.
+ * https://docs.tavily.com/docs/rest-api/api-reference
+ */
+export async function tavilySearch(query, opts = {}) {
+    const apiKey = opts.apiKey ?? process.env["TAVILY_API_KEY"];
+    if (!apiKey)
+        throw new Error("Tavily API key required — set TAVILY_API_KEY or pass opts.apiKey");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15_000);
+    let res;
+    try {
+        res = await fetch("https://api.tavily.com/search", {
+            method: "POST",
+            signal: controller.signal,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query,
+                api_key: apiKey,
+                max_results: opts.numResults ?? 5,
+                search_depth: opts.depth ?? "basic",
+                include_raw_content: false,
+                ...(opts.timeRange ? { time_range: opts.timeRange } : {}),
+                ...(opts.topic ? { topic: opts.topic } : {}),
+            }),
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok)
+        throw new Error(`Tavily API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.results ?? []).map((r) => ({
+        url: r.url,
+        title: r.title,
+        snippet: r.content ?? "",
+        ...(r.published_date ? { publishedAt: r.published_date } : {}),
+    }));
+}
+/**
+ * Search via the DuckDuckGo Instant Answer API.
+ * https://duckduckgo.com/api
+ *
+ * No API key required. Returns structured instant answers (Abstract,
+ * Results, RelatedTopics) mapped to WebSearchResult[].
+ *
+ * Limitation: not a full web index — best for well-known entities and
+ * unambiguous queries. Returns empty when DDG has no instant answer.
+ */
+export async function ddgSearch(query, opts = {}) {
+    const params = new URLSearchParams({
+        q: query,
+        format: "json",
+        no_redirect: "1",
+        no_html: "1",
+        skip_disambig: "1",
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    let res;
+    try {
+        res = await fetch(`https://api.duckduckgo.com/?${params}`, {
+            signal: controller.signal,
+            headers: {
+                Accept: "application/json",
+                // DDG silently returns an empty 200 body for browser-like or
+                // missing User-Agents. A curl/bot-style UA gets a real 202.
+                "User-Agent": "web-spider/0.8",
+            },
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok)
+        throw new Error(`DDG API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    const results = [];
+    const limit = opts.numResults ?? 10;
+    // 1. Instant answer abstract (Wikipedia-style knowledge panel)
+    if (data.Abstract && data.AbstractURL) {
+        results.push({
+            url: data.AbstractURL,
+            title: data.Heading ?? data.AbstractSource ?? "DuckDuckGo",
+            snippet: data.Abstract,
+        });
+    }
+    // 2. Official results (e.g. official site links)
+    for (const r of data.Results ?? []) {
+        if (results.length >= limit)
+            break;
+        if (r.FirstURL)
+            results.push({ url: r.FirstURL, title: r.Text, snippet: r.Text });
+    }
+    // 3. Related topics — flatten one level of nesting
+    for (const topic of data.RelatedTopics ?? []) {
+        if (results.length >= limit)
+            break;
+        if (topic.FirstURL && topic.Text) {
+            results.push({ url: topic.FirstURL, title: topic.Text, snippet: topic.Text });
+        }
+        for (const sub of topic.Topics ?? []) {
+            if (results.length >= limit)
+                break;
+            results.push({ url: sub.FirstURL, title: sub.Text, snippet: sub.Text });
+        }
+    }
+    return results;
+}
+/**
+ * Search using whichever engine is explicitly requested or has an API key
+ * available. Falls through to the DDG Instant Answer API as a zero-cost
+ * last resort — no key required.
+ *
+ * Prefer {@link defaultSearchEngine} + {@link FallbackSearchEngine} when
+ * you need composable retry / fallback behaviour.
+ */
+export async function webSearch(query, opts = {}) {
+    const engine = opts.engine
+        ? resolveSearchEngine(opts.engine, process.env[envKeyForEngine(opts.engine)])
+        : defaultSearchEngine();
+    return engine.search({
+        query,
+        numResults: opts.numResults,
+        timeRange: opts.timeRange,
+        topic: opts.topic,
+    });
+}
+/** The global engine registry. Seeded with built-in engines below. */
+const ENGINE_REGISTRY = new Map();
+/**
+ * Register a search engine under a name.
+ *
+ * Call this to add a new engine without touching any existing code:
+ * @example
+ * registerSearchEngine("my-engine", (key) => new MyEngine(key!))
+ */
+export function registerSearchEngine(name, factory) {
+    ENGINE_REGISTRY.set(name, factory);
+}
+/**
+ * Resolve a registered engine by name, passing the provided API key.
+ * Throws a descriptive error for unknown names or missing required keys.
+ */
+export function resolveSearchEngine(name, key) {
+    const factory = ENGINE_REGISTRY.get(name);
+    if (!factory)
+        throw new Error(`Unknown search engine: "${name}". Register it with registerSearchEngine().`);
+    return factory(key);
+}
+/** @internal Map engine name to its env var key name (for webSearch auto-detect). */
+function envKeyForEngine(name) {
+    const envKeys = {
+        brave: "BRAVE_SEARCH_API_KEY",
+        tavily: "TAVILY_API_KEY",
+        exa: "EXA_API_KEY",
+    };
+    return envKeys[name] ?? "";
+}
+// Seed the registry with built-in engines.
+// Adding a new engine: call registerSearchEngine() — do NOT edit this block.
+registerSearchEngine("brave", (key) => {
+    if (!key)
+        throw new Error("BRAVE_SEARCH_API_KEY not set");
+    return new BraveSearchEngine(key);
+});
+registerSearchEngine("tavily", (key) => {
+    if (!key)
+        throw new Error("TAVILY_API_KEY not set");
+    return new TavilySearchEngine(key);
+});
+registerSearchEngine("exa", (key) => {
+    if (!key)
+        throw new Error("EXA_API_KEY not set");
+    return new ExaSearchEngine(key);
+});
+registerSearchEngine("ddg", () => new DdgSearchEngine());
+// ---------------------------------------------------------------------------
+// ISearchEngine adapters — concrete implementations of the port
+// ---------------------------------------------------------------------------
+/** Maps the canonical timeRange string to Brave's freshness parameter. */
+const BRAVE_FRESHNESS = {
+    day: "pd",
+    week: "pw",
+    month: "pm",
+    year: "py",
+};
+/** Brave Search adapter implementing ISearchEngine. */
+export class BraveSearchEngine {
+    constructor(apiKey, country) {
+        this.apiKey = apiKey;
+        this.country = country;
+    }
+    search(req) {
+        const freshness = req.timeRange ? BRAVE_FRESHNESS[req.timeRange] : undefined;
+        return braveSearch(req.query, {
+            apiKey: this.apiKey,
+            numResults: req.numResults,
+            country: this.country,
+            freshness,
+        });
+    }
+}
+/** Tavily adapter implementing ISearchEngine. */
+export class TavilySearchEngine {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    search(req) {
+        return tavilySearch(req.query, {
+            apiKey: this.apiKey,
+            numResults: req.numResults,
+            timeRange: req.timeRange,
+            topic: req.topic,
+        });
+    }
+}
+/** Exa adapter implementing ISearchEngine. */
+export class ExaSearchEngine {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    search(req) {
+        return exaSearch(req.query, { apiKey: this.apiKey, numResults: req.numResults });
+    }
+}
+/** DuckDuckGo Instant Answer adapter — no API key required. */
+export class DdgSearchEngine {
+    search(req) {
+        return ddgSearch(req.query, { numResults: req.numResults });
+    }
+}
+/**
+ * A composite ISearchEngine that tries each engine in order, falling back
+ * to the next when the current one returns empty results or throws.
+ *
+ * Because it implements ISearchEngine itself it is fully composable —
+ * nest FallbackSearchEngines, wrap them in caches, inject stubs in tests.
+ *
+ * @example
+ * // Tavily with DDG as zero-cost fallback
+ * const engine = new FallbackSearchEngine([
+ *   new TavilySearchEngine(process.env.TAVILY_API_KEY),
+ *   new DdgSearchEngine(),
+ * ]);
+ */
+export class FallbackSearchEngine {
+    constructor(engines, opts = {}) {
+        this.engines = engines;
+        if (engines.length === 0)
+            throw new Error("FallbackSearchEngine requires at least one engine");
+        this.fallbackOnEmpty = opts.fallbackOnEmpty ?? true;
+        this.fallbackOnError = opts.fallbackOnError ?? true;
+    }
+    async search(req) {
+        let lastError;
+        for (const engine of this.engines) {
+            try {
+                const results = await engine.search(req);
+                if (results.length > 0 || !this.fallbackOnEmpty)
+                    return results;
+                // Empty + fallbackOnEmpty → try next engine
+            }
+            catch (err) {
+                if (!this.fallbackOnError)
+                    throw err;
+                lastError = err;
+                // Error + fallbackOnError → try next engine
+            }
+        }
+        // All engines exhausted — surface the last error or return empty
+        if (lastError)
+            throw lastError;
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Wiring — compose engines from environment variables
+// ---------------------------------------------------------------------------
+/**
+ * Build a FallbackSearchEngine chain from environment variables.
+ *
+ * Priority order for keyed engines: Brave → Tavily → Exa.
+ * DuckDuckGo is always appended as the zero-cost last resort.
+ *
+ * The returned engine implements ISearchEngine — swap it for any stub
+ * in tests without touching call sites.
+ */
+export function defaultSearchEngine() {
+    const engines = [];
+    const brave = process.env["BRAVE_SEARCH_API_KEY"];
+    if (brave)
+        engines.push(new BraveSearchEngine(brave));
+    const tavily = process.env["TAVILY_API_KEY"];
+    if (tavily)
+        engines.push(new TavilySearchEngine(tavily));
+    const exa = process.env["EXA_API_KEY"];
+    if (exa)
+        engines.push(new ExaSearchEngine(exa));
+    // DDG always last — no key needed, never throws the "no key" error
+    engines.push(new DdgSearchEngine());
+    return new FallbackSearchEngine(engines);
+}
+//# sourceMappingURL=web-search.js.map