stubsmith 0.0.0-stage → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,806 @@
+/// <reference lib="esnext.disposable" />
+/** Headers as accepted by the maskers. */
+type HeaderInput = Record<string, string> | ReadonlyMap<string, string>;
+type TemplatePart = string | {
+    group: number | string;
+};
+/** One compiled regex mask. */
+interface RegexMask {
+    regex: RegExp;
+    /** Python replacement template. */
+    replace: string;
+    groupCount: number;
+    groupNames: ReadonlySet<string>;
+    /** Parsed lazily, so an invalid template fails at apply time like Python. */
+    parsed?: TemplatePart[];
+}
+/** Immutable pre-compiled masking rules. */
+declare class CompiledRules {
+    /** Lower-cased, stripped field names. */
+    readonly fieldMasks: ReadonlySet<string>;
+    readonly regexMasks: readonly RegexMask[];
+    /**
+     * True when at least one synced regex mask cannot be used: Python rejects
+     * it, or it has no JS translation. The rule's effect is unknown, so
+     * {@link applyRegexes} masks every string it is given (as Python does).
+     */
+    readonly unusable: boolean;
+    constructor(
+    /** Lower-cased, stripped field names. */
+    fieldMasks: ReadonlySet<string>, regexMasks: readonly RegexMask[], 
+    /**
+     * True when at least one synced regex mask cannot be used: Python rejects
+     * it, or it has no JS translation. The rule's effect is unknown, so
+     * {@link applyRegexes} masks every string it is given (as Python does).
+     */
+    unusable?: boolean);
+}
+
+/** `(status, path)` pair of a status-scoped rule. */
+type ScopedRule = readonly [number, string];
+/** Immutable pre-compiled field rules. */
+declare class CompiledFieldRules {
+    readonly keepBody: ReadonlySet<string>;
+    readonly keepQuery: ReadonlySet<string>;
+    /** Lower-cased request header names. */
+    readonly keepHeader: ReadonlySet<string>;
+    readonly keepResp: ReadonlySet<string>;
+    /** Lower-cased response header names. */
+    readonly keepRespHeader: ReadonlySet<string>;
+    readonly keepRespStatus: readonly ScopedRule[];
+    readonly maskRespStatus: readonly ScopedRule[];
+    readonly keepRespHeaderStatus: readonly ScopedRule[];
+    readonly maskRespHeaderStatus: readonly ScopedRule[];
+    /** Semantic type hints of mask rules, keyed by namespace-relative path / name. */
+    readonly bodyMaskTypes: ReadonlyMap<string, string>;
+    readonly queryMaskTypes: ReadonlyMap<string, string>;
+    readonly respMaskTypes: ReadonlyMap<string, string>;
+    constructor(keepBody: ReadonlySet<string>, keepQuery: ReadonlySet<string>, 
+    /** Lower-cased request header names. */
+    keepHeader: ReadonlySet<string>, keepResp: ReadonlySet<string>, 
+    /** Lower-cased response header names. */
+    keepRespHeader: ReadonlySet<string>, keepRespStatus: readonly ScopedRule[], maskRespStatus: readonly ScopedRule[], keepRespHeaderStatus: readonly ScopedRule[], maskRespHeaderStatus: readonly ScopedRule[], 
+    /** Semantic type hints of mask rules, keyed by namespace-relative path / name. */
+    bodyMaskTypes: ReadonlyMap<string, string>, queryMaskTypes: ReadonlyMap<string, string>, respMaskTypes: ReadonlyMap<string, string>);
+}
+
+/** A curated path template with its split segments and literal-segment count precomputed once at load time. */
+interface CuratedTemplate {
+    template: string;
+    literalCount: number;
+    /** Non-empty `/`-separated segments of `template`. */
+    segments: readonly string[];
+    /** Per segment: true when it is a `{name}` wildcard. */
+    wildcards: readonly boolean[];
+}
+
+/** What {@link RulesCache.lookup} returns: `null` is a novel request. */
+type LookupResult = CompiledFieldRules | null;
+declare class RulesCache {
+    private rules;
+    private _cursor;
+    private _projectDefaults;
+    private _emailDomain;
+    private templates;
+    private _groupIdsInPaths;
+    private _valueConfig;
+    private _firstSyncDone;
+    /** Compiled rules for `(endpointId, fp)`, or `null` for an unknown fingerprint (a novel request). */
+    lookup(endpointId: string, fp: string): LookupResult;
+    /** Curated path templates, sorted for matching. A frozen array, replaced (never mutated) by each sync, so no per-call copy. */
+    get pathTemplates(): readonly CuratedTemplate[];
+    /** Synced project defaults, or `null` when none compiled to a rule. */
+    get projectDefaults(): CompiledRules | null;
+    /** Email placeholder domain; `stub.invalid` until a sync supplies one. */
+    get emailDomain(): string;
+    /** Whether path segments that look like IDs become `{id}`; true until a sync sets `project_settings.group_ids_in_paths` to false. */
+    get groupIdsInPaths(): boolean;
+    /** `endpoint_id` to value-discrimination paths (snapshot). */
+    get valueConfig(): Map<string, string[]>;
+    /** Value-discrimination paths for `endpointId` (empty when none). */
+    getValuePaths(endpointId: string): string[];
+    /** Sync cursor, `"0"` initially. */
+    get cursor(): string;
+    /** True once a sync has completed; never cleared. */
+    get firstSyncDone(): boolean;
+    /**
+     * Merge a successful `GET /v1/sdk/sync` body (parsed JSON; `Map` or plain
+     * object). Rules are additive per `(endpoint_id, fingerprint)`; an empty
+     * fingerprint is skipped. The cursor moves only when it is not `"0"`.
+     * `path_templates` is a full replacement (absent clears it);
+     * `project_defaults` is stored only when it compiles to at least one rule,
+     * `email_placeholder_domain` overrides only when a non-empty string;
+     * `request_type_value_config` is a full replacement when an object;
+     * `project_settings.group_ids_in_paths` is stored only when a boolean. A
+     * non-object body is ignored; malformed rule entries are
+     * skipped. All inputs are processed before any state changes.
+     */
+    applySyncResponse(body: unknown): void;
+}
+
+/** One captured request/response pair. Bodies are text; headers are name to value. */
+interface PipelineInput {
+    method: string;
+    /** Full outbound URL including scheme, host, path and query. */
+    url: string;
+    reqHeaders: HeaderInput;
+    reqBody: string;
+    status: number;
+    respHeaders: HeaderInput;
+    respBody: string;
+}
+/** Wire payload minus `source` and `duration` (the client adds those). */
+interface Payload {
+    sdk_version: string;
+    classifier_spec_version: number;
+    sdk_masked: true;
+    sdk_rule_version: string;
+    domain: string;
+    path_template: string;
+    path: string;
+    method: string;
+    status: number;
+    req_fingerprint: string;
+    resp_fingerprint: string;
+    key_paths: string[];
+    resp_key_paths: string[];
+    req_header_names: string[];
+    resp_header_names: string[];
+    query_names: string[];
+    headers: Record<string, string>;
+    req_body: string;
+    resp_headers: Record<string, string>;
+    resp_body: string;
+    novel: boolean;
+    req_body_encoding?: "base64";
+    resp_body_encoding?: "base64";
+    fingerprint_value_paths?: string[];
+    req_value_types?: Record<string, string>;
+    resp_value_types?: Record<string, string>;
+    /**
+     * Raw path (no query) of a capture templated before the first rules sync, so the sender can template
+     * it again once "Group IDs in paths automatically" is known. Private: held in memory, never sent.
+     */
+    _raw_path?: string;
+}
+interface PipelineOptions {
+    /** Overrides `sdk_version` in every payload; defaults to the package version. */
+    sdkVersion?: string;
+    /**
+     * Placeholder salt. When omitted, `STUBSMITH_MASK_SALT` is read at call time
+     * (the conformance behaviour); an empty string means no salt.
+     */
+    salt?: string;
+}
+declare class PrivacyPipeline {
+    private readonly cache;
+    private readonly sdkVersion;
+    /** `undefined` defers to the environment; `null` is an explicit "no salt". */
+    private readonly salt;
+    constructor(rulesCache: RulesCache, opts?: PipelineOptions);
+    /** Privacy-processed payload, or `null` on catastrophic failure (drop the capture). Never throws. */
+    process(input: PipelineInput): Payload | null;
+    private processInner;
+    /** Python `_apply_masking`: returns `[mb, mh, mq, respMb, respMh, novel]`. */
+    private applyMasking;
+}
+
+/** Shared public types for the capture runtime. */
+/** Header name to value; repeated headers are joined with `, ` as Node does. */
+type HeaderRecord = Record<string, string>;
+/** Where a capture came from; the wire `source` field. */
+type CaptureSource = "node-http" | "node-fetch";
+/** One finished request/response pair handed to {@link StubsmithClient.capture}. */
+interface CapturedExchange {
+    method: string;
+    /** Full outbound URL including scheme, host, path and query (the ORIGINAL url for redirects). */
+    url: string;
+    reqHeaders: HeaderRecord;
+    reqBody: string;
+    status: number;
+    respHeaders: HeaderRecord;
+    respBody: string;
+    /** Milliseconds from sending the request to receiving the response headers. */
+    durationMs: number;
+    source: CaptureSource;
+}
+interface StubsmithOptions {
+    /** Defaults to `STUBSMITH_API_KEY`. An empty key disables the SDK entirely. */
+    apiKey?: string;
+    /** Ingest endpoint; defaults to `STUBSMITH_URL`. */
+    url?: string;
+    /** Backend for rules sync; defaults to `STUBSMITH_BACKEND_URL`. */
+    backendUrl?: string;
+    /** Ingest POST timeout in ms. Default 5000. */
+    timeoutMs?: number;
+    /** Fraction of captures sent, 0 to 1. Default 1. */
+    sampleRate?: number;
+    /** Rules poll interval in ms. Default 60000. */
+    rulesPollInterval?: number;
+    /** Gzip payloads of 1024 bytes or more. Default true. */
+    compress?: boolean;
+    /** Debug logging to stderr; defaults to `STUBSMITH_DEBUG`. */
+    debug?: boolean;
+    /**
+     * Placeholder salt; defaults to `STUBSMITH_MASK_SALT`. A value given here is
+     * passed to the privacy pipeline directly; the environment is not modified.
+     */
+    maskSalt?: string;
+    /** Advanced: override the queue and payload ceilings (defaults 1000 items, 32 MiB, 10 MiB). */
+    limits?: {
+        maxQueueItems?: number;
+        maxQueueBytes?: number;
+        maxPayloadBytes?: number;
+    };
+}
+interface FlushOptions {
+    /** Default 5000. */
+    timeoutMs?: number;
+}
+
+declare class StubsmithClient {
+    readonly enabled: boolean;
+    readonly url: string;
+    readonly backendUrl: string;
+    readonly timeoutMs: number;
+    readonly sampleRate: number;
+    readonly compress: boolean;
+    readonly debug: boolean;
+    /** Present only when enabled and the pipeline initialised. */
+    readonly pipeline: PrivacyPipeline | null;
+    readonly rulesCache: RulesCache | null;
+    /** Hold, in ms from client start, for the first rules sync (see `resolveHeld`). Test aid: lower it to run fast. */
+    static firstSyncHoldMs: number;
+    /** Failed sends so far (network error or HTTP status >= 400). */
+    sendFailures: number;
+    /** Captures dropped by the queue caps. */
+    droppedCount: number;
+    private readonly apiKey;
+    private readonly poller;
+    private startedAt;
+    /** waitIdle() calls in progress; while non-zero the sender does not hold captures for the first sync. */
+    private flushing;
+    /** Releases a capture the sender is holding for the first sync (see `resolveHeld`). */
+    private releaseHold;
+    private readonly maxPayloadBytes;
+    private readonly maxQueueBytes;
+    private readonly maxQueueItems;
+    private readonly exitFlushMs;
+    private readonly setsDebug;
+    private readonly queue;
+    private queueBytes;
+    private pumping;
+    private _stopped;
+    private readonly counts;
+    private inflight;
+    private closing;
+    /** Origin and path prefix of the ingest and backend URLs; exchanges under them are never captured. */
+    private readonly ownPrefixes;
+    private readonly oversizeReported;
+    private closeHooks;
+    private readonly exitHook;
+    constructor(options?: StubsmithOptions);
+    /** True once `close()` completed. */
+    get stopped(): boolean;
+    /** True when the first rules sync has completed. */
+    get rulesSynced(): boolean;
+    /**
+     * Resolves true once rules are loaded, false on timeout or when disabled.
+     * The wait holds the process open until it settles, even when the backend fails fast.
+     */
+    waitForRules(timeoutMs: number): Promise<boolean>;
+    /** Run `fn` from `close()` (the instrumentation uses this to unpatch). */
+    onClose(fn: () => void): void;
+    /**
+     * Mask one exchange and queue it. Synchronous and never throws. Cost is the
+     * privacy pipeline plus one `JSON.stringify` of the payload.
+     */
+    capture(ex: CapturedExchange): void;
+    private enqueue;
+    /**
+     * Both bodies go, together, when the payload is over the ceiling: a partial
+     * body is a sample that looks captured and is not. The shape is still
+     * recorded server-side. Warned once per `METHOD path_template`.
+     */
+    private omitBodies;
+    private isOwnUrl;
+    /** `bodies`: also wait for exchanges whose body is still being read (explicit flush/close only). */
+    private idle;
+    /** Start the single sender loop on the next macrotask when it is not running. */
+    private kick;
+    private pump;
+    /**
+     * A capture processed before the first rules sync was templated with ID grouping on, because the
+     * project's "Group IDs in paths automatically" setting was not yet known. The sender (never the
+     * capturing call) waits for the first sync, at most `StubsmithClient.firstSyncHoldMs` from client start, then templates
+     * the raw path again with the synced curated templates and setting. If the bound runs out the
+     * capture-time values stand. The wait ends when a flush starts (`flush()`, `close()` or the exit hook: a
+     * flush means send now, as before the hold existed) or `close()` stops the poller, and its timer is
+     * unref'd.
+     */
+    private resolveHeld;
+    private clearQueue;
+    /** POST one serialised capture. Failures are counted, never thrown. */
+    private send;
+    /**
+     * Resolve when no capture is pending, the queue and the in-flight send are
+     * empty, the timeout elapses, or a new send failure happened since the call
+     * started (the endpoint is unreachable, so waiting longer only costs the
+     * application). The poll timer is ref'd: the sender's sockets are not, so
+     * this is what keeps the process alive while it waits.
+     */
+    flush(opts?: FlushOptions): Promise<void>;
+    private waitIdle;
+    /**
+     * Stop the poller, flush (default 5 s, or `timeoutMs`; `STUBSMITH_FLUSH_TIMEOUT`
+     * is the exit-hook budget and does not apply here), abort a send still in
+     * flight, un-patch and mark stopped. Idempotent.
+     */
+    close(opts?: FlushOptions): Promise<void>;
+    private doClose;
+}
+
+/**
+ * Create the client and patch the hooks. Idempotent: returns the existing
+ * client while it is not stopped and ignores the new options.
+ */
+declare function install(options?: StubsmithOptions): StubsmithClient;
+/** True while an installed client exists and is not stopped. */
+declare function isInstalled(): boolean;
+
+declare const VERSION = "0.2.1";
+
+interface FixturesOptions {
+    /** Only `"status"`: at most one fixture per distinct HTTP status, newest first. */
+    distinct?: "status";
+    /** Maximum number of fixtures (1-100; server default 20). */
+    limit?: number;
+    /** Defaults to `STUBSMITH_API_URL`, then the hosted service. */
+    apiUrl?: string;
+    /** Defaults to `STUBSMITH_API_KEY`. */
+    apiKey?: string;
+}
+type Obj = Record<string, unknown>;
+/** Headers and body for one side (request or response) of a {@link Fixture}. */
+declare class FixtureSide {
+    readonly headers: Record<string, unknown>;
+    readonly body: string | null;
+    constructor(headers: Record<string, unknown> | null | undefined, body: string | null | undefined);
+    /** Parse `body` as JSON. Throws when the body is null or not valid JSON. */
+    json(): unknown;
+}
+/** One recorded HTTP exchange from `/v1/fixtures`. */
+declare class Fixture {
+    readonly id: string;
+    readonly capturedAt: string;
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly durationMs: number | null;
+    readonly request: FixtureSide;
+    readonly response: FixtureSide;
+    constructor(id: string, capturedAt: string, method: string, path: string, status: number, durationMs: number | null, request: FixtureSide, response: FixtureSide);
+    /** @internal */
+    static fromObject(d: unknown): Fixture;
+    toString(): string;
+}
+/** The full `/v1/fixtures` envelope. */
+declare class FixtureBundle {
+    readonly ok: boolean;
+    readonly requestType: Record<string, unknown> | null;
+    readonly fixtures: Fixture[];
+    readonly count: number;
+    constructor(data: Obj);
+    /** The fixture for `status`; throws an Error naming the statuses present when there is none. */
+    byStatus(status: number): Fixture;
+}
+/** Fetch the full `/v1/fixtures` envelope for `"METHOD /path"`. */
+declare function fixturesBundle(spec: string, opts?: FixturesOptions): Promise<FixtureBundle>;
+/** Fetch recorded fixtures for `"METHOD /path"`, newest first. */
+declare function fixtures(spec: string, opts?: FixturesOptions): Promise<Fixture[]>;
+
+/** One stored response sample inside a variant (bundle fetched with `samples > 1`), newest first. */
+interface BundleSample {
+    capture_id?: string | null;
+    captured_at?: string | null;
+    duration_ms?: number | null;
+    headers?: Record<string, string>;
+    /** A JSON-encoded string, or null. An object/array body is serialised like Python `json.dumps`. */
+    body?: string | null | object;
+    body_capped?: boolean;
+    body_encoding?: string | null;
+}
+/** One recorded response status of a stub. */
+interface BundleVariant {
+    status: number;
+    count: number;
+    duration_ms?: number | null;
+    headers?: Record<string, string>;
+    body?: string | null | object;
+    body_capped?: boolean;
+    body_encoding?: string | null;
+    samples?: BundleSample[];
+}
+/** One request shape (fingerprint) of an endpoint. */
+interface BundleStub {
+    fingerprint: string;
+    key_paths: string[];
+    query_names?: string[] | null;
+    content_type?: string | null;
+    field_rules?: unknown[];
+    degraded?: boolean;
+    variants: BundleVariant[];
+}
+interface BundleEndpoint {
+    domain: string;
+    method: string;
+    path_template: string;
+    is_dynamic?: boolean;
+    fingerprint_value_paths?: string[];
+    stubs: BundleStub[];
+}
+interface BundleTruncated {
+    stubs?: {
+        dropped: number;
+        limit: number;
+    };
+    variants?: Array<{
+        endpoint: string;
+        fingerprint: string;
+        dropped: number;
+        limit: number;
+    }>;
+    body_bytes?: {
+        capped: number;
+        limit: number;
+    };
+}
+/** The `.stubsmith/bundle.json` document produced by `stubsmith pull`. */
+interface Bundle {
+    ok?: boolean;
+    version?: number;
+    cursor?: string;
+    generated_at?: string;
+    truncated?: BundleTruncated;
+    /** Project settings as of the pull; absent in bundles from before the settings existed. */
+    project_settings?: {
+        group_ids_in_paths?: boolean;
+    };
+    endpoints: BundleEndpoint[];
+}
+/** Anything `replay()` accepts as a bundle: the typed schema, a loosely typed parsed document (such as `fetchBundle().bundle`), or a file path. */
+type BundleSource = Bundle | Record<string, unknown> | string;
+/** A bundle together with the file it was read from (null for an in-memory object). */
+interface ResolvedBundle {
+    bundle: Bundle;
+    path: string | null;
+}
+/** Load a bundle from an in-memory object (returned as-is) or a file path. */
+declare function loadBundle(source: BundleSource): Bundle;
+/**
+ * Resolve the bundle: the argument (object or path), else `$STUBSMITH_BUNDLE`,
+ * else `.stubsmith/bundle.json` searched upward from the working directory up
+ * to the first `.git` / `package.json` boundary. Throws when none is found.
+ */
+declare function resolveBundle(arg?: BundleSource | null): ResolvedBundle;
+
+interface FetchBundleOptions {
+    /** Recordings per response; above one (or `"all"`) needs an endpoint. */
+    samples?: number | "all" | string;
+    /** Defaults to `STUBSMITH_API_URL`, then `STUBSMITH_BACKEND_URL`, then the hosted service. */
+    apiUrl?: string;
+    /** Defaults to `STUBSMITH_API_KEY`. */
+    apiKey?: string;
+}
+interface PullBundleOptions {
+    /** Defaults to `STUBSMITH_API_URL`, then `STUBSMITH_BACKEND_URL`, then the hosted service. */
+    apiUrl?: string;
+    /** Defaults to `STUBSMITH_API_KEY`. */
+    apiKey?: string;
+    /** `"METHOD /path"` filters, one request each; omitted means one unfiltered request. */
+    endpoints?: string[];
+    /** Recordings per response; above one (or `"all"`) needs `endpoints`. */
+    samples?: number | "all" | string;
+    /** Called before each filtered request (the CLI prints progress). */
+    onFetch?: (method: string, path: string) => void;
+}
+interface BundleStubRef {
+    domain: string;
+    method: string;
+    pathTemplate: string;
+    fingerprint: string;
+}
+interface BundleSummary {
+    endpoints: number;
+    stubs: number;
+    variants: number;
+    /** Every stub the server marked degraded. */
+    degraded: BundleStubRef[];
+    /** Variants with `body_capped` set. */
+    bodyCapped: number;
+}
+interface PullBundleResult {
+    bundle: Bundle;
+    summary: BundleSummary;
+}
+/**
+ * Fetch the raw replay bundle for one request: the whole project, or the
+ * `"METHOD /path"` endpoint. Returned as the server sent it, unmerged and
+ * unsorted, so `replay(await fetchBundle())` works. Does not touch disk.
+ */
+declare function fetchBundle(endpoint?: string, opts?: FetchBundleOptions): Promise<Bundle>;
+/**
+ * Fetch the replay bundle, one request per endpoint (or one unfiltered
+ * request), merged and sorted. Does not touch disk.
+ */
+declare function pullBundle(opts?: PullBundleOptions): Promise<PullBundleResult>;
+
+/** Raised on a miss: the request matched no recorded stub. Replay never falls through to the network. */
+declare class StubNotFound extends Error {
+    readonly method: string;
+    readonly pathTemplate: string;
+    readonly fingerprint: string;
+    constructor(method: string, pathTemplate: string, fingerprint: string, message?: string);
+}
+/** What the engine needs to know about an outbound request. */
+interface ReplayRequest {
+    method: string;
+    /** Absolute URL, query string included. */
+    url: string;
+    /** Header names are matched case-insensitively; only `content-type` is read. */
+    headers?: Record<string, string | string[] | number | undefined> | null;
+    /** Bytes are decoded as UTF-8 (an undecodable body counts as empty). */
+    body?: string | Uint8Array | null;
+}
+/**
+ * One recorded response, as handed to a `select` callback: a variant (or one
+ * sample of a variant) flattened to the unit a test iterates.
+ */
+interface RecordedResponse {
+    status: number;
+    /** How often the variant's status was observed. */
+    count: number;
+    durationMs: number | null;
+    headers: Record<string, string>;
+    /** The stored body: a JSON-encoded string, null, or an object/array. */
+    body: unknown;
+    bodyEncoding: string | null;
+    captureId: string | null;
+    capturedAt: string | null;
+    bodyCapped: boolean;
+}
+/**
+ * Chooses which recorded response to serve. Receives the shape's recordings,
+ * newest first within each status and ordered so the default choice is first.
+ * Return one of them, or null to force a {@link StubNotFound}.
+ */
+type SelectFn = (responses: RecordedResponse[]) => RecordedResponse | null | undefined;
+/** A `select` that serves the first (newest) recording of `status`, or null when none exists. */
+declare function byStatus(status: number): SelectFn;
+/** The response the engine hands to a transport hook. */
+interface ServedPayload {
+    status: number;
+    statusText: string;
+    /** Recorded headers minus hop-by-hop ones. */
+    headers: Record<string, string>;
+    body: Uint8Array;
+    durationMs: number;
+}
+/** One recorded response a replay context served. */
+declare class ServedResponse {
+    readonly domain: string;
+    readonly method: string;
+    readonly pathTemplate: string;
+    readonly fingerprint: string;
+    readonly status: number;
+    readonly captureId: string | null;
+    readonly capturedAt: string | null;
+    /** Position of this response in its stub's recorded list. */
+    readonly index: number;
+    /** How many responses that stub has recorded in total. */
+    readonly total: number;
+    constructor(domain: string, method: string, pathTemplate: string, fingerprint: string, status: number, captureId: string | null, capturedAt: string | null, 
+    /** Position of this response in its stub's recorded list. */
+    index: number, 
+    /** How many responses that stub has recorded in total. */
+    total: number);
+    /** `"GET api.example.com/v1/orders/{id}"`, for test ids and messages. */
+    get endpoint(): string;
+    /** True when this was the last recorded response for its stub (a clamped repeat, not a new recording). */
+    get exhausted(): boolean;
+}
+type StubKey = readonly [string, string, string, string];
+/**
+ * Cursor shared by the contexts `replayAll` yields. One cursor per request
+ * shape (stub key), not one global pass index: which shapes a pass touches is
+ * only discovered by running the caller's code, and a shape found late must
+ * still be looped from its first recording. Each shape advances once per pass,
+ * from the pass on which it was first served.
+ */
+declare class PassState {
+    /** 0-based index of the current pass. */
+    passNo: number;
+    private readonly cursors;
+    private readonly totals;
+    private readonly servedPairs;
+    private touched;
+    /**
+     * Which recording this shape serves in the current pass. Fixed for the whole
+     * pass: a shape called twice in one pass serves the same recording both times.
+     */
+    indexFor(stubKey: StubKey, total: number): number;
+    /** End the pass; returns whether another is needed. */
+    advance(): boolean;
+}
+interface ReplayEngineOptions {
+    select?: SelectFn;
+    /** Serve only recordings with one of these statuses (used by `replayAll`). */
+    statuses?: Iterable<number>;
+    /** Cursor shared across passes (used by `replayAll`). */
+    passState?: PassState;
+    /** File the bundle came from; appended to miss messages. */
+    bundlePath?: string | null;
+}
+/** The result of matching a request: the stub key and its ordered recordings. */
+interface Match {
+    stubKey: StubKey;
+    responses: RecordedResponse[];
+}
+/** Matches requests against a bundle and builds responses. Holds only the list of what it served. */
+declare class ReplayEngine {
+    readonly bundlePath: string | null;
+    private readonly index;
+    /** The project's "Group IDs in paths automatically" setting as of the pull; only an explicit false turns it off. */
+    private readonly groupIds;
+    private readonly select;
+    private readonly statuses;
+    private readonly passState;
+    private readonly log;
+    constructor(bundle: Bundle, opts?: ReplayEngineOptions);
+    /** 1-based pass number under `replayAll`, else 1. */
+    get passNumber(): number;
+    /** Every response served through this engine, in call order. */
+    served(): ServedResponse[];
+    private fail;
+    /** Find the stub for `request`. Throws {@link StubNotFound} on a miss; never reaches the network. */
+    match(request: ReplayRequest): Match;
+    private choose;
+    /** Match `request`, pick the recording, record it in `served()` and build the response. */
+    serve(request: ReplayRequest): ServedPayload;
+}
+
+/**
+ * An active replay: while it is not restored, outbound `http`, `https` and
+ * `fetch` calls are answered from the bundle and never reach the network, and
+ * capture is suppressed. Create one with `replay()` or take one from `replayAll()`.
+ *
+ * Restore contexts in reverse order of creation. Also usable with
+ * `using` / `await using`: `[Symbol.dispose]()` and `[Symbol.asyncDispose]()`
+ * call `restore()`. The methods are attached only where the runtime defines
+ * the symbols, which every supported Node version does.
+ */
+declare class ReplayContext {
+    private readonly engine;
+    /** 0-based pass index under `replayAll()`, else 0. */
+    readonly passIndex: number;
+    private readonly installation;
+    /** @internal Use `replay()` / `replayAll()`. Installs the hooks immediately. */
+    constructor(engine: ReplayEngine, 
+    /** 0-based pass index under `replayAll()`, else 0. */
+    passIndex?: number);
+    /** File the bundle was loaded from, or null for an in-memory bundle. */
+    get bundlePath(): string | null;
+    /** 1-based pass number under `replayAll()`, else 1. */
+    get passNumber(): number;
+    /** True until `restore()` is called. */
+    get active(): boolean;
+    /**
+     * Every response served through this context, in call order. Repeated calls
+     * to the same endpoint appear once per call. Use it to assert coverage
+     * instead of trusting that the code under test reached what you expected.
+     */
+    served(): ServedResponse[];
+    /** Put the original `http`, `https` and `fetch` functions back and re-enable capture. Idempotent. */
+    restore(): void;
+}
+interface ReplayContext extends Disposable, AsyncDisposable {
+}
+
+interface ReplayAllOptions {
+    /** As for `replay()`: a bundle object, a path, or omitted to resolve `$STUBSMITH_BUNDLE` / `.stubsmith/bundle.json`. */
+    bundle?: BundleSource;
+    /**
+     * Loop only recordings whose response status is in this set, e.g. `[200]` or
+     * `[429, 500]`. Undefined loops every recording.
+     *
+     * Usually what you want: it decides what a red build means. Unfiltered, one
+     * test body has to hold for successes and failures alike, and a status that
+     * enters the window later breaks assertions written when only the other kind
+     * existed. A shape with recordings but none of the requested status throws
+     * `StubNotFound` naming the filter and the statuses it does have, rather
+     * than substituting another status. Under a filter the first pass no longer
+     * matches plain `replay()`, whose choice may not be in the set.
+     */
+    statuses?: Iterable<number>;
+    /**
+     * Hard ceiling on passes, as a backstop (default 64). Unfiltered, the pass
+     * count is the largest recorded window among the shapes touched, roughly
+     * (samples per status) x (distinct statuses), so it grows with traffic
+     * without any code change; a `statuses` filter bounds it to one status's window.
+     */
+    maxPasses?: number;
+}
+/**
+ * Run a block once per recorded response, to exercise the whole recorded window
+ * rather than the one response plain `replay()` serves:
+ *
+ * ```ts
+ * for await (const pass of replayAll({ statuses: [500, 502] })) {
+ *   await expect(connector.syncOrders()).rejects.toThrow(UpstreamUnavailable);
+ *   console.log(pass.passNumber, pass.served());
+ * }
+ * ```
+ *
+ * Each iteration yields an active `ReplayContext` (hooks installed for the loop
+ * body, restored when the body finishes, throws, or `break`s). Semantics:
+ *
+ * - Pass one serves exactly what `replay()` serves (without a `statuses`
+ *   filter); pass two serves the next recording of every shape, and so on.
+ *   A shape's recordings are ordered primary status first (most frequent, then
+ *   lowest status), then the other statuses ascending, samples newest first.
+ * - Endpoints are never named. There is one cursor per request shape, fixed
+ *   within a pass (a shape called twice in a pass serves the same recording
+ *   both times) and advanced once per pass for the shapes touched in that pass.
+ *   A shape first reached on a later pass is still looped from its first
+ *   recording.
+ * - A shape with fewer recordings than the current pass keeps serving its last
+ *   one (clamped) rather than throwing; check `served()[i].exhausted` to tell.
+ * - The loop stops when no touched shape has an unseen recording left, or after
+ *   `maxPasses`.
+ * - The body runs against a different recording each pass, so write assertions
+ *   that hold for the whole range you are looping, or filter with `statuses`.
+ *
+ * A bundle with one recording per status (a default `stubsmith pull`) yields one
+ * pass per status; for several recordings per status pull with `--samples all`.
+ *
+ * Misconfiguration (`maxPasses` below 1, an unreadable bundle) throws from this
+ * call, before the first iteration.
+ */
+declare function replayAll(opts?: ReplayAllOptions): AsyncGenerator<ReplayContext, void, undefined>;
+
+interface ReplayOptions {
+    /** A bundle object, a path, or omitted to resolve `$STUBSMITH_BUNDLE` / `.stubsmith/bundle.json` upward from the cwd. */
+    bundle?: BundleSource;
+    /**
+     * Chooses which recorded response to serve. Receives the shape's recordings,
+     * newest first within each status and ordered so the default choice is first;
+     * return one of them, or null to force a `StubNotFound`. The default serves
+     * the first: the newest recording of the most frequent status. `byStatus(n)`
+     * covers the common case; to loop every recording use `replayAll()`.
+     */
+    select?: SelectFn;
+    /** Only `"strict"` exists: every miss throws `StubNotFound`. */
+    onMiss?: "strict";
+}
+/**
+ * Answer outbound `http`, `https` and `fetch` calls from the recorded bundle,
+ * without touching the network, until `restore()` is called. Capture is
+ * suppressed while any replay is active.
+ *
+ * ```ts
+ * const r = replay();
+ * try { await checkout(cart); } finally { r.restore(); }
+ * ```
+ *
+ * Throws when the bundle cannot be located or parsed, before any hook is installed.
+ */
+declare function replay(opts?: ReplayOptions): ReplayContext;
+
+declare const _default: {
+    install: typeof install;
+    isInstalled: typeof isInstalled;
+    VERSION: string;
+};
+
+export { Fixture, FixtureBundle, PrivacyPipeline, ReplayContext, ServedResponse, StubNotFound, StubsmithClient, VERSION, byStatus, _default as default, fetchBundle, fixtures, fixturesBundle, install, isInstalled, loadBundle, pullBundle, replay, replayAll, resolveBundle };
+export type { Bundle, BundleEndpoint, BundleSample, BundleSource, BundleStub, BundleSummary, BundleTruncated, BundleVariant, CaptureSource, CapturedExchange, FetchBundleOptions, FixturesOptions, FlushOptions, HeaderRecord, PullBundleOptions, PullBundleResult, RecordedResponse, ReplayAllOptions, ReplayOptions, SelectFn, StubsmithOptions };