pagesight 0.18.0 → 0.19.0

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

@@ -1,3 +1,4 @@
+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";
@@ -29,6 +30,14 @@ async function pages<T extends GscRequest | GaRequest>(
       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 };
@@ -66,8 +75,17 @@ async function pages<T extends GscRequest | GaRequest>(
   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.warnings = [...new Set(result.warnings)];
   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;
 }
 

package/src/api/schema.ts

@@ -63,11 +63,52 @@ export const gaRequestSchema = z
   .strict();
 export type GaRequest = z.infer<typeof gaRequestSchema>;
 
-const httpUrl = z
+export const gaRealtimeRequestSchema = z
+  .object({
+    dimensions: z
+      .array(z.object({ name: z.string().min(1) }).strict())
+      .max(9)
+      .default([]),
+    metrics: z
+      .array(z.object({ name: z.string().min(1) }).strict())
+      .min(1)
+      .max(10),
+    dimensionFilter: z.record(z.unknown()).optional(),
+    metricFilter: z.record(z.unknown()).optional(),
+    orderBys: z.array(z.record(z.unknown())).optional(),
+    limit: z.coerce.number().int().min(1).max(250000).default(10000),
+    returnPropertyQuota: z.boolean().default(true),
+    minuteRanges: z
+      .array(
+        z
+          .object({
+            name: z
+              .string()
+              .min(1)
+              .refine((n) => !n.startsWith("date_range_") && !n.startsWith("RESERVED_"))
+              .optional(),
+            startMinutesAgo: z.number().int().min(0).max(59).default(29),
+            endMinutesAgo: z.number().int().min(0).max(59).default(0),
+          })
+          .strict()
+          .refine((r) => r.startMinutesAgo >= r.endMinutesAgo, "Start must be at least as many minutes ago as end"),
+      )
+      .min(1)
+      .max(2)
+      .default([{ startMinutesAgo: 29, endMinutesAgo: 0 }]),
+  })
+  .strict();
+export type GaRealtimeRequest = z.infer<typeof gaRealtimeRequestSchema>;
+
+export const httpUrl = z
   .string()
   .url()
   .refine(
-    (v) => ["http:", "https:"].includes(new URL(v).protocol) && !new URL(v).username && !new URL(v).password,
+    (v) =>
+      URL.canParse(v) &&
+      ["http:", "https:"].includes(new URL(v).protocol) &&
+      !new URL(v).username &&
+      !new URL(v).password,
     "Use an HTTP(S) URL without credentials",
   );
 export const configSchema = z
@@ -113,7 +154,29 @@ export const configSchema = z
     "Select at least one page or provider",
   );
 export type SiteConfig = z.infer<typeof configSchema>;
+const assessedSnapshotSchema = snapshotEvidenceSchema.superRefine((snapshot, ctx) => {
+  const config = configSchema.safeParse(snapshot.pages[0].response.context.config);
+  if (!config.success)
+    for (const issue of config.error.issues)
+      ctx.addIssue({ ...issue, path: ["pages", 0, "response", "context", "config", ...issue.path] });
+});
 const operationVariants = z.discriminatedUnion("operation", [
+  z
+    .object({
+      operation: z.literal("opportunities"),
+      snapshot: assessedSnapshotSchema,
+      minImpressions: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).default(20),
+      maxClicks: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(2),
+      maxRows: z.number().int().min(1).max(100).default(10),
+    })
+    .strict(),
+  z
+    .object({
+      operation: z.literal("assess"),
+      snapshot: assessedSnapshotSchema,
+      maxRows: z.number().int().min(1).max(100).default(10),
+    })
+    .strict(),
   z.object({ operation: z.literal("evidence.import"), document: uiFindingsSchema }).strict(),
   z
     .object({
@@ -154,6 +217,7 @@ const operationVariants = z.discriminatedUnion("operation", [
       maxPages: maxPagesSchema,
     })
     .strict(),
+  z.object({ operation: z.literal("ga.realtime"), property: z.string(), request: gaRealtimeRequestSchema }).strict(),
   z.object({ operation: z.literal("ga.accounts") }).strict(),
   z.object({ operation: z.literal("ga.property"), property: z.string() }).strict(),
   z.object({ operation: z.literal("ga.key-events"), property: z.string() }).strict(),

package/src/api/snapshot.ts

@@ -91,6 +91,21 @@ export function snapshotOperations(
           },
         },
       }),
