@automatelab/citation-intelligence 0.4.0

package/dist/tools/ai-overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-overview.d.ts","sourceRoot":"","sources":["../../src/tools/ai-overview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,qBAAqB;;;;CAOjC,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;EAAkC,CAAC;AAEpD,wBAAsB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;GAqClE"}

package/dist/tools/ai-overview.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { serpapiAiOverview } from "../adapters/serpapi.js";
+import { getAiOverview, putAiOverview } from "../lib/cache.js";
+export const aiOverviewInputSchema = {
+    query: z.string().min(1).describe("Search query to check for Google AI Overview."),
+    location: z
+        .string()
+        .optional()
+        .describe("Location string, e.g. 'United States'. Affects AI Overview eligibility."),
+    hl: z.string().default("en").describe("Language code, default 'en'."),
+};
+const inputSchema = z.object(aiOverviewInputSchema);
+export async function aiOverview(input) {
+    const parsed = inputSchema.parse(input);
+    const cached = await getAiOverview(parsed.query, parsed.location, parsed.hl);
+    if (cached) {
+        return {
+            query: parsed.query,
+            fetched_at: cached.fetched_at,
+            ai_overview_present: cached.ai_overview_present,
+            ai_overview_text: cached.ai_overview_text,
+            sources: cached.sources,
+            cached: true,
+        };
+    }
+    const res = await serpapiAiOverview(parsed.query, parsed.location, parsed.hl);
+    const fetched_at = new Date().toISOString();
+    await putAiOverview({
+        type: "ai_overview",
+        query: parsed.query,
+        location: parsed.location,
+        hl: parsed.hl,
+        fetched_at,
+        ai_overview_present: res.ai_overview_present,
+        ai_overview_text: res.ai_overview_text,
+        sources: res.sources,
+    });
+    return {
+        query: parsed.query,
+        fetched_at,
+        ai_overview_present: res.ai_overview_present,
+        ai_overview_text: res.ai_overview_text,
+        sources: res.sources,
+        cached: false,
+    };
+}
+//# sourceMappingURL=ai-overview.js.map

package/dist/tools/ai-overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-overview.js","sourceRoot":"","sources":["../../src/tools/ai-overview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,+CAA+C,CAAC;IAClF,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,yEAAyE,CAAC;IACtF,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CACtE,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEpD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAkC;IACjE,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAExC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7E,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;YAC/C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE5C,MAAM,aAAa,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,UAAU;QACV,mBAAmB,EAAE,GAAG,CAAC,mBAAmB;QAC5C,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,UAAU;QACV,mBAAmB,EAAE,GAAG,CAAC,mBAAmB;QAC5C,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM,EAAE,KAAK;KACd,CAAC;AACJ,CAAC"}

package/dist/tools/am-i-cited.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { Engine } from "../types.js";
+export declare const amICitedInputSchema: {
+    domain: z.ZodString;
+    queries: z.ZodArray<z.ZodString, "many">;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+};
+declare const inputSchema: z.ZodObject<{
+    domain: z.ZodString;
+    queries: z.ZodArray<z.ZodString, "many">;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+}, "strip", z.ZodTypeAny, {
+    engine: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto";
+    domain: string;
+    queries: string[];
+}, {
+    domain: string;
+    queries: string[];
+    engine?: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto" | undefined;
+}>;
+export declare function amICited(input: z.infer<typeof inputSchema>): Promise<{
+    domain: string;
+    engine: Engine;
+    fetched_at: string;
+    results: {
+        query: string;
+        cited: boolean;
+        rank?: number;
+        matching_urls: string[];
+    }[];
+    summary: {
+        queries_total: number;
+        queries_cited: number;
+        citation_rate: number;
+        average_rank: number | undefined;
+    };
+}>;
+export {};
+//# sourceMappingURL=am-i-cited.d.ts.map

package/dist/tools/am-i-cited.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"am-i-cited.d.ts","sourceRoot":"","sources":["../../src/tools/am-i-cited.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAO,MAAM,mBAAmB;;;;CAc/B,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;EAAgC,CAAC;AAoBlD,wBAAsB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;eAKtD,MAAM;eACN,OAAO;eACP,MAAM;uBACE,MAAM,EAAE;;;;;;;;GAwC1B"}

