pagesight 0.17.0 → 0.19.0

package/src/api/compare-snapshots.ts

@@ -0,0 +1,167 @@
+import { canonical, normalizeReport, parseNumericValue, Incompatible, requireSame } from "./report-table.js";
+import { RequestError } from "../shared/http.js";
+import { capture, type Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+
+function metric(baseline: number | string, current: number | string) {
+  const before = parseNumericValue(baseline);
+  const after = parseNumericValue(current);
+  if (before === null || after === null)
+    return {
+      baseline,
+      current,
+      delta: null,
+      percentChange: null,
+      reason: "Unsafe or invalid numeric value; raw values retained.",
+    };
+  const delta = after - before;
+  if (!Number.isFinite(delta) || Math.abs(delta) > Number.MAX_SAFE_INTEGER)
+    return { baseline, current, delta: null, percentChange: null, reason: "Numeric delta exceeds safe range." };
+  const percent = before === 0 ? null : (delta / before) * 100;
+  return { baseline, current, delta, percentChange: percent !== null && Number.isFinite(percent) ? percent : null };
+}
+
+type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
+
+function compareObservation(
+  baseline: Evidence | undefined,
+  current: Evidence | undefined,
+  maxRows: number,
+  beforeContext: SnapshotContext,
+  afterContext: SnapshotContext,
+) {
+  const name = baseline?.name ?? current?.name;
+  const warnings = [...new Set([...(baseline?.warnings ?? []), ...(current?.warnings ?? [])])];
+  if (!baseline || !current)
+    return {
+      name,
+      status: "unavailable",
+      reason: "Observation missing from one snapshot; absence is not zero.",
+      warnings,
+    };
+  if (
+    baseline.provider !== current.provider ||
+    baseline.operation !== current.operation ||
+    baseline.target !== current.target
+  )
+    return { name, status: "incompatible", reason: "Observation provider, operation or target changed.", warnings };
+  if (baseline.operation !== "report" || !["gsc", "ga"].includes(baseline.provider))
+    return {
+      name,
+      status: "unsupported",
+      reason:
+        "This version compares GSC and GA reports only. Bing windows and other observations require a separate comparison policy.",
+      warnings,
+    };
+  if (baseline.status === "error" || current.status === "error" || !baseline.pages.length || !current.pages.length)
+    return { name, status: "unavailable", reason: "A provider report failed or has no response pages.", warnings };
+  try {
+    const a = normalizeReport(baseline, beforeContext);
+    const b = normalizeReport(current, afterContext);
+    requireSame(a.request, b.request, "Requested dimensions, metrics, filters or scope changed.");
+    requireSame(
+      a.semantics,
+      b.semantics,
+      "Provider aggregation, metric types, currency or reporting timezone changed.",
+    );
+    const durationA = Date.parse(a.end) - Date.parse(a.start);
+    const durationB = Date.parse(b.end) - Date.parse(b.start);
+    if (durationA !== durationB || a.end >= b.start)
+      throw new Incompatible("Periods must have equal duration, with baseline ending before current starts.");
+    const common = [...a.rows.keys()].filter((key) => b.rows.has(key)).sort();
+    const onlyBaseline = [...a.rows.keys()].filter((key) => !b.rows.has(key)).sort();
+    const onlyCurrent = [...b.rows.keys()].filter((key) => !a.rows.has(key)).sort();
+    const limitations = [...new Set([...a.warnings, ...b.warnings])];
+    const rows = common.slice(0, maxRows).map((key) => {
+      const before = a.rows.get(key)!;
+      const after = b.rows.get(key)!;
+      return {
+        keys: before.keys,
+        metrics: Object.fromEntries(
+          a.metrics.map((name, index) => [name, metric(before.values[index], after.values[index])]),
+        ),
+      };
+    });
+    if (rows.some((row) => Object.values(row.metrics).some((m) => m.delta === null)))
+      limitations.push("Some numeric values could not be compared safely.");
+    return {
+      name,
+      status: limitations.length || common.length > maxRows ? "limited" : "compared",
+      baselinePeriod: { startDate: a.start, endDate: a.end },
+      currentPeriod: { startDate: b.start, endDate: b.end },
+      dimensions: a.dimensions,
+      rows,
+      commonRowCount: common.length,
+      omittedCommonRows: Math.max(0, common.length - maxRows),
+      rowScope: "observed-keys",
+      baselineOnlyObserved: {
+        count: onlyBaseline.length,
+        keys: onlyBaseline.slice(0, maxRows).map((key) => a.rows.get(key)!.keys),
+      },
+      currentOnlyObserved: {
+        count: onlyCurrent.length,
+        keys: onlyCurrent.slice(0, maxRows).map((key) => b.rows.get(key)!.keys),
+      },
+      warnings: [
+        ...warnings,
+        ...limitations,
+        "Only common observed rows have deltas. Missing rows are unknown; row sums are not exhaustive site totals. Position and CTR deltas retain their provider units.",
+      ],
+    };
+  } catch (error) {
+    return {
+      name,
+      status: "incompatible",
+      reason:
+        error instanceof Incompatible
+          ? error.message
+          : "Report request or response does not match the supported schema.",
+      warnings,
+    };
+  }
+}
+
+export function compareSnapshots(baseline: ImportedSnapshot, current: ImportedSnapshot, maxRows: number) {
+  if (baseline.target !== current.target)
+    throw new RequestError("Snapshots must identify the same site", null, "invalid_input");
+  const before = baseline.pages[0].response.observations;
+  const after = current.pages[0].response.observations;
+  const names = [...new Set([...before, ...after].map((o) => o.name))].sort();
+  const source = (snapshot: ImportedSnapshot) => ({
+    target: snapshot.target,
+    startedAt: snapshot.startedAt,
+    finishedAt: snapshot.finishedAt,
+    canonicalSha256: Bun.CryptoHasher.hash("sha256", canonical(snapshot), "hex"),
+  });
+  return capture(
+    "pagesight",
+    "compare",
+    baseline.target,
+    { baseline: source(baseline), current: source(current), maxRows },
+    async () => {
+      const observations = names.map((name) =>
+        compareObservation(
+          before.find((o) => o.name === name),
+          after.find((o) => o.name === name),
+          maxRows,
+          baseline.pages[0].response.context,
+          current.pages[0].response.context,
+        ),
+      );
+      return {
+        comparisonVersion: 1,
+        observations,
+        summary: Object.fromEntries(
+          ["compared", "limited", "incompatible", "unavailable", "unsupported"].map((status) => [
+            status,
+            observations.filter((o) => o.status === status).length,
+          ]),
+        ),
+      };
+    },
+    [
+      "Descriptive changes only; no causal attribution, ranking recommendations or automatic SEO changes.",
+      ...new Set([...baseline.warnings, ...current.warnings]),
+    ],
+  );
+}

package/src/api/discover.ts

@@ -0,0 +1,39 @@
+import { configSchema } from "./schema.js";
+import { aggregate } from "./evidence.js";
+import type { Executor } from "./execute.js";
+
+export async function discover(url: string, providers: Array<"gsc" | "ga" | "bing">, run: Executor) {
+  const selected = [...new Set(providers)];
+  const observations = await Promise.all(
+    selected.map((provider) => run({ operation: provider === "ga" ? "ga.accounts" : `${provider}.sites` })),
+  );
+  const result = aggregate("discover", url, { url, providers: selected }, observations);
+  const gsc = observations.find((o) => o.provider === "gsc");
+  const bing = observations.find((o) => o.provider === "bing");
+  const bingSites = (bing?.pages[0]?.response as { d?: unknown[] } | undefined)?.d;
+  const ga = observations.find((o) => o.provider === "ga");
+  const sites = (gsc?.pages[0]?.response as { siteEntry?: unknown[] } | undefined)?.siteEntry;
+  const accounts = ga?.pages[0]?.response as
+    | { accountSummaries?: Array<{ propertySummaries?: unknown[] }> }
+    | undefined;
+  Object.assign(result.pages[0].response as object, {
+    config: configSchema.parse({ site: url }),
+    candidates: {
+      bing: bingSites ?? [],
+      gsc: Array.isArray(sites) ? sites : [],
+      ga: accounts?.accountSummaries?.flatMap((a) => a.propertySummaries ?? []) ?? [],
+    },
+    providers: Object.fromEntries(
+      ["gsc", "ga", "bing"].map((p) => [
+        p,
+        selected.includes(p as "gsc" | "ga" | "bing") ? "selected" : "not_selected",
+      ]),
+    ),
+  });
+  result.warnings.push(
+    "No provider property is automatically selected. Copy a verified site/property ID into config before collecting its reports.",
+    "GA display names do not establish a property's hostname. Candidates can belong to other sites; verify the property and web stream.",
+    "The returned config is usable for a site-only snapshot. Sitemap, objective and provider IDs must be supplied explicitly.",
+  );
+  return result;
+}

package/src/api/doctor.ts

@@ -0,0 +1,35 @@
+import { getAuthMethod } from "../providers/gsc-auth.js";
+import { getSite } from "../providers/gsc.js";
+import { defaultDates } from "../shared/dates.js";
+import { aggregate, capture, type Evidence } from "./evidence.js";
+import type { Executor } from "./execute.js";
+import type { SiteConfig } from "./schema.js";
+import { providerSelection } from "./snapshot.js";
+
+export async function doctor(config: SiteConfig, run: Executor): Promise<Evidence> {
+  const pending: Promise<Evidence>[] = [run({ operation: "page", url: config.site })];
+  const site = config.gscSite;
+  const property = config.gaProperty;
+  if (config.bingSite) pending.push(run({ operation: "bing.traffic", site: config.bingSite }));
+  if (site) pending.push(capture("gsc", "access", site, { site, method: getAuthMethod() }, () => getSite(site)));
+  if (property)
+    pending.push(
+      run({ operation: "ga.property", property }),
+      run({
+        operation: "ga.report",
+        property,
+        request: {
+          dateRanges: [{ startDate: defaultDates().endDate, endDate: defaultDates().endDate }],
+          metrics: [{ name: "sessions" }],
+          limit: 1,
+        },
+      }),
+    );
+  const result = aggregate("doctor", config.site, config, await Promise.all(pending));
+  (result.pages[0].response as Record<string, unknown>).providers = {
+    ...providerSelection(config),
+    web: "selected",
+    sitemap: "not_checked",
+  };
+  return result;
+}

package/src/api/evidence-schema.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { dateSchema } from "../shared/dates.js";
+
+export const evidenceSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    provider: z.string().min(1),
+    operation: z.string().min(1),
+    name: z.string().min(1).optional(),
+    target: z.string().min(1),
+    startedAt: z.string().datetime(),
+    finishedAt: z.string().datetime(),
+    status: z.enum(["ok", "partial", "error"]),
+    pages: z.array(
+      z
+        .object({ request: z.unknown(), response: z.unknown() })
+        .passthrough()
+        .refine(
+          (p) => Object.hasOwn(p, "request") && Object.hasOwn(p, "response"),
+          "Evidence pages require a request and response",
+        )
+        .transform((p) => ({ ...p, request: p.request, response: p.response })),
+    ),
+    pagination: z
+      .object({
+        exhausted: z.boolean(),
+        nextOffset: z.number().int().nonnegative().nullable(),
+        rowsReturned: z.number().int().nonnegative(),
+      })
+      .optional(),
+    warnings: z.array(z.string()),
+    error: z
+      .object({
+        code: z.string(),
+        message: z.string(),
+        httpStatus: z.number().int().nullable(),
+        name: z.string().optional(),
+      })
+      .optional(),
+  })
+  .passthrough();
+
+export const snapshotEvidenceSchema = evidenceSchema
+  .extend({
+    provider: z.literal("pagesight"),
+    operation: z.literal("snapshot"),
+    pages: z.tuple([
+      z
+        .object({
+          request: z.unknown(),
+          response: z
+            .object({
+              snapshotVersion: z.literal(1),
+              context: z
+                .object({
+                  config: z.object({ site: z.string().url() }).passthrough(),
+                  requestedDates: z.object({ startDate: dateSchema, endDate: dateSchema }).passthrough(),
+                  observedGscDates: z.array(dateSchema),
+                })
+                .passthrough(),
+              observations: z
+                .array(evidenceSchema.extend({ name: z.string().min(1) }))
+                .min(1)
+                .max(100),
+            })
+            .passthrough(),
+        })
+        .passthrough(),
+    ]),
+  })
+  .refine((s) => s.target === s.pages[0].response.context.config.site, "Snapshot target must match its configured site")
+  .refine(
+    (s) =>
+      new Set(s.pages[0].response.observations.map((o) => o.name)).size === s.pages[0].response.observations.length,
+    "Snapshot observation names must be unique",
+  );
+
+export type ImportedSnapshot = z.infer<typeof snapshotEvidenceSchema>;

