@luckystack/test-runner 0.10.1 → 0.11.0

package/dist/probeRequest.d.ts

@@ -0,0 +1,48 @@
+import type { EndpointDescriptor, HttpMethod } from './types.js';
+export interface ProbeRequestInput {
+    url: string;
+    method: HttpMethod;
+    baseUrl: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    requestTimeoutMs: number;
+}
+export interface ProbeResponse {
+    /** HTTP status. Absent when the probe travelled over Socket.io. */
+    httpStatus?: number;
+    parsed: {
+        status?: string;
+        errorCode?: string;
+    } | null;
+}
+/**
+ * Send a single timed fetch probe and parse the JSON envelope. Returns
+ * `null` when the request itself fails (network error or abort).
+ */
+export declare const sendProbe: (input: ProbeRequestInput) => Promise<ProbeResponse | null>;
+export interface ProbeTransportRequest {
+    endpoint: EndpointDescriptor;
+    baseUrl: string;
+    /** The route payload — the API `data`, or the sync `data` (the transport adds the sync envelope). */
+    body: unknown;
+    /** HTTP headers (session Cookie, CSRF). A socket transport reads only the Cookie. */
+    headers?: Record<string, string>;
+    requestTimeoutMs: number;
+}
+export interface ProbeTransport {
+    readonly name: 'http' | 'socket';
+    /** Resolve with the parsed reply, or `null` when no reply arrived (network error / timeout). */
+    send: (request: ProbeTransportRequest) => Promise<ProbeResponse | null>;
+    /** Release held connections. Optional — the HTTP transport holds none. */
+    close?: () => Promise<void>;
+}
+export interface HttpProbeTransportOptions {
+    /**
+     * Room sent as `receiver` on sync probes. Without one the server answers
+     * `sync.missingReceiver`, which proves the envelope but not the route.
+     */
+    syncReceiver?: string;
+}
+export declare const createHttpProbeTransport: (options?: HttpProbeTransportOptions) => ProbeTransport;
+/** Transport the checks use when the caller supplies none. */
+export declare const defaultProbeTransport: ProbeTransport;

package/dist/rateLimitCheck.d.ts

@@ -0,0 +1,14 @@
+import type { ContractCheckResult, EndpointDescriptor } from './types.js';
+import type { ProbeTransport } from './probeRequest.js';
+export interface RateLimitCheckInput {
+    endpoint: EndpointDescriptor;
+    baseUrl: string;
+    rateLimit: number;
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+    headers?: Record<string, string>;
+    /** Per-call request timeout in ms. Defaults to 10000. */
+    requestTimeoutMs?: number;
+    /** How the probes reach the server. Defaults to HTTP. */
+    transport?: ProbeTransport;
+}
+export declare const runRateLimitCheck: (input: RateLimitCheckInput) => Promise<ContractCheckResult>;

package/dist/reporter.d.ts

@@ -0,0 +1,3 @@
+import type { ContractCheckResult, RunContractSummary } from './types.js';
+export declare const logContractResult: (result: ContractCheckResult) => void;
+export declare const logContractSummary: (summary: RunContractSummary) => void;

package/dist/resetServerState.d.ts

@@ -0,0 +1,13 @@
+import type { TestResetTarget } from '@luckystack/core';
+export interface ResetServerStateInput {
+    baseUrl: string;
+    token?: string;
+    requestTimeoutMs?: number;
+    /**
+     * Clear only these targets (`?only=`). Omit for the server's default reset,
+     * which ALSO deletes every Redis session — including an authenticated sweep's
+     * own. The runner itself always passes `['rateLimits']`.
+     */
+    only?: TestResetTarget[];
+}
+export declare const resetServerState: ({ baseUrl, token, requestTimeoutMs, only }: ResetServerStateInput) => Promise<boolean>;

package/dist/resolveTestBaseUrl.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveTestBaseUrlOptions {
+    /** Project root containing node_modules/.luckystack/dev-server.json. */
+    cwd?: string;
+    /** Used when no explicit override or valid live advertisement exists. */
+    fallbackUrl?: string;
+}
+export declare const resolveTestBaseUrl: (options?: ResolveTestBaseUrlOptions) => string;

package/dist/resolveTestEnvironment.d.ts

