reconify-python 0.1.0__py3-none-any.whl

reconify/__init__.py

@@ -0,0 +1,36 @@
+"""Typed clients for the Reconify Public API."""
+
+__version__ = "0.1.0"
+
+from .client import AsyncReconify, Reconify
+from .errors import (
+    ReconifyAuthenticationError,
+    ReconifyConflictError,
+    ReconifyError,
+    ReconifyNotFoundError,
+    ReconifyPermissionError,
+    ReconifyRateLimitError,
+    ReconifyRequestError,
+    ReconifyServerError,
+    ReconifyServiceUnavailableError,
+    ReconifyValidationError,
+)
+from .transport import RawResponse, RetryConfig
+
+__all__ = [
+    "AsyncReconify",
+    "Reconify",
+    "__version__",
+    "RawResponse",
+    "RetryConfig",
+    "ReconifyError",
+    "ReconifyValidationError",
+    "ReconifyAuthenticationError",
+    "ReconifyPermissionError",
+    "ReconifyNotFoundError",
+    "ReconifyConflictError",
+    "ReconifyRequestError",
+    "ReconifyRateLimitError",
+    "ReconifyServiceUnavailableError",
+    "ReconifyServerError",
+]

reconify/client.py

@@ -0,0 +1,264 @@
+"""Top-level synchronous and asynchronous Reconify clients."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+import httpx
+
+from .errors import ReconifyValidationError
+from .pagination import (
+    aiter_cursor_pages,
+    aiter_offset_pages,
+    iter_cursor_pages,
+    iter_offset_pages,
+)
+from .resources import (
+    ASYNC_RESOURCE_CLASSES,
+    SYNC_RESOURCE_CLASSES,
+    Alerts,
+    AsyncAlerts,
+    AsyncEvents,
+    AsyncIngestion,
+    AsyncIssues,
+    AsyncLedger,
+    AsyncReconciliations,
+    AsyncSearch,
+    AsyncSetup,
+    AsyncTransactions,
+    AsyncWallets,
+    Events,
+    Ingestion,
+    Issues,
+    Ledger,
+    Reconciliations,
+    Search,
+    Setup,
+    Transactions,
+    Wallets,
+)
+from .transport import AsyncTransport, RetryConfig, SyncTransport
+
+DEFAULT_BASE_URL = "https://api.reconifyhq.com/v1"
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    value = (base_url or os.getenv("RECONIFY_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+    return value if value.endswith("/v1") else f"{value}/v1"
+
+
+def _api_key(api_key: str | None) -> str:
+    value = api_key or os.getenv("RECONIFY_API_KEY")
+    if not value:
+        raise ReconifyValidationError("An API key is required")
+    if value.startswith("sk_live_"):
+        raise ReconifyValidationError("Legacy sk_live_ keys are not supported; use an rk_ key")
+    if not value.startswith("rk_"):
+        raise ReconifyValidationError("Reconify public API keys must start with rk_")
+    return value
+
+
+class Reconify:
+    """Synchronous typed Reconify API client."""
+
+    alerts: Alerts
+    events: Events
+    ingestion: Ingestion
+    issues: Issues
+    ledger: Ledger
+    reconciliations: Reconciliations
+    search: Search
+    setup: Setup
+    transactions: Transactions
+    wallets: Wallets
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        request_id: str | None = None,
+        retry: RetryConfig | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = SyncTransport(
+            base_url=_normalize_base_url(base_url),
+            api_key=_api_key(api_key),
+            timeout=timeout,
+            request_id=request_id,
+            retry=retry,
+            client=http_client,
+        )
+        for name, resource_class in SYNC_RESOURCE_CLASSES.items():
+            setattr(self, name, resource_class(self._transport))
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Reconify:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def iter_events(self, **query: Any) -> Iterator[Any]:
+        return iter_cursor_pages(
+            lambda params: self.events.list_events(**params), item_field="events", query=query
+        )
+
+    def iter_issues(self, **query: Any) -> Iterator[Any]:
+        return iter_cursor_pages(
+            lambda params: self.issues.list_issues(**params), item_field="issues", query=query
+        )
+
+    def iter_ledger_sources(self, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.ledger.list_ledger_sources(**params),
+            item_field="sources",
+            query=query,
+        )
+
+    def iter_ledger_transactions(self, source_id: str, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.ledger.list_transactions(source_id, **params),
+            item_field="transactions",
+            query=query,
+        )
+
+    def iter_reconciliation_schedules(self, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.reconciliations.list_reconciliation_schedules(**params),
+            item_field="schedules",
+            query=query,
+        )
+
+    def iter_reconciliations(self, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.reconciliations.list_reconciliations(**params),
+            item_field="reconciliations",
+            query=query,
+        )
+
+    def iter_setup_sources(self, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.setup.list_setup_sources(**params),
+            item_field="sources",
+            query=query,
+        )
+
+    def iter_wallet_transactions(self, **query: Any) -> Iterator[Any]:
+        return iter_cursor_pages(
+            lambda params: self.transactions.list_wallet_transactions(**params),
+            item_field="transactions",
+            query=query,
+        )
+
+    def iter_wallets(self, **query: Any) -> Iterator[Any]:
+        return iter_offset_pages(
+            lambda params: self.wallets.list_wallets(**params), item_field="wallets", query=query
+        )
+
+
+class AsyncReconify:
+    """Asynchronous typed Reconify API client."""
+
+    alerts: AsyncAlerts
+    events: AsyncEvents
+    ingestion: AsyncIngestion
+    issues: AsyncIssues
+    ledger: AsyncLedger
+    reconciliations: AsyncReconciliations
+    search: AsyncSearch
+    setup: AsyncSetup
+    transactions: AsyncTransactions
+    wallets: AsyncWallets
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        request_id: str | None = None,
+        retry: RetryConfig | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(
+            base_url=_normalize_base_url(base_url),
+            api_key=_api_key(api_key),
+            timeout=timeout,
+            request_id=request_id,
+            retry=retry,
+            client=http_client,
+        )
+        for name, resource_class in ASYNC_RESOURCE_CLASSES.items():
+            setattr(self, name, resource_class(self._transport))
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncReconify:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    def iter_events(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_cursor_pages(
+            lambda params: self.events.list_events(**params), item_field="events", query=query
+        )
+
+    def iter_issues(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_cursor_pages(
+            lambda params: self.issues.list_issues(**params), item_field="issues", query=query
+        )
+
+    def iter_ledger_sources(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.ledger.list_ledger_sources(**params),
+            item_field="sources",
+            query=query,
+        )
+
+    def iter_ledger_transactions(self, source_id: str, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.ledger.list_transactions(source_id, **params),
+            item_field="transactions",
+            query=query,
+        )
+
+    def iter_reconciliation_schedules(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.reconciliations.list_reconciliation_schedules(**params),
+            item_field="schedules",
+            query=query,
+        )
+
+    def iter_reconciliations(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.reconciliations.list_reconciliations(**params),
+            item_field="reconciliations",
+            query=query,
+        )
+
+    def iter_setup_sources(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.setup.list_setup_sources(**params),
+            item_field="sources",
+            query=query,
+        )
+
+    def iter_wallet_transactions(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_cursor_pages(
+            lambda params: self.transactions.list_wallet_transactions(**params),
+            item_field="transactions",
+            query=query,
+        )
+
+    def iter_wallets(self, **query: Any) -> AsyncIterator[Any]:
+        return aiter_offset_pages(
+            lambda params: self.wallets.list_wallets(**params), item_field="wallets", query=query
+        )

reconify/errors.py

@@ -0,0 +1,132 @@
+"""Exception types and safe error parsing for Reconify responses."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+class ReconifyError(Exception):
+    """Base class for client, validation, transport, and API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        title: str | None = None,
+        detail: str | None = None,
+        code: str | None = None,
+        validation_errors: list[dict[str, Any]] | None = None,
+        request_id: str | None = None,
+        response_headers: dict[str, str] | None = None,
+        response_metadata: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.title = title
+        self.detail = detail
+        self.code = code
+        self.validation_errors = validation_errors or []
+        self.request_id = request_id
+        self.response_headers = response_headers or {}
+        self.response_metadata = response_metadata or {}
+
+
+class ReconifyValidationError(ReconifyError):
+    """The client rejected invalid arguments before making a request."""
+
+
+class ReconifyAuthenticationError(ReconifyError):
+    """The API key is missing or not accepted (HTTP 401)."""
+
+
+class ReconifyPermissionError(ReconifyError):
+    """The API key cannot access the requested resource (HTTP 403)."""
+
+
+class ReconifyNotFoundError(ReconifyError):
+    """The requested resource does not exist (HTTP 404)."""
+
+
+class ReconifyConflictError(ReconifyError):
+    """The request conflicts with current server state (HTTP 409)."""
+
+
+class ReconifyRequestError(ReconifyError):
+    """The request is malformed or fails validation (HTTP 400/422)."""
+
+
+class ReconifyRateLimitError(ReconifyError):
+    """The API rate limit was exceeded (HTTP 429)."""
+
+
+class ReconifyServiceUnavailableError(ReconifyError):
+    """The API is temporarily unavailable (HTTP 503)."""
+
+
+class ReconifyServerError(ReconifyError):
+    """The API returned an unexpected 5xx response."""
+
+
+_STATUS_ERRORS: dict[int, type[ReconifyError]] = {
+    400: ReconifyRequestError,
+    401: ReconifyAuthenticationError,
+    403: ReconifyPermissionError,
+    404: ReconifyNotFoundError,
+    409: ReconifyConflictError,
+    422: ReconifyRequestError,
+    429: ReconifyRateLimitError,
+    500: ReconifyServerError,
+    503: ReconifyServiceUnavailableError,
+}
+
+
+def error_for_response(
+    status_code: int,
+    headers: dict[str, str],
+    payload: Any,
+    *,
+    request_id: str | None,
+) -> ReconifyError:
+    """Build a typed exception without including credentials or request bodies."""
+
+    data = payload if isinstance(payload, dict) else {}
+    title = data.get("title") if isinstance(data.get("title"), str) else None
+    detail = data.get("detail") if isinstance(data.get("detail"), str) else None
+    if detail is None and isinstance(data.get("error"), str):
+        detail = data["error"]
+    if detail is None and isinstance(data.get("message"), str):
+        detail = data["message"]
+
+    validation = data.get("errors") if isinstance(data.get("errors"), list) else []
+    validation = cast(list[Any], validation)
+    safe_validation = [item for item in validation if isinstance(item, dict)]
+    code = None
+    for item in safe_validation:
+        if item.get("location") == "$code" and isinstance(item.get("message"), str):
+            code = item["message"]
+            break
+    if code is None and isinstance(data.get("code"), str):
+        code = data["code"]
+
+    message = detail or title or f"Reconify API request failed with status {status_code}"
+    exception_type = _STATUS_ERRORS.get(
+        status_code,
+        ReconifyServerError if status_code >= 500 else ReconifyError,
+    )
+    metadata = {
+        key: value
+        for key, value in data.items()
+        if key not in {"detail", "message", "error", "errors"}
+    }
+    return exception_type(
+        message,
+        status_code=status_code,
+        title=title,
+        detail=detail,
+        code=code,
+        validation_errors=safe_validation,
+        request_id=request_id,
+        response_headers=headers,
+        response_metadata=metadata,
+    )