redblack-python-sdk 0.1.0__py3-none-any.whl

redblack/errors.py

@@ -0,0 +1,483 @@
+"""Public exception hierarchy and defensive API-error parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit, urlunsplit
+
+if TYPE_CHECKING:
+    import httpx
+
+_MAX_ERROR_BODY = 65_536
+_SENSITIVE_HEADERS = {
+    "authorization",
+    "client-id",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+    "x-api-key",
+}
+_REQUEST_ID_HEADERS = (
+    "x-request-id",
+    "request-id",
+    "x-correlation-id",
+    "traceparent",
+)
+_SENSITIVE_ASSIGNMENT = re.compile(
+    r"(?i)(authorization|client[_-]?secret|password|access[_-]?token|"
+    r"x-api-key|api[_-]?key)\s*([:=]\s*|[\"']\s*:\s*[\"'])"
+    r"([^,\s&\"']+)"
+)
+_BEARER_VALUE = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")
+
+
+class RedBlackError(Exception):
+    """Base class for all SDK-owned exceptions."""
+
+
+class ConfigurationError(RedBlackError):
+    """The SDK configuration is missing, ambiguous, or unsafe."""
+
+
+class AuthenticationError(RedBlackError):
+    """Token acquisition or a custom token provider failed."""
+
+    def __init__(
+        self,
+        message: str = "RedBlack authentication failed",
+        *,
+        error: str | None = None,
+        error_description: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        secrets: Iterable[str] = (),
+    ) -> None:
+        self.error = redact_text(error, secrets=secrets) if error else None
+        self.error_description = (
+            redact_text(error_description, secrets=secrets) if error_description else None
+        )
+        self.status_code = status_code
+        self.request_id = request_id
+        super().__init__(redact_text(message, secrets=secrets))
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"error={self.error!r}, request_id={self.request_id!r})"
+        )
+
+
+class TransportError(RedBlackError):
+    """The request did not produce an HTTP response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        method: str | None = None,
+        path: str | None = None,
+    ) -> None:
+        self.method = method
+        self.path = path
+        context = _format_request_context(method, path)
+        super().__init__(f"{message}{context}")
+
+
+class RequestTimeoutError(TransportError):
+    """An HTTP request timed out."""
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class ProblemDetails:
+    """Tolerant representation of an RFC-style problem response."""
+
+    type: str | None = None
+    title: str | None = None
+    status: int | None = None
+    detail: str | None = field(default=None, repr=False)
+    instance: str | None = field(default=None, repr=False)
+    extensions: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}), repr=False)
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> ProblemDetails:
+        known = {"type", "title", "status", "detail", "instance"}
+        raw_status = value.get("status")
+        status = (
+            raw_status if isinstance(raw_status, int) and not isinstance(raw_status, bool) else None
+        )
+        return cls(
+            type=_optional_string(value.get("type")),
+            title=_optional_string(value.get("title")),
+            status=status,
+            detail=_optional_string(value.get("detail")),
+            instance=_optional_string(value.get("instance")),
+            extensions=MappingProxyType(
+                {key: item for key, item in value.items() if key not in known}
+            ),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            "ProblemDetails("
+            f"has_type={self.type is not None}, "
+            f"has_title={self.title is not None}, status={self.status!r}, "
+            f"has_detail={self.detail is not None}, "
+            f"extension_count={len(self.extensions)!r})"
+        )
+
+
+class ApiError(RedBlackError):
+    """A RedBlack resource endpoint returned an unsuccessful response."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        method: str,
+        path: str,
+        problem: ProblemDetails | None = None,
+        structured_errors: Any = None,
+        unknown_fields: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        request_id: str | None = None,
+        raw_body: bytes = b"",
+        body_truncated: bool = False,
+    ) -> None:
+        self.status_code = status_code
+        self.method = method.upper()
+        self.path = path
+        self.problem = problem
+        self.structured_errors = structured_errors
+        self.unknown_fields = MappingProxyType(dict(unknown_fields or {}))
+        self.headers = MappingProxyType(dict(headers or {}))
+        self.request_id = request_id
+        self.raw_body = raw_body
+        self.body_truncated = body_truncated
+        message = (
+            f"RedBlack API request failed with HTTP {status_code}"
+            f"{_format_request_context(self.method, self.path)}"
+        )
+        if request_id:
+            message += f" [request_id={request_id}]"
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"method={self.method!r}, path={self.path!r}, "
+            f"request_id={self.request_id!r}, "
+            f"has_problem={self.problem is not None}, "
+            f"raw_body_bytes={len(self.raw_body)!r})"
+        )
+
+
+class BadRequestError(ApiError):
+    """HTTP 400."""
+
+
+class UnauthorizedError(ApiError):
+    """HTTP 401 from a resource endpoint."""
+
+
+class ForbiddenError(ApiError):
+    """HTTP 403."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404 (not found or not visible to this API user)."""
+
+
+class MethodNotAllowedError(ApiError):
+    """HTTP 405."""
+
+
+class ConflictError(ApiError):
+    """HTTP 409."""
+
+
+class GoneError(ApiError):
+    """HTTP 410."""
+
+
+class PreconditionFailedError(ApiError):
+    """HTTP 412, usually an ETag mismatch."""
+
+
+class UnprocessableContentError(ApiError):
+    """HTTP 422."""
+
+
+class RateLimitError(ApiError):
+    """HTTP 429."""
+
+    @property
+    def retry_after(self) -> str | None:
+        return self.headers.get("retry-after")
+
+
+class ServerError(ApiError):
+    """HTTP 5xx."""
+
+
+class ResponseDecodeError(RedBlackError):
+    """A nominally successful response could not be decoded as contracted."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        method: str | None = None,
+        path: str | None = None,
+        request_id: str | None = None,
+        raw_body: bytes = b"",
+    ) -> None:
+        self.status_code = status_code
+        self.method = method
+        self.path = path
+        self.request_id = request_id
+        self.raw_body = bytes(raw_body[:_MAX_ERROR_BODY])
+        self.body_truncated = len(raw_body) > len(self.raw_body)
+        rendered = f"{message}{_format_request_context(method, path)}"
+        if request_id:
+            rendered += f" [request_id={request_id}]"
+        super().__init__(rendered)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"method={self.method!r}, path={self.path!r}, "
+            f"request_id={self.request_id!r}, "
+            f"raw_body_bytes={len(self.raw_body)!r}, "
+            f"body_truncated={self.body_truncated!r})"
+        )
+
+
+class PollingError(RedBlackError):
+    """Base class for local polling and terminal workflow failures."""
+
+
+class PollTimeoutError(PollingError):
+    """A local polling deadline elapsed."""
+
+    timeout: float | None
+    last_value: object | None
+
+    def __init__(
+        self,
+        message_or_timeout: str | float | None,
+        last_value: object | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> None:
+        if isinstance(message_or_timeout, str):
+            message = message_or_timeout
+            resolved_timeout = timeout
+        else:
+            resolved_timeout = message_or_timeout if timeout is None else timeout
+            message = f"workflow did not finish within {resolved_timeout!r} seconds"
+        self.timeout = resolved_timeout
+        self.last_value = last_value
+        super().__init__(message)
+
+
+class OperationFailedError(PollingError):
+    """A server-side long-running operation reached a failed terminal state."""
+
+    def __init__(self, message: str, *, final_state: Any = None) -> None:
+        self.final_state = final_state
+        super().__init__(message)
+
+
+class OperationNeedsInputError(PollingError):
+    """A workflow stopped in a state that requires user action."""
+
+    def __init__(self, message: str, *, final_state: Any = None) -> None:
+        self.final_state = final_state
+        super().__init__(message)
+
+
+_STATUS_ERRORS: dict[int, type[ApiError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    405: MethodNotAllowedError,
+    409: ConflictError,
+    410: GoneError,
+    412: PreconditionFailedError,
+    422: UnprocessableContentError,
+    429: RateLimitError,
+}
+
+
+def api_error_from_response(
+    response: httpx.Response,
+    *,
+    method: str | None = None,
+    path: str | None = None,
+) -> ApiError:
+    """Parse a resource response without trusting its Content-Type header."""
+
+    request_method = method or str(response.request.method)
+    request_path = path or response.request.url.path
+    original = response.content
+    bounded = original[:_MAX_ERROR_BODY]
+    body_truncated = len(original) > len(bounded)
+
+    payload: Any = None
+    if original:
+        try:
+            payload = json.loads(original)
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            payload = None
+
+    problem: ProblemDetails | None = None
+    structured_errors: Any = None
+    unknown_fields: dict[str, Any] = {}
+    if isinstance(payload, Mapping):
+        problem_keys = {"type", "title", "status", "detail", "instance"}
+        if problem_keys.intersection(payload):
+            problem = ProblemDetails.from_mapping(payload)
+        structured_errors = (
+            payload.get("validationErrors")
+            if "validationErrors" in payload
+            else payload.get("errors")
+        )
+        recognized = problem_keys | {"errors", "validationErrors"}
+        unknown_fields = {
+            str(key): value for key, value in payload.items() if key not in recognized
+        }
+    elif payload is not None:
+        unknown_fields = {"payload": payload}
+
+    headers = safe_response_headers(response.headers)
+    request_id = extract_request_id(response.headers)
+    error_class = (
+        ServerError
+        if 500 <= response.status_code <= 599
+        else _STATUS_ERRORS.get(response.status_code, ApiError)
+    )
+    return error_class(
+        status_code=response.status_code,
+        method=request_method,
+        path=request_path,
+        problem=problem,
+        structured_errors=structured_errors,
+        unknown_fields=unknown_fields,
+        headers=headers,
+        request_id=request_id,
+        raw_body=bounded,
+        body_truncated=body_truncated,
+    )
+
+
+def extract_request_id(headers: Mapping[str, str]) -> str | None:
+    """Return the first recognized server correlation header."""
+
+    lowered = {key.lower(): value for key, value in headers.items()}
+    for name in _REQUEST_ID_HEADERS:
+        if value := lowered.get(name):
+            return value
+    return None
+
+
+def safe_response_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    """Copy response headers while removing credential-bearing values."""
+
+    safe: dict[str, str] = {}
+    for name, value in headers.items():
+        lowered = name.lower()
+        if lowered in _SENSITIVE_HEADERS:
+            continue
+        safe[lowered] = sanitize_url(value) if lowered == "location" else redact_text(value)
+    return safe
+
+
+def sanitize_url(value: str) -> str:
+    """Remove user information, query values, and fragments from a URL."""
+
+    try:
+        split = urlsplit(value)
+    except ValueError:
+        return "<redacted-url>"
+    if not split.scheme and not split.netloc:
+        return urlunsplit(("", "", split.path, "", ""))
+    hostname = split.hostname or ""
+    if ":" in hostname and not hostname.startswith("["):
+        hostname = f"[{hostname}]"
+    netloc = hostname
+    try:
+        port = split.port
+    except ValueError:
+        return "<redacted-url>"
+    if port is not None:
+        netloc += f":{port}"
+    return urlunsplit((split.scheme, netloc, split.path, "", ""))
+
+
+def redact_text(value: str | None, *, secrets: Iterable[str] = ()) -> str:
+    """Best-effort defense against common credential strings in diagnostics."""
+
+    if value is None:
+        return ""
+    redacted = str(value)
+    for secret in secrets:
+        if secret:
+            redacted = redacted.replace(secret, "<redacted>")
+    redacted = _BEARER_VALUE.sub("Bearer <redacted>", redacted)
+    redacted = _SENSITIVE_ASSIGNMENT.sub(
+        lambda match: f"{match.group(1)}{match.group(2)}<redacted>", redacted
+    )
+    return redacted
+
+
+def _optional_string(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _format_request_context(method: str | None, path: str | None) -> str:
+    if method and path:
+        return f" ({method.upper()} {path})"
+    if method:
+        return f" ({method.upper()})"
+    if path:
+        return f" ({path})"
+    return ""
+
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConfigurationError",
+    "ConflictError",
+    "ForbiddenError",
+    "GoneError",
+    "MethodNotAllowedError",
+    "NotFoundError",
+    "OperationFailedError",
+    "OperationNeedsInputError",
+    "PollingError",
+    "PollTimeoutError",
+    "PreconditionFailedError",
+    "ProblemDetails",
+    "RateLimitError",
+    "RedBlackError",
+    "RequestTimeoutError",
+    "ResponseDecodeError",
+    "ServerError",
+    "TransportError",
+    "UnauthorizedError",
+    "UnprocessableContentError",
+    "api_error_from_response",
+    "extract_request_id",
+    "redact_text",
+    "safe_response_headers",
+    "sanitize_url",
+]

redblack/models/__init__.py

@@ -0,0 +1,105 @@
+"""Stable application-facing model aliases for RedBlack 2026.3.0.
+
+Exact generated wire types remain available from
+``redblack.models.generated``.
+"""
+
+from . import generated as _generated
+from .base import (
+    UNSET,
+    ODataPageModel,
+    OpenIntEnum,
+    RequestModel,
+    ResponseModel,
+    UnsetType,
+)
+
+Account = _generated.AccountsAccountQueryRow
+AccountExportJob = _generated.AccountsAccountExportJob
+CashAction = _generated.CashActionCashActionQueryRow
+CashActionCreate = _generated.CashActionsAddRequest
+CashActionCreateResult = _generated.CashActionsAddResponse201
+CashActionDeleteResult = _generated.CashActionsDeleteCashActionsResponse200
+CashActionDetails = _generated.CashActionsGetResponse200
+CashActionUpdate = _generated.CashActionsUpdateRequest
+CashActionUpdateResult = _generated.CashActionsUpdateResponse200
+Equivalent = _generated.EquivalentQueryEquivalentsResponse200ValueItem
+EquivalentExportJob = _generated.EquivalentsEquivalentExportJob
+Household = _generated.HouseholdsQueryHouseholdsResponse200ValueItem
+HouseholdExportJob = _generated.HouseholdsHouseholdExportJob
+Order = _generated.OrdersOrderQueryRow
+OrderAddCancelResult = _generated.CommonResponseApiModelBase
+OrderAddResult = _generated.ReviewSetsOrderMessageInOrderAddSessionQueryRow
+OrderAddSession = _generated.ReviewSetsOrderAddSession
+OrderAddSessionItem = _generated.ReviewSetsOrderInOrderAddSession
+OrderCreate = _generated.ReviewSetsOrderAddRequest
+OrderCreateResult = _generated.CommonEntityAddResult
+OrderFilterType = _generated.OrdersOrderQueryFilterType
+PendingOrder = _generated.ReviewSetsPendingOrderQueryRow
+ProblemDetails = _generated.CommonProblemDetails
+ReleaseError = _generated.ReviewSetsQueryReleaseResultsResponse200ValueItem
+ReleaseValidationResult = _generated.ReviewSetsQueryReleaseValidationResultsResponse200ValueItem
+Restriction = _generated.RestrictionQueryRestrictionsResponse200ValueItem
+RestrictionExportJob = _generated.RestrictionsRestrictionExportJob
+ReviewSet = _generated.ReviewSetsQueryResponse200ValueItem
+ReviewSetReleaseSession = _generated.ReviewSetsGetReleaseSessionResponse200
+Security = _generated.SecuritiesSecurityQueryRow
+SweepSecurity = _generated.SecuritiesSweepSecurityQueryRow
+Task = _generated.TasksGetResponse200
+TaskCreate = _generated.TasksAddRequest
+TaskCreateResult = _generated.TasksAddResponse201
+TaskListItem = _generated.TasksTaskQueryRow
+TaskStatus = _generated.TaskSettingsTaskStatusQueryRow
+TaskType = _generated.TaskSettingsTaskTypeQueryRow
+TaskUpdate = _generated.TasksTaskUpdateSpecification
+TaskUpdateResult = _generated.TasksUpdateResponse200
+User = _generated.UsersUserQueryRow
+
+__all__ = [
+    "OpenIntEnum",
+    "ODataPageModel",
+    "RequestModel",
+    "ResponseModel",
+    "UNSET",
+    "UnsetType",
+    "Account",
+    "AccountExportJob",
+    "CashAction",
+    "CashActionCreate",
+    "CashActionCreateResult",
+    "CashActionDeleteResult",
+    "CashActionDetails",
+    "CashActionUpdate",
+    "CashActionUpdateResult",
+    "Equivalent",
+    "EquivalentExportJob",
+    "Household",
+    "HouseholdExportJob",
+    "Order",
+    "OrderAddCancelResult",
+    "OrderAddResult",
+    "OrderAddSession",
+    "OrderAddSessionItem",
+    "OrderCreate",
+    "OrderCreateResult",
+    "OrderFilterType",
+    "PendingOrder",
+    "ProblemDetails",
+    "ReleaseError",
+    "ReleaseValidationResult",
+    "Restriction",
+    "RestrictionExportJob",
+    "ReviewSet",
+    "ReviewSetReleaseSession",
+    "Security",
+    "SweepSecurity",
+    "Task",
+    "TaskCreate",
+    "TaskCreateResult",
+    "TaskListItem",
+    "TaskStatus",
+    "TaskType",
+    "TaskUpdate",
+    "TaskUpdateResult",
+    "User",
+]