@@ -0,0 +1,21 @@
+type MaybePromise<T> = T | Promise<T>;
+export interface ResolveTestEnvironmentInput {
+    /**
+     * Loads the consumer's default-exported `config.ts` object after `.env` files
+     * are available. Keeping this as a callback avoids hardcoding a consumer path
+     * inside the package and keeps `@luckystack/secret-manager` optional.
+     */
+    loadProjectConfig?: () => MaybePromise<unknown>;
+}
+interface RequiredProjectConfigLoader {
+    loadProjectConfig: NonNullable<ResolveTestEnvironmentInput['loadProjectConfig']>;
+}
+/** @internal Runtime guard for untyped callers of the public orchestrators. */
+export declare const assertProjectConfigLoader: (input: unknown, caller: 'runAllTests' | 'runCustomTests') => asserts input is RequiredProjectConfigLoader;
+/**
+ * Load the project's env files and resolve optional secret-manager pointers for
+ * the TEST process. Call before importing integration-test modules that touch a
+ * database, Redis, or another env-backed SDK.
+ */
+export declare const resolveTestEnvironment: (input?: ResolveTestEnvironmentInput) => Promise<void>;
+export {};

package/dist/runAllTests.d.ts

@@ -0,0 +1,88 @@
+import type { InputSchemaMap } from './sampleInputFor.js';
+import { type ResolveTestEnvironmentInput } from './resolveTestEnvironment.js';
+import type { RunCustomTestsSummary } from './customTests.js';
+import type { ApiMethodMap, ApiMetaMap, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunAllTestsInput {
+    apiMethodMap: ApiMethodMap;
+    /**
+     * Generated `syncMetaMap` (from `apiTypes.generated.ts`). When given, the
+     * sweep layers exercise every sync route too; without it sync routes are
+     * not swept (a warning says so).
+     */
+    syncMetaMap?: SyncMetaMap;
+    /** Generated `syncInputSchemas` (from `apiInputSchemas.generated.ts`) — Zod-valid sync sample payloads. */
+    syncInputSchemas?: InputSchemaMap;
+    /**
+     * How sync routes are probed. Defaults to the project's own
+     * `transport.invocation`: `'socket'` → Socket.io (the pipeline real clients
+     * hit), `'routed-http'` → the `/sync/*` HTTP route. The CSRF layer always
+     * probes over HTTP — CSRF is an HTTP-only guard.
+     */
+    syncTransport?: 'socket' | 'http';
+    /**
+     * Write the full `RunAllTestsSummary` as JSON to this path (relative to the
+     * process cwd). Defaults to `TEST_OUTPUT_FILE`, else `test-results.json`;
+     * `false` disables the file.
+     */
+    outputFile?: string | false;
+    /**
+     * Lazy loader for the consumer's default `config.ts` export. Required so
+     * runAllTests cannot silently skip a configured secret manager; resolution
+     * happens in THIS process before any layer or env-backed client is touched.
+     */
+    loadProjectConfig: NonNullable<ResolveTestEnvironmentInput['loadProjectConfig']>;
+    apiMetaMap: ApiMetaMap;
+    apiInputSchemas: InputSchemaMap;
+    baseUrl: string;
+    /** Cookie name for the session token. Defaults to the project's configured session cookie name (`projectConfig.http.sessionCookieName`). */
+    sessionCookieName?: string;
+    /** Auth token applied as a `Cookie` header to sweep-layer requests that need a session. */
+    authToken?: string;
+    /** Endpoints to skip from the sweep layers, e.g. routes that need a file upload. */
+    skip?: string[];
+    /** Substring filter applied to `<page>/<name>/<version>`. */
+    filter?: string;
+    /** Disable individual layers (faster local iteration). */
+    noSweep?: boolean;
+    noFuzz?: boolean;
+    noRateLimit?: boolean;
+    /**
+     * Disable the CSRF-enforcement layer. Defaults to ON (the layer runs) — but it
+     * can only probe past the auth guard with a session, so it is a no-op unless an
+     * `authToken` is supplied.
+     */
+    noCsrf?: boolean;
+    noCustom?: boolean;
+    /**
+     * Token sent as `X-Test-Reset-Token` when the rate-limit layer resets the
+     * shared bucket between endpoints. The server's `/_test/reset` requires
+     * `TEST_RESET_TOKEN` to be set and matching — an unset/wrong token is 403, so
+     * `resetBetweenEndpoints` would silently no-op. Defaults to
+     * `process.env.TEST_RESET_TOKEN` so a CI run with the env set works with no
+     * extra wiring; pass explicitly to override.
+     */
+    resetToken?: string;
+    /**
+     * When a reset token is available, the sweep POSTs
+     * `/_test/reset?only=rateLimits` ONCE before the first layer (no bucket left
+     * drained by an earlier run) and ONCE after the last (the custom layer and the
+     * next run start unthrottled). Only limiter state is cleared: sessions — the
+     * `authToken` session above all — survive, so `TEST_RESET_TOKEN` can be set
+     * on an authenticated sweep. The reset never touches the app database.
+     * Defaults to ON; set `false` to opt out. With no token the bookends are
+     * skipped with a logged note (they can't run — `/_test/reset` 403s).
+     */
+    resetBookends?: boolean;
+}
+export interface RunAllTestsSummary {
+    contract?: RunContractSummary;
+    auth?: RunContractSummary;
+    rateLimit?: RunContractSummary;
+    csrf?: RunContractSummary;
+    fuzz?: RunContractSummary;
+    custom?: RunCustomTestsSummary;
+    totalPassed: number;
+    totalFailed: number;
+}
+export declare const runAllTests: (input: RunAllTestsInput) => Promise<RunAllTestsSummary>;
+export declare const logRunAllSummary: (summary: RunAllTestsSummary) => void;

package/dist/runAuthEnforcementTests.d.ts

@@ -0,0 +1,17 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ApiMetaMap, ContractCheckResult, EndpointDescriptor, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunAuthEnforcementTestsInput {
+    apiMethodMap: ApiMethodMap;
+    apiMetaMap: ApiMetaMap;
+    /** Generated `syncMetaMap`. When given, sync routes are swept too. */
+    syncMetaMap?: SyncMetaMap;
+    baseUrl: string;
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
+    filter?: string;
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    syncTransport?: ProbeTransport;
+    onResult?: (result: ContractCheckResult) => void;
+}
+export declare const runAuthEnforcementTests: (input: RunAuthEnforcementTestsInput) => Promise<RunContractSummary>;

package/dist/runContractTests.d.ts

@@ -0,0 +1,22 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ContractCheckResult, EndpointDescriptor, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunContractTestsInput {
+    apiMethodMap: ApiMethodMap;
+    /** Generated `syncMetaMap`. When given, sync routes are swept too. */
+    syncMetaMap?: SyncMetaMap;
+    baseUrl: string;
+    /**
+     * Endpoints to skip. Matched against `<page>/<name>` (version-agnostic) and
+     * `<page>/<name>/<version>` (version-specific). Useful for endpoints that
+     * are known to need real input (e.g. a file upload).
+     */
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
+    filter?: string;
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+    headers?: Record<string, string>;
+    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    syncTransport?: ProbeTransport;
+    onResult?: (result: ContractCheckResult) => void;
+}
+export declare const runContractTests: (input: RunContractTestsInput) => Promise<RunContractSummary>;

package/dist/runCsrfEnforcementTests.d.ts

@@ -0,0 +1,29 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ApiMetaMap, ContractCheckResult, EndpointDescriptor, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunCsrfEnforcementTestsInput {
+    apiMethodMap: ApiMethodMap;
+    apiMetaMap: ApiMetaMap;
+    /** Generated `syncMetaMap`. When given, sync routes' `/sync/*` HTTP endpoints are probed too. */
+    syncMetaMap?: SyncMetaMap;
+    baseUrl: string;
+    /** Valid session Cookie header (`<name>=<token>`) the probes carry so they reach the CSRF check. */
+    authCookie: string;
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
+    filter?: string;
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+    /**
+     * HTTP transport for sync routes (one carrying the sync `receiver`). CSRF is
+     * an HTTP-only guard, so this must be an HTTP transport even when the project
+     * syncs over Socket.io — the `/sync/*` HTTP route is reachable either way.
+     */
+    syncTransport?: ProbeTransport;
+    /** Per-call request timeout in ms forwarded to each check. */
+    requestTimeoutMs?: number;
+    /** Error code expected on CSRF rejection. Defaults to `auth.csrfMismatch`. */
+    expectedErrorCode?: string;
+    /** HTTP status expected on CSRF rejection. Defaults to 403; pass `false` to skip. */
+    expectedHttpStatus?: number | false;
+    onResult?: (result: ContractCheckResult) => void;
+}
+export declare const runCsrfEnforcementTests: (input: RunCsrfEnforcementTestsInput) => Promise<RunContractSummary>;

package/dist/runFuzzTests.d.ts

@@ -0,0 +1,16 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ContractCheckResult, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunFuzzTestsInput {
+    apiMethodMap: ApiMethodMap;
+    /** Generated `syncMetaMap`. When given, sync routes are swept too. */
+    syncMetaMap?: SyncMetaMap;
+    baseUrl: string;
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
+    filter?: string;
+    headers?: Record<string, string>;
+    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    syncTransport?: ProbeTransport;
+    onResult?: (result: ContractCheckResult) => void;
+}
+export declare const runFuzzTests: (input: RunFuzzTestsInput) => Promise<RunContractSummary>;

package/dist/runRateLimitTests.d.ts

@@ -0,0 +1,38 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ApiMetaMap, ContractCheckResult, EndpointDescriptor, RunContractSummary, SyncMetaMap } from './types.js';
+export interface RunRateLimitTestsInput {
+    apiMethodMap: ApiMethodMap;
+    apiMetaMap: ApiMetaMap;
+    /** Generated `syncMetaMap`. When given, sync routes are swept too. */
+    syncMetaMap?: SyncMetaMap;
+    baseUrl: string;
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
+    filter?: string;
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+    headers?: Record<string, string>;
+    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    syncTransport?: ProbeTransport;
+    /**
+     * Max rateLimit value to test. Endpoints with a higher limit are skipped
+     * to avoid firing thousands of requests in CI.
+     */
+    maxRateLimitToTest?: number;
+    /**
+     * When true, hit `/_test/reset?only=rateLimits` before each endpoint so
+     * limiter state is clean. Only the limiter buckets are cleared — sessions
+     * survive, so an authenticated sweep keeps its session. Requires the server
+     * to allow the endpoint: `NODE_ENV` in { 'development', 'test' } AND
+     * `TEST_RESET_TOKEN` set on the server with a matching `resetToken` here (an
+     * unset token is 403, never open). Without resetting, the shared IP bucket
+     * leaks state between endpoints.
+     */
+    resetBetweenEndpoints?: boolean;
+    /**
+     * Token forwarded as `X-Test-Reset-Token` when resetting. Only relevant in
+     * staging/preview deploys that enable the endpoint behind a token.
+     */
+    resetToken?: string;
+    onResult?: (result: ContractCheckResult) => void;
+}
+export declare const runRateLimitTests: (input: RunRateLimitTestsInput) => Promise<RunContractSummary>;

