pagesight 0.17.0 → 0.19.0

package/src/api/opportunities.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+import { assessSnapshot, type AssessmentTable } from "./assessment.js";
+import { capture } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { configSchema, httpUrl } from "./schema.js";
+import { parseNumericValue } from "./report-table.js";
+
+export interface OpportunityPolicy {
+  minImpressions: number;
+  maxClicks: number;
+  maxRows: number;
+}
+const pageSchema = z.object({
+  url: z.string(),
+  finalUrl: z.string(),
+  status: z.number().int(),
+  title: z.string().nullable(),
+  description: z.string().nullable(),
+  canonical: z.string().nullable(),
+  robots: z.array(z.string()),
+  xRobotsTag: z.string().nullable(),
+  warnings: z.array(z.string()).default([]),
+});
+const inspectionSchema = z.object({
+  inspectionResult: z.object({
+    indexStatusResult: z.object({
+      verdict: z.string().optional(),
+      coverageState: z.string().optional(),
+      indexingState: z.string().optional(),
+      robotsTxtState: z.string().optional(),
+      googleCanonical: z.string().optional(),
+      userCanonical: z.string().optional(),
+      lastCrawlTime: z.string().optional(),
+    }),
+  }),
+});
+const organicNames = [
+  "ga.report.landingPagePlusQueryString+sessionSource.organic",
+  "ga.report.landingPagePlusQueryString+sessionSource+eventName.organic",
+];
+function configuredPath(raw: string, site: string): string | null {
+  try {
+    const url = new URL(raw);
+    if (url.origin === new URL(site).origin && url.href === raw && !raw.includes("#") && !url.username && !url.password)
+      return url.pathname + url.search;
+  } catch {
+    /* Invalid provider URL remains raw evidence. */
+  }
+  return null;
+}
+
+export async function opportunities(snapshot: ImportedSnapshot, policy: OpportunityPolicy) {
+  const config = configSchema.parse(snapshot.pages[0].response.context.config);
+  const observations = snapshot.pages[0].response.observations;
+  // Selection must use all retained rows, not the assessment's presentation cap.
+  const assessment = await assessSnapshot(snapshot, Number.MAX_SAFE_INTEGER);
+  const assessed = assessment.pages[0]?.response as
+    | {
+        tables: AssessmentTable[];
+        snapshotSha256: string;
+        limitations: string[];
+      }
+    | undefined;
+  const tables = assessed?.tables ?? [];
+  const search = tables.find((t) => t.observation === "gsc.report.page");
+  const limits = [
+    ...(assessed?.limitations ?? []),
+    "Cutoffs select an investigation cohort, not a CTR benchmark, SEO score or forecast. Position and query/device/country mix can explain few clicks.",
+    "Candidate ordering covers retained GSC page rows only. Missing pages and missing GA rows are unknown, not zero.",
+    "GA is associated by configured origin and exact path/query only, not verified canonical identity. Landing page is session entry, not event location; no cross-provider funnel is computed.",
+    "Technical observations describe their collection times; they need not represent the historical reporting period. No live requests or imported-claim verification occur.",
+  ];
+  let unusableSearchRows = 0;
+  const result = await capture(
+    "pagesight",
+    "opportunities",
+    snapshot.target,
+    {
+      snapshotSha256: assessed?.snapshotSha256 ?? null,
+      ...policy,
+    },
+    async () => {
+      const candidates = (search?.rows ?? [])
+        .flatMap((row) => {
+          const values = Object.fromEntries(search!.metrics.map((m, i) => [m, row.values[i]]));
+          const impressions = parseNumericValue(values.impressions);
+          const clicks = parseNumericValue(values.clicks);
+          const ctr = parseNumericValue(values.ctr);
+          const position = parseNumericValue(values.position);
+          if (
+            impressions === null ||
+            clicks === null ||
+            !Number.isSafeInteger(impressions) ||
+            !Number.isSafeInteger(clicks) ||
+            impressions < 0 ||
+            ctr === null ||
+            ctr < 0 ||
+            ctr > 1 ||
+            position === null ||
+            position < 0 ||
+            clicks < 0 ||
+            clicks > impressions
+          ) {
+            unusableSearchRows++;
+            return [];
+          }
+          if (impressions < policy.minImpressions || clicks > policy.maxClicks) return [];
+          return [{ url: row.keys[0], values, impressions, clicks }];
+        })
+        .sort(
+          (a, b) =>
+            b.impressions - a.impressions || a.clicks - b.clicks || (a.url < b.url ? -1 : a.url > b.url ? 1 : 0),
+        );
+      const selected = candidates.slice(0, policy.maxRows).map((candidate) => {
+        const unknowns: string[] = [
+          "No page-filtered query/device/country breakdown is used for this candidate; property query totals are not page-level evidence.",
+        ];
+        const nextChecks = [
+          "Inspect page-filtered Search Console queries, device/country mix and position before deciding whether a title/snippet change is appropriate.",
+        ];
+        const path = configuredPath(candidate.url, config.site);
+        if (path === null) unknowns.push("No supported configured-origin/exact-path association for this GSC URL.");
+        const organic = organicNames.map((name) => {
+          const table = tables.find((t) => t.observation === name);
+          const matched = path === null ? [] : (table?.rows.filter((r) => r.keys[0] === path) ?? []);
+          if (!table || !matched.length)
+            unknowns.push(`${name}: ${table ? "no exact observed row; not zero activity" : "report unavailable"}.`);
+          return {
+            source: name,
+            association: path === null ? "unmatched" : "configured-origin-exact-path-not-canonical",
+            dimensions: table?.dimensions ?? [],
+            metrics: table?.metrics ?? [],
+            rows: matched.slice(0, policy.maxRows),
+            observedMatchingRows: matched.length,
+            omittedMatchingRows: Math.max(0, matched.length - policy.maxRows),
+            complete: table?.complete ?? false,
+            limitations: table?.limitations ?? [],
+          };
+        });
+        const technical = observations.flatMap((observation) => {
+          if (observation.status !== "ok" || observation.error || observation.pages.length !== 1) return [];
+          const page = observation.pages[0];
+          const request = page.request as Record<string, unknown> | null;
+          if (
+            observation.provider === "web" &&
+            observation.operation === "page" &&
+            observation.target === candidate.url &&
+            request?.url === candidate.url
+          ) {
+            const parsed = pageSchema.safeParse(page.response);
+            if (!parsed.success || parsed.data.url !== candidate.url) return [];
+            if (
+              parsed.data.canonical !== candidate.url ||
+              parsed.data.status !== 200 ||
+              parsed.data.finalUrl !== candidate.url ||
+              [...parsed.data.robots, parsed.data.xRobotsTag ?? ""].some((v) => /noindex/i.test(v))
+            )
+              nextChecks.push(
+                "Check redirects, canonical and indexing directives against intentional route policy before proposing content edits.",
+              );
+            return [
+              {
+                source: observation.name,
+                kind: "html",
+                collectedAt: observation.finishedAt,
+                evidence: parsed.data as unknown,
+                limitations: [
+                  ...observation.warnings,
+                  ...parsed.data.warnings,
+                  "HTML only; JavaScript execution and crawler access were not tested.",
+                ],
+              },
+            ];
+          }
+          if (
+            observation.provider === "gsc" &&
+            observation.operation === "inspect" &&
+            observation.target === config.gscSite &&
+            request?.inspectionUrl === candidate.url &&
+            request.siteUrl === config.gscSite
+          ) {
+            const parsed = inspectionSchema.safeParse(page.response);
+            if (parsed.success) {
+              const index = parsed.data.inspectionResult.indexStatusResult;
+              if (
+                [index.googleCanonical, index.userCanonical].some(
+                  (canonical) => canonical !== undefined && canonical !== candidate.url,
+                )
+              )
+                nextChecks.unshift(
+                  "Check Google's reported canonical URLs against intentional route policy; canonical differences do not authorize additional GA associations or a rewritten candidate URL.",
+                );
+              if (parsed.data.inspectionResult.indexStatusResult.verdict !== "PASS")
+                nextChecks.unshift(
+                  "Reconcile Google's stored inspection verdict and crawl date with the historical impressions and current route policy before a snippet experiment; these observations may describe different times.",
+                );
+              return [
+                {
+                  source: observation.name,
+                  kind: "google-indexed-state",
+                  collectedAt: observation.finishedAt,
+                  evidence: parsed.data.inspectionResult.indexStatusResult as unknown,
+                  limitations: [
+                    ...observation.warnings,
+                    "Google's stored indexed state, not a live fetch or proof of historical state.",
+                  ],
+                },
+              ];
+            }
+          }
+          return [];
+        });
+        if (!technical.some((t) => t.kind === "html")) {
+          unknowns.push("No usable exact-URL HTML observation.");
+          nextChecks.push(
+            "Collect this URL's HTML metadata and verify title, description, canonical and robots directives.",
+          );
+        }
+        if (!technical.some((t) => t.kind === "google-indexed-state")) {
+          unknowns.push("No usable exact-URL Google inspection.");
+          nextChecks.push("Inspect this exact URL in Search Console; indexed state is not a live fetch.");
+        }
+        nextChecks.push(
+          "Validate the meaning and instrumentation dates of relevant events; compare a later equivalent window without treating event counts as a conversion rate.",
+        );
+        return {
+          url: candidate.url,
+          reason: `${candidate.impressions} observed impressions and ${candidate.clicks} clicks meet the supplied cutoffs. Investigate; this does not establish underperformance.`,
+          search: {
+            source: search!.observation,
+            keys: [candidate.url],
+            metrics: candidate.values,
+            complete: search!.complete,
+            limitations: search!.limitations,
+          },
+          organic,
+          technical,
+          unknowns,
+          nextChecks,
+          suggestedRequests: [
+            {
+              operation: "gsc.report",
+              site: config.gscSite,
+              maxPages: 1,
+              request: {
+                ...snapshot.pages[0].response.context.requestedDates,
+                dimensions: ["query"],
+                dataState: "final",
+                dimensionFilterGroups: [
+                  {
+                    groupType: "and",
+                    filters: [{ dimension: "page", operator: "equals", expression: candidate.url }],
+                  },
+                ],
+              },
+            },
+            ...(httpUrl.safeParse(candidate.url).success && !technical.some((t) => t.kind === "html")
+              ? [{ operation: "page", url: candidate.url }]
+              : []),
+            ...(httpUrl.safeParse(candidate.url).success && !technical.some((t) => t.kind === "google-indexed-state")
+              ? [{ operation: "gsc.inspect", site: config.gscSite, url: candidate.url }]
+              : []),
+          ],
+        };
+      });
+      const associatedPaths = new Set(
+        selected.map((candidate) => configuredPath(candidate.url, config.site)).filter((path) => path !== null),
+      );
+      const unassociatedOrganic = organicNames.map((source) => {
+        const table = tables.find((table) => table.observation === source);
+        const rows = table?.rows.filter((row) => !associatedPaths.has(row.keys[0])) ?? [];
+        return {
+          source,
+          available: Boolean(table),
+          meaning:
+            "Not associated with displayed candidates; includes URL variants, special values and landings outside this selected cohort.",
+          dimensions: table?.dimensions ?? [],
+          metrics: table?.metrics ?? [],
+          rows: rows.slice(0, policy.maxRows),
+          observedRows: table ? rows.length : null,
+          omittedRows: Math.max(0, rows.length - policy.maxRows),
+          complete: table?.complete ?? false,
+          limitations: [
+            ...(table?.limitations ?? []),
+            "(other) aggregates and (not set) values cannot establish exact landing identity. Missing associations are not zero traffic.",
+          ],
+        };
+      });
+      return {
+        site: config.site,
+        basis: "saved-snapshot-not-reverified",
+        snapshotSha256: assessed?.snapshotSha256 ?? null,
+        collectedAt: snapshot.finishedAt,
+        requestedDates: snapshot.pages[0].response.context.requestedDates,
+        policy: {
+          ...policy,
+          ordering: "impressions-desc,clicks-asc,url-asc",
+          meaning: "caller-adjustable investigation cutoffs, not quality benchmarks",
+        },
+        searchReportAvailable: Boolean(search),
+        observedSearchRows: search?.observedRows ?? null,
+        unusableSearchRows,
+        qualifyingObservedRows: search ? candidates.length : null,
+        omittedCandidates: Math.max(0, candidates.length - policy.maxRows),
+        candidates: selected,
+        unassociatedOrganic,
+        limitations: limits,
+      };
+    },
+  );
+  if (
+    result.status !== "error" &&
+    (assessment.status !== "ok" || !search || !search.complete || unusableSearchRows > 0)
+  )
+    result.status = "partial";
+  return result;
+}

