reconify-python 0.1.0__py3-none-any.whl

reconify/transport.py

@@ -0,0 +1,299 @@
+"""HTTP transport, retry policy, and raw response handling."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Generic, TypeVar, cast
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from .errors import ReconifyError, ReconifyValidationError, error_for_response
+from .models import model_dump
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Bounded retry settings. Retries apply to GET by default."""
+
+    max_retries: int = 2
+    base_delay: float = 0.25
+    max_delay: float = 8.0
+    jitter: float = 0.25
+    retry_unsafe_methods: bool = False
+
+
+@dataclass(frozen=True)
+class RawResponse(Generic[T]):
+    """Unparsed response data returned by an operation with ``raw=True``."""
+
+    status_code: int
+    headers: httpx.Headers
+    body: bytes
+    request_id: str | None
+
+    def json(self) -> Any:
+        return json.loads(self.body) if self.body else None
+
+
+def _retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            parsed = parsedate_to_datetime(value)
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=timezone.utc)
+            return max(0.0, (parsed - datetime.now(timezone.utc)).total_seconds())
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+
+def _sleep_for(attempt: int, config: RetryConfig, retry_after: str | None) -> float:
+    server_delay = _retry_after(retry_after)
+    if server_delay is not None:
+        return min(config.max_delay, server_delay)
+    exponential = min(config.max_delay, config.base_delay * (2**attempt))
+    return float(min(config.max_delay, exponential + random.uniform(0.0, config.jitter)))
+
+
+def _can_retry_exception(method: str, attempts: int, config: RetryConfig) -> bool:
+    if attempts >= config.max_retries:
+        return False
+    return method.upper() in {"GET", "HEAD", "OPTIONS"} or config.retry_unsafe_methods
+
+
+def _payload(response: httpx.Response) -> Any:
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except (ValueError, json.JSONDecodeError):
+        return {"detail": response.text}
+
+
+def _validate_request_body(body: Any) -> Any:
+    if isinstance(body, BaseModel):
+        try:
+            return model_dump(body)
+        except ValidationError as exc:
+            raise ReconifyValidationError(str(exc)) from exc
+    return body
+
+
+def _validate_integrity_payload(path: str, body: Any) -> None:
+    if path not in {"/integrity/events", "/integrity/test-events"} or body is None:
+        return
+    payload_size = len(json.dumps(body, separators=(",", ":"), default=str).encode("utf-8"))
+    if payload_size > 5 * 1024 * 1024:
+        raise ReconifyValidationError("Integrity event requests must not exceed 5 MiB")
+
+
+class SyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float | httpx.Timeout = 30.0,
+        request_id: str | None = None,
+        retry: RetryConfig | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.request_id = request_id
+        self.retry = retry or RetryConfig()
+        self._client = client or httpx.Client(timeout=timeout)
+        self._owns_client = client is None
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+        model: type[T] | None = None,
+        raw: bool = False,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> T | RawResponse[T] | None:
+        request_headers = {"Authorization": f"Bearer {self.api_key}"}
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+        if self.request_id:
+            request_headers["X-Request-ID"] = self.request_id
+        request_headers.update(headers or {})
+        data = _validate_request_body(body)
+        _validate_integrity_payload(path, data)
+        params = {key: value for key, value in (query or {}).items() if value is not None}
+        attempts = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    params=params,
+                    json=data if data is not None else None,
+                    headers=request_headers,
+                    timeout=timeout,
+                )
+            except httpx.TransportError:
+                if not _can_retry_exception(method, attempts, self.retry):
+                    raise
+                time.sleep(_sleep_for(attempts, self.retry, None))
+                attempts += 1
+                continue
+            if response.status_code not in {429, 503} or not self._can_retry(method, attempts):
+                return self._finish(response, model=model, raw=raw)
+            delay = _sleep_for(attempts, self.retry, response.headers.get("Retry-After"))
+            time.sleep(delay)
+            attempts += 1
+
+    def _can_retry(self, method: str, attempts: int) -> bool:
+        if attempts >= self.retry.max_retries:
+            return False
+        return method.upper() in {"GET", "HEAD", "OPTIONS"} or self.retry.retry_unsafe_methods
+
+    def _finish(
+        self, response: httpx.Response, *, model: type[T] | None, raw: bool
+    ) -> T | RawResponse[T] | None:
+        request_id = response.headers.get("X-Request-ID")
+        if response.is_error:
+            raise error_for_response(
+                response.status_code,
+                dict(response.headers),
+                _payload(response),
+                request_id=request_id,
+            )
+        if response.status_code == 204:
+            return None
+        if raw:
+            return RawResponse(response.status_code, response.headers, response.content, request_id)
+        payload = _payload(response)
+        if model is None or payload is None:
+            return cast(T | RawResponse[T] | None, payload)
+        try:
+            return model.model_validate(payload)
+        except ValidationError as exc:
+            raise ReconifyError(
+                "The Reconify response did not match the expected schema",
+                status_code=response.status_code,
+                request_id=request_id,
+                response_headers=dict(response.headers),
+            ) from exc
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float | httpx.Timeout = 30.0,
+        request_id: str | None = None,
+        retry: RetryConfig | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.request_id = request_id
+        self.retry = retry or RetryConfig()
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+        model: type[T] | None = None,
+        raw: bool = False,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> T | RawResponse[T] | None:
+        request_headers = {"Authorization": f"Bearer {self.api_key}"}
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+        if self.request_id:
+            request_headers["X-Request-ID"] = self.request_id
+        request_headers.update(headers or {})
+        data = _validate_request_body(body)
+        _validate_integrity_payload(path, data)
+        params = {key: value for key, value in (query or {}).items() if value is not None}
+        attempts = 0
+        while True:
+            try:
+                response = await self._client.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    params=params,
+                    json=data if data is not None else None,
+                    headers=request_headers,
+                    timeout=timeout,
+                )
+            except httpx.TransportError:
+                if not _can_retry_exception(method, attempts, self.retry):
+                    raise
+                await asyncio.sleep(_sleep_for(attempts, self.retry, None))
+                attempts += 1
+                continue
+            if response.status_code not in {429, 503} or not self._can_retry(method, attempts):
+                return self._finish(response, model=model, raw=raw)
+            delay = _sleep_for(attempts, self.retry, response.headers.get("Retry-After"))
+            await asyncio.sleep(delay)
+            attempts += 1
+
+    def _can_retry(self, method: str, attempts: int) -> bool:
+        if attempts >= self.retry.max_retries:
+            return False
+        return method.upper() in {"GET", "HEAD", "OPTIONS"} or self.retry.retry_unsafe_methods
+
+    def _finish(
+        self, response: httpx.Response, *, model: type[T] | None, raw: bool
+    ) -> T | RawResponse[T] | None:
+        request_id = response.headers.get("X-Request-ID")
+        if response.is_error:
+            raise error_for_response(
+                response.status_code,
+                dict(response.headers),
+                _payload(response),
+                request_id=request_id,
+            )
+        if response.status_code == 204:
+            return None
+        if raw:
+            return RawResponse(response.status_code, response.headers, response.content, request_id)
+        payload = _payload(response)
+        if model is None or payload is None:
+            return cast(T | RawResponse[T] | None, payload)
+        try:
+            return model.model_validate(payload)
+        except ValidationError as exc:
+            raise ReconifyError(
+                "The Reconify response did not match the expected schema",
+                status_code=response.status_code,
+                request_id=request_id,
+                response_headers=dict(response.headers),
+            ) from exc
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

