@pagebridge/core 0.0.3 → 0.2.0

package/dist/insight-generator.js

@@ -0,0 +1,286 @@
+import { EXPECTED_CTR_BY_POSITION } from "./ctr-anomaly-analyzer.js";
+import { daysAgo, formatDate } from "./utils/date-utils.js";
+/**
+ * Converts all analyzer outputs into unified insight documents
+ */
+export class InsightGenerator {
+    siteId;
+    property;
+    constructor(siteId, property) {
+        this.siteId = siteId;
+        this.property = property;
+    }
+    /**
+     * Generate unified insights from all analyzer results
+     * Returns a Map keyed by insightId for idempotency
+     */
+    generate(options) {
+        const insights = new Map();
+        const matchMap = new Map((options.matches ?? []).map((m) => [m.gscUrl, m]));
+        // Quick Wins
+        if (options.quickWins) {
+            for (const [url, queries] of options.quickWins) {
+                const match = matchMap.get(url);
+                const topQuery = queries[0];
+                const insightId = this.makeId("quick_win", url);
+                const totalImpressions = queries.reduce((sum, q) => sum + q.impressions, 0);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "quick_win",
+                    status: "open",
+                    priority: this.prioritizeQuickWin(totalImpressions),
+                    opportunityScore: this.scoreQuickWin(queries),
+                    reason: `${queries.length} queries at positions 8-20 with ${totalImpressions.toLocaleString()} total impressions`,
+                    recommendation: `Target the query "${topQuery?.query}" (position ${topQuery?.position.toFixed(1)}) by expanding content, updating meta tags, and adding internal links to reach page 1.`,
+                    url,
+                    pathScope: url,
+                    linkedDocumentId: match?.sanityId,
+                    metrics: {
+                        queryCount: queries.length,
+                        totalImpressions,
+                        avgPosition: queries.reduce((sum, q) => sum + q.position, 0) / queries.length,
+                    },
+                    queries: queries.slice(0, 10).map((q) => ({
+                        query: q.query,
+                        impressions: q.impressions,
+                        clicks: q.clicks,
+                        position: q.position,
+                    })),
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // CTR Anomalies
+        if (options.ctrAnomalies) {
+            for (const [url, anomaly] of options.ctrAnomalies) {
+                const match = matchMap.get(url);
+                const insightId = this.makeId("ctr_anomaly", url);
+                const estimatedImpressions = 500; // Conservative estimate
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "ctr_anomaly",
+                    status: "open",
+                    priority: anomaly.severity === "high" ? "high" : anomaly.severity === "medium" ? "medium" : "low",
+                    opportunityScore: this.scoreCtrAnomaly(anomaly, estimatedImpressions),
+                    reason: anomaly.message,
+                    recommendation: `Review and update your title tag and meta description. Your CTR is ${(anomaly.actualCtr * 100).toFixed(1)}%, but should be around ${(anomaly.expectedCtr * 100).toFixed(1)}% for position ${anomaly.positionBucket}.`,
+                    url,
+                    pathScope: url,
+                    linkedDocumentId: match?.sanityId,
+                    metrics: {
+                        actualCtr: anomaly.actualCtr,
+                        expectedCtr: anomaly.expectedCtr,
+                        position: anomaly.positionBucket,
+                        severity: anomaly.severity === "high" ? 3 : anomaly.severity === "medium" ? 2 : 1,
+                    },
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // Decay Signals
+        if (options.decaySignals) {
+            for (const signal of options.decaySignals) {
+                const match = matchMap.get(signal.page);
+                const insightId = this.makeId(signal.reason, signal.page);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: signal.reason,
+                    status: "open",
+                    priority: signal.severity === "high"
+                        ? "critical"
+                        : signal.severity === "medium"
+                            ? "high"
+                            : "medium",
+                    opportunityScore: this.scoreDecay(signal),
+                    reason: this.formatDecayReason(signal),
+                    recommendation: this.formatDecayRecommendation(signal),
+                    url: signal.page,
+                    pathScope: signal.page,
+                    linkedDocumentId: match?.sanityId,
+                    metrics: {
+                        positionBefore: signal.metrics.positionBefore,
+                        positionNow: signal.metrics.positionNow,
+                        positionDelta: signal.metrics.positionDelta,
+                        ctrBefore: signal.metrics.ctrBefore,
+                        ctrNow: signal.metrics.ctrNow,
+                        impressions: signal.metrics.impressions,
+                    },
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // Cannibalization
+        if (options.cannibalizationTargets) {
+            for (const [url, targets] of options.cannibalizationTargets) {
+                const match = matchMap.get(url);
+                const insightId = this.makeId("cannibalization", url);
+                const sharedQueryCount = targets.reduce((sum, t) => sum + t.sharedQueries.length, 0);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "cannibalization",
+                    status: "open",
+                    priority: sharedQueryCount > 5 ? "high" : "medium",
+                    opportunityScore: sharedQueryCount * 10,
+                    reason: `Competing with ${targets.length} other page${targets.length !== 1 ? "s" : ""} for ${sharedQueryCount} shared queries`,
+                    recommendation: `Consolidate content or differentiate pages. Consider merging into primary page or rewriting to target different angles. Top competing page: ${targets[0]?.competingPage}`,
+                    url,
+                    pathScope: url,
+                    linkedDocumentId: match?.sanityId,
+                    metrics: {
+                        competitorCount: targets.length,
+                        sharedQueryCount,
+                    },
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // Zero-Click Pages
+        if (options.zeroClickPages && options.zeroClickPages.length > 0) {
+            for (const page of options.zeroClickPages) {
+                const insightId = this.makeId("zero_click", page.page);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "zero_click",
+                    status: "open",
+                    priority: page.impressions > 500 ? "high" : "medium",
+                    opportunityScore: page.impressions * 0.01, // Conservative: 1% of impressions
+                    reason: `${page.impressions} impressions but only ${page.clicks} clicks - searchers see your page but don't click`,
+                    recommendation: `Add a concise answer block at the top of your content, improve snippet with power words, and ensure title/description clearly match search intent.`,
+                    url: page.page,
+                    pathScope: page.page,
+                    linkedDocumentId: page.documentId,
+                    metrics: {
+                        impressions: page.impressions,
+                        clicks: page.clicks,
+                        ctr: page.clicks / Math.max(1, page.impressions),
+                    },
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // New Keywords
+        if (options.newKeywords && options.newKeywords.length > 0) {
+            for (const keyword of options.newKeywords) {
+                const insightId = this.makeId("new_keyword", keyword.page);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "new_keyword",
+                    status: "open",
+                    priority: keyword.impressions > 100 ? "medium" : "low",
+                    opportunityScore: keyword.impressions * 0.05,
+                    reason: `New keyword opportunity: "${keyword.query}" appearing with ${keyword.impressions} impressions`,
+                    recommendation: `This keyword is new to your rankings. Double-check your content covers this topic. Add related sections or internal links to strengthen topical authority.`,
+                    url: keyword.page,
+                    pathScope: keyword.page,
+                    linkedDocumentId: keyword.documentId,
+                    metrics: {
+                        impressions: keyword.impressions,
+                        position: keyword.position,
+                    },
+                    queries: [
+                        {
+                            query: keyword.query,
+                            impressions: keyword.impressions,
+                            clicks: 0,
+                            position: keyword.position,
+                        },
+                    ],
+                    dateRange: { start: formatDate(daysAgo(7)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        // Publishing Impact
+        if (options.publishingImpact) {
+            for (const [url, impact] of options.publishingImpact) {
+                const match = matchMap.get(url);
+                const insightId = this.makeId("publishing_impact", url);
+                const positionImproved = (impact.positionDelta ?? 0) < 0;
+                const clicksDelta = (impact.clicksAfter ?? 0) - (impact.clicksBefore ?? 0);
+                insights.set(insightId, {
+                    insightId,
+                    insightType: "publishing_impact",
+                    status: "open",
+                    priority: clicksDelta > 50 ? "high" : "medium",
+                    opportunityScore: Math.max(0, clicksDelta),
+                    reason: `Content was edited ${impact.daysSinceEdit} days ago. Impact: ${positionImproved ? "improved" : "declined"} position by ${Math.abs(impact.positionDelta ?? 0).toFixed(1)}`,
+                    recommendation: `Monitor trends. If positive: document what worked. If negative: consider reverting changes or further optimization.`,
+                    url,
+                    pathScope: url,
+                    linkedDocumentId: match?.sanityId,
+                    metrics: {
+                        positionBefore: impact.positionBefore ?? 0,
+                        positionAfter: impact.positionAfter ?? 0,
+                        positionDelta: impact.positionDelta ?? 0,
+                        clicksBefore: impact.clicksBefore ?? 0,
+                        clicksAfter: impact.clicksAfter ?? 0,
+                        clicksDelta,
+                        daysSinceEdit: impact.daysSinceEdit,
+                    },
+                    dateRange: { start: formatDate(daysAgo(28)), end: formatDate(daysAgo(3)) },
+                    detectedAt: new Date().toISOString(),
+                });
+            }
+        }
+        return insights;
+    }
+    makeId(type, url) {
+        const urlHash = Buffer.from(url).toString("base64").slice(0, 16);
+        return `${this.siteId}:${type}:${urlHash}`;
+    }
+    prioritizeQuickWin(totalImpressions) {
+        if (totalImpressions >= 1000)
+            return "high";
+        if (totalImpressions >= 500)
+            return "medium";
+        return "low";
+    }
+    scoreQuickWin(queries) {
+        const targetCtr = 0.185; // Position 3 CTR
+        return Math.round(queries.reduce((sum, q) => sum + Math.max(0, q.impressions * targetCtr - q.clicks), 0));
+    }
+    scoreCtrAnomaly(anomaly, impressions) {
+        return Math.round(impressions * (anomaly.expectedCtr - anomaly.actualCtr));
+    }
+    scoreDecay(signal) {
+        const ctrBefore = this.estimateCtrFromPosition(signal.metrics.positionBefore);
+        const ctrNow = this.estimateCtrFromPosition(signal.metrics.positionNow);
+        return Math.round(signal.metrics.impressions * (ctrBefore - ctrNow));
+    }
+    estimateCtrFromPosition(pos) {
+        const bucket = Math.floor(pos);
+        const fraction = pos - bucket;
+        const ctr1 = EXPECTED_CTR_BY_POSITION[bucket] ?? 0.028;
+        const ctr2 = EXPECTED_CTR_BY_POSITION[bucket + 1] ?? 0.028;
+        return ctr1 + (ctr2 - ctr1) * fraction;
+    }
+    formatDecayReason(signal) {
+        if (signal.reason === "position_decay") {
+            return `Position dropped from ${signal.metrics.positionBefore.toFixed(1)} to ${signal.metrics.positionNow.toFixed(1)} (−${Math.abs(signal.metrics.positionDelta).toFixed(1)} positions) over 28 days`;
+        }
+        if (signal.reason === "low_ctr") {
+            return `CTR is ${(signal.metrics.ctrNow * 100).toFixed(1)}%, below 1% threshold for top-10 position`;
+        }
+        if (signal.reason === "impressions_drop") {
+            return `Impressions have declined >50% over 28 days`;
+        }
+        return "Content decay detected";
+    }
+    formatDecayRecommendation(signal) {
+        if (signal.reason === "position_decay") {
+            return `Refresh this page: update intro, add recent examples, verify factual accuracy, check internal linking from related posts.`;
+        }
+        if (signal.reason === "low_ctr") {
+            return `Review title tag and meta description. Use power words and match user intent more closely.`;
+        }
+        if (signal.reason === "impressions_drop") {
+            return `Content may be outdated or overtaken by competitors. Perform competitive audit and refresh with new information.`;
+        }
+        return "Review and refresh page content";
+    }
+}

package/dist/insight-writer.d.ts

@@ -0,0 +1,26 @@
+import type { SanityClient } from "@sanity/client";
+import type { SiteInsightData } from "./site-insight-analyzer.js";
+import type { CannibalizationGroup } from "./cannibalization-analyzer.js";
+import type { QuickWinQuery } from "./quick-win-analyzer.js";
+export interface QuickWinPageSummary {
+    page: string;
+    documentId: string;
+    documentTitle: string;
+    queryCount: number;
+    totalImpressions: number;
+    avgPosition: number;
+}
+export declare class InsightWriter {
+    private sanity;
+    constructor(sanity: SanityClient);
+    /**
+     * Upserts a gscSiteInsight document for the given site.
+     * Contains site-wide insights: top performers, zero-click pages,
+     * orphan pages, new keywords, quick win pages, and cannibalization groups.
+     */
+    write(siteId: string, data: SiteInsightData, cannibalizationGroups: CannibalizationGroup[], matchLookup: Map<string, {
+        sanityId: string;
+        title?: string;
+    }>, quickWins?: Map<string, QuickWinQuery[]>): Promise<void>;
+}
+//# sourceMappingURL=insight-writer.d.ts.map

package/dist/insight-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight-writer.d.ts","sourceRoot":"","sources":["../src/insight-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAExC;;;;OAIG;IACG,KAAK,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,EACrB,qBAAqB,EAAE,oBAAoB,EAAE,EAC7C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EAC9D,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC;CA8EjB"}

package/dist/insight-writer.js

@@ -0,0 +1,87 @@
+import { sanityKey } from "./utils/sanity-key.js";
+export class InsightWriter {
+    sanity;
+    constructor(sanity) {
+        this.sanity = sanity;
+    }
+    /**
+     * Upserts a gscSiteInsight document for the given site.
+     * Contains site-wide insights: top performers, zero-click pages,
+     * orphan pages, new keywords, quick win pages, and cannibalization groups.
+     */
+    async write(siteId, data, cannibalizationGroups, matchLookup, quickWins) {
+        const insightId = `siteInsight-${siteId}`;
+        // Aggregate quick wins per page for the dashboard
+        const quickWinPages = [];
+        if (quickWins) {
+            for (const [page, queries] of quickWins) {
+                if (queries.length === 0)
+                    continue;
+                const totalImpressions = queries.reduce((s, q) => s + q.impressions, 0);
+                const avgPosition = queries.reduce((s, q) => s + q.position, 0) / queries.length;
+                quickWinPages.push({
+                    _key: sanityKey(`qw:${page}`),
+                    page,
+                    documentId: matchLookup.get(page)?.sanityId ?? "",
+                    documentTitle: matchLookup.get(page)?.title ?? "",
+                    queryCount: queries.length,
+                    totalImpressions,
+                    avgPosition,
+                });
+            }
+            quickWinPages.sort((a, b) => b.totalImpressions - a.totalImpressions);
+        }
+        const enriched = {
+            _id: insightId,
+            _type: "gscSiteInsight",
+            site: { _type: "reference", _ref: siteId },
+            topPerformers: data.topPerformers.map((p) => ({
+                _key: sanityKey(`tp:${p.page}`),
+                page: p.page,
+                documentId: matchLookup.get(p.page)?.sanityId ?? "",
+                documentTitle: matchLookup.get(p.page)?.title ?? "",
+                clicks: p.clicks,
+                impressions: p.impressions,
+                position: p.position,
+            })),
+            zeroClickPages: data.zeroClickPages.map((p) => ({
+                _key: sanityKey(`zc:${p.page}`),
+                page: p.page,
+                documentId: matchLookup.get(p.page)?.sanityId ?? "",
+                documentTitle: matchLookup.get(p.page)?.title ?? "",
+                impressions: p.impressions,
+                clicks: p.clicks,
+                position: p.position,
+            })),
+            orphanPages: data.orphanPages.map((p) => ({
+                _key: sanityKey(`op:${p.page}`),
+                page: p.page,
+                documentId: matchLookup.get(p.page)?.sanityId ?? "",
+                documentTitle: matchLookup.get(p.page)?.title ?? "",
+            })),
+            quickWinPages,
+            newKeywordOpportunities: data.newKeywordOpportunities.map((k) => ({
+                _key: sanityKey(`nk:${k.query}:${k.page}`),
+                query: k.query,
+                page: k.page,
+                documentId: matchLookup.get(k.page)?.sanityId ?? "",
+                impressions: k.impressions,
+                position: k.position,
+            })),
+            cannibalizationGroups: cannibalizationGroups.slice(0, 50).map((g) => ({
+                _key: sanityKey(`cg:${g.query}`),
+                query: g.query,
+                pages: g.pages.map((p) => ({
+                    _key: sanityKey(`cgp:${g.query}:${p.page}`),
+                    page: p.page,
+                    documentId: matchLookup.get(p.page)?.sanityId ?? "",
+                    clicks: p.clicks,
+                    impressions: p.impressions,
+                    position: p.position,
+                })),
+            })),
+            lastComputedAt: new Date().toISOString(),
+        };
+        await this.sanity.createOrReplace(enriched);
+    }
+}

package/dist/publishing-impact-analyzer.d.ts

@@ -0,0 +1,23 @@
+import type { DrizzleClient } from "@pagebridge/db";
+import type { PublishingImpact } from "./sync-engine.js";
+export interface EditDateInfo {
+    url: string;
+    editedAt: Date;
+}
+export declare class PublishingImpactAnalyzer {
+    private db;
+    constructor(db: DrizzleClient);
+    /**
+     * Compares 14-day window before vs. 14-day window after the last content edit.
+     * Requires at least 7 days since edit to have meaningful "after" data.
+     *
+     * Note: `editDates` typically comes from Sanity's `_updatedAt` field, which
+     * includes ALL document updates (not just content edits). This means schema
+     * migrations, metadata changes, or SEO field updates will also trigger a
+     * before/after comparison. For more accurate results, pass a dedicated
+     * `contentLastEditedAt` field if available.
+     */
+    analyze(siteId: string, editDates: Map<string, Date>): Promise<Map<string, PublishingImpact>>;
+    private getWindowMetrics;
+}
+//# sourceMappingURL=publishing-impact-analyzer.d.ts.map

package/dist/publishing-impact-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing-impact-analyzer.d.ts","sourceRoot":"","sources":["../src/publishing-impact-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED,qBAAa,wBAAwB;IACvB,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,aAAa;IAErC;;;;;;;;;OASG;IACG,OAAO,CACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;YA+C3B,gBAAgB;CAyC/B"}

package/dist/publishing-impact-analyzer.js

@@ -0,0 +1,79 @@
+import { searchAnalytics } from "@pagebridge/db";
+import { and, eq, gte, lte, sql } from "drizzle-orm";
+import { formatDate } from "./utils/date-utils.js";
+export class PublishingImpactAnalyzer {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Compares 14-day window before vs. 14-day window after the last content edit.
+     * Requires at least 7 days since edit to have meaningful "after" data.
+     *
+     * Note: `editDates` typically comes from Sanity's `_updatedAt` field, which
+     * includes ALL document updates (not just content edits). This means schema
+     * migrations, metadata changes, or SEO field updates will also trigger a
+     * before/after comparison. For more accurate results, pass a dedicated
+     * `contentLastEditedAt` field if available.
+     */
+    async analyze(siteId, editDates) {
+        const results = new Map();
+        const now = new Date();
+        for (const [page, editDate] of editDates) {
+            const daysSinceEdit = Math.floor((now.getTime() - editDate.getTime()) / (1000 * 60 * 60 * 24));
+            // Need at least 7 days of post-edit data
+            if (daysSinceEdit < 7)
+                continue;
+            const beforeStart = new Date(editDate);
+            beforeStart.setDate(beforeStart.getDate() - 14);
+            const beforeEnd = new Date(editDate);
+            const afterStart = new Date(editDate);
+            const afterEnd = new Date(editDate);
+            afterEnd.setDate(afterEnd.getDate() + Math.min(14, daysSinceEdit));
+            const [beforeMetrics, afterMetrics] = await Promise.all([
+                this.getWindowMetrics(siteId, page, beforeStart, beforeEnd),
+                this.getWindowMetrics(siteId, page, afterStart, afterEnd),
+            ]);
+            if (!beforeMetrics || !afterMetrics)
+                continue;
+            results.set(page, {
+                lastEditedAt: editDate.toISOString(),
+                daysSinceEdit,
+                positionBefore: beforeMetrics.position,
+                positionAfter: afterMetrics.position,
+                positionDelta: afterMetrics.position - beforeMetrics.position,
+                clicksBefore: beforeMetrics.clicks,
+                clicksAfter: afterMetrics.clicks,
+                impressionsBefore: beforeMetrics.impressions,
+                impressionsAfter: afterMetrics.impressions,
+                ctrBefore: beforeMetrics.ctr,
+                ctrAfter: afterMetrics.ctr,
+            });
+        }
+        return results;
+    }
+    async getWindowMetrics(siteId, page, startDate, endDate) {
+        const rows = await this.db
+            .select({
+            totalClicks: sql `sum(${searchAnalytics.clicks})`,
+            totalImpressions: sql `sum(${searchAnalytics.impressions})`,
+            avgPosition: sql `avg(${searchAnalytics.position})`,
+        })
+            .from(searchAnalytics)
+            .where(and(eq(searchAnalytics.siteId, siteId), eq(searchAnalytics.page, page), gte(searchAnalytics.date, formatDate(startDate)), lte(searchAnalytics.date, formatDate(endDate))));
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        const clicks = Number(row.totalClicks) || 0;
+        const impressions = Number(row.totalImpressions) || 0;
+        const position = Number(row.avgPosition) || 0;
+        if (impressions === 0)
+            return undefined;
+        return {
+            clicks,
+            impressions,
+            ctr: impressions > 0 ? clicks / impressions : 0,
+            position,
+        };
+    }
+}

package/dist/quick-win-analyzer.d.ts

@@ -0,0 +1,30 @@
+import type { DrizzleClient } from "@pagebridge/db";
+export interface QuickWinQuery {
+    query: string;
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+}
+export interface QuickWinConfig {
+    /** Minimum average position to qualify (default: 8) */
+    positionMin: number;
+    /** Maximum average position to qualify (default: 20) */
+    positionMax: number;
+    /** Minimum total impressions to qualify (default: 50) */
+    minImpressions: number;
+    /** Maximum quick wins per page (default: 10) */
+    maxPerPage: number;
+}
+export declare class QuickWinAnalyzer {
+    private db;
+    private config;
+    constructor(db: DrizzleClient, config?: Partial<QuickWinConfig>);
+    /**
+     * Finds "quick win" queries for all pages: queries where position is 8-20
+     * with significant impressions. These are page-1 opportunities where a small
+     * content tweak could improve ranking.
+     */
+    analyze(siteId: string): Promise<Map<string, QuickWinQuery[]>>;
+}
+//# sourceMappingURL=quick-win-analyzer.d.ts.map

package/dist/quick-win-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-win-analyzer.d.ts","sourceRoot":"","sources":["../src/quick-win-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKpD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AASD,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,EAAE;IAHZ,OAAO,CAAC,MAAM,CAAiB;gBAGrB,EAAE,EAAE,aAAa,EACzB,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAKlC;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;CA4DrE"}

package/dist/quick-win-analyzer.js

@@ -0,0 +1,66 @@
+import { queryAnalytics } from "@pagebridge/db";
+import { and, eq, gte, lte, sql } from "drizzle-orm";
+import { daysAgo, formatDate } from "./utils/date-utils.js";
+const defaultConfig = {
+    positionMin: 8,
+    positionMax: 20,
+    minImpressions: 50,
+    maxPerPage: 10,
+};
+export class QuickWinAnalyzer {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = { ...defaultConfig, ...config };
+    }
+    /**
+     * Finds "quick win" queries for all pages: queries where position is 8-20
+     * with significant impressions. These are page-1 opportunities where a small
+     * content tweak could improve ranking.
+     */
+    async analyze(siteId) {
+        const startDate = daysAgo(28);
+        const endDate = daysAgo(3);
+        const results = await this.db
+            .select({
+            page: queryAnalytics.page,
+            query: queryAnalytics.query,
+            totalClicks: sql `sum(${queryAnalytics.clicks})`,
+            totalImpressions: sql `sum(${queryAnalytics.impressions})`,
+            avgPosition: sql `avg(${queryAnalytics.position})`,
+        })
+            .from(queryAnalytics)
+            .where(and(eq(queryAnalytics.siteId, siteId), gte(queryAnalytics.date, formatDate(startDate)), lte(queryAnalytics.date, formatDate(endDate))))
+            .groupBy(queryAnalytics.page, queryAnalytics.query);
+        const quickWins = new Map();
+        for (const row of results) {
+            const position = Number(row.avgPosition) || 0;
+            const impressions = Number(row.totalImpressions) || 0;
+            const clicks = Number(row.totalClicks) || 0;
+            if (position < this.config.positionMin ||
+                position > this.config.positionMax ||
+                impressions < this.config.minImpressions) {
+                continue;
+            }
+            const entry = {
+                query: row.query,
+                clicks,
+                impressions,
+                ctr: impressions > 0 ? clicks / impressions : 0,
+                position,
+            };
+            const existing = quickWins.get(row.page) ?? [];
+            existing.push(entry);
+            quickWins.set(row.page, existing);
+        }
+        // Sort by impressions desc and cap per page
+        for (const [page, queries] of quickWins) {
+            queries.sort((a, b) => b.impressions - a.impressions);
+            if (queries.length > this.config.maxPerPage) {
+                quickWins.set(page, queries.slice(0, this.config.maxPerPage));
+            }
+        }
+        return quickWins;
+    }
+}

package/dist/site-insight-analyzer.d.ts

@@ -0,0 +1,45 @@
+import type { DrizzleClient } from "@pagebridge/db";
+export interface TopPerformer {
+    page: string;
+    documentId?: string;
+    documentTitle?: string;
+    clicks: number;
+    impressions: number;
+    position: number;
+}
+export interface ZeroClickPage {
+    page: string;
+    documentId?: string;
+    documentTitle?: string;
+    impressions: number;
+    clicks: number;
+    position: number;
+}
+export interface OrphanPage {
+    page: string;
+    documentId?: string;
+    documentTitle?: string;
+    lastImpression?: string;
+}
+export interface NewKeywordOpportunity {
+    query: string;
+    page: string;
+    impressions: number;
+    position: number;
+}
+export interface SiteInsightData {
+    topPerformers: TopPerformer[];
+    zeroClickPages: ZeroClickPage[];
+    orphanPages: OrphanPage[];
+    newKeywordOpportunities: NewKeywordOpportunity[];
+}
+export declare class SiteInsightAnalyzer {
+    private db;
+    constructor(db: DrizzleClient);
+    analyze(siteId: string, allPages: string[]): Promise<SiteInsightData>;
+    private getTopPerformers;
+    private getZeroClickPages;
+    private getOrphanPages;
+    private getNewKeywordOpportunities;
+}
+//# sourceMappingURL=site-insight-analyzer.d.ts.map

package/dist/site-insight-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-insight-analyzer.d.ts","sourceRoot":"","sources":["../src/site-insight-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,uBAAuB,EAAE,qBAAqB,EAAE,CAAC;CAClD;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,aAAa;IAE/B,OAAO,CACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,eAAe,CAAC;YAiBb,gBAAgB;YAgChB,iBAAiB;YAoCjB,cAAc;YAqDd,0BAA0B;CA0DzC"}