pagesight 0.17.0 → 0.19.0

package/docs/usage.md

@@ -0,0 +1,135 @@
+# Using Pagesight
+
+## API
+
+```ts
+import { execute } from "pagesight";
+
+const report = await execute({
+  operation: "gsc.report",
+  site: "sc-domain:example.com",
+  request: {
+    startDate: "2026-08-01",
+    endDate: "2026-08-28",
+    dimensions: ["page"],
+  },
+  maxPages: 4,
+});
+```
+
+Each result contains `schemaVersion`, `provider`, `operation`, `target`, collection
+timestamps, `status`, request/response `pages`, `warnings`, and any `error` and
+`failedRequest`. Reports include `pagination` with `exhausted`, `nextOffset` and
+`rowsReturned`. Raw provider metadata, aggregation, quota, sampling and thresholding
+are retained. Exhausted pagination does **not** imply exhaustive search coverage.
+GA evidence identifies the credential source variable, credential type, and service
+account email when present. It never includes the token or private key. Aggregate
+results include a concise per-observation `summary` alongside full observations.
+
+| Operation                                    | Required inputs                                          |
+| -------------------------------------------- | -------------------------------------------------------- |
+| `discover`                                   | `url`; optional `providers` (`["gsc", "ga"]` by default) |
+| `bing.sites`                                 | None                                                     |
+| `bing.queries`, `bing.pages`, `bing.traffic` | `site`                                                   |
+| `gsc.sites`                                  | None                                                     |
+| `gsc.sitemaps`                               | `site`                                                   |
+| `gsc.inspect`                                | `site`, `url`                                            |
+| `gsc.report`                                 | `site`, `request`; optional `maxPages`                   |
+| `ga.accounts`                                | None                                                     |
+| `ga.property`, `ga.key-events`               | `property`                                               |
+| `ga.realtime`                                | `property`, `request`; moving window, no offset          |
+| `ga.report`                                  | `property`, `request`; optional `maxPages`               |
+| `page`                                       | `url`                                                    |
+| `speed.psi`                                  | `url`; optional `strategy` (`mobile` or `desktop`)       |
+| `speed.crux`, `speed.history`                | `url`; optional `origin: true`, `formFactor`             |
+| `doctor`                                     | `config`                                                 |
+| `assess`                                     | `snapshot`; optional `maxRows` (default 10, max 100)     |
+| `snapshot`                                   | `config`, `startDate`, `endDate`; optional `maxPages`    |
+
+`operationSchema` and `configSchema` are exported for typed validation. The MCP
+`observe` input uses the same schema. `page` observes fetched HTML, status,
+redirects, canonical, robots directives, JSON-LD and a content hash. It does not
+execute browser JavaScript. The original MCP page tool retains its additional
+link, social-meta and contrast checks.
+
+See [measurement and verification](measurement.md) for saved-snapshot assessments,
+Realtime requests, freshness limits and repeatable browser checks.
+
+## CLI
+
+```sh
+pagesight --help
+pagesight discover --url https://example.com/ --providers gsc,ga
+pagesight doctor --config seo.config.json
+pagesight gsc report --site sc-domain:example.com --request report.json --max-pages 4
+pagesight ga report --property 123456 --request ga-report.json
+pagesight page --url https://example.com/
+pagesight speed psi --url https://example.com/
+pagesight speed crux --url https://example.com/ --origin
+pagesight snapshot --config seo.config.json --out observations/baseline.json
+pagesight api --request operation.json
+```
+
+A GSC `report.json` uses the provider request shape. Defaults are finalized data,
+Web search, no dimensions, 25,000 rows, offset zero. Ad hoc commands fetch one page
+unless `--max-pages` is supplied (maximum 20). Request examples:
+
+```json
+{ "startDate": "2026-08-01", "endDate": "2026-08-28", "dimensions": ["page"] }
+```
+
+```json
+{
+  "dateRanges": [{ "startDate": "2026-08-01", "endDate": "2026-08-28" }],
+  "dimensions": [{ "name": "eventName" }],
+  "metrics": [{ "name": "eventCount" }, { "name": "keyEvents" }],
+  "dimensionFilter": {
+    "filter": { "fieldName": "hostName", "stringFilter": { "matchType": "EXACT", "value": "example.com" } }
+  }
+}
+```
+
+GA report defaults are 10,000 rows, offset zero and quota metadata requested.
+`rowCount` determines remaining pages. For discovery/key-event lists, retain and
+check any `nextPageToken`; these small metadata requests currently return one page.
+They return `status: partial` when another metadata page is available.
+
+All data commands output JSON; `--json` is accepted. `--out` writes the same result.
+Exit codes: 0 success, 1 provider failure, 2 invalid input, 3 partial evidence.
+Partial snapshots are saved. A successful report can still have provider coverage
+limitations; inspect warnings and metadata before making comparisons.
+
+## Local HTTP interface
+
+```sh
+# Set PAGESIGHT_API_TOKEN in your private environment file (at least 24 characters).
+pagesight serve --port 6095
+```
+
+Send the shared operation JSON to `POST http://127.0.0.1:6095/v1/query` with
+`Authorization: Bearer <PAGESIGHT_API_TOKEN>`. The server binds only to loopback.
+Missing/invalid authentication returns 401; invalid operations return 400; provider
+failures return 502; partial evidence returns 200 with `status: partial`.
+This interface is for local agents, not an Internet deployment.
+
+## MCP compatibility
+
+Run `pagesight mcp` to start the stdio MCP server. Configure your host to run
+`bun /path/to/pagesight/packages/pagesight/src/index.ts mcp` with the environment above. Existing MCP
+launch configurations must include the `mcp` argument; no arguments show CLI help.
+
+The new `observe` tool accepts `{ "request": <operation object> }` and returns
+structured API evidence. The original six tools remain available:
+
+| Tool     | Capability                                                                |
+| -------- | ------------------------------------------------------------------------- |
+| `audit`  | PageSpeed, metadata, robots, sitemap processing errors and URL inspection |
+| `page`   | Metadata, links, JSON-LD checks, redirects and contrast                   |
+| `speed`  | PageSpeed and CrUX snapshots/history                                      |
+| `search` | GSC reports, sitemap metadata and selected URL inspection                 |
+| `ai`     | Robots and crawler-registry checks, llms.txt detection                    |
+| `setup`  | Existing GSC authentication helpers                                       |
+
+The legacy text tools do not invent indexed counts from deprecated sitemap fields,
+extrapolate sample verdicts to the whole site, or treat missing comparison rows as zero.
+Use `observe` for exact request/response evidence and pagination status.