reconify_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: reconify-python
+Version: 0.1.0
+Summary: Typed Python client for the Reconify Public API
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: bump2version>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Reconify Python SDK
+
+Typed synchronous and asynchronous clients for the Reconify Public API.
+
+## Installation
+
+```bash
+pip install reconify-python
+```
+
+## Quickstart
+
+```python
+from reconify import Reconify
+
+with Reconify(api_key="rk_...") as client:
+    sources = client.ledger.list_ledger_sources(limit=25)
+    for source in sources.sources or []:
+        print(source.id, source.name)
+```
+
+The key may also be supplied through `RECONIFY_API_KEY`. The default endpoint is
+`https://api.reconifyhq.com/v1`; pass `base_url="https://staging.example/v1"`
+for staging or self-hosted deployments. `/v1` is added when it is absent.
+
+## Async usage and pagination
+
+```python
+from reconify import AsyncReconify
+
+async with AsyncReconify() as client:
+    async for event in client.iter_events(limit=100):
+        print(event.id)
+```
+
+Cursor and offset iterators preserve opaque cursors and the server's page size.
+When an endpoint accepts both cursor and offset pagination, `after` takes
+precedence.
+
+Every list operation also has a natural iterator on the client, for example
+`client.iter_reconciliations(limit=100)` or
+`client.iter_wallet_transactions(after="cursor")`. The async equivalent is
+an async iterator. Iterators forward query parameters using keyword arguments,
+so they never expose transport details.
+
+## Errors and retries
+
+HTTP failures raise typed `ReconifyError` subclasses. Every HTTP error exposes
+`status_code`, `detail`, `code`, validation details, response headers, and the
+response `request_id` without including credentials or request bodies.
+
+429, 503, and transient HTTP transport failures such as timeouts are retried
+for safe methods with bounded exponential backoff and jitter. Mutating methods
+are not retried unless `RetryConfig(retry_unsafe_methods=True)` is supplied.
+Transaction ingestion retries must reuse each row's `idempotencyKey`.
+
+The client default timeout is 30 seconds. Individual operations can override
+it with `timeout=...`, including an `httpx.Timeout` object. Async operations
+also support normal `asyncio` cancellation, which is the Python equivalent of
+context cancellation in other SDKs.
+
+Use `raw=True` on any operation to receive status, headers, request ID, and raw
+body through `RawResponse`.
+
+## Test-session and ingestion headers
+
+Integrity ingestion and test-session submission accept
+`integrity_test_session=...`, which is sent as `X-Integrity-Test-Session`.
+Integrity batches support 1–500 events and ledger transaction batches support
+1–5000 transactions; the SDK does not truncate caller input.
+
+The SDK intentionally excludes reconciliation adjustment, evidence, lifecycle,
+report-item, and signoff operations. The retained reconciliation surface is
+integrity sources, reconciliation list/create/get, and all schedule operations.
+
+## API reference
+
+The public operation methods are grouped by API module. Request bodies use the
+typed Pydantic models exported from `reconify.models`; list query parameters use
+the OpenAPI names in snake_case. Every operation accepts `raw=True` and a
+per-request `timeout` override.
+
+| Module | Methods |
+| --- | --- |
+| Alerts | `list_alert_rules`, `put_alert_rule` |
+| Events | `list_events`, `get_event`, `reveal_event_field` |
+| Ingestion | `ingest_integrity_events`, `ingest_integrity_test_events` |
+| Issues | `list_issues`, `get_issue_summary`, `get_issue`, `update_issue`, `list_issue_deliveries`, `retry_issue_delivery`, `add_issue_note`, `resolve_issue` |
+| Ledger | `list_ledger_sources`, `create_ledger_source`, `delete_ledger_source`, `get_ledger_source`, `update_ledger_source`, `list_source_periods`, `list_transactions`, `ingest_transactions` |
+| Reconciliations | `list_integrity_sources_for_reconciliation`, `list_reconciliation_schedules`, `create_reconciliation_schedule`, `delete_reconciliation_schedule`, `get_reconciliation_schedule`, `update_reconciliation_schedule`, `list_reconciliations`, `create_reconciliation`, `get_reconciliation` |
+| Search | `search_integrity_resources` |
+| Setup | `list_setup_integrations`, `get_setup_integration`, `list_setup_sources`, `create_setup_source`, `get_setup_source`, `update_setup_source`, `disable_setup_source`, `create_test_session`, `get_test_session`, `get_test_session_result`, `retry_test_session`, `submit_test_session_events` |
+| Transactions | `list_wallet_transactions`, `get_wallet_transaction` |
+| Wallets | `list_wallets`, `get_wallet`, `get_wallet_balance` |
+
+## Build and deploy
+
+Build the distributable artifacts locally or in CI:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+The resulting wheel and source archive in `dist/` are ready for publication to
+an internal or public Python package registry. CI builds both artifacts after
+running lint, type checking, and tests.

