@webcrawl/mcp 1.4.2 → 1.4.4

package/dist/core/extract/currency.js

@@ -0,0 +1,259 @@
+const VALID_ISO_CURRENCIES = new Set([
+    "USD",
+    "AUD",
+    "GBP",
+    "EUR",
+    "CAD",
+    "NZD",
+    "SGD",
+    "HKD",
+    "JPY",
+    "CNY",
+    "INR",
+    "CHF",
+    "SEK",
+    "NOK",
+    "DKK",
+    "ZAR",
+    "BRL",
+    "MXN",
+    "AED",
+    "SAR",
+    "THB",
+    "MYR",
+    "IDR",
+    "PHP",
+    "VND",
+    "KRW",
+    "PLN",
+    "TRY",
+    "TWD",
+]);
+/**
+ * Derive ISO 4217 currency code from a raw price string and/or 2-letter ISO country code.
+ * Uses standard currency symbols and ISO country conventions without hardcoded retailer lists.
+ */
+export function resolveCurrencyCode(rawPriceOrCurrency, countryCode) {
+    const s = (rawPriceOrCurrency || "").trim();
+    const isoMatches = s.match(/\b([A-Z]{3})\b/g);
+    if (isoMatches) {
+        for (const code of isoMatches) {
+            if (VALID_ISO_CURRENCIES.has(code)) {
+                return code;
+            }
+        }
+    }
+    if (/A\$|AU\$/i.test(s)) {
+        return "AUD";
+    }
+    if (/NZ\$/i.test(s)) {
+        return "NZD";
+    }
+    if (/CA\$|C\$/i.test(s)) {
+        return "CAD";
+    }
+    if (/S\$|SG\$/i.test(s)) {
+        return "SGD";
+    }
+    if (/HK\$/i.test(s)) {
+        return "HKD";
+    }
+    if (/NT\$/i.test(s)) {
+        return "TWD";
+    }
+    if (s.includes("£")) {
+        return "GBP";
+    }
+    if (s.includes("€")) {
+        return "EUR";
+    }
+    if (s.includes("¥")) {
+        return (countryCode || "").toUpperCase() === "CN" ? "CNY" : "JPY";
+    }
+    if (s.includes("₹") ||
+        /\bRs\.?(?:\s|\d)/i.test(s) ||
+        /\b(?:crores?|cr|lakhs?|lacs?)\b/i.test(s)) {
+        return "INR";
+    }
+    if (s.includes("₫") || /\b(?:đồng|vnd|triệu|tỷ)\b/i.test(s)) {
+        return "VND";
+    }
+    if (s.includes("฿")) {
+        return "THB";
+    }
+    if (s.includes("₱")) {
+        return "PHP";
+    }
+    if (s.includes("₩")) {
+        return "KRW";
+    }
+    if (/\bzł\b/i.test(s)) {
+        return "PLN";
+    }
+    if (/\bRM\s*\d/i.test(s)) {
+        return "MYR";
+    }
+    if (/\bRp\.?\s*\d/i.test(s)) {
+        return "IDR";
+    }
+    const cc = (countryCode || "").trim().toUpperCase();
+    // Bare "$" in non-dollar countries (e.g. EU, GB, IN, VN, JP) indicates USD pricing
+    if (s.includes("$") &&
+        !["US", "AU", "CA", "NZ", "SG", "HK", "TW", "MX", ""].includes(cc)) {
+        return "USD";
+    }
+    const COUNTRY_TO_CURRENCY = {
+        AU: "AUD",
+        GB: "GBP",
+        UK: "GBP",
+        CA: "CAD",
+        NZ: "NZD",
+        SG: "SGD",
+        IN: "INR",
+        VN: "VND",
+        JP: "JPY",
+        CN: "CNY",
+        HK: "HKD",
+        TW: "TWD",
+        KR: "KRW",
+        TH: "THB",
+        MY: "MYR",
+        ID: "IDR",
+        PH: "PHP",
+        CH: "CHF",
+        SE: "SEK",
+        NO: "NOK",
+        DK: "DKK",
+        PL: "PLN",
+        CZ: "CZK",
+        HU: "HUF",
+        RO: "RON",
+        TR: "TRY",
+        AE: "AED",
+        SA: "SAR",
+        ZA: "ZAR",
+        BR: "BRL",
+        MX: "MXN",
+    };
+    if (COUNTRY_TO_CURRENCY[cc]) {
+        return COUNTRY_TO_CURRENCY[cc];
+    }
+    if ([
+        "DE",
+        "FR",
+        "IT",
+        "ES",
+        "NL",
+        "IE",
+        "AT",
+        "BE",
+        "PT",
+        "FI",
+        "GR",
+        "LU",
+        "SK",
+        "SI",
+        "EE",
+        "LV",
+        "LT",
+        "HR",
+        "CY",
+        "MT",
+        "EU",
+    ].includes(cc)) {
+        return "EUR";
+    }
+    return "USD";
+}
+/**
+ * Parse a numeric price and currency from a human price string such as
+ * "$360.41", "A$399.00", "£173.49", "1.299,00 €", "₹1,19,900", "₹1.45 Crores", "S$429", "7.490.000 ₫".
+ */
+export function parsePriceString(raw, countryCode, explicitCurrency, maxAllowedPrice = 1_000_000) {
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw <= 0) {
+            return null;
+        }
+        const numCurrency = resolveCurrencyCode(explicitCurrency, countryCode);
+        return {
+            price: Number(raw.toFixed(2)),
+            rawPrice: `${numCurrency} ${raw.toFixed(2)}`,
+            currency: numCurrency,
+        };
+    }
+    if (!raw || typeof raw !== "string") {
+        return null;
+    }
+    const cleaned = raw.replace(/\s+/g, " ").trim();
+    if (!cleaned) {
+        return null;
+    }
+    const currency = resolveCurrencyCode(explicitCurrency || cleaned, countryCode);
+    // High-denomination currencies (VND, IDR, KRW, JPY, INR) allow much higher nominal numeric caps
+    const highDenomMultiplier = currency === "VND" || currency === "IDR"
+        ? 25_000
+        : currency === "KRW" || currency === "JPY" || currency === "INR"
+            ? 500
+            : 1;
+    const effectiveMaxPrice = maxAllowedPrice * highDenomMultiplier;
+    // Handle Indian Crore / Lakh and Vietnamese tỷ / triệu multipliers
+    const unitMatch = cleaned.match(/(\d[\d,.]*)\s*(crores?|cr|lakhs?|lacs?|tỷ|triệu)\b/i);
+    if (unitMatch) {
+        const baseNum = Number.parseFloat(unitMatch[1].replace(/,/g, ""));
+        const unit = unitMatch[2].toLowerCase();
+        const mult = unit.startsWith("cr")
+            ? 10_000_000
+            : unit.startsWith("la")
+                ? 100_000
+                : unit === "tỷ"
+                    ? 1_000_000_000
+                    : 1_000_000;
+        const total = Math.round(baseNum * mult);
+        if (Number.isFinite(total) && total > 0 && total <= effectiveMaxPrice) {
+            return {
+                price: total,
+                rawPrice: cleaned,
+                currency,
+            };
+        }
+    }
+    const numMatch = cleaned.match(/(\d[\d,.]*)/);
+    if (!numMatch) {
+        return null;
+    }
+    let numStr = numMatch[1].replace(/[.,]$/, "");
+    // Handle multi-dot thousands (e.g. "7.490.000" in VND/EUR/IDR) and European decimal comma ("194,99" or "1.299,00")
+    if (/^\d{1,3}(?:\.\d{3}){2,}$/.test(numStr)) {
+        numStr = numStr.replace(/\./g, "");
+    }
+    else if (/^\d{1,3}\.\d{3}$/.test(numStr) &&
+        (currency === "VND" || currency === "IDR" || currency === "EUR")) {
+        numStr = numStr.replace(/\./g, "");
+    }
+    else if (/\.\d{3},\d{1,2}$/.test(numStr)) {
+        numStr = numStr.replace(/\./g, "").replace(",", ".");
+    }
+    else if (/^\d+,\d{1,2}$/.test(numStr)) {
+        numStr = numStr.replace(",", ".");
+    }
+    else {
+        numStr = numStr.replace(/,/g, "");
+    }
+    const value = Number.parseFloat(numStr);
+    if (!Number.isFinite(value) || value <= 0 || value > effectiveMaxPrice) {
+        return null;
+    }
+    return {
+        price: Number(value.toFixed(2)),
+        rawPrice: cleaned,
+        currency,
+    };
+}
+export function extractDomainHost(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./i, "").toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/core/extract/cve-cache.d.ts