+      ga(["landingPagePlusQueryString", "sessionSource", "eventName"], ["eventCount"], true, {
+        dimensionFilter: {
+          andGroup: {
+            expressions: [
+              hostFilter,
+              {
+                filter: {
+                  fieldName: "sessionDefaultChannelGroup",
+                  stringFilter: { matchType: "EXACT", value: "Organic Search" },
+                },
+              },
+            ],
+          },
+        },
+      }),
     );
   }
   operations.push(...config.pages.map((url) => ({ operation: "page" as const, url })));
@@ -158,10 +173,14 @@ export async function snapshot(
   );
   if (!config.context.successEvents.length)
     result.warnings.push("No validated success events configured. Do not optimize total keyEvents as conversions.");
+  if (config.context.successEvents.length)
+    result.warnings.push(
+      "Configured success events are caller-designated; Pagesight has not independently validated their tracking or business meaning.",
+    );
   return result;
 }
 
-function observationName(op: Operation): string {
+export function observationName(op: Operation): string {
   if (op.operation === "gsc.report") return `gsc.report.${op.request.dimensions?.join("+") || "property"}`;
   if (op.operation === "ga.report") {
     const dimensions = op.request.dimensions?.map((d) => d.name).join("+") || "property";

package/src/api/ui-findings.ts

@@ -12,7 +12,7 @@ const url = z
 const timestamp = z.string().datetime({ offset: true });
 export const uiFindingsSchema = z
   .object({
-    provider: z.enum(["bing", "gsc", "other"]),
+    provider: z.enum(["bing", "gsc", "ga", "other"]),
     site: url,
     source: z
       .object({

package/src/assessment-text.ts

@@ -0,0 +1,55 @@
+import type { Evidence } from "./api/evidence.js";
+
+// Provider values are untrusted text, including terminal control characters.
+const text = (value: unknown) =>
+  JSON.stringify(value).replace(
+    /[\u007f-\u009f\u2028\u2029]/gu,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+export function renderAssessment(result: Evidence): string {
+  const assessment = result.pages[0]?.response as
+    | {
+        site: string;
+        snapshotSha256: string;
+        requestedDates: { startDate: string; endDate: string };
+        collectedAt: string;
+        findings: Array<{ level: string; message: string; sources: string[]; nextCheck: string }>;
+        tables: Array<{
+          observation: string;
+          scope: string;
+          dimensions: string[];
+          metrics: string[];
+          rows: Array<{ keys: string[]; values: Array<string | number> }>;
+          observedRows: number;
+          displayedRows: number;
+          complete: boolean;
+          limitations: string[];
+        }>;
+        limitations: string[];
+      }
+    | undefined;
+  if (!assessment) return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [
+    `Pagesight assessment: ${text(assessment.site)} (${result.status})`,
+    `Report period: ${assessment.requestedDates.startDate}–${assessment.requestedDates.endDate}`,
+    `Snapshot collected: ${assessment.collectedAt}; supplied evidence, not reverified.`,
+    `Snapshot hash (normalized JSON): ${assessment.snapshotSha256}`,
+    "",
+    ...assessment.findings.flatMap((f) => [
+      `- [${text(f.level)}] ${text(f.message)}`,
+      `  Source: ${f.sources.map(text).join(", ")}`,
+      `  Next check: ${text(f.nextCheck)}`,
+    ]),
+  ];
+  for (const table of assessment.tables) {
+    lines.push(
+      "",
+      `${text(table.observation)} (${table.scope}; showing ${table.displayedRows}/${table.observedRows} observed rows; ${table.complete ? "pagination exhausted" : "incomplete report"})`,
+    );
+    lines.push(`  ${[...table.dimensions, ...table.metrics].map(text).join(" | ")}`);
+    for (const row of table.rows) lines.push(`  ${[...row.keys, ...row.values].map(text).join(" | ")}`);
+    for (const limitation of table.limitations) lines.push(`  Limit: ${text(limitation)}`);
+  }
+  lines.push("", ...assessment.limitations.map((l) => `Limit: ${text(l)}`));
+  return `${lines.join("\n")}\n`;
+}

package/src/cli.ts

@@ -1,3 +1,5 @@
+import { renderAssessment } from "./assessment-text.js";
+import { renderOpportunities } from "./opportunities-text.js";
 import { parseArgs } from "node:util";
 import { defaultDates } from "./shared/dates.js";
 import { execute } from "./api/index.js";
@@ -22,6 +24,7 @@ pagesight bing sites
 pagesight bing queries --site https://example.com/
 pagesight bing pages --site https://example.com/
 pagesight bing traffic --site https://example.com/
+pagesight ga realtime --property 123456 --request realtime.json
 pagesight ga accounts
 pagesight ga property --property 123456
 pagesight ga key-events --property 123456
@@ -31,12 +34,14 @@ pagesight speed psi --url https://example.com/ [--strategy mobile]
 pagesight speed crux --url https://example.com/ [--origin] [--form-factor PHONE]
 pagesight speed history --url https://example.com/ [--origin]
 pagesight snapshot --config seo.config.json [--start YYYY-MM-DD --end YYYY-MM-DD]
+pagesight assess --snapshot saved.json [--format text] [--max-rows 10]
+pagesight opportunities --snapshot saved.json [--min-impressions 20] [--max-clicks 2] [--max-rows 10] [--format text]
 pagesight compare --baseline before.json --current after.json [--max-rows 100]
 pagesight evidence import --request findings.json
 pagesight api --request operation.json
 pagesight serve [--port 6095]    Local HTTP API; requires PAGESIGHT_API_TOKEN
 
-All data commands emit JSON. --json is accepted for clarity.
+Data commands emit JSON by default; assess --format text prints a readable summary. --json is accepted for clarity.
 --out FILE saves the same evidence locally. Exit: 0 success, 1 provider failure,
 2 invalid input, 3 partial evidence. Snapshot defaults to 28 days ending Pacific
 today minus 3 days; max-pages defaults to 4 (ad hoc reports: 1; maximum: 20).
@@ -76,9 +81,13 @@ export async function runCli(args: string[]): Promise<number> {
         "form-factor": { type: "string" },
         origin: { type: "boolean" },
         providers: { type: "string" },
+        snapshot: { type: "string" },
+        format: { type: "string" },
         baseline: { type: "string" },
         current: { type: "string" },
         "max-rows": { type: "string" },
+        "min-impressions": { type: "string" },
+        "max-clicks": { type: "string" },
       },
     });
     if (args.length === 0 || values.help || positionals[0] === "help") {
@@ -93,6 +102,8 @@ export async function runCli(args: string[]): Promise<number> {
       : family;
     const flags: Record<string, string[]> = {
       "evidence.import": ["request"],
+      assess: ["snapshot", "max-rows", "format"],
+      opportunities: ["snapshot", "max-rows", "format", "min-impressions", "max-clicks"],
       discover: ["url", "providers"],
       compare: ["baseline", "current", "max-rows"],
       "bing.crawl-stats": ["site"],
@@ -108,6 +119,7 @@ export async function runCli(args: string[]): Promise<number> {
       "gsc.sitemaps": ["site"],
       "gsc.inspect": ["site", "url"],
       "gsc.report": ["site", "request", "max-pages"],
+      "ga.realtime": ["property", "request"],
       "ga.accounts": [],
       "ga.property": ["property"],
       "ga.key-events": ["property"],
@@ -134,10 +146,28 @@ export async function runCli(args: string[]): Promise<number> {
       process.stderr.write(`Pagesight API listening on ${server.url}v1/query\n`);
       return 0;
     }
+    if (values.format && !["json", "text"].includes(values.format))
+      throw new RequestError("Use --format json or text", null, "invalid_input");
+    if (values.json && values.format === "text")
+      throw new RequestError("--json and --format text conflict", null, "invalid_input");
     let input: unknown;
     if (operation === "api") input = await jsonFile(values.request, "request");
     else if (operation === "evidence.import")
       input = { operation, document: await jsonFile(values.request, "request") };
+    else if (operation === "opportunities")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        minImpressions: Number(values["min-impressions"] ?? 20),
+        maxClicks: Number(values["max-clicks"] ?? 2),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
+    else if (operation === "assess")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
     else if (operation === "compare")
       input = {
         operation,
@@ -169,7 +199,12 @@ export async function runCli(args: string[]): Promise<number> {
       };
     }
     const result = await execute(input);
-    const output = `${JSON.stringify(result, null, 2)}\n`;
+    const output =
+      values.format === "text"
+        ? operation === "opportunities"
+          ? renderOpportunities(result)
+          : renderAssessment(result)
+        : `${JSON.stringify(result, null, 2)}\n`;
     if (values.out) await Bun.write(values.out, output);
     process.stdout.write(output);
     return result.status === "ok" ? 0 : result.status === "partial" ? 3 : 1;

package/src/opportunities-text.ts

@@ -0,0 +1,61 @@
+import type { Evidence } from "./api/evidence.js";
+
+const text = (value: unknown) =>
+  JSON.stringify(value).replace(
+    /[\u007f-\u009f\u2028\u2029]/gu,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+export function renderOpportunities(result: Evidence): string {
+  const out = result.pages[0]?.response as
+    | {
+        site: string;
+        policy: unknown;
+        observedSearchRows: number | null;
+        unusableSearchRows: number;
+        qualifyingObservedRows: number | null;
+        omittedCandidates: number;
+        requestedDates: unknown;
+        snapshotSha256: string;
+        limitations: string[];
+        unassociatedOrganic: unknown[];
+        candidates: Array<{
+          url: string;
+          reason: string;
+          search: unknown;
+          organic: unknown;
+          technical: unknown;
+          unknowns: string[];
+          nextChecks: string[];
+          suggestedRequests: unknown[];
+        }>;
+      }
+    | undefined;
+  if (!out) return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [
+    `Pagesight opportunities: ${text(out.site)} (${result.status})`,
+    `Period: ${text(out.requestedDates)}; supplied snapshot, not reverified.`,
+    `Snapshot hash: ${out.snapshotSha256}`,
+    `Selection policy: ${text(out.policy)}`,
+    `Observed search rows: ${text(out.observedSearchRows)}; unusable: ${out.unusableSearchRows}; qualifying: ${text(out.qualifyingObservedRows)}; omitted candidates: ${out.omittedCandidates}`,
+  ];
+  for (const candidate of out.candidates)
+    lines.push(
+      "",
+      text(candidate.url),
+      `Why: ${text(candidate.reason)}`,
+      `Search: ${text(candidate.search)}`,
+      `Organic associations: ${text(candidate.organic)}`,
+      `Technical evidence: ${text(candidate.technical)}`,
+      ...candidate.unknowns.map((u) => `Unknown: ${text(u)}`),
+      ...candidate.nextChecks.map((n) => `Next check: ${text(n)}`),
+      ...candidate.suggestedRequests.map((request) => `Suggested API request: ${text(request)}`),
+    );
+  lines.push(
+    "",
+    ...out.unassociatedOrganic.map(
+      (table) => `Organic evidence not associated with displayed candidates: ${text(table)}`,
+    ),
+  );
+  lines.push("", ...out.limitations.map((l) => `Limit: ${text(l)}`));
+  return `${lines.join("\n")}\n`;
+}

package/src/tools/observe.ts

@@ -5,7 +5,7 @@ import { RequestError } from "../shared/http.js";
 export function registerObserveTool(server: McpServer): void {
   server.tool(
     "observe",
-    "Run the shared Pagesight API. Read-only operations: discover; bing.sites/queries/pages/traffic/crawl-stats/crawl-issues/url-info/link-counts/url-links; evidence.import (unverified UI findings); gsc.sites/sitemaps/inspect/report; ga.accounts/property/key-events/report; page (metadata and image ALT evidence); speed.psi/crux/history; doctor; snapshot; compare. Pass the API operation object as request. Returns structured evidence, exact effective requests, provider responses and partial errors. See the CLI --help and README for report/config shapes.",
+    "Run the shared Pagesight API. Read-only operations: discover; bing.sites/queries/pages/traffic/crawl-stats/crawl-issues/url-info/link-counts/url-links; evidence.import (unverified UI findings); gsc.sites/sitemaps/inspect/report; ga.accounts/property/key-events/report/realtime; page (metadata and image ALT evidence); speed.psi/crux/history; doctor; snapshot; assess (saved evidence summary); compare. Pass the API operation object as request. Returns structured evidence, exact effective requests, provider responses and partial errors. See the CLI --help and README for report/config shapes.",
     { request: operationSchema },
     async ({ request }) => {
       try {