@zimic/interceptor/dist/http.d.ts

Next-gen TypeScript-first HTTP intercepting and mocking

import { HttpMethodSchema, HttpRequest, HttpHeaders, HttpRequestHeadersSchema, InferPathParams, HttpSearchParams, HttpRequestSearchParamsSchema, HttpRequestBodySchema, HttpStatusCode, HttpResponseSchema, HttpResponseBodySchema, HttpHeadersInit, HttpResponse, HttpResponseHeadersSchema, HttpSchema, HttpBody, HttpSchemaMethod, HttpSchemaPath, HttpHeadersSchema, HttpSearchParamsSchema, HttpFormData, HttpResponseSchemaStatusCode, HttpMethod, LiteralHttpSchemaPathFromNonLiteral } from '@zimic/http';

/**
 * An error thrown when the interceptor is running and some operation requires it to be stopped first.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstart `interceptor.start()` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstop `interceptor.stop()` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorisrunning `interceptor.isRunning` API reference}
 */
declare class RunningHttpInterceptorError extends Error {
    constructor(additionalMessage: string);
}

/**
 * An error thrown when the interceptor is not running and it's not possible to use the mocking utilities.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstart `interceptor.start()` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstop `interceptor.stop()` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorisrunning `interceptor.isRunning` API reference}
 */
declare class NotRunningHttpInterceptorError extends Error {
    constructor();
}

/**
 * An error thrown when an unknown interceptor platform is detected. Currently, the platforms `node` and `browser` are
 * supported.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorplatform `interceptor.platform` API reference}
 */
declare class UnknownHttpInterceptorPlatformError extends Error {
    constructor();
}

declare class UnknownHttpInterceptorTypeError extends TypeError {
    constructor(unknownType: unknown);
}

/**
 * Error thrown when the safe limit of saved intercepted requests is exceeded.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor` API reference}
 */
declare class RequestSavingSafeLimitExceededError extends TypeError {
    constructor(numberOfSavedRequests: number, safeLimit: number);
}

/**
 * Error thrown when a value is not valid {@link https://developer.mozilla.org/docs/Web/API/FormData FormData}. HTTP
 * interceptors might throw this error when trying to parse the body of a request or response with the header
 * `'content-type': 'multipart/form-data'`, if the content cannot be parsed to form data.
 */
declare class InvalidFormDataError extends SyntaxError {
    constructor(value: string);
}

/**
 * Error thrown when a value is not valid JSON. HTTP interceptors might throw this error when trying to parse the body
 * of a request or response with the header `'content-type': 'application/json'`, if the content cannot be parsed to
 * JSON.
 */
declare class InvalidJSONError extends SyntaxError {
    constructor(value: string);
}

/**
 * An error thrown when the browser mock service worker is not found.
 *
 * @see {@link https://zimic.dev/docs/interceptor/cli/browser#zimic-interceptor-browser-init `zimic-interceptor browser init` API reference}
 */
declare class UnregisteredBrowserServiceWorkerError extends Error {
    constructor();
    static matchesRawError(error: unknown): boolean;
}

/**
 * Error thrown when trying to access requests when the interceptor is not configured to do so.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor` API reference}
 */
declare class DisabledRequestSavingError extends TypeError {
    constructor();
}

type Default<Type, IfEmpty = never> = [undefined | void] extends [Type] ? IfEmpty : Exclude<Type, undefined | void>;
type IfNever<Type, Yes, No = Type> = [Type] extends [never] ? Yes : No;
type PossiblePromise<Type> = Type | PromiseLike<Type>;
type ReplaceBy<Type, Source, Target> = Type extends Source ? Target : Type;
type PartialByKey<Type, Key extends keyof Type> = Omit<Type, Key> & Partial<Pick<Type, Key>>;
type DeepPartial<Type> = Type extends (...parameters: never[]) => unknown ? Type : Type extends (infer ArrayItem)[] ? DeepPartial<ArrayItem>[] : Type extends object ? {
    [Key in keyof Type]?: DeepPartial<Type[Key]>;
} : Type;
interface Range<Type> {
    min: Type;
    max: Type;
}

