# Fetch

Low-latency raw HTTP fetch with byte-for-byte upstream responses. Accessed via `client.fetch`.

## create

```ts
client.fetch.create(opts: FetchOpts, requestOptions?: RequestOptions): Promise<FetchResult>
```

POST /v1/fetch — fetch URL content via POST body.

Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.
The body is returned verbatim — a JSON-serving upstream comes back as the
raw JSON string, not a parsed object.

`requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
optional caller `signal`. It matters most here: ByteKit's own ceiling for a
fetch is 60 s, so without a per-call budget a slow upstream holds the caller for
the constructor default (2 minutes) rather than a duration the caller chose.

## get

```ts
client.fetch.get(opts: FetchGetOpts, requestOptions?: RequestOptions): Promise<FetchResult>
```

GET /v1/fetch — fetch URL content via query params.

Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.

Accepts `url`, `country`, `timeout_ms` and `cache_ttl`. The spec also declares a `custom`
query param for this endpoint, which this method deliberately does not expose; use
`create()` for custom metadata.

The query string is built by iterating `FETCH_GET_QUERY_KEYS`, the same list
`FetchGetOpts` is derived from, so every accepted option is necessarily
serialized.

`requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
optional caller `signal`. As on `create`, ByteKit's own ceiling for a fetch is
60 s, so a per-call budget is what keeps a slow upstream from holding the caller
for the constructor default.

## Options (`FetchOpts`)

- `url` (required) — `string`
- `country` — `string`
- `timeout_ms` — `number`
- `cache_ttl` — `string | 0` — How long a freshly fetched URL may be served from cache. Matches the
OpenAPI `FetchRequest.cache_ttl` schema: a duration string (`"48h"`,
`"2d"`, up to `168h` / `7d`) or the integer `0` to disable caching.
Defaults to `"48h"` server-side when omitted.
- `custom` — `Record<string, unknown>` — User-supplied JSON payload, base64-encoded into the `X-Fetch-Custom`
response header so callers can correlate the response to caller-side
state. Capped at 4096 UTF-8 bytes after JSON serialization. Does NOT
affect cache-key inputs.