memydev-base-sdk 0.1.0__py3-none-any.whl

memybase/_sync/_self.py

@@ -0,0 +1,139 @@
+# GENERATED by scripts/gen_sync.py from memybase/_self.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Customer self-service operations on /api/self/*.
+@module memybase._self
+@description Mirrors the /api/self router 1:1: profile, openapi, projects CRUD + archive/restore,
+             databases CRUD, schema versions/activate, api-keys,
+             settings, plan, usage. All methods require tenant-level auth.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+# Absolute import of the shared/pure module (same pattern as _collection.py / _transport.py): unasync
+# generates memybase/_sync/_self.py, whose relative `from ._types` would resolve to a nonexistent
+# memybase/_sync/_types.py — the absolute path makes both the async module and its sync twin bind the
+# SAME single _types module.
+from memybase._types import SchemaActivationJobSummary
+
+from ._transport import Transport
+
+__all__ = ["SelfService"]
+
+_e = lambda s: quote(str(s), safe="")  # noqa: E731
+
+
+class SelfService:
+    """Async handle for authenticated /api/self/* customer endpoints."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    # ── Profile ──────────────────────────────────────────────────────────────
+    def profile(self) -> Any:
+        return self._t.request("GET", "/api/self/profile")
+
+    def openapi(self) -> Any:
+        return self._t.request("GET", "/api/self/openapi.json")
+
+    # ── Projects ─────────────────────────────────────────────────────────────
+    def list_projects(self) -> Any:
+        return self._t.request("GET", "/api/self/projects")
+
+    def create_project(self, body: dict[str, Any]) -> Any:
+        return self._t.request("POST", "/api/self/projects", json_body=body)
+
+    def get_project(self, ref: str) -> Any:
+        return self._t.request("GET", f"/api/self/projects/{_e(ref)}")
+
+    def update_project(self, ref: str, body: dict[str, Any]) -> Any:
+        return self._t.request("PATCH", f"/api/self/projects/{_e(ref)}", json_body=body)
+
+    def archive_project(self, ref: str) -> None:
+        self._t.request("POST", f"/api/self/projects/{_e(ref)}/archive")
+
+    def restore_project(self, ref: str) -> None:
+        self._t.request("POST", f"/api/self/projects/{_e(ref)}/restore")
+
+    def delete_project(self, ref: str) -> None:
+        self._t.request("DELETE", f"/api/self/projects/{_e(ref)}")
+
+    # ── Databases ────────────────────────────────────────────────────────────
+    def list_databases(self, project_ref: str) -> Any:
+        return self._t.request("GET", f"/api/self/projects/{_e(project_ref)}/databases")
+
+    def create_database(self, project_ref: str, body: dict[str, Any]) -> Any:
+        return self._t.request("POST", f"/api/self/projects/{_e(project_ref)}/databases", json_body=body)
+
+    def delete_database(self, project_ref: str, db: str) -> None:
+        self._t.request("DELETE", f"/api/self/projects/{_e(project_ref)}/databases/{_e(db)}")
+
+    def archive_database(self, project_ref: str, db: str) -> None:
+        self._t.request("POST", f"/api/self/projects/{_e(project_ref)}/databases/{_e(db)}/archive")
+
+    def restore_database(self, project_ref: str, db: str) -> None:
+        self._t.request("POST", f"/api/self/projects/{_e(project_ref)}/databases/{_e(db)}/restore")
+
+    # ── Schema ───────────────────────────────────────────────────────────────
+    def list_schema_versions(self, project_ref: str, db: str | None = None) -> Any:
+        base = f"/api/self/projects/{_e(project_ref)}"
+        path = f"{base}/databases/{_e(db)}/schema/versions" if db else f"{base}/schema/versions"
+        return self._t.request("GET", path)
+
+    def activate_schema(self, project_ref: str, draft: dict[str, Any], db: str | None = None) -> Any:
+        base = f"/api/self/projects/{_e(project_ref)}"
+        path = f"{base}/databases/{_e(db)}/schema/activate" if db else f"{base}/schema/activate"
+        return self._t.request("POST", path, json_body=draft)
+
+    def activate_schema_spec(self, project_ref: str, spec: dict[str, Any], db: str | None = None) -> Any:
+        base = f"/api/self/projects/{_e(project_ref)}"
+        path = f"{base}/databases/{_e(db)}/schema/design" if db else f"{base}/schema/design"
+        return self._t.request("POST", path, json_body=spec)
+
+    def get_schema_activation(
+        self, project_ref: str, job_id: str, db: str | None = None
+    ) -> SchemaActivationJobSummary:
+        base = f"/api/self/projects/{_e(project_ref)}"
+        path = f"{base}/databases/{_e(db)}/schema/activations/{_e(job_id)}" if db else f"{base}/schema/activations/{_e(job_id)}"
+        return self._t.request("GET", path)
+
+    def rollback_schema_activation(
+        self, project_ref: str, job_id: str, db: str | None = None
+    ) -> SchemaActivationJobSummary:
+        base = f"/api/self/projects/{_e(project_ref)}"
+        path = f"{base}/databases/{_e(db)}/schema/activations/{_e(job_id)}/rollback" if db else f"{base}/schema/activations/{_e(job_id)}/rollback"
+        return self._t.request("POST", path)
+
+    # ── Settings ─────────────────────────────────────────────────────────────
+    def get_settings(self, scope_type: str | None = None, scope_id: str | None = None) -> Any:
+        if scope_type and scope_id:
+            return self._t.request("GET", f"/api/self/settings/{_e(scope_type)}/{_e(scope_id)}")
+        return self._t.request("GET", "/api/self/settings")
+
+    def update_settings(self, values: dict[str, Any], scope_type: str | None = None, scope_id: str | None = None) -> Any:
+        if scope_type and scope_id:
+            return self._t.request("PUT", f"/api/self/settings/{_e(scope_type)}/{_e(scope_id)}", json_body=values)
+        return self._t.request("PUT", "/api/self/settings", json_body=values)
+
+    # ── API Keys ─────────────────────────────────────────────────────────────
+    def list_api_keys(self) -> Any:
+        return self._t.request("GET", "/api/self/api-keys")
+
+    def create_api_key(self, body: dict[str, Any]) -> Any:
+        return self._t.request("POST", "/api/self/api-keys", json_body=body)
+
+    def revoke_api_key(self, key_id: str) -> None:
+        self._t.request("DELETE", f"/api/self/api-keys/{_e(key_id)}")
+
+    def purge_api_key(self, key_id: str) -> None:
+        self._t.request("DELETE", f"/api/self/api-keys/{_e(key_id)}/purge")
+
+    # ── Plan & Usage ─────────────────────────────────────────────────────────
+    def get_plan(self) -> Any:
+        return self._t.request("GET", "/api/self/plan")
+
+    def get_usage(self) -> Any:
+        return self._t.request("GET", "/api/self/usage")

memybase/_sync/_transport.py

@@ -0,0 +1,223 @@
+# GENERATED by scripts/gen_sync.py from memybase/_transport.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview HTTP transport layer — auth injection, timeout, retry with backoff.
+@module memybase._transport
+@description Wraps httpx.AsyncClient with auth header injection (X-Api-Key > Bearer > X-User-Token),
+             per-request timeout, and bounded exponential backoff retry (reads: 408/429/503; writes:
+             429/503 only — never after bytes sent). Honors Retry-After header.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+import time
+import math
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional, TypedDict
+from urllib.parse import urlencode, quote
+
+import httpx
+
+# Absolute import of the shared/pure module: unasync generates memybase/_sync/_transport.py, whose
+# relative `from ._errors` would resolve to a nonexistent memybase/_sync/_errors.py — the absolute path
+# makes both the async module and its sync twin bind the SAME single _errors module.
+from memybase._errors import (
+    MemyBaseError,
+    NetworkError,
+    TimeoutError,
+    decode_error,
+)
+
+__all__ = ["Transport", "RetryConfig"]
+
+_READ_RETRY = frozenset({408, 429, 503})
+_WRITE_RETRY = frozenset({429, 503})
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "QUERY"})
+
+_DEFAULT_MAX_RETRIES = 2
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_BASE_DELAY = 0.5
+_MAX_BACKOFF = 30.0
+
+
+class RetryConfig(TypedDict, total=False):
+    """Retry policy matching the JS SDK's retry config, using Pythonic snake_case keys."""
+
+    max_retries: int
+    base_delay: float
+    retryable_statuses: list[int]
+
+
+class Transport:
+    """Internal HTTP transport with auth, timeout, and retry."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        user_token: Optional[str] = None,
+        cookie: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: Optional[int] = None,
+        retry: Optional[RetryConfig] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._token = token
+        self._user_token = user_token
+        self._cookie = cookie
+        self._extra_headers = dict(headers) if headers else {}
+        self._timeout = timeout
+        self._max_retries = _resolve_max_retries(retry, max_retries)
+        self._base_delay = _resolve_base_delay(retry)
+        self._extra_retryable_statuses = frozenset(int(s) for s in (retry or {}).get("retryable_statuses", []))
+        # Additive test seam: an injected httpx transport (e.g. httpx.MockTransport backed by an
+        # in-process fake engine) routes every request through the SAME real code paths
+        # (auth/serialize/retry/decode) with zero network. Untouched in prod (None → default transport).
+        self._transport = transport
+        self._client: Optional[httpx.Client] = None
+
+    def _auth_headers(self) -> dict[str, str]:
+        # Precedence X-Api-Key > Bearer > X-User-Token, matching the JS SDK + contract.authHeaders. A
+        # session `cookie` is ADDITIVE (can coexist with a key) — the /api/self surface accepts lo_at
+        # cookie auth, so a cookie-only consumer can reach it.
+        h: dict[str, str] = {}
+        if self._api_key:
+            h["X-Api-Key"] = self._api_key
+        elif self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        elif self._user_token:
+            h["X-User-Token"] = self._user_token
+        if self._cookie:
+            h["Cookie"] = self._cookie
+        return h
+
+    def _get_client(self) -> httpx.Client:
+        if self._client is None or self._client.is_closed:
+            # Arbitrary extra headers are merged LAST so a caller can inject tracing/idempotency headers
+            # (and override the defaults if intended), mirroring JS's {Accept, ...auth, ...extraHeaders}.
+            kwargs: dict[str, Any] = {
+                "base_url": self.base_url,
+                "timeout": self._timeout,
+                "headers": {
+                    "Accept": "application/json",
+                    "User-Agent": "memybase-python/0.1.0",
+                    **self._auth_headers(),
+                    **self._extra_headers,
+                },
+            }
+            if self._transport is not None:
+                kwargs["transport"] = self._transport
+            self._client = httpx.Client(**kwargs)
+        return self._client
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        params: Optional[dict[str, str]] = None,
+        headers: Optional[dict[str, str]] = None,
+        text: bool = False,
+    ) -> Any:
+        """Send a request and return parsed JSON/text (or None for 204)."""
+        is_safe = method.upper() in _SAFE_METHODS
+        retryable_statuses = (_READ_RETRY | self._extra_retryable_statuses) if is_safe else _WRITE_RETRY
+        client = self._get_client()
+        attempt = 0
+
+        while True:
+            try:
+                resp = client.request(
+                    method,
+                    path,
+                    json=json_body,
+                    params=params,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries and is_safe:
+                    attempt += 1
+                    time.sleep(_backoff(attempt, self._base_delay))
+                    continue
+                raise TimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+
+            if resp.status_code == 204:
+                return None
+
+            if 200 <= resp.status_code < 300:
+                if text:
+                    return resp.text
+                return resp.json() if resp.content else None
+
+            if resp.status_code in retryable_statuses and attempt < self._max_retries:
+                retry_after = _parse_retry_after(resp.headers.get("retry-after"))
+                delay = retry_after if retry_after is not None else _backoff(attempt + 1, self._base_delay)
+                attempt += 1
+                time.sleep(min(delay, _MAX_BACKOFF))
+                continue
+
+            body = _safe_json(resp)
+            raise decode_error(
+                resp.status_code,
+                body=body,
+                retry_after_header=resp.headers.get("retry-after"),
+            )
+
+    def health(self, timeout: Optional[float] = None) -> bool:
+        """Unauthenticated liveness probe → GET {base_url}/api/health (process-up; no Mongo, schema, or
+        key required). True on a 2xx, False on any non-OK / network error / timeout — a cheap, schema-
+        independent reachability signal for readiness gates, safe to call BEFORE a schema is provisioned."""
+        client = self._get_client()
+        try:
+            resp = client.request("GET", "/api/health", timeout=timeout or self._timeout)
+        except httpx.HTTPError:
+            return False
+        return 200 <= resp.status_code < 300
+
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+def _resolve_max_retries(retry: Optional[RetryConfig], legacy_max_retries: Optional[int]) -> int:
+    if retry and "max_retries" in retry:
+        return int(retry["max_retries"])
+    if legacy_max_retries is not None:
+        return int(legacy_max_retries)
+    return _DEFAULT_MAX_RETRIES
+
+
+def _resolve_base_delay(retry: Optional[RetryConfig]) -> float:
+    if retry and "base_delay" in retry:
+        return float(retry["base_delay"])
+    return _DEFAULT_BASE_DELAY
+
+
+def _backoff(attempt: int, base_delay: float = _DEFAULT_BASE_DELAY) -> float:
+    return min(_MAX_BACKOFF, base_delay * (2 ** (attempt - 1)))
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+def _safe_json(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except Exception:
+        return None

memybase/_transport.py

@@ -0,0 +1,257 @@
+"""
+@fileoverview HTTP transport layer — auth injection, timeout, retry with backoff.
+@module memybase._transport
+@description Wraps httpx.AsyncClient with auth header injection (X-Api-Key > Bearer > X-User-Token),
+             per-request timeout, and bounded exponential backoff retry (reads: 408/429/503; writes:
+             429/503 only — never after bytes sent). Honors Retry-After header.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+import asyncio
+import math
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Optional, TypedDict
+from urllib.parse import urlencode, quote
+
+import httpx
+
+# Absolute import of the shared/pure module: unasync generates memybase/_sync/_transport.py, whose
+# relative `from ._errors` would resolve to a nonexistent memybase/_sync/_errors.py — the absolute path
+# makes both the async module and its sync twin bind the SAME single _errors module.
+from memybase._errors import (
+    MemyBaseError,
+    NetworkError,
+    TimeoutError,
+    decode_error,
+)
+
+__all__ = ["Transport", "RetryConfig"]
+
+_READ_RETRY = frozenset({408, 429, 503})
+_WRITE_RETRY = frozenset({429, 503})
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "QUERY"})
+
+_DEFAULT_MAX_RETRIES = 2
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_BASE_DELAY = 0.5
+_MAX_BACKOFF = 30.0
+
+
+class RetryConfig(TypedDict, total=False):
+    """Retry policy matching the JS SDK's retry config, using Pythonic snake_case keys."""
+
+    max_retries: int
+    base_delay: float
+    retryable_statuses: list[int]
+
+
+class Transport:
+    """Internal HTTP transport with auth, timeout, and retry."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        user_token: Optional[str] = None,
+        cookie: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: Optional[int] = None,
+        retry: Optional[RetryConfig] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._token = token
+        self._user_token = user_token
+        self._cookie = cookie
+        self._extra_headers = dict(headers) if headers else {}
+        self._timeout = timeout
+        self._max_retries = _resolve_max_retries(retry, max_retries)
+        self._base_delay = _resolve_base_delay(retry)
+        self._extra_retryable_statuses = frozenset(int(s) for s in (retry or {}).get("retryable_statuses", []))
+        # Additive test seam: an injected httpx transport (e.g. httpx.MockTransport backed by an
+        # in-process fake engine) routes every request through the SAME real code paths
+        # (auth/serialize/retry/decode) with zero network. Untouched in prod (None → default transport).
+        self._transport = transport
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _auth_headers(self) -> dict[str, str]:
+        # Precedence X-Api-Key > Bearer > X-User-Token, matching the JS SDK + contract.authHeaders. A
+        # session `cookie` is ADDITIVE (can coexist with a key) — the /api/self surface accepts lo_at
+        # cookie auth, so a cookie-only consumer can reach it.
+        h: dict[str, str] = {}
+        if self._api_key:
+            h["X-Api-Key"] = self._api_key
+        elif self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        elif self._user_token:
+            h["X-User-Token"] = self._user_token
+        if self._cookie:
+            h["Cookie"] = self._cookie
+        return h
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            # Arbitrary extra headers are merged LAST so a caller can inject tracing/idempotency headers
+            # (and override the defaults if intended), mirroring JS's {Accept, ...auth, ...extraHeaders}.
+            kwargs: dict[str, Any] = {
+                "base_url": self.base_url,
+                "timeout": self._timeout,
+                "headers": {
+                    "Accept": "application/json",
+                    "User-Agent": "memybase-python/0.1.0",
+                    **self._auth_headers(),
+                    **self._extra_headers,
+                },
+            }
+            if self._transport is not None:
+                kwargs["transport"] = self._transport
+            self._client = httpx.AsyncClient(**kwargs)
+        return self._client
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        params: Optional[dict[str, str]] = None,
+        headers: Optional[dict[str, str]] = None,
+        text: bool = False,
+    ) -> Any:
+        """Send a request and return parsed JSON/text (or None for 204)."""
+        is_safe = method.upper() in _SAFE_METHODS
+        retryable_statuses = (_READ_RETRY | self._extra_retryable_statuses) if is_safe else _WRITE_RETRY
+        client = self._get_client()
+        attempt = 0
+
+        while True:
+            try:
+                resp = await client.request(
+                    method,
+                    path,
+                    json=json_body,
+                    params=params,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries and is_safe:
+                    attempt += 1
+                    await asyncio.sleep(_backoff(attempt, self._base_delay))
+                    continue
+                raise TimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+
+            if resp.status_code == 204:
+                return None
+
+            if 200 <= resp.status_code < 300:
+                if text:
+                    return resp.text
+                return resp.json() if resp.content else None
+
+            if resp.status_code in retryable_statuses and attempt < self._max_retries:
+                retry_after = _parse_retry_after(resp.headers.get("retry-after"))
+                delay = retry_after if retry_after is not None else _backoff(attempt + 1, self._base_delay)
+                attempt += 1
+                await asyncio.sleep(min(delay, _MAX_BACKOFF))
+                continue
+
+            body = _safe_json(resp)
+            raise decode_error(
+                resp.status_code,
+                body=body,
+                retry_after_header=resp.headers.get("retry-after"),
+            )
+
+    async def health(self, timeout: Optional[float] = None) -> bool:
+        """Unauthenticated liveness probe → GET {base_url}/api/health (process-up; no Mongo, schema, or
+        key required). True on a 2xx, False on any non-OK / network error / timeout — a cheap, schema-
+        independent reachability signal for readiness gates, safe to call BEFORE a schema is provisioned."""
+        client = self._get_client()
+        try:
+            resp = await client.request("GET", "/api/health", timeout=timeout or self._timeout)
+        except httpx.HTTPError:
+            return False
+        return 200 <= resp.status_code < 300
+
+    # <sync:exclude>  realtime SSE (open_sse) is async-only — see _realtime.py; gen_sync.py drops this.
+    @asynccontextmanager
+    async def open_sse(
+        self,
+        path: str,
+        *,
+        last_event_id: Optional[str] = None,
+    ) -> AsyncIterator[httpx.Response]:
+        """Open a Server-Sent-Events GET stream as an async context manager.
+
+        Sets Accept: text/event-stream (+ Last-Event-ID for resume), decodes a >=400 body into the
+        proper MemyBaseError (so realtime failures surface the same typed exceptions as regular
+        requests), and wraps httpx transport failures into TimeoutError / NetworkError. The caller
+        iterates ``resp.aiter_lines()`` inside the ``async with`` — the stream (and connection) is
+        released on exit. Supersedes the removed ``request_stream`` (which never set SSE headers and
+        detached the stream context manager, leaking the connection).
+        """
+        client = self._get_client()
+        headers = {"Accept": "text/event-stream"}
+        if last_event_id:
+            headers["Last-Event-ID"] = last_event_id
+        try:
+            async with client.stream("GET", path, headers=headers) as resp:
+                if resp.status_code >= 400:
+                    await resp.aread()
+                    raise decode_error(
+                        resp.status_code,
+                        body=_safe_json(resp),
+                        retry_after_header=resp.headers.get("retry-after"),
+                    )
+                yield resp
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc)) from exc
+        except httpx.HTTPError as exc:
+            raise NetworkError(str(exc)) from exc
+    # </sync:exclude>
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+def _resolve_max_retries(retry: Optional[RetryConfig], legacy_max_retries: Optional[int]) -> int:
+    if retry and "max_retries" in retry:
+        return int(retry["max_retries"])
+    if legacy_max_retries is not None:
+        return int(legacy_max_retries)
+    return _DEFAULT_MAX_RETRIES
+
+
+def _resolve_base_delay(retry: Optional[RetryConfig]) -> float:
+    if retry and "base_delay" in retry:
+        return float(retry["base_delay"])
+    return _DEFAULT_BASE_DELAY
+
+
+def _backoff(attempt: int, base_delay: float = _DEFAULT_BASE_DELAY) -> float:
+    return min(_MAX_BACKOFF, base_delay * (2 ** (attempt - 1)))
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+def _safe_json(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except Exception:
+        return None