type HttpRequestHandlerResponseBody<ResponseSchema extends HttpResponseSchema, StatusCode extends HttpStatusCode> = HttpResponseBodySchema<{
    response: {
        [Code in StatusCode]: ResponseSchema;
    };
}, StatusCode>;
type HttpRequestHandlerResponseWithBody<ResponseSchema extends HttpResponseSchema, StatusCode extends HttpStatusCode> = unknown extends ResponseSchema['body'] ? {
    body?: null;
} : undefined extends ResponseSchema['body'] ? {
    body?: HttpRequestHandlerResponseBody<ResponseSchema, StatusCode>;
} : {
    body: HttpRequestHandlerResponseBody<ResponseSchema, StatusCode>;
};
type HttpRequestHandlerResponseDeclarationHeaders<ResponseSchema extends HttpResponseSchema> = HttpHeadersInit<PartialByKey<Default<ResponseSchema['headers']>, 'content-type'>>;
type HttpRequestHandlerResponseDeclarationWithHeaders<ResponseSchema extends HttpResponseSchema> = undefined extends ResponseSchema['headers'] ? {
    headers?: HttpRequestHandlerResponseDeclarationHeaders<ResponseSchema>;
} : Exclude<keyof ResponseSchema['headers'], symbol> extends 'content-type' ? {
    headers?: HttpRequestHandlerResponseDeclarationHeaders<ResponseSchema>;
} : {
    headers: HttpRequestHandlerResponseDeclarationHeaders<ResponseSchema>;
};
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrespond `handler.respond()` API reference} */
type HttpRequestHandlerResponseDeclaration<MethodSchema extends HttpMethodSchema = HttpMethodSchema, StatusCode extends HttpStatusCode = HttpStatusCode> = StatusCode extends StatusCode ? {
    status: StatusCode;
} & HttpRequestHandlerResponseWithBody<Default<Default<MethodSchema['response']>[StatusCode]>, StatusCode> & HttpRequestHandlerResponseDeclarationWithHeaders<Default<Default<MethodSchema['response']>[StatusCode]>> : never;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrespond `handler.respond()` API reference} */
type HttpRequestHandlerResponseDeclarationFactory<Path extends string, MethodSchema extends HttpMethodSchema, StatusCode extends HttpStatusCode = HttpStatusCode> = (request: Omit<HttpInterceptorRequest<Path, MethodSchema>, 'response'>) => PossiblePromise<HttpRequestHandlerResponseDeclaration<MethodSchema, StatusCode>>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrequests `handler.requests` API reference} */
interface HttpInterceptorRequest<Path extends string, MethodSchema extends HttpMethodSchema> extends Omit<HttpRequest, keyof Body | 'headers' | 'clone'> {
    /**
     * The headers of the request.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/headers#using-request-headers Using request headers}
     */
    headers: HttpHeaders<Default<HttpRequestHeadersSchema<MethodSchema>>>;
    /**
     * The path parameters of the request. They are parsed from the path string when using dynamic paths.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/path-params#using-request-path-params Using request path parameters}
     */
    pathParams: InferPathParams<Path>;
    /**
     * The search parameters of the request.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/search-params#using-request-search-params Using request search parameters}
     */
    searchParams: HttpSearchParams<Default<HttpRequestSearchParamsSchema<MethodSchema>>>;
    /**
     * The body of the request. It is already parsed by default as detailed in
     * {@link https://zimic.dev/docs/interceptor/guides/http/bodies#default-body-parsing Default body parsing}.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/bodies#using-request-bodies Using request bodies}
     */
    body: ReplaceBy<HttpRequestBodySchema<MethodSchema>, ArrayBuffer | ReadableStream, Blob>;
    /** The raw request object. */
    raw: HttpRequest<HttpRequestBodySchema<MethodSchema>, Default<HttpRequestHeadersSchema<MethodSchema>>>;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrequests `handler.requests` API reference} */