package/dist/tools/am-i-cited.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { checkCitations } from "./check-citations.js";
+export const amICitedInputSchema = {
+    domain: z
+        .string()
+        .min(1)
+        .describe("Domain to check, e.g. 'automatelab.tech' (without protocol)."),
+    queries: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(20)
+        .describe("Queries to test the domain against. 1-20 queries per call."),
+    engine: z
+        .enum(["perplexity", "claude", "openai", "gemini", "bing", "auto"])
+        .default("auto")
+        .describe("AI engine to query."),
+};
+const inputSchema = z.object(amICitedInputSchema);
+function normalizeDomain(d) {
+    return d
+        .replace(/^https?:\/\//, "")
+        .replace(/^www\./, "")
+        .replace(/\/$/, "")
+        .toLowerCase();
+}
+function urlMatchesDomain(url, needle) {
+    try {
+        const u = new URL(url);
+        const host = u.hostname.toLowerCase().replace(/^www\./, "");
+        return host === needle || host.endsWith("." + needle);
+    }
+    catch {
+        return false;
+    }
+}
+export async function amICited(input) {
+    const parsed = inputSchema.parse(input);
+    const needle = normalizeDomain(parsed.domain);
+    const results = [];
+    let resolvedEngine = parsed.engine;
+    for (const query of parsed.queries) {
+        const res = await checkCitations({
+            query,
+            engine: parsed.engine,
+            max_results: 20,
+        });
+        resolvedEngine = res.engine;
+        const matches = res.citations.filter((c) => urlMatchesDomain(c.url, needle));
+        const rank = matches.length > 0 ? matches[0].rank : undefined;
+        results.push({
+            query,
+            cited: matches.length > 0,
+            rank,
+            matching_urls: matches.map((m) => m.url),
+        });
+    }
+    const cited = results.filter((r) => r.cited);
+    const ranks = cited.map((r) => r.rank).filter((r) => r !== undefined);
+    const average_rank = ranks.length > 0 ? ranks.reduce((a, b) => a + b, 0) / ranks.length : undefined;
+    return {
+        domain: parsed.domain,
+        engine: resolvedEngine,
+        fetched_at: new Date().toISOString(),
+        results,
+        summary: {
+            queries_total: parsed.queries.length,
+            queries_cited: cited.length,
+            citation_rate: parsed.queries.length > 0 ? cited.length / parsed.queries.length : 0,
+            average_rank,
+        },
+    };
+}
+//# sourceMappingURL=am-i-cited.js.map

package/dist/tools/am-i-cited.js.map

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

package/dist/tools/audit-sitemap.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export declare const auditSitemapInputSchema: {
+    sitemap_url: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+};
+declare const inputSchema: z.ZodObject<{
+    sitemap_url: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    sitemap_url: string;
+    concurrency: number;
+}, {
+    sitemap_url: string;
+    limit?: number | undefined;
+    concurrency?: number | undefined;
+}>;
+export declare function auditSitemap(input: z.infer<typeof inputSchema>): Promise<{
+    sitemap_url: string;
+    total_urls: number;
+    audited: number;
+    message: string;
+    fetched_at?: undefined;
+    average_score?: undefined;
+    worst_first?: undefined;
+    errors?: undefined;
+} | {
+    sitemap_url: string;
+    fetched_at: string;
+    total_urls: number;
+    audited: number;
+    average_score: number;
+    worst_first: {
+        url: string;
+        score: number;
+        grade: string;
+        signals: Record<string, unknown>;
+        top_fix?: string;
+    }[];
+    errors: {
+        url: string;
+        error: string;
+    }[];
+    message?: undefined;
+}>;
+export {};
+//# sourceMappingURL=audit-sitemap.d.ts.map

package/dist/tools/audit-sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sitemap.d.ts","sourceRoot":"","sources":["../../src/tools/audit-sitemap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,uBAAuB;;;;CAmBnC,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;EAAoC,CAAC;AAkCtD,wBAAsB,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;;;;;;;;;;aAcxD,MAAM;eAAS,MAAM;eAAS,MAAM;iBAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;kBAAY,MAAM;;;aACxF,MAAM;eAAS,MAAM;;;GAmCjC"}

package/dist/tools/audit-sitemap.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import * as cheerio from "cheerio";
+import { fetchText } from "../lib/fetch.js";
+import { predictCitation } from "./predict-citation.js";
+export const auditSitemapInputSchema = {
+    sitemap_url: z
+        .string()
+        .url()
+        .describe("URL of sitemap.xml (or a sitemap index). Nested sitemaps are followed."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(50)
+        .describe("Max URLs to score. Sitemap is sliced after parsing."),
+    concurrency: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .default(3)
+        .describe("Parallel predict_citation calls. Higher is faster but more rate-limit risk."),
+};
+const inputSchema = z.object(auditSitemapInputSchema);
+async function parseSitemap(url, depth = 0) {
+    if (depth > 2)
+        return [];
+    const { text } = await fetchText(url, { timeoutMs: 15_000 });
+    const $ = cheerio.load(text, { xmlMode: true });
+    const childSitemaps = $("sitemap > loc")
+        .toArray()
+        .map((el) => $(el).text().trim())
+        .filter(Boolean);
+    if (childSitemaps.length > 0) {
+        const nested = await Promise.all(childSitemaps.map((s) => parseSitemap(s, depth + 1)));
+        return nested.flat();
+    }
+    return $("url > loc")
+        .toArray()
+        .map((el) => $(el).text().trim())
+        .filter(Boolean);
+}
+async function pool(items, n, fn) {
+    const out = new Array(items.length);
+    let i = 0;
+    const workers = Array.from({ length: Math.min(n, items.length) }, async () => {
+        while (true) {
+            const idx = i++;
+            if (idx >= items.length)
+                return;
+            out[idx] = await fn(items[idx]);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+export async function auditSitemap(input) {
+    const parsed = inputSchema.parse(input);
+    const urls = (await parseSitemap(parsed.sitemap_url)).slice(0, parsed.limit);
+    if (urls.length === 0) {
+        return {
+            sitemap_url: parsed.sitemap_url,
+            total_urls: 0,
+            audited: 0,
+            message: "no URLs found in sitemap",
+        };
+    }
+    const rows = await pool(urls, parsed.concurrency, async (url) => {
+        try {
+            const r = await predictCitation({ url });
+            return {
+                url,
+                score: r.score,
+                grade: r.grade,
+                signals: r.signals,
+                top_fix: r.fixes?.[0]?.suggestion,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { url, error: message };
+        }
+    });
+    const scored = rows.filter((r) => "score" in r);
+    scored.sort((a, b) => a.score - b.score);
+    const avg = scored.length > 0
+        ? scored.reduce((s, r) => s + r.score, 0) / scored.length
+        : 0;
+    return {
+        sitemap_url: parsed.sitemap_url,
+        fetched_at: new Date().toISOString(),
+        total_urls: urls.length,
+        audited: rows.length,
+        average_score: Math.round(avg),
+        worst_first: scored.slice(0, 20),
+        errors: rows.filter((r) => "error" in r),
+    };
+}
+//# sourceMappingURL=audit-sitemap.js.map

package/dist/tools/audit-sitemap.js.map

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

package/dist/tools/check-citations.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { Engine } from "../types.js";
+export declare const checkCitationsInputSchema: {
+    query: z.ZodString;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+};
+declare const inputSchema: z.ZodObject<{
+    query: z.ZodString;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    engine: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto";
+    max_results: number;
+}, {
+    query: string;
+    engine?: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto" | undefined;
+    max_results?: number | undefined;
+}>;
+export declare function checkCitations(input: z.infer<typeof inputSchema>): Promise<{
+    query: string;
+    engine: Engine;
+    fetched_at: string;
+    citations: import("../types.js").Citation[];
+    raw_answer: string | undefined;
+    cached: boolean;
+}>;
+export {};
+//# sourceMappingURL=check-citations.d.ts.map

package/dist/tools/check-citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-citations.d.ts","sourceRoot":"","sources":["../../src/tools/check-citations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,aAAa,CAAC;AAEzD,eAAO,MAAM,yBAAyB;;;;CAarC,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;EAAsC,CAAC;AAgCxD,wBAAsB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;GAmDtE"}

package/dist/tools/check-citations.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { perplexitySearch } from "../adapters/perplexity.js";
+import { bingSearch } from "../adapters/bing.js";
+import { claudeSearch } from "../adapters/anthropic.js";
+import { openaiSearch } from "../adapters/openai.js";
+import { geminiSearch } from "../adapters/gemini.js";
+import { envKey } from "../lib/config.js";
+import { getCitations, putCitations } from "../lib/cache.js";
+import { ToolFetchError } from "../lib/fetch.js";
+export const checkCitationsInputSchema = {
+    query: z.string().min(1).describe("The search query to test (what would a user ask an AI?)"),
+    engine: z
+        .enum(["perplexity", "claude", "openai", "gemini", "bing", "auto"])
+        .default("auto")
+        .describe("AI engine to query. 'auto' picks the first available based on configured API keys."),
+    max_results: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(10)
+        .describe("Maximum citations to return."),
+};
+const inputSchema = z.object(checkCitationsInputSchema);
+function pickAutoEngine() {
+    if (envKey("PERPLEXITY_API_KEY"))
+        return "perplexity";
+    if (envKey("ANTHROPIC_API_KEY"))
+        return "claude";
+    if (envKey("OPENAI_API_KEY"))
+        return "openai";
+    if (envKey("GEMINI_API_KEY"))
+        return "gemini";
+    if (envKey("BING_API_KEY"))
+        return "bing";
+    return null;
+}
+async function runEngine(engine, query, maxResults) {
+    switch (engine) {
+        case "perplexity":
+            return perplexitySearch(query, maxResults);
+        case "claude":
+            return claudeSearch(query, maxResults);
+        case "openai":
+            return openaiSearch(query, maxResults);
+        case "gemini":
+            return geminiSearch(query, maxResults);
+        case "bing":
+            return bingSearch(query, maxResults);
+        case "auto":
+            throw new Error("auto engine should be resolved before runEngine");
+    }
+}
+export async function checkCitations(input) {
+    const parsed = inputSchema.parse(input);
+    const requested = parsed.engine;
+    let engine;
+    if (requested === "auto") {
+        const picked = pickAutoEngine();
+        if (!picked) {
+            throw new ToolFetchError({
+                type: "no_engine_available",
+                message: "No engine API key configured. Set one of: PERPLEXITY_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, BING_API_KEY.",
+            });
+        }
+        engine = picked;
+    }
+    else {
+        engine = requested;
+    }
+    const cached = await getCitations(parsed.query, engine);
+    if (cached) {
+        return {
+            query: parsed.query,
+            engine,
+            fetched_at: cached.fetched_at,
+            citations: cached.citations.slice(0, parsed.max_results),
+            raw_answer: cached.raw_answer,
+            cached: true,
+        };
+    }
+    const result = await runEngine(engine, parsed.query, parsed.max_results);
+    const fetched_at = new Date().toISOString();
+    await putCitations({
+        type: "citation_check",
+        engine,
+        query: parsed.query,
+        fetched_at,
+        citations: result.citations,
+        raw_answer: result.raw_answer,
+    });
+    return {
+        query: parsed.query,
+        engine,
+        fetched_at,
+        citations: result.citations,
+        raw_answer: result.raw_answer,
+        cached: false,
+    };
+}
+//# sourceMappingURL=check-citations.js.map

package/dist/tools/check-citations.js.map

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

package/dist/tools/citation-freshness-score.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const citationFreshnessScoreInputSchema: {
+    query: z.ZodString;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+};
+declare const inputSchema: z.ZodObject<{
+    query: z.ZodString;
+    engine: z.ZodDefault<z.ZodEnum<["perplexity", "claude", "openai", "gemini", "bing", "auto"]>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    engine: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto";
+    max_results: number;
+}, {
+    query: string;
+    engine?: "perplexity" | "claude" | "openai" | "gemini" | "bing" | "auto" | undefined;
+    max_results?: number | undefined;
+}>;
+export declare function citationFreshnessScore(input: z.infer<typeof inputSchema>): Promise<{
+    query: string;
+    engine: import("../types.js").Engine;
+    fetched_at: string;
+    recency_score: number;
+    average_days_old: number | null;
+    buckets: {
+        fresh: number;
+        current: number;
+        stale: number;
+        ancient: number;
+        unknown: number;
+    };
+    per_url: ({
+        url: string;
+        rank: number;
+        date_modified_iso: string | null;
+        last_modified_days_ago: number | null;
+        bucket: "fresh" | "current" | "stale" | "ancient" | "unknown";
+        weight: number;
+        error?: undefined;
+    } | {
+        url: string;
+        rank: number;
+        error: string;
+        date_modified_iso?: undefined;
+        last_modified_days_ago?: undefined;
+        bucket?: undefined;
+        weight?: undefined;
+    })[];
+    note: string;
+}>;
+export {};
+//# sourceMappingURL=citation-freshness-score.d.ts.map

package/dist/tools/citation-freshness-score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-freshness-score.d.ts","sourceRoot":"","sources":["../../src/tools/citation-freshness-score.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,iCAAiC;;;;CAa7C,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;EAA8C,CAAC;AAiBhE,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2D9E"}

package/dist/tools/citation-freshness-score.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { checkCitations } from "./check-citations.js";
+import { collectSignals } from "../adapters/predictors.js";
+import { log } from "../lib/log.js";
+export const citationFreshnessScoreInputSchema = {
+    query: z.string().min(1).describe("Search query whose cited URLs to score for freshness."),
+    engine: z
+        .enum(["perplexity", "claude", "openai", "gemini", "bing", "auto"])
+        .default("auto")
+        .describe("AI engine to query for the citation set."),
+    max_results: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(10)
+        .describe("How many cited URLs to inspect."),
+};
+const inputSchema = z.object(citationFreshnessScoreInputSchema);
+function freshnessBucket(daysAgo) {
+    if (daysAgo === undefined)
+        return "unknown";
+    if (daysAgo <= 180)
+        return "fresh";
+    if (daysAgo <= 365)
+        return "current";
+    if (daysAgo <= 730)
+        return "stale";
+    return "ancient";
+}
+// Recency weight from 0..1; halves every 365 days.
+function weight(daysAgo) {
+    if (daysAgo === undefined)
+        return 0;
+    const halflife = 365;
+    return Math.max(0, Math.pow(0.5, daysAgo / halflife));
+}
+export async function citationFreshnessScore(input) {
+    const parsed = inputSchema.parse(input);
+    log.debug("citation_freshness_score start", { query: parsed.query });
+    const citations = await checkCitations({
+        query: parsed.query,
+        engine: parsed.engine,
+        max_results: parsed.max_results,
+    });
+    const perUrl = await Promise.all(citations.citations.map(async (c) => {
+        try {
+            const signals = await collectSignals(c.url);
+            return {
+                url: c.url,
+                rank: c.rank,
+                date_modified_iso: signals.date_modified_iso ?? null,
+                last_modified_days_ago: signals.last_modified_days_ago ?? null,
+                bucket: freshnessBucket(signals.last_modified_days_ago),
+                weight: Number(weight(signals.last_modified_days_ago).toFixed(3)),
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { url: c.url, rank: c.rank, error: msg };
+        }
+    }));
+    const scored = perUrl.filter((r) => "weight" in r);
+    const known = scored.filter((r) => r.last_modified_days_ago !== null);
+    const avgDaysAgo = known.length > 0
+        ? Math.round(known.reduce((a, r) => a + r.last_modified_days_ago, 0) / known.length)
+        : null;
+    const recencyScore = scored.length > 0
+        ? Math.round((scored.reduce((a, r) => a + r.weight, 0) / scored.length) * 100)
+        : 0;
+    const counts = {
+        fresh: scored.filter((r) => r.bucket === "fresh").length,
+        current: scored.filter((r) => r.bucket === "current").length,
+        stale: scored.filter((r) => r.bucket === "stale").length,
+        ancient: scored.filter((r) => r.bucket === "ancient").length,
+        unknown: perUrl.length - known.length,
+    };
+    return {
+        query: parsed.query,
+        engine: citations.engine,
+        fetched_at: new Date().toISOString(),
+        recency_score: recencyScore,
+        average_days_old: avgDaysAgo,
+        buckets: counts,
+        per_url: perUrl,
+        note: "recency_score is a 0-100 average of per-URL recency weights (halflife=365d). Pages with no detectable dateModified contribute weight 0.",
+    };
+}
+//# sourceMappingURL=citation-freshness-score.js.map

package/dist/tools/citation-freshness-score.js.map

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