Align Python SDK v3.0.0 with Rust reference SDK

Brings the Python SDK to full parity with the prod Rust reference
implementation: base URL, response headers, all types/resources, and
file download support. Verified against the live API.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mivertowski

CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-04-08
+
+### Changed
+
+- **Breaking**: Base URL changed from `https://api.vynco.ch` to `https://vynco.ch/api` — matches the Rust reference SDK
+- **Breaking**: Response header names changed — `X-Rate-Limit-Limit` → `X-RateLimit-Limit` (matching Rust SDK)
+- **Breaking**: `DashboardResponse.data` model changed — `DataCompleteness` fields updated to `total_companies`, `enriched_companies`, `companies_with_industry`, `companies_with_geo`, `total_persons`, `total_changes`, `total_sogc_publications`
+- **Breaking**: `PipelineStatus` model changed — `name` → `id`, `records_processed` → `items_processed`, `duration_seconds` removed
+- **Breaking**: `AuditorTenureStats` model rewritten — fields now `total_tracked`, `current_auditors`, `tenures_over_10_years`, `tenures_over_7_years`, `avg_tenure_years`, `longest_tenure`
+- **Breaking**: `exports.download()` and `graph.export()` now return `ExportFile` dataclass (with `bytes`, `content_type`, `filename`, `meta`) instead of `Response[bytes]`
+- **Company** model expanded with 25+ new fields: `currency`, `purpose`, `founding_date`, `registration_date`, `deletion_date`, `legal_seat`, `municipality`, `data_source`, `enrichment_level`, `address_street`, `address_house_number`, `address_zip_code`, `address_city`, `address_canton`, `website`, `sub_industry`, `employee_count`, `auditor_name`, `latitude`, `longitude`, `geo_precision`, `noga_code`, `sanctions_hit`, `last_screened_at`, `is_finma_regulated`, `ehraid`, `chid`, `cantonal_excerpt_url`, `old_names`, `translations`
+- `companies.list()` now accepts `status`, `legal_form`, `capital_min`, `capital_max`, `auditor_category`, `sort_by`, `sort_desc` filter parameters
+
+### Added
+
+- **`ResponseMeta.rate_limit_remaining`** — remaining requests in rate limit window (`X-RateLimit-Remaining`)
+- **`ResponseMeta.rate_limit_reset`** — Unix timestamp when rate limit resets (`X-RateLimit-Reset`)
+- **`ExportFile`** dataclass — returned by file download endpoints (`exports.download()`, `graph.export()`, `companies.export_excel()`)
+- **`companies.get_full(uid)`** — full company details with persons, changes, relationships
+- **`companies.classification(uid)`** — industry classification
+- **`companies.structure(uid)`** — corporate structure (head offices, branches, M&A)
+- **`companies.acquisitions(uid)`** — M&A relationships
+- **`companies.notes(uid)`**, **`create_note()`**, **`update_note()`**, **`delete_note()`** — company notes CRUD
+- **`companies.tags(uid)`**, **`create_tag()`**, **`delete_tag()`**, **`all_tags()`** — company tags CRUD
+- **`companies.export_excel()`** — Excel/CSV export of companies
+- **`persons.search(q, page, page_size)`** — search persons by name
+- **`persons.get(id)`** — get person detail with all roles
+- **`teams.join(token)`** — join a team via invitation token
+- **`dossiers.generate(uid)`** — generate a dossier for a company
+- New typed models: `CompanyFullResponse`, `PersonEntry`, `ChangeEntry`, `RelationshipEntry`, `Classification`, `CorporateStructure`, `RelatedCompanyEntry`, `Acquisition`, `Note`, `Tag`, `TagSummary`, `PersonSearchResult`, `PersonDetail`, `PersonRoleDetail`, `JoinTeamResponse`, `LongestTenure`
+- Retry logic now respects `X-RateLimit-Reset` header in addition to `Retry-After`
+
 ## [2.0.0] - 2026-03-31
 
 ### Changed

README.md

@@ -29,6 +29,10 @@ print(f"Found {result.data.total} companies")
 company = client.companies.get("CHE-105.805.080")
 print(f"{company.data.name}: {company.data.legal_form}")
 
