http

type AssertableJSON interface {
	// Json returns the underlying JSON data as a map.
	Json() map[string]any
	// Count asserts that the property at the given key is an array and has the expected number of items.
	Count(key string, length int) AssertableJSON
	// Each gets the array at the given key and enforces the callback's assertions on every item in that array.
	Each(key string, callback func(AssertableJSON)) AssertableJSON
	// First gets the array at the given key and enforces the callback's assertions on the first item only.
	First(key string, callback func(AssertableJSON)) AssertableJSON
	// Has asserts that the property at the given key exists.
	Has(key string) AssertableJSON
	// HasAll asserts that all the provided keys exist.
	HasAll(keys []string) AssertableJSON
	// HasAny asserts that at least one of the provided keys exists.
	HasAny(keys []string) AssertableJSON
	// HasWithScope asserts that the property at the given key is an array of the expected length,
	// and enforces the callback's assertions on the first item of that array.
	// This is useful for verifying the structure of the items within a list.
	HasWithScope(key string, length int, callback func(AssertableJSON)) AssertableJSON
	// Missing asserts that the property at the given key does not exist.
	Missing(key string) AssertableJSON
	// MissingAll asserts that none of the provided keys exist.
	MissingAll(keys []string) AssertableJSON
	// Where asserts that the property at the given key equals the expected value.
	Where(key string, value any) AssertableJSON
	// WhereNot asserts that the property at the given key does not equal the provided value.
	WhereNot(key string, value any) AssertableJSON
}

type Request interface {
	// Get sends a GET request to the given URI.
	Get(uri string) (Response, error)
	// Post sends a POST request to the given URI with the provided body.
	Post(uri string, body io.Reader) (Response, error)
	// Put sends a PUT request to the given URI with the provided body.
	Put(uri string, body io.Reader) (Response, error)
	// Delete sends a DELETE request to the given URI with the provided body.
	Delete(uri string, body io.Reader) (Response, error)
	// Patch sends a PATCH request to the given URI with the provided body.
	Patch(uri string, body io.Reader) (Response, error)
	// Head sends a HEAD request to the given URI.
	Head(uri string) (Response, error)
	// Options sends an OPTIONS request to the given URI.
	Options(uri string) (Response, error)

	// FlushHeaders removes all currently configured headers.
	FlushHeaders() Request
	// WithBasicAuth sets the Authorization header using Basic Auth credentials.
	WithBasicAuth(username, password string) Request
	// WithContext sets the context for the request.
	WithContext(ctx context.Context) Request
	// WithCookie adds a single cookie to the request.
	WithCookie(cookie *http.Cookie) Request
	// WithCookies adds multiple cookies to the request.
	WithCookies(cookies []*http.Cookie) Request
	// WithHeader sets a specific header key and value.
	WithHeader(key, value string) Request
	// WithHeaders adds multiple headers to the request.
	WithHeaders(headers map[string]string) Request
	// WithoutHeader removes a specific header from the request.
	WithoutHeader(key string) Request
	// WithToken sets the Authorization header using a Bearer token.
	// An optional second argument can specify the token type (default is "Bearer").
	WithToken(token string, ttype ...string) Request
	// WithoutToken removes the Authorization header.
	WithoutToken() Request
	// WithSession sets the session attributes for the request.
	WithSession(attributes map[string]any) Request
}

