reconify-python 0.1.0__tar.gz → 1.0.0__tar.gz

{reconify_python-0.1.0 → reconify_python-1.0.0}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.0
+current_version = 1.0.0
 commit = True
 tag = True
 tag_name = v{new_version}

reconify_python-1.0.0/.conductor/settings.toml

@@ -0,0 +1,18 @@
+"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
+
+[scripts]
+setup = "python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'"
+run_mode = "concurrent"
+
+[scripts.run.verify]
+command = ".venv/bin/python scripts/fetch_contract.py && .venv/bin/ruff check . && .venv/bin/mypy src && .venv/bin/pytest -q && .venv/bin/python -m build"
+icon = "check"
+default = true
+
+[scripts.run.sync-contract]
+command = ".venv/bin/python scripts/fetch_contract.py --latest && .venv/bin/python -m pytest -q tests/test_openapi_coverage.py"
+icon = "refresh-cw"
+
+[scripts.run.release-check]
+command = ".venv/bin/ruff check . && .venv/bin/mypy src && .venv/bin/pytest -q && .venv/bin/python -m build"
+icon = "package-check"

{reconify_python-0.1.0 → reconify_python-1.0.0}/.github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
           python-version: "3.12"
       - run: python -m pip install --upgrade pip
       - run: pip install ".[dev]"
+      - run: python scripts/fetch_contract.py
       - run: ruff check .
       - run: mypy src
       - run: pytest -q

reconify_python-1.0.0/.github/workflows/sync-contract.yml

@@ -0,0 +1,36 @@
+name: Sync public OpenAPI contract
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "23 6 * * 1"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install ".[dev]"
+      - run: python scripts/fetch_contract.py --latest
+      - run: python -m pytest -q tests/test_openapi_coverage.py
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q
+      - run: python -m build
+      - uses: peter-evans/create-pull-request@v7
+        with:
+          branch: automation/openapi-contract-sync
+          delete-branch: true
+          commit-message: "chore: sync public OpenAPI contract"
+          title: "chore: sync public OpenAPI contract"
+          body: |
+            This automated update was generated from the public Reconify OpenAPI
+            manifest. Review generated API models, examples, and migration notes before merging.

{reconify_python-0.1.0 → reconify_python-1.0.0}/.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 .mypy_cache/
 .ruff_cache/
 .venv/
+.contract/
 dist/
 build/
 *.egg-info/

reconify_python-1.0.0/.openapi-contract.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.0.0",
+  "sha256": "04170b7eda8a7bacef6591a7132b9a5cbdb62963af9ca6260e1948c1ee8233c1"
+}

reconify_python-1.0.0/AGENTS.md

@@ -0,0 +1,29 @@
+# Reconify Python SDK agent guide
+
+This repository publishes reconify-python, the typed synchronous and
+asynchronous client for the public Reconify /v1 API.
+
+## Contract authority
+
+The SaaS Go API owns the contract. Fetch the pinned public artifact with
+python scripts/fetch_contract.py, or update to the manifest version with
+python scripts/fetch_contract.py --latest.
+
+For local SaaS work, set RECONIFY_OPENAPI_SPEC to an explicit OpenAPI JSON
+file. Do not use sibling repositories or absolute workspace paths.
+
+The resource and transport layers are handwritten for Python ergonomics.
+tests/test_openapi_coverage.py is the contract boundary and must remain
+spec-driven. Keep Pydantic models aligned with the downloaded schemas.
+
+## Supported surface
+
+The SDK exposes metadata, events, ingestion, issues, and organization
+resources. Internal /business/v1 routes and the former ledger, wallet, setup,
+search, alert, and reconciliation surface are not public SDK APIs.
+
+## Verification
+
+Run ruff check ., mypy src, pytest -q, and python -m build before releasing.
+Keep credentials out of errors and logs, preserve request IDs, and update
+examples and migration notes when the public contract changes.