@@ -0,0 +1,62 @@
+import { type CveRecord } from "./cve.js";
+/** Only CVEs published (or numbered) in this year or later are stored. */
+export declare const CVE_STORE_SINCE = 2020;
+/** A cached keyword result is trusted for this long before NVD is asked again. */
+export declare const QUERY_TTL_MS: number;
+export interface CachedCves {
+    records: CveRecord[];
+    /** Ids served from cache that are due a background refresh. */
+    stale: string[];
+}
+export interface CveCacheStore {
+    get(ids: string[]): Promise<CachedCves>;
+    getQuery(keyword: string): Promise<string[] | null>;
+    putQuery(keyword: string, ids: string[]): Promise<void>;
+    search(keyword: string, limit: number): Promise<CveRecord[]>;
+    upsert(records: CveRecord[]): Promise<number>;
+}
+/** True when a record falls inside the stored window (published year, else id year). */
+export declare function isCacheableCve(r: CveRecord): boolean;
+export declare function isStale(fetchedAt: Date, published: string | undefined, now?: number): boolean;
+export declare function cveQueryKey(keyword: string): string;
+/** One row of the batched upsert; exported so the SQL shape is unit-testable. */
+export declare function cveRow(r: CveRecord): unknown[];
+/**
+ * INSERT … ON CONFLICT for `n` rows. An existing row is only replaced when the
+ * incoming record is at least as new (`modified`) and actually differs, so cache
+ * hits written back unchanged cost no row churn.
+ */
+export declare function buildUpsertSql(n: number): string;
+interface PgPoolLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Array<Record<string, any>>;
+        rowCount?: number | null;
+    }>;
+}
+/**
+ * Registers an external Postgres pool & schema (e.g., Supabase Postgres in webcrawl.app cloud)
+ * when the engine is consumed as an installed npm package (`webcrawl/extract/cve-cache`).
+ */
+export declare function registerExternalCveDb(mods: {
+    getPgPool?: () => Promise<PgPoolLike | null>;
+    CVE_SCHEMA_SQL?: string;
+} | null): void;
+/** Swap the backing store (tests). Pass null to restore Postgres. */
+export declare function setCveCacheStoreForTests(store: CveCacheStore | null): void;
+/** Cached records for exact ids (CVE or alias such as GHSA). Never throws. */
+export declare function getCachedCves(ids: string[]): Promise<CachedCves>;
+/** Ids NVD returned for this keyword within QUERY_TTL_MS, or null. Never throws. */
+export declare function getCachedQuery(keyword: string): Promise<string[] | null>;
+export declare function rememberQuery(keyword: string, ids: string[]): void;
+/** Full-text search over cached rows; the fallback when NVD is down or rate limited. */
+export declare function searchCachedCves(keyword: string, limit: number): Promise<CveRecord[]>;
+/** Store records in the window; resolves to rows written (0 on any failure). */
+export declare function upsertCves(records: CveRecord[]): Promise<number>;
+/** Background write that outlives the response on Vercel (no-op elsewhere). */
+export declare function runInBackground(p: Promise<unknown>): void;
+/**
+ * Background refresh of stale ids: fetch live, merge over the cached copy (keeps
+ * OSV fixed versions the live NVD record lacks), write back.
+ */
+export declare function refreshStaleCves(stale: string[], cached: CveRecord[], fetchLive: (ids: string[]) => Promise<CveRecord[]>): void;
+export {};