package/dist/runRegisteredLayers.d.ts

@@ -0,0 +1,24 @@
+import type { InputSchemaMap } from './sampleInputFor.js';
+import type { TestSummary } from './extensionRegistry.js';
+import type { ApiMethodMap, EndpointDescriptor, SyncMetaMap } from './types.js';
+export interface RunRegisteredLayersInput {
+    apiMethodMap: ApiMethodMap;
+    /** Generated `syncMetaMap`. When given, layers also run against every sync route. */
+    syncMetaMap?: SyncMetaMap;
+    /** Session/bearer token forwarded to each layer's `run({ authToken })`. */
+    authToken?: string;
+    /**
+     * Endpoints to skip — matched against `<page>/<name>` (version-agnostic) and
+     * `<page>/<name>/<version>`, same convention as the built-in sweeps.
+     */
+    skip?: string[];
+    /** Substring filter on `<page>/<name>/<version>`, same as the built-in sweeps. */
+    filter?: string;
+    /** Generated `apiInputSchemas` — source of each API route's `sampleInput`. */
+    apiInputSchemas?: InputSchemaMap;
+    /** Generated `syncInputSchemas` — source of each sync route's `sampleInput`. */
+    syncInputSchemas?: InputSchemaMap;
+    /** Custom sample factory; wins over the schema maps when given. */
+    inputFor?: (endpoint: EndpointDescriptor) => unknown;
+}
+export declare const runRegisteredLayers: (input: RunRegisteredLayersInput) => Promise<TestSummary>;

