client

type Factory interface {
	// Request embeds the Request interface, allowing direct usage like Http.Get().
	Request

	// AllowStrayRequests permits specific URL patterns to bypass the mock firewall.
	AllowStrayRequests(patterns []string) Factory

	// AssertNotSent verifies that no request matching the given assertion was sent.
	AssertNotSent(assertion func(req Request) bool) bool

	// AssertNothingSent verifies that no HTTP requests were sent at all.
	AssertNothingSent() bool

	// AssertSent verifies that at least one request matching the given assertion was sent.
	AssertSent(assertion func(req Request) bool) bool

	// AssertSentCount verifies that the specific number of requests matching the criteria were sent.
	AssertSentCount(count int) bool

	// Client returns a new request builder.
	// If name is provided, it returns the configuration for that specific client.
	// If no name is provided, it returns the default client.
	Client(name ...string) Request

	// Fake registers the mock rules for testing.
	Fake(mocks map[string]any) Factory

	// PreventStrayRequests enforces that all sent requests must match a defined mock rule.
	PreventStrayRequests() Factory

	// Reset restores the factory to its original state, clearing all mocks.
	Reset()

	// Response returns a builder for creating stubbed responses.
	Response() FakeResponse

	// Sequence returns a builder for defining ordered mock responses.
	Sequence() FakeSequence
}

type FakeResponse interface {
	// File creates a mock response using the contents of a file at the specified path.
	File(status int, path string) Response

	// Json creates a mock response with a JSON body and "application/json" content type.
	Json(status int, obj any) Response

	// Make constructs a custom mock response with the specified body, status, and headers.
	Make(status int, body string, header http.Header) Response

	// OK creates a generic 200 OK mock response with an empty body.
	OK() Response

	// Status creates a mock response with the specified status code and an empty body.
	Status(status int) Response

	// String creates a mock response with a raw string body.
	String(status int, body string) Response
}

type FakeSequence interface {
	// Push adds a specific response to the sequence.
	Push(response Response, count ...int) FakeSequence

	// PushStatus adds a status-only response to the sequence.
	PushStatus(status int, count ...int) FakeSequence

	// PushString adds a string-body response to the sequence.
	PushString(status int, body string, count ...int) FakeSequence

	// WhenEmpty defines the default response to return when the sequence is exhausted.
	WhenEmpty(response Response) FakeSequence
}

type Request interface {
	// Accept sets the "Accept" header to the specified content type.
	Accept(contentType string) Request

	// AcceptJSON sets the "Accept" header to "application/json".
	AcceptJSON() Request

	// AsForm sets the "Content-Type" header to "application/x-www-form-urlencoded".
	AsForm() Request

	// BaseUrl sets the base URL for the request, overriding the configuration.
	BaseUrl(url string) Request

	// Body returns the raw payload of the request as a string.
	Body() string

	// ClientName returns the name of the client configuration used for this request.
	ClientName() string

	// Clone creates a deep copy of the request builder.
	Clone() Request

	// Delete sends a DELETE request to the specified URI with the given body.
	Delete(uri string, body io.Reader) (Response, error)

	// FlushHeaders removes all currently configured headers from the request builder.
	FlushHeaders() Request

	// Get sends a GET request to the specified URI.
	Get(uri string) (Response, error)

	// Head sends a HEAD request to the specified URI.
	Head(uri string) (Response, error)

	// Header retrieves the value of a specific header key.
	Header(key string) string

	// Headers retrieves all headers associated with the request.
	Headers() http.Header

	// HttpClient returns the underlying standard library *http.Client.
	HttpClient() *http.Client

	// Input retrieves a specific value from the request body or query parameters.
	Input(key string) any

	// Method returns the HTTP verb of the request.
	Method() string

	// Options sends an OPTIONS request to the specified URI.
	Options(uri string) (Response, error)

	// Patch sends a PATCH request to the specified URI with the given body.
	Patch(uri string, body io.Reader) (Response, error)

	// Post sends a POST request to the specified URI with the given body.
	Post(uri string, body io.Reader) (Response, error)

	// Put sends a PUT request to the specified URI with the given body.
	Put(uri string, body io.Reader) (Response, error)

	// ReplaceHeaders replaces all existing headers with the provided map.
	ReplaceHeaders(headers map[string]string) Request

	// Url returns the full, resolved URL of the request.
	Url() string

	// WithBasicAuth sets the "Authorization" header using the Basic Auth standard.
	WithBasicAuth(username, password string) Request

	// WithContext sets the context for the request.
	WithContext(ctx context.Context) Request

	// WithCookie adds a single http.Cookie to the request.
	WithCookie(cookie *http.Cookie) Request

	// WithCookies adds multiple http.Cookie objects to the request.
	WithCookies(cookies []*http.Cookie) Request

	// WithHeader adds a specific header key-value pair to the request.
	WithHeader(key, value string) Request

	// WithHeaders adds multiple headers to the request from a map.
	WithHeaders(headers map[string]string) Request

	// WithQueryParameter adds a single query parameter to the URL.
	WithQueryParameter(key, value string) Request

	// WithQueryParameters adds multiple query parameters to the URL from a map.
	WithQueryParameters(params map[string]string) Request

	// WithQueryString parses a raw query string and adds it to the URL.
	WithQueryString(query string) Request

	// WithToken sets the "Authorization" header using a Bearer token.
	WithToken(token string, ttype ...string) Request

	// WithUrlParameter replaces a URL parameter placeholder with the given value.
	WithUrlParameter(key, value string) Request

	// WithUrlParameters replaces multiple URL parameter placeholders with values from a map.
	WithUrlParameters(params map[string]string) Request

	// WithoutHeader removes a specific header from the request by key.
	WithoutHeader(key string) Request

	// WithoutToken removes the "Authorization" header from the request.
	WithoutToken() Request
}

