positronic-platform-client 0.37.1__py3-none-any.whl

platform_client/billing.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Annotated, Self
+
+from platform_client.enums import BillingMode, BillingRole, BillingState
+from platform_client.ids import INT64_MAX as INT64_MAX
+from platform_client.ids import OrgSlug, PackageId, PurchaseId, UserId
+from positronic_evals.slug import Slugged
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, computed_field, model_validator
+
+CREDIT_SCALE = 60_000_000_000
+NANOSECONDS_PER_MINUTE = 60_000_000_000
+NANOSECONDS_PER_SECOND = 1_000_000_000
+CreditUnits = Annotated[int, Field(strict=True, ge=0, le=INT64_MAX)]
+
+
+class Tariff(BaseModel):
+    model_config = ConfigDict(extra='forbid', frozen=True)
+
+    version: str
+    episode_units: CreditUnits
+    minute_units: CreditUnits
+    duration_rounding_sec: int = Field(default=0, strict=True, ge=0, le=INT64_MAX // NANOSECONDS_PER_SECOND)
+
+    @staticmethod
+    def content_hash(episode_units: int, minute_units: int, duration_rounding_sec: int = 0) -> str:
+        content = f'v1:{CREDIT_SCALE}:{episode_units}:{minute_units}'
+        if duration_rounding_sec:
+            content = f'v2:{CREDIT_SCALE}:{episode_units}:{minute_units}:{duration_rounding_sec}'
+        return hashlib.sha256(content.encode()).hexdigest()
+
+    @classmethod
+    def for_rates(cls, episode_units: int, minute_units: int, *, duration_rounding_sec: int) -> Tariff:
+        return cls(
+            version=cls.content_hash(episode_units, minute_units, duration_rounding_sec),
+            episode_units=episode_units,
+            minute_units=minute_units,
+            duration_rounding_sec=duration_rounding_sec,
+        )
+
+    def charge_units(self, duration_ns: int) -> int:
+        if type(duration_ns) is not int or not 0 <= duration_ns <= INT64_MAX:
+            raise ValueError('duration must be an integer nanosecond count within the storage limit')
+        if self.duration_rounding_sec:
+            step_ns = self.duration_rounding_sec * NANOSECONDS_PER_SECOND
+            duration_ns = (duration_ns + step_ns - 1) // step_ns * step_ns
+        units = self.episode_units + duration_ns * self.minute_units // NANOSECONDS_PER_MINUTE
+        if units > INT64_MAX:
+            raise ValueError('episode credits exceed the storage limit')
+        return units
+
+    @model_validator(mode='after')
+    def _version_binds_the_rates(self) -> Self:
+        if self.version != self.content_hash(self.episode_units, self.minute_units, self.duration_rounding_sec):
+            raise ValueError('tariff version does not match its rates')
+        return self
+
+
+class QuoteLine(BaseModel):
+    model_config = ConfigDict(extra='forbid', frozen=True)
+
+    task_pos: int = Field(strict=True, ge=0, le=INT64_MAX)
+    endpoint: str = Field(min_length=1)
+    count: int = Field(strict=True, ge=1, le=INT64_MAX)
+    cap_ns: int = Field(strict=True, ge=1, le=INT64_MAX)
+    max_units: CreditUnits
+
+
+class CreditQuote(BaseModel):
+    model_config = ConfigDict(extra='forbid', frozen=True)
+
+    terms: Tariff
+    lines: tuple[QuoteLine, ...] = Field(min_length=1)
+    total_units: CreditUnits
+
+    @model_validator(mode='after')
+    def _lines_match_the_terms(self) -> Self:
+        bindings = [(line.task_pos, line.endpoint) for line in self.lines]
+        if len(set(bindings)) != len(bindings):
+            raise ValueError('quote repeats a task endpoint')
+        for line in self.lines:
+            maximum = line.count * self.terms.charge_units(line.cap_ns)
+            if line.max_units != maximum:
+                raise ValueError('quote line does not match its tariff')
+        if self.total_units != sum(line.max_units for line in self.lines):
+            raise ValueError('quote total does not match its lines')
+        return self
+
+
+class RequestBilling(BaseModel):
+    model_config = ConfigDict(extra='forbid', frozen=True)
+
+    mode: Slugged[BillingMode]
+    quote: CreditQuote | None = None
+    state: Slugged[BillingState]
+
+    @model_validator(mode='after')
+    def _mode_has_the_matching_quote(self) -> Self:
+        if (self.mode is BillingMode.pay_as_you_go) != (self.quote is not None):
+            raise ValueError('a pay_as_you_go request requires a quote, and a packaged request cannot carry one')
+        if self.mode is BillingMode.packaged and self.state is not BillingState.settled:
+            raise ValueError('a packaged request holds no credits')
+        return self
+
+
+class CreditBalance(BaseModel):
+    posted_units: CreditUnits
+    reserved_units: CreditUnits
+
+    @computed_field
+    @property
+    def available_units(self) -> int:
+        return self.posted_units - self.reserved_units
+
+    @model_validator(mode='after')
+    def _holds_fit_the_balance(self) -> Self:
+        if self.available_units < 0:
+            raise ValueError('reserved credits exceed posted credits')
+        return self
+
+
+class CreditPackage(BaseModel):
+    model_config = ConfigDict(extra='forbid', frozen=True)
+
+    id: PackageId = Field(min_length=1)
+    credit_units: CreditUnits = Field(gt=0)
+    amount_minor: int = Field(strict=True, gt=0, le=INT64_MAX)
+    currency: str = Field(pattern=r'^[a-z]{3}$')
+
+
+class BillingAccount(BaseModel):
+    org: OrgSlug
+    mode: Slugged[BillingMode]
+    billing_role: Slugged[BillingRole]
+    balance: CreditBalance
+    tariff: Tariff
+    packages: tuple[CreditPackage, ...]
+
+
+class PurchaseView(BaseModel):
+    id: PurchaseId = Field(min_length=1)
+    package: CreditPackage
+    initiated_by: UserId
+    created_at: AwareDatetime
+    checkout_url: str | None = Field(default=None, min_length=1)
+    granted_at: AwareDatetime | None = None
+    review_reason: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode='after')
+    def _payable_link_matches_lifecycle(self) -> Self:
+        if self.checkout_url is not None and (self.granted_at is not None or self.review_reason is not None):
+            raise ValueError('a reviewed or credited purchase cannot carry a payable link')
+        return self
+
+
+class PurchaseListResponse(BaseModel):
+    purchases: list[PurchaseView]
+    next: PurchaseId | None

