vectoramp 0.1.0__py3-none-any.whl

vectoramp/sources.py

@@ -0,0 +1,506 @@
+"""Typed ingestion source builders for the VectorAmp SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping, Optional, Protocol, Sequence, Union, runtime_checkable
+from urllib.parse import urlparse
+
+from .types import JSON
+
+KnownSourceType = Literal["s3", "web", "gcs", "gdrive", "file_upload", "jira", "confluence"]
+
+
+@runtime_checkable
+class SourceBuilder(Protocol):
+    """Object that can be converted to a source-create request."""
+
+    def to_create_request(self) -> JSON:
+        """Return the body fields accepted by the source-create API."""
+
+
+@dataclass(frozen=True)
+class GenericSource:
+    """Escape hatch for source types not yet modeled by the SDK.
+
+    Args:
+        name: Source name. Defaults to the normalized ``source_type``.
+        source_type: API source type. Required.
+        config: Source-specific configuration.
+        description: Optional source description.
+        metadata: Optional source metadata.
+    """
+
+    name: Optional[str] = None
+    source_type: str = ""
+    config: Mapping[str, Any] = field(default_factory=dict)
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this generic source."""
+        if not self.source_type:
+            raise ValueError("GenericSource requires source_type.")
+        return _source_body(
+            name=self.name or _default_source_name(self.source_type),
+            source_type=self.source_type,
+            config=self.config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class WebSource:
+    """Web crawler ingestion source.
+
+    Args:
+        name: Source name. Defaults to ``web-{host-or-path}`` from the first URL.
+        start_urls: Crawl entry URLs. At least one URL is required.
+        max_depth: Optional crawl depth limit.
+        max_pages: Optional page limit.
+        allowed_domains: Optional domain allow-list.
+        include_patterns: Optional URL include patterns.
+        exclude_patterns: Optional URL exclude patterns.
+        crawl_delay_seconds: Optional delay between requests.
+        sync_mode: Optional sync mode. Omitted from the request when ``None`` so
+            the server applies its default (``"incremental"``).
+        description: Optional source description.
+        metadata: Optional source metadata.
+        config_extra: Optional extra config fields merged into the request.
+    """
+
+    name: Optional[str] = None
+    start_urls: Sequence[str] = ()
+    max_depth: Optional[int] = None
+    max_pages: Optional[int] = None
+    allowed_domains: Optional[Sequence[str]] = None
+    include_patterns: Optional[Sequence[str]] = None
+    exclude_patterns: Optional[Sequence[str]] = None
+    crawl_delay_seconds: Optional[float] = None
+    include_assets: Optional[bool] = None
+    max_assets_per_page: Optional[int] = None
+    sync_mode: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this web source."""
+        if not self.start_urls:
+            raise ValueError("WebSource requires at least one start URL.")
+        config: JSON = {"start_urls": list(self.start_urls)}
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional(config, "max_depth", self.max_depth)
+        _set_optional(config, "max_pages", self.max_pages)
+        _set_optional_sequence(config, "allowed_domains", self.allowed_domains)
+        _set_optional_sequence(config, "include_patterns", self.include_patterns)
+        _set_optional_sequence(config, "exclude_patterns", self.exclude_patterns)
+        _set_optional(config, "crawl_delay_seconds", self.crawl_delay_seconds)
+        _set_optional(config, "include_assets", self.include_assets)
+        _set_optional(config, "max_assets_per_page", self.max_assets_per_page)
+        _merge_extra(config, self.config_extra)
+        return _source_body(
+            name=self.name or _default_web_source_name(self.start_urls),
+            source_type="web",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class S3Source:
+    """Amazon S3 ingestion source.
+
+    Args:
+        name: Source name. Defaults to ``s3-{bucket}``.
+        bucket: S3 bucket name. Required.
+        region: AWS region. Defaults to ``"us-east-1"``.
+        prefix: Optional key prefix.
+        sync_mode: Optional sync mode. Omitted from the request when ``None`` so
+            the server applies its default (``"incremental"``).
+        access_key_id: Optional AWS access key id.
+        secret_access_key: Optional AWS secret access key.
+        role_arn: Optional role ARN.
+        endpoint_url: Optional S3-compatible endpoint URL.
+        file_patterns: Optional file pattern filters.
+        max_file_size_mb: Optional max file size in MB.
+        description: Optional source description.
+        metadata: Optional source metadata.
+        config_extra: Optional extra config fields merged into the request.
+    """
+
+    name: Optional[str] = None
+    bucket: str = ""
+    region: str = "us-east-1"
+    prefix: Optional[str] = None
+    sync_mode: Optional[str] = None
+    access_key_id: Optional[str] = None
+    secret_access_key: Optional[str] = None
+    role_arn: Optional[str] = None
+    endpoint_url: Optional[str] = None
+    file_patterns: Optional[Sequence[str]] = None
+    max_file_size_mb: Optional[int] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this S3 source."""
+        if not self.bucket:
+            raise ValueError("S3Source requires bucket.")
+        config: JSON = {"bucket": self.bucket, "region": self.region}
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional(config, "prefix", self.prefix)
+        _set_optional(config, "access_key_id", self.access_key_id)
+        _set_optional(config, "secret_access_key", self.secret_access_key)
+        _set_optional(config, "role_arn", self.role_arn)
+        _set_optional(config, "endpoint_url", self.endpoint_url)
+        _set_optional_sequence(config, "file_patterns", self.file_patterns)
+        _set_optional(config, "max_file_size_mb", self.max_file_size_mb)
+        _merge_extra(config, self.config_extra)
+        return _source_body(
+            name=self.name or _default_source_name("s3", self.bucket),
+            source_type="s3",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class GCSSource:
+    """Google Cloud Storage ingestion source."""
+
+    name: Optional[str] = None
+    bucket: str = ""
+    prefix: Optional[str] = None
+    project_id: Optional[str] = None
+    credentials_json: Optional[Mapping[str, Any]] = None
+    sync_mode: Optional[str] = None
+    file_patterns: Optional[Sequence[str]] = None
+    max_file_size_mb: Optional[int] = None
+    connection_id: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        if not self.bucket:
+            raise ValueError("GCSSource requires bucket.")
+        config: JSON = {"bucket": self.bucket}
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional(config, "prefix", self.prefix)
+        _set_optional(config, "project_id", self.project_id)
+        if self.credentials_json is not None:
+            config["credentials_json"] = dict(self.credentials_json)
+        _set_optional_sequence(config, "file_patterns", self.file_patterns)
+        _set_optional(config, "max_file_size_mb", self.max_file_size_mb)
+        _set_optional(config, "connection_id", self.connection_id)
+        _merge_extra(config, self.config_extra)
+        return _source_body(
+            name=self.name or _default_source_name("gcs", self.bucket),
+            source_type="gcs",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class GoogleDriveSource:
+    """Google Drive ingestion source.
+
+    Args:
+        name: Source name. Defaults to ``gdrive-{first-folder-or-file-id}`` or
+            ``gdrive``.
+        folder_ids: Optional folder ids to ingest.
+        file_ids: Optional file ids to ingest.
+        auth_mode: Auth mode. Defaults to ``"oauth"``.
+        oauth_credentials: Optional OAuth credential payload.
+        include_shared_drives: Optional shared-drive toggle.
+        sync_mode: Optional sync mode. Omitted from the request when ``None`` so
+            the server applies its default (``"incremental"``).
+        service_account_json: Optional service-account credential payload.
+        credentials_json: Optional generic credential payload.
+        connection_id: Optional id of a stored OAuth connection (see
+            ``client.connections``) to authorize the source with.
+        description: Optional source description.
+        metadata: Optional source metadata.
+        config_extra: Optional extra config fields merged into the request.
+    """
+
+    name: Optional[str] = None
+    folder_ids: Optional[Sequence[str]] = None
+    file_ids: Optional[Sequence[str]] = None
+    auth_mode: str = "oauth"
+    oauth_credentials: Optional[Mapping[str, Any]] = None
+    include_shared_drives: Optional[bool] = None
+    sync_mode: Optional[str] = None
+    service_account_json: Optional[Mapping[str, Any]] = None
+    credentials_json: Optional[Mapping[str, Any]] = None
+    connection_id: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this Google Drive source."""
+        config: JSON = {"auth_mode": self.auth_mode}
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional_sequence(config, "folder_ids", self.folder_ids)
+        _set_optional_sequence(config, "file_ids", self.file_ids)
+        _set_optional(config, "include_shared_drives", self.include_shared_drives)
+        if self.oauth_credentials is not None:
+            config["oauth_credentials"] = dict(self.oauth_credentials)
+        if self.service_account_json is not None:
+            config["service_account_json"] = dict(self.service_account_json)
+        if self.credentials_json is not None:
+            config["credentials_json"] = dict(self.credentials_json)
+        _set_optional(config, "connection_id", self.connection_id)
+        _merge_extra(config, self.config_extra)
+        return _source_body(
+            name=self.name or _default_google_drive_source_name(self.folder_ids, self.file_ids),
+            source_type="gdrive",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class FileUploadSource:
+    """File-upload ingestion source.
+
+    This models the source record only. Use ``dataset.ingest_files`` or
+    ``client.ingestion.ingest_files`` for the local presigned-upload flow; those
+    helpers auto-create a ``file_upload`` source when uploading files.
+
+    Args:
+        name: Source name. Defaults to ``"vectoramp-python-upload"``.
+        storage_provider: Upload storage provider. Defaults to ``"s3"``.
+        sync_mode: Sync mode. Defaults to ``"full"``.
+        description: Optional source description.
+        metadata: Optional source metadata.
+        config_extra: Optional extra config fields merged into the request.
+    """
+
+    name: str = "vectoramp-python-upload"
+    storage_provider: str = "s3"
+    sync_mode: str = "full"
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this file-upload source."""
+        config: JSON = {
+            "storage_provider": self.storage_provider,
+            "sync_mode": self.sync_mode,
+        }
+        _merge_extra(config, self.config_extra)
+        return _source_body(
+            name=self.name,
+            source_type="file_upload",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class JiraSource:
+    """Jira ingestion source.
+
+    ``include_comments`` defaults to true. ``sync_mode`` is omitted from the
+    request when ``None`` so the server applies its default (``"incremental"``).
+    """
+
+    name: Optional[str] = None
+    cloud_id: str = ""
+    access_token: Optional[str] = None
+    project_keys: Optional[Sequence[str]] = None
+    jql: Optional[str] = None
+    include_comments: bool = True
+    sync_mode: Optional[str] = None
+    connection_id: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        if not self.cloud_id:
+            raise ValueError("JiraSource requires cloud_id.")
+        config: JSON = {
+            "cloud_id": self.cloud_id,
+            "include_comments": self.include_comments,
+        }
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional(config, "access_token", self.access_token)
+        _set_optional_sequence(config, "project_keys", self.project_keys)
+        _set_optional(config, "jql", self.jql)
+        _set_optional(config, "connection_id", self.connection_id)
+        _merge_extra(config, self.config_extra)
+        hint = self.project_keys[0] if self.project_keys else self.cloud_id
+        return _source_body(
+            name=self.name or _default_source_name("jira", hint),
+            source_type="jira",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+@dataclass(frozen=True)
+class ConfluenceSource:
+    """Confluence ingestion source.
+
+    Confluence spaces and pages from an Atlassian Cloud site. Provide either
+    ``cloud_id`` (Atlassian OAuth cloud/site id) or ``base_url`` (e.g.
+    ``"https://company.atlassian.net"``). For basic auth, set ``username`` and
+    ``api_token``; for OAuth, set ``oauth_credentials``.
+
+    Args:
+        name: Source name. Defaults to ``confluence-{cloud-id-or-host}``.
+        cloud_id: Atlassian OAuth cloud/site id. Required unless ``base_url`` set.
+        base_url: Atlassian site base URL. Required unless ``cloud_id`` set.
+        auth_mode: Auth mode. Defaults to ``"basic"``.
+        username: Optional basic-auth username (typically an account email).
+        api_token: Optional basic-auth API token.
+        oauth_credentials: Optional Atlassian OAuth credential payload.
+        spaces: Optional space keys to ingest. Empty means all accessible spaces.
+        include_attachments: Whether to ingest attachments. Defaults to ``False``.
+        sync_mode: Optional sync mode. Omitted from the request when ``None`` so
+            the server applies its default (``"incremental"``).
+        connection_id: Optional id of a stored OAuth connection (see
+            ``client.connections``) to authorize the source with.
+        description: Optional source description.
+        metadata: Optional source metadata.
+        config_extra: Optional extra config fields merged into the request.
+    """
+
+    name: Optional[str] = None
+    cloud_id: Optional[str] = None
+    base_url: Optional[str] = None
+    auth_mode: str = "basic"
+    username: Optional[str] = None
+    api_token: Optional[str] = None
+    oauth_credentials: Optional[Mapping[str, Any]] = None
+    spaces: Optional[Sequence[str]] = None
+    include_attachments: bool = False
+    sync_mode: Optional[str] = None
+    connection_id: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    config_extra: Optional[Mapping[str, Any]] = None
+
+    def to_create_request(self) -> JSON:
+        """Return source-create request fields for this Confluence source."""
+        if not self.cloud_id and not self.base_url:
+            raise ValueError("ConfluenceSource requires cloud_id or base_url.")
+        config: JSON = {
+            "auth_mode": self.auth_mode,
+            "include_attachments": self.include_attachments,
+        }
+        _set_optional(config, "cloud_id", self.cloud_id)
+        _set_optional(config, "base_url", self.base_url)
+        _set_optional(config, "username", self.username)
+        _set_optional(config, "api_token", self.api_token)
+        if self.oauth_credentials is not None:
+            config["oauth_credentials"] = dict(self.oauth_credentials)
+        _set_optional_sequence(config, "spaces", self.spaces)
+        _set_optional(config, "sync_mode", self.sync_mode)
+        _set_optional(config, "connection_id", self.connection_id)
+        _merge_extra(config, self.config_extra)
+        hint = self.cloud_id or _confluence_host_hint(self.base_url)
+        return _source_body(
+            name=self.name or _default_source_name("confluence", hint),
+            source_type="confluence",
+            config=config,
+            description=self.description,
+            metadata=self.metadata,
+        )
+
+
+TypedSource = Union[
+    GenericSource,
+    WebSource,
+    S3Source,
+    GCSSource,
+    GoogleDriveSource,
+    FileUploadSource,
+    JiraSource,
+    ConfluenceSource,
+]
+SourceInput = Union[str, TypedSource]
+
+
+def _source_body(
+    *,
+    name: str,
+    source_type: str,
+    config: Mapping[str, Any],
+    description: Optional[str],
+    metadata: Optional[Mapping[str, Any]],
+) -> JSON:
+    body: JSON = {"name": name, "source_type": source_type, "config": dict(config)}
+    if description is not None:
+        body["description"] = description
+    if metadata is not None:
+        body["metadata"] = dict(metadata)
+    return body
+
+
+def _default_web_source_name(start_urls: Sequence[str]) -> str:
+    first_url = start_urls[0]
+    parsed = urlparse(first_url)
+    hint = parsed.netloc or parsed.path or first_url
+    return _default_source_name("web", hint)
+
+
+def _default_google_drive_source_name(
+    folder_ids: Optional[Sequence[str]], file_ids: Optional[Sequence[str]]
+) -> str:
+    hint = None
+    if folder_ids:
+        hint = folder_ids[0]
+    elif file_ids:
+        hint = file_ids[0]
+    return _default_source_name("gdrive", hint)
+
+
+def _confluence_host_hint(base_url: Optional[str]) -> Optional[str]:
+    if not base_url:
+        return None
+    parsed = urlparse(base_url)
+    return parsed.netloc or parsed.path or base_url
+
+
+def _default_source_name(source_type: str, hint: Optional[str] = None) -> str:
+    parts = [source_type.replace("_", "-")]
+    if hint:
+        slug = _slugify(str(hint))
+        if slug:
+            parts.append(slug)
+    return "-".join(parts)
+
+
+def _slugify(value: str) -> str:
+    slug = "".join(char.lower() if char.isalnum() else "-" for char in value)
+    return "-".join(part for part in slug.split("-") if part)[:48]
+
+
+def _set_optional(config: JSON, key: str, value: Any) -> None:
+    if value is not None:
+        config[key] = value
+
+
+def _set_optional_sequence(config: JSON, key: str, value: Optional[Sequence[str]]) -> None:
+    if value is not None:
+        config[key] = list(value)
+
+
+def _merge_extra(config: JSON, extra: Optional[Mapping[str, Any]]) -> None:
+    if extra is not None:
+        config.update(dict(extra))

vectoramp/transport.py

@@ -0,0 +1,198 @@
+"""Transport abstraction for VectorAmp.
+
+The public client depends on this small interface rather than directly on httpx.  REST is the
+current implementation; a future gRPC transport can implement the same request/stream surface.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Iterator, Mapping, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+from .exceptions import APIError, AuthenticationError
+
+
+class BaseTransport(ABC):
+    """Minimal transport contract used by resource clients."""
+
+    @abstractmethod
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Send one request and return decoded response content."""
+
+    @abstractmethod
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        """Yield JSON-decoded Server-Sent Event data chunks."""
+
+    def download(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> bytes:
+        """Send one request and return raw response bytes."""
+        raise NotImplementedError("transport does not support raw downloads")
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release transport resources."""
+
+
+class RestTransport(BaseTransport):
+    """httpx-backed REST transport."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://api.vectoramp.com",
+        timeout: float = 30.0,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise AuthenticationError(
+                "An API key is required. Pass api_key or set VECTORAMP_API_KEY."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/") + "/"
+        self._owns_client = client is None
+        self.client = client or httpx.Client(timeout=timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        response = self.client.request(
+            method,
+            self._url(path),
+            params=self._clean(params),
+            json=json_body,
+            headers=self._headers(headers),
+        )
+        return self._decode_response(response)
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        request_headers = self._headers({"Accept": "text/event-stream", **dict(headers or {})})
+        with self.client.stream(
+            method, self._url(path), json=json_body, headers=request_headers
+        ) as response:
+            self._raise_for_status(response)
+            for line in response.iter_lines():
+                if not line or line.startswith(":"):
+                    continue
+                if line.startswith("data:"):
+                    payload = line[5:].strip()
+                    if payload == "[DONE]":
+                        break
+                    yield json.loads(payload)
+
+    def download(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> bytes:
+        """Send one request and return raw response bytes."""
+        response = self.client.request(
+            method,
+            self._url(path),
+            params=self._clean(params),
+            headers=self._headers(headers),
+            follow_redirects=True,
+        )
+        self._raise_for_status(response)
+        return response.content
+
+    def put_url(
+        self,
+        url: str,
+        *,
+        content: bytes,
+        content_type: Optional[str] = None,
+    ) -> None:
+        """Upload bytes to a presigned URL without VectorAmp auth headers."""
+        headers = {"Content-Type": content_type} if content_type else None
+        response = self.client.put(url, content=content, headers=headers)
+        self._raise_for_status(response)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self.client.close()
+
+    def _url(self, path: str) -> str:
+        return urljoin(self.base_url, path.lstrip("/"))
+
+    def _headers(self, headers: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        merged = {"X-API-Key": self.api_key, "User-Agent": "vectoramp-python/0.1.0"}
+        if headers:
+            merged.update(headers)
+        return merged
+
+    @staticmethod
+    def _clean(params: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+        if params is None:
+            return None
+        return {key: value for key, value in params.items() if value is not None}
+
+    @classmethod
+    def _decode_response(cls, response: httpx.Response) -> Any:
+        cls._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        content_type = response.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return response.json()
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            payload = response.json()
+            message = (
+                payload.get("message")
+                or payload.get("detail")
+                or payload.get("error")
+                or str(payload)
+            )
+        except ValueError:
+            message = response.text
+        raise APIError(response.status_code, message, response=response)