reconify_python-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0
+
+- Rebuilt the client for the current 13-operation public monitoring API.
+- Added metadata, organization, issue notes, and issue-linked event resources.
+- Removed the obsolete ledger, wallet, setup, search, alert, and reconciliation
+  surface.
+- Added pinned public OpenAPI synchronization and contract coverage checks.
+
+## 0.1.0
+
+- Initial typed Reconify Python SDK.
+- Added sync and async clients for the retained 50-operation API surface.
+- Excluded deep reconciliation adjustment, evidence, lifecycle, report-item,
+  and signoff operations.

reconify_python-1.0.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: reconify-python
+Version: 1.0.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 public Reconify v1 API.
+
+## Installation and quickstart
+
+```sh
+pip install reconify-python
+```
+
+```python
+from reconify import Reconify
+
+with Reconify(api_key="rk_...") as client:
+    events = client.events.list_events(limit=25)
+    for event in events.events:
+        print(event.id, event.status)
+```
+
+The API key may also come from `RECONIFY_API_KEY`. The default endpoint is
+`https://api.reconifyhq.com/v1`. `RECONIFY_API_URL` or `base_url` can select a
+staging or self-hosted endpoint, and URLs with or without `/v1` are accepted.
+
+## Public resources
+
+The client exposes metadata, events, ingestion, issues, and organization. The
+current public contract contains exactly 13 operations. Python methods use
+`snake_case` names and typed Pydantic v2 models from `reconify.models`.
+
+Sync and async clients provide cursor iterators:
+
+```python
+from reconify import AsyncReconify
+
+async with AsyncReconify() as client:
+    async for event in client.iter_events(limit=100):
+        print(event.id)
+```
+
+Every operation supports `raw=True` for `RawResponse` and per-request timeout
+through the `timeout` keyword. API errors expose status, detail, code,
+validation details, response headers, and request ID without including keys or
+request bodies. Safe methods retry bounded `429`, `503`, and transport failures
+by default; unsafe retries require `RetryConfig(retry_unsafe_methods=True)`.
+
+## Contract synchronization
+
+```sh
+python scripts/fetch_contract.py
+python scripts/fetch_contract.py --latest
+pytest -q tests/test_openapi_coverage.py
+```
+
+The default source is the public manifest at
+<https://docs.reconifyhq.com/openapi/manifest.json>. For local SaaS changes,
+set `RECONIFY_OPENAPI_SPEC` to an explicit OpenAPI JSON file. The SDK never
+depends on another checkout or an absolute workspace path.
+
+## Migration to 1.0.0
+
+Version `1.0.0` targets the current monitoring and issue-investigation API. The
+former ledger, wallet, setup, search, alert, and reconciliation methods are
+removed because they are not part of the public contract. See
+[UPGRADING.md](UPGRADING.md).
+
+## Build and release
+
+```sh
+ruff check .
+mypy src
+pytest -q
+python -m build
+```
+
+The release workflow publishes the built wheel to PyPI after a GitHub release.
+Additive contract changes require a minor SDK release; SDK fixes require a
+patch release; breaking public API changes require a new API version and SDK
+major release.

reconify_python-1.0.0/README.md

