---@meta
---@diagnostic disable: missing-return
-- Type stubs for the `http` module: the global table, the response/opts/session
-- classes, and the get/post/… shorthands (lua/stdlib/http.lua assigns those
-- dynamically in a loop, invisible to the language server). request, getJSON,
-- postJSON and session are NOT stubbed — they are annotated at their real
-- definitions in lua/stdlib/http.lua. Reference: docs/http.md
--
-- A non-2xx status is NOT an error (see resp.ok/resp.status); only failing to
-- get a response at all (DNS, connection, TLS, timeout) raises.

http = {}

---@class http.Response
---@field status integer HTTP status code, e.g. 200
---@field ok boolean true when status is 2xx
---@field url string final URL after redirects
---@field headers table<string, string> response headers, keyed by lowercase name; repeats joined with ", " (except set-cookie: first value only, see setCookies)
---@field setCookies string[] every Set-Cookie header value on the final response
---@field body string raw response body
---@field json fun(): any parse body as JSON (JSON null becomes utils.NULL); raises on invalid JSON

---@class http.Auth
---@field username string
---@field password string
---@field scheme "basic"|"digest"? default "basic"

---@class http.RequestOpts
---@field headers table<string, string>? extra request headers
---@field body string? raw request body (set Content-Type yourself)
---@field json any? serialized to JSON; sets Content-Type: application/json
---@field form table<string, string|number>? URL-encoded; sets application/x-www-form-urlencoded
---@field cookies table<string, string>? cookies for this request (merged with the session jar; not combinable with a Cookie header)
---@field timeout number? per-request timeout in seconds (default 30)
---@field auth http.Auth? basic or digest credentials

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.get(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.post(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.put(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.patch(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.delete(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function http.head(url, opts) end

----------------------------------------------------------------------
-- Sessions: a cookie jar carried across requests
----------------------------------------------------------------------

---@class http.Session
local Session = {}

---@param method string
---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:request(method, url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:get(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:post(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:put(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:patch(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:delete(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return http.Response
function Session:head(url, opts) end

---@param url string
---@param opts http.RequestOpts?
---@return any body
---@return http.Response resp
function Session:getJSON(url, opts) end

---@param url string
---@param body any
---@param opts http.RequestOpts?
---@return http.Response
function Session:postJSON(url, body, opts) end

---The unexpired cookies as a nested table, {domain = {name = value}}.
---@return table<string, table<string, string>>
function Session:cookies() end

---Empty the in-memory jar.
function Session:clearCookies() end

---Write the jar to a JSONL file (one cookie per line, including session cookies).
---@param path string
function Session:save(path) end

---Load a jar file, replacing the current jar contents.
---@param path string
function Session:load(path) end