pagesight 0.16.0 → 0.18.0

package/src/tools/page/structured-data.ts

@@ -0,0 +1,288 @@
+interface SchemaRule {
+  source: string;
+  required: string[];
+  requiredAny?: string[];
+  recommended: string[];
+  imageFields: string[];
+  nestedRequired?: Record<string, string[]>;
+}
+
+interface ValidationIssue {
+  type: string;
+  level: "required" | "recommended";
+  field: string;
+}
+
+export function formatJsonLdType(value: unknown, separator = ", "): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((item): item is string => typeof item === "string"))
+    return value.join(separator);
+  return JSON.stringify(value) ?? "undefined";
+}
+
+export function formatJsonLd(data: unknown, indent = 0): string[] {
+  const lines: string[] = [];
+  const pad = "  ".repeat(indent);
+
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      lines.push(...formatJsonLd(item, indent));
+    }
+    return lines;
+  }
+
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    const type = obj["@type"];
+    if (type) {
+      const label = formatJsonLdType(type);
+      lines.push(`${pad}@type: ${label}`);
+    }
+
+    for (const [key, val] of Object.entries(obj)) {
+      if (key.startsWith("@") && key !== "@type") continue;
+      if (key === "@type") continue;
+      if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        const str = String(val);
+        lines.push(`${pad}${key}: ${str.length > 100 ? `${str.slice(0, 100)}...` : str}`);
+      } else if (Array.isArray(val)) {
+        lines.push(`${pad}${key}: [${val.length} items]`);
+      } else if (val && typeof val === "object") {
+        const nested = val as Record<string, unknown>;
+        if (nested["@type"]) {
+          lines.push(`${pad}${key}:`);
+          lines.push(...formatJsonLd(nested, indent + 1));
+        }
+      }
+    }
+  }
+
+  return lines;
+}
+
+// Presence checks for selected Google-documented fields, reviewed 2026-09-08.
+// These do not cover every conditional requirement, value rule, or eligibility policy.
+const SCHEMA_RULES: Record<string, SchemaRule> = {
+  WebSite: {
+    source: "https://developers.google.com/search/docs/appearance/site-names",
+    required: ["name", "url"],
+    recommended: ["alternateName"],
+    imageFields: [],
+  },
+  Organization: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/organization",
+    required: [],
+    recommended: ["name", "url", "logo", "sameAs", "contactPoint"],
+    imageFields: ["logo"],
+  },
+  Article: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/article",
+    required: [],
+    recommended: ["headline", "image", "datePublished", "author", "dateModified"],
+    imageFields: ["image"],
+  },
+  NewsArticle: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/article",
+    required: [],
+    recommended: ["headline", "image", "datePublished", "author", "dateModified"],
+    imageFields: ["image"],
+  },
+  Product: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/product-snippet",
+    required: ["name"],
+    requiredAny: ["offers", "review", "aggregateRating"],
+    recommended: ["offers", "review", "aggregateRating"],
+    imageFields: ["image"],
+  },
+  LocalBusiness: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/local-business",
+    required: ["name", "address"],
+    recommended: ["telephone", "openingHoursSpecification", "url"],
+    imageFields: ["image"],
+  },
+  BreadcrumbList: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/breadcrumb",
+    required: ["itemListElement"],
+    recommended: [],
+    imageFields: [],
+  },
+  Event: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/event",
+    required: ["name", "startDate", "location"],
+    recommended: ["endDate", "image", "description", "offers", "organizer"],
+    imageFields: ["image"],
+  },
+  Recipe: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/recipe",
+    required: ["name", "image"],
+    recommended: ["author", "datePublished", "description", "recipeIngredient", "recipeInstructions"],
+    imageFields: ["image"],
+  },
+  VideoObject: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/video",
+    required: ["name", "thumbnailUrl", "uploadDate"],
+    recommended: ["description", "duration", "contentUrl", "embedUrl"],
+    imageFields: ["thumbnailUrl"],
+  },
+  SoftwareApplication: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/software-app",
+    required: ["name", "offers"],
+    requiredAny: ["review", "aggregateRating"],
+    recommended: ["applicationCategory", "operatingSystem", "review", "aggregateRating"],
+    imageFields: ["image"],
+    nestedRequired: { offers: ["price"] },
+  },
+  Dataset: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/dataset",
+    required: ["name", "description"],
+    recommended: ["distribution", "creator", "license"],
+    imageFields: [],
+    nestedRequired: { distribution: ["contentUrl"] },
+  },
+  BlogPosting: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/article",
+    required: [],
+    recommended: ["headline", "image", "datePublished", "author", "dateModified"],
+    imageFields: ["image"],
+  },
+  Course: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/course",
+    required: ["name", "description"],
+    recommended: ["provider"],
+    imageFields: [],
+  },
+  JobPosting: {
+    source: "https://developers.google.com/search/docs/appearance/structured-data/job-posting",
+    required: ["title", "description", "datePosted", "hiringOrganization"],
+    recommended: ["employmentType", "baseSalary"],
+    imageFields: [],
+  },
+};
+
+function getNestedValue(obj: Record<string, unknown>, field: string): unknown {
+  const val = obj[field];
+  if (val !== undefined && val !== null && val !== "" && !(Array.isArray(val) && val.length === 0)) return val;
+  return undefined;
+}
+
+export function validateJsonLd(blocks: unknown[]): {
+  issues: ValidationIssue[];
+  imageUrls: string[];
+  validatedTypes: Set<string>;
+} {
+  const issues: ValidationIssue[] = [];
+  const imageUrls: string[] = [];
+  const validatedTypes = new Set<string>();
+
+  function validateBlock(data: unknown) {
+    if (Array.isArray(data)) {
+      for (const item of data) validateBlock(item);
+      return;
+    }
+    if (!data || typeof data !== "object") return;
+
+    const obj = data as Record<string, unknown>;
+    const rawType = obj["@type"];
+    const types = Array.isArray(rawType) ? rawType : rawType ? [rawType] : [];
+
+    for (const type of types) {
+      const rule = SCHEMA_RULES[String(type)];
+      if (!rule) continue;
+      validatedTypes.add(String(type));
+
+      for (const field of rule.required) {
+        if (getNestedValue(obj, field) === undefined) {
+          issues.push({ type: String(type), level: "required", field });
+        }
+      }
+
+      if (rule.requiredAny && !rule.requiredAny.some((field) => getNestedValue(obj, field) !== undefined)) {
+        issues.push({ type: String(type), level: "required", field: rule.requiredAny.join(" or ") });
+      }
+
+      for (const field of rule.recommended) {
+        if (getNestedValue(obj, field) === undefined) {
+          issues.push({ type: String(type), level: "recommended", field });
+        }
+      }
+
+      // Check each nested object; one complete entry cannot hide an incomplete sibling.
+      if (rule.nestedRequired) {
+        for (const [parent, fields] of Object.entries(rule.nestedRequired)) {
+          const parentVal = obj[parent];
+          if (parentVal && typeof parentVal === "object") {
+            const targets = Array.isArray(parentVal) ? parentVal : [parentVal];
+            for (const target of targets) {
+              if (target && typeof target === "object") {
+                const nested = target as Record<string, unknown>;
+                for (const field of fields) {
+                  if (nested[field] === undefined || nested[field] === null || nested[field] === "") {
+                    issues.push({ type: String(type), level: "required", field: `${parent}.${field}` });
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Collect image URLs for validation
+      for (const field of rule.imageFields) {
+        const val = obj[field];
+        if (typeof val === "string" && val.startsWith("http")) {
+          imageUrls.push(val);
+        } else if (val && typeof val === "object") {
+          const nested = val as Record<string, unknown>;
+          const url = nested.url ?? nested.contentUrl;
+          if (typeof url === "string" && url.startsWith("http")) {
+            imageUrls.push(url);
+          }
+        }
+      }
+    }
+
+    // Recurse into nested objects and arrays (e.g., @graph)
+    for (const val of Object.values(obj)) {
+      if (Array.isArray(val)) {
+        for (const item of val) validateBlock(item);
+      } else if (val && typeof val === "object") {
+        validateBlock(val);
+      }
+    }
+  }
+
+  for (const block of blocks) validateBlock(block);
+  return { issues, imageUrls, validatedTypes };
+}
+
+export function formatValidation(issues: ValidationIssue[], validatedTypes: Set<string>): string[] {
+  const lines: string[] = [
+    "Selected field-presence checks only; values, conditional rules, and Google eligibility are not fully checked.",
+  ];
+
+  // Report only the subset checked here, not complete rich-result eligibility.
+  const typesWithRequiredIssues = new Set(issues.filter((i) => i.level === "required").map((i) => i.type));
+  for (const type of validatedTypes) {
+    if (!typesWithRequiredIssues.has(type)) {
+      lines.push(`CHECKED  ${type} — no missing required fields in the checked subset`);
+    }
+  }
+
+  for (const type of validatedTypes) lines.push(`Source (${type}): ${SCHEMA_RULES[type].source}`);
+
+  const required = issues.filter((i) => i.level === "required");
+  const recommended = issues.filter((i) => i.level === "recommended");
+
+  if (required.length > 0) {
+    for (const i of required) {
+      lines.push(`MISSING  ${i.type}.${i.field} (required in checked subset)`);
+    }
+  }
+  if (recommended.length > 0) {
+    for (const i of recommended) {
+      lines.push(`OPTIONAL ${i.type}.${i.field}`);
+    }
+  }
+
+  return lines;
+}

package/src/tools/page/tool.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { analyzePage } from "./analyze.js";
+import { analyzeBatch } from "./batch.js";
+import { analyzeContrast } from "./contrast.js";
+
+export function registerPageTool(server: McpServer): void {
+  server.tool(
+    "page",
+    "Analyze what's on a page — meta tags, Open Graph, Twitter Card, structured data (JSON-LD), internal links, and redirect chains. Also includes a WCAG contrast checker for accessibility fixes.",
+    {
+      url: z.string().url().optional().describe("Single URL to analyze. Use this OR urls, not both."),
+      urls: z
+        .array(z.string().url())
+        .min(2)
+        .max(10)
+        .optional()
+        .describe(
+          "Multiple URLs (2-10) for batch analysis. Returns a summary table of meta tags, structured data, and link health per page.",
+        ),
+      check_links: z
+        .boolean()
+        .optional()
+        .describe("Check internal links for broken links and redirect chains. Default: true. Set false to skip."),
+      user_agent: z.string().optional().describe("Custom User-Agent for page fetch. Default: Googlebot-compatible."),
+      foreground: z
+        .string()
+        .optional()
+        .describe("Foreground (text) hex color for WCAG contrast check (e.g., '#D4594C'). Use with background."),
+      background: z.string().optional().describe("Background hex color for contrast check (e.g., '#FFFFFF')."),
+      large_text: z
+        .boolean()
+        .optional()
+        .describe("Whether text is large (≥18pt or ≥14pt bold). Lowers AA threshold to 3:1."),
+    },
+    async (options) => {
+      const { url, urls, foreground, background, large_text } = options;
+      if (urls) return analyzeBatch(urls, options);
+      if (foreground && background && !url) return analyzeContrast(foreground, background, large_text);
+      if (url) return analyzePage(url, options);
+      return {
+        content: [
+          { type: "text", text: "Provide 'url' for page analysis or 'foreground' + 'background' for contrast check." },
+        ],
+      };
+    },
+  );
+}

package/src/tools/search/actions.ts

@@ -0,0 +1,56 @@
+import { type SearchOptions } from "./schema.js";
+import { runInspect } from "./inspection.js";
+import { runCoverage } from "./coverage.js";
+import { runListSites, runGetSite, runGetSitemap, runSitemaps } from "./sites.js";
+import { runAnalytics } from "./analytics.js";
+import { runGaps } from "./gaps.js";
+import { runSample } from "./sample.js";
+import { textResult } from "./result.js";
+export async function runSearch(params: SearchOptions) {
+  const { site_url, url, sitemap_url, sample_size, filter, start_date, end_date, dimensions, filters, compare } =
+    params;
+  // ── Route to action ──
+  const hasAnalyticsParams = !!(start_date || end_date || dimensions || filters || compare);
+
+  const resolvedAction =
+    params.action ??
+    (url && site_url && !hasAnalyticsParams
+      ? "inspect"
+      : sample_size || filter
+        ? "sample"
+        : hasAnalyticsParams
+          ? "analytics"
+          : sitemap_url && site_url
+            ? "get_sitemap"
+            : site_url
+              ? "sitemaps"
+              : "list_sites");
+
+  try {
+    switch (resolvedAction) {
+      case "inspect":
+        return await runInspect(params);
+      case "sample":
+        return await runSample(params);
+      case "coverage":
+        return await runCoverage(params);
+      case "list_sites":
+        return await runListSites();
+      case "get_site":
+        return await runGetSite(params);
+      case "get_sitemap":
+        return await runGetSitemap(params);
+      case "sitemaps":
+        return await runSitemaps(params);
+      case "analytics":
+        return await runAnalytics(params);
+      case "gaps":
+        return await runGaps(params);
+    }
+    const unhandled: never = resolvedAction;
+    return textResult(`Error: Unknown action "${String(unhandled)}".`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return textResult(`Error: ${msg}`);
+  }
+}

package/src/tools/search/analytics.ts

@@ -0,0 +1,266 @@
+import { querySearchAnalytics, type SearchAnalyticsFilter, type SearchAnalyticsResponse } from "../../providers/gsc.js";
+import { pacificDaysAgo } from "../../shared/dates.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+interface Totals {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+
+function computeTotals(rows: SearchAnalyticsResponse["rows"]): Totals {
+  const r = rows ?? [];
+  const clicks = r.reduce((sum, row) => sum + row.clicks, 0);
+  const impressions = r.reduce((sum, row) => sum + row.impressions, 0);
+  const ctr = impressions > 0 ? clicks / impressions : 0;
+  const position = impressions > 0 ? r.reduce((sum, row) => sum + row.position * row.impressions, 0) / impressions : 0;
+  return { clicks, impressions, ctr, position };
+}
+
+function pctChange(current: number, previous: number): string {
+  if (previous === 0) return current > 0 ? `+${current} (new)` : "0%";
+  const change = ((current - previous) / previous) * 100;
+  return `${change > 0 ? "+" : ""}${change.toFixed(1)}%`;
+}
+
+function formatPerformance(
+  siteUrl: string,
+  result: SearchAnalyticsResponse,
+  dimensions: string[],
+  startDate: string,
+  endDate: string,
+): string {
+  const rows = result.rows ?? [];
+  const lines: string[] = [
+    `=== Search Performance: ${siteUrl} ===`,
+    `Period: ${startDate} to ${endDate}`,
+    `Dimensions: ${dimensions.join(", ")}`,
+    `Aggregation: ${result.responseAggregationType ?? "auto"}`,
+    `Results: ${rows.length}`,
+    "",
+  ];
+
+  if (result.metadata) {
+    if (result.metadata.first_incomplete_date)
+      lines.push(`Data incomplete from: ${result.metadata.first_incomplete_date}`);
+    if (result.metadata.first_incomplete_hour)
+      lines.push(`Hourly data incomplete from: ${result.metadata.first_incomplete_hour}`);
+    lines.push("");
+  }
+
+  if (rows.length === 0) {
+    lines.push("No data found for this period and filters.");
+    return lines.join("\n");
+  }
+
+  const totals = computeTotals(rows);
+
+  if (totals.impressions < 10) {
+    lines.push("⚠ Low data volume — trends may not be meaningful.", "");
+  }
+
+  lines.push(
+    `--- Returned-row summary (${rows.length} rows; not property totals) ---`,
+    "API top-row limits and query privacy exclusions may omit data.",
+    "",
+    `Clicks: ${totals.clicks.toLocaleString()}`,
+    `Impressions: ${totals.impressions.toLocaleString()}`,
+    `Avg CTR: ${(totals.ctr * 100).toFixed(1)}%`,
+    `Avg Position: ${totals.position.toFixed(1)}`,
+    "",
+    "--- Top Results ---",
+    "",
+  );
+
+  const top = rows.slice(0, 25);
+  for (const row of top) {
+    const keys = row.keys.map((k, i) => `${dimensions[i] ?? "key"}=${k}`).join(" | ");
+    lines.push(`${keys}`);
+    lines.push(
+      `  Clicks: ${row.clicks} | Impressions: ${row.impressions} | CTR: ${(row.ctr * 100).toFixed(1)}% | Position: ${row.position.toFixed(1)}`,
+    );
+  }
+
+  if (rows.length > 25) {
+    lines.push("", `... and ${rows.length - 25} more rows`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatComparison(
+  siteUrl: string,
+  current: SearchAnalyticsResponse,
+  previous: SearchAnalyticsResponse,
+  dimensions: string[],
+  currentStart: string,
+  currentEnd: string,
+  previousStart: string,
+  previousEnd: string,
+): string {
+  const curRows = current.rows ?? [];
+  const prevRows = previous.rows ?? [];
+  const cur = computeTotals(curRows);
+  const prev = computeTotals(prevRows);
+
+  const lines: string[] = [
+    `=== Search Performance: ${siteUrl} ===`,
+    `Current:  ${currentStart} to ${currentEnd}`,
+    `Previous: ${previousStart} to ${previousEnd}`,
+    `Dimensions: ${dimensions.join(", ")}`,
+    "",
+  ];
+
+  if (cur.impressions < 10 && prev.impressions < 10) {
+    lines.push("⚠ Low data volume — trends may not be meaningful.", "");
+  }
+
+  lines.push("--- Returned-row summary (not property totals) ---", "");
+  lines.push("Query privacy exclusions, top-row limits and aggregation may omit data.");
+  lines.push("Position changes can reflect a different mix of impressions, not a ranking change.", "");
+  lines.push("             Current     Previous    Change");
+  lines.push(
+    `Clicks:      ${String(cur.clicks.toLocaleString()).padEnd(12)} ${String(prev.clicks.toLocaleString()).padEnd(12)} ${pctChange(cur.clicks, prev.clicks)}`,
+  );
+  lines.push(
+    `Impressions: ${String(cur.impressions.toLocaleString()).padEnd(12)} ${String(prev.impressions.toLocaleString()).padEnd(12)} ${pctChange(cur.impressions, prev.impressions)}`,
+  );
+  const curCtr = `${(cur.ctr * 100).toFixed(1)}%`;
+  const prevCtr = `${(prev.ctr * 100).toFixed(1)}%`;
+  lines.push(`Avg CTR:     ${curCtr.padEnd(12)} ${prevCtr.padEnd(12)} ${((cur.ctr - prev.ctr) * 100).toFixed(1)}pp`);
+  const posStatus =
+    prev.position === 0 && cur.position > 0
+      ? "new"
+      : cur.position < prev.position
+        ? "improved"
+        : cur.position > prev.position
+          ? "regressed"
+          : "stable";
+  lines.push(
+    `Avg Position:${String(cur.position.toFixed(1)).padEnd(13)} ${String(prev.position.toFixed(1)).padEnd(12)} ${posStatus} (${(cur.position - prev.position).toFixed(1)})`,
+  );
+  lines.push("");
+
+  // Build lookup for previous period rows
+  const prevMap = new Map<string, (typeof prevRows)[0]>();
+  for (const row of prevRows) {
+    prevMap.set(JSON.stringify(row.keys), row);
+  }
+
+  // Find biggest movers (by click change)
+  const movers: Array<{ keys: string[]; curClicks: number; prevClicks: number; curPos: number; prevPos: number }> = [];
+  for (const row of curRows) {
+    const key = JSON.stringify(row.keys);
+    const prevRow = prevMap.get(key);
+    if (!prevRow) continue;
+    movers.push({
+      keys: row.keys,
+      curClicks: row.clicks,
+      prevClicks: prevRow.clicks,
+      curPos: row.position,
+      prevPos: prevRow.position,
+    });
+  }
+
+  lines.push("Movers include only rows observed in both periods. Missing rows are unknown, not zero.", "");
+
+  movers.sort((a, b) => Math.abs(b.curClicks - b.prevClicks) - Math.abs(a.curClicks - a.prevClicks));
+
+  const improved = movers.filter((m) => m.curClicks > m.prevClicks).slice(0, 10);
+  const regressed = movers.filter((m) => m.curClicks < m.prevClicks).slice(0, 10);
+
+  if (improved.length > 0) {
+    lines.push("--- Improved ---", "");
+    for (const m of improved) {
+      const keys = m.keys.map((k, i) => `${dimensions[i] ?? "key"}=${k}`).join(" | ");
+      const posChange = m.prevPos > 0 ? ` | Position: ${m.prevPos.toFixed(1)} → ${m.curPos.toFixed(1)}` : "";
+      lines.push(`${keys}`);
+      lines.push(`  Clicks: ${m.prevClicks} → ${m.curClicks} (${pctChange(m.curClicks, m.prevClicks)})${posChange}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("--- Regressed ---", "");
+  if (regressed.length > 0) {
+    for (const m of regressed) {
+      const keys = m.keys.map((k, i) => `${dimensions[i] ?? "key"}=${k}`).join(" | ");
+      const posChange = m.prevPos > 0 ? ` | Position: ${m.prevPos.toFixed(1)} → ${m.curPos.toFixed(1)}` : "";
+      lines.push(`${keys}`);
+      lines.push(`  Clicks: ${m.prevClicks} → ${m.curClicks} (${pctChange(m.curClicks, m.prevClicks)})${posChange}`);
+    }
+  } else {
+    lines.push("(none)");
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function runAnalytics(options: SearchOptions) {
+  const {
+    site_url,
+    start_date,
+    end_date,
+    dimensions,
+    search_type,
+    data_state,
+    aggregation_type,
+    filters,
+    row_limit,
+    start_row,
+    compare,
+  } = options;
+  if (!site_url) return textResult("Error: site_url is required for analytics.");
+
+  const startDate = start_date ?? pacificDaysAgo(28);
+  const endDate = end_date ?? pacificDaysAgo(3);
+
+  if (start_date && Number.isNaN(new Date(start_date).getTime())) {
+    return textResult(`Error: invalid start_date "${start_date}". Use YYYY-MM-DD format.`);
+  }
+  if (end_date && Number.isNaN(new Date(end_date).getTime())) {
+    return textResult(`Error: invalid end_date "${end_date}". Use YYYY-MM-DD format.`);
+  }
+  const dims = dimensions ?? ["query", "page"];
+
+  const filterGroups =
+    filters && filters.length > 0
+      ? [{ groupType: "and" as const, filters: filters as SearchAnalyticsFilter[] }]
+      : undefined;
+
+  const queryOpts = {
+    startDate,
+    endDate,
+    dimensions: dims,
+    type: search_type,
+    dataState: data_state,
+    aggregationType: aggregation_type,
+    rowLimit: row_limit ?? 1000,
+    startRow: start_row,
+    dimensionFilterGroups: filterGroups,
+  };
+
+  if (compare) {
+    // Calculate previous period of equal length
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+    const durationMs = end.getTime() - start.getTime();
+    const prevEnd = new Date(start.getTime() - 1 * 24 * 60 * 60 * 1000); // day before current start
+    const prevStart = new Date(prevEnd.getTime() - durationMs);
+    const prevStartDate = prevStart.toISOString().split("T")[0];
+    const prevEndDate = prevEnd.toISOString().split("T")[0];
+
+    const [current, previous] = await Promise.all([
+      querySearchAnalytics(site_url, queryOpts),
+      querySearchAnalytics(site_url, { ...queryOpts, startDate: prevStartDate, endDate: prevEndDate }),
+    ]);
+
+    return textResult(
+      formatComparison(site_url, current, previous, dims, startDate, endDate, prevStartDate, prevEndDate),
+    );
+  }
+
+  const result = await querySearchAnalytics(site_url, queryOpts);
+  return textResult(formatPerformance(site_url, result, dims, startDate, endDate));
+}