package/src/api/evidence.ts

@@ -0,0 +1,99 @@
+import { RequestError } from "../shared/http.js";
+
+export interface Evidence {
+  schemaVersion: 1;
+  provider: string;
+  operation: string;
+  name?: string;
+  target: string;
+  startedAt: string;
+  finishedAt: string;
+  status: "ok" | "partial" | "error";
+  pages: Array<{ request: unknown; response: unknown }>;
+  pagination?: { exhausted: boolean; nextOffset: number | null; rowsReturned: number };
+  warnings: string[];
+  credential?: { source: string; type: string | null; clientEmail: string | null };
+  failedRequest?: unknown;
+  error?: { code: string; message: string; httpStatus: number | null; name?: string };
+}
+
+export function createEvidence(provider: string, operation: string, target: string): Evidence {
+  return {
+    schemaVersion: 1,
+    provider,
+    operation,
+    target,
+    startedAt: new Date().toISOString(),
+    finishedAt: "",
+    status: "ok",
+    pages: [],
+    warnings: [],
+  };
+}
+
+export function fail(result: Evidence, error: unknown): void {
+  result.status = result.pages.length ? "partial" : "error";
+  result.error =
+    error instanceof RequestError
+      ? { code: error.code, message: error.message, httpStatus: error.status }
+      : {
+          code: "operation_failed",
+          message: "Operation failed; check credentials, request and provider availability",
+          httpStatus: null,
+          name: error instanceof Error ? error.name : "UnknownError",
+        };
+}
+
+export async function capture(
+  provider: string,
+  operation: string,
+  target: string,
+  request: unknown,
+  run: () => Promise<unknown>,
+  warnings: string[] = [],
+): Promise<Evidence> {
+  const result = createEvidence(provider, operation, target);
+  result.warnings.push(...warnings);
+  try {
+    result.pages.push({ request, response: await run() });
+  } catch (error) {
+    result.failedRequest = request;
+    fail(result, error);
+  }
+  result.finishedAt = new Date().toISOString();
+  return result;
+}
+
+export function aggregate(operation: string, target: string, request: unknown, observations: Evidence[]): Evidence {
+  if (!observations.length) throw new RequestError("Select at least one observation", null, "invalid_input");
+  return {
+    schemaVersion: 1,
+    provider: "pagesight",
+    operation,
+    target,
+    startedAt: observations.map((o) => o.startedAt).sort()[0] ?? new Date().toISOString(),
+    finishedAt: new Date().toISOString(),
+    status: observations.every((o) => o.status === "ok")
+      ? "ok"
+      : observations.every((o) => o.status === "error")
+        ? "error"
+        : "partial",
+    pages: [
+      {
+        request,
+        response: {
+          observations,
+          summary: observations.map((o) => ({
+            provider: o.provider,
+            operation: o.operation,
+            ...(o.name ? { name: o.name } : {}),
+            target: o.target,
+            status: o.status,
+            errorCode: o.error?.code ?? null,
+          })),
+        },
+      },
+    ],
+    warnings: [],
+  };
+}

