appnigma-sdk 0.1.0__py3-none-any.whl

appnigma/__init__.py

@@ -0,0 +1,37 @@
+"""The package a customer's product installs to reach its Appnigma microserver."""
+
+from appnigma._client import Appnigma
+from appnigma._constants import CONNECTION_STATUSES, ERROR_CODES, OBJECTS, PLATFORM_REQUEST_METHODS
+from appnigma._errors import (
+    AppnigmaError,
+    AuthError,
+    InputError,
+    NetworkError,
+    NotAvailableError,
+    NotFoundError,
+    RateLimitError,
+    ReconnectError,
+    RetiredError,
+    ServerError,
+)
+from appnigma._version import API_DESCRIPTION_VERSION, __version__
+
+__all__ = [
+    "API_DESCRIPTION_VERSION",
+    "CONNECTION_STATUSES",
+    "ERROR_CODES",
+    "OBJECTS",
+    "PLATFORM_REQUEST_METHODS",
+    "Appnigma",
+    "AppnigmaError",
+    "AuthError",
+    "InputError",
+    "NetworkError",
+    "NotAvailableError",
+    "NotFoundError",
+    "RateLimitError",
+    "ReconnectError",
+    "RetiredError",
+    "ServerError",
+    "__version__",
+]

appnigma/_checks.py

@@ -0,0 +1,96 @@
+"""Refusals made here, before any call, for a setting or an input the server
+would refuse anyway. Same shape as the server's, so one `except` handles both."""
+
+import math
+from typing import Any, NoReturn
+from urllib.parse import urlsplit
+
+from appnigma._constants import (
+    API_URL_ENV_NAME,
+    DEFAULT_BASE_URL,
+    END_CUSTOMER_ID_PATH_RULE,
+    END_CUSTOMER_ID_PATH_UNSAFE,
+    END_CUSTOMER_ID_PATTERN,
+    END_CUSTOMER_ID_RULE,
+    KEY_ENV_NAME,
+    KEY_PREFIX,
+    LOCAL_HOSTS,
+    MAX_TIMER_MS,
+)
+from appnigma._errors import AuthError, InputError
+
+
+def refuse(field: str, problem: str) -> NoReturn:
+    raise InputError(
+        code="INVALID_INPUT",
+        message=f"{field} {problem}",
+        details={"problems": [{"field": field, "problem": problem}]},
+    )
+
+
+def _is_whole(value: Any) -> bool:
+    # In Python `True` is an int; a setting that asks for a number refuses it.
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def check_key(key: Any) -> str:
+    if not key:
+        raise AuthError(code="SDK_KEY_MISSING", message=f"No SDK key: pass key=, or set {KEY_ENV_NAME}")
+    if not isinstance(key, str) or not key.startswith(KEY_PREFIX):
+        raise AuthError(code="SDK_KEY_MISSING", message=f"That is not an Appnigma SDK key, it starts with {KEY_PREFIX}")
+    return key
+
+
+def check_timeout_ms(value: Any) -> int:
+    if _is_whole(value) and 1 <= value <= MAX_TIMER_MS:
+        return value
+    refuse("timeout_ms", f"must be a whole number of milliseconds from 1 to {MAX_TIMER_MS}")
+
+
+def check_max_retries(value: Any) -> int:
+    if _is_whole(value) and value >= 0:
+        return value
+    refuse("max_retries", "must be a whole number, 0 or more")
+
+
+def check_max_retry_wait_ms(value: Any) -> float:
+    is_number = _is_whole(value) or (isinstance(value, float) and math.isfinite(value))
+    if is_number and 0 <= value <= MAX_TIMER_MS:
+        return value
+    refuse("max_retry_wait_ms", f"must be a number of milliseconds from 0 to {MAX_TIMER_MS}")
+
+
+def check_end_customer_id(value: Any) -> str:
+    if not isinstance(value, str) or not END_CUSTOMER_ID_PATTERN.fullmatch(value):
+        refuse("end_customer_id", END_CUSTOMER_ID_RULE)
+    if value in END_CUSTOMER_ID_PATH_UNSAFE:
+        refuse("end_customer_id", END_CUSTOMER_ID_PATH_RULE)
+    return value
+
+
+def check_platform(value: Any) -> str:
+    if isinstance(value, str) and value:
+        return value
+    refuse("platform", "must be a platform key, such as hubspot")
+
+
+def check_base_url(setting: str | None) -> str:
+    """The setting if there is one, else production. An empty setting counts as
+    none. Only https, or http to this machine, so a key never crosses a network
+    unencrypted."""
+    address = (setting or "").strip() or DEFAULT_BASE_URL
+    address = address.rstrip("/")
+    if not _allowed_address(address):
+        refuse(API_URL_ENV_NAME, "must be an https:// address, or http:// to localhost")
+    return address
+
+
+def _allowed_address(address: str) -> bool:
+    try:
+        parsed = urlsplit(address)
+        host = parsed.hostname
+    except ValueError:
+        return False
+    if parsed.scheme == "https":
+        return bool(host)
+    return parsed.scheme == "http" and host in LOCAL_HOSTS