package/dist/sampleInputFor.d.ts

@@ -0,0 +1,13 @@
+import type { ZodType } from 'zod';
+import type { EndpointDescriptor } from './types.js';
+export type InputSchemaMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, ZodType | undefined>>>>>>;
+export interface CreateSampleInputForOptions {
+    apiInputSchemas?: InputSchemaMap;
+    syncInputSchemas?: InputSchemaMap;
+    /**
+     * Prefix for generated unconstrained strings — pass the run's
+     * `createTestDataMarker()` so rows the probes create are identifiable.
+     */
+    stringPrefix?: string;
+}
+export declare const createSampleInputFor: (options: CreateSampleInputForOptions) => (endpoint: EndpointDescriptor) => unknown;

package/dist/schemaSampleInput.d.ts

@@ -0,0 +1,12 @@
+import type { z } from 'zod';
+export interface SampleSchemaOptions {
+    /**
+     * Marker prefix applied to generated UNCONSTRAINED string values so any rows
+     * a sweep creates are identifiable + collision-free (finding #98). Strings
+     * that carry a format (email/url/uuid/datetime/…) or a check (min/max/
+     * length/regex) are left as-is, since prefixing could break the route's own
+     * validation and defeat the contract layer's "valid input" guarantee.
+     */
+    stringPrefix?: string;
+}
+export declare const sampleSchemaInput: (schema: z.ZodType, options?: SampleSchemaOptions) => unknown;