interface HttpInterceptorResponse<MethodSchema extends HttpMethodSchema, StatusCode extends HttpStatusCode> extends Omit<HttpResponse, keyof Body | 'headers' | 'clone'> {
    /**
     * The headers of the response.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/headers#using-response-headers Using response headers}
     */
    headers: HttpHeaders<Default<HttpResponseHeadersSchema<MethodSchema, StatusCode>>>;
    /** The status code of the response. */
    status: StatusCode;
    /**
     * The body of the response. It is already parsed by default as detailed in
     * {@link https://zimic.dev/docs/interceptor/guides/http/bodies#default-body-parsing Default body parsing}.
     *
     * @see {@link https://zimic.dev/docs/interceptor/guides/http/bodies#using-response-bodies Using response bodies}
     */
    body: ReplaceBy<HttpResponseBodySchema<MethodSchema, StatusCode>, ArrayBuffer | ReadableStream, Blob>;
    /** The raw response object. */
    raw: HttpResponse<HttpResponseBodySchema<MethodSchema, StatusCode>, Default<HttpResponseHeadersSchema<MethodSchema, StatusCode>>, StatusCode>;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrequests `handler.requests` API reference} */
interface InterceptedHttpInterceptorRequest<Path extends string, MethodSchema extends HttpMethodSchema, StatusCode extends HttpStatusCode = never> extends HttpInterceptorRequest<Path, MethodSchema> {
    /** The response that was returned for the intercepted request. */
    response: StatusCode extends [never] ? never : HttpInterceptorResponse<MethodSchema, StatusCode>;
}

type UnhandledHttpInterceptorRequestMethodSchema = HttpSchema.Method<{
    request: {
        headers: Record<string, string>;
        searchParams: Record<string, string | string[]>;
        body: HttpBody;
    };
}>;
type UnhandledHttpInterceptorRequest = Omit<HttpInterceptorRequest<string, UnhandledHttpInterceptorRequestMethodSchema>, 'response'>;

/** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptortype `interceptor.type` API reference} */
type HttpInterceptorType = 'local' | 'remote';
/** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorplatform `interceptor.platform` API reference} */
type HttpInterceptorPlatform = 'node' | 'browser';
/** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
declare namespace UnhandledRequestStrategy {
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type Action = 'bypass' | 'reject';
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    interface Declaration<DeclarationAction extends Action = Action> {
        /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
        action: DeclarationAction;
        /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
        log?: boolean;
    }
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type DeclarationFactory<DeclarationAction extends Action = Action> = (request: UnhandledHttpInterceptorRequest) => PossiblePromise<Declaration<DeclarationAction>>;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type LocalDeclaration = Declaration;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type LocalDeclarationFactory = DeclarationFactory;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type RemoteDeclaration = Declaration<'reject'>;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type RemoteDeclarationFactory = DeclarationFactory<'reject'>;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type Local = LocalDeclaration | LocalDeclarationFactory;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    type Remote = RemoteDeclaration | RemoteDeclarationFactory;
}
type UnhandledRequestStrategy = UnhandledRequestStrategy.Local | UnhandledRequestStrategy.Remote;
interface SharedHttpInterceptorOptions {
    /** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference} */
    type?: HttpInterceptorType;
    /** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference} */
    baseURL: string;
    /** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference} */
    requestSaving?: Partial<HttpInterceptorRequestSaving>;
}
/**
 * @see {@link https://zimic.dev/docs/interceptor/guides/http/local-interceptors#creating-a-local-http-interceptor Creating a local HTTP interceptor}
 * @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference}
 */
interface LocalHttpInterceptorOptions extends SharedHttpInterceptorOptions {
    type?: 'local';
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    onUnhandledRequest?: UnhandledRequestStrategy.Local;
}
interface HttpInterceptorAuthOptions {
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/remote-interceptors#interceptor-server-authentication Interceptor server authentication} */
    token: string;
}
/**
 * @see {@link https://zimic.dev/docs/interceptor/guides/http/remote-interceptors#creating-a-remote-http-interceptor Creating a remote HTTP interceptor}
 * @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference}
 */
interface RemoteHttpInterceptorOptions extends SharedHttpInterceptorOptions {
    type: 'remote';
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/remote-interceptors#interceptor-server-authentication Interceptor server authentication} */
    auth?: HttpInterceptorAuthOptions;
    /** @see {@link https://zimic.dev/docs/interceptor/guides/http/unhandled-requests Unhandled requests} */
    onUnhandledRequest?: UnhandledRequestStrategy.Remote;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference} */