package/package.json

@@ -1,54 +1,51 @@
 {
   "name": "pagesight",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "See your site the way search engines and AI see it.",
   "keywords": [
-    "seo",
+    "ai-crawlers",
+    "core-web-vitals",
     "geo",
     "google-search-console",
+    "mcp",
     "pagespeed-insights",
-    "core-web-vitals",
-    "web-performance",
     "robots-txt",
-    "ai-crawlers",
-    "mcp"
+    "seo",
+    "web-performance"
   ],
+  "homepage": "https://github.com/caiopizzol/pagesight",
+  "license": "MIT",
+  "author": "Caio Pizzol",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caiopizzol/pagesight.git",
+    "directory": "packages/pagesight"
+  },
+  "bin": {
+    "pagesight": "src/index.ts"
+  },
   "files": [
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "type": "module",
-  "main": "src/index.ts",
-  "bin": {
-    "pagesight": "src/index.ts"
+  "main": "src/api/index.ts",
+  "exports": {
+    ".": "./src/api/index.ts"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/caiopizzol/pagesight.git"
-  },
-  "homepage": "https://github.com/caiopizzol/pagesight",
-  "author": "Caio Pizzol",
   "scripts": {
     "start": "bun run src/index.ts",
-    "test": "bun test",
-    "lint": "biome check src/",
-    "format": "biome format --write src/"
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun test __tests__"
   },
-  "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "saxes": "^6.0.0",
     "zod": "^3.24.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.6",
-    "@semantic-release/npm": "^13.1.5",
-    "@types/bun": "^1.3.11",
-    "lefthook": "^2.1.4",
-    "semantic-release": "^25.0.3",
-    "semantic-release-ai-notes": "^0.2.3"
+    "@types/bun": "^1.3.11"
   }
 }

package/src/api/assessment.ts