+# Full company details with persons, changes, relationships
+full = client.companies.get_full("CHE-105.805.080")
+print(f"Board: {len(full.data.persons)} persons")
+
 # Sanctions screening
 screening = client.screening.screen(name="Suspicious Corp")
 print(f"Risk: {screening.data.risk_level} ({screening.data.hit_count} hits)")
@@ -55,12 +59,12 @@ async def main():
 
 ## API Coverage
 
-18 resource modules covering 69 endpoints:
+18 resource modules covering 90+ endpoints:
 
 | Resource | Methods |
 |----------|---------|
 | `client.health` | `check` |
-| `client.companies` | `list`, `get`, `count`, `events`, `statistics`, `compare`, `news`, `reports`, `relationships`, `hierarchy`, `fingerprint`, `nearby` |
+| `client.companies` | `list`, `get`, `get_full`, `count`, `events`, `statistics`, `compare`, `news`, `reports`, `relationships`, `hierarchy`, `classification`, `fingerprint`, `structure`, `acquisitions`, `nearby`, `notes`, `create_note`, `update_note`, `delete_note`, `tags`, `create_tag`, `delete_tag`, `all_tags`, `export_excel` |
 | `client.auditors` | `history`, `tenures` |
 | `client.dashboard` | `get` |
 | `client.screening` | `screen` |
@@ -71,11 +75,11 @@ async def main():
 | `client.api_keys` | `list`, `create`, `revoke` |
 | `client.credits` | `balance`, `usage`, `history` |
 | `client.billing` | `create_checkout`, `create_portal` |
-| `client.teams` | `me`, `create`, `members`, `invite_member`, `update_member_role`, `remove_member`, `billing_summary` |
+| `client.teams` | `me`, `create`, `members`, `invite_member`, `update_member_role`, `remove_member`, `billing_summary`, `join` |
 | `client.changes` | `list`, `by_company`, `statistics` |
-| `client.persons` | `board_members` |
+| `client.persons` | `board_members`, `search`, `get` |
 | `client.analytics` | `cantons`, `auditors`, `cluster`, `anomalies`, `rfm_segments`, `cohorts`, `candidates` |
-| `client.dossiers` | `create`, `list`, `get`, `delete` |
+| `client.dossiers` | `create`, `list`, `get`, `delete`, `generate` |
 | `client.graph` | `get`, `export`, `analyze` |
 
 ## Response Metadata
@@ -85,21 +89,23 @@ Every response includes header metadata for credit tracking and rate limiting:
 ```python
 resp = client.companies.get("CHE-105.805.080")
 
-print(f"Request ID: {resp.meta.request_id}")          # X-Request-Id
-print(f"Credits used: {resp.meta.credits_used}")       # X-Credits-Used
+print(f"Request ID: {resp.meta.request_id}")               # X-Request-Id
+print(f"Credits used: {resp.meta.credits_used}")            # X-Credits-Used
 print(f"Credits remaining: {resp.meta.credits_remaining}")  # X-Credits-Remaining
-print(f"Rate limit: {resp.meta.rate_limit_limit}")     # X-Rate-Limit-Limit
-print(f"Data source: {resp.meta.data_source}")         # X-Data-Source
+print(f"Rate limit: {resp.meta.rate_limit_limit}")          # X-RateLimit-Limit
+print(f"Rate remaining: {resp.meta.rate_limit_remaining}")  # X-RateLimit-Remaining
+print(f"Rate reset: {resp.meta.rate_limit_reset}")          # X-RateLimit-Reset
+print(f"Data source: {resp.meta.data_source}")              # X-Data-Source
 ```
 
 ## Configuration
 
 ```python
 client = vynco.Client(
     api_key="vc_live_xxx",
-    base_url="https://api.vynco.ch",  # default
-    timeout=30.0,                      # seconds, default
-    max_retries=2,                     # default, retries on 429/5xx
+    base_url="https://vynco.ch/api",  # default
+    timeout=30.0,                     # seconds, default
+    max_retries=2,                    # default, retries on 429/5xx
 )
 ```
 
