agent-bober 0.17.1 → 0.19.0

package/dist/seo/sources/dataforseo-adapter.js

@@ -0,0 +1,335 @@
+/**
+ * DataForSeoAdapter — the SECOND live network `SeoDataSource`
+ * (spec-20260715-ultimate-seo-suite, Sprint 9). Serves `serp` + `keywords` +
+ * `backlinks` from the real DataForSEO v3 API, behind the `"serp-provider"`
+ * egress axis. Near-verbatim clone of `GscAdapter` (Sprint 8) — SAME ADR-5
+ * shape, six diffs: axis, which methods serve data, endpoints/auth, and
+ * (the load-bearing new behavior) real USD cost booking.
+ *
+ * ADR-5 (the load-bearing invariant of this file, reused verbatim from
+ * `GscAdapter`): EVERY capability method that would open a socket begins
+ * with these two gates, IN ORDER, before any network work:
+ *   1. `this.egress.assertAllowed("serp-provider")` — throws when the axis
+ *      is off; caught immediately and converted to `abstain` WITHOUT opening
+ *      a socket (never hoisted into a caller/runner — see `src/seo/egress.ts`).
+ *   2. `this.governor.admit(req)` — synchronous, never throws, no side
+ *      effect; refused admission also aborts before any socket opens.
+ * Only after BOTH gates pass does the injected `HttpClient` make a request.
+ * Any HTTP/network/parse error (including 402/429/5xx) degrades to
+ * `{ kind: "abstain", reason }` — this method NEVER throws to the caller.
+ *
+ * DataForSEO differs from GSC in that it is PAY-AS-YOU-GO: unlike GSC's
+ * `estCostUsd: 0` (free), every serving method here computes a real USD
+ * cost (research §4 price ladder), passes it as `estCostUsd` to `admit()`
+ * (worst-case pre-emption), books the ACTUAL USD via `governor.record()`
+ * only after a successful round-trip, and stamps `provenance.costUsd`.
+ * A 402/429/5xx means DataForSEO did NOT charge — abstain BEFORE any
+ * `record()` call, so nothing is ever booked for a failed request.
+ *
+ * The real global `fetch` is referenced NOWHERE in this file — the injected
+ * `HttpClient` (`../adapters/http.js`) is the sole transport, defaulting to
+ * `defaultHttpClient` (production) or a fixture/spy client (tests), so CI
+ * never opens a real socket.
+ */
+import { Buffer } from "node:buffer";
+import { defaultHttpClient } from "../adapters/http.js";
+// -- DataForSEO endpoint + price constants (research S4) --------------------
+const DFS_BASE = "https://api.dataforseo.com/v3";
+const DFS_SERP_URL = `${DFS_BASE}/serp/google/organic/live/advanced`;
+const DFS_KEYWORDS_URL = `${DFS_BASE}/dataforseo_labs/google/keyword_ideas/live`;
+const DFS_BACKLINKS_URL = `${DFS_BASE}/backlinks/backlinks/live`;
+/** SERP price ladder, per task — research §4 (research-...-research.md:98). DO NOT approximate. */
+const SERP_PRICE_USD = {
+    standard: 0.0006,
+    priority: 0.0012,
+    live: 0.002,
+};
+/** Backlinks pricing — research §4: `$0.02/req + $0.00003/row`. */
+const BACKLINKS_BASE_USD = 0.02;
+const BACKLINKS_PER_ROW_USD = 0.00003;
+/**
+ * bober: research §4 prices only SERP + backlinks, not the keyword_ideas
+ *        endpoint. Using the same per-task price as standard SERP ($0.0006)
+ *        as a documented placeholder — this is an ASSUMPTION, not a pinned
+ *        research number. Revisit if/when a keywords price is confirmed.
+ */
+const KEYWORDS_TASK_USD = 0.0006;
+// -- Response parsers (pure, total — [] on any shape mismatch) --------------
+/** Walk a DataForSEO v3 envelope's `tasks[0].result[0].items[]`; `[]` on any shape mismatch. */
+function firstResultItems(raw) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const tasks = raw["tasks"];
+    if (!Array.isArray(tasks) || tasks.length === 0)
+        return [];
+    const task0 = tasks[0];
+    if (!task0 || typeof task0 !== "object")
+        return [];
+    const result = task0["result"];
+    if (!Array.isArray(result) || result.length === 0)
+        return [];
+    const result0 = result[0];
+    if (!result0 || typeof result0 !== "object")
+        return [];
+    const items = result0["items"];
+    return Array.isArray(items) ? items : [];
+}
+/** Parse a DataForSEO `serp/google/organic/live/advanced` response into typed rows. */
+function parseSerp(raw, keyword, location) {
+    const rows = [];
+    for (const item of firstResultItems(raw)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const r = item;
+        if (typeof r["rank_absolute"] !== "number" || typeof r["url"] !== "string")
+            continue;
+        const row = { keyword, position: r["rank_absolute"], url: r["url"], location };
+        if (typeof r["title"] === "string")
+            row.title = r["title"];
+        rows.push(row);
+    }
+    return rows;
+}
+/** Parse a DataForSEO `dataforseo_labs/google/keyword_ideas/live` response into typed rows. */
+function parseKeywords(raw, location) {
+    const rows = [];
+    for (const item of firstResultItems(raw)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const r = item;
+        if (typeof r["keyword"] !== "string")
+            continue;
+        const row = { keyword: r["keyword"], location };
+        const info = r["keyword_info"];
+        if (info && typeof info === "object") {
+            const i = info;
+            if (typeof i["search_volume"] === "number")
+                row.searchVolume = i["search_volume"];
+            if (typeof i["cpc"] === "number")
+                row.cpc = i["cpc"];
+            if (typeof i["competition"] === "number")
+                row.competition = i["competition"];
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+/** Parse a DataForSEO `backlinks/backlinks/live` response into typed rows. */
+function parseBacklinks(raw) {
+    const rows = [];
+    for (const item of firstResultItems(raw)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const r = item;
+        if (typeof r["url_from"] !== "string" || typeof r["url_to"] !== "string")
+            continue;
+        const row = { sourceUrl: r["url_from"], targetUrl: r["url_to"] };
+        if (typeof r["anchor"] === "string")
+            row.anchor = r["anchor"];
+        if (typeof r["dofollow"] === "boolean")
+            row.dofollow = r["dofollow"];
+        rows.push(row);
+    }
+    return rows;
+}
+// -- DataForSeoAdapter --------------------------------------------------------
+/**
+ * Live DataForSEO `SeoDataSource`. Serves `serp` + `keywords` + `backlinks`;
+ * `search-analytics`/`url-inspection` are NOT DataForSEO capabilities
+ * (`{ kind: "disabled" }` unconditionally — GscAdapter serves those).
+ *
+ * bober: no OAuth/refresh flow here — the HTTP Basic credential is injected
+ *        fully-formed via `getBasicAuth`; add credential rotation only if a
+ *        credential store is wired in a later sprint.
+ */
+export class DataForSeoAdapter {
+    egress;
+    governor;
+    http;
+    getBasicAuth;
+    constructor(egress, governor, 
+    // Injectable transport — default = the ONE global-fetch wrapper
+    // (`../adapters/http.js`). Tests inject a fake `HttpClient`.
+    http = defaultHttpClient, 
+    // HTTP Basic credential provider — injected, NEVER hardcoded. Tests stub
+    // it (`async () => "dGVzdDp0ZXN0"`); production defaults to base64
+    // `login:password` read from env.
+    getBasicAuth = () => Promise.resolve(Buffer.from(`${process.env["DATAFORSEO_LOGIN"] ?? ""}:${process.env["DATAFORSEO_PASSWORD"] ?? ""}`).toString("base64"))) {
+        this.egress = egress;
+        this.governor = governor;
+        this.http = http;
+        this.getBasicAuth = getBasicAuth;
+    }
+    capabilities() {
+        return ["serp", "keywords", "backlinks"];
+    }
+    /**
+     * SERP query. ADR-5 preamble (egress gate, then quota gate) runs before
+     * any network work; USD cost is the fixed per-task price for `q.priority`
+     * (default `"standard"`) — booked in `admit()` (estimate) and `record()`
+     * (actual, identical since SERP is a fixed-price task, sc-9-3).
+     */
+    async serp(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("serp-provider");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-serp-provider-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const price = SERP_PRICE_USD[q.priority ?? "standard"];
+        const admitReq = {
+            source: "dataforseo",
+            capability: "serp",
+            scope: {},
+            estRows: 1, // one task per call; inert for dataforseo (quota-governor.ts:158,179)
+            estCostUsd: price,
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may a socket open. --
+        try {
+            const cred = await this.getBasicAuth();
+            const res = await this.http.request(DFS_SERP_URL, {
+                method: "POST",
+                headers: { Authorization: `Basic ${cred}`, "Content-Type": "application/json" },
+                body: JSON.stringify([{ keyword: q.keyword, location_name: q.location, priority: q.priority }]),
+            });
+            if (!res.ok) {
+                return { kind: "abstain", reason: `dataforseo-http-${res.status}` }; // 402/429/5xx -> abstain, NEVER throw
+            }
+            const rows = parseSerp(await res.json(), q.keyword, q.location);
+            // SERP is a fixed-price task — the actual charge equals the estimate.
+            const actualCostUsd = price;
+            await this.governor.record(admitReq, actualCostUsd);
+            const provenance = {
+                source: "dataforseo",
+                retrievedAt: new Date().toISOString(),
+                costUsd: actualCostUsd,
+            };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // network/parse error -> abstain, NEVER throw
+        }
+    }
+    /**
+     * Keyword ideas query. Same ADR-5 preamble as `serp`; USD cost uses the
+     * documented `KEYWORDS_TASK_USD` placeholder (research §4 does not pin a
+     * keywords price — see the constant's `bober:` comment).
+     */
+    async keywords(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("serp-provider");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-serp-provider-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const admitReq = {
+            source: "dataforseo",
+            capability: "keywords",
+            scope: {},
+            estRows: q.keywords.length,
+            estCostUsd: KEYWORDS_TASK_USD,
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may a socket open. --
+        try {
+            const cred = await this.getBasicAuth();
+            const res = await this.http.request(DFS_KEYWORDS_URL, {
+                method: "POST",
+                headers: { Authorization: `Basic ${cred}`, "Content-Type": "application/json" },
+                body: JSON.stringify([{ keywords: q.keywords, location_name: q.location }]),
+            });
+            if (!res.ok) {
+                return { kind: "abstain", reason: `dataforseo-http-${res.status}` }; // 402/429/5xx -> abstain, NEVER throw
+            }
+            const rows = parseKeywords(await res.json(), q.location);
+            const actualCostUsd = KEYWORDS_TASK_USD;
+            await this.governor.record({ ...admitReq, estRows: rows.length }, actualCostUsd);
+            const provenance = {
+                source: "dataforseo",
+                retrievedAt: new Date().toISOString(),
+                costUsd: actualCostUsd,
+            };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // network/parse error -> abstain, NEVER throw
+        }
+    }
+    /**
+     * Backlinks query. Same ADR-5 preamble; USD cost is `$0.02/req` plus
+     * `$0.00003/row` — `admit()` uses the worst-case `q.limit` estimate,
+     * `record()`/`provenance.costUsd` use the ACTUAL returned row count.
+     */
+    async backlinks(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("serp-provider");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-serp-provider-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const admitReq = {
+            source: "dataforseo",
+            capability: "backlinks",
+            scope: {},
+            estRows: q.limit ?? 0,
+            estCostUsd: BACKLINKS_BASE_USD + (q.limit ?? 0) * BACKLINKS_PER_ROW_USD, // worst-case pre-emption
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may a socket open. --
+        try {
+            const cred = await this.getBasicAuth();
+            const res = await this.http.request(DFS_BACKLINKS_URL, {
+                method: "POST",
+                headers: { Authorization: `Basic ${cred}`, "Content-Type": "application/json" },
+                body: JSON.stringify([{ target: q.target, limit: q.limit }]),
+            });
+            if (!res.ok) {
+                return { kind: "abstain", reason: `dataforseo-http-${res.status}` }; // 402/429/5xx -> abstain, NEVER throw
+            }
+            const rows = parseBacklinks(await res.json());
+            // Actual charge is recomputed from the rows actually returned, not the worst-case estimate.
+            const actualCostUsd = BACKLINKS_BASE_USD + rows.length * BACKLINKS_PER_ROW_USD;
+            await this.governor.record({ ...admitReq, estRows: rows.length }, actualCostUsd);
+            const provenance = {
+                source: "dataforseo",
+                retrievedAt: new Date().toISOString(),
+                costUsd: actualCostUsd,
+            };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // network/parse error -> abstain, NEVER throw
+        }
+    }
+    // -- Capabilities DataForSEO does not serve; GscAdapter covers these --
+    async searchAnalytics(_q) {
+        return { kind: "disabled" };
+    }
+    async urlInspection(_q) {
+        return { kind: "disabled" };
+    }
+    // -- DataForSEO does not serve ai-visibility/link-graph either (spec-20260717-seo-improver-builder, Sprint 1) --
+    async aiVisibility(_q) {
+        return { kind: "disabled" };
+    }
+    async linkGraph(_q) {
+        return { kind: "disabled" };
+    }
+}
+//# sourceMappingURL=dataforseo-adapter.js.map

package/dist/seo/sources/dataforseo-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataforseo-adapter.js","sourceRoot":"","sources":["../../../src/seo/sources/dataforseo-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAqBxD,8EAA8E;AAE9E,MAAM,QAAQ,GAAG,+BAA+B,CAAC;AACjD,MAAM,YAAY,GAAG,GAAG,QAAQ,oCAAoC,CAAC;AACrE,MAAM,gBAAgB,GAAG,GAAG,QAAQ,4CAA4C,CAAC;AACjF,MAAM,iBAAiB,GAAG,GAAG,QAAQ,2BAA2B,CAAC;AAEjE,mGAAmG;AACnG,MAAM,cAAc,GAAuD;IACzE,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;IAChB,IAAI,EAAE,KAAK;CACZ,CAAC;AAEF,mEAAmE;AACnE,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAChC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC,8EAA8E;AAE9E,gGAAgG;AAChG,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAI,GAA+B,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,MAAM,MAAM,GAAI,KAAiC,CAAC,QAAQ,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,KAAK,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED,uFAAuF;AACvF,SAAS,SAAS,CAAC,GAAY,EAAE,OAAe,EAAE,QAAgB;IAChE,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAChD,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,IAAI,OAAO,CAAC,CAAC,eAAe,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,QAAQ;YAAE,SAAS;QACrF,MAAM,GAAG,GAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;QACxF,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+FAA+F;AAC/F,SAAS,aAAa,CAAC,GAAY,EAAE,QAAgB;IACnD,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAChD,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,SAAS;QAC/C,MAAM,GAAG,GAAe,EAAE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,CAAC,GAAG,IAA+B,CAAC;YAC1C,IAAI,OAAO,CAAC,CAAC,eAAe,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC;YAClF,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;YACrD,IAAI,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,SAAS,cAAc,CAAC,GAAY;IAClC,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAChD,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,IAAI,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;YAAE,SAAS;QACnF,MAAM,GAAG,GAAgB,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9E,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;YAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC9D,IAAI,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAiB;IAET;IACA;IAGA;IAIA;IATnB,YACmB,MAAsB,EACtB,QAA0B;IAC3C,gEAAgE;IAChE,6DAA6D;IAC5C,OAAmB,iBAAiB;IACrD,yEAAyE;IACzE,mEAAmE;IACnE,kCAAkC;IACjB,eAAsC,GAAG,EAAE,CAC1D,OAAO,CAAC,OAAO,CACb,MAAM,CAAC,IAAI,CACT,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,EAAE,CACvF,CAAC,QAAQ,CAAC,QAAQ,CAAC,CACrB;QAbc,WAAM,GAAN,MAAM,CAAgB;QACtB,aAAQ,GAAR,QAAQ,CAAkB;QAG1B,SAAI,GAAJ,IAAI,CAAgC;QAIpC,iBAAY,GAAZ,YAAY,CAK1B;IACF,CAAC;IAEJ,YAAY;QACV,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,CAAY;QACrB,yCAAyC;QACzC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;QACtE,CAAC;QAED,mEAAmE;QACnE,MAAM,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,IAAI,UAAU,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAiB;YAC7B,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,MAAM;YAClB,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,CAAC,EAAE,sEAAsE;YAClF,UAAU,EAAE,KAAK;SAClB,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtD,CAAC;QAED,oCAAoC;QACpC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;gBAChD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;aAChG,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,sCAAsC;YAC7G,CAAC;YACD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;YAEhE,sEAAsE;YACtE,MAAM,aAAa,GAAG,KAAK,CAAC;YAC5B,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;YAEpD,MAAM,UAAU,GAAmB;gBACjC,MAAM,EAAE,YAAY;gBACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACrC,OAAO,EAAE,aAAa;aACvB,CAAC;YACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,8CAA8C;QACpG,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,CAAe;QAC5B,yCAAyC;QACzC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;QACtE,CAAC;QAED,mEAAmE;QACnE,MAAM,QAAQ,GAAiB;YAC7B,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,UAAU;YACtB,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM;YAC1B,UAAU,EAAE,iBAAiB;SAC9B,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtD,CAAC;QAED,oCAAoC;QACpC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE;gBACpD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;aAC5E,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,sCAAsC;YAC7G,CAAC;YACD,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;YAEzD,MAAM,aAAa,GAAG,iBAAiB,CAAC;YACxC,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC;YAEjF,MAAM,UAAU,GAAmB;gBACjC,MAAM,EAAE,YAAY;gBACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACrC,OAAO,EAAE,aAAa;aACvB,CAAC;YACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,8CAA8C;QACpG,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,CAAgB;QAC9B,yCAAyC;QACzC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;QACtE,CAAC;QAED,mEAAmE;QACnE,MAAM,QAAQ,GAAiB;YAC7B,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,WAAW;YACvB,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;YACrB,UAAU,EAAE,kBAAkB,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,qBAAqB,EAAE,yBAAyB;SACnG,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtD,CAAC;QAED,oCAAoC;QACpC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE;gBACrD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;aAC7D,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,sCAAsC;YAC7G,CAAC;YACD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YAE9C,4FAA4F;YAC5F,MAAM,aAAa,GAAG,kBAAkB,GAAG,IAAI,CAAC,MAAM,GAAG,qBAAqB,CAAC;YAC/E,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC;YAEjF,MAAM,UAAU,GAAmB;gBACjC,MAAM,EAAE,YAAY;gBACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACrC,OAAO,EAAE,aAAa;aACvB,CAAC;YACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,8CAA8C;QACpG,CAAC;IACH,CAAC;IAED,wEAAwE;IAExE,KAAK,CAAC,eAAe,CAAC,EAAwB;QAC5C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,EAAsB;QACxC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IAED,iHAAiH;IAEjH,KAAK,CAAC,YAAY,CAAC,EAAqB;QACtC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,EAAkB;QAChC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/seo/sources/dataforseo-serp-provider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DataForSeoSerpProvider — the `SerpProvider` (`../serp-provider.js`)
+ * implementation backed by the DataForSEO SERP API
+ * (spec-20260717-seo-improver-builder, Sprint 8; ADR-10).
+ *
+ * A THIN delegate over the existing, already egress+governor-gated
+ * `DataForSeoAdapter.serp` path (`./dataforseo-adapter.ts:190-238`) — this
+ * class does no HTTP, no parsing, no egress check, and no USD booking of
+ * its own. `adapter.serp` already:
+ *   1. asserts the `"serp-provider"` egress axis (`dataforseo-adapter.ts:193`),
+ *   2. gates `governor.admit()` before opening a socket,
+ *   3. books the actual USD via `governor.record(admitReq, 0.0006)`
+ *      (`dataforseo-adapter.ts:227`) ONLY after a successful round-trip.
+ * Calling it a SECOND time here would double-charge and break the
+ * byte-identical-when-off / byte-identical-to-today invariant — so this
+ * wrapper's `serp()` body is a single delegating call, nothing else.
+ */
+import type { DataOutcome } from "../types.js";
+import type { SerpRow } from "../data-source.js";
+import type { SerpProvider } from "../serp-provider.js";
+import type { DataForSeoAdapter } from "./dataforseo-adapter.js";
+export declare class DataForSeoSerpProvider implements SerpProvider {
+    private readonly adapter;
+    readonly name: "dataforseo";
+    readonly estCostUsdPerResult = 0.0006;
+    constructor(adapter: DataForSeoAdapter);
+    /** Delegates to the existing, already egress+governor-gated `adapter.serp` path — output byte-identical to today. */
+    serp(keyword: string, location: string): Promise<DataOutcome<SerpRow[]>>;
+}
+//# sourceMappingURL=dataforseo-serp-provider.d.ts.map

package/dist/seo/sources/dataforseo-serp-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataforseo-serp-provider.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/dataforseo-serp-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAUjE,qBAAa,sBAAuB,YAAW,YAAY;IAI7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,QAAQ,CAAC,mBAAmB,UAA4B;gBAE3B,OAAO,EAAE,iBAAiB;IAEvD,qHAAqH;IACrH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;CAGzE"}

package/dist/seo/sources/dataforseo-serp-provider.js

@@ -0,0 +1,20 @@
+/**
+ * Documented standard-SERP price (mirrors the `SERP_PRICE_USD.standard`
+ * constant, `dataforseo-adapter.ts:67-71` — NOT exported from that module,
+ * restated here as metadata only; the real charge is computed and booked
+ * inside the wrapped adapter, not by this constant).
+ */
+const DATAFORSEO_SERP_COST_USD = 0.0006;
+export class DataForSeoSerpProvider {
+    adapter;
+    name = "dataforseo";
+    estCostUsdPerResult = DATAFORSEO_SERP_COST_USD;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /** Delegates to the existing, already egress+governor-gated `adapter.serp` path — output byte-identical to today. */
+    serp(keyword, location) {
+        return this.adapter.serp({ keyword, location });
+    }
+}
+//# sourceMappingURL=dataforseo-serp-provider.js.map

package/dist/seo/sources/dataforseo-serp-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataforseo-serp-provider.js","sourceRoot":"","sources":["../../../src/seo/sources/dataforseo-serp-provider.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAExC,MAAM,OAAO,sBAAsB;IAIJ;IAHpB,IAAI,GAAG,YAAqB,CAAC;IAC7B,mBAAmB,GAAG,wBAAwB,CAAC;IAExD,YAA6B,OAA0B;QAA1B,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IAE3D,qHAAqH;IACrH,IAAI,CAAC,OAAe,EAAE,QAAgB;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/seo/sources/engine-scrape-parser-chatgpt.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ChatgptUiScrapeParser — PURE, network-free transform from raw scraped
+ * ChatGPT-UI answer-page markdown into a normalized `ParsedAnswer` (in-house-
+ * ai-visibility, Sprint 10; arch-20260717-in-house-oss-ai-visibility-
+ * architecture.md:139-141,250-251,281).
+ *
+ * This module has ZERO dependencies on damcrawler, egress, or any network
+ * primitive — it is a synchronous, deterministic markdown -> data mapping,
+ * mirroring `DeterministicMentionCitationExtractor`'s "PURE, synchronous,
+ * network-free transform" contract (`./mention-citation-extractor.ts:8`).
+ * `ScrapeArmEngineProvider` is the ONLY caller, and it invokes `.parse()`
+ * strictly AFTER the raw scraped markdown has already passed through the
+ * fail-closed `ContentSanitizer` at the network->in-process boundary
+ * (sc-10-2, Sprint-9 F1 lesson) — this parser never sees unsanitized text
+ * in production, but it does not (and must not) assume that; it never
+ * throws regardless of input.
+ *
+ * ChatGPT's exported/rendered answer-page markdown is NOT a stable, fully
+ * documented format — this parser degrades gracefully on drift: "parser
+ * drift => empty answerText => downstream observation counts as not-
+ * mentioned" (arch:281) is the explicit contract, not a bug to fix later.
+ * Empty/whitespace/malformed input always yields `{ answerText: "",
+ * citations: [] }` — this class NEVER fabricates a positive observation.
+ *
+ * Extraction strategy (deterministic, markdown-shape heuristics only):
+ *   1. `answerText` — the raw markdown with any trailing "Sources"/
+ *      "Citations" section (and any markdown link syntax) stripped, then
+ *      trimmed. A ChatGPT-UI answer page renders the assistant's prose
+ *      followed by an optional sources block; this parser treats everything
+ *      before that block (or the whole trimmed text, when no block is
+ *      found) as the answer.
+ *   2. `citations` — markdown links (`[title](url)`) found ANYWHERE in the
+ *      raw markdown, deduplicated by URL, mapped to `GroundedCitation`
+ *      `{ url, title }`. A bare autolink (`<https://...>`) or a bare URL is
+ *      also captured with its url as its own title (no better title is
+ *      derivable). Malformed/empty href or link text never crashes the
+ *      parser — such candidates are simply skipped.
+ */
+import type { GroundedCitation } from "../../providers/grounded-search.js";
+/** Raw scraped page handed to the parser — already sanitized by the caller (sc-10-2). */
+export type RawScrape = {
+    url: string;
+    markdown: string;
+    links?: string[];
+};
+/** Normalized parse result. `citations` reuses the locked `GroundedCitation` shape. */
+export type ParsedAnswer = {
+    answerText: string;
+    citations: GroundedCitation[];
+};
+export interface EngineScrapeParser {
+    parse(raw: RawScrape): ParsedAnswer;
+}
+/**
+ * `EngineScrapeParser` for the `"chatgpt-ui"` scrape engine. PURE,
+ * synchronous, dependency-free; never throws; empty/malformed input yields
+ * `{ answerText: "", citations: [] }`.
+ */
+export declare class ChatgptUiScrapeParser implements EngineScrapeParser {
+    parse(raw: RawScrape): ParsedAnswer;
+}
+//# sourceMappingURL=engine-scrape-parser-chatgpt.d.ts.map

package/dist/seo/sources/engine-scrape-parser-chatgpt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-scrape-parser-chatgpt.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/engine-scrape-parser-chatgpt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE5E,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY,CAAC;CACrC;AAiED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY;CASpC"}

package/dist/seo/sources/engine-scrape-parser-chatgpt.js

@@ -0,0 +1,72 @@
+/** Heading text (case-insensitive) that marks the start of a trailing sources/citations block. */
+const SOURCES_HEADING = /^#{0,6}\s*(sources|citations|references)\s*:?\s*$/im;
+/** Markdown inline link: `[title](url)`. Title may be empty; url must be non-whitespace. */
+const MARKDOWN_LINK = /\[([^\]]*)\]\(\s*(\S+?)\s*(?:"[^"]*")?\s*\)/g;
+/** Bare autolink: `<https://example.com>`. */
+const AUTOLINK = /<((?:https?:\/\/)[^\s<>]+)>/g;
+/** Bare URL not already captured by the two patterns above (best-effort fallback). */
+const BARE_URL = /(?<![("<])\bhttps?:\/\/[^\s)\]"'<>]+/g;
+/** `try { new URL(...) } catch { false }` — never throws; rejects a candidate url as unusable. */
+function isUsableUrl(candidate) {
+    try {
+        new URL(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Strips a trailing "Sources"/"Citations"/"References" heading and
+ * everything after it, returning only the prose above it. When no such
+ * heading is found, returns the input unchanged (the whole text is prose).
+ */
+function stripTrailingSourcesBlock(markdown) {
+    const match = SOURCES_HEADING.exec(markdown);
+    if (!match)
+        return markdown;
+    return markdown.slice(0, match.index);
+}
+/**
+ * Extracts every distinct citation link from the raw markdown — markdown
+ * links first, then autolinks, then bare URLs — deduplicated by URL
+ * (first-seen title wins). Never throws on malformed link syntax.
+ */
+function extractCitations(markdown) {
+    const seen = new Set();
+    const citations = [];
+    const addCandidate = (url, title) => {
+        const trimmedUrl = url.trim();
+        if (!trimmedUrl || !isUsableUrl(trimmedUrl) || seen.has(trimmedUrl))
+            return;
+        seen.add(trimmedUrl);
+        const trimmedTitle = title.trim();
+        citations.push({ url: trimmedUrl, title: trimmedTitle.length > 0 ? trimmedTitle : trimmedUrl });
+    };
+    for (const m of markdown.matchAll(MARKDOWN_LINK)) {
+        addCandidate(m[2] ?? "", m[1] ?? "");
+    }
+    for (const m of markdown.matchAll(AUTOLINK)) {
+        addCandidate(m[1] ?? "", m[1] ?? "");
+    }
+    for (const m of markdown.matchAll(BARE_URL)) {
+        addCandidate(m[0] ?? "", m[0] ?? "");
+    }
+    return citations;
+}
+/**
+ * `EngineScrapeParser` for the `"chatgpt-ui"` scrape engine. PURE,
+ * synchronous, dependency-free; never throws; empty/malformed input yields
+ * `{ answerText: "", citations: [] }`.
+ */
+export class ChatgptUiScrapeParser {
+    parse(raw) {
+        const markdown = typeof raw?.markdown === "string" ? raw.markdown : "";
+        if (markdown.trim().length === 0)
+            return { answerText: "", citations: [] };
+        const answerText = stripTrailingSourcesBlock(markdown).trim();
+        const citations = extractCitations(markdown);
+        return { answerText, citations };
+    }
+}
+//# sourceMappingURL=engine-scrape-parser-chatgpt.js.map

package/dist/seo/sources/engine-scrape-parser-chatgpt.js.map

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

package/dist/seo/sources/engine-scrape-parser-perplexity.d.ts

@@ -0,0 +1,10 @@
+import type { EngineScrapeParser, RawScrape, ParsedAnswer } from "./engine-scrape-parser-chatgpt.js";
+/**
+ * `EngineScrapeParser` for the `"perplexity-ui"` scrape engine. PURE,
+ * synchronous, dependency-free; never throws; empty/malformed input yields
+ * `{ answerText: "", citations: [] }`.
+ */
+export declare class PerplexityUiScrapeParser implements EngineScrapeParser {
+    parse(raw: RawScrape): ParsedAnswer;
+}
+//# sourceMappingURL=engine-scrape-parser-perplexity.d.ts.map

package/dist/seo/sources/engine-scrape-parser-perplexity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-scrape-parser-perplexity.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/engine-scrape-parser-perplexity.ts"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAiErG;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB;IACjE,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY;CASpC"}

package/dist/seo/sources/engine-scrape-parser-perplexity.js

@@ -0,0 +1,72 @@
+/** Heading text (case-insensitive) that marks the start of a trailing sources/citations block. */
+const SOURCES_HEADING = /^#{0,6}\s*(sources|citations|references)\s*:?\s*$/im;
+/** Markdown inline link: `[title](url)`. Title may be empty; url must be non-whitespace. */
+const MARKDOWN_LINK = /\[([^\]]*)\]\(\s*(\S+?)\s*(?:"[^"]*")?\s*\)/g;
+/** Bare autolink: `<https://example.com>`. */
+const AUTOLINK = /<((?:https?:\/\/)[^\s<>]+)>/g;
+/** Bare URL not already captured by the two patterns above (best-effort fallback). */
+const BARE_URL = /(?<![("<])\bhttps?:\/\/[^\s)\]"'<>]+/g;
+/** `try { new URL(...) } catch { false }` — never throws; rejects a candidate url as unusable. */
+function isUsableUrl(candidate) {
+    try {
+        new URL(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Strips a trailing "Sources"/"Citations"/"References" heading and
+ * everything after it, returning only the prose above it. When no such
+ * heading is found, returns the input unchanged (the whole text is prose).
+ */
+function stripTrailingSourcesBlock(markdown) {
+    const match = SOURCES_HEADING.exec(markdown);
+    if (!match)
+        return markdown;
+    return markdown.slice(0, match.index);
+}
+/**
+ * Extracts every distinct citation link from the raw markdown — markdown
+ * links first, then autolinks, then bare URLs — deduplicated by URL
+ * (first-seen title wins). Never throws on malformed link syntax.
+ */
+function extractCitations(markdown) {
+    const seen = new Set();
+    const citations = [];
+    const addCandidate = (url, title) => {
+        const trimmedUrl = url.trim();
+        if (!trimmedUrl || !isUsableUrl(trimmedUrl) || seen.has(trimmedUrl))
+            return;
+        seen.add(trimmedUrl);
+        const trimmedTitle = title.trim();
+        citations.push({ url: trimmedUrl, title: trimmedTitle.length > 0 ? trimmedTitle : trimmedUrl });
+    };
+    for (const m of markdown.matchAll(MARKDOWN_LINK)) {
+        addCandidate(m[2] ?? "", m[1] ?? "");
+    }
+    for (const m of markdown.matchAll(AUTOLINK)) {
+        addCandidate(m[1] ?? "", m[1] ?? "");
+    }
+    for (const m of markdown.matchAll(BARE_URL)) {
+        addCandidate(m[0] ?? "", m[0] ?? "");
+    }
+    return citations;
+}
+/**
+ * `EngineScrapeParser` for the `"perplexity-ui"` scrape engine. PURE,
+ * synchronous, dependency-free; never throws; empty/malformed input yields
+ * `{ answerText: "", citations: [] }`.
+ */
+export class PerplexityUiScrapeParser {
+    parse(raw) {
+        const markdown = typeof raw?.markdown === "string" ? raw.markdown : "";
+        if (markdown.trim().length === 0)
+            return { answerText: "", citations: [] };
+        const answerText = stripTrailingSourcesBlock(markdown).trim();
+        const citations = extractCitations(markdown);
+        return { answerText, citations };
+    }
+}
+//# sourceMappingURL=engine-scrape-parser-perplexity.js.map

package/dist/seo/sources/engine-scrape-parser-perplexity.js.map

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