package/src/api/execute.ts

@@ -0,0 +1,160 @@
+import { assessSnapshot } from "./assessment.js";
+import { opportunities } from "./opportunities.js";
+import { gaRealtime } from "./ga-realtime.js";
+import { importUiFindings } from "./ui-findings.js";
+import { doctor } from "./doctor.js";
+import { ZodError } from "zod";
+import { queryCrux, queryCruxHistory } from "../providers/crux.js";
+import { gaCredentialInfo, gaFetch, normalizeGaProperty } from "../providers/ga.js";
+import { inspectUrlResponse, listSitemapsResponse, listSitesResponse } from "../providers/gsc.js";
+import { RequestError } from "../shared/http.js";
+import { runPagespeed } from "../providers/pagespeed.js";
+import { bingDiagnostics, bingObservation } from "./bing.js";
+import { compareSnapshots } from "./compare-snapshots.js";
+import { capture, type Evidence } from "./evidence.js";
+import { gaReport, gscReport } from "./reports.js";
+import { operationSchema } from "./schema.js";
+import { discover } from "./discover.js";
+import { snapshot } from "./snapshot.js";
+import { observePage } from "../web/page-observation.js";
+
+export type Executor = (input: unknown) => Promise<Evidence>;
+type ParsedOperation = ReturnType<typeof operationSchema.parse>;
+
+export async function execute(input: unknown): Promise<Evidence> {
+  let op: ParsedOperation;
+  try {
+    op = operationSchema.parse(input);
+  } catch (error) {
+    throw new RequestError(
+      error instanceof ZodError
+        ? error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+        : "Invalid operation",
+      null,
+      "invalid_input",
+    );
+  }
+  const result = await dispatch(op);
+  if (op.operation.startsWith("ga.")) result.credential = await gaCredentialInfo();
+  if (op.operation.startsWith("bing."))
+    result.credential = { source: "BING_WEBMASTER_API_KEY", type: "api_key", clientEmail: null };
+  const response = result.pages[0]?.response as { nextPageToken?: string } | undefined;
+  if (response?.nextPageToken) {
+    result.status = "partial";
+    result.warnings.push("More metadata pages are available; nextPageToken is preserved in the response.");
+  }
+  return result;
+}
+
+async function dispatch(op: ParsedOperation): Promise<Evidence> {
+  switch (op.operation) {
+    case "opportunities":
+      return opportunities(op.snapshot, {
+        minImpressions: op.minImpressions,
+        maxClicks: op.maxClicks,
+        maxRows: op.maxRows,
+      });
+    case "assess":
+      return assessSnapshot(op.snapshot, op.maxRows);
+    case "evidence.import":
+      return importUiFindings(op.document);
+    case "compare":
+      return compareSnapshots(op.baseline, op.current, op.maxRows);
+    case "discover":
+      return discover(op.url, op.providers, execute);
+    case "bing.crawl-stats":
+    case "bing.crawl-issues":
+      return bingDiagnostics(op.operation === "bing.crawl-stats" ? "crawl-stats" : "crawl-issues", op.site);
+    case "bing.url-info":
+      return bingDiagnostics("url-info", op.site, op.url);
+    case "bing.link-counts":
+      return bingDiagnostics("link-counts", op.site, undefined, op.maxPages);
+    case "bing.url-links":
+      return bingDiagnostics("url-links", op.site, op.url, op.maxPages);
+    case "bing.sites":
+      return bingObservation("sites");
+    case "bing.queries":
+      return bingObservation("queries", op.site);
+    case "bing.pages":
+      return bingObservation("pages", op.site);
+    case "bing.traffic":
+      return bingObservation("traffic", op.site);
+    case "gsc.sites":
+      return capture("gsc", "sites", "accessible-properties", {}, listSitesResponse);
+    case "gsc.sitemaps":
+      return capture("gsc", "sitemaps", op.site, { site: op.site }, () => listSitemapsResponse(op.site), [
+        "contents[].indexed is deprecated and must not be interpreted.",
+      ]);
+    case "gsc.inspect":
+      return capture(
+        "gsc",
+        "inspect",
+        op.site,
+        { inspectionUrl: op.url, siteUrl: op.site },
+        () => inspectUrlResponse(op.url, op.site),
+        ["Inspection describes Google's indexed state, not a live fetch. This is one URL, not site coverage."],
+      );
+    case "gsc.report":
+      return gscReport(op.site, op.request, op.maxPages);
+    case "ga.accounts":
+      return capture(
+        "ga",
+        "accounts",
+        "accessible-properties",
+        { pageSize: 200 },
+        () => gaFetch("accountSummaries?pageSize=200", undefined, true),
+        ["If nextPageToken is present, this discovery response is incomplete."],
+      );
+    case "ga.property":
+      return capture("ga", "property", normalizeGaProperty(op.property), {}, () =>
+        gaFetch(normalizeGaProperty(op.property), undefined, true),
+      );
+    case "ga.key-events":
+      return capture(
+        "ga",
+        "key-events",
+        normalizeGaProperty(op.property),
+        { pageSize: 200 },
+        () => gaFetch(`${normalizeGaProperty(op.property)}/keyEvents?pageSize=200`, undefined, true),
+        [
+          "Configured key events are not necessarily validated product outcomes; inspect event names. Check nextPageToken.",
+        ],
+      );
+    case "ga.realtime":
+      return gaRealtime(op.property, op.request);
+    case "ga.report":
+      return gaReport(op.property, op.request, op.maxPages);
+    case "page":
+      return capture("web", "page", op.url, { url: op.url }, () => observePage(op.url));
+    case "speed.psi":
+      return capture(
+        "psi",
+        "run",
+        op.url,
+        { url: op.url, strategy: op.strategy, categories: ["performance", "seo"] },
+        () => runPagespeed(op.url, { strategy: op.strategy, categories: ["performance", "seo"] }),
+        ["Single Lighthouse lab run; not field performance or ranking evidence."],
+      );
+    case "speed.crux":
+    case "speed.history": {
+      const request = {
+        ...(op.origin ? { origin: new URL(op.url).origin } : { url: op.url }),
+        formFactor: op.formFactor,
+      };
+      return capture(
+        "crux",
+        op.operation,
+        op.url,
+        request,
+        () => (op.operation === "speed.crux" ? queryCrux(request) : queryCruxHistory(request)),
+        [
+          "NOT_FOUND means no record for the requested scope, not zero performance. CrUX aggregates 28-day windows; history periods overlap.",
+        ],
+      );
+    }
+    case "doctor":
+      return doctor(op.config, execute);
+    case "snapshot":
+      return snapshot(op, execute);
+  }
+}