type HttpInterceptorOptions = LocalHttpInterceptorOptions | RemoteHttpInterceptorOptions;

type PartialHttpHeadersOrSchema<Schema extends HttpHeadersSchema.Loose> = IfNever<Schema, never, Partial<Schema> | HttpHeaders<Partial<Schema>> | HttpHeaders<Schema>>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
type HttpRequestHandlerHeadersStaticRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> = PartialHttpHeadersOrSchema<Default<HttpRequestHeadersSchema<Default<Schema[Path][Method]>>>>;
type PartialHttpSearchParamsOrSchema<Schema extends HttpSearchParamsSchema.Loose> = IfNever<Schema, never, Partial<Schema> | HttpSearchParams<Partial<Schema>> | HttpSearchParams<Schema>>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
type HttpRequestHandlerSearchParamsStaticRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> = PartialHttpSearchParamsOrSchema<Default<HttpRequestSearchParamsSchema<Default<Schema[Path][Method]>>>>;
type PartialBodyOrSchema<Body extends HttpBody> = Body extends HttpFormData<infer Schema> ? HttpFormData<Partial<Schema>> | HttpFormData<Schema> : Body extends HttpSearchParams<infer Schema> ? HttpSearchParams<Partial<Schema>> | HttpSearchParams<Schema> : Body extends Blob ? Body : Body extends ArrayBuffer ? Body : Body extends ReadableStream ? Body : DeepPartial<Body>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
type HttpRequestHandlerBodyStaticRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> = PartialBodyOrSchema<HttpRequestBodySchema<Default<Schema[Path][Method]>>>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
interface HttpRequestHandlerStaticRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> {
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    headers?: HttpRequestHandlerHeadersStaticRestriction<Schema, Method, Path>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    searchParams?: HttpRequestHandlerSearchParamsStaticRestriction<Schema, Method, Path>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    body?: HttpRequestHandlerBodyStaticRestriction<Schema, Method, Path>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    exact?: boolean;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
type HttpRequestHandlerComputedRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> = (request: HttpInterceptorRequest<Path, Default<Schema[Path][Method]>>) => PossiblePromise<boolean>;
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
type HttpRequestHandlerRestriction<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> = HttpRequestHandlerStaticRestriction<Schema, Method, Path> | HttpRequestHandlerComputedRestriction<Schema, Method, Path>;
interface RestrictionDiff<Value> {
    expected: Value;
    received: Value;
}
interface RestrictionDiffs {
    computed?: RestrictionDiff<boolean>;
    headers?: RestrictionDiff<HttpHeaders<any>>;
    searchParams?: RestrictionDiff<HttpSearchParams<any>>;
    body?: RestrictionDiff<unknown>;
}
interface UnmatchedHttpInterceptorRequestGroup {
    request: HttpInterceptorRequest<string, never>;
    diff: RestrictionDiffs;
}

/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler `HttpRequestHandler` API reference} */
interface HttpRequestHandler<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>> {
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlermethod `handler.method` API reference}
     */
    get method(): Method;
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerpath `handler.path` API reference}
     */
    get path(): Path;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler `HttpRequestHandler` API reference} */
interface LocalHttpRequestHandler<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>, StatusCode extends HttpStatusCode = never> extends HttpRequestHandler<Schema, Method, Path> {
    /** @readonly */
    get type(): 'local';
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    with: (restriction: HttpRequestHandlerRestriction<Schema, Method, Path>) => this;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrespond `handler.respond()` API reference} */
    respond: <NewStatusCode extends HttpResponseSchemaStatusCode<Default<Default<Schema[Path][Method]>['response']>>>(declaration: HttpRequestHandlerResponseDeclaration<Default<Schema[Path][Method]>, NewStatusCode> | HttpRequestHandlerResponseDeclarationFactory<Path, Default<Schema[Path][Method]>, NewStatusCode>) => LocalHttpRequestHandler<Schema, Method, Path, NewStatusCode>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlertimes `handler.times()` API reference} */
    times: ((numberOfRequests: number) => this) & ((minNumberOfRequests: number, maxNumberOfRequests: number) => this);
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerchecktimes `handler.checkTimes()` API reference} */
    checkTimes: () => void;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerclear `handler.clear()` API reference} */
    clear: () => this;
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrequests `handler.requests` API reference}
     */
    get requests(): readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
}
/**
 * A synced remote HTTP request handler. When a remote handler is synced, it is guaranteed that all of the mocking
 * operations were committed to the connected {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler `HttpRequestHandler` API reference}
 */
