@houtini/better-search-console 1.0.0

package/dist/tools/get-overview.js

@@ -0,0 +1,111 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { Database } from '../core/Database.js';
+import { sanitizeSiteUrl, getDataDir, getPeriodDates } from './helpers.js';
+export async function getOverviewData(gscClient, params) {
+    const { dateRange = '28d', sortBy = 'alpha', search } = params;
+    const { current, prior } = getPeriodDates(dateRange);
+    const dataDir = getDataDir();
+    // Get all properties from GSC API
+    const allProperties = await gscClient.listProperties();
+    const properties = [];
+    const pctChange = (curr, prev) => prev === 0 ? null : Math.round(((curr - prev) / prev) * 1000) / 10;
+    for (const prop of allProperties) {
+        const dbFilename = sanitizeSiteUrl(prop.siteUrl) + '.db';
+        const dbPath = join(dataDir, dbFilename);
+        // Skip properties without synced data
+        if (!existsSync(dbPath))
+            continue;
+        // Extract clean domain
+        let domain = prop.siteUrl
+            .replace(/^sc-domain:/, '')
+            .replace(/^https?:\/\//, '')
+            .replace(/\/+$/, '');
+        // Filter by search substring
+        if (search && !domain.toLowerCase().includes(search.toLowerCase()))
+            continue;
+        const db = new Database(dbPath);
+        try {
+            // Summary for current period
+            const currentSummary = db.queryOne(`
+        SELECT
+          COALESCE(SUM(clicks), 0) as clicks,
+          COALESCE(SUM(impressions), 0) as impressions,
+          ROUND(CAST(SUM(clicks) AS REAL) / NULLIF(SUM(impressions), 0), 4) as ctr,
+          ROUND(AVG(position), 1) as avg_position
+        FROM search_analytics
+        WHERE date BETWEEN ? AND ?
+      `, [current.startDate, current.endDate]);
+            // Summary for prior period
+            const priorSummary = db.queryOne(`
+        SELECT
+          COALESCE(SUM(clicks), 0) as clicks,
+          COALESCE(SUM(impressions), 0) as impressions,
+          ROUND(CAST(SUM(clicks) AS REAL) / NULLIF(SUM(impressions), 0), 4) as ctr,
+          ROUND(AVG(position), 1) as avg_position
+        FROM search_analytics
+        WHERE date BETWEEN ? AND ?
+      `, [prior.startDate, prior.endDate]);
+            // Skip if no data at all
+            if (currentSummary.clicks === 0 && currentSummary.impressions === 0 &&
+                priorSummary.clicks === 0 && priorSummary.impressions === 0)
+                continue;
+            // Daily sparkline data
+            const sparkline = db.query(`
+        SELECT date,
+          SUM(clicks) as clicks,
+          SUM(impressions) as impressions
+        FROM search_analytics
+        WHERE date BETWEEN ? AND ?
+        GROUP BY date
+        ORDER BY date ASC
+      `, [current.startDate, current.endDate]);
+            // Last synced
+            const meta = db.getPropertyMeta(prop.siteUrl);
+            properties.push({
+                siteUrl: prop.siteUrl,
+                domain,
+                lastSyncedAt: meta?.lastSyncedAt ?? null,
+                current: {
+                    clicks: currentSummary.clicks,
+                    impressions: currentSummary.impressions,
+                    ctr: currentSummary.ctr ?? 0,
+                    avgPosition: currentSummary.avg_position ?? null,
+                },
+                changes: {
+                    clicksPct: pctChange(currentSummary.clicks, priorSummary.clicks),
+                    impressionsPct: pctChange(currentSummary.impressions, priorSummary.impressions),
+                    ctrPct: pctChange(currentSummary.ctr ?? 0, priorSummary.ctr ?? 0),
+                    avgPositionPct: (currentSummary.avg_position != null && priorSummary.avg_position != null)
+                        ? pctChange(currentSummary.avg_position, priorSummary.avg_position)
+                        : null,
+                },
+                sparkline,
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    // Sort
+    switch (sortBy) {
+        case 'clicks':
+            properties.sort((a, b) => b.current.clicks - a.current.clicks);
+            break;
+        case 'impressions':
+            properties.sort((a, b) => b.current.impressions - a.current.impressions);
+            break;
+        case 'ctr':
+            properties.sort((a, b) => b.current.ctr - a.current.ctr);
+            break;
+        case 'position':
+            properties.sort((a, b) => (a.current.avgPosition ?? 999) - (b.current.avgPosition ?? 999)); // lower is better, null sorts last
+            break;
+        case 'alpha':
+        default:
+            properties.sort((a, b) => a.domain.localeCompare(b.domain));
+            break;
+    }
+    return { dateRange, sortBy, properties };
+}
+//# sourceMappingURL=get-overview.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-overview.js","sourceRoot":"","sources":["../../src/tools/get-overview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAiC3E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAoB,EACpB,MAAsB;IAEtB,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,kCAAkC;IAClC,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,cAAc,EAAE,CAAC;IACvD,MAAM,UAAU,GAAuB,EAAE,CAAC;IAE1C,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,IAAY,EAAiB,EAAE,CAC9D,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAErE,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAEzC,sCAAsC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAS;QAElC,uBAAuB;QACvB,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO;aACtB,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC;aAC1B,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;aAC3B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAEvB,6BAA6B;QAC7B,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QAE7E,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,6BAA6B;YAC7B,MAAM,cAAc,GAAG,EAAE,CAAC,QAAQ,CAAC;;;;;;;;OAQlC,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAEzC,2BAA2B;YAC3B,MAAM,YAAY,GAAG,EAAE,CAAC,QAAQ,CAAC;;;;;;;;OAQhC,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAErC,yBAAyB;YACzB,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,IAAI,cAAc,CAAC,WAAW,KAAK,CAAC;gBAC/D,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,WAAW,KAAK,CAAC;gBAAE,SAAS;YAE1E,uBAAuB;YACvB,MAAM,SAAS,GAAG,EAAE,CAAC,KAAK,CAAC;;;;;;;;OAQ1B,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAEzC,cAAc;YACd,MAAM,IAAI,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAE9C,UAAU,CAAC,IAAI,CAAC;gBACd,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM;gBACN,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,IAAI;gBACxC,OAAO,EAAE;oBACP,MAAM,EAAE,cAAc,CAAC,MAAM;oBAC7B,WAAW,EAAE,cAAc,CAAC,WAAW;oBACvC,GAAG,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC;oBAC5B,WAAW,EAAE,cAAc,CAAC,YAAY,IAAI,IAAI;iBACjD;gBACD,OAAO,EAAE;oBACP,SAAS,EAAE,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;oBAChE,cAAc,EAAE,SAAS,CAAC,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,WAAW,CAAC;oBAC/E,MAAM,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,EAAE,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;oBACjE,cAAc,EAAE,CAAC,cAAc,CAAC,YAAY,IAAI,IAAI,IAAI,YAAY,CAAC,YAAY,IAAI,IAAI,CAAC;wBACxF,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,YAAY,EAAE,YAAY,CAAC,YAAY,CAAC;wBACnE,CAAC,CAAC,IAAI;iBACT;gBACD,SAAS;aACV,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IAED,OAAO;IACP,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC/D,MAAM;QACR,KAAK,aAAa;YAChB,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YACzE,MAAM;QACR,KAAK,KAAK;YACR,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACzD,MAAM;QACR,KAAK,UAAU;YACb,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,mCAAmC;YAC/H,MAAM;QACR,KAAK,OAAO,CAAC;QACb;YACE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5D,MAAM;IACV,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAC3C,CAAC"}

package/dist/tools/helpers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Sanitize a GSC site URL into a safe filename.
+ * e.g. "sc-domain:simracingcockpit.gg" → "simracingcockpit.gg"
+ * e.g. "https://www.example.com/" → "www.example.com"
+ */
+export declare function sanitizeSiteUrl(siteUrl: string): string;
+/**
+ * Get the data directory for SQLite databases.
+ * Priority: BSC_DATA_DIR env var > cross-platform home directory fallback.
+ *
+ * Defaults:
+ *   Windows: C:\seo-audits\better-search-console
+ *   macOS:   ~/seo-audits/better-search-console
+ *   Linux:   ~/seo-audits/better-search-console
+ */
+export declare function getDataDir(): string;
+/**
+ * Get the database path for a given site URL.
+ */
+export declare function getDbPath(siteUrl: string): string;
+/**
+ * Parse a date range shorthand into start/end dates.
+ * Supports: "7d", "14d", "28d", "3m", "6m", "8m", "12m", "16m",
+ * plus named presets: "1d", "lw", "tm", "lm", "tq", "lq", "ytd"
+ */
+export declare function parseDateRange(range: string, referenceDate?: Date): {
+    startDate: string;
+    endDate: string;
+};
+export type ComparisonMode = 'previous_period' | 'year_over_year' | 'previous_month' | 'disabled';
+/**
+ * Get current + prior period date ranges from a date range shorthand.
+ * Supports multiple comparison modes.
+ */
+export declare function getPeriodDates(range: string, referenceDate?: Date, comparisonMode?: ComparisonMode, matchWeekdays?: boolean): {
+    current: {
+        startDate: string;
+        endDate: string;
+    };
+    prior: {
+        startDate: string;
+        endDate: string;
+    };
+};
+/**
+ * Default start date: 3 months ago for fast initial sync.
+ * Users can pass startDate explicitly for longer ranges (up to 16 months).
+ */
+export declare function defaultStartDate(): string;
+/**
+ * Default end date: today.
+ */
+export declare function defaultEndDate(): string;
+/**
+ * Render an ASCII sparkline from an array of numbers.
+ * Uses Unicode block characters for a compact visual trend.
+ */
+export declare function asciiSparkline(data: number[]): string;
+/**
+ * Format a number with k/M suffixes for compact display.
+ */
+export declare function formatCompact(n: number): string;
+/**
+ * Format a percentage change with sign and arrow.
+ */
+export declare function formatChange(pct: number | null): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/tools/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/tools/helpers.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAOnC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAuD1G;AAED,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAElG;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,IAAI,EACpB,cAAc,GAAE,cAAkC,EAClD,aAAa,GAAE,OAAe,GAC7B;IACD,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,CAmFA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAGD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAOrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAIvD"}

package/dist/tools/helpers.js

@@ -0,0 +1,239 @@
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Sanitize a GSC site URL into a safe filename.
+ * e.g. "sc-domain:simracingcockpit.gg" → "simracingcockpit.gg"
+ * e.g. "https://www.example.com/" → "www.example.com"
+ */
+export function sanitizeSiteUrl(siteUrl) {
+    let name = siteUrl;
+    // Remove sc-domain: prefix
+    name = name.replace(/^sc-domain:/, '');
+    // Remove protocol
+    name = name.replace(/^https?:\/\//, '');
+    // Remove trailing slash
+    name = name.replace(/\/+$/, '');
+    // Replace unsafe chars
+    name = name.replace(/[^a-zA-Z0-9.-]/g, '_');
+    return name;
+}
+/**
+ * Get the data directory for SQLite databases.
+ * Priority: BSC_DATA_DIR env var > cross-platform home directory fallback.
+ *
+ * Defaults:
+ *   Windows: C:\seo-audits\better-search-console
+ *   macOS:   ~/seo-audits/better-search-console
+ *   Linux:   ~/seo-audits/better-search-console
+ */
+export function getDataDir() {
+    const dataDir = process.env.BSC_DATA_DIR
+        || join(homedir(), 'seo-audits', 'better-search-console');
+    if (!existsSync(dataDir)) {
+        mkdirSync(dataDir, { recursive: true });
+    }
+    return dataDir;
+}
+/**
+ * Get the database path for a given site URL.
+ */
+export function getDbPath(siteUrl) {
+    return join(getDataDir(), sanitizeSiteUrl(siteUrl) + '.db');
+}
+function formatDate(d) {
+    return d.toISOString().split('T')[0];
+}
+/**
+ * Parse a date range shorthand into start/end dates.
+ * Supports: "7d", "14d", "28d", "3m", "6m", "8m", "12m", "16m",
+ * plus named presets: "1d", "lw", "tm", "lm", "tq", "lq", "ytd"
+ */
+export function parseDateRange(range, referenceDate) {
+    const now = referenceDate || new Date();
+    const today = formatDate(now);
+    // Named presets
+    switch (range) {
+        case 'lw': { // Last Week (Mon-Sun)
+            const d = new Date(now);
+            const day = d.getDay() || 7; // convert Sunday=0 to 7
+            d.setDate(d.getDate() - day - 6); // Monday of last week
+            const start = formatDate(d);
+            d.setDate(d.getDate() + 6); // Sunday of last week
+            return { startDate: start, endDate: formatDate(d) };
+        }
+        case 'tm': { // This Month
+            const d = new Date(now.getFullYear(), now.getMonth(), 1);
+            return { startDate: formatDate(d), endDate: today };
+        }
+        case 'lm': { // Last Month
+            const start = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+            const end = new Date(now.getFullYear(), now.getMonth(), 0); // last day of prev month
+            return { startDate: formatDate(start), endDate: formatDate(end) };
+        }
+        case 'tq': { // This Quarter
+            const qStart = new Date(now.getFullYear(), Math.floor(now.getMonth() / 3) * 3, 1);
+            return { startDate: formatDate(qStart), endDate: today };
+        }
+        case 'lq': { // Last Quarter
+            const qm = Math.floor(now.getMonth() / 3) * 3;
+            const start = new Date(now.getFullYear(), qm - 3, 1);
+            const end = new Date(now.getFullYear(), qm, 0);
+            return { startDate: formatDate(start), endDate: formatDate(end) };
+        }
+        case 'ytd': { // Year to Date
+            const start = new Date(now.getFullYear(), 0, 1);
+            return { startDate: formatDate(start), endDate: today };
+        }
+    }
+    // Numeric presets: "7d", "3m", etc.
+    const match = range.match(/^(\d+)(d|m)$/);
+    if (!match) {
+        throw new Error(`Invalid date range: "${range}". Use format like "7d", "28d", "3m", "6m", "12m", "16m", or named presets: "lw", "tm", "lm", "tq", "lq", "ytd".`);
+    }
+    const amount = parseInt(match[1], 10);
+    const unit = match[2];
+    const start = new Date(now);
+    if (unit === 'd') {
+        start.setDate(start.getDate() - amount);
+    }
+    else if (unit === 'm') {
+        start.setMonth(start.getMonth() - amount);
+    }
+    return { startDate: formatDate(start), endDate: today };
+}
+/**
+ * Get current + prior period date ranges from a date range shorthand.
+ * Supports multiple comparison modes.
+ */
+export function getPeriodDates(range, referenceDate, comparisonMode = 'previous_period', matchWeekdays = false) {
+    const current = parseDateRange(range, referenceDate);
+    if (comparisonMode === 'disabled') {
+        // Return empty prior period — callers should check for this
+        return {
+            current,
+            prior: { startDate: current.startDate, endDate: current.startDate },
+        };
+    }
+    const startMs = new Date(current.startDate).getTime();
+    const endMs = new Date(current.endDate).getTime();
+    const DAY = 24 * 60 * 60 * 1000;
+    const durationMs = endMs - startMs;
+    let priorStart;
+    let priorEnd;
+    switch (comparisonMode) {
+        case 'year_over_year': {
+            const s = new Date(current.startDate);
+            const e = new Date(current.endDate);
+            const sDay = s.getDate();
+            const eDay = e.getDate();
+            s.setFullYear(s.getFullYear() - 1);
+            // Handle leap year: Feb 29 → Feb 28 (setFullYear may roll to Mar 1)
+            if (s.getDate() !== sDay)
+                s.setDate(0); // last day of previous month
+            e.setFullYear(e.getFullYear() - 1);
+            if (e.getDate() !== eDay)
+                e.setDate(0);
+            priorStart = s;
+            priorEnd = e;
+            break;
+        }
+        case 'previous_month': {
+            const s = new Date(current.startDate);
+            const e = new Date(current.endDate);
+            const sMonth = (s.getMonth() - 1 + 12) % 12;
+            const eMonth = (e.getMonth() - 1 + 12) % 12;
+            s.setMonth(s.getMonth() - 1);
+            // Handle day overflow: e.g. Mar 31 → setMonth(-1) → "Feb 31" → Mar 3
+            if (s.getMonth() !== sMonth)
+                s.setDate(0); // last day of intended month
+            e.setMonth(e.getMonth() - 1);
+            if (e.getMonth() !== eMonth)
+                e.setDate(0);
+            priorStart = s;
+            priorEnd = e;
+            break;
+        }
+        case 'previous_period':
+        default: {
+            priorEnd = new Date(startMs - DAY);
+            priorStart = new Date(priorEnd.getTime() - durationMs);
+            break;
+        }
+    }
+    // Match weekdays: shift prior period so that the start day-of-week matches
+    if (matchWeekdays) {
+        const currentStartDay = new Date(current.startDate).getDay();
+        const priorStartDay = priorStart.getDay();
+        let diff = currentStartDay - priorStartDay;
+        // Find the closest shift that aligns weekdays (within ±3 days)
+        if (diff > 3)
+            diff -= 7;
+        if (diff < -3)
+            diff += 7;
+        priorStart = new Date(priorStart.getTime() + diff * DAY);
+        priorEnd = new Date(priorEnd.getTime() + diff * DAY);
+        // Safety: ensure prior period never overlaps with current period
+        const currentStartMs = new Date(current.startDate).getTime();
+        if (priorEnd.getTime() >= currentStartMs) {
+            const overshoot = priorEnd.getTime() - currentStartMs + DAY;
+            priorStart = new Date(priorStart.getTime() - overshoot);
+            priorEnd = new Date(priorEnd.getTime() - overshoot);
+        }
+    }
+    return {
+        current,
+        prior: {
+            startDate: formatDate(priorStart),
+            endDate: formatDate(priorEnd),
+        },
+    };
+}
+/**
+ * Default start date: 3 months ago for fast initial sync.
+ * Users can pass startDate explicitly for longer ranges (up to 16 months).
+ */
+export function defaultStartDate() {
+    const d = new Date();
+    d.setMonth(d.getMonth() - 3);
+    return formatDate(d);
+}
+/**
+ * Default end date: today.
+ */
+export function defaultEndDate() {
+    return formatDate(new Date());
+}
+/**
+ * Render an ASCII sparkline from an array of numbers.
+ * Uses Unicode block characters for a compact visual trend.
+ */
+export function asciiSparkline(data) {
+    if (data.length === 0)
+        return '';
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    const range = max - min || 1;
+    const blocks = ' \u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588';
+    return data.map(v => blocks[Math.round(((v - min) / range) * 8)]).join('');
+}
+/**
+ * Format a number with k/M suffixes for compact display.
+ */
+export function formatCompact(n) {
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
+    if (n >= 1_000)
+        return (n / 1_000).toFixed(1).replace(/\.0$/, '') + 'k';
+    return String(n);
+}
+/**
+ * Format a percentage change with sign and arrow.
+ */
+export function formatChange(pct) {
+    if (pct === null)
+        return 'n/a';
+    const sign = pct > 0 ? '+' : '';
+    return `${sign}${pct}%`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/tools/helpers.js.map

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

package/dist/tools/list-properties.d.ts

@@ -0,0 +1,4 @@
+import { GscClient } from '../core/GscClient.js';
+import type { PropertyStatus } from '../types/index.js';
+export declare function listProperties(gscClient: GscClient): Promise<PropertyStatus[]>;
+//# sourceMappingURL=list-properties.d.ts.map

package/dist/tools/list-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-properties.d.ts","sourceRoot":"","sources":["../../src/tools/list-properties.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,wBAAsB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAgCpF"}

package/dist/tools/list-properties.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { Database } from '../core/Database.js';
+import { sanitizeSiteUrl, getDataDir } from './helpers.js';
+export async function listProperties(gscClient) {
+    const properties = await gscClient.listProperties();
+    const dataDir = getDataDir();
+    const results = [];
+    for (const prop of properties) {
+        const dbFilename = sanitizeSiteUrl(prop.siteUrl) + '.db';
+        const dbPath = join(dataDir, dbFilename);
+        let lastSyncedAt = null;
+        let rowCount = null;
+        if (existsSync(dbPath)) {
+            const db = new Database(dbPath);
+            try {
+                const meta = db.getPropertyMeta(prop.siteUrl);
+                lastSyncedAt = meta?.lastSyncedAt || null;
+                rowCount = db.getRowCount();
+            }
+            finally {
+                db.close();
+            }
+        }
+        results.push({
+            siteUrl: prop.siteUrl,
+            permissionLevel: prop.permissionLevel,
+            lastSyncedAt,
+            rowCount,
+            dbPath: existsSync(dbPath) ? dbPath : null,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=list-properties.js.map

package/dist/tools/list-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-properties.js","sourceRoot":"","sources":["../../src/tools/list-properties.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAoB;IACvD,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,cAAc,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACzC,IAAI,YAAY,GAAkB,IAAI,CAAC;QACvC,IAAI,QAAQ,GAAkB,IAAI,CAAC;QAEnC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC9C,YAAY,GAAG,IAAI,EAAE,YAAY,IAAI,IAAI,CAAC;gBAC1C,QAAQ,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;YAC9B,CAAC;oBAAS,CAAC;gBACT,EAAE,CAAC,KAAK,EAAE,CAAC;YACb,CAAC;QACH,CAAC;QAED,OAAO,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,YAAY;YACZ,QAAQ;YACR,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/tools/query-data.d.ts

@@ -0,0 +1,12 @@
+export interface QueryDataArgs {
+    siteUrl: string;
+    sql: string;
+    params?: any[];
+}
+export interface QueryDataResult {
+    columns: string[];
+    rows: any[];
+    rowCount: number;
+}
+export declare function queryData(args: QueryDataArgs): QueryDataResult;
+//# sourceMappingURL=query-data.d.ts.map

package/dist/tools/query-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-data.d.ts","sourceRoot":"","sources":["../../src/tools/query-data.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAgB9D"}

package/dist/tools/query-data.js

@@ -0,0 +1,20 @@
+import { existsSync } from 'fs';
+import { Database } from '../core/Database.js';
+import { getDbPath } from './helpers.js';
+export function queryData(args) {
+    const { siteUrl, sql, params = [] } = args;
+    const dbPath = getDbPath(siteUrl);
+    if (!existsSync(dbPath)) {
+        throw new Error(`No database found for "${siteUrl}". Run sync_gsc_data first.`);
+    }
+    const db = new Database(dbPath);
+    try {
+        const rows = db.executeReadOnlyQuery(sql, params);
+        const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+        return { columns, rows, rowCount: rows.length };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=query-data.js.map

package/dist/tools/query-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-data.js","sourceRoot":"","sources":["../../src/tools/query-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAczC,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAElC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,6BAA6B,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAClD,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/tools/sync-data.d.ts

@@ -0,0 +1,11 @@
+import { GscClient } from '../core/GscClient.js';
+import type { SyncResult } from '../types/index.js';
+export interface SyncDataArgs {
+    siteUrl: string;
+    startDate?: string;
+    endDate?: string;
+    dimensions?: string[];
+    searchType?: 'web' | 'discover' | 'googleNews' | 'image' | 'video';
+}
+export declare function syncData(gscClient: GscClient, args: SyncDataArgs, signal?: AbortSignal): Promise<SyncResult>;
+//# sourceMappingURL=sync-data.d.ts.map

package/dist/tools/sync-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-data.d.ts","sourceRoot":"","sources":["../../src/tools/sync-data.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,OAAO,CAAC;CACpE;AAKD,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAiErB"}

package/dist/tools/sync-data.js

@@ -0,0 +1,62 @@
+import { Database } from '../core/Database.js';
+import { DataSync } from '../core/DataSync.js';
+import { getDbPath, defaultStartDate, defaultEndDate } from './helpers.js';
+// Track active syncs to prevent duplicate concurrent syncs
+const activeSyncs = new Set();
+export async function syncData(gscClient, args, signal) {
+    const { siteUrl, endDate = defaultEndDate(), dimensions, } = args;
+    let { startDate } = args;
+    // Prevent duplicate syncs for the same property
+    if (activeSyncs.has(siteUrl)) {
+        return {
+            siteUrl,
+            dateFrom: startDate || '',
+            dateTo: endDate,
+            rowsFetched: 0,
+            rowsInserted: 0,
+            durationMs: 0,
+            status: 'error',
+            error: `A sync is already running for ${siteUrl}. Wait for it to complete or restart Claude Desktop to cancel it.`,
+        };
+    }
+    const dbPath = getDbPath(siteUrl);
+    const db = new Database(dbPath);
+    activeSyncs.add(siteUrl);
+    try {
+        // Incremental sync: if no explicit start date, resume from last synced date
+        if (!startDate) {
+            const lastDate = db.getLastSyncDate(siteUrl);
+            if (lastDate) {
+                const d = new Date(lastDate);
+                d.setDate(d.getDate() + 1);
+                const nextDay = d.toISOString().slice(0, 10);
+                if (nextDay <= endDate) {
+                    startDate = nextDay;
+                }
+                else {
+                    return {
+                        siteUrl,
+                        dateFrom: lastDate,
+                        dateTo: endDate,
+                        rowsFetched: 0,
+                        rowsInserted: 0,
+                        durationMs: 0,
+                        status: 'already_current',
+                    };
+                }
+            }
+            else {
+                startDate = defaultStartDate();
+            }
+        }
+        db.upsertPropertyMeta(siteUrl, 'syncing');
+        const sync = new DataSync(db, gscClient);
+        const result = await sync.syncProperty(siteUrl, startDate, endDate, dimensions, args.searchType, signal);
+        return result;
+    }
+    finally {
+        activeSyncs.delete(siteUrl);
+        db.close();
+    }
+}
+//# sourceMappingURL=sync-data.js.map

package/dist/tools/sync-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-data.js","sourceRoot":"","sources":["../../src/tools/sync-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAU3E,2DAA2D;AAC3D,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAoB,EACpB,IAAkB,EAClB,MAAoB;IAEpB,MAAM,EACJ,OAAO,EACP,OAAO,GAAG,cAAc,EAAE,EAC1B,UAAU,GACX,GAAG,IAAI,CAAC;IAET,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAEzB,gDAAgD;IAChD,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO;YACP,QAAQ,EAAE,SAAS,IAAI,EAAE;YACzB,MAAM,EAAE,OAAO;YACf,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,iCAAiC,OAAO,mEAAmE;SACnH,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAEzB,IAAI,CAAC;QACH,4EAA4E;QAC5E,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC7B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;gBAC3B,MAAM,OAAO,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7C,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;oBACvB,SAAS,GAAG,OAAO,CAAC;gBACtB,CAAC;qBAAM,CAAC;oBACN,OAAO;wBACL,OAAO;wBACP,QAAQ,EAAE,QAAQ;wBAClB,MAAM,EAAE,OAAO;wBACf,WAAW,EAAE,CAAC;wBACd,YAAY,EAAE,CAAC;wBACf,UAAU,EAAE,CAAC;wBACb,MAAM,EAAE,iBAAiB;qBAC1B,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,SAAS,GAAG,gBAAgB,EAAE,CAAC;YACjC,CAAC;QACH,CAAC;QAED,EAAE,CAAC,kBAAkB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAE1C,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CACpC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CACjE,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}