package/dist/core/extract/cve-cache.js

@@ -0,0 +1,277 @@
+// Read-through CVE cache in Postgres (Supabase in prod). Search fills it as
+// requests resolve CVEs from NVD/OSV, so it grows incrementally with real traffic.
+// Every function degrades to a miss / no-op when there is no DB, the table can't
+// be created, or a query is slow: the cache must never fail or stall a search.
+import { mergeCveRecords, normalizeCveId } from "./cve.js";
+/** Only CVEs published (or numbered) in this year or later are stored. */
+export const CVE_STORE_SINCE = 2020;
+/** Re-fetch a cached record after this long (recent CVEs change faster). */
+const STALE_MS = 7 * 24 * 3600_000;
+const STALE_RECENT_MS = 24 * 3600_000;
+const RECENT_MS = 60 * 24 * 3600_000;
+/** A cached keyword result is trusted for this long before NVD is asked again. */
+export const QUERY_TTL_MS = 24 * 3600_000;
+const DB_TIMEOUT_MS = 1500;
+const UPSERT_CHUNK = 200;
+/** True when a record falls inside the stored window (published year, else id year). */
+export function isCacheableCve(r) {
+    if (r.source === "page")
+        return false;
+    const year = Number((r.published ?? "").slice(0, 4)) || Number(r.id.match(/^CVE-(\d{4})-/i)?.[1]);
+    return Number.isFinite(year) && year >= CVE_STORE_SINCE;
+}
+export function isStale(fetchedAt, published, now = Date.now()) {
+    const age = now - fetchedAt.getTime();
+    const pub = published ? Date.parse(published) : NaN;
+    const recent = Number.isFinite(pub) && now - pub < RECENT_MS;
+    return age > (recent ? STALE_RECENT_MS : STALE_MS);
+}
+export function cveQueryKey(keyword) {
+    return keyword.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 200);
+}
+/** One row of the batched upsert; exported so the SQL shape is unit-testable. */
+export function cveRow(r) {
+    const products = (r.affected ?? [])
+        .map((a) => [a.vendor, a.product, a.ecosystem].filter(Boolean).join(" "))
+        .join(" ")
+        .slice(0, 2000);
+    return [
+        normalizeCveId(r.id),
+        (r.aliases ?? []).map(normalizeCveId),
+        r.title ?? null,
+        r.summary ?? "",
+        r.severity ?? null,
+        r.cvssScore ?? null,
+        products,
+        !!r.kev,
+        r.published ?? null,
+        r.modified ?? null,
+        JSON.stringify(r),
+    ];
+}
+const COLS = 11;
+/**
+ * INSERT … ON CONFLICT for `n` rows. An existing row is only replaced when the
+ * incoming record is at least as new (`modified`) and actually differs, so cache
+ * hits written back unchanged cost no row churn.
+ */
+export function buildUpsertSql(n) {
+    const values = Array.from({ length: n }, (_, i) => {
+        const b = i * COLS;
+        return `($${b + 1}, $${b + 2}::text[], $${b + 3}, $${b + 4}, $${b + 5}, $${b + 6}::real, $${b + 7}, $${b + 8}, $${b + 9}::timestamptz, $${b + 10}::timestamptz, $${b + 11}::jsonb)`;
+    }).join(",\n");
+    return `INSERT INTO cves (id, aliases, title, summary, severity, cvss_score, products, kev, published, modified, record)
+VALUES ${values}
+ON CONFLICT (id) DO UPDATE SET
+  aliases = EXCLUDED.aliases, title = EXCLUDED.title, summary = EXCLUDED.summary,
+  severity = EXCLUDED.severity, cvss_score = EXCLUDED.cvss_score, products = EXCLUDED.products,
+  kev = EXCLUDED.kev, published = EXCLUDED.published, modified = EXCLUDED.modified,
+  record = EXCLUDED.record, fetched_at = NOW()
+WHERE (cves.modified IS NULL OR EXCLUDED.modified IS NULL OR EXCLUDED.modified >= cves.modified)
+  AND (cves.record IS DISTINCT FROM EXCLUDED.record OR cves.fetched_at < NOW() - INTERVAL '1 hour')`;
+}
+function withTimeout(p, fallback, ms = DB_TIMEOUT_MS) {
+    let timer;
+    return Promise.race([
+        p.catch(() => fallback),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(fallback), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+let tableState = null;
+let optionalDbPromise = null;
+/**
+ * Registers an external Postgres pool & schema (e.g., Supabase Postgres in webcrawl.app cloud)
+ * when the engine is consumed as an installed npm package (`webcrawl/extract/cve-cache`).
+ */
+export function registerExternalCveDb(mods) {
+    optionalDbPromise = Promise.resolve(mods);
+    tableState = null;
+}
+function loadOptionalDbModules() {
+    if (!optionalDbPromise) {
+        const dbIndexPath = "../db/index.js";
+        const dbSchemaPath = "../db/schema.js";
+        optionalDbPromise = Promise.all([
+            import(/* @vite-ignore */ dbIndexPath).catch(() => null),
+            import(/* @vite-ignore */ dbSchemaPath).catch(() => null),
+        ]).then(([dbMod, schemaMod]) => {
+            if (!dbMod?.getPgPool)
+                return null;
+            return {
+                getPgPool: dbMod.getPgPool,
+                CVE_SCHEMA_SQL: schemaMod?.CVE_SCHEMA_SQL,
+            };
+        });
+    }
+    return optionalDbPromise;
+}
+async function cvePool() {
+    const mods = await loadOptionalDbModules();
+    if (!mods?.getPgPool)
+        return null;
+    const pool = await mods.getPgPool();
+    if (!pool)
+        return null;
+    tableState ??= (async () => {
+        try {
+            const r = await pool.query("SELECT to_regclass('public.cves') IS NOT NULL AND to_regclass('public.cve_queries') IS NOT NULL AS ok");
+            if (!r.rows[0]?.ok && mods.CVE_SCHEMA_SQL) {
+                await pool.query(mods.CVE_SCHEMA_SQL);
+            }
+            return true;
+        }
+        catch (err) {
+            console.warn("[cve-cache] disabled:", err instanceof Error ? err.message : err);
+            return false;
+        }
+    })();
+    return (await tableState) ? pool : null;
+}
+const pgStore = {
+    async get(ids) {
+        const pool = await cvePool();
+        if (!pool || ids.length === 0)
+            return { records: [], stale: [] };
+        const norm = [...new Set(ids.map(normalizeCveId))];
+        const res = await pool.query("SELECT id, record, fetched_at FROM cves WHERE id = ANY($1::text[]) OR aliases && $1::text[]", [norm]);
+        const records = [];
+        const stale = [];
+        for (const row of res.rows) {
+            const rec = row.record;
+            records.push(rec);
+            if (isStale(new Date(row.fetched_at), rec.published))
+                stale.push(String(row.id));
+        }
+        if (res.rows.length) {
+            runInBackground(pool.query("UPDATE cves SET hits = hits + 1 WHERE id = ANY($1::text[])", [
+                res.rows.map((r) => r.id),
+            ]));
+        }
+        return { records, stale };
+    },
+    async getQuery(keyword) {
+        const pool = await cvePool();
+        if (!pool)
+            return null;
+        const res = await pool.query("SELECT ids FROM cve_queries WHERE keyword = $1 AND fetched_at > NOW() - make_interval(secs => $2)", [cveQueryKey(keyword), QUERY_TTL_MS / 1000]);
+        return res.rows[0] ? res.rows[0].ids : null;
+    },
+    async putQuery(keyword, ids) {
+        const pool = await cvePool();
+        if (!pool)
+            return;
+        await pool.query(`INSERT INTO cve_queries (keyword, ids, fetched_at) VALUES ($1, $2::text[], NOW())
+       ON CONFLICT (keyword) DO UPDATE SET ids = EXCLUDED.ids, fetched_at = NOW()`, [cveQueryKey(keyword), ids.map(normalizeCveId)]);
+    },
+    async search(keyword, limit) {
+        const pool = await cvePool();
+        if (!pool || !keyword.trim())
+            return [];
+        const res = await pool.query(`SELECT record FROM cves, websearch_to_tsquery('simple', $1) q
+       WHERE search @@ q
+       ORDER BY ts_rank(search, q) DESC, published DESC NULLS LAST
+       LIMIT $2`, [keyword, limit]);
+        return res.rows.map((r) => r.record);
+    },
+    async upsert(records) {
+        const pool = await cvePool();
+        if (!pool)
+            return 0;
+        let written = 0;
+        for (let i = 0; i < records.length; i += UPSERT_CHUNK) {
+            const chunk = records.slice(i, i + UPSERT_CHUNK);
+            const res = await pool.query(buildUpsertSql(chunk.length), chunk.flatMap(cveRow));
+            written += res.rowCount ?? 0;
+        }
+        return written;
+    },
+};
+let override = null;
+/** Swap the backing store (tests). Pass null to restore Postgres. */
+export function setCveCacheStoreForTests(store) {
+    override = store;
+    tableState = null;
+}
+function store() {
+    return override ?? pgStore;
+}
+function debug(msg) {
+    if (process.env.DEBUG_SEARCH_TIMING || process.env.DEBUG_CVE_CACHE)
+        console.log(`[cve-cache] ${msg}`);
+}
+/** Cached records for exact ids (CVE or alias such as GHSA). Never throws. */
+export async function getCachedCves(ids) {
+    if (ids.length === 0)
+        return { records: [], stale: [] };
+    const out = await withTimeout(store().get(ids), { records: [], stale: [] });
+    debug(`get ${ids.join(",")} -> ${out.records.length} hit, ${out.stale.length} stale`);
+    return out;
+}
+/** Ids NVD returned for this keyword within QUERY_TTL_MS, or null. Never throws. */
+export async function getCachedQuery(keyword) {
+    const ids = await withTimeout(store().getQuery(keyword), null);
+    debug(`query "${keyword}" -> ${ids ? `${ids.length} ids` : "miss"}`);
+    return ids;
+}
+export function rememberQuery(keyword, ids) {
+    runInBackground(store().putQuery(keyword, ids));
+}
+/** Full-text search over cached rows; the fallback when NVD is down or rate limited. */
+export async function searchCachedCves(keyword, limit) {
+    return withTimeout(store().search(keyword, limit), []);
+}
+/** Store records in the window; resolves to rows written (0 on any failure). */
+export async function upsertCves(records) {
+    const keep = records.filter(isCacheableCve);
+    if (keep.length === 0)
+        return 0;
+    try {
+        const n = await store().upsert(keep);
+        debug(`upsert ${keep.length} -> ${n} written`);
+        return n;
+    }
+    catch (err) {
+        console.warn("[cve-cache] upsert failed:", err instanceof Error ? err.message : err);
+        return 0;
+    }
+}
+let vercelWaitUntilPromise = null;
+function getOptionalWaitUntil() {
+    if (!vercelWaitUntilPromise) {
+        const pkgName = "@vercel/functions";
+        vercelWaitUntilPromise = import(/* @vite-ignore */ pkgName)
+            .then((m) => (typeof m?.waitUntil === "function" ? m.waitUntil : null))
+            .catch(() => null);
+    }
+    return vercelWaitUntilPromise;
+}
+/** Background write that outlives the response on Vercel (no-op elsewhere). */
+export function runInBackground(p) {
+    const safe = p.catch(() => { });
+    void getOptionalWaitUntil().then((fn) => {
+        try {
+            fn?.(safe);
+        }
+        catch {
+            void safe;
+        }
+    });
+}
+/**
+ * Background refresh of stale ids: fetch live, merge over the cached copy (keeps
+ * OSV fixed versions the live NVD record lacks), write back.
+ */
+export function refreshStaleCves(stale, cached, fetchLive) {
+    if (stale.length === 0)
+        return;
+    runInBackground((async () => {
+        const live = await fetchLive(stale);
+        if (live.length === 0)
+            return;
+        const staleSet = new Set(stale);
+        const merged = mergeCveRecords([...live, ...cached.filter((c) => staleSet.has(normalizeCveId(c.id)))], stale.length * 2);
+        await upsertCves(merged);
+    })());
+}

package/dist/core/extract/cve.d.ts

@@ -0,0 +1,57 @@
+export type CveSeverity = "critical" | "high" | "medium" | "low" | "none";
+export interface CveAffected {
+    vendor?: string;
+    product: string;
+    ecosystem?: string;
+    /** Human range, e.g. ">=5.6.0 <5.6.2" or "5.6.0, 5.6.1" */
+    versions?: string;
+    fixed?: string;
+}
+export interface CveRecord {
+    id: string;
+    aliases?: string[];
+    title?: string;
+    summary: string;
+    severity?: CveSeverity;
+    /** 0-10, highest available of CVSS v4.0 / v3.1 / v3.0 / v2.0 */
+    cvssScore?: number;
+    cvssVector?: string;
+    cvssVersion?: "4.0" | "3.1" | "3.0" | "2.0";
+    cwe?: string[];
+    affected?: CveAffected[];
+    published?: string;
+    modified?: string;
+    /** Listed in CISA's Known Exploited Vulnerabilities catalog */
+    kev?: boolean;
+    references: string[];
+    url: string;
+    source: "nvd" | "osv" | "page";
+}
+export declare const SEVERITY_ORDER: Record<CveSeverity, number>;
+/** CVSS v3.0/v3.1 base score from a vector string (FIRST spec). Undefined for v4 or malformed vectors. */
+export declare function cvss3BaseScore(vector: string): number | undefined;
+/** CVSS v3/v4 qualitative rating bands. */
+export declare function severityFromScore(score: number | undefined): CveSeverity | undefined;
+export declare function normalizeCveId(id: string): string;
+/** Unique CVE ids in order of first appearance. */
+export declare function extractCveIdsFromText(text: string, max?: number): string[];
+export declare function extractGhsaIdsFromText(text: string, max?: number): string[];
+export declare function looksLikeVulnId(query: string): boolean;
+export declare const nvdUrl: (id: string) => string;
+type Json = Record<string, any>;
+/** One NVD `vulnerabilities[].cve` object (or the wrapper) -> CveRecord. */
+export declare function parseNvdCve(input: Json): CveRecord | null;
+/** NVD 2.0 response body -> records. */
+export declare function parseNvdResponse(body: Json): CveRecord[];
+/** One OSV vulnerability object -> CveRecord, keyed by its CVE alias when it has one. */
+export declare function parseOsvVuln(v: Json): CveRecord | null;
+/**
+ * Merge records for the same vulnerability across sources (matched on id or any alias).
+ * NVD wins for scores, CWE and KEV; OSV fills ecosystem packages and fixed versions.
+ */
+export declare function mergeCveRecords(records: CveRecord[], max?: number): CveRecord[];
+/** Exact-id hits first, then KEV, then severity, then newest. */
+export declare function sortCveRecords(records: CveRecord[], pinnedIds?: string[]): CveRecord[];
+/** "9.8 Critical" / "High" for cards and MCP text. */
+export declare function cveSeverityLabel(r: Pick<CveRecord, "cvssScore" | "severity">): string | undefined;
+export {};