package/src/api/ga-freshness.ts

@@ -0,0 +1,20 @@
+export function gaFreshnessWarnings(endDates: string[], timeZone: unknown, collectedAt: string): string[] {
+  if (typeof timeZone !== "string" || !timeZone)
+    return ["GA property timezone is unavailable; report freshness could not be assessed."];
+  let collectedDate: string;
+  try {
+    collectedDate = new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(new Date(collectedAt));
+  } catch {
+    return ["GA property timezone or collection time is invalid; report freshness could not be assessed."];
+  }
+  return endDates.some((end) => Date.parse(collectedDate) - Date.parse(end) < 3 * 86400000)
+    ? [
+        "GA was collected fewer than three property-calendar days after the requested end date; recent data may still change. This precaution is not a finalization guarantee for older data.",
+      ]
+    : [];
+}

package/src/api/ga-realtime.ts

@@ -0,0 +1,40 @@
+import { gaFetch, normalizeGaProperty, type GaReport } from "../providers/ga.js";
+import { RequestError } from "../shared/http.js";
+import { createEvidence, fail, type Evidence } from "./evidence.js";
+import type { GaRealtimeRequest } from "./schema.js";
+
+export async function gaRealtime(
+  property: string,
+  request: GaRealtimeRequest,
+  query = (r: GaRealtimeRequest) => gaFetch<GaReport>(`${normalizeGaProperty(property)}:runRealtimeReport`, r),
+): Promise<Evidence> {
+  const result = createEvidence("ga", "realtime", normalizeGaProperty(property));
+  result.warnings.push(
+    "Realtime is a moving window of reported property activity, not a historical or finalized report. Requested filters determine scope; no production hostname filter is added.",
+    "Activity does not identify a particular browser test or prove event counts are correct. Empty rows do not prove collection failed.",
+    "Realtime dimensions and metrics differ from standard reports. Windows beyond 29 minutes ago require Analytics 360; overlapping ranges count overlapping events in both ranges.",
+  );
+  try {
+    const response = await query(request);
+    result.pages.push({ request, response });
+    if (response.rows !== undefined && !Array.isArray(response.rows))
+      throw new RequestError("Invalid realtime rows", null, "invalid_response");
+    const count = response.rows?.length ?? 0;
+    const total = response.rowCount ?? (count === 0 && Array.isArray(response.metricHeaders) ? 0 : undefined);
+    if (!Number.isSafeInteger(total) || Number(total) < count)
+      throw new RequestError("Invalid realtime rowCount", null, "invalid_response");
+    const exhausted = total === count;
+    result.pagination = { exhausted, nextOffset: null, rowsReturned: count };
+    if (!exhausted) {
+      result.status = "partial";
+      result.warnings.push(
+        "Realtime rows were truncated. The API has no offset or page token; narrow dimensions or raise the limit. Missing rows are unknown, not zero.",
+      );
+    }
+  } catch (error) {
+    result.failedRequest = request;
+    fail(result, error);
+  }
+  result.finishedAt = new Date().toISOString();
+  return result;
+}

package/src/api/index.ts

@@ -0,0 +1,5 @@
+export { execute } from "./execute.js";
+export type { Evidence } from "./evidence.js";
+export { configSchema, type Operation, operationSchema } from "./schema.js";
+export { evidenceSchema, snapshotEvidenceSchema } from "./evidence-schema.js";
+export { RequestError } from "../shared/http.js";