appnigma/_client.py

@@ -0,0 +1,211 @@
+import os
+from collections.abc import Mapping
+from typing import Any
+
+from appnigma import _checks, _errors, _names
+from appnigma._connections import Connections
+from appnigma._constants import (
+    API_URL_ENV_NAME,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_RETRY_WAIT_MS,
+    DEFAULT_TIMEOUT_MS,
+    KEY_ENV_NAME,
+)
+from appnigma._crm import Crm
+from appnigma._errors import ServerError
+from appnigma._retry import Policy, with_retries
+
+
+class Appnigma:
+    """What a customer creates. The key comes from `key` or from the
+    APPNIGMA_SDK_KEY environment variable; a client started with no key, or
+    with one that does not start with apn_live_, raises AuthError at once,
+    before any call.
+
+    Every call takes keyword arguments in Python style and answers a dict with
+    keys in Python style, except inside content that is not ours (a record's
+    properties, a function's input and output, a platform's answer), which
+    comes back exactly as it was sent. Every call also takes `timeout_ms`, the
+    time limit of one attempt.
+    """
+
+    def __init__(
+        self,
+        key: str | None = None,
+        *,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_wait_ms: float = DEFAULT_MAX_RETRY_WAIT_MS,
+        transport: Any = None,
+    ) -> None:
+        """`transport` is for tests; a customer never passes it."""
+        self._key = _checks.check_key(key if key is not None else os.environ.get(KEY_ENV_NAME))
+        self._base_url = _checks.check_base_url(os.environ.get(API_URL_ENV_NAME))
+        self._timeout_ms = _checks.check_timeout_ms(timeout_ms)
+        self._max_retries = _checks.check_max_retries(max_retries)
+        self._max_retry_wait_ms = _checks.check_max_retry_wait_ms(max_retry_wait_ms)
+        self._policy = Policy(max_retries=self._max_retries, max_retry_wait_ms=self._max_retry_wait_ms)
+        # A write whose repeat is not harmless gets one attempt. create_link
+        # makes a new link every time; run is your own function, and only you
+        # know whether running it twice is harmless; request with a method
+        # other than GET may change the platform. post is retried because the
+        # server updates the record that matches.
+        self._one_attempt = Policy(max_retries=0, max_retry_wait_ms=self._max_retry_wait_ms)
+        if transport is None:
+            # Imported here, not at the top, so `import appnigma` does not load
+            # the generated client and pydantic until a client is made.
+            from appnigma._transport import Transport
+
+            transport = Transport(base_url=self._base_url, key=self._key)
+        self._transport = transport
+        self._connections = Connections(self)
+        self._crm = Crm(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def timeout_ms(self) -> int:
+        return self._timeout_ms
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    @property
+    def max_retry_wait_ms(self) -> float:
+        return self._max_retry_wait_ms
+
+    @property
+    def connections(self) -> Connections:
+        """Connecting an end customer: `create_link` and `get`."""
+        return self._connections
+
+    @property
+    def crm(self) -> Crm:
+        """An end customer's CRM data in one shape: `contacts`, `companies` and
+        `deals`, each with `list` and `get`."""
+        return self._crm
+
+    def post(
+        self,
+        *,
+        end_customer_id: str,
+        platform: str,
+        object: str,
+        record: Mapping[str, Any],
+        unique_by: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """Creates a record in the end customer's HubSpot, or updates the one
+        that already matches on `unique_by` (email for a contact unless you
+        name another property; required for a company and a deal)."""
+        # The generated client serialises only a plain dict: a read-only
+        # mapping would raise, and a UserDict would be sent under "data".
+        body = _names.camel_keys(
+            end_customer_id=end_customer_id, platform=platform, object=object, record=dict(record), unique_by=unique_by
+        )
+        return self._call("post_record", {"post_input": body}, timeout_ms=timeout_ms)
+
+    def pull(
+        self,
+        *,
+        end_customer_id: str,
+        platform: str,
+        object: str,
+        limit: int | None = None,
+        after: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """One page of records and a marker for the next; `next` is None on
+        the last page. `limit` is 1 to 100."""
+        body = _names.camel_keys(
+            end_customer_id=end_customer_id, platform=platform, object=object, limit=limit, after=after
+        )
+        return self._call("pull_records", {"pull_input": body}, timeout_ms=timeout_ms)
+
+    def run(
+        self,
+        *,
+        end_customer_id: str,
+        platform: str,
+        function_name: str,
+        input: Any,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """One of your own functions, by platform and name: its live version
+        runs, and the answer's `ran_as` says whose it was. Made once, never
+        retried."""
+        body = _names.camel_keys(
+            end_customer_id=end_customer_id,
+            platform=platform,
+            function_name=function_name,
+            input=input,
+        )
+        return self._call("run_function", {"run_input": body}, policy=self._one_attempt, timeout_ms=timeout_ms)
+
+    def catalog(self, *, platform: str | None = None, timeout_ms: int | None = None) -> dict[str, Any]:
+        """Your own functions, with their shapes. `platform` narrows the list."""
+        return self._call("list_functions", {"platform": platform}, timeout_ms=timeout_ms)
+
+    def guide(self, *, timeout_ms: int | None = None) -> dict[str, Any]:
+        """The guide for your developers, as markdown, written for your company
+        from what is live right now."""
+        return self._call("get_guide", timeout_ms=timeout_ms)
+
+    def request(
+        self,
+        *,
+        end_customer_id: str,
+        platform: str,
+        method: str,
+        path: str,
+        body: Any = None,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """Anything else on the end customer's platform, answered as the
+        platform answered, refusals included. A GET is retried like a read;
+        any other method is made once."""
+        payload = _names.camel_keys(
+            end_customer_id=end_customer_id, platform=platform, method=method, path=path, body=body
+        )
+        policy = self._policy if method == "GET" else self._one_attempt
+        return self._call("platform_request", {"platform_request_input": payload}, policy=policy, timeout_ms=timeout_ms)
+
+    def _call(
+        self,
+        operation: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        policy: Policy | None = None,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """One call: through the transport, under the given retry policy, and
+        into the answer or the error for its status. Used by Connections and
+        Crm as well."""
+        attempt_ms = self._timeout_ms if timeout_ms is None else _checks.check_timeout_ms(timeout_ms)
+        answer = with_retries(
+            policy or self._policy, lambda: self._transport.attempt(operation, params, timeout_ms=attempt_ms)
+        )
+        return _read_answer(answer)
+
+
+def _read_answer(answer: dict[str, Any]) -> dict[str, Any]:
+    """A success whose body is not JSON is a server error: a proxy page or an
+    empty body is never handed back as data."""
+    if not answer["ok"]:
+        raise _errors.from_answer(
+            status=answer["status"],
+            body=answer["json"],
+            request_id=answer["request_id"],
+            retry_after_seconds=answer["retry_after_seconds"],
+        )
+    if answer["json"] is None:
+        raise ServerError(
+            code="INTERNAL_ERROR",
+            status=answer["status"],
+            request_id=answer["request_id"],
+            message=f"The Appnigma API answered {answer['status']} with a body that is not JSON",
+        )
+    return _names.answer(answer["json"])

appnigma/_connections.py

@@ -0,0 +1,38 @@
+from typing import TYPE_CHECKING, Any
+
+from appnigma import _checks, _names
+
+if TYPE_CHECKING:
+    from appnigma._client import Appnigma
+
+
+class Connections:
+    """Connecting an end customer to their account on a platform:
+    `client.connections.create_link` and `client.connections.get`."""
+
+    def __init__(self, client: "Appnigma") -> None:
+        self._client = client
+
+    def create_link(
+        self, *, end_customer_id: str, platform: str, return_url: str, timeout_ms: int | None = None
+    ) -> dict[str, Any]:
+        """A link to the connect page for one end customer on one platform. It
+        works once and expires after 15 minutes. Made once, never retried:
+        every call makes a new link."""
+        body = _names.camel_keys(end_customer_id=end_customer_id, platform=platform, return_url=return_url)
+        return self._client._call(
+            "create_connection_link",
+            {"create_connection_link_input": body},
+            policy=self._client._one_attempt,
+            timeout_ms=timeout_ms,
+        )
+
+    def get(self, *, end_customer_id: str, platform: str, timeout_ms: int | None = None) -> dict[str, Any]:
+        """Whether one end customer is connected on one platform. The id travels
+        in the path, so it is checked here first: a bad one is refused as the
+        server would refuse it, and never becomes a wrong route."""
+        _checks.check_end_customer_id(end_customer_id)
+        _checks.check_platform(platform)
+        return self._client._call(
+            "get_connection", {"end_customer_id": end_customer_id, "platform": platform}, timeout_ms=timeout_ms
+        )

appnigma/_constants.py

@@ -0,0 +1,83 @@
+import re
+
+KEY_PREFIX = "apn_live_"
+
+# Where `Appnigma()` finds the key when none is passed.
+KEY_ENV_NAME = "APPNIGMA_SDK_KEY"
+
+# Where the client calls: production.
+DEFAULT_BASE_URL = "https://engine.appnigma.ai"
+
+# Points the client at a local or staging server for our own testing. Read
+# from the environment, never a client setting, and never in the README: a
+# customer always calls production.
+API_URL_ENV_NAME = "APPNIGMA_API_URL"
+
+# The only hosts the address may reach over plain http://, so a key never
+# crosses a network unencrypted. As `urlsplit` gives them: lowercase, and an
+# IPv6 address without its brackets.
+LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+ROUTE_BASE = "/sdk/v1"
+
+REQUEST_ID_HEADER = "x-request-id"
+RETRY_AFTER_HEADER = "retry-after"
+
+# How long one attempt may take before it counts as a network failure.
+DEFAULT_TIMEOUT_MS = 30_000
+
+# The same ceiling the TypeScript package applies, so the READMEs show the
+# same numbers.
+MAX_TIMER_MS = 2_147_483_647
+
+# Tries again after the first attempt: three attempts in all.
+DEFAULT_MAX_RETRIES = 2
+
+# A Retry-After longer than this is reported, not waited for.
+DEFAULT_MAX_RETRY_WAIT_MS = 30_000
+
+# This package's own code for "no answer arrived". Not in the server's table,
+# which only lists codes the server can send.
+NETWORK_ERROR_CODE = "NETWORK_ERROR"
+
+# The one 409 that sends an end customer through the connect flow again.
+RECONNECT_ERROR_CODE = "CONNECTION_NEEDS_RECONNECT"
+
+# An end customer id is 1 to 100 of letters, digits, dot, dash or underscore.
+# Matched whole, with `fullmatch`.
+END_CUSTOMER_ID_PATTERN = re.compile(r"[A-Za-z0-9._-]{1,100}")
+END_CUSTOMER_ID_RULE = "must be 1 to 100 characters: letters, digits, dot, dash or underscore"
+
+# `.` and `..` fit the pattern but cannot travel in a URL path.
+END_CUSTOMER_ID_PATH_UNSAFE = (".", "..")
+END_CUSTOMER_ID_PATH_RULE = "cannot be only dots, it travels in the URL path"
+
+# The server's error codes (the API description, 18.2). This package keeps its
+# own copy: it is published on its own. A test compares it with the
+# TypeScript package's list.
+ERROR_CODES = (
+    "INVALID_INPUT",
+    "SDK_KEY_MISSING",
+    "SDK_KEY_INVALID",
+    "SDK_KEY_CANCELLED",
+    "MICROSERVER_NOT_ENABLED",
+    "PLATFORM_NOT_ENABLED",
+    "END_CUSTOMER_NOT_FOUND",
+    "FUNCTION_NOT_FOUND",
+    "FUNCTION_RETIRED",
+    "CONNECTION_NEEDS_RECONNECT",
+    "RATE_LIMITED",
+    "PLATFORM_RATE_LIMITED",
+    "PLATFORM_ERROR",
+    "TIMED_OUT",
+    "LOGIC_FAILED",
+    "INTERNAL_ERROR",
+    "RECORD_NOT_FOUND",
+    "DATA_TYPE_NOT_AVAILABLE",
+    "ACTION_NOT_FOUND",
+    "MISSING_SCOPES",
+)
+
+OBJECTS = ("contact", "company", "deal")
+CONNECTION_STATUSES = ("connected", "needs_reconnect", "disconnected")
+PLATFORM_REQUEST_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")

appnigma/_crm.py

@@ -0,0 +1,45 @@
+from typing import TYPE_CHECKING, Any
+
+from appnigma import _names
+
+if TYPE_CHECKING:
+    from appnigma._client import Appnigma
+
+
+class CrmObjects:
+    """The two reads of one CRM object. Reads, so they are retried."""
+
+    def __init__(self, client: "Appnigma", *, list_operation: str, get_operation: str) -> None:
+        self._client = client
+        self._list_operation = list_operation
+        self._get_operation = get_operation
+
+    def list(
+        self,
+        *,
+        end_customer_id: str,
+        platform: str,
+        limit: int | None = None,
+        cursor: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """One page of records and a marker for the next; pass `next` as
+        `cursor` for the following page. `limit` is 1 to 100."""
+        body = _names.camel_keys(end_customer_id=end_customer_id, platform=platform, limit=limit, cursor=cursor)
+        return self._client._call(self._list_operation, {"crm_list_input": body}, timeout_ms=timeout_ms)
+
+    def get(self, *, end_customer_id: str, platform: str, id: str, timeout_ms: int | None = None) -> dict[str, Any]:
+        """One record by its id in the CRM."""
+        body = _names.camel_keys(end_customer_id=end_customer_id, platform=platform, id=id)
+        return self._client._call(self._get_operation, {"crm_get_input": body}, timeout_ms=timeout_ms)
+
+
+class Crm:
+    """An end customer's CRM data in one shape, whichever CRM they use:
+    `client.crm.contacts`, `client.crm.companies` and `client.crm.deals`, each
+    with `list` and `get`."""
+
+    def __init__(self, client: "Appnigma") -> None:
+        self.contacts = CrmObjects(client, list_operation="list_crm_contacts", get_operation="get_crm_contact")
+        self.companies = CrmObjects(client, list_operation="list_crm_companies", get_operation="get_crm_company")
+        self.deals = CrmObjects(client, list_operation="list_crm_deals", get_operation="get_crm_deal")

appnigma/_errors.py

@@ -0,0 +1,156 @@
+from typing import Any
+
+from appnigma._constants import NETWORK_ERROR_CODE, RECONNECT_ERROR_CODE
+
+
+class AppnigmaError(Exception):
+    """Every failure this package raises, whether the server answered with an
+    error or could not be reached at all.
+
+    Catch this for "anything from Appnigma", or one of the subclasses for one
+    kind of failure. `code` is the string the server sent, known to this
+    package or not; `status` and `request_id` are None when nothing came back.
+    `str(error)` is the message.
+    """
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        status: int | None = None,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.details = details if details is not None else {}
+
+
+class InputError(AppnigmaError):
+    """400. The server names each field it could not accept, as `problems`: a
+    list of `{"field": ..., "problem": ...}`. Also raised locally for a bad
+    setting or a bad end customer id, before any call."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.problems = read_problems(self.details)
+
+
+class AuthError(AppnigmaError):
+    """401 and 403, and a client started without a key."""
+
+
+class NotFoundError(AppnigmaError):
+    """404."""
+
+
+class RetiredError(AppnigmaError):
+    """410 FUNCTION_RETIRED: the function was live and was removed from your
+    logic. It will not answer again, so it is never tried again."""
+
+
+class ReconnectError(AppnigmaError):
+    """409 CONNECTION_NEEDS_RECONNECT: the end customer has to approve again."""
+
+
+class NotAvailableError(AppnigmaError):
+    """Any other 409: the platform cannot give this yet."""
+
+
+class RateLimitError(AppnigmaError):
+    """429. `retry_after_seconds` is what the server's Retry-After header said,
+    or None when it sent none."""
+
+    def __init__(self, *, retry_after_seconds: float | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(AppnigmaError):
+    """Any 5xx, any status this package does not know, and any answer that is
+    not JSON. Our side is at fault, not the caller's input."""
+
+
+class NetworkError(AppnigmaError):
+    """No answer arrived: the call failed, or the attempt ran out of time.
+    `__cause__` is the underlying exception when there is one."""
+
+    def __init__(self, *, message: str, cause: BaseException | None = None) -> None:
+        super().__init__(code=NETWORK_ERROR_CODE, message=message)
+        self.__cause__ = cause
+
+
+# Turns one answer from the server into the error for its status. The class is
+# chosen by status, not by code, so a code this package has never seen still
+# lands in the right class with its string kept.
+
+_PROBLEM_KEYS = ("field", "problem")
+
+# Every status the server's table names; any other is a ServerError. 409 is
+# chosen by code as well, in error_class.
+_CLASS_BY_STATUS: dict[int, type[AppnigmaError]] = {
+    400: InputError,
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    410: RetiredError,
+    429: RateLimitError,
+}
+
+
+def from_answer(
+    *, status: int, body: Any, request_id: str | None, retry_after_seconds: float | None = None
+) -> AppnigmaError:
+    shape = read_error_shape(body) or {"code": "INTERNAL_ERROR", "message": "", "details": {}}
+    kwargs = {
+        "code": shape["code"],
+        "message": shape["message"] or f"The Appnigma API answered {status}",
+        "status": status,
+        "request_id": request_id,
+        "details": shape["details"],
+    }
+    cls = error_class(status, shape["code"])
+    if cls is RateLimitError:
+        return RateLimitError(retry_after_seconds=retry_after_seconds, **kwargs)
+    return cls(**kwargs)
+
+
+def error_class(status: int, code: str) -> type[AppnigmaError]:
+    """Only CONNECTION_NEEDS_RECONNECT asks for a reconnect; any other 409 is
+    something the platform cannot give yet."""
+    if status == 409:
+        return ReconnectError if code == RECONNECT_ERROR_CODE else NotAvailableError
+    return _CLASS_BY_STATUS.get(status, ServerError)
+
+
+def read_error_shape(body: Any) -> dict[str, Any] | None:
+    """Our shape is `{"error": {"code", "message", "details"}}`, as JSON parses
+    it. Anything else reads as "not our shape"."""
+    if not isinstance(body, dict) or not isinstance(body.get("error"), dict):
+        return None
+    error = body["error"]
+    code = error.get("code")
+    if not isinstance(code, str) or not code:
+        return None
+    message = error.get("message")
+    details = error.get("details")
+    return {
+        "code": code,
+        "message": message if isinstance(message, str) else "",
+        "details": details if isinstance(details, dict) else {},
+    }
+
+
+def read_problems(details: dict[str, Any]) -> list[dict[str, str]]:
+    entries = details.get("problems")
+    if not isinstance(entries, list):
+        return []
+    return [
+        {"field": entry["field"], "problem": entry["problem"]}
+        for entry in entries
+        if isinstance(entry, dict) and all(isinstance(entry.get(key), str) for key in _PROBLEM_KEYS)
+    ]