@@ -114,7 +120,7 @@ client = vynco.Client()  # reads from VYNCO_API_KEY
 ```
 
 The client automatically retries on HTTP 429 (rate limited) and 5xx (server error) with
-exponential backoff (500ms x 2^attempt). It respects the `Retry-After` header when present.
+exponential backoff (500ms x 2^attempt). It respects the `Retry-After` and `X-RateLimit-Reset` headers when present.
 
 ## Error Handling
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vynco"
-version = "2.0.0"
+version = "3.0.0"
 description = "Python SDK for the VynCo Swiss Corporate Intelligence API"
 readme = "README.md"
 license = "Apache-2.0"

src/vynco/__init__.py

@@ -18,8 +18,9 @@
     ValidationError,
     VyncoError,
 )
-from vynco._response import Response, ResponseMeta
+from vynco._response import ExportFile, Response, ResponseMeta
 from vynco.types import (
+    Acquisition,
     AddCompaniesResponse,
     AiSearchResponse,
     AnomalyResponse,
@@ -32,15 +33,19 @@
     BillingSummary,
     BoardMember,
     CantonDistribution,
+    ChangeEntry,
     ChangeStatistics,
+    Classification,
     ClusterResponse,
     CohortResponse,
     Company,
     CompanyChange,
     CompanyCount,
+    CompanyFullResponse,
     CompanyReport,
     CompanyStatistics,
     CompareResponse,
+    CorporateStructure,
     CreateWebhookResponse,
     CreditBalance,
     CreditHistory,
@@ -60,17 +65,27 @@
     HealthResponse,
     HierarchyResponse,
     Invitation,
+    JoinTeamResponse,
     NearbyCompany,
     NetworkAnalysisResponse,
     NewsItem,
+    Note,
     PaginatedResponse,
+    PersonDetail,
+    PersonEntry,
+    PersonRoleDetail,
+    PersonSearchResult,
+    RelatedCompanyEntry,
     Relationship,
+    RelationshipEntry,
     RfmSegmentsResponse,
     RiskFactor,
     RiskScoreResponse,
     ScreeningHit,
     ScreeningResponse,
     SessionUrl,
+    Tag,
+    TagSummary,
     Team,
     TeamMember,
     TestDeliveryResponse,
@@ -103,6 +118,7 @@
     # Response
     "Response",
     "ResponseMeta",
+    "ExportFile",
     # Types
     "PaginatedResponse",
     "HealthResponse",
@@ -117,6 +133,17 @@
     "HierarchyResponse",
     "Fingerprint",
     "NearbyCompany",
+    "Classification",
+    "CorporateStructure",
+    "RelatedCompanyEntry",
+    "Acquisition",
+    "Note",
+    "Tag",
+    "TagSummary",
+    "CompanyFullResponse",
+    "PersonEntry",
+    "ChangeEntry",
+    "RelationshipEntry",
     "AuditorHistoryResponse",
     "AuditorTenure",
     "AuditorMarketShare",
@@ -148,9 +175,13 @@
     "TeamMember",
     "Invitation",
     "BillingSummary",
+    "JoinTeamResponse",
     "CompanyChange",
     "ChangeStatistics",
     "BoardMember",
+    "PersonSearchResult",
+    "PersonDetail",
+    "PersonRoleDetail",
     "CantonDistribution",
     "ClusterResponse",
     "AnomalyResponse",

src/vynco/_base_client.py

@@ -14,7 +14,7 @@
     ServerError,
     VyncoError,
 )
-from vynco._response import Response, ResponseMeta
+from vynco._response import ExportFile, Response, ResponseMeta
 
 T = TypeVar("T")
 
@@ -41,7 +41,9 @@ def _parse_meta(headers: httpx.Headers) -> ResponseMeta:
         request_id=headers.get("X-Request-Id"),
         credits_used=_parse_int(headers.get("X-Credits-Used")),
         credits_remaining=_parse_int(headers.get("X-Credits-Remaining")),
-        rate_limit_limit=_parse_int(headers.get("X-Rate-Limit-Limit")),
+        rate_limit_limit=_parse_int(headers.get("X-RateLimit-Limit")),
+        rate_limit_remaining=_parse_int(headers.get("X-RateLimit-Remaining")),
+        rate_limit_reset=_parse_int(headers.get("X-RateLimit-Reset")),
         data_source=headers.get("X-Data-Source"),
     )
 
@@ -142,10 +144,10 @@ def _url(self, path: str) -> str:
     def _retry_delay(self, attempt: int, headers: httpx.Headers | None = None) -> float:
         """Compute retry delay with exponential backoff, respecting Retry-After."""
         if headers:
-            retry_after = headers.get("Retry-After")
+            retry_after = headers.get("Retry-After") or headers.get("X-RateLimit-Reset")
             if retry_after:
                 try:
-                    return float(retry_after)
+                    return min(float(retry_after), 60.0)
                 except ValueError:
                     pass
         return 0.5 * float(2**attempt)
@@ -187,3 +189,25 @@ def _handle_empty_response(self, resp: httpx.Response) -> ResponseMeta:
                 body = {"detail": resp.text, "status": resp.status_code}
             raise _map_error(resp.status_code, body)
         return meta
+
+    def _handle_bytes_response(self, resp: httpx.Response) -> ExportFile:
+        meta = _parse_meta(resp.headers)
+        if not resp.is_success:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"detail": resp.text, "status": resp.status_code}
+            raise _map_error(resp.status_code, body)
+
+        content_type = resp.headers.get("content-type", "application/octet-stream")
+        filename = ""
+        disposition = resp.headers.get("content-disposition", "")
+        if "filename=" in disposition:
+            filename = disposition.split("filename=")[1].strip('"')
+
+        return ExportFile(
+            meta=meta,
+            bytes=resp.content,
+            content_type=content_type,
+            filename=filename,
+        )

src/vynco/_client.py

@@ -7,7 +7,7 @@
 
 from vynco._base_client import BaseClientConfig
 from vynco._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
-from vynco._response import Response, ResponseMeta
+from vynco._response import ExportFile, Response, ResponseMeta
 from vynco.resources.ai import Ai, AsyncAi
 from vynco.resources.analytics import Analytics, AsyncAnalytics
 from vynco.resources.api_keys import ApiKeys, AsyncApiKeys
@@ -138,6 +138,17 @@ async def _request_empty(
         resp = await self._request(method, path, params=params, json=json)
         return self._handle_empty_response(resp)
 
+    async def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> ExportFile:
+        resp = await self._request(method, path, params=params, json=json)
+        return self._handle_bytes_response(resp)
+
     async def close(self) -> None:
         await self._http.aclose()
 
@@ -257,6 +268,17 @@ def _request_empty(
         resp = self._request(method, path, params=params, json=json)
         return self._handle_empty_response(resp)
 
+    def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> ExportFile:
+        resp = self._request(method, path, params=params, json=json)
+        return self._handle_bytes_response(resp)
+
     def close(self) -> None:
         self._http.close()
 

src/vynco/_constants.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-DEFAULT_BASE_URL = "https://api.vynco.ch"
+DEFAULT_BASE_URL = "https://vynco.ch/api"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 2
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"

src/vynco/_response.py

@@ -20,10 +20,16 @@ class ResponseMeta:
     """Remaining credit balance after this request (X-Credits-Remaining)."""
 
     rate_limit_limit: int | None = None
-    """Maximum requests per minute for the current tier (X-Rate-Limit-Limit)."""
+    """Maximum requests per minute for the current tier (X-RateLimit-Limit)."""
+
+    rate_limit_remaining: int | None = None
+    """Remaining requests in the current rate limit window (X-RateLimit-Remaining)."""
+
+    rate_limit_reset: int | None = None
+    """Unix timestamp when the rate limit window resets (X-RateLimit-Reset)."""
 
     data_source: str | None = None
-    """Data source for OGD compliance (X-Data-Source): "Zefix" or "LINDAS"."""
+    """Data source attribution (X-Data-Source)."""
 
 
 @dataclass
@@ -32,3 +38,13 @@ class Response(Generic[T]):
 
     data: T
     meta: ResponseMeta = field(default_factory=ResponseMeta)
+
+
+@dataclass
+class ExportFile:
+    """Downloaded export file with raw bytes and metadata."""
+
+    meta: ResponseMeta
+    bytes: bytes
+    content_type: str
+    filename: str