@@ -0,0 +1,78 @@
+# Reconify Python SDK
+
+Typed synchronous and asynchronous clients for the public Reconify v1 API.
+
+## Installation and quickstart
+
+```sh
+pip install reconify-python
+```
+
+```python
+from reconify import Reconify
+
+with Reconify(api_key="rk_...") as client:
+    events = client.events.list_events(limit=25)
+    for event in events.events:
+        print(event.id, event.status)
+```
+
+The API key may also come from `RECONIFY_API_KEY`. The default endpoint is
+`https://api.reconifyhq.com/v1`. `RECONIFY_API_URL` or `base_url` can select a
+staging or self-hosted endpoint, and URLs with or without `/v1` are accepted.
+
+## Public resources
+
+The client exposes metadata, events, ingestion, issues, and organization. The
+current public contract contains exactly 13 operations. Python methods use
+`snake_case` names and typed Pydantic v2 models from `reconify.models`.
+
+Sync and async clients provide cursor iterators:
+
+```python
+from reconify import AsyncReconify
+
+async with AsyncReconify() as client:
+    async for event in client.iter_events(limit=100):
+        print(event.id)
+```
+
+Every operation supports `raw=True` for `RawResponse` and per-request timeout
+through the `timeout` keyword. API errors expose status, detail, code,
+validation details, response headers, and request ID without including keys or
+request bodies. Safe methods retry bounded `429`, `503`, and transport failures
+by default; unsafe retries require `RetryConfig(retry_unsafe_methods=True)`.
+
+## Contract synchronization
+
+```sh
+python scripts/fetch_contract.py
+python scripts/fetch_contract.py --latest
+pytest -q tests/test_openapi_coverage.py
+```
+
+The default source is the public manifest at
+<https://docs.reconifyhq.com/openapi/manifest.json>. For local SaaS changes,
+set `RECONIFY_OPENAPI_SPEC` to an explicit OpenAPI JSON file. The SDK never
+depends on another checkout or an absolute workspace path.
+
+## Migration to 1.0.0
+
+Version `1.0.0` targets the current monitoring and issue-investigation API. The
+former ledger, wallet, setup, search, alert, and reconciliation methods are
+removed because they are not part of the public contract. See
+[UPGRADING.md](UPGRADING.md).
+
+## Build and release
+
+```sh
+ruff check .
+mypy src
+pytest -q
+python -m build
+```
+
+The release workflow publishes the built wheel to PyPI after a GitHub release.
+Additive contract changes require a minor SDK release; SDK fixes require a
+patch release; breaking public API changes require a new API version and SDK
+major release.

reconify_python-1.0.0/UPGRADING.md

@@ -0,0 +1,17 @@
+# Upgrading to 1.0.0
+
+The 1.0.0 client is rebuilt against the current public Reconify v1 contract.
+It removes methods that described private or retired ledger, wallet, setup,
+search, alert, and reconciliation routes.
+
+Use these resources:
+
+- metadata: API information and health
+- events: event listing, lookup, and issue-linked evidence
+- ingestion: monitoring event batches
+- issues: issue listing, lookup, assignment, notes, and linked data
+- organization: organization and member reads
+
+Python models use snake_case fields and preserve unknown enum values through
+tolerant string enums. Regenerate or refresh the models after downloading a
+new public contract version.

reconify_python-1.0.0/context7.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Reconify Python SDK",
+  "description": "Typed synchronous and asynchronous Python clients for the Reconify Public API.",
+  "folders": ["src"],
+  "excludeFolders": ["tests", "reports"],
+  "rules": [
+    "Use Reconify for synchronous code and AsyncReconify for asynchronous code.",
+    "Provide the API key with api_key or RECONIFY_API_KEY; configure staging or self-hosted deployments with base_url.",
+    "Treat pagination cursors as opaque. When an endpoint accepts both cursor and offset pagination, after takes precedence.",
+    "Safe methods retry 429, 503, and transient transport failures by default. Mutating methods require RetryConfig(retry_unsafe_methods=True) to opt into retries.",
+    "Reuse each row's idempotencyKey when retrying transaction ingestion.",
+    "Use raw=True when callers need status, headers, request IDs, and raw response bodies; use the per-request timeout override when needed."
+  ]
+}

