# std.http

Blocking HTTP client helpers for tool-style scripts.

```tea
use http from "std.http"
```

Examples may be fragments requiring the module import or additional setup.

## std.http.new_request

```tea
pub def new_request(method: String, url_text: String) -> Request
```

Create a request with empty headers/body and no timeout override.

## std.http.new_request_with

```tea
pub def new_request_with(method: String, url_text: String, headers: Dict[String, String], body: String, timeout_ms: Int) -> Request
```

Create a request with explicit headers, body, and timeout.

```tea
use http from "std.http"

const request = http.new_request_with(
  "GET", "https://example.com/", {"accept": "text/html"}, "", 5000
)
@println(request.timeout_ms) # 5000
```

## std.http.with_query

```tea
pub def with_query(req: Request, params: Dict[String, String]) -> Request
```

Append query parameters to a request URL.

```tea
use http from "std.http"

const request = http.new_request("GET", "https://example.com/search")
const search = http.with_query(request, {"q": "tea"})
@println(search.url) # https://example.com/search?q=tea
```

## std.http.send

```tea
pub def send(req: Request) -> Response
```

Send an HTTP request synchronously.

```tea
use http from "std.http"

const request = http.new_request_with(
  "GET", "https://example.com/", {"accept": "text/html"}, "", 5000
)
const response = http.check(http.send(request))
@println(response.body)
```

## std.http.get

```tea
pub def get(url_text: String) -> Response
```

Send a GET request.

```tea
use http from "std.http"

const response = http.get("https://example.com/")
@println(response.status)
if response.ok
  @println(response.body)
end
```

## std.http.get_with

```tea
pub def get_with(url_text: String, headers: Dict[String, String]) -> Response
```

Send a GET request with headers.

## std.http.post

```tea
pub def post(url_text: String, body: String) -> Response
```

Send a POST request with a text body.

## std.http.post_with

```tea
pub def post_with(url_text: String, headers: Dict[String, String], body: String) -> Response
```

Send a POST request with headers and a text body.

## std.http.put

```tea
pub def put(url_text: String, body: String) -> Response
```

Send a PUT request with a text body.

## std.http.patch

```tea
pub def patch(url_text: String, body: String) -> Response
```

Send a PATCH request with a text body.

## std.http.delete

```tea
pub def delete(url_text: String) -> Response
```

Send a DELETE request.

## std.http.post_json

```tea
pub def post_json[T](url_text: String, value: T) -> Response
```

Send a JSON POST request.

```tea
use http from "std.http"

# Requires a local API accepting POST /messages.
const response = http.post_json("http://127.0.0.1:8080/messages", {"text": "Hello, Tea!"})
@println(http.check(response).status)
```

## std.http.decode_json

```tea
pub def decode_json[T](response: Response) -> T ! json.DecodeError
```

Decode a JSON response body.

```tea
use http from "std.http"

# Requires a local API returning a JSON object of strings.
const response = http.check(http.get("http://127.0.0.1:8080/config"))
const config: Dict[String, String] = http.decode_json[Dict[String, String]](response)
@println(config["name"])
```

## std.http.header

```tea
pub def header(response: Response, name: String) -> String?
```

Return a response header by name when present.

```tea
use http from "std.http"

const response = http.get("https://example.com/")
const content_type = http.header(response, "Content-Type")
@println(content_type ?? "No content type provided")
```

## std.http.header_or

```tea
pub def header_or(response: Response, name: String, fallback: String) -> String
```

Return a response header by name or a fallback value.

## std.http.body_text

```tea
pub def body_text(response: Response) -> String
```

Return the text body of a response.

## std.http.body_bytes

```tea
pub def body_bytes(response: Response) -> List[Int]
```

Return the raw body bytes of a response.

## std.http.check

```tea
pub def check(response: Response) -> Response
```

Fail when the response status is not successful.

```tea
use http from "std.http"

const response = http.check(http.get("https://example.com/"))
@println(response.body) # Reached only for a successful response
```

## std.http.download

```tea
pub def download(url_text: String, file_path: String) -> Response ! fs.FsError
```

Download a URL to a file path and return the response.