interface SyncedRemoteHttpRequestHandler<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>, StatusCode extends HttpStatusCode = never> extends HttpRequestHandler<Schema, Method, Path> {
    /** @readonly */
    get type(): 'remote';
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerwithrestriction `handler.with()` API reference} */
    with: (restriction: HttpRequestHandlerRestriction<Schema, Method, Path>) => PendingRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrespond `handler.respond()` API reference} */
    respond: <NewStatusCode extends HttpResponseSchemaStatusCode<Default<Default<Schema[Path][Method]>['response']>>>(declaration: HttpRequestHandlerResponseDeclaration<Default<Schema[Path][Method]>, NewStatusCode> | HttpRequestHandlerResponseDeclarationFactory<Path, Default<Schema[Path][Method]>, NewStatusCode>) => PendingRemoteHttpRequestHandler<Schema, Method, Path, NewStatusCode>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlertimes `handler.times()` API reference} */
    times: ((numberOfRequests: number) => PendingRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>) & ((minNumberOfRequests: number, maxNumberOfRequests: number) => PendingRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>);
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerchecktimes `handler.checkTimes()` API reference} */
    checkTimes: () => Promise<void>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerclear `handler.clear()` API reference} */
    clear: () => PendingRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>;
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler#handlerrequests `handler.requests` API reference}
     */
    get requests(): readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
}
/**
 * A pending remote HTTP request handler. When a remote handler is pending, it is not guaranteed that all of the mocking
 * operations were committed to the connected {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
 *
 * To commit a remote interceptor, you can `await` it or use the methods {@link then handler.then()},
 * {@link catch handler.catch()}, and {@link finally handler.finally()}.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler `HttpRequestHandler` API reference}
 */
interface PendingRemoteHttpRequestHandler<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>, StatusCode extends HttpStatusCode = never> extends SyncedRemoteHttpRequestHandler<Schema, Method, Path, StatusCode> {
    /**
     * Waits for the remote handler to be synced with the connected
     * {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
     */
    then: <FulfilledResult = SyncedRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>, RejectedResult = never>(onFulfilled?: ((handler: SyncedRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>) => PossiblePromise<FulfilledResult>) | null, onRejected?: ((reason: unknown) => PossiblePromise<RejectedResult>) | null) => Promise<FulfilledResult | RejectedResult>;
    /**
     * Waits for the remote handler to be synced with the connected
     * {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
     */
    catch: <RejectedResult = never>(onRejected?: ((reason: unknown) => PossiblePromise<RejectedResult>) | null) => Promise<SyncedRemoteHttpRequestHandler<Schema, Method, Path, StatusCode> | RejectedResult>;
    /**
     * Waits for the remote handler to be synced with the connected
     * {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
     */
    finally: (onFinally?: (() => void) | null) => Promise<SyncedRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>>;
}
/**
 * A remote HTTP request handler to declare responses for intercepted requests. In a remote handler, the mocking
 * operations are asynchronous and include remote calls to the connected
 * {@link https://zimic.dev/docs/interceptor/cli/server interceptor server}.
 *
 * When multiple handlers of the same interceptor match the same method and path, the _last_ handler created with
 * {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptormethodpath `interceptor.<method>(path)`}
 * will be used.
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-request-handler `HttpRequestHandler` API reference}
 */
type RemoteHttpRequestHandler<Schema extends HttpSchema, Method extends HttpSchemaMethod<Schema>, Path extends HttpSchemaPath<Schema, Method>, StatusCode extends HttpStatusCode = never> = PendingRemoteHttpRequestHandler<Schema, Method, Path, StatusCode>;