package/src/api/report-table.ts

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import type { Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { gaRequestSchema, gscRequestSchema } from "./schema.js";
+import { gaFreshnessWarnings } from "./ga-freshness.js";
+
+const gscRow = z
+  .object({
+    keys: z.array(z.string()).optional(),
+    clicks: z.number().finite(),
+    impressions: z.number().finite(),
+    ctr: z.number().finite(),
+    position: z.number().finite(),
+  })
+  .passthrough();
+const gscResponse = z
+  .object({
+    rows: z.array(gscRow).default([]),
+    responseAggregationType: z.string().min(1),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .passthrough();
+const gaResponse = z
+  .object({
+    dimensionHeaders: z.array(z.object({ name: z.string() })).default([]),
+    metricHeaders: z.array(z.object({ name: z.string(), type: z.string().optional() })).min(1),
+    rows: z
+      .array(
+        z.object({
+          dimensionValues: z.array(z.object({ value: z.string() })).default([]),
+          metricValues: z.array(z.object({ value: z.string() })),
+        }),
+      )
+      .default([]),
+    metadata: z.object({ timeZone: z.string().min(1), currencyCode: z.string().optional() }).passthrough(),
+  })
+  .passthrough();
+const gaComparisonDimensions = new Set([
+  "hostName",
+  "sessionDefaultChannelGroup",
+  "sessionSourceMedium",
+  "eventName",
+  "landingPagePlusQueryString",
+  "sessionSource",
+]);
+
+export function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "undefined";
+}
+
+type RawValue = number | string;
+type Report = {
+  request: unknown;
+  start: string;
+  end: string;
+  dimensions: string[];
+  metrics: string[];
+  semantics: unknown;
+  rows: Map<string, { keys: string[]; values: RawValue[] }>;
+  warnings: string[];
+};
+export class Incompatible extends Error {}
+export const requireSame = (a: unknown, b: unknown, message: string) => {
+  if (canonical(a) !== canonical(b)) throw new Incompatible(message);
+};
+
+type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
+
+export function normalizeReport(observation: Evidence, context: SnapshotContext): Report {
+  let report: Report | undefined;
+  let offset = 0;
+  for (const page of observation.pages) {
+    let current: Omit<Report, "rows">;
+    let rows: Array<{ keys: string[]; values: RawValue[] }>;
+    if (observation.provider === "gsc") {
+      const q = gscRequestSchema.parse(page.request);
+      const response = gscResponse.parse(page.response);
+      if (
+        q.dataState !== "final" ||
+        Object.keys(response.metadata ?? {}).some((key) => key.startsWith("first_incomplete"))
+      )
+        throw new Incompatible("GSC data must be finalized.");
+      if (q.startRow !== offset)
+        throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
+      if (q.dimensions.some((dimension) => dimension === "date" || dimension === "hour"))
+        throw new Incompatible(
+          "Time dimensions need a separate alignment policy; this comparison uses non-time row keys.",
+        );
+      const { startDate, endDate, startRow: _startRow, rowLimit: _rowLimit, ...scope } = q;
+      current = {
+        request: scope,
+        start: startDate,
+        end: endDate,
+        dimensions: q.dimensions,
+        metrics: ["clicks", "impressions", "ctr", "position"],
+        semantics: { aggregation: response.responseAggregationType, timezone: "America/Los_Angeles" },
+        warnings: [],
+      };
+      if (!context.observedGscDates.includes(endDate))
+        current.warnings.push(
+          "GSC has no observed date row for the requested end date; trailing days may be unavailable or have no activity.",
+        );
+      rows = response.rows.map((r) => ({ keys: r.keys ?? [], values: [r.clicks, r.impressions, r.ctr, r.position] }));
+    } else {
+      const q = gaRequestSchema.parse(page.request);
+      const response = gaResponse.parse(page.response);
+      if (q.dateRanges.length !== 1) throw new Incompatible("GA comparison requires exactly one date range.");
+      if (
+        q.dimensions.some(
+          (dimension) => !gaComparisonDimensions.has(dimension.name) || Object.hasOwn(dimension, "dimensionExpression"),
+        )
+      )
+        throw new Incompatible("GA comparison supports only snapshot dimension names without dimension expressions.");
+      if (q.offset !== offset) throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
+      const { dateRanges, offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...scope } = q;
+      const dimensions = q.dimensions.map((d) => d.name);
+      const metrics = q.metrics.map((m) => m.name);
+      if (new Set(metrics).size !== metrics.length)
+        throw new Incompatible("GA metric names must be unique to preserve every compared value.");
+      requireSame(
+        response.dimensionHeaders.map((h) => h.name),
+        dimensions,
+        "GA dimension headers must match the request.",
+      );
+      requireSame(
+        response.metricHeaders.map((h) => h.name),
+        metrics,
+        "GA metric headers must match the request.",
+      );
+      current = {
+        request: scope,
+        start: dateRanges[0].startDate,
+        end: dateRanges[0].endDate,
+        dimensions,
+        metrics,
+        semantics: {
+          timezone: response.metadata.timeZone,
+          currency: response.metadata.currencyCode ?? null,
+          metrics: response.metricHeaders,
+        },
+        warnings: [],
+      };
+      if (response.metadata.subjectToThresholding) current.warnings.push("GA report is subject to thresholding.");
+      if (response.metadata.dataLossFromOtherRow)
+        current.warnings.push("GA high-cardinality rows were combined into (other).");
+      if (Array.isArray(response.metadata.samplingMetadatas) && response.metadata.samplingMetadatas.length)
+        current.warnings.push("GA report is sampled.");
+      current.warnings.push(...gaFreshnessWarnings([current.end], response.metadata.timeZone, observation.finishedAt));
+      if (response.metricHeaders.some((h) => h.type === "TYPE_CURRENCY") && !response.metadata.currencyCode)
+        throw new Incompatible("GA currency metrics require a known response currency.");
+      rows = response.rows.map((r) => ({
+        keys: r.dimensionValues.map((v) => v.value),
+        values: r.metricValues.map((v) => v.value),
+      }));
+    }
+    requireSame(
+      { startDate: current.start, endDate: current.end },
+      { startDate: context.requestedDates.startDate, endDate: context.requestedDates.endDate },
+      "Report period does not match the snapshot context.",
+    );
+    if (report) {
+      requireSame(
+        [report.request, report.start, report.end, report.semantics],
+        [current.request, current.start, current.end, current.semantics],
+        "Report scope or metadata changed between pages.",
+      );
+      report.warnings.push(...current.warnings);
+    } else report = { ...current, rows: new Map() };
+    for (const row of rows) {
+      if (row.keys.length !== current.dimensions.length || row.values.length !== current.metrics.length)
+        throw new Incompatible("Row shape does not match the requested dimensions and metrics.");
+      const key = canonical(row.keys);
+      if (report.rows.has(key)) throw new Incompatible("Duplicate row keys make this report ambiguous.");
+      report.rows.set(key, row);
+    }
+    offset += rows.length;
+  }
+  if (!report) throw new Incompatible("No report pages available.");
+  if (observation.provider === "ga") {
+    const totals = observation.pages.map((p) => (p.response as { rowCount?: number }).rowCount ?? 0);
+    if (
+      totals.some((n) => !Number.isSafeInteger(n) || n < offset || n !== totals[0]) ||
+      (observation.pagination?.exhausted && totals[0] !== offset)
+    )
+      throw new Incompatible("GA rowCount conflicts with retained rows or completeness.");
+  }
+
+  if (
+    observation.pagination &&
+    (observation.pagination.rowsReturned !== offset ||
+      observation.pagination.nextOffset !== (observation.pagination.exhausted ? null : offset))
+  )
+    throw new Incompatible("Report pagination does not match the retained rows.");
+  if (observation.status !== "ok" || !observation.pagination?.exhausted || observation.error)
+    report.warnings.push(
+      "Report has incomplete pagination or a provider failure; only observed common rows can be compared.",
+    );
+  return report;
+}
+
+export function parseNumericValue(value: RawValue): number | null {
+  if (typeof value === "string" && !/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/u.test(value)) return null;
+  const result = Number(value);
+  if (typeof value === "string" && !/^-?\d+$/u.test(value)) {
+    const mantissa = value.split(/[eE]/u)[0];
+    const significant = mantissa.replace(/[-.]/gu, "").replace(/^0+/u, "").replace(/0+$/u, "");
+    if (significant.length > 15 || (result === 0 && /[1-9]/u.test(mantissa))) return null;
+  }
+  return Number.isFinite(result) && Math.abs(result) <= Number.MAX_SAFE_INTEGER ? result : null;
+}

package/src/api/reports.ts

@@ -0,0 +1,108 @@
+import { gaFreshnessWarnings } from "./ga-freshness.js";
+import { type GaReport, gaFetch, normalizeGaProperty } from "../providers/ga.js";
+import { querySearchAnalytics, type SearchAnalyticsResponse } from "../providers/gsc.js";
+import { RequestError } from "../shared/http.js";
+import { type Evidence, createEvidence, fail } from "./evidence.js";
+import type { GaRequest, GscRequest } from "./schema.js";
+
+type Query<T> = (request: T) => Promise<SearchAnalyticsResponse | GaReport>;
+
+async function pages<T extends GscRequest | GaRequest>(
+  provider: "gsc" | "ga",
+  target: string,
+  request: T,
+  maxPages: number,
+  query: Query<T>,
+): Promise<Evidence> {
+  const result = createEvidence(provider, "report", target);
+  const isGsc = provider === "gsc";
+  const offsetKey = isGsc ? "startRow" : "offset";
+  let offset = Number(isGsc ? (request as GscRequest).startRow : (request as GaRequest).offset);
+  const limit = Number(isGsc ? (request as GscRequest).rowLimit : (request as GaRequest).limit);
+  result.pagination = { exhausted: false, nextOffset: offset, rowsReturned: 0 };
+  if (isGsc) {
+    result.warnings.push(
+      "GSC dates are America/Los_Angeles; API top-row limits apply even after pagination is exhausted.",
+    );
+    if ((request as GscRequest).dimensions.includes("query"))
+      result.warnings.push("Anonymized queries are omitted. Query-row sums are not property totals.");
+    if ((request as GscRequest).dimensions.includes("page"))
+      result.warnings.push("Page aggregation differs from property aggregation; do not reconcile their row sums.");
+    if ((request as GscRequest).dataState !== "final")
+      result.warnings.push("Fresh data can be incomplete even when metadata is absent for this grouping.");
+  } else if (
+    (request as GaRequest).dimensions.some((dimension) => dimension.name === "landingPagePlusQueryString") &&
+    (request as GaRequest).dimensions.some((dimension) => dimension.name === "eventName")
+  ) {
+    result.warnings.push(
+      "Landing page is the first pageview of the session, not necessarily where an event occurred. Event counts are occurrences, not unique sessions or a conversion rate.",
+      "Landing URLs retain query strings and (not set)/(other) values; do not join them to Search Console canonical URLs without verified mapping.",
+    );
+  }
+  for (let page = 0; page < maxPages; page++) {
+    const effective = { ...request, [offsetKey]: offset };
+    try {
+      const response = await query(effective);
+      if (response.rows !== undefined && !Array.isArray(response.rows))
+        throw new RequestError("Invalid report rows", null, "invalid_response");
+      const count = response.rows?.length ?? 0;
+      const rowCount =
+        (response as GaReport).rowCount ??
+        (count === 0 && Array.isArray((response as GaReport).metricHeaders) ? 0 : undefined);
+      if (!isGsc && (!Number.isSafeInteger(rowCount) || Number(rowCount) < 0))
+        throw new RequestError("GA response missing a valid rowCount", null, "invalid_response");
+      result.pages.push({ request: effective, response });
+      result.pagination.rowsReturned += count;
+      offset += count;
+      const exhausted = isGsc ? count < limit : offset >= Number(rowCount);
+      result.pagination.exhausted = exhausted;
+      result.pagination.nextOffset = exhausted ? null : offset;
+      if (!isGsc) {
+        const metadata = (response as GaReport).metadata;
+        if (metadata?.subjectToThresholding) result.warnings.push("GA report is subject to thresholding.");
+        if (metadata?.dataLossFromOtherRow)
+          result.warnings.push("GA high-cardinality rows were combined into (other).");
+        if (metadata?.samplingMetadatas?.length) result.warnings.push("GA report is sampled; see response metadata.");
+      }
+      if (exhausted) break;
+      if (!count) throw new RequestError("Provider pagination made no progress", null, "invalid_response");
+    } catch (error) {
+      result.failedRequest = effective;
+      fail(result, error);
+      break;
+    }
+  }
+  if (!result.pagination.exhausted && !result.error) result.status = "partial";
+  if (!result.pagination.exhausted)
+    result.warnings.push("Pagination not exhausted. Missing rows are unknown, not zero.");
+  result.finishedAt = new Date().toISOString();
+  if (!isGsc)
+    for (const page of result.pages)
+      result.warnings.push(
+        ...gaFreshnessWarnings(
+          (request as GaRequest).dateRanges.map((range) => range.endDate),
+          (page.response as GaReport).metadata?.timeZone,
+          result.finishedAt,
+        ),
+      );
+  result.warnings = [...new Set(result.warnings)];
+  return result;
+}
+
+export function gscReport(
+  site: string,
+  request: GscRequest,
+  maxPages: number,
+  query = (r: GscRequest) => querySearchAnalytics(site, r),
+): Promise<Evidence> {
+  return pages("gsc", site, request, maxPages, query);
+}
+
+export function gaReport(
+  property: string,
+  request: GaRequest,
+  maxPages: number,
+  query = (r: GaRequest) => gaFetch<GaReport>(`${normalizeGaProperty(property)}:runReport`, r),
+): Promise<Evidence> {
+  return pages("ga", normalizeGaProperty(property), request, maxPages, query);
+}