type Response interface {
	// Accepted determines if the response status code is 202 Accepted.
	Accepted() bool

	// BadRequest determines if the response status code is 400 Bad Request.
	BadRequest() bool

	// Bind unmarshalls the JSON response body into the provided value.
	Bind(value any) error

	// Body returns the response body as a string.
	Body() (string, error)

	// ClientError determines if the response status code is in the 400-499 range.
	ClientError() bool

	// Conflict determines if the response status code is 409 Conflict.
	Conflict() bool

	// Cookie retrieves a cookie by name from the response.
	Cookie(name string) *http.Cookie

	// Cookies returns all cookies provided by the response.
	Cookies() []*http.Cookie

	// Created determines if the response status code is 201 Created.
	Created() bool

	// Failed determines if the response status code is >= 400.
	Failed() bool

	// Forbidden determines if the response status code is 403 Forbidden.
	Forbidden() bool

	// Found determines if the response status code is 302 Found.
	Found() bool

	// Header retrieves the first value of a specific header from the response.
	Header(name string) string

	// Headers returns all headers from the response.
	Headers() http.Header

	// Json returns the response body parsed as a map.
	Json() (map[string]any, error)

	// MovedPermanently determines if the response status code is 301 Moved Permanently.
	MovedPermanently() bool

	// NoContent determines if the response status code is 204 No Content.
	NoContent() bool

	// NotFound determines if the response status code is 404 Not Found.
	NotFound() bool

	// OK determines if the response status code is 200 OK.
	OK() bool

	// Origin returns the underlying standard library *http.Response.
	Origin() *http.Response

	// PaymentRequired determines if the response status code is 402 Payment Required.
	PaymentRequired() bool

	// Redirect determines if the response status code is in the 300-399 range.
	Redirect() bool

	// RequestTimeout determines if the response status code is 408 Request Timeout.
	RequestTimeout() bool

	// ServerError determines if the response status code is >= 500.
	ServerError() bool

	// Status returns the integer HTTP status code of the response.
	Status() int

	// Stream returns the underlying reader to stream the response body.
	Stream() (io.ReadCloser, error)

	// Successful determines if the response status code is in the 200-299 range.
	Successful() bool

	// TooManyRequests determines if the response status code is 429 Too Many Requests.
	TooManyRequests() bool

	// Unauthorized determines if the response status code is 401 Unauthorized.
	Unauthorized() bool

	// UnprocessableEntity determines if the response status code is 422 Unprocessable Entity.
	UnprocessableEntity() bool
}