type SyncHttpInterceptorMethodHandler<Schema extends HttpSchema, Method extends HttpMethod> = Method extends HttpSchemaMethod<Schema> ? <Path extends HttpSchemaPath.NonLiteral<Schema, Method>>(path: Path) => LocalHttpRequestHandler<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>> : (path: never) => LocalHttpRequestHandler<any, any, never>;
type AsyncHttpInterceptorMethodHandler<Schema extends HttpSchema, Method extends HttpMethod> = Method extends HttpSchemaMethod<Schema> ? <Path extends HttpSchemaPath.NonLiteral<Schema, Method>>(path: Path) => RemoteHttpRequestHandler<Schema, Method, LiteralHttpSchemaPathFromNonLiteral<Schema, Method, Path>> : (path: never) => RemoteHttpRequestHandler<any, any, never>;

/** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor` API reference} */
interface HttpInterceptorRequestSaving {
    /** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor` API reference} */
    enabled: boolean;
    /** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor` API reference} */
    safeLimit: number;
}
/** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor `HttpInterceptor` API reference} */
interface HttpInterceptor<_Schema extends HttpSchema> {
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorbaseurl `interceptor.baseURL` API reference} */
    baseURL: string;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorrequestsaving `interceptor.requestSaving` API reference} */
    requestSaving: HttpInterceptorRequestSaving;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptoronunhandledrequest `interceptor.onUnhandledRequest` API reference} */
    onUnhandledRequest?: UnhandledRequestStrategy;
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorplatform `interceptor.platform` API reference}
     */
    get platform(): HttpInterceptorPlatform | null;
    /**
     * @readonly
     * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorisrunning `interceptor.isRunning` API reference}
     */
    get isRunning(): boolean;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstart `interceptor.start()` API reference} */
    start: () => Promise<void>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorstop `interceptor.stop()` API reference} */
    stop: () => Promise<void>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorchecktimes `interceptor.checkTimes()` API reference} */
    checkTimes: (() => void) | (() => Promise<void>);
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorclear `interceptor.clear()` API reference} */
    clear: (() => void) | (() => Promise<void>);
}
/**
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor `HttpInterceptor` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/guides/http/local-interceptors Using local interceptors}
 */
interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInterceptor<Schema> {
    /** @readonly */
    get type(): 'local';
    onUnhandledRequest?: UnhandledRequestStrategy.Local;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorget `interceptor.get()` API reference} */
    get: SyncHttpInterceptorMethodHandler<Schema, 'GET'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorpost `interceptor.post()` API reference} */
    post: SyncHttpInterceptorMethodHandler<Schema, 'POST'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorpatch `interceptor.patch()` API reference} */
    patch: SyncHttpInterceptorMethodHandler<Schema, 'PATCH'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorput `interceptor.put()` API reference} */
    put: SyncHttpInterceptorMethodHandler<Schema, 'PUT'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptordelete `interceptor.delete()` API reference} */
    delete: SyncHttpInterceptorMethodHandler<Schema, 'DELETE'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorhead `interceptor.head()` API reference} */
    head: SyncHttpInterceptorMethodHandler<Schema, 'HEAD'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptoroptions `interceptor.options()` API reference} */
    options: SyncHttpInterceptorMethodHandler<Schema, 'OPTIONS'>;
    checkTimes: () => void;
    clear: () => void;
}
/**
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor `HttpInterceptor` API reference}
 * @see {@link https://zimic.dev/docs/interceptor/guides/http/remote-interceptors Using remote interceptors}
 */
interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpInterceptor<Schema> {
    /** @readonly */
    get type(): 'remote';
    onUnhandledRequest?: UnhandledRequestStrategy.Remote;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorauth `interceptor.auth` API reference} */
    auth?: RemoteHttpInterceptorOptions['auth'];
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorget `interceptor.get()` API reference} */
    get: AsyncHttpInterceptorMethodHandler<Schema, 'GET'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorpost `interceptor.post()` API reference} */
    post: AsyncHttpInterceptorMethodHandler<Schema, 'POST'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorpatch `interceptor.patch()` API reference} */
    patch: AsyncHttpInterceptorMethodHandler<Schema, 'PATCH'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorput `interceptor.put()` API reference} */
    put: AsyncHttpInterceptorMethodHandler<Schema, 'PUT'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptordelete `interceptor.delete()` API reference} */
    delete: AsyncHttpInterceptorMethodHandler<Schema, 'DELETE'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptorhead `interceptor.head()` API reference} */
    head: AsyncHttpInterceptorMethodHandler<Schema, 'HEAD'>;
    /** @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor#interceptoroptions `interceptor.options()` API reference} */
    options: AsyncHttpInterceptorMethodHandler<Schema, 'OPTIONS'>;
    checkTimes: () => Promise<void>;
    clear: () => Promise<void>;
}