package/dist/socketProbeTransport.d.ts

@@ -0,0 +1,9 @@
+import type { ProbeTransport } from './probeRequest.js';
+export interface SocketProbeTransportOptions {
+    baseUrl: string;
+    /** Room every sync probe targets; authenticated sockets join it first. */
+    receiver: string;
+    /** Session cookie name, used to read the token out of a probe's Cookie header. */
+    sessionCookieName: string;
+}
+export declare const createSocketProbeTransport: (options: SocketProbeTransportOptions) => ProbeTransport;

package/dist/streamWatcher.d.ts

@@ -0,0 +1,37 @@
+export interface StreamChunkFrame {
+    /** Per-request correlation id stamped by the server. */
+    cb?: string;
+    /** Full route name (`sync/<page>/<name>/<version>`). */
+    fullName?: string;
+    /** Always `'stream'` for chunk frames. */
+    status?: 'stream';
+    /** Payload fields spread on top of the envelope. */
+    [key: string]: unknown;
+}
+export interface StreamWatcher<TChunk extends StreamChunkFrame = StreamChunkFrame> {
+    /** Chunks received so far. Array reference is stable; entries are pushed in arrival order. */
+    readonly chunks: TChunk[];
+    /** Wait until `predicate(chunks)` returns true, or until timeout (default 5000ms). */
+    stopAt(predicate: (chunks: TChunk[]) => boolean, timeoutMs?: number): Promise<void>;
+    /** Wait until N total chunks received, or until timeout. */
+    waitForCount(n: number, timeoutMs?: number): Promise<void>;
+    /** Close socket B. Tests SHOULD call this in cleanup; ctx auto-closes all watchers when the test ends. */
+    close(): Promise<void>;
+}
+export interface OpenStreamWatcherInput {
+    /** Server URL (same as `ctx`'s `baseUrl`). */
+    baseUrl: string;
+    /** Room to join as a pure subscriber. */
+    roomCode: string;
+    /** Active session token (used for `joinRoom` auth). May be null for routes that don't require auth. */
+    token: string | null;
+    /**
+     * Resolved route name `sync/<page>/<name>/<version>` — chunk frames are
+     * filtered by their `fullName` property so a watcher only surfaces chunks
+     * for the route its test is bound to.
+     */
+    routeFullName: string;
+    /** Default 5000ms — overridable per `stopAt` / `waitForCount` call. */
+    defaultTimeoutMs?: number;
+}
+export declare const openStreamWatcher: <TChunk extends StreamChunkFrame = StreamChunkFrame>(input: OpenStreamWatcherInput) => Promise<StreamWatcher<TChunk>>;

package/dist/testDataMarker.d.ts

@@ -0,0 +1,2 @@
+export declare const TEST_DATA_PREFIX = "lstest_";
+export declare const createTestDataMarker: () => string;

package/dist/testLayerHelpers.d.ts

