pagesight 0.16.0 → 0.18.0

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;
+}

package/src/api/compare-snapshots.ts

@@ -0,0 +1,377 @@
+import { z } from "zod";
+import { RequestError } from "../shared/http.js";
+import { capture, type Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { gaRequestSchema, gscRequestSchema } from "./schema.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",
+]);
+
+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[];
+};
+class Incompatible extends Error {}
+const requireSame = (a: unknown, b: unknown, message: string) => {
+  if (canonical(a) !== canonical(b)) throw new Incompatible(message);
+};
+
+type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
+
+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.");
+      const collectedDate = new Intl.DateTimeFormat("en-CA", {
+        timeZone: response.metadata.timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(new Date(observation.finishedAt));
+      if (Date.parse(collectedDate) - Date.parse(current.end) < 3 * 86400000)
+        current.warnings.push(
+          "GA was collected fewer than three property-calendar days after the requested end date; recent data may still change.",
+        );
+      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.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;
+}
+
+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;
+}
+
+function metric(baseline: RawValue, current: RawValue) {
+  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 };
+}
+
+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>;