platform_client/boards.py

@@ -0,0 +1,24 @@
+"""The slug a ranking board is read by. `rankings.list` names every slug the caller can read.
+
+The platform owns the set, so a board this client has never heard of still reaches the server.
+"""
+
+from __future__ import annotations
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+
+class BoardRef(str):
+    """The slug of a board the platform publishes, as a validated `str`."""
+
+    __slots__ = ()
+
+    def __new__(cls, value: str) -> BoardRef:
+        if not value or any(c.isspace() for c in value):
+            raise ValueError(f'not a board slug: {value!r}')
+        return super().__new__(cls, value)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: type, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        return core_schema.no_info_after_validator_function(cls, core_schema.str_schema())

platform_client/catalog.py

@@ -0,0 +1,62 @@
+"""What the platform offers: the evals a caller may name, and the tasks a caller may compose into one.
+
+Both lists depend on the caller's grant. Every registered user sees the evals a submission
+names, and a customer grant adds the rig's evals and tasks.
+"""
+
+from __future__ import annotations
+
+from platform_client.enums import CameraVantage, Placement, StartPose
+from platform_client.eval_plan import Clutter
+from platform_client.tasks import TaskRef
+from positronic_evals.evals import EvalRef
+from positronic_evals.slug import Slugged
+from pydantic import BaseModel, Field
+
+
+class TaskSummary(BaseModel):
+    """`catalog.tasks` — one task the caller may put in a plan, as the catalogue states it.
+
+    `tote_placement` and `external_cameras` list the sides a plan may choose, or ask `random` to
+    draw from. `external_cameras` is keyed by the mount name the task defines.
+    `default_cap_per_episode_sec` applies when the plan states no cap. `clutter` applies when the
+    plan states none; a task carrying neither draws no clutter objects. `start_pose` applies when
+    the plan states none.
+    """
+
+    id: TaskRef
+    embodiment: str
+    task: str
+    setup: str = ''
+    total_items: int | None = None
+    objects: list[str] = Field(default_factory=list)
+    tote_placement: list[Slugged[Placement]] = Field(default_factory=list)
+    camera_vantage: Slugged[CameraVantage] | None = None
+    external_cameras: dict[str, list[Slugged[Placement]]] = Field(default_factory=dict)
+    default_cap_per_episode_sec: int | None = None
+    clutter: Clutter | None = None
+    start_pose: Slugged[StartPose] = StartPose.nominal
+
+
+class EvalSummary(BaseModel):
+    """`catalog.evals` — one eval `submissions.create` accepts by name, with a policy image.
+
+    `tasks` names what the eval runs, in the embodiment's own spelling. `composable` is true for an
+    eval built from catalogue tasks: a caller may compose a plan over the same tasks. A pinned eval
+    fixes its trials and accepts no `tasks` from the caller.
+    """
+
+    id: EvalRef
+    embodiment: str
+    tasks: list[str] = Field(default_factory=list)
+    composable: bool
+    primary_metric: str | None = None
+    description: str = ''
+
+
+class TaskListResponse(BaseModel):
+    tasks: list[TaskSummary] = Field(default_factory=list)
+
+
+class EvalListResponse(BaseModel):
+    evals: list[EvalSummary] = Field(default_factory=list)

