"""Shared utilities for service HTTP clients."""


def extract_error_text(response) -> str:
    """
    Extract a human-readable error message from an httpx Response.

    Priority:
      1. JSON body  -> 'detail' field  (FastAPI / DRF standard)
      2. JSON body  -> 'message' field
      3. JSON body  -> entire dict as string
      4. Raw response text (truncated to 300 chars)
    """
    try:
        body = response.json()
        if isinstance(body, dict):
            msg = body.get("detail") or body.get("message")
            if msg:
                # msg may itself be a list of validation errors
                if isinstance(msg, list):
                    parts = []
                    for item in msg:
                        if isinstance(item, dict):
                            parts.append(item.get("msg") or str(item))
                        else:
                            parts.append(str(item))
                    return "; ".join(parts)
                return str(msg)
            return str(body)
    except Exception:
        pass
    text = response.text or ""
    return text[:300] if len(text) > 300 else text