@automatelab/citation-intelligence 0.5.1 → 0.7.0

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

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export declare const sitemapCitationMapInputSchema: {
+    sitemap_url: z.ZodString;
+    domain: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+declare const inputSchema: z.ZodObject<{
+    sitemap_url: z.ZodString;
+    domain: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    sitemap_url: string;
+    domain?: string | undefined;
+    since?: string | undefined;
+}, {
+    sitemap_url: string;
+    domain?: string | undefined;
+    since?: string | undefined;
+    limit?: number | undefined;
+}>;
+export declare function sitemapCitationMap(input: z.infer<typeof inputSchema>): Promise<{
+    sitemap_url: string;
+    total_urls: number;
+    mapped: number;
+    unmapped: number;
+    message: string;
+    domain?: undefined;
+    since?: undefined;
+    fetched_at?: undefined;
+    coverage_pct?: undefined;
+    citations_in_cache?: undefined;
+    mapped_urls?: undefined;
+    unmapped_urls?: undefined;
+    note?: undefined;
+} | {
+    sitemap_url: string;
+    domain: string;
+    total_urls: number;
+    mapped: number;
+    unmapped: number;
+    message: string;
+    since?: undefined;
+    fetched_at?: undefined;
+    coverage_pct?: undefined;
+    citations_in_cache?: undefined;
+    mapped_urls?: undefined;
+    unmapped_urls?: undefined;
+    note?: undefined;
+} | {
+    sitemap_url: string;
+    domain: string;
+    since: string | undefined;
+    fetched_at: string;
+    total_urls: number;
+    mapped: number;
+    unmapped: number;
+    coverage_pct: number;
+    citations_in_cache: number;
+    mapped_urls: {
+        url: string;
+        citation_count: number;
+        unique_queries: number;
+        engines: string[];
+        last_seen: string;
+        sample_queries: string[];
+    }[];
+    unmapped_urls: {
+        url: string;
+    }[];
+    note: string;
+    message?: undefined;
+}>;
+export {};
+//# sourceMappingURL=sitemap-citation-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap-citation-map.d.ts","sourceRoot":"","sources":["../../src/tools/sitemap-citation-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,6BAA6B;;;;;CAuBzC,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;EAA0C,CAAC;AAgC5D,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAsElE,MAAM;wBACK,MAAM;wBACN,MAAM;iBACb,MAAM,EAAE;mBACN,MAAM;wBACD,MAAM,EAAE;;;aAEA,MAAM;;;;GA4CjC"}

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

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import * as cheerio from "cheerio";
+import { fetchText } from "../lib/fetch.js";
+import { citedForDomain } from "../lib/cache.js";
+import { log } from "../lib/log.js";
+export const sitemapCitationMapInputSchema = {
+    sitemap_url: z
+        .string()
+        .url()
+        .describe("URL of sitemap.xml (or a sitemap index). Nested sitemaps are followed."),
+    domain: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Domain to look up citations for. If omitted, inferred from the sitemap host."),
+    since: z
+        .string()
+        .optional()
+        .describe("ISO date floor; only count citations recorded on or after this date."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(5000)
+        .default(500)
+        .describe("Max sitemap URLs to consider."),
+};
+const inputSchema = z.object(sitemapCitationMapInputSchema);
+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);
+}
+function normalizeUrl(u) {
+    try {
+        const parsed = new URL(u);
+        parsed.hash = "";
+        let p = parsed.pathname.replace(/\/+$/, "") || "/";
+        parsed.pathname = p;
+        return parsed.toString().toLowerCase();
+    }
+    catch {
+        return u.toLowerCase();
+    }
+}
+export async function sitemapCitationMap(input) {
+    const parsed = inputSchema.parse(input);
+    log.debug("sitemap_citation_map start", { sitemap_url: parsed.sitemap_url });
+    const inferredDomain = parsed.domain ?? (() => {
+        try {
+            return new URL(parsed.sitemap_url).hostname;
+        }
+        catch {
+            return "";
+        }
+    })();
+    if (!inferredDomain) {
+        return {
+            sitemap_url: parsed.sitemap_url,
+            total_urls: 0,
+            mapped: 0,
+            unmapped: 0,
+            message: "could not infer domain from sitemap_url and no domain provided",
+        };
+    }
+    const urls = (await parseSitemap(parsed.sitemap_url)).slice(0, parsed.limit);
+    if (urls.length === 0) {
+        return {
+            sitemap_url: parsed.sitemap_url,
+            domain: inferredDomain,
+            total_urls: 0,
+            mapped: 0,
+            unmapped: 0,
+            message: "no URLs found in sitemap",
+        };
+    }
+    const citations = await citedForDomain(inferredDomain, parsed.since, undefined, 100_000);
+    // Bucket cached citations by normalized URL.
+    const byUrl = new Map();
+    for (const c of citations) {
+        const norm = normalizeUrl(c.url);
+        let entry = byUrl.get(norm);
+        if (!entry) {
+            entry = {
+                queries: new Set(),
+                engines: new Set(),
+                last_seen: c.fetched_at,
+                raw_urls: new Set(),
+            };
+            byUrl.set(norm, entry);
+        }
+        entry.queries.add(c.query);
+        entry.engines.add(c.engine);
+        entry.raw_urls.add(c.url);
+        if (c.fetched_at > entry.last_seen)
+            entry.last_seen = c.fetched_at;
+    }
+    const mapped = [];
+    const unmapped = [];
+    for (const u of urls) {
+        const norm = normalizeUrl(u);
+        const hit = byUrl.get(norm);
+        if (!hit) {
+            unmapped.push({ url: u });
+            continue;
+        }
+        const sampleQueries = [...hit.queries].slice(0, 5);
+        mapped.push({
+            url: u,
+            citation_count: citations.filter((c) => normalizeUrl(c.url) === norm).length,
+            unique_queries: hit.queries.size,
+            engines: [...hit.engines].sort(),
+            last_seen: hit.last_seen,
+            sample_queries: sampleQueries,
+        });
+    }
+    mapped.sort((a, b) => b.citation_count - a.citation_count || b.unique_queries - a.unique_queries);
+    // Bucket sitemap URLs that aren't mapped, ranked by traffic potential isn't
+    // available here - emit deterministically (alphabetical, top first).
+    unmapped.sort((a, b) => a.url.localeCompare(b.url));
+    return {
+        sitemap_url: parsed.sitemap_url,
+        domain: inferredDomain,
+        since: parsed.since,
+        fetched_at: new Date().toISOString(),
+        total_urls: urls.length,
+        mapped: mapped.length,
+        unmapped: unmapped.length,
+        coverage_pct: urls.length === 0 ? 0 : Math.round((mapped.length / urls.length) * 1000) / 10,
+        citations_in_cache: citations.length,
+        mapped_urls: mapped,
+        unmapped_urls: unmapped.slice(0, 200),
+        note: "mapped_urls = sitemap URLs that appear in the citation cache. unmapped_urls = sitemap URLs the cache has never seen cited (next-action candidates). Coverage_pct = mapped / total_urls. Cache must be primed first via check_citations or run_panel.",
+    };
+}
+//# sourceMappingURL=sitemap-citation-map.js.map

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

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