reconify_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+reconify/__init__.py,sha256=zd4a21ozt8VkPdgPQO2PXRv_Wz2IepC-x4Q9g9FIufY,878
+reconify/client.py,sha256=2smGF9y6v7sVO1xXp5SYbXXaGFrD3o7Q30Zkc3z1iPg,8349
+reconify/errors.py,sha256=Dt9UVBSt34jL09AnYWRDKk0UEu70UpmDhQI_MyOzrkM,4185
+reconify/models.py,sha256=SBzHBV8Chd5BT0eFa-IbtCk8eYZI7-5eJLCB7yiuTCM,45483
+reconify/pagination.py,sha256=R0kJgeFYmuTujl9VEHCMEarTjp_J3aLuxEM_tRiruss,3486
+reconify/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reconify/transport.py,sha256=WFJ3zTjoaUd_PkV9JU3KaA-ahRc7fi0pY-iz9SezhIc,10709
+reconify/resources/__init__.py,sha256=XN-fcvMI5TsG8G1EnVq47NkUgAOWBvOd_k3u4JkmnRo,5325
+reconify/resources/alerts.py,sha256=hZ15beElYoGaPefFSlsU-NyswUwj92w-zjzC4QbTvvs,1605
+reconify/resources/base.py,sha256=qHZm6LuIPJmLTKAjj221QaWuUi0aorIa8GWeWB4qtDs,3279
+reconify/resources/events.py,sha256=tc-5Fkb9G59W9ee1r0Yd7Nv_Kn6FuMeNCoCiQ0T3qHk,2213
+reconify/resources/ingestion.py,sha256=7uzumDHPbiY-dPe4HPIZc250LqxMFA3Izm78s5iLC8E,2652
+reconify/resources/issues.py,sha256=ulTlQVcOtgPCthg5MLlxWpAe3u3MWvaJ2xP8CVPaznM,6113
+reconify/resources/ledger.py,sha256=I1ReJqEo-Qin5vvT126Y36YPaaXwk-DmuOGix2PkXm0,6391
+reconify/resources/reconciliations.py,sha256=uCZqG8tMiBz_pzgD0htdEx5aELL-F2XoTv8AyQHv98g,7458
+reconify/resources/search.py,sha256=CtRzVyD3fsYLWUtzNd7HA0S2JkNakg905-97JlLRHe8,885
+reconify/resources/setup.py,sha256=SxBXerZzQVB9Xkw17PLngQg8z5Z8S_zLYKNfyCFKn_k,9756
+reconify/resources/transactions.py,sha256=4pRd7MW9DFp9U_J-mBj3x_cYcMor8FlhdVia0OaeAC4,1678
+reconify/resources/wallets.py,sha256=R0dbzK5DpqvT54FmCkXXw0rcH3LepI22Pl94voC5e_Q,2261
+reconify_python-0.1.0.dist-info/METADATA,sha256=nyF8H5D8zRyeXJyuXDHCMKHAaJNj0u1b8WbcDAlvS0M,5328
+reconify_python-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+reconify_python-0.1.0.dist-info/licenses/LICENSE,sha256=q4Eqlx9sTPEY6DaOMuTjXAtVA7uEjxZkcvaJzcuYaIw,1065
+reconify_python-0.1.0.dist-info/RECORD,,

reconify_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

reconify_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reconify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.