@houtini/seo-audit-console 0.2.0

package/dist/core/GscSync.d.ts

@@ -0,0 +1,20 @@
+import { GscClient } from './GscClient.js';
+import type { FetchOptions } from './types.js';
+export declare const FULL_DIMENSIONS: string[];
+export interface SyncResult {
+    siteUrl: string;
+    rowsFetched: number;
+    startDate: string;
+    endDate: string;
+}
+/**
+ * Fetch GSC search analytics into a property's SQLite DB, computing the
+ * normalised `page_key` on write so it joins to crawl data later.
+ */
+export declare class GscSync {
+    private readonly gsc;
+    private readonly dataDir;
+    constructor(gsc: GscClient, dataDir: string);
+    run(siteUrl: string, options: FetchOptions, update: (p: Record<string, unknown>) => void, signal: AbortSignal): Promise<SyncResult>;
+}
+//# sourceMappingURL=GscSync.d.ts.map

package/dist/core/GscSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GscSync.d.ts","sourceRoot":"","sources":["../../src/core/GscSync.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,YAAY,CAAC;AAM1D,eAAO,MAAM,eAAe,UAAiD,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAa,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAxC,GAAG,EAAE,SAAS,EAAmB,OAAO,EAAE,MAAM;IAEvE,GAAG,CACP,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5C,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,CAAC;CA8GvB"}

package/dist/core/GscSync.js