type Response interface {
	// Bind unmarshalls the JSON response body into the provided value.
	Bind(value any) error
	// Content returns the raw response body as a string.
	Content() (string, error)
	// Cookie retrieves a cookie from the response by name.
	Cookie(name string) *http.Cookie
	// Cookies returns all cookies from the response.
	Cookies() []*http.Cookie
	// Headers returns the response headers.
	Headers() http.Header
	// IsServerError returns true if the status code is >= 500 and < 600.
	IsServerError() bool
	// IsSuccessful returns true if the status code is >= 200 and < 300.
	IsSuccessful() bool
	// Json returns the response body as a map.
	Json() (map[string]any, error)
	// Session returns the session attributes associated with the response.
	Session() (map[string]any, error)

	// AssertStatus asserts that the response has the given status code.
	AssertStatus(status int) Response
	// AssertOk asserts that the response has a 200 OK status code.
	AssertOk() Response
	// AssertCreated asserts that the response has a 201 Created status code.
	AssertCreated() Response
	// AssertAccepted asserts that the response has a 202 Accepted status code.
	AssertAccepted() Response
	// AssertNoContent asserts that the response has the given status code (default 204) and empty content.
	AssertNoContent(status ...int) Response
	// AssertMovedPermanently asserts that the response has a 301 Moved Permanently status code.
	AssertMovedPermanently() Response
	// AssertFound asserts that the response has a 302 Found status code.
	AssertFound() Response
	// AssertNotModified asserts that the response has a 304 Not Modified status code.
	AssertNotModified() Response
	// AssertPartialContent asserts that the response has a 206 Partial Content status code.
	AssertPartialContent() Response
	// AssertTemporaryRedirect asserts that the response has a 307 Temporary Redirect status code.
	AssertTemporaryRedirect() Response
	// AssertBadRequest asserts that the response has a 400 Bad Request status code.
	AssertBadRequest() Response
	// AssertUnauthorized asserts that the response has a 401 Unauthorized status code.
	AssertUnauthorized() Response
	// AssertPaymentRequired asserts that the response has a 402 Payment Required status code.
	AssertPaymentRequired() Response
	// AssertForbidden asserts that the response has a 403 Forbidden status code.
	AssertForbidden() Response
	// AssertNotFound asserts that the response has a 404 Not Found status code.
	AssertNotFound() Response
	// AssertMethodNotAllowed asserts that the response has a 405 Method Not Allowed status code.
	AssertMethodNotAllowed() Response
	// AssertNotAcceptable asserts that the response has a 406 Not Acceptable status code.
	AssertNotAcceptable() Response
	// AssertConflict asserts that the response has a 409 Conflict status code.
	AssertConflict() Response
	// AssertRequestTimeout asserts that the response has a 408 Request Timeout status code.
	AssertRequestTimeout() Response
	// AssertGone asserts that the response has a 410 Gone status code.
	AssertGone() Response
	// AssertUnsupportedMediaType asserts that the response has a 415 Unsupported Media Type status code.
	AssertUnsupportedMediaType() Response
	// AssertUnprocessableEntity asserts that the response has a 422 Unprocessable Entity status code.
	AssertUnprocessableEntity() Response
	// AssertTooManyRequests asserts that the response has a 429 Too Many Requests status code.
	AssertTooManyRequests() Response
	// AssertInternalServerError asserts that the response has a 500 Internal Server Error status code.
	AssertInternalServerError() Response
	// AssertServiceUnavailable asserts that the response has a 503 Service Unavailable status code.
	AssertServiceUnavailable() Response
	// AssertHeader asserts that the given header exists and optionally matches the value.
	AssertHeader(headerName, value string) Response
	// AssertHeaderMissing asserts that the given header is not present.
	AssertHeaderMissing(string) Response
	// AssertCookie asserts that the given cookie exists and optionally matches the value.
	AssertCookie(name, value string) Response
	// AssertCookieExpired asserts that the given cookie has expired.
	AssertCookieExpired(string) Response
	// AssertCookieNotExpired asserts that the given cookie has not expired.
	AssertCookieNotExpired(string) Response
	// AssertCookieMissing asserts that the given cookie is not present.
	AssertCookieMissing(string) Response
	// AssertSuccessful asserts that the response status code is >= 200 and < 300.
	AssertSuccessful() Response
	// AssertServerError asserts that the response status code is >= 500 and < 600.
	AssertServerError() Response
	// AssertDontSee asserts that the given strings are not present in the response body.
	AssertDontSee(value []string, escaped ...bool) Response
	// AssertSee asserts that the given strings are present in the response body.
	AssertSee(value []string, escaped ...bool) Response
	// AssertSeeInOrder asserts that the given strings are present in the response body in order.
	AssertSeeInOrder(value []string, escaped ...bool) Response
	// AssertJson asserts that the response JSON contains the given data.
	AssertJson(map[string]any) Response
	// AssertExactJson asserts that the response JSON matches the given data exactly.
	AssertExactJson(map[string]any) Response
	// AssertJsonMissing asserts that the response JSON does not contain the given keys or values.
	AssertJsonMissing(map[string]any) Response
	// AssertFluentJson allows for complex JSON assertions using a callback.
	AssertFluentJson(func(json AssertableJSON)) Response
}