platform_client/client.py

@@ -0,0 +1,336 @@
+"""`PlatformClient` — one method per gateway endpoint, request model in, response model out.
+
+    with PlatformClient() as client:
+        # keeps the key it returns; the timeout covers the gateway's check of the credential
+        client.register(RegisterRequest(credential=..., alias=...), timeout=client.register_timeout())
+        plan = EvalPlan(request_type=PrivateEval(org=...), tasks=..., endpoints=..., episodes_per_endpoint=...)
+        client.create_submission(plan)
+
+The platform is `base_url`, else `POSITRONIC_PLATFORM_URL`, else production; the key is `api_key`,
+else `POSITRONIC_PLATFORM_API_KEY`, else whatever `register` came back with. A non-2xx raises
+`PlatformError` carrying the error envelope.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import Enum, auto
+from types import TracebackType
+from typing import Any, ClassVar, Self, TypeVar
+
+import httpx
+from platform_client import routes
+from platform_client.billing import BillingAccount, PurchaseListResponse, PurchaseView
+from platform_client.boards import BoardRef
+from platform_client.catalog import EvalListResponse, TaskListResponse
+from platform_client.errors import PlatformError
+from platform_client.eval_plan import REVEAL_REGISTRY_PASSWORD, EvalPlan
+from platform_client.identity_providers import longest_register_timeout
+from platform_client.ids import ApiKey, OrgSlug, PurchaseId, SubmissionId
+from platform_client.requests import (
+    DEFAULT_PURCHASE_PAGE_SIZE,
+    BillingOrgQuery,
+    BillingPurchaseCreateRequest,
+    BillingPurchaseGetQuery,
+    BillingPurchaseListQuery,
+    CancelRequest,
+    RankingsQuery,
+    RegisterRequest,
+    SubmissionArtifactsQuery,
+    SubmissionGetQuery,
+    SubmissionListQuery,
+)
+from platform_client.responses import (
+    ArtifactListResponse,
+    AuthConfig,
+    BoardListResponse,
+    CancelResponse,
+    MeResponse,
+    RankingsResponse,
+    RegisterResponse,
+    ResolvedPlan,
+    SubmissionCreateResponse,
+    SubmissionListResponse,
+    SubmissionView,
+)
+from pydantic import BaseModel, TypeAdapter
+
+M = TypeVar('M', bound=BaseModel)
+
+DEFAULT_TIMEOUT_S = 30.0
+
+# The platform a caller reaches with no configuration at all.
+DEFAULT_PLATFORM_URL = 'https://platform.positronic.ro'
+
+# What an authenticated call sends, what `users.register` must not, and what a caller's own client
+# may therefore not default — three places that have to agree.
+AUTH_HEADER = 'Authorization'
+
+API_URL_ENV = 'POSITRONIC_PLATFORM_URL'
+API_KEY_ENV = 'POSITRONIC_PLATFORM_API_KEY'
+CREDENTIAL_ENV = 'POSITRONIC_PLATFORM_CREDENTIAL'
+
+
+def resolve_api_key(api_key: ApiKey | None = None) -> ApiKey | None:
+    """The key to authenticate with: what the caller passed, else the environment, else none."""
+    if api_key is not None:
+        return api_key
+    from_env = os.environ.get(API_KEY_ENV)
+    return ApiKey(from_env) if from_env else None
+
+
+def require_absolute_url(url: str | httpx.URL, source: str) -> None:
+    """Refuse a base URL that does not parse or names no host, naming the value and what it has to be.
+
+    Every endpoint sends a path relative to the client's base URL, so one that names no host — empty,
+    or a bare path — resolves against nothing and the request never leaves for a platform.
+    """
+    try:
+        parsed = httpx.URL(url)
+    except httpx.InvalidURL as exc:
+        raise ValueError(f'{source} is {str(url)!r}, which does not parse as a URL: {exc}') from exc
+    if parsed.is_absolute_url:
+        return
+    raise ValueError(
+        f'{source} is {str(url)!r}, which names no host: give an absolute URL, scheme and host, naming the platform'
+    )
+
+
+def resolve_base_url(base_url: str | None = None) -> str:
+    """The platform to talk to: what the caller passed, else the environment, else the default."""
+    for value, source in ((base_url, 'base_url'), (os.environ.get(API_URL_ENV), API_URL_ENV)):
+        if value is None:
+            continue
+        # Empty is a misconfiguration, not a request for the default: `--platform-url=` reads as a
+        # platform the caller named, and falling through would send that run to the production one.
+        if not value.strip():
+            raise ValueError(f'{source} is empty; name a platform, or leave it unset for {DEFAULT_PLATFORM_URL}')
+        require_absolute_url(value, source)
+        return value
+    return DEFAULT_PLATFORM_URL
+
+
+class Auth(Enum):
+    """What an endpoint does with the client's API key."""
+
+    REQUIRED = auto()
+    # Sent when one is set: a public board answers either way, a tenant's board only with a key.
+    OPTIONAL = auto()
+    NONE = auto()
+
+
+class PlatformClient:
+    """A caller's handle on one platform.
+
+    Pass an `httpx.Client` instead of a `base_url` when the transport matters (an in-process ASGI
+    transport, a proxy, a retry policy); it carries its own base URL, so the two are exclusive.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: ApiKey | None = None,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._owns_client = client is None
+        if client is None:
+            url = resolve_base_url(base_url)
+            # An environment proxy would carry a plain-http key or token off the machine.
+            client = httpx.Client(base_url=url, timeout=timeout, trust_env=httpx.URL(url).scheme == 'https')
+        else:
+            if base_url is not None:
+                raise ValueError('a client of your own already carries its base URL; pass one or the other')
+            require_absolute_url(client.base_url, "the supplied client's base_url")
+            if AUTH_HEADER in client.headers:
+                # httpx MERGES client-level headers into every request, so a default here would reach
+                # `users.register`, which this module declares unauthenticated and the gateway reads
+                # as a registration by whoever that credential names.
+                raise ValueError(f'the supplied client carries a default {AUTH_HEADER} header; pass the key as api_key')
+            if client.auth is not None:
+                # An auth flow reaches the same requests by another route: httpx runs it on every
+                # one, so it would sign `users.register` too.
+                raise ValueError(
+                    f'the supplied client carries an auth flow, which sets {AUTH_HEADER} on every '
+                    f'request including `users.register`; pass the key as api_key'
+                )
+        self._client = client
+        self.api_key = resolve_api_key(api_key)
+
+    @property
+    def base_url(self) -> str:
+        """The platform URL this client resolved and reaches."""
+        return str(self._client.base_url)
+
+    # --- endpoints ---------------------------------------------------------------------------
+
+    def auth_config(self) -> AuthConfig:
+        """The sign-ins this platform takes."""
+        return self._get(routes.AUTH_CONFIG, AuthConfig, auth=Auth.NONE)
+
+    def register_timeout(self) -> httpx.Timeout:
+        """The bound on `users.register` for a credential of any sign-in this platform takes, from `auth.config`.
+
+        The gateway checks the credential with the identity provider inside the call, and a caller that gives
+        up first leaves a key behind that it can never read.
+        """
+        return longest_register_timeout(self.auth_config())
+
+    # `users.register` checks the credential with its identity provider before it answers.
+    DEFAULT_REGISTER_TIMEOUT: ClassVar[httpx.Timeout] = httpx.Timeout(90.0)
+
+    def register(
+        self, request: RegisterRequest, *, timeout: httpx.Timeout = DEFAULT_REGISTER_TIMEOUT
+    ) -> RegisterResponse:
+        """Create-or-return a user, KEEPING any key it returns — the next call is authenticated.
+
+        A key comes back only on a first registration or a `rotate`; a repeat registration answers
+        `existing` with none, and the client goes on holding whatever it already had. Without `timeout`
+        it waits `DEFAULT_REGISTER_TIMEOUT`; `register_timeout()` gives the bound `auth.config` implies.
+        """
+        response = self._post(routes.USERS_REGISTER, request, RegisterResponse, auth=Auth.NONE, timeout=timeout)
+        if response.api_key is not None:
+            self.api_key = response.api_key
+        return response
+
+    def me(self) -> MeResponse:
+        return self._get(routes.USERS_ME, MeResponse)
+
+    def billing_account(self, org: OrgSlug) -> BillingAccount:
+        return self._get(routes.BILLING_ACCOUNT, BillingAccount, query=BillingOrgQuery(org=org))
+
+    def create_purchase(self, request: BillingPurchaseCreateRequest) -> PurchaseView:
+        return self._post(routes.BILLING_PURCHASES_CREATE, request, PurchaseView)
+
+    def get_purchase(self, purchase_id: PurchaseId) -> PurchaseView:
+        return self._get(routes.BILLING_PURCHASES_GET, PurchaseView, query=BillingPurchaseGetQuery(id=purchase_id))
+
+    def list_purchases(
+        self, org: OrgSlug, *, after: PurchaseId | None = None, limit: int = DEFAULT_PURCHASE_PAGE_SIZE
+    ) -> PurchaseListResponse:
+        """Read one history page. Pass its `next` as `after` until `next` is None."""
+        query = BillingPurchaseListQuery(org=org, after=after, limit=limit)
+        return self._get(routes.BILLING_PURCHASES_LIST, PurchaseListResponse, query=query)
+
+    def create_submission(self, plan: EvalPlan) -> SubmissionCreateResponse:
+        """Run one plan. A plan that states its own tasks needs a customer grant: a key without one
+        is refused `forbidden`."""
+        return self._post(routes.SUBMISSIONS_CREATE, plan, SubmissionCreateResponse)
+
+    def resolve_plan(self, plan: EvalPlan) -> ResolvedPlan:
+        """The plan as it would run, with nothing filed."""
+        return self._post(routes.SUBMISSIONS_RESOLVE, plan, ResolvedPlan)
+
+    def list_submissions(
+        self, *, after: SubmissionId | None = None, limit: int | None = None
+    ) -> SubmissionListResponse:
+        """One page of the caller's submissions, oldest first — or every user's, for an admin or
+        service principal. Pass a page's `next` as `after` for the page after it."""
+        query = SubmissionListQuery(after=after, limit=limit)
+        return self._get(routes.SUBMISSIONS_LIST, SubmissionListResponse, query=query)
+
+    # The view is a discriminated union rather than a model, so it validates through an adapter.
+    # Built once, because building one costs more than the validation it then does.
+    _SUBMISSION_VIEW: ClassVar[TypeAdapter[SubmissionView]] = TypeAdapter(SubmissionView)
+
+    def get_submission(self, submission_id: SubmissionId) -> SubmissionView:
+        query = SubmissionGetQuery(id=submission_id)
+        return self._SUBMISSION_VIEW.validate_json(self._send('GET', routes.SUBMISSIONS_GET, query=query).content)
+
+    def list_artifacts(
+        self,
+        submission_id: SubmissionId,
+        *,
+        prefix: str | None = None,
+        after: str | None = None,
+        limit: int | None = None,
+    ) -> ArtifactListResponse:
+        """One page of the objects a finished submission wrote, in key order.
+
+        `prefix` keeps the page to one directory under the submission, and a page's `next` is the
+        `after` of the page behind it. A submission short of finished is refused `bad_request`.
+        """
+        query = SubmissionArtifactsQuery(id=submission_id, prefix=prefix, after=after, limit=limit)
+        return self._get(routes.SUBMISSIONS_ARTIFACTS, ArtifactListResponse, query=query)
+
+    def cancel_submission(self, request: CancelRequest) -> CancelResponse:
+        return self._post(routes.SUBMISSIONS_CANCEL, request, CancelResponse)
+
+    def rankings(self, *, board: BoardRef) -> RankingsResponse:
+        """One board by slug."""
+        query = RankingsQuery(board=board)
+        return self._get(routes.RANKINGS_GET, RankingsResponse, query=query, auth=Auth.OPTIONAL)
+
+    def list_boards(self) -> BoardListResponse:
+        """The boards this caller can read: the public ones, plus their tenant's once a key is set."""
+        return self._get(routes.RANKINGS_LIST, BoardListResponse, auth=Auth.OPTIONAL)
+
+    def catalog_evals(self) -> EvalListResponse:
+        """The evals a plan names, for this key's grant. The catalogue expands one into its tasks."""
+        return self._get(routes.CATALOG_EVALS, EvalListResponse)
+
+    def catalog_tasks(self) -> TaskListResponse:
+        """The tasks a plan may compose, for this key's grant. A key with no customer grant is refused `forbidden`."""
+        return self._get(routes.CATALOG_TASKS, TaskListResponse)
+
+    # --- plumbing ----------------------------------------------------------------------------
+
+    # Validated from the raw bytes, never from a decoded object: an id is hex text on the wire and
+    # only the JSON schema enforces that, so decoding first would take a number as well.
+    def _get(self, path: str, model: type[M], *, query: BaseModel | None = None, auth: Auth = Auth.REQUIRED) -> M:
+        return model.model_validate_json(self._send('GET', path, query=query, auth=auth).content)
+
+    def _post(
+        self,
+        path: str,
+        request: BaseModel,
+        model: type[M],
+        *,
+        auth: Auth = Auth.REQUIRED,
+        timeout: httpx.Timeout | None = None,
+    ) -> M:
+        # This dump reveals the registry password. Every other dump masks it.
+        body = request.model_dump(mode='json', context={REVEAL_REGISTRY_PASSWORD: True})
+        # None keeps the client's own timeout.
+        sent = self._send(
+            'POST', path, json=body, auth=auth, timeout=httpx.USE_CLIENT_DEFAULT if timeout is None else timeout
+        )
+        return model.model_validate_json(sent.content)
+
+    def _send(
+        self, method: str, path: str, *, query: BaseModel | None = None, auth: Auth = Auth.REQUIRED, **kwargs: Any
+    ) -> httpx.Response:
+        # `exclude_none` is what makes an unset parameter absent from the URL rather than an empty
+        # value, which the gateway would have to tell apart from a caller that meant the empty string.
+        if query is not None:
+            kwargs['params'] = query.model_dump(mode='json', exclude_none=True)
+        headers: dict[str, str] = {}
+        if auth is Auth.REQUIRED and self.api_key is None:
+            raise ValueError(f'{path} needs an API key: pass api_key=, set {API_KEY_ENV}, or call register() first')
+        if auth is not Auth.NONE and self.api_key is not None:
+            headers[AUTH_HEADER] = f'Bearer {self.api_key}'
+        response = self._client.request(method, path, headers=headers, **kwargs)
+        # Not `>= 400`: httpx follows no redirect by default, so a 3xx arrives here with a body that
+        # is not an envelope and would surface as a parse error instead of the promised PlatformError.
+        if not 200 <= response.status_code < 300:
+            try:
+                payload: object = response.json()
+            except ValueError:
+                # A failure need not carry an envelope at all: a proxy's HTML 502 arrives here too.
+                payload = response.text
+            raise PlatformError.from_payload(response.status_code, payload)
+        return response
+
+    def close(self) -> None:
+        """Close the underlying transport, unless the caller supplied its own client."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()