package/dist/tools/structured-data-repair.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const structuredDataRepairInputSchema: {
+    url: z.ZodString;
+};
+declare const inputSchema: z.ZodObject<{
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+export declare function structuredDataRepair(input: z.infer<typeof inputSchema>): Promise<{
+    url: string;
+    fetched_at: string;
+    schema_types_present: string[];
+    signals_detected: Record<string, string>;
+    suggestions: {
+        type: string;
+        signal: string;
+        ready_to_paste: string;
+    }[];
+    summary: {
+        types_present: number;
+        signals_detected: number;
+        suggestions_count: number;
+    };
+    note: string;
+}>;
+export {};
+//# sourceMappingURL=structured-data-repair.d.ts.map

package/dist/tools/structured-data-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-data-repair.d.ts","sourceRoot":"","sources":["../../src/tools/structured-data-repair.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,+BAA+B;;CAO3C,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;EAA4C,CAAC;AA4P9D,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC;;;;;;;;;;;;;;;;GAwF5E"}

package/dist/tools/structured-data-repair.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import * as cheerio from "cheerio";
+import { fetchText, ToolFetchError } from "../lib/fetch.js";
+export const structuredDataRepairInputSchema = {
+    url: z
+        .string()
+        .url()
+        .describe("URL to inspect for missing JSON-LD. The page is fetched and its content signals are used to suggest schema types."),
+};
+const inputSchema = z.object(structuredDataRepairInputSchema);
+// Detect @types already present in any JSON-LD block on the page.
+function extractPresentTypes(html) {
+    const $ = cheerio.load(html);
+    const present = new Set();
+    $('script[type="application/ld+json"]').each((_, el) => {
+        try {
+            const json = JSON.parse($(el).text());
+            collectTypes(json, present);
+        }
+        catch {
+            // ignore malformed blocks
+        }
+    });
+    return present;
+}
+function collectTypes(node, out) {
+    if (!node || typeof node !== "object")
+        return;
+    if (Array.isArray(node)) {
+        node.forEach((n) => collectTypes(n, out));
+        return;
+    }
+    const obj = node;
+    const t = obj["@type"];
+    const types = Array.isArray(t)
+        ? t.filter((x) => typeof x === "string")
+        : typeof t === "string"
+            ? [t]
+            : [];
+    for (const type of types)
+        out.add(type);
+    for (const v of Object.values(obj))
+        collectTypes(v, out);
+}
+function buildBlogPostingTemplate($, url) {
+    const headline = $('meta[property="og:title"]').attr("content") ||
+        $("h1").first().text().trim() ||
+        "FILL: Article headline";
+    const description = $('meta[property="og:description"]').attr("content") ||
+        $('meta[name="description"]').attr("content") ||
+        "FILL: Article description";
+    const datePublished = $('meta[property="article:published_time"]').attr("content") ||
+        $('time[datetime]').first().attr("datetime") ||
+        "FILL: 2025-01-01T00:00:00Z";
+    const author = $('meta[name="author"]').attr("content") ||
+        $('[rel="author"]').first().text().trim() ||
+        "FILL: Author Name";
+    const image = $('meta[property="og:image"]').attr("content") || "FILL: https://…/image.jpg";
+    return {
+        "@context": "https://schema.org",
+        "@type": "BlogPosting",
+        headline,
+        description,
+        url,
+        datePublished,
+        author: { "@type": "Person", name: author },
+        image,
+    };
+}
+function buildFaqTemplate($, pairs) {
+    const mainEntity = pairs.slice(0, 5).map(({ q, a }) => ({
+        "@type": "Question",
+        name: q,
+        acceptedAnswer: { "@type": "Answer", text: a },
+    }));
+    if (mainEntity.length === 0) {
+        mainEntity.push({
+            "@type": "Question",
+            name: "FILL: Question text?",
+            acceptedAnswer: { "@type": "Answer", text: "FILL: Answer text." },
+        });
+    }
+    return {
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        mainEntity,
+    };
+}
+function buildHowToTemplate(steps, $) {
+    const name = $('meta[property="og:title"]').attr("content") ||
+        $("h1").first().text().trim() ||
+        "FILL: How-to title";
+    const stepItems = steps.length > 0
+        ? steps.slice(0, 10).map((text, i) => ({
+            "@type": "HowToStep",
+            position: i + 1,
+            text: text.trim(),
+        }))
+        : [
+            { "@type": "HowToStep", position: 1, text: "FILL: Step 1 instructions." },
+            { "@type": "HowToStep", position: 2, text: "FILL: Step 2 instructions." },
+        ];
+    return {
+        "@context": "https://schema.org",
+        "@type": "HowTo",
+        name,
+        step: stepItems,
+    };
+}
+function buildBreadcrumbTemplate(url, $) {
+    const parsed = new URL(url);
+    const parts = parsed.pathname.replace(/\/$/, "").split("/").filter(Boolean);
+    const itemListElement = [
+        {
+            "@type": "ListItem",
+            position: 1,
+            name: $('meta[property="og:site_name"]').attr("content") || "Home",
+            item: `${parsed.protocol}//${parsed.host}/`,
+        },
+        ...parts.map((seg, i) => ({
+            "@type": "ListItem",
+            position: i + 2,
+            name: seg
+                .replace(/[-_]/g, " ")
+                .replace(/\b\w/g, (c) => c.toUpperCase()) || "FILL: Section name",
+            item: `${parsed.protocol}//${parsed.host}/${parts.slice(0, i + 1).join("/")}/`,
+        })),
+    ];
+    return {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        itemListElement,
+    };
+}
+function buildOrganizationTemplate($, url) {
+    const parsed = new URL(url);
+    const name = $('meta[property="og:site_name"]').attr("content") ||
+        $("title").text().trim() ||
+        "FILL: Organization name";
+    const logo = $('link[rel="icon"][type="image/png"]').attr("href") ||
+        $('link[rel="apple-touch-icon"]').attr("href") ||
+        "FILL: https://…/logo.png";
+    return {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        name,
+        url: `${parsed.protocol}//${parsed.host}/`,
+        logo,
+        sameAs: ["FILL: https://twitter.com/…", "FILL: https://linkedin.com/company/…"],
+    };
+}
+// Heuristics to detect content signals.
+function detectSignals(html, url) {
+    const $ = cheerio.load(html);
+    const signals = new Map();
+    // BlogPosting signal: og:type=article or a byline element
+    const ogType = $('meta[property="og:type"]').attr("content");
+    const hasAuthor = $('[rel="author"], .author, .byline, [class*="author"], [class*="byline"]').length > 0;
+    if (ogType === "article" || hasAuthor) {
+        signals.set("BlogPosting", ogType === "article" ? "og:type=article" : "byline element found");
+    }
+    // FAQPage signal: heading that looks like a question followed by a paragraph
+    const faqPairs = [];
+    $("h2, h3, h4, dt").each((_, el) => {
+        const text = $(el).text().trim();
+        if (text.endsWith("?") || /^(what|how|why|when|where|who|can|does|is|are|do)/i.test(text)) {
+            const answer = $(el).next("p, dd").text().trim() ||
+                $(el).next("div").find("p").first().text().trim();
+            if (answer.length > 20) {
+                faqPairs.push({ q: text, a: answer.slice(0, 300) });
+            }
+        }
+    });
+    if (faqPairs.length >= 2) {
+        signals.set("FAQPage", `${faqPairs.length} question/answer pairs detected`);
+        signals.set("_faqPairs", faqPairs);
+    }
+    // HowTo signal: ordered list or headings with step/numbered prefix
+    const olItems = [];
+    $("ol > li").each((_, el) => {
+        olItems.push($(el).text().trim());
+    });
+    const stepHeadings = [];
+    $("h2, h3").each((_, el) => {
+        const t = $(el).text().trim();
+        if (/^step\s*\d+/i.test(t) || /^\d+[\.\)]\s/.test(t)) {
+            stepHeadings.push(t);
+        }
+    });
+    if (olItems.length >= 3) {
+        signals.set("HowTo", `ordered list with ${olItems.length} items`);
+        signals.set("_steps", olItems);
+    }
+    else if (stepHeadings.length >= 2) {
+        signals.set("HowTo", `${stepHeadings.length} step headings`);
+        signals.set("_steps", stepHeadings);
+    }
+    // BreadcrumbList signal: pathname has 2+ segments
+    try {
+        const parts = new URL(url).pathname.replace(/\/$/, "").split("/").filter(Boolean);
+        if (parts.length >= 2) {
+            signals.set("BreadcrumbList", `URL has ${parts.length + 1} path segments`);
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Organization signal: root URL (homepage)
+    try {
+        const parsed = new URL(url);
+        if (parsed.pathname === "/" || parsed.pathname === "") {
+            signals.set("Organization", "homepage URL");
+        }
+    }
+    catch {
+        // ignore
+    }
+    return signals;
+}
+export async function structuredDataRepair(input) {
+    const parsed = inputSchema.parse(input);
+    const url = parsed.url;
+    const { text, status } = await fetchText(url, { timeoutMs: 15_000 });
+    if (status >= 400) {
+        throw new ToolFetchError({
+            type: "fetch_error",
+            url,
+            status,
+            message: `URL returned HTTP ${status} - cannot inspect a non-existent page.`,
+        });
+    }
+    const $ = cheerio.load(text);
+    const presentTypes = extractPresentTypes(text);
+    const signals = detectSignals(text, url);
+    // Build suggestions for signalled types that are not already present.
+    const suggestions = [];
+    if (signals.has("BlogPosting") && !presentTypes.has("BlogPosting") && !presentTypes.has("Article")) {
+        suggestions.push({
+            type: "BlogPosting",
+            signal: signals.get("BlogPosting"),
+            template: buildBlogPostingTemplate($, url),
+        });
+    }
+    if (signals.has("FAQPage") && !presentTypes.has("FAQPage")) {
+        const faqPairs = signals.get("_faqPairs");
+        suggestions.push({
+            type: "FAQPage",
+            signal: signals.get("FAQPage"),
+            template: buildFaqTemplate($, faqPairs ?? []),
+        });
+    }
+    if (signals.has("HowTo") && !presentTypes.has("HowTo")) {
+        const steps = signals.get("_steps");
+        suggestions.push({
+            type: "HowTo",
+            signal: signals.get("HowTo"),
+            template: buildHowToTemplate(steps ?? [], $),
+        });
+    }
+    if (signals.has("BreadcrumbList") && !presentTypes.has("BreadcrumbList")) {
+        suggestions.push({
+            type: "BreadcrumbList",
+            signal: signals.get("BreadcrumbList"),
+            template: buildBreadcrumbTemplate(url, $),
+        });
+    }
+    if (signals.has("Organization") && !presentTypes.has("Organization")) {
+        suggestions.push({
+            type: "Organization",
+            signal: signals.get("Organization"),
+            template: buildOrganizationTemplate($, url),
+        });
+    }
+    const signalEntries = {};
+    for (const [k, v] of signals.entries()) {
+        if (!k.startsWith("_"))
+            signalEntries[k] = v;
+    }
+    return {
+        url,
+        fetched_at: new Date().toISOString(),
+        schema_types_present: [...presentTypes],
+        signals_detected: signalEntries,
+        suggestions: suggestions.map((s) => ({
+            type: s.type,
+            signal: s.signal,
+            ready_to_paste: JSON.stringify(s.template, null, 2),
+        })),
+        summary: {
+            types_present: presentTypes.size,
+            signals_detected: Object.keys(signalEntries).length,
+            suggestions_count: suggestions.length,
+        },
+        note: "Fields marked 'FILL:' require manual completion. Paste each ready_to_paste block into a <script type=\"application/ld+json\"> tag in <head>.",
+    };
+}
+//# sourceMappingURL=structured-data-repair.js.map

package/dist/tools/structured-data-repair.js.map

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

package/dist/types.d.ts

@@ -1,4 +1,12 @@
-export type Engine = "perplexity" | "claude" | "openai" | "gemini" | "bing" | "brave" | "auto";
+export type Engine = "perplexity" | "claude" | "openai" | "gemini" | "bing_serp" | "brave_serp" | "brave" | "google_ai_mode" | "auto";
+/** How the data was collected — lets callers understand what the result actually measures. */
+export type Surface = "consumer_scrape" | "api_proxy" | "web_rank" | "static_signal";
+export declare const ENGINE_SURFACE: Record<Exclude<Engine, "auto">, Surface>;
+/**
+ * One-line note explaining what each engine result actually measures vs the
+ * consumer product. Included in every tool response as `interpretation_note`.
+ */
+export declare const ENGINE_INTERPRETATION_NOTE: Record<Exclude<Engine, "auto">, string>;
 export type Citation = {
     url: string;
     title?: string;
@@ -8,6 +16,7 @@ export type Citation = {
 export type NormalizedCitationResult = {
     query: string;
     engine: Engine;
+    surface: Surface;
     fetched_at: string;
     citations: Citation[];
     raw_answer?: string;
@@ -19,7 +28,7 @@ export type AdapterResult = {
 };
 export type ToolError = {
     type: "missing_key";
-    engine: Engine;
+    engine: Engine | "google_ai_mode";
     env_var: string;
     message: string;
 } | {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GACd,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GACd,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,OAAO,GACP,gBAAgB,GAChB,MAAM,CAAC;AAEX,8FAA8F;AAC9F,MAAM,MAAM,OAAO,GACf,iBAAiB,GACjB,WAAW,GACX,UAAU,GACV,eAAe,CAAC;AAEpB,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CASnE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAiB9E,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -1,2 +1,25 @@
-export {};
+export const ENGINE_SURFACE = {
+    perplexity: "consumer_scrape",
+    claude: "api_proxy",
+    openai: "api_proxy",
+    gemini: "api_proxy",
+    google_ai_mode: "consumer_scrape",
+    bing_serp: "web_rank",
+    brave_serp: "web_rank",
+    brave: "web_rank",
+};
+/**
+ * One-line note explaining what each engine result actually measures vs the
+ * consumer product. Included in every tool response as `interpretation_note`.
+ */
+export const ENGINE_INTERPRETATION_NOTE = {
+    google_ai_mode: "SerpAPI scrape of the real Google AI Overview — pixel-accurate to what google.com users see.",
+    perplexity: "sonar-pro API with a consumer-equivalent system prompt. Real perplexity.ai users may see sonar-reasoning-pro with multi-turn follow-ups.",
+    openai: "gpt-4o-search-preview API. Real chatgpt.com users get gpt-4o + SearchGPT with different ranking and UI-level re-scoring.",
+    claude: "claude-sonnet-4-7 API with web_search tool (max 5 uses). Real claude.ai users get a different model tier and citation UI.",
+    gemini: "gemini-2.5-pro API with google_search grounding. Real gemini.google.com uses the same grounding index but different re-ranking.",
+    bing_serp: "Bing Web Search API — traditional SERP rank, NOT LLM citation behavior.",
+    brave_serp: "Brave Search API — traditional SERP rank, NOT LLM citation behavior.",
+    brave: "Brave Search API — traditional SERP rank, NOT LLM citation behavior.",
+};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,cAAc,GAA6C;IACtE,UAAU,EAAE,iBAAiB;IAC7B,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,cAAc,EAAE,iBAAiB;IACjC,SAAS,EAAE,UAAU;IACrB,UAAU,EAAE,UAAU;IACtB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA4C;IACjF,cAAc,EACZ,8FAA8F;IAChG,UAAU,EACR,0IAA0I;IAC5I,MAAM,EACJ,0HAA0H;IAC5H,MAAM,EACJ,2HAA2H;IAC7H,MAAM,EACJ,iIAAiI;IACnI,SAAS,EACP,yEAAyE;IAC3E,UAAU,EACR,sEAAsE;IACxE,KAAK,EACH,sEAAsE;CACzE,CAAC"}