brellium-api-client 0.2.0__py3-none-any.whl

brellium_api_client/_base_client.py

@@ -0,0 +1,2904 @@
+from __future__ import annotations
+
+import sys
+import json
+import time
+import uuid
+import zlib
+import email
+import asyncio
+import inspect
+import logging
+import platform
+import warnings
+import email.utils
+from types import TracebackType
+from random import random
+from dataclasses import field, dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Type,
+    Union,
+    Generic,
+    Mapping,
+    TypeVar,
+    Iterable,
+    Iterator,
+    Optional,
+    Generator,
+    AsyncIterator,
+    cast,
+    overload,
+)
+from typing_extensions import Literal, override, get_origin
+
+import anyio
+import httpx
+import pydantic
+from httpx import URL
+from pydantic import PrivateAttr
+
+from . import _exceptions
+from ._qs import Querystring
+from ._decoding import CodingRefused, BoundedDecoder, decoding_error
+from ._files import to_httpx_files, async_to_httpx_files
+from ._types import (
+    Body,
+    Omit,
+    Query,
+    Headers,
+    Timeout,
+    NotGiven,
+    ResponseT,
+    AnyMapping,
+    PostParser,
+    BinaryTypes,
+    RequestFiles,
+    HttpxSendArgs,
+    RequestOptions,
+    AsyncBinaryTypes,
+    HttpxRequestFiles,
+    ModelBuilderProtocol,
+    not_given,
+)
+from ._utils import is_dict, is_list, asyncify, is_given, lru_cache, is_mapping
+from ._compat import PYDANTIC_V1, model_copy, model_dump
+from ._models import GenericModel, SecurityOptions, FinalRequestOptions, validate_type, construct_type
+from ._response import (
+    APIResponse,
+    BaseAPIResponse,
+    AsyncAPIResponse,
+    BinaryAPIResponse,
+    AsyncBinaryAPIResponse,
+    StreamedBinaryAPIResponse,
+    AsyncStreamedBinaryAPIResponse,
+    extract_response_type,
+)
+from ._constants import (
+    DEFAULT_TIMEOUT,
+    MAX_RETRY_DELAY,
+    DEFAULT_MAX_RETRIES,
+    INITIAL_RETRY_DELAY,
+    RAW_RESPONSE_HEADER,
+    OVERRIDE_CAST_TO_HEADER,
+    DEFAULT_CONNECTION_LIMITS,
+)
+from ._streaming import Stream, SSEDecoder, AsyncStream, SSEBytesDecoder
+from ._exceptions import (
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    APIConnectionError,
+    APIResponseValidationError,
+)
+from ._utils._json import openapi_dumps
+
+log: logging.Logger = logging.getLogger(__name__)
+
+# TODO: make base page type vars covariant
+SyncPageT = TypeVar("SyncPageT", bound="BaseSyncPage[Any]")
+AsyncPageT = TypeVar("AsyncPageT", bound="BaseAsyncPage[Any]")
+
+
+_T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
+
+_StreamT = TypeVar("_StreamT", bound=Stream[Any])
+_AsyncStreamT = TypeVar("_AsyncStreamT", bound=AsyncStream[Any])
+
+if TYPE_CHECKING:
+    from httpx._config import (
+        DEFAULT_TIMEOUT_CONFIG,  # pyright: ignore[reportPrivateImportUsage]
+    )
+
+    HTTPX_DEFAULT_TIMEOUT = DEFAULT_TIMEOUT_CONFIG
+else:
+    try:
+        from httpx._config import DEFAULT_TIMEOUT_CONFIG as HTTPX_DEFAULT_TIMEOUT
+    except ImportError:
+        # httpx's own default of five seconds, for a version that no longer exposes the constant.
+        HTTPX_DEFAULT_TIMEOUT = Timeout(5.0)
+
+
+# The redirect statuses the SDK follows, the ones the fetch spec follows. A 300 only offers choices
+# and a 304 tells a conditional request its copy is current, so neither is a hop: like a redirect
+# without a `Location`, each reaches the caller as a status error.
+_REDIRECT_STATUSES: frozenset[int] = frozenset({301, 302, 303, 307, 308})
+
+# How many redirects one request follows before giving up with a connection error.
+MAX_REDIRECTS = 20
+
+# Every header a credential travels in, lower-cased: `Authorization`, `Proxy-Authorization`, `Cookie`,
+# the conventional key headers, and each header this SDK's auth schemes place (an `apiKey` scheme
+# names its own). A redirect that leaves the origin drops all of them; the log masks the same set.
+_CREDENTIAL_HEADERS: frozenset[str] = frozenset(
+    ("authorization", "proxy-authorization", "api-key", "x-api-key", "cookie", "set-cookie")
+)
+
+# The query parameters this SDK's `apiKey` schemes place a credential in.
+_CREDENTIAL_QUERY: tuple[str, ...] = ()
+
+# The headers that describe a request body, dropped with the body when a redirect turns the request
+# into a bodiless GET (the fetch spec's list, plus the framing headers httpx sets).
+_BODY_HEADERS: tuple[str, ...] = (
+    "content-type",
+    "content-length",
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "transfer-encoding",
+)
+
+_DEFAULT_PORTS: Dict[str, int] = {"http": 80, "https": 443}
+
+# The most bytes a buffered response body may decode to (after transparent decompression), so a
+# hostile or broken server cannot make the client hold an unbounded body in memory. A binary
+# download or a streamed response is handed to the caller unread and is not capped.
+MAX_RESPONSE_BODY_BYTES = 64 * 1024 * 1024
+
+# The most bytes of an error response's body read for its message and `body`; the rest is dropped.
+MAX_ERROR_BODY_BYTES = 64 * 1024
+
+
+class _ResponseRefused(Exception):
+    """A response the SDK will not act on, reported to the caller as an SDK error with `message`."""
+
+    def __init__(self, message: str, *, request: httpx.Request) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+
+
+class _RedirectRefused(_ResponseRefused):
+    """A redirect the SDK will not follow; it reaches the caller as an `APIConnectionError`."""
+
+
+class _BodyRefused(_ResponseRefused):
+    """A buffered body the SDK will not read; it reaches the caller as an `APIError` and is not retried."""
+
+
+class _BodyTooLarge(_BodyRefused):
+    """A buffered body larger than `MAX_RESPONSE_BODY_BYTES`."""
+
+
+def _origin(url: URL) -> tuple[str, str, int | None]:
+    """Scheme, host and port of `url`, the default port spelled out, so `https://h:443` is `https://h`."""
+    scheme = url.scheme.lower()
+    return (scheme, url.host.lower(), url.port if url.port is not None else _DEFAULT_PORTS.get(scheme))
+
+
+def _is_followed_redirect(response: httpx.Response) -> bool:
+    """Whether `response` is a redirect the SDK follows: a 301, 302, 303, 307 or 308 naming a `Location`."""
+    return response.status_code in _REDIRECT_STATUSES and bool(response.headers.get("location", "").strip())
+
+
+def _is_replayable(stream: object) -> bool:
+    """Whether a request body can be sent again on the next hop.
+
+    Bytes can, and so can a multipart body whose files are bytes or seekable (httpx rewinds each one
+    as it renders the part). An iterator or an unseekable file was consumed by the first request, so
+    resending it would deliver an empty or truncated body the server would act on.
+    """
+    if isinstance(stream, httpx.ByteStream):
+        return True
+    fields = getattr(stream, "fields", None)
+    if fields is None:
+        return False
+    for field in cast("list[Any]", fields):
+        file = getattr(field, "file", None)
+        if file is None or isinstance(file, (bytes, str)):
+            continue
+        seekable = getattr(file, "seekable", None)
+        try:
+            if not (callable(seekable) and seekable()):
+                return False
+        except Exception:
+            return False
+    return True
+
+
+def _redirect_request(
+    request: httpx.Request, response: httpx.Response, *, sent_headers: httpx.Headers, keep_credentials: bool
+) -> tuple[httpx.Request, bool]:
+    """The request a followed redirect sends next, and whether it still carries the credentials.
+
+    `Location` is resolved against the URL that was redirected (RFC 3986 section 5.2). Only http and
+    https are followed, and never from https down to http, which would send the request and its
+    credentials in clear.
+
+    A 303 answering anything but HEAD, and a 301 or 302 answering a POST, is fetched again as a
+    bodiless GET, as the fetch spec does. Every other redirect keeps its method and resends its body
+    (a PUT answered with a 301 must not become a GET that succeeds without doing what was asked), and
+    a body that cannot be replayed is refused rather than resent empty.
+
+    Leaving the origin (scheme, host and port) drops every credential header, whether the client or a
+    per-call `extra_headers` set it, and the drop holds for the rest of the chain, so a chain that
+    comes back to the first origin arrives without them. A query-placed key cannot leave at all: the
+    target's query is the `Location`'s own. On the same origin a relative `Location` cannot carry the
+    query key, so it is carried over exactly as a header credential is.
+
+    The next hop is built from `sent_headers`, the headers as they stood before httpx ran the auth flow:
+    an `httpx.Auth` signs the request object in place, so its headers (whatever their names) must not
+    be copied onto a hop it did not sign. A hop that stays on the origin is signed again on send.
+    """
+    location = response.headers.get("location", "").strip()
+    try:
+        target = request.url.join(location)
+    except Exception as exc:
+        raise _RedirectRefused("Redirect with an unusable Location header", request=request) from exc
+
+    scheme = target.scheme.lower()
+    if scheme not in ("http", "https") or not target.host:
+        raise _RedirectRefused("Redirect to an unsupported URL scheme", request=request)
+    if request.url.scheme.lower() == "https" and scheme == "http":
+        raise _RedirectRefused("Redirect from https to insecure http", request=request)
+    target = target.copy_with(fragment=None)
+
+    headers = httpx.Headers(sent_headers)
+    method = request.method.upper()
+    status = response.status_code
+    stream: Any = request.stream
+    if (status == 303 and method != "HEAD") or (status in (301, 302) and method == "POST"):
+        method = "GET"
+        stream = None
+        for name in _BODY_HEADERS:
+            headers.pop(name, None)
+    elif not _is_replayable(stream):
+        raise _RedirectRefused("Redirect would resend a request body that cannot be replayed", request=request)
+
+    if keep_credentials and _origin(request.url) == _origin(target):
+        present = set(target.params.keys())
+        carried = [
+            (key, value)
+            for key, value in request.url.params.multi_items()
+            if key in _CREDENTIAL_QUERY and key not in present
+        ]
+        if carried:
+            target = target.copy_merge_params(tuple(carried))
+        _merge_set_cookies(headers, response, target)
+    else:
+        keep_credentials = False
+        for name in [name for name in headers if name.lower() in _CREDENTIAL_HEADERS]:
+            del headers[name]
+
+    # httpx only fills `Host` in for a request built without a stream, so it is set here for both.
+    headers["Host"] = target.netloc.decode("ascii")
+    extensions = dict(request.extensions)
+    if "_" in target.host:
+        # work around https://github.com/encode/httpx/discussions/2880, as `_build_request` does
+        extensions["sni_hostname"] = target.host.replace("_", "-")
+    else:
+        extensions.pop("sni_hostname", None)
+
+    return httpx.Request(method, target, headers=headers, stream=stream, extensions=extensions), keep_credentials
+
+
+def _merge_set_cookies(headers: httpx.Headers, response: httpx.Response, target: httpx.URL) -> None:
+    """Folds the cookies a same-origin redirect sets into the next hop's `Cookie` header.
+
+    httpx writes a request's cookies into a header when the request is built, so without this a cookie
+    the 3xx itself sets (a session, say) would be missing from the next hop, as it is not when httpx
+    follows. A cookie the redirect sets replaces the one of the same name the header carried.
+    """
+    if not response.headers.get_list("set-cookie"):
+        return
+    fresh = httpx.Cookies()
+    fresh.extract_cookies(response)
+    probe = httpx.Request("GET", target)
+    fresh.set_cookie_header(probe)
+    added = probe.headers.get("cookie")
+    if not added:
+        return
+    pairs: Dict[str, str] = {}
+    for part in [*headers.get("cookie", "").split(";"), *added.split(";")]:
+        part = part.strip()
+        if part:
+            pairs[part.partition("=")[0]] = part
+    headers["Cookie"] = "; ".join(pairs.values())
+
+
+def _describe_body(value: object) -> str:
+    """A request body as the debug log shows it: its shape and size, never its values.
+
+    A mapping lists its keys, which are the API's field names; every value, nested ones included,
+    stays out of the log.
+    """
+    if isinstance(value, (bytes, bytearray)):
+        return f"<{len(value)} bytes>"
+    if isinstance(value, str):
+        return f"<{len(value)} characters>"
+    if is_mapping(value):
+        keys = ", ".join(sorted(str(key) for key in value))
+        return f"<mapping with keys: {keys}>"
+    if is_list(value) or isinstance(value, tuple):
+        return f"<{len(cast('list[object]', value))} items>"
+    return f"<{type(value).__name__}>"
+
+
+def _read_deadline(request: httpx.Request, started: float) -> float | None:
+    """When reading a buffered body must have finished: the request's read timeout after `started`, when its headers arrived.
+
+    httpx applies its read timeout to each socket read, so a server trickling one byte per read keeps
+    a body arriving forever; this turns the same number into a deadline for reading the whole body.
+    """
+    timeout = cast("Mapping[str, Any]", request.extensions.get("timeout") or {})
+    read = timeout.get("read")
+    return None if read is None else started + float(read)
+
+
+def _is_unbuffered_cast(cast_to: object) -> bool:
+    """Whether `cast_to` hands the body to the caller as it arrived: a binary download or a raw `httpx.Response`.
+
+    Those bodies are the caller's to bound, so neither the size cap nor the read deadline applies.
+    The legacy binary wrapper is matched by name, since its module ships only with the legacy surface.
+    """
+    origin = get_origin(cast_to) or cast_to
+    if not inspect.isclass(origin):
+        return False
+    if issubclass(
+        origin,
+        (
+            httpx.Response,
+            BinaryAPIResponse,
+            AsyncBinaryAPIResponse,
+            StreamedBinaryAPIResponse,
+            AsyncStreamedBinaryAPIResponse,
+        ),
+    ):
+        return True
+    return any(base.__name__ == "HttpxBinaryResponseContent" for base in origin.__mro__)
+
+
+def _body_limit(response: httpx.Response, *, capped: bool) -> tuple[int | None, bool]:
+    """The byte limit for reading `response`, and whether reaching it truncates rather than refuses.
+
+    An error body is read for its message only, so it is cut at `MAX_ERROR_BODY_BYTES`; a success body
+    is refused past `MAX_RESPONSE_BODY_BYTES`, unless `capped` is off for a body the caller takes raw.
+    """
+    if not response.is_success:
+        return MAX_ERROR_BODY_BYTES, True
+    return (MAX_RESPONSE_BODY_BYTES if capped else None), False
+
+
+def _too_large(response: httpx.Response, limit: int) -> _BodyTooLarge:
+    """The error for a success body that decoded past `limit` bytes."""
+    return _BodyTooLarge(
+        f"Response body exceeds the {limit} byte limit ({limit // (1024 * 1024)} MiB) for a buffered response",
+        request=response.request,
+    )
+
+
+class _BodyBuffer:
+    """The decoded bytes of a buffered body read so far, held to the limit `_body_limit` sets."""
+
+    def __init__(self, response: httpx.Response, *, capped: bool) -> None:
+        self._response = response
+        self._limit, self._truncate = _body_limit(response, capped=capped)
+        self._chunks: List[bytes] = []
+        self._size = 0
+
+    def add(self, pieces: Iterable[bytes]) -> bool:
+        """Appends `pieces`; True once a truncated body is full and reading should stop.
+
+        A body refused past the limit raises `_BodyTooLarge` as soon as a piece would cross it, so a
+        decompression bomb stops being inflated there.
+        """
+        for piece in pieces:
+            if self._limit is not None and self._size + len(piece) > self._limit:
+                if not self._truncate:
+                    raise _too_large(self._response, self._limit)
+                self._chunks.append(piece[: self._limit - self._size])
+                return True
+            self._size += len(piece)
+            self._chunks.append(piece)
+        return False
+
+    @property
+    def truncates(self) -> bool:
+        """Whether this is an error body, read for its message: past the limit or the deadline it is cut, not refused."""
+        return self._truncate
+
+    def content(self) -> bytes:
+        """The body read, decoded and joined."""
+        return b"".join(self._chunks)
+
+
+def _read_body(response: httpx.Response, *, capped: bool, deadline: float | None) -> None:
+    """Reads `response`'s body into memory, bounded in size and, when `deadline` is set, in time.
+
+    The bytes are counted after transparent decompression, and gzip and deflate (stacked or not) are
+    inflated by `BoundedDecoder` in bounded steps, so a small compressed body cannot expand past the
+    limit. A read still running at `deadline` raises `httpx.ReadTimeout`, which the request loop
+    retries or reports like any other timeout, except on an error body, which keeps what arrived by
+    then so its status error still stands; httpx cannot interrupt one blocked socket read, so the
+    deadline can be overrun by at most one read timeout.
+    """
+    body = _BodyBuffer(response, capped=capped)
+    try:
+        decoder = BoundedDecoder.for_response(response, capped=capped)
+        if decoder is None:
+            for chunk in response.iter_bytes():
+                if body.add((chunk,)):
+                    break
+                if deadline is not None and time.monotonic() > deadline:
+                    if body.truncates:
+                        break
+                    raise httpx.ReadTimeout("Timed out reading the response body", request=response.request)
+        else:
+            for raw in response.iter_raw():
+                if body.add(decoder.decode(raw)):
+                    break
+                if deadline is not None and time.monotonic() > deadline:
+                    if body.truncates:
+                        break
+                    raise httpx.ReadTimeout("Timed out reading the response body", request=response.request)
+            else:
+                body.add(decoder.flush())
+    except CodingRefused as exc:
+        raise _BodyRefused(exc.message, request=response.request) from None
+    except zlib.error as exc:
+        raise decoding_error(response, exc) from exc
+    finally:
+        response.close()
+    response._content = body.content()  # pyright: ignore[reportPrivateUsage]
+
+
+async def _aread_body(response: httpx.Response, *, capped: bool, deadline: float | None) -> None:
+    """The async twin of `_read_body`, where the deadline cancels a read that is still blocked."""
+    body = _BodyBuffer(response, capped=capped)
+
+    async def read() -> None:
+        """Reads the body into `body` until it ends or `body` is full."""
+        decoder = BoundedDecoder.for_response(response, capped=capped)
+        if decoder is None:
+            async for chunk in response.aiter_bytes():
+                if body.add((chunk,)):
+                    return
+            return
+        async for raw in response.aiter_raw():
+            if body.add(decoder.decode(raw)):
+                return
+        body.add(decoder.flush())
+
+    try:
+        if deadline is None:
+            await read()
+        else:
+            try:
+                with anyio.fail_after(max(0.0, deadline - time.monotonic())):
+                    await read()
+            except TimeoutError as exc:
+                if not body.truncates:
+                    raise httpx.ReadTimeout("Timed out reading the response body", request=response.request) from exc
+    except CodingRefused as exc:
+        raise _BodyRefused(exc.message, request=response.request) from None
+    except zlib.error as exc:
+        raise decoding_error(response, exc) from exc
+    finally:
+        await response.aclose()
+    response._content = body.content()  # pyright: ignore[reportPrivateUsage]
+
+
+@dataclass
+class SchemeCredentials:
+    """The credential one security scheme puts on a request, split by where it is sent."""
+
+    headers: Dict[str, str] = field(default_factory=dict)
+    query: Dict[str, str] = field(default_factory=dict)
+    cookies: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def configured(self) -> bool:
+        """Whether the scheme's client option(s) are set, so it has a credential to send."""
+        return bool(self.headers or self.query or self.cookies)
+
+
+def _merge_scheme_credentials(parts: List[SchemeCredentials]) -> SchemeCredentials:
+    """The credentials of several schemes sent together, one request's worth."""
+    merged = SchemeCredentials()
+    for part in parts:
+        merged.headers.update(part.headers)
+        merged.query.update(part.query)
+        merged.cookies.update(part.cookies)
+    return merged
+
+
+@dataclass(frozen=True)
+class AuthLocations:
+    """The lower-cased header names, and the query and cookie names, the client's credentials use."""
+
+    headers: frozenset[str] = frozenset()
+    query: frozenset[str] = frozenset()
+    cookies: frozenset[str] = frozenset()
+
+
+@dataclass
+class CursorPageConfig:
+    """Per-operation cursor pagination descriptor baked into a page by the generated list method.
+
+    The Python view of the shared, language-neutral descriptor: where the items array lives, how to
+    read the next cursor, which request param carries it, and on which carrier (query vs body).
+    Driving extraction from this config — rather than typed `items`/`next_cursor` model fields — lets
+    one page class serve every cursor scheme, including `cursor_id` (cursor read from the last item)
+    and body-carried cursors.
+    """
+
+    # Body path to the items array (e.g. ["items"], ["data"]).
+    items_path: List[str] = field(default_factory=list)
+    # "field" (a top-level response field) or "item" (a field on the last item — `cursor_id`).
+    cursor_kind: str = "field"
+    # Path to the cursor value: from the body root when cursor_kind is "field", or from the last item.
+    cursor_path: List[str] = field(default_factory=list)
+    # Request param wire name that carries the cursor.
+    cursor_param: str = "cursor"
+    # "query" or "body": the carrier the cursor param rides on the next request.
+    cursor_location: str = "query"
+    # Keep paginating across an empty page when set.
+    continue_on_empty_items: bool = False
+    # Body path to the scheme's `has_more` boolean. Only an explicit False stops pagination;
+    # a missing or non-boolean value falls back to cursor-presence semantics.
+    has_more_path: List[str] = field(default_factory=list)
+
+
+class PageInfo:
+    """Stores the necessary information to build the request to retrieve the next page.
+
+    Exactly one of `url`, `params` (query carrier), or `json` (body carrier) must be set.
+    """
+
+    url: URL | NotGiven
+    params: Query | NotGiven
+    json: Body | NotGiven
+
+    @overload
+    def __init__(
+        self,
+        *,
+        url: URL,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        params: Query,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        json: Body,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        *,
+        url: URL | NotGiven = not_given,
+        json: Body | NotGiven = not_given,
+        params: Query | NotGiven = not_given,
+    ) -> None:
+        self.url = url
+        self.json = json
+        self.params = params
+
+    @override
+    def __repr__(self) -> str:
+        if self.url:
+            return f"{self.__class__.__name__}(url={self.url})"
+        if self.json:
+            return f"{self.__class__.__name__}(json={self.json})"
+        return f"{self.__class__.__name__}(params={self.params})"
+
+
+class BasePage(GenericModel, Generic[_T]):
+    """
+    Defines the core interface for pagination.
+
+    Type Args:
+        ModelT: The pydantic model that represents an item in the response.
+
+    Methods:
+        has_next_page(): Check if there is another page available
+        next_page_info(): Get the necessary information to make a request for the next page
+    """
+
+    _options: FinalRequestOptions = PrivateAttr()
+    _model: Type[_T] = PrivateAttr()
+    # Per-operation cursor descriptor; set by the paginated method via _set_private_attributes and
+    # carried forward across pages so every page extracts items/cursor identically. None for pages
+    # that predate metadata-driven pagination.
+    _cursor_config: Optional[CursorPageConfig] = PrivateAttr(None)
+
+    def has_next_page(self) -> bool:
+        items = self._get_page_items()
+        if not items:
+            return False
+        return self.next_page_info() is not None
+
+    def next_page_info(self) -> Optional[PageInfo]: ...
+
+    def _get_page_items(self) -> Iterable[_T]:  # type: ignore[empty-body]
+        ...
+
+    def _params_from_url(self, url: URL) -> httpx.QueryParams:
+        # TODO: do we have to preprocess params here?
+        return httpx.QueryParams(cast(Any, self._options.params)).merge(url.params)
+
+    def _info_to_options(self, info: PageInfo) -> FinalRequestOptions:
+        options = model_copy(self._options)
+        options._strip_raw_response_header()
+
+        if not isinstance(info.params, NotGiven):
+            options.params = {**options.params, **info.params}
+            return options
+
+        if not isinstance(info.url, NotGiven):
+            # The next request carries this client's credentials, so a page URL a response names on
+            # another scheme, host or port is refused rather than dialed: a server must not be able
+            # to send the caller's key elsewhere by naming it as the next page. The message names
+            # neither URL, since either may carry a token. The origin compared is the one that served
+            # this page: an operation with its own `servers` entry is sent to an absolute URL, else
+            # to the client's base URL. `_client` is declared by the sync and async page classes,
+            # each with its own client type.
+            current = URL(self._options.url)
+            served_by: URL = current if current.is_absolute_url else cast(Any, self)._client.base_url
+            if info.url.is_absolute_url and _origin(info.url) != _origin(served_by):
+                raise RuntimeError("Refusing to follow a next page URL that points away from the API's origin")
+            params = self._params_from_url(info.url)
+            url = info.url.copy_with(params=params)
+            options.params = dict(url.params)
+            options.url = str(url)
+            return options
+
+        if not isinstance(info.json, NotGiven):
+            if not is_mapping(info.json):
+                raise TypeError("Pagination is only supported with mappings")
+
+            if not options.json_data:
+                options.json_data = {**info.json}
+            else:
+                if not is_mapping(options.json_data):
+                    raise TypeError("Pagination is only supported with mappings")
+
+                options.json_data = {**options.json_data, **info.json}
+            return options
+
+        raise ValueError("Unexpected PageInfo state")
+
+    def _next_page_repeats(self) -> bool:
+        """Whether the next page's request would be exactly the request that fetched this page.
+
+        A server that answers with the cursor (or link, or body token) it was just given would make
+        auto-pagination fetch the same page forever, so the walk stops there instead.
+        """
+        info = self.next_page_info()
+        if info is None:
+            return False
+        try:
+            options = self._info_to_options(info)
+        except (TypeError, ValueError):
+            return False
+        return (
+            options.url == self._options.url
+            and options.params == self._options.params
+            and options.json_data == self._options.json_data
+        )
+
+
+class BaseSyncPage(BasePage[_T], Generic[_T]):
+    _client: SyncAPIClient = pydantic.PrivateAttr()
+
+    def _set_private_attributes(
+        self,
+        client: SyncAPIClient,
+        model: Type[_T],
+        options: FinalRequestOptions,
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> None:
+        if (not PYDANTIC_V1) and getattr(self, "__pydantic_private__", None) is None:
+            self.__pydantic_private__ = {}
+
+        self._model = model
+        self._client = client
+        self._options = options
+        self._cursor_config = cursor_config
+
+    # Pydantic uses a custom `__iter__` method to support casting BaseModels
+    # to dictionaries. e.g. dict(model).
+    # As we want to support `for item in page`, this is inherently incompatible
+    # with the default pydantic behaviour. It is not possible to support both
+    # use cases at once. Fortunately, this is not a big deal as all other pydantic
+    # methods should continue to work as expected as there is an alternative method
+    # to cast a model to a dictionary, model.dict(), which is used internally
+    # by pydantic.
+    def __iter__(self) -> Iterator[_T]:  # type: ignore
+        for page in self.iter_pages():
+            for item in page._get_page_items():
+                yield item
+
+    def iter_pages(self: SyncPageT) -> Iterator[SyncPageT]:
+        page = self
+        while True:
+            yield page
+            if page.has_next_page() and not page._next_page_repeats():
+                page = page.get_next_page()
+            else:
+                return
+
+    def get_next_page(self: SyncPageT) -> SyncPageT:
+        info = self.next_page_info()
+        if not info:
+            raise RuntimeError(
+                "No next page expected; please check `.has_next_page()` before calling `.get_next_page()`."
+            )
+
+        options = self._info_to_options(info)
+        # Carry the cursor descriptor forward so the next page extracts items/cursor identically.
+        return self._client._request_api_list(
+            self._model, page=self.__class__, options=options, cursor_config=self._cursor_config
+        )
+
+
+class AsyncPaginator(Generic[_T, AsyncPageT]):
+    def __init__(
+        self,
+        client: AsyncAPIClient,
+        options: FinalRequestOptions,
+        page_cls: Type[AsyncPageT],
+        model: Type[_T],
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> None:
+        self._model = model
+        self._client = client
+        self._options = options
+        self._page_cls = page_cls
+        self._cursor_config = cursor_config
+
+    def __await__(self) -> Generator[Any, None, AsyncPageT]:
+        return self._get_page().__await__()
+
+    async def _get_page(self) -> AsyncPageT:
+        def _parser(resp: AsyncPageT) -> AsyncPageT:
+            resp._set_private_attributes(
+                model=self._model,
+                options=self._options,
+                client=self._client,
+                cursor_config=self._cursor_config,
+            )
+            return resp
+
+        self._options.post_parser = _parser
+
+        return await self._client.request(self._page_cls, self._options)
+
+    async def __aiter__(self) -> AsyncIterator[_T]:
+        # https://github.com/microsoft/pyright/issues/3464
+        page = cast(
+            AsyncPageT,
+            await self,  # type: ignore
+        )
+        async for item in page:
+            yield item
+
+
+class BaseAsyncPage(BasePage[_T], Generic[_T]):
+    _client: AsyncAPIClient = pydantic.PrivateAttr()
+
+    def _set_private_attributes(
+        self,
+        model: Type[_T],
+        client: AsyncAPIClient,
+        options: FinalRequestOptions,
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> None:
+        if (not PYDANTIC_V1) and getattr(self, "__pydantic_private__", None) is None:
+            self.__pydantic_private__ = {}
+
+        self._model = model
+        self._client = client
+        self._options = options
+        self._cursor_config = cursor_config
+
+    async def __aiter__(self) -> AsyncIterator[_T]:
+        async for page in self.iter_pages():
+            for item in page._get_page_items():
+                yield item
+
+    async def iter_pages(self: AsyncPageT) -> AsyncIterator[AsyncPageT]:
+        page = self
+        while True:
+            yield page
+            if page.has_next_page() and not page._next_page_repeats():
+                page = await page.get_next_page()
+            else:
+                return
+
+    async def get_next_page(self: AsyncPageT) -> AsyncPageT:
+        info = self.next_page_info()
+        if not info:
+            raise RuntimeError(
+                "No next page expected; please check `.has_next_page()` before calling `.get_next_page()`."
+            )
+
+        options = self._info_to_options(info)
+        # Carry the cursor descriptor forward so the next page extracts items/cursor identically.
+        return await self._client._request_api_list(
+            self._model, page=self.__class__, options=options, cursor_config=self._cursor_config
+        )
+
+
+_HttpxClientT = TypeVar("_HttpxClientT", bound=Union[httpx.Client, httpx.AsyncClient])
+_DefaultStreamT = TypeVar("_DefaultStreamT", bound=Union[Stream[Any], AsyncStream[Any]])
+
+
+class BaseClient(Generic[_HttpxClientT, _DefaultStreamT]):
+    _client: _HttpxClientT
+    _version: str
+    _base_url: URL
+    max_retries: int
+    timeout: Union[float, Timeout, None]
+    _strict_response_validation: bool
+    _idempotency_header: str | None
+    _default_stream_cls: type[_DefaultStreamT] | None = None
+
+    def __init__(
+        self,
+        *,
+        version: str,
+        base_url: str | URL,
+        _strict_response_validation: bool,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float | Timeout | None = DEFAULT_TIMEOUT,
+        custom_headers: Mapping[str, str] | None = None,
+        custom_query: Mapping[str, object] | None = None,
+    ) -> None:
+        self._version = version
+        self._base_url = self._enforce_trailing_slash(URL(base_url))
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._custom_headers = custom_headers or {}
+        self._custom_query = custom_query or {}
+        self._strict_response_validation = _strict_response_validation
+        self._idempotency_header = None
+        self._platform: Platform | None = None
+
+        if max_retries is None:  # pyright: ignore[reportUnnecessaryComparison]
+            raise TypeError(
+                "max_retries cannot be None. If you want to disable retries, pass `0`; if you want unlimited retries, pass `math.inf` or a very high number; if you want the default behavior, pass `brellium_api_client.DEFAULT_MAX_RETRIES`"
+            )
+
+    def _enforce_trailing_slash(self, url: URL) -> URL:
+        if url.raw_path.endswith(b"/"):
+            return url
+        return url.copy_with(raw_path=url.raw_path + b"/")
+
+    def _make_status_error_from_response(
+        self,
+        response: httpx.Response,
+    ) -> APIStatusError:
+        if response.is_closed and not response.is_stream_consumed:
+            # We can't read the response body as it has been closed
+            # before it was read. This can happen if an event hook
+            # raises a status error.
+            body = None
+            err_msg = f"Error code: {response.status_code}"
+        else:
+            err_text = response.text.strip()
+            body = err_text
+
+            try:
+                body = json.loads(err_text)
+                err_msg = f"Error code: {response.status_code} - {body}"
+            except Exception:
+                err_msg = err_text or f"Error code: {response.status_code}"
+
+        return self._make_status_error(err_msg, body=body, response=response)
+
+    def _make_status_error(
+        self,
+        err_msg: str,
+        *,
+        body: object,
+        response: httpx.Response,
+    ) -> _exceptions.APIStatusError:
+        raise NotImplementedError()
+
+    @property
+    def _auth_by_scheme(self) -> dict[str, SchemeCredentials]:
+        """The credentials each security scheme is sent with, by the scheme's name in the document."""
+        return {}
+
+    def _select_auth(self, security: SecurityOptions) -> SchemeCredentials:
+        """
+        The credentials an operation with its own `security` requirements is sent with.
+
+        The first alternative whose schemes all have a configured credential wins, and only its
+        credentials are sent: two schemes can share a wire slot (`Authorization` for Basic and
+        Bearer), so merging every configured credential would let one overwrite the one the
+        operation asked for. An empty alternative is the anonymous one and selects nothing.
+
+        With no alternative met, the configured part of the first alternative that has one is sent:
+        the request only goes out at all when the caller supplies the rest some other way (see
+        `_credential_supplied`), and withholding the half the client holds would leave it incomplete.
+        An empty (anonymous) alternative counts as met, so an operation that also accepts `{}` is sent
+        nothing rather than a partial credential. Only schemes the operation names are ever sent.
+        """
+        available = self._auth_by_scheme
+        partial: SchemeCredentials | None = None
+        for alternative in security:
+            parts = [available.get(scheme) for scheme in alternative]
+            configured = [part for part in parts if part is not None and part.configured]
+            if len(configured) == len(parts):
+                return _merge_scheme_credentials(configured)
+            if partial is None and configured:
+                partial = _merge_scheme_credentials(configured)
+        return partial if partial is not None else SchemeCredentials()
+
+    @property
+    def _auth_locations(self) -> AuthLocations:
+        """Where the client's credentials travel, configured or not."""
+        return AuthLocations()
+
+    def _credential_supplied(
+        self,
+        security: SecurityOptions,
+        headers: Mapping[str, str],
+        custom_headers: Headers,
+        params: Query,
+        cookies: Mapping[str, str],
+    ) -> bool:
+        """
+        Whether the request already carries a credential the caller set some other way than a client
+        option — the client's `default_headers` or `default_query`, or the call's `extra_headers` or
+        `extra_query` — or omits a credential header on purpose, as the client-wide check accepts.
+
+        A value `_select_auth` put on the request is the client's own partial credential, not the
+        caller's, so it never counts: a half-configured alternative is refused unless the caller
+        supplies the rest.
+        """
+        locations = self._auth_locations
+        selected = self._select_auth(security)
+        selected_headers = {name.lower(): value for name, value in selected.headers.items()}
+        return (
+            any(
+                name.lower() in locations.headers and value and selected_headers.get(name.lower()) != value
+                for name, value in headers.items()
+            )
+            or any(
+                name.lower() in locations.headers and isinstance(value, Omit) for name, value in custom_headers.items()
+            )
+            or any(
+                params.get(name) is not None and params.get(name) != selected.query.get(name)
+                for name in locations.query
+            )
+            or any(
+                cookies.get(name) is not None and cookies.get(name) != selected.cookies.get(name)
+                for name in locations.cookies
+            )
+        )
+
+    def _security_met(self, security: SecurityOptions) -> bool:
+        """
+        Whether an operation's own requirements can be met: it is public (`[]`), lists the anonymous
+        alternative (an empty one), or the credentials of some alternative are all configured.
+        """
+        available = self._auth_by_scheme
+        return not security or any(
+            all((part := available.get(scheme)) is not None and part.configured for scheme in alternative)
+            for alternative in security
+        )
+
+    def _auth_query(
+        self,
+        security: SecurityOptions | None,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _auth_cookies(
+        self,
+        security: SecurityOptions | None,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _custom_auth(
+        self,
+        security: SecurityOptions | None,  # noqa: ARG002
+    ) -> httpx.Auth | None:
+        # Single hook for custom httpx auth on both the sync and async request paths. It defaults to
+        # the legacy public `custom_auth` property so subclasses that already override that property
+        # keep applying identically on both paths; override `_custom_auth` itself to layer
+        # per-operation, security-aware auth on top.
+        return self.custom_auth
+
+    def _build_headers(
+        self,
+        options: FinalRequestOptions,
+        *,
+        params: Query,
+        cookies: Mapping[str, str],
+        retries_taken: int = 0,
+    ) -> httpx.Headers:
+        custom_headers = options.headers or {}
+        # Auth headers are folded into `default_headers` (matching the reference SDKs), so
+        # merging `default_headers` here already applies the configured credentials.
+        default_headers = self.default_headers
+        if options.security is not None:
+            # The operation names its own requirements: swap the client-wide credential headers for
+            # the selected alternative's, keeping any header the caller configured on the client.
+            auth_names = {name.lower() for name in self.auth_headers}
+            custom_names = {name.lower() for name in self._custom_headers}
+            default_headers = {
+                **{
+                    name: value
+                    for name, value in default_headers.items()
+                    if name.lower() not in auth_names or name.lower() in custom_names
+                },
+                **self._select_auth(options.security).headers,
+                **self._custom_headers,
+            }
+        headers_dict = _merge_mappings(default_headers, custom_headers)
+        if options.security is None:
+            # The client-wide check that some credential is configured.
+            self._validate_headers(headers_dict, custom_headers, params, cookies)
+        elif not self._security_met(options.security) and not self._credential_supplied(
+            options.security, headers_dict, custom_headers, params, cookies
+        ):
+            # An operation naming its own requirements is checked against those alone: a public one
+            # or one met by a query key is never refused for want of a header, and the client-wide
+            # check would both pass a document whose root allows anonymous calls and name credentials
+            # that cannot meet this operation. A credential the caller supplies outside the client's
+            # options takes the place of a configured one; the selected credentials are already
+            # swapped in above, so an unselected configured one does not count.
+            alternatives = " or ".join(" + ".join(alternative) for alternative in options.security)
+            raise TypeError(
+                f"Could not resolve authentication method for this operation. Expected the credentials of {alternatives} to be set."
+            )
+
+        # headers are case-insensitive while dictionaries are not.
+        headers = httpx.Headers(headers_dict)
+
+        idempotency_header = self._idempotency_header
+        if idempotency_header and options.idempotency_key and idempotency_header not in headers:
+            headers[idempotency_header] = options.idempotency_key
+
+        # Don't set these headers if they were already set or removed by the caller. We check
+        # `custom_headers`, which can contain `Omit()`, instead of `headers` to account for the removal case.
+        lower_custom_headers = [header.lower() for header in custom_headers]
+        if "x-scalar-retry-count" not in lower_custom_headers:
+            headers["x-scalar-retry-count"] = str(retries_taken)
+        if "x-scalar-read-timeout" not in lower_custom_headers:
+            timeout = self.timeout if isinstance(options.timeout, NotGiven) else options.timeout
+            if isinstance(timeout, Timeout):
+                timeout = timeout.read
+            if timeout is not None:
+                headers["x-scalar-read-timeout"] = str(timeout)
+
+        return headers
+
+    def _prepare_url(self, url: str) -> URL:
+        """
+        Merge a URL argument together with any 'base_url' on the client,
+        to create the URL used for the outgoing request.
+        """
+        target = URL(url)
+        if target.is_absolute_url:
+            return target
+
+        # A relative URL always extends the base path, even when it starts with "/": operation paths
+        # are written from the API root, which is wherever `base_url` points. Exactly one "/" joins
+        # the two halves. `raw_path` carries the query string, so a query on `url` is kept.
+        base_path = self.base_url.raw_path.rstrip(b"/")
+        return self.base_url.copy_with(raw_path=b"/".join((base_path, target.raw_path.lstrip(b"/"))))
+
+    def _make_sse_decoder(self) -> SSEDecoder | SSEBytesDecoder:
+        return SSEDecoder()
+
+    def _build_request(
+        self,
+        options: FinalRequestOptions,
+        *,
+        retries_taken: int = 0,
+    ) -> httpx.Request:
+        if log.isEnabledFor(logging.DEBUG):
+            # The request bodies are described, never dumped: a body carries whatever the caller
+            # sends (passwords, tokens, personal data), and the log redaction only knows credential
+            # header and query names. The headers and params are dumped, masked by that redaction.
+            dumped = model_dump(
+                options,
+                exclude_unset=True,
+                exclude={"content", "json_data", "extra_json", "files"},
+            )
+            for name in ("content", "json_data", "extra_json", "files"):
+                value: object = getattr(options, name, None)
+                if value is not None and is_given(value):
+                    dumped[name] = _describe_body(value)
+            log.debug("Request options: %s", dumped)
+        kwargs: dict[str, Any] = {}
+
+        json_data = options.json_data
+        if options.extra_json is not None:
+            if json_data is None:
+                json_data = cast(Body, options.extra_json)
+            elif is_mapping(json_data):
+                json_data = _merge_mappings(json_data, options.extra_json)
+            else:
+                raise RuntimeError(f"Unexpected JSON data type, {type(json_data)}, cannot merge with `extra_body`")
+
+        params = _merge_mappings({**self._auth_query(options.security), **self.default_query}, options.params)
+        cookies = self._auth_cookies(options.security)
+        headers = self._build_headers(options, retries_taken=retries_taken, params=params, cookies=cookies)
+        content_type = headers.get("Content-Type")
+        files = options.files
+
+        # If the given Content-Type header is multipart/form-data then it
+        # has to be removed so that httpx can generate the header with
+        # additional information for us as it has to be in this form
+        # for the server to be able to correctly parse the request:
+        # multipart/form-data; boundary=---abc--
+        if content_type is not None and content_type.startswith("multipart/form-data"):
+            if "boundary" not in content_type:
+                # only remove the header if the boundary hasn't been explicitly set
+                # as the caller doesn't want httpx to come up with their own boundary
+                headers.pop("Content-Type")
+
+            # As we are now sending multipart/form-data instead of application/json
+            # we need to tell httpx to use it, https://www.python-httpx.org/advanced/clients/#multipart-file-encoding
+            if json_data:
+                if not is_dict(json_data):
+                    raise TypeError(
+                        f"Expected query input to be a dictionary for multipart requests but got {type(json_data)} instead."
+                    )
+                kwargs["data"] = self._serialize_multipartform(json_data)
+
+            # httpx determines whether or not to send a "multipart/form-data"
+            # request based on the truthiness of the "files" argument.
+            # This gets around that issue by generating a dict value that
+            # evaluates to true.
+            #
+            # https://github.com/encode/httpx/discussions/2399#discussioncomment-3814186
+            if not files:
+                files = cast(HttpxRequestFiles, ForceMultipartDict())
+
+        prepared_url = self._prepare_url(options.url)
+        # preserve hard-coded query params from the url
+        if params and prepared_url.query:
+            params = {**dict(prepared_url.params.items()), **params}
+            prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0])
+        if "_" in prepared_url.host:
+            # work around https://github.com/encode/httpx/discussions/2880
+            kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}
+
+        is_body_allowed = options.method.lower() != "get"
+
+        if is_body_allowed:
+            if options.content is not None and json_data is not None:
+                raise TypeError("Passing both `content` and `json_data` is not supported")
+            if options.content is not None and files is not None:
+                raise TypeError("Passing both `content` and `files` is not supported")
+            if options.content is not None:
+                kwargs["content"] = options.content
+            elif isinstance(json_data, bytes):
+                kwargs["content"] = json_data
+            elif not files:
+                # Don't set content when JSON is sent as multipart/form-data,
+                # since httpx's content param overrides other body arguments
+                kwargs["content"] = openapi_dumps(json_data) if is_given(json_data) and json_data is not None else None
+            kwargs["files"] = files
+        else:
+            headers.pop("Content-Type", None)
+            kwargs.pop("data", None)
+
+        # TODO: report this error to httpx
+        return self._client.build_request(  # pyright: ignore[reportUnknownMemberType]
+            headers=headers,
+            timeout=self.timeout if isinstance(options.timeout, NotGiven) else options.timeout,
+            method=options.method,
+            url=prepared_url,
+            # the `Query` type that we use is incompatible with qs'
+            # `Params` type as it needs to be typed as `Mapping[str, object]`
+            # so that passing a `TypedDict` doesn't cause an error.
+            # https://github.com/microsoft/pyright/issues/3526#event-6715453066
+            params=self.qs.stringify(cast(Mapping[str, Any], params)) if params else None,
+            cookies=cookies or None,
+            **kwargs,
+        )
+
+    def _serialize_multipartform(self, data: Mapping[object, object]) -> dict[str, object]:
+        items = self.qs.stringify_items(
+            # TODO: type ignore is required as stringify_items is well typed but we can't be
+            # well typed without heavy validation.
+            data,  # type: ignore
+            array_format="brackets",
+        )
+        serialized: dict[str, object] = {}
+        for key, value in items:
+            existing = serialized.get(key)
+
+            if not existing:
+                serialized[key] = value
+                continue
+
+            # If a value has already been set for this key then that
+            # means we're sending data like `array[]=[1, 2, 3]` and we
+            # need to tell httpx that we want to send multiple values with
+            # the same key which is done by using a list or a tuple.
+            #
+            # Note: 2d arrays should never result in the same key at both
+            # levels so it's safe to assume that if the value is a list,
+            # it was because we changed it to be a list.
+            if is_list(existing):
+                existing.append(value)
+            else:
+                serialized[key] = [existing, value]
+
+        return serialized
+
+    def _maybe_override_cast_to(self, cast_to: type[ResponseT], options: FinalRequestOptions) -> type[ResponseT]:
+        if not is_given(options.headers):
+            return cast_to
+
+        # make a copy of the headers so we don't mutate user-input
+        headers = dict(options.headers)
+
+        # we internally support defining a temporary header to override the
+        # default `cast_to` type for use with `.with_raw_response` and `.with_streaming_response`
+        # see _response.py for implementation details
+        override_cast_to = headers.pop(OVERRIDE_CAST_TO_HEADER, not_given)
+        if is_given(override_cast_to):
+            options.headers = headers
+            return cast(Type[ResponseT], override_cast_to)
+
+        return cast_to
+
+    def _should_stream_response_body(self, request: httpx.Request) -> bool:
+        return request.headers.get(RAW_RESPONSE_HEADER) == "stream"  # type: ignore[no-any-return]
+
+    def _process_response_data(
+        self,
+        *,
+        data: object,
+        cast_to: type[ResponseT],
+        response: httpx.Response,
+    ) -> ResponseT:
+        if data is None:
+            return cast(ResponseT, None)
+
+        if cast_to is object:
+            return cast(ResponseT, data)
+
+        try:
+            if inspect.isclass(cast_to) and issubclass(cast_to, ModelBuilderProtocol):
+                return cast(ResponseT, cast_to.build(response=response, data=data))
+
+            if self._strict_response_validation:
+                return cast(ResponseT, validate_type(type_=cast_to, value=data))
+
+            return cast(ResponseT, construct_type(type_=cast_to, value=data))
+        except pydantic.ValidationError as err:
+            raise APIResponseValidationError(response=response, body=data) from err
+
+    @property
+    def qs(self) -> Querystring:
+        return Querystring()
+
+    @property
+    def custom_auth(self) -> httpx.Auth | None:
+        return None
+
+    @property
+    def auth_headers(self) -> dict[str, str]:
+        return {}
+
+    @property
+    def default_headers(self) -> dict[str, str | Omit]:
+        return {
+            "Accept": "application/json",
+            # Only the codings `BoundedDecoder` inflates in bounded steps; httpx would otherwise add br
+            # and zstd whenever their optional packages are installed, and inflates those unbounded.
+            "Accept-Encoding": "gzip, deflate",
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+            **self.platform_headers(),
+            **self.auth_headers,
+            **self._custom_headers,
+        }
+
+    @property
+    def default_query(self) -> dict[str, object]:
+        return {
+            **self._custom_query,
+        }
+
+    def _validate_headers(
+        self,
+        headers: Headers,  # noqa: ARG002
+        custom_headers: Headers,  # noqa: ARG002
+        params: Query,  # noqa: ARG002
+        cookies: Mapping[str, str],  # noqa: ARG002
+    ) -> None:
+        """Validate merged auth-bearing headers, query params, and cookies.
+
+        Does nothing by default.
+        """
+        return
+
+    @property
+    def user_agent(self) -> str:
+        return f"{self.__class__.__name__}/Python {self._version}"
+
+    @property
+    def base_url(self) -> URL:
+        return self._base_url
+
+    @base_url.setter
+    def base_url(self, url: URL | str) -> None:
+        self._base_url = self._enforce_trailing_slash(url if isinstance(url, URL) else URL(url))
+
+    def platform_headers(self) -> Dict[str, str]:
+        # the actual implementation is in a separate `lru_cache` decorated
+        # function because adding `lru_cache` to methods will leak memory
+        # https://github.com/python/cpython/issues/88476
+        return platform_headers(self._version, platform=self._platform)
+
+    def _parse_retry_after_header(self, response_headers: Optional[httpx.Headers] = None) -> float | None:
+        """Returns a float of the number of seconds (not milliseconds) to wait after retrying, or None if unspecified.
+
+        About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+        See also  https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After#syntax
+        """
+        if response_headers is None:
+            return None
+
+        # First, try the non-standard `retry-after-ms` header for milliseconds,
+        # which is more precise than integer-seconds `retry-after`
+        try:
+            retry_ms_header = response_headers.get("retry-after-ms", None)
+            return float(retry_ms_header) / 1000
+        except (TypeError, ValueError):
+            pass
+
+        # Next, try parsing `retry-after` header as seconds (allowing nonstandard floats).
+        retry_header = response_headers.get("retry-after")
+        try:
+            # note: the spec indicates that this should only ever be an integer
+            # but if someone sends a float there's no reason for us to not respect it
+            return float(retry_header)
+        except (TypeError, ValueError):
+            pass
+
+        # Last, try parsing `retry-after` as a date.
+        retry_date_tuple = email.utils.parsedate_tz(retry_header)
+        if retry_date_tuple is None:
+            return None
+
+        retry_date = email.utils.mktime_tz(retry_date_tuple)
+        return float(retry_date - time.time())
+
+    def _calculate_retry_timeout(
+        self,
+        remaining_retries: int,
+        options: FinalRequestOptions,
+        response_headers: Optional[httpx.Headers] = None,
+    ) -> float:
+        max_retries = options.get_max_retries(self.max_retries)
+
+        # If the API asks us to wait a certain amount of time (and it's a reasonable amount), just do what it says.
+        retry_after = self._parse_retry_after_header(response_headers)
+        if retry_after is not None and 0 < retry_after <= 60:
+            return retry_after
+
+        # Also cap retry count to 1000 to avoid any potential overflows with `pow`
+        nb_retries = min(max_retries - remaining_retries, 1000)
+
+        # Apply exponential backoff, but not more than the max.
+        sleep_seconds = min(INITIAL_RETRY_DELAY * pow(2.0, nb_retries), MAX_RETRY_DELAY)
+
+        # Apply some jitter, plus-or-minus half a second.
+        jitter = 1 - 0.25 * random()
+        timeout = sleep_seconds * jitter
+        return timeout if timeout >= 0 else 0
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        # Note: this is not a standard header
+        should_retry_header = response.headers.get("x-should-retry")
+
+        # If the server explicitly says whether or not to retry, obey.
+        if should_retry_header == "true":
+            log.debug("Retrying as header `x-should-retry` is set to `true`")
+            return True
+        if should_retry_header == "false":
+            log.debug("Not retrying as header `x-should-retry` is set to `false`")
+            return False
+
+        # Retry on request timeouts.
+        if response.status_code == 408:
+            log.debug("Retrying due to status code %i", response.status_code)
+            return True
+
+        # Retry on lock timeouts.
+        if response.status_code == 409:
+            log.debug("Retrying due to status code %i", response.status_code)
+            return True
+
+        # Retry on rate limits.
+        if response.status_code == 429:
+            log.debug("Retrying due to status code %i", response.status_code)
+            return True
+
+        # Retry internal errors.
+        if response.status_code >= 500:
+            log.debug("Retrying due to status code %i", response.status_code)
+            return True
+
+        log.debug("Not retrying")
+        return False
+
+    def _idempotency_key(self) -> str:
+        return f"scalar-python-retry-{uuid.uuid4()}"
+
+
+class _DefaultHttpxClient(httpx.Client):
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+        kwargs.setdefault("limits", DEFAULT_CONNECTION_LIMITS)
+        # The SDK follows redirects itself (see `_send_following_redirects`), so httpx never does.
+        kwargs.setdefault("follow_redirects", False)
+        super().__init__(**kwargs)
+
+
+if TYPE_CHECKING:
+    DefaultHttpxClient = httpx.Client
+    """An alias to `httpx.Client` that provides the same defaults that this SDK
+    uses internally.
+
+    This is useful because overriding the `http_client` with your own instance of
+    `httpx.Client` will result in httpx's defaults being used, not ours.
+    """
+else:
+    DefaultHttpxClient = _DefaultHttpxClient
+
+
+class SyncHttpxClientWrapper(DefaultHttpxClient):
+    def __del__(self) -> None:
+        if self.is_closed:
+            return
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+class SyncAPIClient(BaseClient[httpx.Client, Stream[Any]]):
+    _client: httpx.Client
+    _default_stream_cls: type[Stream[Any]] | None = None
+
+    def __init__(
+        self,
+        *,
+        version: str,
+        base_url: str | URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float | Timeout | None | NotGiven = not_given,
+        http_client: httpx.Client | None = None,
+        custom_headers: Mapping[str, str] | None = None,
+        custom_query: Mapping[str, object] | None = None,
+        _strict_response_validation: bool,
+        **kwargs: Any,
+    ) -> None:
+        if not is_given(timeout):
+            # if the user passed in a custom http client with a non-default
+            # timeout set then we use that timeout.
+            #
+            # note: there is an edge case here where the user passes in a client
+            # where they've explicitly set the timeout to match the default timeout
+            # as this check is structural, meaning that we'll think they didn't
+            # pass in a timeout and will ignore it
+            if http_client and http_client.timeout != HTTPX_DEFAULT_TIMEOUT:
+                timeout = http_client.timeout
+            else:
+                timeout = DEFAULT_TIMEOUT
+
+        if http_client is not None and not isinstance(http_client, httpx.Client):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError(
+                f"Invalid `http_client` argument; Expected an instance of `httpx.Client` but got {type(http_client)}"
+            )
+
+        super().__init__(
+            version=version,
+            # cast to a valid type because mypy doesn't understand our type narrowing
+            timeout=cast(Timeout, timeout),
+            base_url=base_url,
+            max_retries=max_retries,
+            custom_query=custom_query,
+            custom_headers=custom_headers,
+            _strict_response_validation=_strict_response_validation,
+        )
+        self._client = http_client or SyncHttpxClientWrapper(
+            base_url=base_url,
+            # cast to a valid type because mypy doesn't understand our type narrowing
+            timeout=cast(Timeout, timeout),
+            # Used by generated `with_options(_extra_kwargs=...)` for HTTPX client configuration.
+            **kwargs,
+        )
+
+    def is_closed(self) -> bool:
+        return self._client.is_closed
+
+    def close(self) -> None:
+        """Close the underlying HTTPX client.
+
+        The client will *not* be usable after this.
+        """
+        # If an error is thrown while constructing a client, self._client
+        # may not be present
+        if hasattr(self, "_client"):
+            self._client.close()
+
+    def __enter__(self: _T) -> _T:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _prepare_options(
+        self,
+        options: FinalRequestOptions,  # noqa: ARG002
+    ) -> FinalRequestOptions:
+        """Hook for mutating the given options"""
+        return options
+
+    def _prepare_request(
+        self,
+        request: httpx.Request,  # noqa: ARG002
+    ) -> None:
+        """This method is used as a callback for mutating the `Request` object
+        after it has been constructed.
+        This is useful for cases where you want to add certain headers based off of
+        the request properties, e.g. `url`, `method` etc.
+        """
+        return None
+
+    def _send_following_redirects(
+        self,
+        request: httpx.Request,
+        *,
+        options: FinalRequestOptions,
+        auth: httpx.Auth | None,
+    ) -> httpx.Response:
+        """Sends `request`, following redirects in the SDK rather than in httpx, and returns the final response unread.
+
+        httpx is told not to follow on every send, so a caller-supplied `http_client` built with
+        `follow_redirects=True` cannot follow either: httpx strips only `Authorization` on a
+        cross-origin hop and would resend an API key header, cookies and a 307/308 body to whatever
+        host the server names. See `_redirect_request` for what each hop keeps. A hop that has left
+        the origin is sent with a no-op `auth`, so neither `custom_auth`, the caller's client-level
+        `auth=` nor a `.netrc` entry (httpx < 0.24 reads one by default) signs it.
+
+        `options.follow_redirects=False` turns following off altogether: the 3xx itself reaches the
+        caller as a status error. Unset or `True`, the SDK follows at most `MAX_REDIRECTS` hops.
+        """
+        keep_credentials = True
+        hops = 0
+        while True:
+            kwargs: HttpxSendArgs = {"follow_redirects": False}
+            if not keep_credentials:
+                kwargs["auth"] = httpx.Auth()
+            elif auth is not None:
+                kwargs["auth"] = auth
+            sent_headers = httpx.Headers(request.headers)
+            response = self._client.send(request, stream=True, **kwargs)
+            if options.follow_redirects is False or not _is_followed_redirect(response):
+                return response
+            try:
+                if hops >= MAX_REDIRECTS:
+                    raise _RedirectRefused(f"Maximum redirects ({MAX_REDIRECTS}) exceeded", request=request)
+                request, keep_credentials = _redirect_request(
+                    request, response, sent_headers=sent_headers, keep_credentials=keep_credentials
+                )
+            finally:
+                response.close()
+            hops += 1
+            log.debug("Following redirect %i to %s", response.status_code, request.url)
+
+    @overload
+    def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: Literal[True],
+        stream_cls: Type[_StreamT],
+    ) -> _StreamT: ...
+
+    @overload
+    def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: bool = False,
+        stream_cls: Type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT: ...
+
+    def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: bool = False,
+        stream_cls: type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT:
+        cast_to = self._maybe_override_cast_to(cast_to, options)
+
+        # create a copy of the options we were given so that if the
+        # options are mutated later & we then retry, the retries are
+        # given the original options
+        input_options = model_copy(options)
+        if input_options.idempotency_key is None and input_options.method.lower() != "get":
+            # ensure the idempotency key is reused between requests
+            input_options.idempotency_key = self._idempotency_key()
+
+        response: httpx.Response | None = None
+        max_retries = input_options.get_max_retries(self.max_retries)
+
+        retries_taken = 0
+        for retries_taken in range(max_retries + 1):
+            options = model_copy(input_options)
+            options = self._prepare_options(options)
+
+            remaining_retries = max_retries - retries_taken
+            request = self._build_request(options, retries_taken=retries_taken)
+            self._prepare_request(request)
+
+            custom_auth = self._custom_auth(options.security)
+            streamed = stream or self._should_stream_response_body(request=request)
+
+            log.debug("Sending HTTP Request: %s %s", request.method, request.url)
+
+            response = None
+            try:
+                response = self._send_following_redirects(request, options=options, auth=custom_auth)
+                # The body's deadline starts once the headers are in: sending the request and waiting
+                # for the answer are bounded by httpx's own write and read timeouts.
+                started = time.monotonic()
+                if not streamed:
+                    # Only a successful download is the caller's to bound; an error body is read for
+                    # its message, capped and on the deadline like any other.
+                    unbounded = _is_unbuffered_cast(cast_to) and response.is_success
+                    _read_body(
+                        response,
+                        capped=not unbounded,
+                        deadline=None if unbounded else _read_deadline(request, started),
+                    )
+            except _RedirectRefused as err:
+                log.debug("Refusing redirect: %s", err.message)
+                raise APIConnectionError(message=err.message, request=err.request) from None
+            except _BodyRefused as err:
+                log.debug("Refusing response body: %s", err.message)
+                raise APIError(err.message, err.request, body=None) from None
+            except httpx.TimeoutException as err:
+                log.debug("Encountered httpx.TimeoutException", exc_info=True)
+
+                if remaining_retries > 0:
+                    self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=None,
+                    )
+                    continue
+
+                log.debug("Raising timeout error")
+                raise APITimeoutError(request=request) from err
+            except Exception as err:
+                log.debug("Encountered Exception", exc_info=True)
+
+                if remaining_retries > 0:
+                    self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=None,
+                    )
+                    continue
+
+                log.debug("Raising connection error")
+                raise APIConnectionError(request=request) from err
+
+            log.debug(
+                'HTTP Response: %s %s "%i %s" %s',
+                response.request.method,
+                response.request.url,
+                response.status_code,
+                response.reason_phrase,
+                response.headers,
+            )
+
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as err:  # thrown on 3xx (one not followed), 4xx and 5xx
+                log.debug("Encountered httpx.HTTPStatusError", exc_info=True)
+
+                if remaining_retries > 0 and self._should_retry(err.response):
+                    err.response.close()
+                    self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=response,
+                    )
+                    continue
+
+                # A streamed response is still unread: read the first `MAX_ERROR_BODY_BYTES` of it
+                # for the message, within the read deadline, never the whole body a hostile server
+                # could make endless or trickle forever.
+                if not err.response.is_closed:
+                    _read_body(
+                        err.response, capped=True, deadline=_read_deadline(err.response.request, time.monotonic())
+                    )
+
+                log.debug("Re-raising status error")
+                raise self._make_status_error_from_response(err.response) from None
+
+            break
+
+        assert response is not None, "could not resolve response (should never happen)"
+        return self._process_response(
+            cast_to=cast_to,
+            options=options,
+            response=response,
+            stream=stream,
+            stream_cls=stream_cls,
+            retries_taken=retries_taken,
+        )
+
+    def _sleep_for_retry(
+        self, *, retries_taken: int, max_retries: int, options: FinalRequestOptions, response: httpx.Response | None
+    ) -> None:
+        remaining_retries = max_retries - retries_taken
+        if remaining_retries == 1:
+            log.debug("1 retry left")
+        else:
+            log.debug("%i retries left", remaining_retries)
+
+        timeout = self._calculate_retry_timeout(remaining_retries, options, response.headers if response else None)
+        log.info("Retrying request to %s in %f seconds", options.url, timeout)
+
+        time.sleep(timeout)
+
+    def _process_response(
+        self,
+        *,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        response: httpx.Response,
+        stream: bool,
+        stream_cls: type[Stream[Any]] | type[AsyncStream[Any]] | None,
+        retries_taken: int = 0,
+    ) -> ResponseT:
+        origin = get_origin(cast_to) or cast_to
+
+        if (
+            inspect.isclass(origin)
+            and issubclass(origin, BaseAPIResponse)
+            # we only want to actually return the custom BaseAPIResponse class if we're
+            # returning the raw response, or if we're not streaming SSE, as if we're streaming
+            # SSE then `cast_to` doesn't actively reflect the type we need to parse into
+            and (not stream or bool(response.request.headers.get(RAW_RESPONSE_HEADER)))
+        ):
+            if not issubclass(origin, APIResponse):
+                raise TypeError(f"API Response types must subclass {APIResponse}; Received {origin}")
+
+            response_cls = cast("type[BaseAPIResponse[Any]]", cast_to)
+            return cast(
+                ResponseT,
+                response_cls(
+                    raw=response,
+                    client=self,
+                    cast_to=extract_response_type(response_cls),
+                    stream=stream,
+                    stream_cls=stream_cls,
+                    options=options,
+                    retries_taken=retries_taken,
+                ),
+            )
+
+        if cast_to == httpx.Response:
+            return cast(ResponseT, response)
+
+        api_response = APIResponse(
+            raw=response,
+            client=self,
+            cast_to=cast("type[ResponseT]", cast_to),  # pyright: ignore[reportUnnecessaryCast]
+            stream=stream,
+            stream_cls=stream_cls,
+            options=options,
+            retries_taken=retries_taken,
+        )
+        if bool(response.request.headers.get(RAW_RESPONSE_HEADER)):
+            return cast(ResponseT, api_response)
+
+        return api_response.parse()
+
+    def _request_api_list(
+        self,
+        model: Type[object],
+        page: Type[SyncPageT],
+        options: FinalRequestOptions,
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> SyncPageT:
+        def _parser(resp: SyncPageT) -> SyncPageT:
+            resp._set_private_attributes(
+                client=self,
+                model=model,
+                options=options,
+                cursor_config=cursor_config,
+            )
+            return resp
+
+        options.post_parser = _parser
+
+        return self.request(page, options, stream=False)
+
+    @overload
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: Literal[True],
+        stream_cls: type[_StreamT],
+    ) -> _StreamT: ...
+
+    @overload
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: bool,
+        stream_cls: type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT: ...
+
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: bool = False,
+        stream_cls: type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT:
+        opts = FinalRequestOptions.construct(method="get", url=path, **options)
+        # cast is required because mypy complains about returning Any even though
+        # it understands the type variables
+        return cast(ResponseT, self.request(cast_to, opts, stream=stream, stream_cls=stream_cls))
+
+    @overload
+    def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        options: RequestOptions = {},
+        files: RequestFiles | None = None,
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        options: RequestOptions = {},
+        files: RequestFiles | None = None,
+        stream: Literal[True],
+        stream_cls: type[_StreamT],
+    ) -> _StreamT: ...
+
+    @overload
+    def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        options: RequestOptions = {},
+        files: RequestFiles | None = None,
+        stream: bool,
+        stream_cls: type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT: ...
+
+    def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        options: RequestOptions = {},
+        files: RequestFiles | None = None,
+        stream: bool = False,
+        stream_cls: type[_StreamT] | None = None,
+    ) -> ResponseT | _StreamT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="post", url=path, json_data=body, content=content, files=to_httpx_files(files), **options
+        )
+        return cast(ResponseT, self.request(cast_to, opts, stream=stream, stream_cls=stream_cls))
+
+    def patch(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="patch", url=path, json_data=body, content=content, files=to_httpx_files(files), **options
+        )
+        return self.request(cast_to, opts)
+
+    def put(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="put", url=path, json_data=body, content=content, files=to_httpx_files(files), **options
+        )
+        return self.request(cast_to, opts)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: BinaryTypes | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(method="delete", url=path, json_data=body, content=content, **options)
+        return self.request(cast_to, opts)
+
+    def get_api_list(
+        self,
+        path: str,
+        *,
+        model: Type[object],
+        page: Type[SyncPageT],
+        body: Body | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        method: str = "get",
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> SyncPageT:
+        opts = FinalRequestOptions.construct(
+            method=method, url=path, json_data=body, files=to_httpx_files(files), **options
+        )
+        return self._request_api_list(model, page, opts, cursor_config=cursor_config)
+
+
+class _DefaultAsyncHttpxClient(httpx.AsyncClient):
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+        kwargs.setdefault("limits", DEFAULT_CONNECTION_LIMITS)
+        # The SDK follows redirects itself (see `_send_following_redirects`), so httpx never does.
+        kwargs.setdefault("follow_redirects", False)
+        super().__init__(**kwargs)
+
+
+try:
+    import httpx_aiohttp
+except ImportError:
+
+    class _DefaultAioHttpClient(httpx.AsyncClient):
+        def __init__(self, **_kwargs: Any) -> None:
+            raise RuntimeError("To use the aiohttp client you must have installed the package with the `aiohttp` extra")
+else:
+
+    class _DefaultAioHttpClient(httpx_aiohttp.HttpxAiohttpClient):  # type: ignore
+        def __init__(self, **kwargs: Any) -> None:
+            kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+            kwargs.setdefault("limits", DEFAULT_CONNECTION_LIMITS)
+            # The SDK follows redirects itself (see `_send_following_redirects`), so httpx never does.
+            kwargs.setdefault("follow_redirects", False)
+
+            super().__init__(**kwargs)
+
+
+if TYPE_CHECKING:
+    DefaultAsyncHttpxClient = httpx.AsyncClient
+    """An alias to `httpx.AsyncClient` that provides the same defaults that this SDK
+    uses internally.
+
+    This is useful because overriding the `http_client` with your own instance of
+    `httpx.AsyncClient` will result in httpx's defaults being used, not ours.
+    """
+
+    DefaultAioHttpClient = httpx.AsyncClient
+    """An alias to `httpx.AsyncClient` that changes the default HTTP transport to `aiohttp`."""
+else:
+    DefaultAsyncHttpxClient = _DefaultAsyncHttpxClient
+    DefaultAioHttpClient = _DefaultAioHttpClient
+
+
+class AsyncHttpxClientWrapper(DefaultAsyncHttpxClient):
+    def __del__(self) -> None:
+        if self.is_closed:
+            return
+
+        try:
+            # TODO(someday): support non asyncio runtimes here
+            asyncio.get_running_loop().create_task(self.aclose())
+        except Exception:
+            pass
+
+
+class AsyncAPIClient(BaseClient[httpx.AsyncClient, AsyncStream[Any]]):
+    _client: httpx.AsyncClient
+    _default_stream_cls: type[AsyncStream[Any]] | None = None
+
+    def __init__(
+        self,
+        *,
+        version: str,
+        base_url: str | URL,
+        _strict_response_validation: bool,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float | Timeout | None | NotGiven = not_given,
+        http_client: httpx.AsyncClient | None = None,
+        custom_headers: Mapping[str, str] | None = None,
+        custom_query: Mapping[str, object] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if not is_given(timeout):
+            # if the user passed in a custom http client with a non-default
+            # timeout set then we use that timeout.
+            #
+            # note: there is an edge case here where the user passes in a client
+            # where they've explicitly set the timeout to match the default timeout
+            # as this check is structural, meaning that we'll think they didn't
+            # pass in a timeout and will ignore it
+            if http_client and http_client.timeout != HTTPX_DEFAULT_TIMEOUT:
+                timeout = http_client.timeout
+            else:
+                timeout = DEFAULT_TIMEOUT
+
+        if http_client is not None and not isinstance(http_client, httpx.AsyncClient):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError(
+                f"Invalid `http_client` argument; Expected an instance of `httpx.AsyncClient` but got {type(http_client)}"
+            )
+
+        super().__init__(
+            version=version,
+            base_url=base_url,
+            # cast to a valid type because mypy doesn't understand our type narrowing
+            timeout=cast(Timeout, timeout),
+            max_retries=max_retries,
+            custom_query=custom_query,
+            custom_headers=custom_headers,
+            _strict_response_validation=_strict_response_validation,
+        )
+        self._client = http_client or AsyncHttpxClientWrapper(
+            base_url=base_url,
+            # cast to a valid type because mypy doesn't understand our type narrowing
+            timeout=cast(Timeout, timeout),
+            # Used by generated `with_options(_extra_kwargs=...)` for HTTPX client configuration.
+            **kwargs,
+        )
+
+    def is_closed(self) -> bool:
+        return self._client.is_closed
+
+    async def close(self) -> None:
+        """Close the underlying HTTPX client.
+
+        The client will *not* be usable after this.
+        """
+        await self._client.aclose()
+
+    async def __aenter__(self: _T) -> _T:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _prepare_options(
+        self,
+        options: FinalRequestOptions,  # noqa: ARG002
+    ) -> FinalRequestOptions:
+        """Hook for mutating the given options"""
+        return options
+
+    async def _prepare_request(
+        self,
+        request: httpx.Request,  # noqa: ARG002
+    ) -> None:
+        """This method is used as a callback for mutating the `Request` object
+        after it has been constructed.
+        This is useful for cases where you want to add certain headers based off of
+        the request properties, e.g. `url`, `method` etc.
+        """
+        return None
+
+    async def _send_following_redirects(
+        self,
+        request: httpx.Request,
+        *,
+        options: FinalRequestOptions,
+        auth: httpx.Auth | None,
+    ) -> httpx.Response:
+        """The async twin of `SyncAPIClient._send_following_redirects`, which documents the rules."""
+        keep_credentials = True
+        hops = 0
+        while True:
+            kwargs: HttpxSendArgs = {"follow_redirects": False}
+            if not keep_credentials:
+                kwargs["auth"] = httpx.Auth()
+            elif auth is not None:
+                kwargs["auth"] = auth
+            sent_headers = httpx.Headers(request.headers)
+            response = await self._client.send(request, stream=True, **kwargs)
+            if options.follow_redirects is False or not _is_followed_redirect(response):
+                return response
+            try:
+                if hops >= MAX_REDIRECTS:
+                    raise _RedirectRefused(f"Maximum redirects ({MAX_REDIRECTS}) exceeded", request=request)
+                request, keep_credentials = _redirect_request(
+                    request, response, sent_headers=sent_headers, keep_credentials=keep_credentials
+                )
+            finally:
+                await response.aclose()
+            hops += 1
+            log.debug("Following redirect %i to %s", response.status_code, request.url)
+
+    @overload
+    async def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    async def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: Literal[True],
+        stream_cls: type[_AsyncStreamT],
+    ) -> _AsyncStreamT: ...
+
+    @overload
+    async def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: bool,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT: ...
+
+    async def request(
+        self,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        *,
+        stream: bool = False,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT:
+        if self._platform is None:
+            # `get_platform` can make blocking IO calls so we
+            # execute it earlier while we are in an async context
+            self._platform = await asyncify(get_platform)()
+
+        cast_to = self._maybe_override_cast_to(cast_to, options)
+
+        # create a copy of the options we were given so that if the
+        # options are mutated later & we then retry, the retries are
+        # given the original options
+        input_options = model_copy(options)
+        if input_options.idempotency_key is None and input_options.method.lower() != "get":
+            # ensure the idempotency key is reused between requests
+            input_options.idempotency_key = self._idempotency_key()
+
+        response: httpx.Response | None = None
+        max_retries = input_options.get_max_retries(self.max_retries)
+
+        retries_taken = 0
+        for retries_taken in range(max_retries + 1):
+            options = model_copy(input_options)
+            options = await self._prepare_options(options)
+
+            remaining_retries = max_retries - retries_taken
+            request = self._build_request(options, retries_taken=retries_taken)
+            await self._prepare_request(request)
+
+            custom_auth = self._custom_auth(options.security)
+            streamed = stream or self._should_stream_response_body(request=request)
+
+            log.debug("Sending HTTP Request: %s %s", request.method, request.url)
+
+            response = None
+            try:
+                response = await self._send_following_redirects(request, options=options, auth=custom_auth)
+                # The body's deadline starts once the headers are in: sending the request and waiting
+                # for the answer are bounded by httpx's own write and read timeouts.
+                started = time.monotonic()
+                if not streamed:
+                    # Only a successful download is the caller's to bound; an error body is read for
+                    # its message, capped and on the deadline like any other.
+                    unbounded = _is_unbuffered_cast(cast_to) and response.is_success
+                    await _aread_body(
+                        response,
+                        capped=not unbounded,
+                        deadline=None if unbounded else _read_deadline(request, started),
+                    )
+            except _RedirectRefused as err:
+                log.debug("Refusing redirect: %s", err.message)
+                raise APIConnectionError(message=err.message, request=err.request) from None
+            except _BodyRefused as err:
+                log.debug("Refusing response body: %s", err.message)
+                raise APIError(err.message, err.request, body=None) from None
+            except httpx.TimeoutException as err:
+                log.debug("Encountered httpx.TimeoutException", exc_info=True)
+
+                if remaining_retries > 0:
+                    await self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=None,
+                    )
+                    continue
+
+                log.debug("Raising timeout error")
+                raise APITimeoutError(request=request) from err
+            except Exception as err:
+                log.debug("Encountered Exception", exc_info=True)
+
+                if remaining_retries > 0:
+                    await self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=None,
+                    )
+                    continue
+
+                log.debug("Raising connection error")
+                raise APIConnectionError(request=request) from err
+
+            log.debug(
+                'HTTP Response: %s %s "%i %s" %s',
+                response.request.method,
+                response.request.url,
+                response.status_code,
+                response.reason_phrase,
+                response.headers,
+            )
+
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as err:  # thrown on 3xx (one not followed), 4xx and 5xx
+                log.debug("Encountered httpx.HTTPStatusError", exc_info=True)
+
+                if remaining_retries > 0 and self._should_retry(err.response):
+                    await err.response.aclose()
+                    await self._sleep_for_retry(
+                        retries_taken=retries_taken,
+                        max_retries=max_retries,
+                        options=input_options,
+                        response=response,
+                    )
+                    continue
+
+                # A streamed response is still unread: read the first `MAX_ERROR_BODY_BYTES` of it
+                # for the message, within the read deadline, never the whole body a hostile server
+                # could make endless or trickle forever.
+                if not err.response.is_closed:
+                    await _aread_body(
+                        err.response, capped=True, deadline=_read_deadline(err.response.request, time.monotonic())
+                    )
+
+                log.debug("Re-raising status error")
+                raise self._make_status_error_from_response(err.response) from None
+
+            break
+
+        assert response is not None, "could not resolve response (should never happen)"
+        return await self._process_response(
+            cast_to=cast_to,
+            options=options,
+            response=response,
+            stream=stream,
+            stream_cls=stream_cls,
+            retries_taken=retries_taken,
+        )
+
+    async def _sleep_for_retry(
+        self, *, retries_taken: int, max_retries: int, options: FinalRequestOptions, response: httpx.Response | None
+    ) -> None:
+        remaining_retries = max_retries - retries_taken
+        if remaining_retries == 1:
+            log.debug("1 retry left")
+        else:
+            log.debug("%i retries left", remaining_retries)
+
+        timeout = self._calculate_retry_timeout(remaining_retries, options, response.headers if response else None)
+        log.info("Retrying request to %s in %f seconds", options.url, timeout)
+
+        await anyio.sleep(timeout)
+
+    async def _process_response(
+        self,
+        *,
+        cast_to: Type[ResponseT],
+        options: FinalRequestOptions,
+        response: httpx.Response,
+        stream: bool,
+        stream_cls: type[Stream[Any]] | type[AsyncStream[Any]] | None,
+        retries_taken: int = 0,
+    ) -> ResponseT:
+        origin = get_origin(cast_to) or cast_to
+
+        if (
+            inspect.isclass(origin)
+            and issubclass(origin, BaseAPIResponse)
+            # we only want to actually return the custom BaseAPIResponse class if we're
+            # returning the raw response, or if we're not streaming SSE, as if we're streaming
+            # SSE then `cast_to` doesn't actively reflect the type we need to parse into
+            and (not stream or bool(response.request.headers.get(RAW_RESPONSE_HEADER)))
+        ):
+            if not issubclass(origin, AsyncAPIResponse):
+                raise TypeError(f"API Response types must subclass {AsyncAPIResponse}; Received {origin}")
+
+            response_cls = cast("type[BaseAPIResponse[Any]]", cast_to)
+            return cast(
+                "ResponseT",
+                response_cls(
+                    raw=response,
+                    client=self,
+                    cast_to=extract_response_type(response_cls),
+                    stream=stream,
+                    stream_cls=stream_cls,
+                    options=options,
+                    retries_taken=retries_taken,
+                ),
+            )
+
+        if cast_to == httpx.Response:
+            return cast(ResponseT, response)
+
+        api_response = AsyncAPIResponse(
+            raw=response,
+            client=self,
+            cast_to=cast("type[ResponseT]", cast_to),  # pyright: ignore[reportUnnecessaryCast]
+            stream=stream,
+            stream_cls=stream_cls,
+            options=options,
+            retries_taken=retries_taken,
+        )
+        if bool(response.request.headers.get(RAW_RESPONSE_HEADER)):
+            return cast(ResponseT, api_response)
+
+        return await api_response.parse()
+
+    def _request_api_list(
+        self,
+        model: Type[_T],
+        page: Type[AsyncPageT],
+        options: FinalRequestOptions,
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> AsyncPaginator[_T, AsyncPageT]:
+        return AsyncPaginator(client=self, options=options, page_cls=page, model=model, cursor_config=cursor_config)
+
+    @overload
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: Literal[True],
+        stream_cls: type[_AsyncStreamT],
+    ) -> _AsyncStreamT: ...
+
+    @overload
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: bool,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT: ...
+
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        options: RequestOptions = {},
+        stream: bool = False,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT:
+        opts = FinalRequestOptions.construct(method="get", url=path, **options)
+        return await self.request(cast_to, opts, stream=stream, stream_cls=stream_cls)
+
+    @overload
+    async def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        stream: Literal[False] = False,
+    ) -> ResponseT: ...
+
+    @overload
+    async def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        stream: Literal[True],
+        stream_cls: type[_AsyncStreamT],
+    ) -> _AsyncStreamT: ...
+
+    @overload
+    async def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        stream: bool,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT: ...
+
+    async def post(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        stream: bool = False,
+        stream_cls: type[_AsyncStreamT] | None = None,
+    ) -> ResponseT | _AsyncStreamT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="post", url=path, json_data=body, content=content, files=await async_to_httpx_files(files), **options
+        )
+        return await self.request(cast_to, opts, stream=stream, stream_cls=stream_cls)
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="patch",
+            url=path,
+            json_data=body,
+            content=content,
+            files=await async_to_httpx_files(files),
+            **options,
+        )
+        return await self.request(cast_to, opts)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if files is not None and content is not None:
+            raise TypeError("Passing both `files` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(
+            method="put", url=path, json_data=body, content=content, files=await async_to_httpx_files(files), **options
+        )
+        return await self.request(cast_to, opts)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        cast_to: Type[ResponseT],
+        body: Body | None = None,
+        content: AsyncBinaryTypes | None = None,
+        options: RequestOptions = {},
+    ) -> ResponseT:
+        if body is not None and content is not None:
+            raise TypeError("Passing both `body` and `content` is not supported")
+        if isinstance(body, bytes):
+            warnings.warn(
+                "Passing raw bytes as `body` is deprecated and will be removed in a future version. "
+                "Please pass raw bytes via the `content` parameter instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        opts = FinalRequestOptions.construct(method="delete", url=path, json_data=body, content=content, **options)
+        return await self.request(cast_to, opts)
+
+    def get_api_list(
+        self,
+        path: str,
+        *,
+        model: Type[_T],
+        page: Type[AsyncPageT],
+        body: Body | None = None,
+        files: RequestFiles | None = None,
+        options: RequestOptions = {},
+        method: str = "get",
+        cursor_config: Optional[CursorPageConfig] = None,
+    ) -> AsyncPaginator[_T, AsyncPageT]:
+        opts = FinalRequestOptions.construct(
+            method=method, url=path, json_data=body, files=to_httpx_files(files), **options
+        )
+        return self._request_api_list(model, page, opts, cursor_config=cursor_config)
+
+
+def make_request_options(
+    *,
+    query: Query | None = None,
+    extra_headers: Headers | None = None,
+    extra_query: Query | None = None,
+    extra_body: Body | None = None,
+    idempotency_key: str | None = None,
+    timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    post_parser: PostParser | NotGiven = not_given,
+    security: SecurityOptions | None = None,
+) -> RequestOptions:
+    """Create a dict of type RequestOptions without keys of NotGiven values."""
+    options: RequestOptions = {}
+    if extra_headers is not None:
+        options["headers"] = extra_headers
+
+    if extra_body is not None:
+        options["extra_json"] = cast(AnyMapping, extra_body)
+
+    if query is not None:
+        options["params"] = query
+
+    if extra_query is not None:
+        options["params"] = {**options.get("params", {}), **extra_query}
+
+    if not isinstance(timeout, NotGiven):
+        options["timeout"] = timeout
+
+    if idempotency_key is not None:
+        options["idempotency_key"] = idempotency_key
+
+    if is_given(post_parser):
+        # internal
+        options["post_parser"] = post_parser  # type: ignore
+
+    if security is not None:
+        options["security"] = security
+
+    return options
+
+
+class ForceMultipartDict(Dict[str, None]):
+    def __bool__(self) -> bool:
+        return True
+
+
+class OtherPlatform:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    @override
+    def __str__(self) -> str:
+        return f"Other:{self.name}"
+
+
+Platform = Union[
+    OtherPlatform,
+    Literal[
+        "MacOS",
+        "Linux",
+        "Windows",
+        "FreeBSD",
+        "OpenBSD",
+        "iOS",
+        "Android",
+        "Unknown",
+    ],
+]
+
+
+def get_platform() -> Platform:
+    try:
+        system = platform.system().lower()
+        platform_name = platform.platform().lower()
+    except Exception:
+        return "Unknown"
+
+    if "iphone" in platform_name or "ipad" in platform_name:
+        # Tested using Python3IDE on an iPhone 11 and Pythonista on an iPad 7
+        # system is Darwin and platform_name is a string like:
+        # - Darwin-21.6.0-iPhone12,1-64bit
+        # - Darwin-21.6.0-iPad7,11-64bit
+        return "iOS"
+
+    if system == "darwin":
+        return "MacOS"
+
+    if system == "windows":
+        return "Windows"
+
+    if "android" in platform_name:
+        # Tested using Pydroid 3
+        # system is Linux and platform_name is a string like 'Linux-5.10.81-android12-9-00001-geba40aecb3b7-ab8534902-aarch64-with-libc'
+        return "Android"
+
+    # The BSDs are not Linux distributions: `platform.system()` reports them by name (`FreeBSD`,
+    # `OpenBSD`), so the kernel name alone tells them apart and no distribution lookup is needed.
+    if system == "freebsd":
+        return "FreeBSD"
+
+    if system == "openbsd":
+        return "OpenBSD"
+
+    if system == "linux":
+        return "Linux"
+
+    if platform_name:
+        return OtherPlatform(platform_name)
+
+    return "Unknown"
+
+
+@lru_cache(maxsize=None)
+def platform_headers(version: str, *, platform: Platform | None) -> Dict[str, str]:
+    return {
+        "X-Scalar-Lang": "python",
+        "X-Scalar-Package-Version": version,
+        "X-Scalar-OS": str(platform or get_platform()),
+        "X-Scalar-Arch": str(get_architecture()),
+        "X-Scalar-Runtime": get_python_runtime(),
+        "X-Scalar-Runtime-Version": get_python_version(),
+    }
+
+
+class OtherArch:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    @override
+    def __str__(self) -> str:
+        return f"other:{self.name}"
+
+
+Arch = Union[OtherArch, Literal["x32", "x64", "arm", "arm64", "unknown"]]
+
+
+def get_python_runtime() -> str:
+    try:
+        return platform.python_implementation()
+    except Exception:
+        return "unknown"
+
+
+def get_python_version() -> str:
+    try:
+        return platform.python_version()
+    except Exception:
+        return "unknown"
+
+
+def get_architecture() -> Arch:
+    try:
+        machine = platform.machine().lower()
+    except Exception:
+        return "unknown"
+
+    if machine in ("arm64", "aarch64"):
+        return "arm64"
+
+    # TODO: untested
+    if machine == "arm":
+        return "arm"
+
+    if machine == "x86_64":
+        return "x64"
+
+    # TODO: untested
+    if sys.maxsize <= 2**32:
+        return "x32"
+
+    if machine:
+        return OtherArch(machine)
+
+    return "unknown"
+
+
+def _merge_mappings(
+    obj1: Mapping[_T_co, Union[_T, Omit]],
+    obj2: Mapping[_T_co, Union[_T, Omit]],
+) -> Dict[_T_co, _T]:
+    """Merge two mappings of the same type, removing any values that are instances of `Omit`.
+
+    In cases with duplicate keys the second mapping takes precedence.
+    """
+    merged = {**obj1, **obj2}
+    return {key: value for key, value in merged.items() if not isinstance(value, Omit)}