{reconify_python-0.1.0 → reconify_python-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "reconify-python"
-version = "0.1.0"
+version = "1.0.0"
 description = "Typed Python client for the Reconify Public API"
 readme = "README.md"
 requires-python = ">=3.10"

reconify_python-1.0.0/scripts/fetch_contract.py

@@ -0,0 +1,65 @@
+"""Fetch and verify the pinned public OpenAPI contract."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.parse import urljoin
+from urllib.request import urlopen
+
+ROOT = Path(__file__).resolve().parents[1]
+PIN_PATH = ROOT / ".openapi-contract.json"
+DEFAULT_OUTPUT = ROOT / ".contract" / "reconify.openapi.json"
+DEFAULT_MANIFEST_URL = "https://docs.reconifyhq.com/openapi/manifest.json"
+
+
+def main() -> None:
+    output = Path(os.environ.get("RECONIFY_OPENAPI_SPEC", str(DEFAULT_OUTPUT)))
+    update_to_latest = "--latest" in sys.argv
+    if os.environ.get("RECONIFY_OPENAPI_SPEC"):
+        content = output.read_bytes()
+        if update_to_latest:
+            document = json.loads(content)
+            version = document.get("info", {}).get("version")
+            if not version:
+                raise SystemExit("Local OpenAPI contract has no info.version")
+            PIN_PATH.write_text(
+                json.dumps(
+                    {
+                        "version": version,
+                        "sha256": hashlib.sha256(content).hexdigest(),
+                    },
+                    indent=2,
+                )
+                + "\n"
+            )
+        print(f"Using local OpenAPI contract: {output}")
+        return
+
+    pinned = json.loads(PIN_PATH.read_text())
+    manifest_url = os.environ.get("RECONIFY_OPENAPI_MANIFEST_URL", DEFAULT_MANIFEST_URL)
+    with urlopen(manifest_url, timeout=30) as response:
+        manifest = json.loads(response.read())
+    version = manifest["contract_version"] if update_to_latest else pinned["version"]
+    artifact = manifest["versions"].get(version)
+    if artifact is None:
+        raise SystemExit(f"OpenAPI manifest has no version {version}")
+    if not update_to_latest and artifact["sha256"] != pinned["sha256"]:
+        raise SystemExit(f"OpenAPI manifest checksum changed for pinned version {version}")
+    with urlopen(urljoin(manifest_url, artifact["url"]), timeout=30) as response:
+        content = response.read()
+    digest = hashlib.sha256(content).hexdigest()
+    if update_to_latest:
+        PIN_PATH.write_text(json.dumps({"version": version, "sha256": digest}, indent=2) + "\n")
+    elif digest != pinned["sha256"]:
+        raise SystemExit(f"OpenAPI checksum mismatch: expected {pinned['sha256']}, got {digest}")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_bytes(content)
+    print(f"Fetched OpenAPI {version} to {output}")
+
+
+if __name__ == "__main__":
+    main()

{reconify_python-0.1.0 → reconify_python-1.0.0}/src/reconify/__init__.py

@@ -1,6 +1,6 @@
 """Typed clients for the Reconify Public API."""
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"
 
 from .client import AsyncReconify, Reconify
 from .errors import (

reconify_python-1.0.0/src/reconify/client.py

@@ -0,0 +1,157 @@
+"""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, iter_cursor_pages
+from .resources import (
+    ASYNC_RESOURCE_CLASSES,
+    SYNC_RESOURCE_CLASSES,
+    AsyncEvents,
+    AsyncIngestion,
+    AsyncIssues,
+    AsyncMetadata,
+    AsyncOrganization,
+    Events,
+    Ingestion,
+    Issues,
+    Metadata,
+    Organization,
+)
+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; set api_key or RECONIFY_API_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."""
+
+    metadata: Metadata
+    events: Events
+    ingestion: Ingestion
+    issues: Issues
+    organization: Organization
+
+    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_issue_events(self, issue_id: str, **query: Any) -> Iterator[Any]:
+        return iter_cursor_pages(
+            lambda params: self.events.list_issue_events(issue_id, **params),
+            item_field="events",
+            query=query,
+        )
+
+
+class AsyncReconify:
+    """Asynchronous typed Reconify API client."""
+
+    metadata: AsyncMetadata
+    events: AsyncEvents
+    ingestion: AsyncIngestion
+    issues: AsyncIssues
+    organization: AsyncOrganization
+
+    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_issue_events(self, issue_id: str, **query: Any) -> AsyncIterator[Any]:
+        return aiter_cursor_pages(
+            lambda params: self.events.list_issue_events(issue_id, **params),
+            item_field="events",
+            query=query,
+        )