@testrelic/core 2.4.10 → 2.4.11-next.9

package/dist/index.d.cts

@@ -0,0 +1,777 @@
+/**
+ * @testrelic/core — Shared type definitions
+ *
+ * All interfaces for the JSON output schema, reporter configuration,
+ * and internal fixture-to-reporter communication.
+ *
+ * Schema Version: 1.0.0
+ */
+type NavigationType = 'goto' | 'navigation' | 'back' | 'forward' | 'refresh' | 'spa_route' | 'spa_replace' | 'hash_change' | 'link_click' | 'form_submit' | 'redirect' | 'popstate' | 'page_load' | 'manual_record' | 'fallback' | 'dummy';
+interface TestRunReport {
+    readonly schemaVersion: string;
+    readonly testRunId: string;
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly totalDuration: number;
+    readonly summary: Summary;
+    readonly ci: CIMetadata | null;
+    readonly metadata: Record<string, unknown> | null;
+    readonly timeline: readonly (TimelineEntry | TimelineStep)[];
+    readonly shardRunIds: string[] | null;
+}
+/** Breakdown of API calls by HTTP response status range. */
+interface ApiCallsByStatusRange {
+    readonly '2xx': number;
+    readonly '3xx': number;
+    readonly '4xx': number;
+    readonly '5xx': number;
+    readonly error: number;
+}
+/** Statistical distribution of API call response times in milliseconds. */
+interface ApiResponseTimeStats {
+    readonly avg: number;
+    readonly min: number;
+    readonly max: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly p99: number;
+}
+interface Summary {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly flaky: number;
+    readonly skipped: number;
+    readonly timedout: number;
+    readonly totalApiCalls: number;
+    readonly uniqueApiUrls: number;
+    readonly apiCallsByMethod: Record<string, number>;
+    readonly apiCallsByStatusRange: ApiCallsByStatusRange;
+    readonly apiResponseTime: ApiResponseTimeStats | null;
+    readonly totalAssertions: number;
+    readonly passedAssertions: number;
+    readonly failedAssertions: number;
+    readonly totalNavigations: number;
+    readonly uniqueNavigationUrls: number;
+    readonly totalTimelineSteps: number;
+    readonly totalActionSteps: number;
+    readonly actionStepsByCategory: Record<string, number>;
+}
+interface CIMetadata {
+    readonly provider: CIProvider;
+    readonly buildId: string | null;
+    readonly commitSha: string | null;
+    readonly branch: string | null;
+    readonly runUrl: string | null;
+}
+type CIProvider = 'github-actions' | 'gitlab-ci' | 'jenkins' | 'circleci' | 'bitbucket-pipelines' | 'unknown';
+interface TimelineEntry {
+    readonly url: string;
+    readonly navigationType: NavigationType;
+    readonly visitedAt: string;
+    readonly duration: number;
+    readonly specFile: string;
+    readonly domContentLoadedAt: string | null;
+    readonly networkIdleAt: string | null;
+    readonly networkStats: NetworkStats | null;
+    readonly tests: TestResult[];
+}
+interface TestResult {
+    readonly title: string;
+    readonly status: TestStatus;
+    readonly duration: number;
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly retryCount: number;
+    readonly tags: string[];
+    readonly failure: FailureDiagnostic | null;
+    readonly testId: string;
+    readonly filePath: string;
+    readonly suiteName: string;
+    readonly testType: TestType;
+    readonly isFlaky: boolean;
+    readonly retryStatus: string | null;
+    readonly expectedStatus: TestStatus;
+    readonly actualStatus: TestStatus;
+    readonly artifacts: TestArtifacts | null;
+    readonly networkRequests: CapturedNetworkRequest[] | null;
+    readonly apiCalls: readonly ApiCallRecord[] | null;
+    readonly apiAssertions: readonly ApiAssertion[] | null;
+    readonly actions: readonly ActionStep[] | null;
+    readonly consoleLogs: readonly ConsoleLogEntry[] | null;
+}
+type ResourceType = 'xhr' | 'document' | 'script' | 'stylesheet' | 'image' | 'font' | 'other';
+interface CapturedNetworkRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly resourceType: ResourceType;
+    readonly statusCode: number;
+    readonly responseTimeMs: number;
+    readonly startedAt: string;
+    readonly requestHeaders: Record<string, string> | null;
+    readonly requestBody: string | null;
+    readonly responseBody: string | null;
+    readonly responseHeaders: Record<string, string> | null;
+    readonly contentType: string | null;
+    readonly responseSize: number;
+    readonly requestBodyTruncated: boolean;
+    readonly responseBodyTruncated: boolean;
+    readonly isBinary: boolean;
+    readonly error: string | null;
+}
+interface TestArtifacts {
+    readonly screenshot?: string;
+    readonly video?: string;
+    readonly screenshotKey?: string;
+    readonly videoKey?: string;
+}
+type TestStatus = 'passed' | 'failed' | 'skipped' | 'flaky' | 'timedout';
+type TestType = 'e2e' | 'api' | 'unit' | 'mobile' | 'unknown';
+interface FailureDiagnostic {
+    readonly message: string;
+    readonly line: number | null;
+    readonly code: string | null;
+    readonly stack: string | null;
+}
+interface NetworkStats {
+    readonly totalRequests: number;
+    readonly failedRequests: number;
+    readonly failedRequestUrls: string[];
+    readonly totalBytes: number;
+    readonly byType: ResourceBreakdown;
+}
+interface ResourceBreakdown {
+    readonly xhr: number;
+    readonly document: number;
+    readonly script: number;
+    readonly stylesheet: number;
+    readonly image: number;
+    readonly font: number;
+    readonly other: number;
+}
+interface ApiCallRecord {
+    /** Unique call identifier within the test (e.g., "api-call-0") */
+    readonly id: string;
+    /** ISO 8601 timestamp when the call was initiated */
+    readonly timestamp: string;
+    /** HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, or custom via fetch() */
+    readonly method: string;
+    /** Full resolved URL (after baseURL resolution by Playwright) */
+    readonly url: string;
+    /** All request headers sent, or null if unavailable */
+    readonly requestHeaders: Record<string, string> | null;
+    /** Request payload as string (JSON-serialized for objects). Null for bodiless methods */
+    readonly requestBody: string | null;
+    /** HTTP response status code, or null if request errored before response */
+    readonly responseStatusCode: number | null;
+    /** HTTP response status text, or null if request errored before response */
+    readonly responseStatusText: string | null;
+    /** All response headers received, or null if request errored before response */
+    readonly responseHeaders: Record<string, string> | null;
+    /** Response body: string for text/JSON, base64 for binary. Null on error */
+    readonly responseBody: string | null;
+    /** Duration in milliseconds from request initiation to response received */
+    readonly responseTimeMs: number;
+    /** Whether the response body is stored as a base64-encoded binary string */
+    readonly isBinary: boolean;
+    /** Error message if the call failed (network error, timeout), null on success */
+    readonly error: string | null;
+}
+/** Categorization of the assertion being made. */
+type AssertionType = 'status' | 'statusOk' | 'header' | 'bodyField' | 'bodyMatch' | 'bodyContains' | 'custom';
+/** Source location where an assertion was made in the test file. */
+interface AssertionLocation {
+    /** Absolute or relative file path to the test file */
+    readonly file: string;
+    /** Line number (1-based) */
+    readonly line: number;
+    /** Column number (1-based), if available */
+    readonly column?: number;
+}
+/** A single captured assertion on API response data. */
+interface ApiAssertion {
+    /** Links to ApiCallRecord.id from the API proxy */
+    readonly callId: string;
+    /** Category of assertion */
+    readonly type: AssertionType;
+    /** What the test expected */
+    readonly expected: unknown;
+    /** What was actually received */
+    readonly actual: unknown;
+    /** Whether the assertion passed or failed */
+    readonly status: 'passed' | 'failed';
+    /** Source location of the assertion in the test file */
+    readonly location: AssertionLocation;
+    /** String representation of the assertion expression (best-effort) */
+    readonly expression?: string;
+}
+/** Test identity block attached to every timeline step. */
+interface StepTestIdentity {
+    readonly title: string;
+    readonly fullTitle: readonly string[];
+    readonly status: TestStatus;
+    readonly duration: number;
+    readonly retries: number;
+    readonly retry: number;
+    readonly tags: readonly string[];
+    readonly failure: FailureDiagnostic | null;
+}
+/** Request details within an API call step. */
+interface ApiCallStepRequest {
+    readonly headers: Record<string, string> | null;
+    readonly body: unknown;
+}
+/** Response details within an API call step. */
+interface ApiCallStepResponse {
+    readonly statusCode: number;
+    readonly statusText: string;
+    readonly headers: Record<string, string> | null;
+    readonly body: unknown;
+}
+/** An assertion linked to an API call step (callId omitted — implicit from parent). */
+interface StepAssertion {
+    readonly type: AssertionType;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    readonly status: 'passed' | 'failed';
+    readonly location: AssertionLocation;
+    readonly expression?: string;
+}
+/** A browser navigation event in the unified timeline. */
+interface NavigationStep {
+    readonly index: number;
+    readonly type: 'navigation';
+    readonly url: string;
+    readonly timestamp: string;
+    readonly durationOnUrl: number;
+    readonly navigationType: NavigationType;
+    readonly domContentLoadedAt: string | null;
+    readonly networkIdleAt: string | null;
+    readonly networkStats: NetworkStats | null;
+    readonly specFile: string;
+    readonly test: StepTestIdentity;
+}
+/** An API request event in the unified timeline. */
+interface ApiCallStep {
+    readonly index: number;
+    readonly type: 'api_call';
+    readonly callId: string;
+    readonly method: string;
+    readonly url: string;
+    readonly timestamp: string;
+    readonly responseTime: number | null;
+    readonly request: ApiCallStepRequest;
+    readonly response: ApiCallStepResponse | null;
+    readonly error?: string | null;
+    readonly assertions: readonly StepAssertion[];
+    readonly specFile: string;
+    readonly test: StepTestIdentity;
+}
+/** Discriminated union of all timeline step types. */
+type TimelineStep = NavigationStep | ApiCallStep;
+/** Categorized type of a captured test action. */
+type ActionCategory = 'ui_action' | 'assertion' | 'custom_step';
+/** A single captured test action step. */
+interface ActionStep {
+    readonly title: string;
+    readonly category: ActionCategory;
+    readonly timestamp: string;
+    readonly duration: number;
+    readonly videoOffset: number | null;
+    readonly status: 'passed' | 'failed';
+    readonly error: string | null;
+    readonly children: readonly ActionStep[];
+}
+/** Level of a captured console/terminal log message. */
+type ConsoleLogLevel = 'log' | 'warn' | 'error' | 'info' | 'debug' | 'stdout' | 'stderr';
+/** A single captured console or terminal log entry. */
+interface ConsoleLogEntry {
+    /** Log level or stream type */
+    readonly level: ConsoleLogLevel;
+    /** Text content of the log message */
+    readonly text: string;
+    /** ISO 8601 timestamp when the log was captured */
+    readonly timestamp: string;
+    /** Source file location (browser console only, best-effort) */
+    readonly location: string | null;
+}
+/** Report generation mode. */
+type ReportMode = 'streaming' | 'embedded' | 'auto';
+interface ReporterConfig {
+    readonly outputPath?: string;
+    readonly includeStackTrace?: boolean;
+    readonly includeCodeSnippets?: boolean;
+    readonly codeContextLines?: number;
+    readonly includeNetworkStats?: boolean;
+    readonly navigationTypes?: NavigationType[] | null;
+    readonly redactPatterns?: (string | RegExp)[];
+    readonly testRunId?: string | null;
+    readonly metadata?: Record<string, unknown> | null;
+    readonly openReport?: boolean;
+    readonly htmlReportPath?: string;
+    readonly includeArtifacts?: boolean;
+    /** When false, disables API call interception in the unified fixture. Default: true */
+    readonly trackApiCalls?: boolean;
+    /** When true, suppresses console summary output. Default: false */
+    readonly quiet?: boolean;
+    /** When true, captures Playwright test steps (actions). Default: true */
+    readonly includeActionSteps?: boolean;
+    /** Capture request headers for API calls. Default: true */
+    readonly captureRequestHeaders?: boolean;
+    /** Capture response headers for API calls. Default: true */
+    readonly captureResponseHeaders?: boolean;
+    /** Capture request body for API calls. Default: true */
+    readonly captureRequestBody?: boolean;
+    /** Capture response body for API calls. Default: true */
+    readonly captureResponseBody?: boolean;
+    /** Capture API assertions (both pass and fail). Default: true */
+    readonly captureAssertions?: boolean;
+    /**
+     * Header names whose values are replaced with "[REDACTED]".
+     * Case-insensitive matching. Default: ['authorization', 'cookie', 'set-cookie', 'x-api-key']
+     */
+    readonly redactHeaders?: string[];
+    /**
+     * Body field names whose values are replaced with "[REDACTED]" at any depth.
+     * Default: ['password', 'secret', 'token', 'apiKey', 'api_key']
+     */
+    readonly redactBodyFields?: string[];
+    /**
+     * Only track API calls matching these URL patterns.
+     * Default: undefined (track all)
+     */
+    readonly apiIncludeUrls?: (string | RegExp)[];
+    /**
+     * Exclude API calls matching these URL patterns. Takes precedence over include.
+     * Default: undefined (exclude none)
+     */
+    readonly apiExcludeUrls?: (string | RegExp)[];
+    /** Capture browser console logs (E2E) and terminal output (API). Default: true */
+    readonly captureConsoleLogs?: boolean;
+    /** Cloud integration configuration. Default: undefined (local mode) */
+    readonly cloud?: CloudReporterOptions;
+    /**
+     * Report generation mode.
+     * - `'embedded'`: All data embedded in a single HTML file (current behavior)
+     * - `'streaming'`: Data streamed to disk per-test, served via local server
+     * - `'auto'`: Use embedded for < streamingThreshold tests, streaming otherwise
+     * Default: `'auto'`
+     */
+    readonly reportMode?: ReportMode;
+    /**
+     * Test count threshold for auto mode. When the suite has >= this many tests,
+     * streaming mode is used. Default: 500
+     */
+    readonly streamingThreshold?: number;
+}
+interface NavigationAnnotation {
+    readonly url: string;
+    readonly navigationType: NavigationType;
+    readonly timestamp: string;
+    readonly domContentLoadedAt?: string;
+    readonly networkIdleAt?: string;
+    readonly networkStats?: NetworkStats;
+}
+/** Consolidated data payload sent from a worker fixture to the reporter. */
+interface TestRelicDataPayload {
+    /** Marker to identify TestRelic attachments. Always `true`. */
+    readonly testRelicData: true;
+    /** Payload format version (semver). */
+    readonly version: string;
+    /** Navigation events collected during the test. */
+    readonly navigations: readonly NavigationAnnotation[];
+    /** Captured network requests during the test. */
+    readonly networkRequests: readonly CapturedNetworkRequest[];
+    /** API calls made via APIRequestContext proxy. */
+    readonly apiCalls: readonly ApiCallRecord[];
+    /** Assertions captured on API responses. */
+    readonly apiAssertions: readonly ApiAssertion[];
+    /** Console/terminal logs captured during the test. Optional for backward compat. */
+    readonly consoleLogs?: readonly ConsoleLogEntry[];
+}
+/** Current payload format version. */
+declare const PAYLOAD_VERSION = "2.0.0";
+/** Legacy payload version (pre-streaming). */
+declare const PAYLOAD_VERSION_LEGACY = "1.0.0";
+/** Attachment name used for the consolidated payload. */
+declare const ATTACHMENT_NAME = "testrelic-data";
+/** Attachment content type. */
+declare const ATTACHMENT_CONTENT_TYPE = "application/json";
+/**
+ * File-based data payload (v2.0.0).
+ *
+ * Heavy data (network requests, console logs, API calls) is written to
+ * JSONL files on disk and referenced by path. Only lightweight data
+ * (navigations, assertions) is kept inline.
+ */
+interface TestRelicFilePayload {
+    /** Marker to identify TestRelic attachments. Always `true`. */
+    readonly testRelicData: true;
+    /** Payload format version — `"2.0.0"` for file-based payloads. */
+    readonly version: '2.0.0';
+    /** Navigation events (small, kept inline). */
+    readonly navigations: readonly NavigationAnnotation[];
+    /** API assertions (small, kept inline). */
+    readonly apiAssertions: readonly ApiAssertion[];
+    /** Absolute path to JSONL file containing CapturedNetworkRequest items. */
+    readonly networkRequestsFile: string | null;
+    /** Number of network request items in the file. */
+    readonly networkRequestsCount: number;
+    /** Absolute path to JSONL file containing ConsoleLogEntry items. */
+    readonly consoleLogsFile: string | null;
+    /** Number of console log items in the file. */
+    readonly consoleLogsCount: number;
+    /** Absolute path to JSONL file containing ApiCallRecord items. */
+    readonly apiCallsFile: string | null;
+    /** Number of API call items in the file. */
+    readonly apiCallsCount: number;
+}
+/** Type guard: validates that a parsed object is a v2 file-based payload. */
+declare function isTestRelicFilePayload(obj: unknown): obj is TestRelicFilePayload;
+/** Type guard: validates that a parsed object is a v1 inline data payload. */
+declare function isTestRelicDataPayload(obj: unknown): obj is TestRelicDataPayload;
+/** Upload strategy for cloud timeline data. */
+type UploadStrategy = 'batch' | 'realtime' | 'both';
+/** Current cloud/local operating mode. */
+type AuthMode = 'cloud' | 'local' | 'pending';
+/** Resolved cloud configuration, immutable after initialization. */
+interface CloudConfig {
+    readonly apiKey: string | null;
+    readonly endpoint: string;
+    readonly uploadStrategy: UploadStrategy;
+    readonly timeout: number;
+    readonly projectName: string | null;
+    readonly queueMaxAge: number;
+    readonly queueDirectory: string;
+    readonly uploadArtifacts: boolean;
+    readonly artifactMaxSizeMb: number;
+}
+/** Mutable auth state tracked by the cloud client. */
+interface AuthState {
+    mode: AuthMode;
+    accessToken: string | null;
+    refreshToken: string | null;
+    expiresAt: number | null;
+    orgId: string | null;
+    orgName: string | null;
+    userId: string | null;
+    userName: string | null;
+}
+/** Auto-collected git information. All fields nullable. */
+interface GitMetadata {
+    readonly branch: string | null;
+    readonly commitSha: string | null;
+    readonly commitMessage: string | null;
+    readonly commitAuthor: string | null;
+    readonly remoteUrl: string | null;
+}
+/** Cached repo identity. */
+interface RepoResolution {
+    readonly repoId: string;
+    readonly gitId: string;
+    readonly displayName: string;
+    readonly resolvedAt: number;
+    readonly apiKeyHash: string;
+}
+/** A single queued upload payload. */
+interface QueueEntry {
+    readonly version: string;
+    readonly queuedAt: string;
+    readonly reason: string;
+    readonly retryCount: number;
+    readonly targetEndpoint: string;
+    readonly method: string;
+    readonly payload: Record<string, unknown>;
+    readonly headers: Record<string, string>;
+}
+/** Inline cloud configuration accepted via reporter options. */
+interface CloudReporterOptions {
+    readonly apiKey?: string;
+    readonly endpoint?: string;
+    readonly upload?: UploadStrategy;
+    readonly timeout?: number;
+    readonly projectName?: string;
+    readonly queueMaxAge?: string;
+    readonly queueDirectory?: string;
+    readonly uploadArtifacts?: boolean;
+    readonly artifactMaxSizeMb?: number;
+}
+interface MergeOptions {
+    readonly output: string;
+    readonly testRunId?: string;
+}
+/** A single artifact file within a test's artifact folder. */
+interface ArtifactFile {
+    /** File name (e.g., `screenshot.png`, `video.webm`) */
+    readonly name: string;
+    /** Artifact type for rendering */
+    readonly type: 'screenshot' | 'video' | 'other';
+    /** Path relative to the report output directory */
+    readonly relativePath: string;
+    /** File size in bytes */
+    readonly sizeBytes: number;
+}
+/** A single test's artifacts within a run folder. */
+interface ArtifactTestEntry {
+    /** Sanitized test folder name */
+    readonly testName: string;
+    /** List of artifact files for this test */
+    readonly files: readonly ArtifactFile[];
+}
+/** A single test run's artifact folder in the manifest. */
+interface ArtifactRunEntry {
+    /** Timestamp-based folder name (e.g., `2026-03-02T14-30-00`) */
+    readonly folderName: string;
+    /** ISO 8601 timestamp parsed from folder name */
+    readonly timestamp: string;
+    /** Sum of all file sizes in this run folder */
+    readonly totalSizeBytes: number;
+    /** Number of test artifact subdirectories */
+    readonly testCount: number;
+    /** Per-test artifact details */
+    readonly tests: readonly ArtifactTestEntry[];
+    /** Whether this folder belongs to the current report's run */
+    readonly isCurrentRun: boolean;
+}
+/** Top-level manifest structure written as `artifact-manifest.json`. */
+interface ArtifactRunManifest {
+    /** Manifest schema version (starts at `"1.0"`) */
+    readonly schemaVersion: string;
+    /** ISO 8601 timestamp of manifest generation */
+    readonly generatedAt: string;
+    /** Relative path to artifacts directory from report (e.g., `"artifacts"`) */
+    readonly artifactBaseDir: string;
+    /** Sum of all run folder sizes */
+    readonly totalSizeBytes: number;
+    /** All discovered run folders, sorted newest first */
+    readonly runs: readonly ArtifactRunEntry[];
+    /** Port of the artifact management server, or null if not running */
+    readonly serverPort: number | null;
+}
+/** Compact index entry for a single test — kept in memory during run. */
+interface TestIndexEntry {
+    /** Deterministic hash ID (first 12 chars of SHA-256) */
+    readonly id: string;
+    /** Test title (leaf name) */
+    readonly title: string;
+    /** Full title path (describe blocks + test name) */
+    readonly titlePath: readonly string[];
+    /** Relative path to test file */
+    readonly filePath: string;
+    /** Test outcome */
+    readonly status: TestStatus;
+    /** Test duration in milliseconds */
+    readonly duration: number;
+    /** Playwright project name */
+    readonly project: string;
+    /** Retry attempt number (0 = first run) */
+    readonly retryIndex: number;
+    /** Test tags */
+    readonly tags: readonly string[];
+    /** Whether this test has network request data */
+    readonly hasNetworkData: boolean;
+    /** Whether this test has console log data */
+    readonly hasConsoleData: boolean;
+    /** Whether this test has screenshot/video artifacts */
+    readonly hasArtifacts: boolean;
+    /** Whether this test has action step data */
+    readonly hasActionSteps: boolean;
+    /** First line of error message (failed/flaky tests only) */
+    readonly errorMessage: string | null;
+    /** Number of network requests captured */
+    readonly networkCount: number;
+    /** Number of console log entries captured */
+    readonly consoleCount: number;
+    /** Number of action steps captured */
+    readonly actionCount: number;
+    /** Whether this is a retry attempt (not the final attempt) */
+    readonly isRetry: boolean;
+}
+/**
+ * Full detail data for a single test, stored on disk.
+ *
+ * In v3 (stream-to-disk), heavy data (network requests, console logs,
+ * API calls) is stored in separate JSONL files alongside meta.json.
+ * The `has*` and `*Count` fields indicate availability without loading.
+ */
+interface TestDetailData {
+    /** Same as TestIndexEntry.id */
+    readonly id: string;
+    /** Page navigation events (inline — typically small) */
+    readonly navigations: readonly NavigationAnnotation[];
+    /** API assertion results (inline — typically small) */
+    readonly apiAssertions: readonly ApiAssertion[];
+    /** Nested action step tree (inline — typically small) */
+    readonly actions: readonly ActionStep[];
+    /** References to screenshot/video files */
+    readonly artifacts: TestArtifacts | null;
+    /** Error details for failed/flaky tests */
+    readonly failureDiagnostic: FailureDiagnostic | null;
+    /** Whether network.jsonl exists for this test */
+    readonly hasNetworkFile: boolean;
+    /** Number of items in network.jsonl */
+    readonly networkRequestsCount: number;
+    /** Whether console.jsonl exists for this test */
+    readonly hasConsoleFile: boolean;
+    /** Number of items in console.jsonl */
+    readonly consoleLogsCount: number;
+    /** Whether api-calls.jsonl exists for this test */
+    readonly hasApiCallsFile: boolean;
+    /** Number of items in api-calls.jsonl */
+    readonly apiCallsCount: number;
+    /** Test start time (ISO 8601) — used for video sync */
+    readonly startedAt?: string;
+}
+/** Streaming report summary — running counters written to summary.json. */
+interface StreamingReportSummary {
+    /** Unique run identifier */
+    readonly testRunId: string;
+    /** ISO 8601 start timestamp */
+    readonly startedAt: string;
+    /** ISO 8601 completion timestamp */
+    readonly completedAt: string;
+    /** Wall-clock duration in ms */
+    readonly totalDuration: number;
+    /** Total number of test results */
+    readonly total: number;
+    /** Tests that passed */
+    readonly passed: number;
+    /** Tests that failed */
+    readonly failed: number;
+    /** Tests that passed on retry */
+    readonly flaky: number;
+    /** Tests that were skipped */
+    readonly skipped: number;
+    /** Tests that timed out */
+    readonly timedOut: number;
+    /** Tests that were interrupted */
+    readonly interrupted: number;
+    /** Total API calls across all tests */
+    readonly totalApiCalls: number;
+    /** Total assertions across all tests */
+    readonly totalAssertions: number;
+    /** Total page navigations */
+    readonly totalNavigations: number;
+    /** Total network requests captured */
+    readonly totalNetworkRequests: number;
+    /** Total console log entries captured */
+    readonly totalConsoleLogs: number;
+    /** Total action steps captured */
+    readonly totalActionSteps: number;
+    /** User-provided metadata */
+    readonly metadata: Record<string, unknown> | null;
+    /** Report generation mode */
+    readonly reportMode: ReportMode;
+    /** Per-file aggregation */
+    readonly files: readonly StreamingFileStats[];
+    /** Enriched summary (matches existing Summary interface) */
+    readonly enrichedSummary: Summary | null;
+    /** Validation cross-check data */
+    readonly validation: StreamingValidation | null;
+    /** Write errors encountered during streaming */
+    readonly writeErrors: readonly StreamingWriteError[];
+}
+/** Per-file test aggregation for streaming reports. */
+interface StreamingFileStats {
+    readonly filePath: string;
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly flaky: number;
+    readonly skipped: number;
+    readonly timedOut: number;
+}
+/** Validation cross-check between reporter counts and Playwright. */
+interface StreamingValidation {
+    readonly reporterTotal: number;
+    readonly indexTotal: number;
+    readonly playwrightStatus: string;
+    readonly isValid: boolean;
+}
+/** A write error that occurred during streaming. */
+interface StreamingWriteError {
+    readonly testId: string;
+    readonly error: string;
+    readonly timestamp: string;
+}
+/** Top-level manifest for a streaming report directory. */
+interface StreamingReportManifest {
+    /** Schema version (`"2.0"` for streaming format) */
+    readonly schemaVersion: string;
+    /** ISO 8601 generation timestamp */
+    readonly generatedAt: string;
+    /** Report generation mode */
+    readonly reportMode: ReportMode;
+    /** Relative path to summary.json */
+    readonly summaryFile: string;
+    /** Relative path to index.json */
+    readonly indexFile: string;
+    /** Relative path to tests/ directory */
+    readonly testsDir: string;
+    /** Relative path to artifacts/ directory */
+    readonly artifactsDir: string;
+    /** Total number of test detail files */
+    readonly testCount: number;
+    /** Total size of all report data on disk */
+    readonly totalSizeBytes: number;
+}
+
+/**
+ * @testrelic/core — Configurable logger
+ *
+ * Provides a Logger interface with a no-op default.
+ * Never uses console.* directly (Constitution SDK Constraint).
+ */
+interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+interface LoggerOptions {
+    readonly handler?: (level: LogLevel, message: string, args: unknown[]) => void;
+}
+type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+declare function createLogger(options?: LoggerOptions): Logger;
+
+/**
+ * @testrelic/core — Structured error factory
+ *
+ * Machine-readable error codes for programmatic handling.
+ */
+declare const ErrorCode: {
+    readonly CONFIG_INVALID: "TESTRELIC_CONFIG_INVALID";
+    readonly OUTPUT_WRITE_FAILED: "TESTRELIC_OUTPUT_WRITE_FAILED";
+    readonly MERGE_INVALID_SCHEMA: "TESTRELIC_MERGE_INVALID_SCHEMA";
+    readonly MERGE_READ_FAILED: "TESTRELIC_MERGE_READ_FAILED";
+    readonly NAVIGATION_FLUSH_FAILED: "TESTRELIC_NAVIGATION_FLUSH_FAILED";
+    readonly CODE_EXTRACT_FAILED: "TESTRELIC_CODE_EXTRACT_FAILED";
+    readonly HTML_REPORT_FAILED: "TESTRELIC_HTML_REPORT_FAILED";
+    readonly CLOUD_AUTH_FAILED: "TESTRELIC_CLOUD_AUTH_FAILED";
+    readonly CLOUD_UPLOAD_FAILED: "TESTRELIC_CLOUD_UPLOAD_FAILED";
+    readonly CLOUD_CONFIG_INVALID: "TESTRELIC_CLOUD_CONFIG_INVALID";
+    readonly CLOUD_QUEUE_FAILED: "TESTRELIC_CLOUD_QUEUE_FAILED";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class TestRelicError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string, cause?: unknown);
+}
+declare function createError(code: ErrorCode, message: string, cause?: unknown): TestRelicError;
+
+/**
+ * @testrelic/core — Lightweight runtime type guards
+ *
+ * Hand-written guards, no runtime schema libraries (Constitution SDK Constraint).
+ */
+
+declare function isValidNavigationType(value: unknown): value is NavigationType;
+declare function isValidConfig(input: unknown): input is ReporterConfig;
+declare function isValidApiKeyFormat(value: unknown): value is string;
+declare function isValidUploadStrategy(value: unknown): value is UploadStrategy;
+declare function isValidEndpointUrl(value: unknown): boolean;
+declare function isValidCloudConfig(input: unknown): input is CloudConfig;
+declare function isValidQueueEntry(input: unknown): input is QueueEntry;
+declare function isValidTestRunReport(value: unknown): value is TestRunReport;
+
+export { ATTACHMENT_CONTENT_TYPE, ATTACHMENT_NAME, type ActionCategory, type ActionStep, type ApiAssertion, type ApiCallRecord, type ApiCallStep, type ApiCallStepRequest, type ApiCallStepResponse, type ArtifactFile, type ArtifactRunEntry, type ArtifactRunManifest, type ArtifactTestEntry, type AssertionLocation, type AssertionType, type AuthMode, type AuthState, type CIMetadata, type CIProvider, type CapturedNetworkRequest, type CloudConfig, type CloudReporterOptions, type ConsoleLogEntry, type ConsoleLogLevel, ErrorCode, type FailureDiagnostic, type GitMetadata, type LogLevel, type Logger, type LoggerOptions, type MergeOptions, type NavigationAnnotation, type NavigationStep, type NavigationType, type NetworkStats, PAYLOAD_VERSION, PAYLOAD_VERSION_LEGACY, type QueueEntry, type RepoResolution, type ReportMode, type ReporterConfig, type ResourceBreakdown, type ResourceType, type StepAssertion, type StepTestIdentity, type StreamingFileStats, type StreamingReportManifest, type StreamingReportSummary, type StreamingValidation, type StreamingWriteError, type Summary, type TestArtifacts, type TestDetailData, type TestIndexEntry, type TestRelicDataPayload, TestRelicError, type TestRelicFilePayload, type TestResult, type TestRunReport, type TestStatus, type TestType, type TimelineEntry, type TimelineStep, type UploadStrategy, createError, createLogger, isTestRelicDataPayload, isTestRelicFilePayload, isValidApiKeyFormat, isValidCloudConfig, isValidConfig, isValidEndpointUrl, isValidNavigationType, isValidQueueEntry, isValidTestRunReport, isValidUploadStrategy };