@@ -0,0 +1,133 @@
+import { AuditDatabase } from './AuditDatabase.js';
+import { dbPathFor } from './paths.js';
+import { urlKey, hostFormForProperty } from './url-key.js';
+// Lean default: date×query×page is everything the audit + merged checks need, without
+// the device×country multiplication that explodes row counts on large sites. Pass
+// FULL_DIMENSIONS (segments) to also populate the device/country breakdowns.
+const LITE_DIMENSIONS = ['date', 'query', 'page'];
+export const FULL_DIMENSIONS = ['date', 'query', 'page', 'device', 'country'];
+/**
+ * Fetch GSC search analytics into a property's SQLite DB, computing the
+ * normalised `page_key` on write so it joins to crawl data later.
+ */
+export class GscSync {
+    gsc;
+    dataDir;
+    constructor(gsc, dataDir) {
+        this.gsc = gsc;
+        this.dataDir = dataDir;
+    }
+    async run(siteUrl, options, update, signal) {
+        const db = new AuditDatabase(dbPathFor(this.dataDir, siteUrl));
+        try {
+            const hostForm = hostFormForProperty(siteUrl);
+            db.upsertProperty(siteUrl, hostForm ?? 'asis');
+            const insert = db.db.prepare(`INSERT INTO search_analytics
+           (date, query, page, page_key, device, country, search_type, clicks, impressions, ctr, position)
+         VALUES (@date, @query, @page, @page_key, @device, @country, @search_type, @clicks, @impressions, @ctr, @position)
+         ON CONFLICT(date, query, page, device, country) DO UPDATE SET
+           clicks = excluded.clicks, impressions = excluded.impressions, search_type = excluded.search_type,
+           ctr = excluded.ctr, position = excluded.position, page_key = excluded.page_key`);
+            const insertMany = db.db.transaction((records) => {
+                for (const r of records)
+                    insert.run(r);
+            });
+            let total = 0;
+            let options2 = { ...options, dimensions: options.dimensions ?? LITE_DIMENSIONS };
+            let dims = options2.dimensions;
+            // Summary/totals SUM across one grouping. Mixing lite (device='') with segmented
+            // (device='DESKTOP'…) rows would double-count, so the table holds ONE grouping shape.
+            const cnt = (sql) => db.db.prepare(sql).get().n;
+            const hasLite = cnt(`SELECT COUNT(*) n FROM search_analytics WHERE device = ''`) > 0;
+            const hasSegmented = cnt(`SELECT COUNT(*) n FROM search_analytics WHERE device <> ''`) > 0;
+            // PRESERVE existing history: a routine (default/lite) sync over segmented history must NOT
+            // wipe it — keep segmenting instead, so a short window sync never destroys months of data.
+            if (!dims.includes('device') && hasSegmented && !hasLite) {
+                options2 = { ...options2, dimensions: FULL_DIMENSIONS };
+                dims = options2.dimensions;
+            }
+            const wantsSegments = dims.includes('device');
+            // Only wipe on a genuine, unavoidable shape conflict (e.g. an explicit lite→segmented
+            // upgrade, or a pre-existing mixed table) — never on the routine preserve path above.
+            // The wipe is DEFERRED into the same transaction as the first fetched batch: if the
+            // API call fails or the job is aborted before any rows arrive, months of history are
+            // NOT destroyed and replaced by nothing.
+            let mustWipe = (wantsSegments && hasLite) || (!wantsSegments && hasSegmented);
+            // Search-type guard (mirrors the lite/segmented shape-guard): the unique index
+            // (date,query,page,device,country) does NOT include search_type — rebuilding it on existing
+            // rows would rewrite months of history — so the table holds ONE search type at a time.
+            // Syncing a different type (e.g. discover over web history) would silently mix/overwrite
+            // rows; treat it as a shape conflict instead, and let the wipe ride the first batch's
+            // transaction exactly like the lite/segmented wipe (a failed fetch destroys nothing).
+            const wantType = options.searchType ?? 'web';
+            const storedTypes = db.db
+                .prepare(`SELECT DISTINCT COALESCE(search_type, 'web') t FROM search_analytics`)
+                .all().map(r => r.t);
+            if (storedTypes.length && (storedTypes.length > 1 || storedTypes[0] !== wantType))
+                mustWipe = true;
+            const wipeAndInsert = db.db.transaction((records) => {
+                db.db.exec('DELETE FROM search_analytics');
+                for (const r of records)
+                    insert.run(r);
+            });
+            // ── Incremental resume ─────────────────────────────────────────────────────────────────
+            // The first sync pulls the requested window; every sync after that only fetches from the
+            // last stored date minus a lag buffer (GSC restates the most recent ~3 days), instead of
+            // re-pulling the whole window. Turns a 30-minute, 1.8M-row refresh into a seconds-long delta.
+            // Runs AFTER the mode-guard: if the table was just wiped (shape conflict) MAX(date) is null →
+            // full window. `fullResync` forces the full window. Only ever NARROWS the window (never widens
+            // past the requested start), and resumes from wherever the data left off (covers any gap).
+            const LAG_DAYS = 3;
+            if (!options.fullResync && !mustWipe) { // a pending wipe means the stored MAX(date) is the OLD shape's — pull the full window
+                const mx = db.db.prepare('SELECT MAX(date) d FROM search_analytics').get().d;
+                if (mx) {
+                    const resume = new Date(Date.parse(mx) - LAG_DAYS * 86400000).toISOString().slice(0, 10);
+                    // Already synced past the requested window (e.g. a historical/comparison pull whose
+                    // endDate predates the stored data): no-op instead of calling GSC with start > end.
+                    if (resume > options2.endDate) {
+                        db.db.prepare(`UPDATE property_meta SET last_synced_at = datetime('now') WHERE site_url = ?`).run(siteUrl);
+                        return { siteUrl, rowsFetched: 0, startDate: options2.startDate, endDate: options2.endDate };
+                    }
+                    if (resume > options2.startDate) {
+                        options2 = { ...options2, startDate: resume };
+                    }
+                }
+            }
+            await this.gsc.fetchSearchAnalytics(siteUrl, options2, signal, ({ rows }) => {
+                const records = rows.map((row) => {
+                    const keys = row.keys ?? [];
+                    const rec = {};
+                    dims.forEach((d, i) => (rec[d] = keys[i] ?? null));
+                    const page = rec.page;
+                    return {
+                        date: rec.date,
+                        query: rec.query ?? null,
+                        page: page ?? null,
+                        page_key: page ? urlKey(page, { hostForm }) : null,
+                        device: rec.device ?? '', // '' = not segmented (lite); keeps the unique index dedup working
+                        country: rec.country ?? '',
+                        search_type: wantType,
+                        clicks: row.clicks,
+                        impressions: row.impressions,
+                        ctr: row.ctr,
+                        position: row.position,
+                    };
+                });
+                if (mustWipe) {
+                    wipeAndInsert(records);
+                    mustWipe = false;
+                }
+                else
+                    insertMany(records);
+                total += records.length;
+                update({ siteUrl, rowsFetched: total });
+            });
+            db.db.prepare(`UPDATE property_meta SET last_synced_at = datetime('now') WHERE site_url = ?`).run(siteUrl);
+            return { siteUrl, rowsFetched: total, startDate: options2.startDate, endDate: options2.endDate };
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+//# sourceMappingURL=GscSync.js.map

package/dist/core/GscSync.js.map

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

package/dist/core/JobManager.d.ts

@@ -0,0 +1,30 @@
+import type { JobState } from './types.js';
+export interface Job {
+    id: string;
+    type: string;
+    state: JobState;
+    startedAt: string;
+    updatedAt: string;
+    progress: Record<string, unknown>;
+    error?: string;
+    result?: unknown;
+}
+type JobFn = (update: (p: Record<string, unknown>) => void, signal: AbortSignal) => Promise<unknown>;
+/**
+ * Generic async-job registry — the return-jobId-then-poll pattern that keeps
+ * long operations (GSC sync, crawl) off the synchronous MCP tool-call path so
+ * they never hit the client timeout. Mirrors better-search-console's sync model.
+ */
+export declare class JobManager {
+    private jobs;
+    private controllers;
+    private readonly maxRetained;
+    constructor(maxRetained?: number);
+    start(type: string, fn: JobFn): string;
+    get(id: string): Job | undefined;
+    list(): Job[];
+    cancel(id: string): boolean;
+    private prune;
+}
+export {};
+//# sourceMappingURL=JobManager.d.ts.map

package/dist/core/JobManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobManager.d.ts","sourceRoot":"","sources":["../../src/core/JobManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAErG;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,SAAK;IAI5B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM;IAkCtC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAIhC,IAAI,IAAI,GAAG,EAAE;IAIb,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAO3B,OAAO,CAAC,KAAK;CASd"}

package/dist/core/JobManager.js

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Generic async-job registry — the return-jobId-then-poll pattern that keeps
+ * long operations (GSC sync, crawl) off the synchronous MCP tool-call path so
+ * they never hit the client timeout. Mirrors better-search-console's sync model.
+ */
+export class JobManager {
+    jobs = new Map();
+    controllers = new Map();
+    maxRetained;
+    constructor(maxRetained = 50) {
+        this.maxRetained = maxRetained;
+    }
+    start(type, fn) {
+        const id = randomUUID().slice(0, 8);
+        const now = new Date().toISOString();
+        const job = { id, type, state: 'running', startedAt: now, updatedAt: now, progress: {} };
+        const controller = new AbortController();
+        this.jobs.set(id, job);
+        this.controllers.set(id, controller);
+        this.prune();
+        const update = (p) => {
+            job.progress = { ...job.progress, ...p };
+            job.updatedAt = new Date().toISOString();
+        };
+        // Run detached — do NOT await. The tool returns the id immediately.
+        // Promise.resolve().then(...) so a synchronous throw in fn becomes a rejection
+        // (caught below) rather than an uncaught exception that crashes the MCP process.
+        Promise.resolve()
+            .then(() => fn(update, controller.signal))
+            .then(result => {
+            job.result = result;
+            job.state = controller.signal.aborted ? 'cancelled' : 'completed';
+            job.updatedAt = new Date().toISOString();
+        })
+            .catch((err) => {
+            job.state = 'failed';
+            job.error = err instanceof Error ? err.message : String(err);
+            job.updatedAt = new Date().toISOString();
+        })
+            .finally(() => this.controllers.delete(id));
+        return id;
+    }
+    get(id) {
+        return this.jobs.get(id);
+    }
+    list() {
+        return [...this.jobs.values()].sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+    }
+    cancel(id) {
+        const c = this.controllers.get(id);
+        if (!c)
+            return false;
+        c.abort();
+        return true;
+    }
+    prune() {
+        if (this.jobs.size <= this.maxRetained)
+            return;
+        const done = [...this.jobs.values()]
+            .filter(j => j.state === 'completed' || j.state === 'failed' || j.state === 'cancelled')
+            .sort((a, b) => (a.updatedAt < b.updatedAt ? -1 : 1));
+        while (this.jobs.size > this.maxRetained && done.length) {
+            this.jobs.delete(done.shift().id);
+        }
+    }
+}
+//# sourceMappingURL=JobManager.js.map

package/dist/core/JobManager.js.map

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

package/dist/core/RankTracker.d.ts

@@ -0,0 +1,25 @@
+import { DataForSeoClient } from './DataForSeoClient.js';
+export interface RankTrackResult {
+    siteUrl: string;
+    target: string;
+    periods: number;
+    range: {
+        start: string;
+        end: string;
+    } | null;
+    cached: boolean;
+    cost: number;
+}
+/**
+ * Ingests the DataForSEO over-time sequence (monthly rank distribution + ETV) into
+ * rank_history, so charts have a real time axis to reconcile against GSC's daily data.
+ */
+export declare class RankTracker {
+    private readonly dfs;
+    private readonly dataDir;
+    constructor(dfs: DataForSeoClient, dataDir: string);
+    run(siteUrl: string, opts: {
+        location?: string | number;
+    }, update: (p: Record<string, unknown>) => void, _signal: AbortSignal): Promise<RankTrackResult>;
+}
+//# sourceMappingURL=RankTracker.d.ts.map

package/dist/core/RankTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RankTracker.d.ts","sourceRoot":"","sources":["../../src/core/RankTracker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAIzD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAQD;;;GAGG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAoB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAA/C,GAAG,EAAE,gBAAgB,EAAmB,OAAO,EAAE,MAAM;IAE9E,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EACpC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5C,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;CA2D5B"}

package/dist/core/RankTracker.js

@@ -0,0 +1,78 @@
+import { AuditDatabase } from './AuditDatabase.js';
+import { dbPathFor } from './paths.js';
+import { hostFormForProperty } from './url-key.js';
+function domainFromProperty(siteUrl) {
+    return siteUrl.replace(/^sc-domain:/, '').replace(/^https?:\/\//, '').replace(/\/+$/, '');
+}
+const n = (v) => Number(v) || 0;
+/**
+ * Ingests the DataForSEO over-time sequence (monthly rank distribution + ETV) into
+ * rank_history, so charts have a real time axis to reconcile against GSC's daily data.
+ */
+export class RankTracker {
+    dfs;
+    dataDir;
+    constructor(dfs, dataDir) {
+        this.dfs = dfs;
+        this.dataDir = dataDir;
+    }
+    async run(siteUrl, opts, update, _signal) {
+        const target = domainFromProperty(siteUrl);
+        const db = new AuditDatabase(dbPathFor(this.dataDir, siteUrl));
+        try {
+            db.upsertProperty(siteUrl, hostFormForProperty(siteUrl) ?? 'asis');
+            if (opts.location !== undefined)
+                db.setDfsLocation(siteUrl, opts.location);
+            const location = opts.location ?? db.getDfsLocation(siteUrl);
+            const r = await this.dfs.historicalRankOverview(target, location);
+            const items = r.tasks[0]?.result?.[0]?.items ?? [];
+            const upsert = db.db.prepare(`INSERT INTO rank_history (period, pos_1_3, pos_4_10, pos_11_20, pos_21_100, etv, keyword_count,
+           is_new, is_up, is_down, is_lost, estimated_paid_traffic_cost, source, fetched_at)
+         VALUES (@period,@pos_1_3,@pos_4_10,@pos_11_20,@pos_21_100,@etv,@keyword_count,
+           @is_new,@is_up,@is_down,@is_lost,@estimated_paid_traffic_cost,'dataforseo:historical_rank_overview',datetime('now'))
+         ON CONFLICT(period) DO UPDATE SET pos_1_3=excluded.pos_1_3, pos_4_10=excluded.pos_4_10,
+           pos_11_20=excluded.pos_11_20, pos_21_100=excluded.pos_21_100, etv=excluded.etv,
+           keyword_count=excluded.keyword_count, is_new=excluded.is_new, is_up=excluded.is_up,
+           is_down=excluded.is_down, is_lost=excluded.is_lost,
+           estimated_paid_traffic_cost=excluded.estimated_paid_traffic_cost, fetched_at=datetime('now')`);
+            const rows = items.filter(it => Number.isInteger(it?.year) && Number.isInteger(it?.month)).map(it => {
+                const o = it.metrics?.organic ?? {};
+                // Guard year/month — a malformed item would upsert an "undefined-NaN" period row
+                // that then poisons the dashboard's rank-history axis and date reconciliation.
+                const period = `${it.year}-${String(it.month).padStart(2, '0')}`;
+                const pos_1_3 = n(o.pos_1) + n(o.pos_2_3);
+                const pos_4_10 = n(o.pos_4_10);
+                const pos_11_20 = n(o.pos_11_20);
+                const pos_21_100 = n(o.pos_21_30) + n(o.pos_31_40) + n(o.pos_41_50) + n(o.pos_51_60) +
+                    n(o.pos_61_70) + n(o.pos_71_80) + n(o.pos_81_90) + n(o.pos_91_100);
+                // DataForSEO names the total field `count`; fall back to summing the buckets
+                // so keyword_count isn't a silent 0 if the field name differs.
+                return {
+                    period, pos_1_3, pos_4_10, pos_11_20, pos_21_100,
+                    etv: n(o.etv),
+                    keyword_count: n(o.count) || (pos_1_3 + pos_4_10 + pos_11_20 + pos_21_100),
+                    // Keyword-movement counts + paid-value equivalent — same response, previously dropped.
+                    is_new: n(o.is_new), is_up: n(o.is_up), is_down: n(o.is_down), is_lost: n(o.is_lost),
+                    estimated_paid_traffic_cost: o.estimated_paid_traffic_cost != null ? n(o.estimated_paid_traffic_cost) : null,
+                };
+            });
+            const tx = db.db.transaction((rs) => { for (const row of rs)
+                upsert.run(row); });
+            tx(rows);
+            const periods = rows.map(r2 => r2.period).sort();
+            update({ siteUrl, periods: periods.length });
+            return {
+                siteUrl,
+                target,
+                periods: periods.length,
+                range: periods.length ? { start: periods[0], end: periods[periods.length - 1] } : null,
+                cached: r.cached,
+                cost: r.cost,
+            };
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+//# sourceMappingURL=RankTracker.js.map

package/dist/core/RankTracker.js.map

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

package/dist/core/Refresh.d.ts

@@ -0,0 +1,32 @@
+import { GscSync } from './GscSync.js';
+import { Crawler } from './Crawler.js';
+import { UrlInspector } from './UrlInspector.js';
+import { RankTracker } from './RankTracker.js';
+export interface RefreshOptions {
+    gsc?: boolean;
+    crawl?: boolean;
+    inspect?: boolean;
+    ranks?: boolean;
+    segments?: boolean;
+    full?: boolean;
+    location?: string | number;
+    startDate?: string;
+    endDate?: string;
+    maxPages?: number;
+    inspectLimit?: number;
+}
+/**
+ * Orchestrates a full property refresh — GSC sync → crawl → URL inspection — as a
+ * single job. Each phase is skippable, so the same entry point serves both
+ * "sync everything" and "just update X". Inspection runs last so it can target
+ * top pages by freshly-synced clicks (else crawl in-degree).
+ */
+export declare class Refresh {
+    private readonly sync;
+    private readonly crawler;
+    private readonly inspector;
+    private readonly rankTracker;
+    constructor(sync: GscSync | null, crawler: Crawler, inspector: UrlInspector | null, rankTracker: RankTracker | null);
+    run(siteUrl: string, opts: RefreshOptions, update: (p: Record<string, unknown>) => void, signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=Refresh.d.ts.map

package/dist/core/Refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Refresh.d.ts","sourceRoot":"","sources":["../../src/core/Refresh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAmB,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAHX,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,YAAY,GAAG,IAAI,EAC9B,WAAW,EAAE,WAAW,GAAG,IAAI;IAG5C,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5C,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAqDpC"}

package/dist/core/Refresh.js

@@ -0,0 +1,73 @@
+import { FULL_DIMENSIONS } from './GscSync.js';
+const isoDaysAgo = (d) => new Date(Date.now() - d * 86400000).toISOString().slice(0, 10);
+/**
+ * Orchestrates a full property refresh — GSC sync → crawl → URL inspection — as a
+ * single job. Each phase is skippable, so the same entry point serves both
+ * "sync everything" and "just update X". Inspection runs last so it can target
+ * top pages by freshly-synced clicks (else crawl in-degree).
+ */
+export class Refresh {
+    sync;
+    crawler;
+    inspector;
+    rankTracker;
+    constructor(sync, crawler, inspector, rankTracker) {
+        this.sync = sync;
+        this.crawler = crawler;
+        this.inspector = inspector;
+        this.rankTracker = rankTracker;
+    }
+    async run(siteUrl, opts, update, signal) {
+        const out = { siteUrl, phases: [] };
+        const phases = out.phases;
+        if (opts.gsc !== false) {
+            if (!this.sync) {
+                out.gscSkipped = 'no GSC credentials';
+            }
+            else {
+                update({ phase: 'gsc' });
+                phases.push('gsc');
+                out.gsc = await this.sync.run(siteUrl, {
+                    startDate: opts.startDate ?? isoDaysAgo(90),
+                    endDate: opts.endDate ?? isoDaysAgo(0),
+                    ...(opts.segments ? { dimensions: FULL_DIMENSIONS } : {}),
+                    ...(opts.full ? { fullResync: true } : {}),
+                }, p => update({ phase: 'gsc', ...p }), signal);
+            }
+        }
+        if (signal.aborted)
+            return out;
+        if (opts.crawl !== false) {
+            update({ phase: 'crawl' });
+            phases.push('crawl');
+            out.crawl = await this.crawler.run(siteUrl, { maxPages: opts.maxPages }, p => update({ phase: 'crawl', ...p }), signal);
+        }
+        if (signal.aborted)
+            return out;
+        if (opts.inspect !== false) {
+            if (!this.inspector) {
+                out.inspectSkipped = 'no GSC credentials';
+            }
+            else {
+                update({ phase: 'inspect' });
+                phases.push('inspect');
+                out.inspect = await this.inspector.run(siteUrl, { limit: opts.inspectLimit }, p => update({ phase: 'inspect', ...p }), signal);
+            }
+        }
+        if (signal.aborted)
+            return out;
+        if (opts.ranks !== false) {
+            if (!this.rankTracker) {
+                out.ranksSkipped = 'no DataForSEO credentials';
+            }
+            else {
+                update({ phase: 'ranks' });
+                phases.push('ranks');
+                out.ranks = await this.rankTracker.run(siteUrl, { location: opts.location }, p => update({ phase: 'ranks', ...p }), signal);
+            }
+        }
+        update({ phase: 'done' });
+        return out;
+    }
+}
+//# sourceMappingURL=Refresh.js.map

package/dist/core/Refresh.js.map

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

package/dist/core/UrlInspector.d.ts

@@ -0,0 +1,22 @@
+import { GscClient } from './GscClient.js';
+export interface InspectResult {
+    siteUrl: string;
+    inspected: number;
+    failed: number;
+}
+/**
+ * Sampled GSC URL Inspection pass → url_inspection table. The API is quota-limited
+ * (~2k/day, ~600/min per site), so we inspect priority URLs only: top pages by GSC
+ * clicks if synced, else top crawled pages by in-degree.
+ */
+export declare class UrlInspector {
+    private readonly gsc;
+    private readonly dataDir;
+    constructor(gsc: GscClient, dataDir: string);
+    private targetUrls;
+    run(siteUrl: string, opts: {
+        limit?: number;
+        delayMs?: number;
+    }, update: (p: Record<string, unknown>) => void, signal: AbortSignal): Promise<InspectResult>;
+}
+//# sourceMappingURL=UrlInspector.d.ts.map

package/dist/core/UrlInspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UrlInspector.d.ts","sourceRoot":"","sources":["../../src/core/UrlInspector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAI3C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAa,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAxC,GAAG,EAAE,SAAS,EAAmB,OAAO,EAAE,MAAM;IAE7E,OAAO,CAAC,UAAU;IAcZ,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5C,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC;CA4D1B"}

package/dist/core/UrlInspector.js

@@ -0,0 +1,92 @@
+import { AuditDatabase } from './AuditDatabase.js';
+import { dbPathFor } from './paths.js';
+import { urlKey, hostFormForProperty } from './url-key.js';
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/**
+ * Sampled GSC URL Inspection pass → url_inspection table. The API is quota-limited
+ * (~2k/day, ~600/min per site), so we inspect priority URLs only: top pages by GSC
+ * clicks if synced, else top crawled pages by in-degree.
+ */
+export class UrlInspector {
+    gsc;
+    dataDir;
+    constructor(gsc, dataDir) {
+        this.gsc = gsc;
+        this.dataDir = dataDir;
+    }
+    targetUrls(db, limit) {
+        const byClicks = db.db
+            .prepare(`SELECT page AS url FROM search_analytics WHERE page IS NOT NULL
+         GROUP BY page ORDER BY SUM(clicks) DESC LIMIT ?`)
+            .all(limit);
+        if (byClicks.length)
+            return byClicks.map(r => r.url);
+        const byLinks = db.db
+            .prepare(`SELECT url FROM pages WHERE status_code = 200 ORDER BY inlink_count DESC LIMIT ?`)
+            .all(limit);
+        return byLinks.map(r => r.url);
+    }
+    async run(siteUrl, opts, update, signal) {
+        const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+        const delayMs = opts.delayMs ?? 200;
+        const hostForm = hostFormForProperty(siteUrl);
+        const db = new AuditDatabase(dbPathFor(this.dataDir, siteUrl));
+        try {
+            const urls = this.targetUrls(db, limit);
+            const upsert = db.db.prepare(`INSERT INTO url_inspection
+           (url_key, url, verdict, coverage_state, indexing_state, robots_txt_state, page_fetch_state,
+            last_crawl_time, google_canonical, user_canonical, crawled_as, mobile_usability, rich_results, referring_urls, inspected_at)
+         VALUES (@url_key,@url,@verdict,@coverage_state,@indexing_state,@robots_txt_state,@page_fetch_state,
+            @last_crawl_time,@google_canonical,@user_canonical,@crawled_as,@mobile_usability,@rich_results,@referring_urls,datetime('now'))
+         ON CONFLICT(url_key) DO UPDATE SET
+           verdict=excluded.verdict, coverage_state=excluded.coverage_state, indexing_state=excluded.indexing_state,
+           robots_txt_state=excluded.robots_txt_state, page_fetch_state=excluded.page_fetch_state,
+           last_crawl_time=excluded.last_crawl_time, google_canonical=excluded.google_canonical,
+           user_canonical=excluded.user_canonical, crawled_as=excluded.crawled_as,
+           mobile_usability=excluded.mobile_usability, rich_results=excluded.rich_results,
+           referring_urls=excluded.referring_urls, inspected_at=datetime('now')`);
+            let inspected = 0;
+            let failed = 0;
+            for (const url of urls) {
+                if (signal.aborted)
+                    break;
+                try {
+                    const r = await this.gsc.inspectUrl(siteUrl, url);
+                    const idx = r.indexStatusResult ?? {};
+                    upsert.run({
+                        url_key: urlKey(url, { hostForm }),
+                        url,
+                        verdict: idx.verdict ?? null,
+                        coverage_state: idx.coverageState ?? null,
+                        indexing_state: idx.indexingState ?? null,
+                        robots_txt_state: idx.robotsTxtState ?? null,
+                        page_fetch_state: idx.pageFetchState ?? null,
+                        last_crawl_time: idx.lastCrawlTime ?? null,
+                        google_canonical: idx.googleCanonical ?? null,
+                        user_canonical: idx.userCanonical ?? null,
+                        crawled_as: idx.crawledAs ?? null,
+                        mobile_usability: r.mobileUsabilityResult?.verdict ?? null,
+                        rich_results: r.richResultsResult ? JSON.stringify(r.richResultsResult) : null,
+                        // Sample of pages Google found linking here — external corroboration for orphan checks.
+                        referring_urls: Array.isArray(idx.referringUrls) && idx.referringUrls.length ? JSON.stringify(idx.referringUrls) : null,
+                    });
+                    inspected++;
+                }
+                catch (err) {
+                    failed++;
+                    console.error(`[inspect] ${url}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (inspected % 10 === 0)
+                    update({ siteUrl, inspected, failed });
+                if (delayMs)
+                    await sleep(delayMs);
+            }
+            update({ siteUrl, inspected, failed });
+            return { siteUrl, inspected, failed };
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+//# sourceMappingURL=UrlInspector.js.map