@@ -0,0 +1,55 @@
+import type { ProbeTransport } from './probeRequest.js';
+import type { ApiMethodMap, ApiMetaMap, ContractCheckResult, EndpointDescriptor, HttpMethod, RouteMetaMap, RunContractSummary, SyncMetaMap } from './types.js';
+export declare const LAYER_KEYS: {
+    readonly contract: 'contract';
+    readonly auth: 'auth-enforcement';
+    readonly rateLimit: 'rate-limit';
+    readonly csrf: 'csrf-enforcement';
+    readonly fuzz: 'fuzz';
+    readonly custom: 'custom';
+};
+export declare const STATE_CHANGING_METHODS: Set<HttpMethod>;
+/** `<page>/<name>/<version>` — the key `filter` and `skip` match against. */
+export declare const routeKey: (endpoint: EndpointDescriptor) => string;
+/** Whether an endpoint matches a substring `filter` (no filter matches all). */
+export declare const matchesFilter: (endpoint: EndpointDescriptor, filter: string | undefined) => boolean;
+export interface SelectEndpointsInput {
+    apiMethodMap: ApiMethodMap;
+    /** Generated `syncMetaMap`. When given, sync routes are swept too. */
+    syncMetaMap?: SyncMetaMap;
+    /** Substring filter on `<page>/<name>/<version>`. Non-matching routes are never requested. */
+    filter?: string;
+}
+/**
+ * The endpoints a sweep layer exercises: every API route, plus every sync
+ * route when a `syncMetaMap` is supplied, narrowed by `filter`. Filtering
+ * here — before any request — is what makes `filter` limit the traffic, not
+ * just the report.
+ */
+export declare const selectEndpoints: (input: SelectEndpointsInput) => EndpointDescriptor[];
+/** The meta map that describes `endpoint`: `syncMetaMap` for sync routes, else `apiMetaMap`. */
+export declare const metaMapFor: (endpoint: EndpointDescriptor, apiMetaMap: ApiMetaMap, syncMetaMap: SyncMetaMap | undefined) => RouteMetaMap;
+/** The transport for `endpoint`: `syncTransport` for sync routes when given, else HTTP. */
+export declare const transportFor: (endpoint: EndpointDescriptor, syncTransport: ProbeTransport | undefined) => ProbeTransport;
+/**
+ * Whether an endpoint is in the explicit skip list. Matched against
+ * `<page>/<name>` (version-agnostic) and `<page>/<name>/<version>`
+ * (version-specific).
+ */
+export declare const shouldSkip: (endpoint: EndpointDescriptor, skip: string[]) => boolean;
+/** Whether the endpoint's meta entry declares `auth.login: true`. */
+export declare const requiresLogin: (metaMap: RouteMetaMap, endpoint: EndpointDescriptor) => boolean;
+/** Whether the endpoint requires ANY authorization: `auth.login: true` OR a
+ *  declared non-empty `auth.additional[]` predicate list (role/tenant/ownership
+ *  guards). The auth sweep must probe BOTH — an additional[]-only route (login:
+ *  false) is still authz-protected and an unauth call must be rejected. */
+export declare const hasAuthRequirement: (metaMap: RouteMetaMap, endpoint: EndpointDescriptor) => boolean;
+/** Whether the meta map carries an entry for this endpoint at all. */
+export declare const hasMetaEntry: (metaMap: RouteMetaMap, endpoint: EndpointDescriptor) => boolean;
+/**
+ * The endpoint's declared numeric rate limit, or `null` when it has none
+ * (`false`/`undefined`) or no meta entry exists.
+ */
+export declare const getRateLimit: (metaMap: RouteMetaMap, endpoint: EndpointDescriptor) => number | null;
+/** Aggregate pass/fail/skip counts over a sweep layer's results. */
+export declare const calculateSummary: (results: ContractCheckResult[]) => RunContractSummary;

package/dist/testSocket.d.ts