declare class TimesDeclarationPointer extends Error {
    constructor(minNumberOfRequests: number, maxNumberOfRequests?: number);
}

interface TimesCheckErrorOptions {
    requestLimits: Range<number>;
    numberOfMatchedRequests: number;
    declarationPointer: TimesDeclarationPointer | undefined;
    unmatchedRequestGroups: UnmatchedHttpInterceptorRequestGroup[];
    hasRestrictions: boolean;
    requestSaving: HttpInterceptorRequestSaving;
}
declare class TimesCheckError extends TypeError {
    constructor(options: TimesCheckErrorOptions);
}

/**
 * Infers the schema of an {@link https://zimic.dev/docs/interceptor/api/http-interceptor `HttpInterceptor`}.
 *
 * @example
 *   import { type InferHttpInterceptorSchema } from '@zimic/http';
 *
 *   const interceptor = createHttpInterceptor<{
 *     '/users': {
 *       GET: {
 *         response: { 200: { body: User[] } };
 *       };
 *     };
 *   }>({
 *     baseURL: 'http://localhost:3000',
 *   });
 *
 *   type Schema = InferHttpInterceptorSchema<typeof interceptor>;
 *   // {
 *   //   '/users': {
 *   //     GET: {
 *   //       response: { 200: { body: User[] } };
 *   //     };
 *   //   };
 *   // }
 *
 * @see {@link https://zimic.dev/docs/interceptor/api/http-interceptor `HttpInterceptor` API reference}
 */
type InferHttpInterceptorSchema<Interceptor> = Interceptor extends LocalHttpInterceptor<infer Schema> ? Schema : Interceptor extends RemoteHttpInterceptor<infer Schema> ? Schema : never;

/** @see {@link https://zimic.dev/docs/interceptor/api/create-http-interceptor `createHttpInterceptor()` API reference} */
declare function createHttpInterceptor<Schema extends HttpSchema>(options: LocalHttpInterceptorOptions): LocalHttpInterceptor<Schema>;
declare function createHttpInterceptor<Schema extends HttpSchema>(options: RemoteHttpInterceptorOptions): RemoteHttpInterceptor<Schema>;
declare function createHttpInterceptor<Schema extends HttpSchema>(options: HttpInterceptorOptions): LocalHttpInterceptor<Schema> | RemoteHttpInterceptor<Schema>;

export { DisabledRequestSavingError, type HttpInterceptor, type HttpInterceptorOptions, type HttpInterceptorPlatform, type HttpInterceptorRequest, type HttpInterceptorResponse, type HttpInterceptorType, type HttpRequestHandler, type HttpRequestHandlerBodyStaticRestriction, type HttpRequestHandlerComputedRestriction, type HttpRequestHandlerHeadersStaticRestriction, type HttpRequestHandlerResponseDeclaration, type HttpRequestHandlerResponseDeclarationFactory, type HttpRequestHandlerRestriction, type HttpRequestHandlerSearchParamsStaticRestriction, type HttpRequestHandlerStaticRestriction, type InferHttpInterceptorSchema, type InterceptedHttpInterceptorRequest, InvalidFormDataError, InvalidJSONError, type LocalHttpInterceptor, type LocalHttpInterceptorOptions, type LocalHttpRequestHandler, NotRunningHttpInterceptorError, type PendingRemoteHttpRequestHandler, type RemoteHttpInterceptor, type RemoteHttpInterceptorOptions, type RemoteHttpRequestHandler, RequestSavingSafeLimitExceededError, RunningHttpInterceptorError, type SyncedRemoteHttpRequestHandler, TimesCheckError, type UnhandledHttpInterceptorRequest, UnhandledRequestStrategy, UnknownHttpInterceptorPlatformError, UnknownHttpInterceptorTypeError, UnregisteredBrowserServiceWorkerError, createHttpInterceptor };