ssrwire 0.1.0

package/src/types.ts

@@ -0,0 +1,160 @@
+export type Severity = "info" | "warning" | "error";
+
+export type ElementLocation = "head" | "body" | "document";
+
+export interface TimingMark {
+  readonly atMs: number;
+  readonly observedByByte: number;
+}
+
+export interface ElementSignal extends TimingMark {
+  readonly value: string;
+  readonly location: ElementLocation;
+}
+
+export type RobotsAudience = "robots" | "googlebot" | "bingbot";
+
+export interface RobotsSignal extends ElementSignal {
+  readonly audience: RobotsAudience;
+}
+
+export interface JsonLdSignal extends TimingMark {
+  readonly location: ElementLocation;
+  readonly valid?: boolean;
+  readonly types: readonly string[];
+  readonly bytes: number;
+  readonly analysisLimit?: string;
+  readonly error?: string;
+}
+
+export interface DocumentSignals {
+  readonly title?: ElementSignal;
+  readonly titles?: readonly ElementSignal[];
+  readonly descriptions: readonly ElementSignal[];
+  readonly canonicals: readonly ElementSignal[];
+  readonly robots: readonly RobotsSignal[];
+  readonly h1s: readonly ElementSignal[];
+  readonly firstMainText?: ElementSignal;
+  readonly jsonLd: readonly JsonLdSignal[];
+  readonly headClosed?: TimingMark;
+  readonly bodyStarted?: TimingMark;
+  readonly documentClosed?: TimingMark;
+}
+
+export interface AgentProfile {
+  readonly key: string;
+  readonly label: string;
+  readonly userAgent: string;
+  readonly requiresHeadMetadata: boolean;
+}
+
+export interface RedirectHop {
+  readonly url: string;
+  readonly status: number;
+  readonly location: string;
+  readonly durationMs: number;
+}
+
+export interface HeaderSnapshot {
+  readonly values: Readonly<Record<string, string>>;
+  readonly setCookiePresent: boolean;
+}
+
+export interface ProbeTimings {
+  readonly headersMs: number;
+  readonly firstByteMs?: number;
+  readonly completeMs?: number;
+}
+
+export type ProbeCompletion =
+  | "complete"
+  | "max-bytes-exceeded"
+  | "timeout"
+  | "network-error"
+  | "invalid-response";
+
+export interface ProbeOptions {
+  readonly url: string;
+  readonly agent: AgentProfile;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly timeoutMs: number;
+  readonly maxBytes: number;
+  readonly maxRedirects: number;
+  /** Keep reflected header values internal so callers can analyze raw evidence before redaction. */
+  readonly redactHeaderValues?: boolean;
+}
+
+export interface ProbeResult {
+  readonly requestedUrl: string;
+  readonly finalUrl: string;
+  readonly agent: AgentProfile;
+  readonly status?: number;
+  readonly redirects: readonly RedirectHop[];
+  readonly headers: HeaderSnapshot;
+  readonly timings: ProbeTimings;
+  readonly bytesRead: number;
+  readonly bodySha256?: string;
+  readonly signals: DocumentSignals;
+  readonly completion: ProbeCompletion;
+  readonly error?: string;
+}
+
+export interface TargetExpectations {
+  readonly statuses: readonly number[];
+  readonly finalUrl?: string;
+  readonly requireTitle: boolean;
+  readonly requireDescription: boolean;
+  readonly requireCanonical: boolean;
+  readonly requireH1: boolean;
+  readonly requireMainText: boolean;
+  readonly maxFirstByteMs?: number;
+  readonly maxCriticalMs?: number;
+}
+
+export interface AuditTarget {
+  readonly url: string;
+  readonly expectations: TargetExpectations;
+}
+
+export interface SsrWireConfig {
+  readonly targets: readonly AuditTarget[];
+  readonly agents: readonly AgentProfile[];
+  readonly headers: Readonly<Record<string, string>>;
+  readonly timeoutMs: number;
+  readonly maxBytes: number;
+  readonly maxRedirects: number;
+}
+
+export interface Finding {
+  readonly code: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly url: string;
+  readonly agent?: string;
+  readonly evidence?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface TargetAuditResult {
+  readonly target: AuditTarget;
+  readonly probes: readonly ProbeResult[];
+  readonly findings: readonly Finding[];
+}
+
+export interface AuditSummary {
+  readonly targets: number;
+  readonly probes: number;
+  readonly errors: number;
+  readonly warnings: number;
+  readonly info: number;
+  readonly incomplete: number;
+}
+
+export interface AuditResult {
+  readonly version: string;
+  readonly generatedAt: string;
+  readonly durationMs: number;
+  readonly results: readonly TargetAuditResult[];
+  readonly summary: AuditSummary;
+}
+
+export type ReportFormat = "terminal" | "json" | "sarif";

package/src/version.ts

@@ -0,0 +1,19 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const packageJson: unknown = require("../package.json");
+
+function readVersion(value: unknown): string {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "version" in value &&
+    typeof value.version === "string"
+  ) {
+    return value.version;
+  }
+
+  throw new Error("SSRWire could not read its package version.");
+}
+
+export const VERSION = readVersion(packageJson);