@@ -0,0 +1,58 @@
+import { Socket } from 'socket.io-client';
+export declare const nextResponseIndex: () => number;
+export interface ConnectTestSocketInput {
+    baseUrl: string;
+    /** Session token, or null for an anonymous socket. */
+    token: string | null;
+    /** Prefix for error messages (e.g. `watchStream`, `callSync`). */
+    label: string;
+    /** Session cookie name. Defaults to the project's configured cookie. */
+    sessionCookieName?: string;
+    connectTimeoutMs?: number;
+}
+/**
+ * Open a socket.io connection authenticated the way a browser would be, and
+ * wait until it is connected. On a connect timeout / connect_error the socket
+ * is torn down before the error is thrown, so a failed attempt never leaks.
+ */
+export declare const connectTestSocket: (input: ConnectTestSocketInput) => Promise<Socket>;
+/**
+ * Close a socket that runs on a session the runner does NOT own (the sweep's
+ * `authToken`) without ending that session.
+ *
+ * With `@luckystack/presence` installed, a token whose last socket closes is
+ * logged out once the short disconnect grace window expires — a closed browser
+ * tab ends the session. A plain `disconnect()` therefore deleted the caller's
+ * session seconds after every sweep. Sending `intentionalDisconnect` first is
+ * the signal a real client sends on a tab switch: presence keeps the session
+ * and the server closes the socket itself. Without presence nobody listens,
+ * so the socket is closed locally after a short wait.
+ */
+export declare const releaseTestSocket: (socket: Socket) => Promise<void>;
+/**
+ * Join `room` and wait for the server's ack. Rejects when the server refuses
+ * the join (e.g. `auth.required` for an anonymous socket) or never answers.
+ */
+export declare const joinTestRoom: (socket: Socket, room: string, options: {
+    label: string;
+    timeoutMs?: number;
+}) => Promise<void>;
+export interface EmitSyncInput {
+    /** `<page>/<name>/<version>` — the route path without the `sync/` prefix. */
+    routePath: string;
+    data: unknown;
+    receiver: string | undefined;
+    ignoreSelf?: boolean;
+    timeoutMs: number;
+}
+export type EmitSyncOutcome = {
+    kind: 'response';
+    payload: unknown;
+} | {
+    kind: 'timeout';
+};
+/**
+ * Send one sync request over `socket` exactly like the real client does and
+ * resolve with the server's single reply on `sync-<responseIndex>`.
+ */
+export declare const emitSyncOverSocket: (socket: Socket, input: EmitSyncInput) => Promise<EmitSyncOutcome>;

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+export type ApiMethodMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, string>>>>>>;
+export type SyncMethodMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, string>>>>>>;
+export interface ApiMetaEntry {
+    method: string;
+    auth: {
+        login: boolean;
+        additional?: Record<string, unknown>[];
+        hasAdditional?: boolean;
+    };
+    rateLimit?: number | false;
+}
+export type ApiMetaMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, ApiMetaEntry>>>>>>;
+export interface SyncMetaEntry {
+    auth: ApiMetaEntry['auth'];
+    rateLimit?: number | false;
+}
+export type SyncMetaMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, SyncMetaEntry>>>>>>;
+export type RouteMetaEntry = Pick<ApiMetaEntry, 'auth' | 'rateLimit'>;
+export type RouteMetaMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, RouteMetaEntry>>>>>>;
+export interface EndpointDescriptor {
+    page: string;
+    name: string;
+    version: string;
+    method: HttpMethod;
+    /** `api/<page>/<name>/<version>` or `sync/<page>/<name>/<version>` */
+    fullPath: string;
+    /** Route kind. Absent means `'api'` — only `walkSyncEndpoints` sets `'sync'`. */
+    kind?: 'api' | 'sync';
+}
+export interface ContractCheckResult {
+    endpoint: EndpointDescriptor;
+    status: 'pass' | 'fail' | 'skipped';
+    httpStatus?: number;
+    responseStatus?: 'success' | 'error' | 'unknown';
+    errorCode?: string;
+    reason?: string;
+    durationMs: number;
+}
+export interface RunContractSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    results: ContractCheckResult[];
+}

package/dist/walkEndpoints.d.ts

@@ -0,0 +1,6 @@
+import type { EndpointDescriptor, SyncMetaMap, SyncMethodMap } from './types.js';
+type ApiMethodMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, string>>>>>>;
+export declare const walkEndpoints: (apiMethodMap: ApiMethodMap) => EndpointDescriptor[];
+type SyncRouteMap = Partial<Record<string, Partial<Record<string, Partial<Record<string, unknown>>>>>>;
+export declare const walkSyncEndpoints: (syncMap: SyncMethodMap | SyncMetaMap | SyncRouteMap) => EndpointDescriptor[];
+export {};