@@ -0,0 +1,315 @@
+import { z } from "zod";
+import { capture, type Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { configSchema, gaRequestSchema, gscRequestSchema } from "./schema.js";
+import { snapshotOperations, observationName } from "./snapshot.js";
+import { canonical, normalizeReport, parseNumericValue } from "./report-table.js";
+import { normalizeGaProperty } from "../providers/ga.js";
+
+interface Finding {
+  code: string;
+  level: "attention" | "info" | "unknown";
+  message: string;
+  sources: string[];
+  nextCheck: string;
+}
+export interface AssessmentTable {
+  observation: string;
+  scope: "search-property" | "production" | "production-organic" | "all-hostnames";
+  dimensions: string[];
+  metrics: string[];
+  rows: Array<{ keys: string[]; values: Array<string | number> }>;
+  observedRows: number;
+  displayedRows: number;
+  complete: boolean;
+  limitations: string[];
+}
+
+function reportScope(provider: string, request: unknown) {
+  if (provider === "ga") {
+    const { offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...scope } = gaRequestSchema.parse(request);
+    return scope;
+  }
+  const { startRow: _offset, rowLimit: _limit, ...scope } = gscRequestSchema.parse(request);
+  return scope;
+}
+
+export async function assessSnapshot(snapshot: ImportedSnapshot, maxRows: number): Promise<Evidence> {
+  const { context, observations } = snapshot.pages[0].response;
+  const config = configSchema.parse(context.config);
+  const { startDate, endDate } = context.requestedDates;
+  const hash = Bun.CryptoHasher.hash("sha256", canonical(snapshot), "hex");
+  const result = await capture("pagesight", "assess", snapshot.target, { snapshotSha256: hash, maxRows }, async () => {
+    const findings: Finding[] = [];
+    const tables: AssessmentTable[] = [];
+    let configuredKeyEvents: Array<{ eventName: string; countingMethod?: string }> = [];
+    const keyEventSource = observations.find((o) => o.name === "ga.key-events");
+    const add = (code: string, level: Finding["level"], message: string, sources: string[], nextCheck: string) =>
+      findings.push({ code, level, message, sources, nextCheck });
+    if (config.gaProperty) {
+      if (!config.context.successEvents.length)
+        add(
+          "no-success-events",
+          "attention",
+          "No success events are designated in the site configuration. Reported key events are not validated product outcomes.",
+          ["context.config.context.successEvents"],
+          "Define the useful visitor action, then verify its tracking before evaluating SEO outcomes.",
+        );
+      else
+        add(
+          "success-events-unverified",
+          "info",
+          `Site configuration designates ${config.context.successEvents.length} success event(s); showing ${Math.min(config.context.successEvents.length, maxRows)}: ${config.context.successEvents.slice(0, maxRows).join(", ")} as success events; Pagesight has not independently validated them.`,
+          ["context.config.context.successEvents"],
+          "Verify each event against a real user action and provider reports.",
+        );
+    }
+    if (config.gaProperty) {
+      if (!keyEventSource || keyEventSource.status === "error" || !keyEventSource.pages.length)
+        add(
+          "key-event-metadata-unavailable",
+          "unknown",
+          "Configured GA key-event metadata is unavailable.",
+          ["ga.key-events"],
+          "Read GA key-event metadata separately from observed event counts.",
+        );
+      else {
+        try {
+          if (
+            keyEventSource.provider !== "ga" ||
+            keyEventSource.operation !== "key-events" ||
+            keyEventSource.target !== normalizeGaProperty(config.gaProperty)
+          )
+            throw new Error();
+          const metadata = z.object({
+            keyEvents: z
+              .array(z.object({ eventName: z.string().min(1), countingMethod: z.string().optional() }))
+              .default([]),
+            nextPageToken: z.string().optional(),
+          });
+          const pages = keyEventSource.pages.map((p) => metadata.parse(p.response));
+          configuredKeyEvents = pages.flatMap((p) => p.keyEvents);
+          if (pages.some((p) => p.nextPageToken) || keyEventSource.status !== "ok" || keyEventSource.error)
+            add(
+              "key-event-metadata-partial",
+              "unknown",
+              "Only part of the configured key-event list is available.",
+              ["ga.key-events"],
+              "Retrieve the remaining metadata before claiming this is the complete configuration.",
+            );
+          add(
+            "configured-key-events",
+            "info",
+            `GA configuration contains ${configuredKeyEvents.length} observed key-event entries; showing ${Math.min(configuredKeyEvents.length, maxRows)}: ${
+              configuredKeyEvents
+                .slice(0, maxRows)
+                .map((e) => `${e.eventName}${e.countingMethod ? ` (${e.countingMethod})` : ""}`)
+                .join(", ") || "no observed key-event entries"
+            }. Configuration does not prove events occurred or outcomes are valid.`,
+            ["ga.key-events"],
+            "Compare configured events with observed report rows and separately validate their business meaning.",
+          );
+        } catch {
+          add(
+            "key-event-metadata-unusable",
+            "unknown",
+            "Key-event metadata does not match the configured property or supported shape.",
+            ["ga.key-events"],
+            "Recollect key-event metadata for the configured property.",
+          );
+        }
+      }
+    }
+    for (const operation of snapshotOperations(config, startDate, endDate, 1)) {
+      if (operation.operation !== "ga.report" && operation.operation !== "gsc.report") continue;
+      if (
+        operation.operation === "gsc.report" &&
+        operation.request.dimensions?.some((d) => ["date", "hour"].includes(d))
+      )
+        continue;
+      const name = observationName(operation);
+      const observation = observations.find((o) => o.name === name);
+      if (!observation || observation.status === "error" || !observation.pages.length) {
+        add(
+          "report-unavailable",
+          "unknown",
+          `${name}: no usable report is available.`,
+          [name],
+          "Collect or retry this report; absence is not zero activity.",
+        );
+        continue;
+      }
+      try {
+        const provider = operation.operation === "ga.report" ? "ga" : "gsc";
+        const target = operation.operation === "ga.report" ? normalizeGaProperty(operation.property) : operation.site;
+        if (observation.provider !== provider || observation.operation !== "report" || observation.target !== target)
+          throw new Error("Provider or property does not match the site configuration.");
+        for (const page of observation.pages)
+          if (canonical(reportScope(provider, page.request)) !== canonical(reportScope(provider, operation.request)))
+            throw new Error("Report filters, dates or dimensions do not match the configured snapshot report.");
+        const normalized = normalizeReport(observation, context);
+        if (
+          provider === "gsc" &&
+          normalized.dimensions.length === 0 &&
+          observation.pages.some(
+            (p) => (p.response as { responseAggregationType?: string }).responseAggregationType !== "byProperty",
+          )
+        )
+          throw new Error("GSC property totals require byProperty response aggregation.");
+        const allRows = [...normalized.rows.values()];
+        const limitations = [...new Set([...observation.warnings, ...normalized.warnings])];
+        const complete =
+          observation.status === "ok" && !observation.error && observation.pagination?.exhausted === true;
+        const sorted = [...allRows].sort((a, b) => {
+          const av = parseNumericValue(a.values[0]);
+          const bv = parseNumericValue(b.values[0]);
+          return (bv ?? -Infinity) - (av ?? -Infinity) || canonical(a.keys).localeCompare(canonical(b.keys));
+        });
+        const scope =
+          provider === "gsc"
+            ? "search-property"
+            : normalized.dimensions[0] === "hostName"
+              ? "all-hostnames"
+              : name.endsWith(".organic")
+                ? "production-organic"
+                : "production";
+        tables.push({
+          observation: name,
+          scope,
+          dimensions: normalized.dimensions,
+          metrics: normalized.metrics,
+          rows: sorted.slice(0, maxRows),
+          observedRows: allRows.length,
+          displayedRows: Math.min(allRows.length, maxRows),
+          complete,
+          limitations,
+        });
+        if (name === "ga.report.landingPagePlusQueryString+sessionSource+eventName.organic")
+          add(
+            "organic-landing-events",
+            "info",
+            "These event occurrences are associated with organic sessions' landing pages, not necessarily the pages where the events occurred. Counts are not unique sessions, conversion rates or validated outcomes.",
+            [name, "ga.report.landingPagePlusQueryString+sessionSource.organic"],
+            "Inspect relevant event names alongside landing-page traffic. Preserve raw query strings and provider coverage; verify event meaning and instrumentation changes before prioritizing SEO work.",
+          );
+        if (normalized.dimensions[0] === "hostName") {
+          const other = allRows.filter(
+            (row) =>
+              row.keys[0] !== config.productionHostname && row.values.some((v) => (parseNumericValue(v) ?? 0) > 0),
+          );
+          if (other.length)
+            add(
+              "other-hostnames",
+              "info",
+              `The hostname census contains activity on ${other.length} other observed hostname(s): ${other
+                .slice(0, maxRows)
+                .map((r) => r.keys[0])
+                .join(
+                  ", ",
+                )}. This does not invalidate correctly production-filtered reports or identify internal visitors on production.`,
+              [name],
+              "Keep production reports filtered to the intended hostname; separately evaluate internal-traffic handling.",
+            );
+        }
+        if (name === "ga.report.eventName") {
+          const keyIndex = normalized.metrics.indexOf("keyEvents");
+          const eventRows = allRows.filter((r) => (parseNumericValue(r.values[keyIndex]) ?? 0) > 0);
+          if (eventRows.length > maxRows)
+            add(
+              "event-findings-capped",
+              "info",
+              `Showing ${maxRows} of ${eventRows.length} observed event rows with positive key-event counts.`,
+              [name],
+              "Increase maxRows or inspect the original report for other event names.",
+            );
+          for (const row of eventRows.slice(0, maxRows)) {
+            const event = row.keys[0];
+            const excluded = config.context.excludedKeyEvents.includes(event);
+            add(
+              excluded ? "excluded-key-event" : "reported-key-event",
+              excluded ? "attention" : "info",
+              `${event}: ${row.values[keyIndex]} reported key events${excluded ? "; excluded from success metrics by site configuration" : "; business meaning is not validated by its name or count"}.`,
+              [name],
+              "Inspect the event definition and verify the real user action; do not infer its generation rule from the name.",
+            );
+          }
+          for (const configured of configuredKeyEvents.slice(0, maxRows))
+            if (!allRows.some((r) => r.keys[0] === configured.eventName))
+              add(
+                "configured-event-not-observed",
+                "info",
+                `GA-configured key event ${configured.eventName} has no observed event row in this period and scope. This does not establish zero activity or broken tracking.`,
+                ["ga.key-events", name],
+                "Check date, hostname and report coverage before investigating the event's instrumentation.",
+              );
+          for (const event of config.context.successEvents.slice(0, maxRows))
+            if (!allRows.some((r) => r.keys[0] === event))
+              add(
+                "success-event-not-observed",
+                "unknown",
+                `Configured success event ${event} has no observed row in this report; that is not proof of zero events or broken tracking.`,
+                [name, "context.config.context.successEvents"],
+                "Check report coverage, dates, filters and a real user flow.",
+              );
+        }
+      } catch (error) {
+        add(
+          "report-unusable",
+          "unknown",
+          `${name}: ${error instanceof Error && error.name !== "ZodError" ? error.message : "Request or response does not match the supported report shape."}`,
+          [name],
+          "Inspect the original report and recollect a compatible snapshot before drawing conclusions.",
+        );
+      }
+    }
+    for (const observation of observations.filter((o) => o.status !== "ok" || o.error))
+      add(
+        "provider-incomplete",
+        "unknown",
+        `${observation.name}: ${observation.status}${observation.error ? ` (${observation.error.code})` : ""}.`,
+        [observation.name],
+        "Inspect the retained provider error or pagination before relying on missing data.",
+      );
+    return {
+      assessmentVersion: 1,
+      site: config.site,
+      requestedDates: context.requestedDates,
+      collectedAt: snapshot.finishedAt,
+      basis: "saved-snapshot-not-reverified",
+      snapshotSha256: hash,
+      providerSelection: {
+        gsc: Boolean(config.gscSite),
+        ga: Boolean(config.gaProperty),
+        bing: Boolean(config.bingSite),
+      },
+      findings,
+      tables,
+      displayLimit: maxRows,
+      observations: observations.map((o) => ({
+        name: o.name,
+        provider: o.provider,
+        status: o.status,
+        warnings: o.warnings,
+        errorCode: o.error?.code ?? null,
+      })),
+      limitations: [
+        ...new Set([
+          ...snapshot.warnings,
+          "This assessment describes supplied snapshot evidence; it makes no new provider requests and does not authenticate imported claims. The hash identifies normalized snapshot JSON, not file bytes.",
+          "Configured success events are caller-designated, not independently validated. Aggregate reports cannot diagnose duplicate tags, prove a particular browser test arrived, or establish SEO causation.",
+          "Tables retain raw values for observed rows; capped lists are not exhaustive rankings. GSC property, page and query counts and GA sessions have different semantics and must not be reconciled as a funnel.",
+        ]),
+      ],
+    };
+  });
+  const assessment = result.pages[0]?.response as { findings: Finding[]; tables: AssessmentTable[] } | undefined;
+  if (
+    result.status !== "error" &&
+    (snapshot.status !== "ok" ||
+      snapshot.error ||
+      assessment?.findings.some((f) => f.level === "unknown") ||
+      assessment?.tables.some((t) => !t.complete))
+  )
+    result.status = "partial";
+  return result;
+}

package/src/api/bing.ts

@@ -0,0 +1,83 @@
+import { type BingAction, bingFetch, bingMethods } from "../providers/bing.js";
+import { capture, createEvidence, fail } from "./evidence.js";
+
+export function bingObservation(action: BingAction, site?: string) {
+  return capture(
+    "bing",
+    action,
+    site ?? "accessible-sites",
+    { method: bingMethods[action], ...(site === undefined ? {} : { siteUrl: site }) },
+    () => bingFetch(action, site),
+    [
+      "Bing returns one provider-defined response. These methods support no date range or pagination; completeness is unknown.",
+      ...(action === "sites"
+        ? ["Site verification is not evidence of indexing or traffic."]
+        : [
+            "Raw Bing Date strings are retained. Reporting timezone is unknown; snapshot requested dates do not constrain this response.",
+            action === "traffic"
+              ? "Updated daily. Since 2023-03-24 traffic includes Web, Chat, News, Images, Videos and Knowledge Panel; it is not Google Web scope or isolated AI citation evidence."
+              : "Top-row statistics updated weekly; missing queries/pages are unknown, not zero. Do not assume exhaustive coverage or a Web-only scope.",
+            ...(action === "pages" ? ["In GetPageStats, the Query field contains the page URL."] : []),
+          ]),
+    ],
+  );
+}
+
+export async function bingDiagnostics(
+  action: "crawl-stats" | "crawl-issues" | "url-info" | "link-counts" | "url-links",
+  site: string,
+  url?: string,
+  maxPages = 1,
+) {
+  const result = createEvidence("bing", action, site);
+  result.warnings.push(
+    "Provider dates, count periods and units are retained as reported. Empty reports are not proof of no issues or links.",
+    "Crawl issues are not the Bing UI recommendations list. Link counts do not measure domain quality. InIndex and sitemap counts have different scopes.",
+    "URL-info HttpStatus is provider metadata; zero is not a successful HTTP response. Indexed/crawled state is not a live fetch.",
+  );
+  const paginated = action === "link-counts" || action === "url-links";
+  let page = 0;
+  let rowsReturned = 0;
+  let exhausted = false;
+  let totalPages: number | undefined;
+  for (; page < (paginated ? maxPages : 1); page++) {
+    const parameters: Record<string, string> = {
+      ...(url ? { [action === "url-links" ? "link" : "url"]: url } : {}),
+      ...(paginated ? { page: String(page) } : {}),
+    };
+    const request = { method: bingMethods[action], siteUrl: site, ...parameters };
+    try {
+      const response = await bingFetch(action, site, parameters);
+      result.pages.push({ request, response });
+      if (!paginated) break;
+      const d = response.d as { TotalPages: number; Links?: unknown[]; Details?: unknown[] };
+      rowsReturned += (d.Links ?? d.Details ?? []).length;
+      if (totalPages !== undefined && totalPages !== d.TotalPages) {
+        result.status = "partial";
+        result.warnings.push(
+          "Provider TotalPages changed during pagination; coverage is unstable. Restart to obtain a fresh report.",
+        );
+        page++;
+        break;
+      }
+      totalPages = d.TotalPages;
+      if (page + 1 >= d.TotalPages) {
+        exhausted = true;
+        break;
+      }
+    } catch (error) {
+      result.failedRequest = request;
+      fail(result, error);
+      break;
+    }
+  }
+  if (paginated) {
+    result.pagination = { exhausted, nextOffset: exhausted ? null : page, rowsReturned };
+    result.warnings.push(
+      "nextOffset is a zero-based provider page, not a row offset. Exhaustion describes the returned report, not exhaustive backlink coverage.",
+    );
+    if (!exhausted && result.status === "ok") result.status = "partial";
+  }
+  result.finishedAt = new Date().toISOString();
+  return result;
+}