vynco 2.0.0__py3-none-any.whl

vynco/__init__.py

@@ -0,0 +1,166 @@
+"""VynCo Python SDK — Python client for the VynCo Swiss Corporate Intelligence API."""
+
+from __future__ import annotations
+
+from vynco._client import AsyncClient, Client
+from vynco._constants import __version__
+from vynco._errors import (
+    AuthenticationError,
+    ConfigError,
+    ConflictError,
+    DeserializationError,
+    ForbiddenError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    ValidationError,
+    VyncoError,
+)
+from vynco._response import Response, ResponseMeta
+from vynco.types import (
+    AddCompaniesResponse,
+    AiSearchResponse,
+    AnomalyResponse,
+    ApiKey,
+    ApiKeyCreated,
+    AuditCandidate,
+    AuditorHistoryResponse,
+    AuditorMarketShare,
+    AuditorTenure,
+    BillingSummary,
+    BoardMember,
+    CantonDistribution,
+    ChangeStatistics,
+    ClusterResponse,
+    CohortResponse,
+    Company,
+    CompanyChange,
+    CompanyCount,
+    CompanyReport,
+    CompanyStatistics,
+    CompareResponse,
+    CreateWebhookResponse,
+    CreditBalance,
+    CreditHistory,
+    CreditLedgerEntry,
+    CreditUsage,
+    DashboardResponse,
+    Dossier,
+    DossierResponse,
+    DossierSummary,
+    EventListResponse,
+    ExportDownload,
+    ExportJob,
+    Fingerprint,
+    GraphLink,
+    GraphNode,
+    GraphResponse,
+    HealthResponse,
+    HierarchyResponse,
+    Invitation,
+    NearbyCompany,
+    NetworkAnalysisResponse,
+    NewsItem,
+    PaginatedResponse,
+    Relationship,
+    RfmSegmentsResponse,
+    RiskFactor,
+    RiskScoreResponse,
+    ScreeningHit,
+    ScreeningResponse,
+    SessionUrl,
+    Team,
+    TeamMember,
+    TestDeliveryResponse,
+    Watchlist,
+    WatchlistCompaniesResponse,
+    WatchlistSummary,
+    WebhookDelivery,
+    WebhookSubscription,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "AsyncClient",
+    "Client",
+    # Errors
+    "VyncoError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "ConfigError",
+    "DeserializationError",
+    # Response
+    "Response",
+    "ResponseMeta",
+    # Types
+    "PaginatedResponse",
+    "HealthResponse",
+    "Company",
+    "CompanyCount",
+    "CompanyStatistics",
+    "EventListResponse",
+    "CompareResponse",
+    "NewsItem",
+    "CompanyReport",
+    "Relationship",
+    "HierarchyResponse",
+    "Fingerprint",
+    "NearbyCompany",
+    "AuditorHistoryResponse",
+    "AuditorTenure",
+    "AuditorMarketShare",
+    "DashboardResponse",
+    "ScreeningResponse",
+    "ScreeningHit",
+    "Watchlist",
+    "WatchlistSummary",
+    "WatchlistCompaniesResponse",
+    "AddCompaniesResponse",
+    "WebhookSubscription",
+    "CreateWebhookResponse",
+    "TestDeliveryResponse",
+    "WebhookDelivery",
+    "ExportJob",
+    "ExportDownload",
+    "DossierResponse",
+    "AiSearchResponse",
+    "RiskScoreResponse",
+    "RiskFactor",
+    "ApiKey",
+    "ApiKeyCreated",
+    "CreditBalance",
+    "CreditUsage",
+    "CreditHistory",
+    "CreditLedgerEntry",
+    "SessionUrl",
+    "Team",
+    "TeamMember",
+    "Invitation",
+    "BillingSummary",
+    "CompanyChange",
+    "ChangeStatistics",
+    "BoardMember",
+    "CantonDistribution",
+    "ClusterResponse",
+    "AnomalyResponse",
+    "RfmSegmentsResponse",
+    "CohortResponse",
+    "AuditCandidate",
+    "Dossier",
+    "DossierSummary",
+    "GraphResponse",
+    "GraphNode",
+    "GraphLink",
+    "NetworkAnalysisResponse",
+]

vynco/_base_client.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import os
+from typing import Any, TypeVar, get_args, get_origin
+
+import httpx
+from pydantic import BaseModel
+
+from vynco._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, __version__
+from vynco._errors import (
+    STATUS_ERROR_MAP,
+    ConfigError,
+    DeserializationError,
+    ServerError,
+    VyncoError,
+)
+from vynco._response import Response, ResponseMeta
+
+T = TypeVar("T")
+
+_PARAM_RENAME = {"query": "search", "change_type": "type"}
+
+
+def _build_params(kwargs: dict[str, Any]) -> dict[str, str]:
+    """Build query parameters from keyword arguments, dropping None values."""
+    params: dict[str, str] = {}
+    for key, value in kwargs.items():
+        if key == "self" or value is None:
+            continue
+        wire_key = _PARAM_RENAME.get(key, key)
+        # Convert snake_case to camelCase for the wire
+        parts = wire_key.split("_")
+        camel = parts[0] + "".join(p.capitalize() for p in parts[1:])
+        params[camel] = str(value).lower() if isinstance(value, bool) else str(value)
+    return params
+
+
+def _parse_meta(headers: httpx.Headers) -> ResponseMeta:
+    """Extract metadata from API response headers."""
+    return 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")),
+        data_source=headers.get("X-Data-Source"),
+    )
+
+
+def _parse_int(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _map_error(status_code: int, body: dict[str, Any]) -> VyncoError:
+    """Map an HTTP status code and response body to a typed error."""
+    detail = body.get("detail", "")
+    message = body.get("message", "")
+    status = body.get("status", status_code)
+
+    error_cls = STATUS_ERROR_MAP.get(status_code)
+    if error_cls:
+        return error_cls(detail=detail, message=message, status=status)
+    if status_code >= 500:
+        return ServerError(detail=detail, message=message, status=status)
+    return ServerError(detail=detail or f"HTTP {status_code}", message=message, status=status)
+
+
+def _deserialize(data: Any, response_type: type[T]) -> T:
+    """Deserialize JSON data into the given type."""
+    origin = get_origin(response_type)
+    args = get_args(response_type)
+
+    # list[X]
+    if origin is list and args:
+        item_type = args[0]
+        items: list[Any]
+        if isinstance(data, list):
+            items = data
+        elif isinstance(data, dict):
+            # Try "data" key, then first array-valued key
+            maybe = data.get("data")
+            if isinstance(maybe, list):
+                items = maybe
+            else:
+                for val in data.values():
+                    if isinstance(val, list):
+                        items = val
+                        break
+                else:
+                    items = [data]
+        else:
+            items = [data]
+        if issubclass(item_type, BaseModel):
+            return [item_type.model_validate(item) for item in items]  # type: ignore[return-value]
+        return items  # type: ignore[return-value]
+
+    # Pydantic model (including generics like PaginatedResponse[Company])
+    if isinstance(response_type, type) and issubclass(response_type, BaseModel):
+        return response_type.model_validate(data)
+    if origin and args and isinstance(origin, type) and issubclass(origin, BaseModel):
+        # Generic model like PaginatedResponse[Company]
+        concrete = response_type  # Already parameterized
+        if isinstance(concrete, type) and issubclass(concrete, BaseModel):
+            return concrete.model_validate(data)
+        # For runtime generics, we need the origin class
+        return origin.model_validate(data)  # type: ignore[no-any-return]
+
+    # dict or other simple types
+    return data  # type: ignore[no-any-return]
+
+
+class BaseClientConfig:
+    """Shared configuration for async and sync clients."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("VYNCO_API_KEY", "")
+        if not self.api_key:
+            raise ConfigError("API key must not be empty. Pass api_key or set VYNCO_API_KEY.")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"vynco-python/{__version__}",
+        }
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    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")
+            if retry_after:
+                try:
+                    return float(retry_after)
+                except ValueError:
+                    pass
+        return 0.5 * float(2**attempt)
+
+    def _should_retry(self, status_code: int) -> bool:
+        return status_code == 429 or status_code >= 500
+
+    def _handle_response(self, resp: httpx.Response, response_type: type[T]) -> Response[T]:
+        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)
+
+        if resp.status_code == 204 or not resp.content:
+            return Response(data=None, meta=meta)  # type: ignore[arg-type]
+
+        try:
+            data = resp.json()
+        except Exception as e:
+            raise DeserializationError(detail=f"Failed to parse JSON: {e}") from e
+
+        try:
+            parsed = _deserialize(data, response_type)
+        except Exception as e:
+            raise DeserializationError(detail=f"Failed to deserialize response: {e}") from e
+
+        return Response(data=parsed, meta=meta)
+
+    def _handle_empty_response(self, resp: httpx.Response) -> ResponseMeta:
+        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)
+        return meta

vynco/_client.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TypeVar
+
+import httpx
+
+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.resources.ai import Ai, AsyncAi
+from vynco.resources.analytics import Analytics, AsyncAnalytics
+from vynco.resources.api_keys import ApiKeys, AsyncApiKeys
+from vynco.resources.auditors import AsyncAuditors, Auditors
+from vynco.resources.billing import AsyncBilling, Billing
+from vynco.resources.changes import AsyncChanges, Changes
+from vynco.resources.companies import AsyncCompanies, Companies
+from vynco.resources.credits import AsyncCredits, Credits
+from vynco.resources.dashboard import AsyncDashboard, Dashboard
+from vynco.resources.dossiers import AsyncDossiers, Dossiers
+from vynco.resources.exports import AsyncExports, Exports
+from vynco.resources.graph import AsyncGraph, Graph
+from vynco.resources.health import AsyncHealth, Health
+from vynco.resources.persons import AsyncPersons, Persons
+from vynco.resources.screening import AsyncScreening, Screening
+from vynco.resources.teams import AsyncTeams, Teams
+from vynco.resources.watchlists import AsyncWatchlists, Watchlists
+from vynco.resources.webhooks import AsyncWebhooks, Webhooks
+
+T = TypeVar("T")
+
+
+class AsyncClient(BaseClientConfig):
+    """Async client for the VynCo API.
+
+    Uses httpx.AsyncClient under the hood. Supports ``async with`` for
+    automatic cleanup.
+
+    Example::
+
+        async with vynco.AsyncClient("vc_live_xxx") as client:
+            result = await client.companies.list(query="Novartis")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = httpx.AsyncClient(
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        self.health = AsyncHealth(self)
+        self.companies = AsyncCompanies(self)
+        self.auditors = AsyncAuditors(self)
+        self.dashboard = AsyncDashboard(self)
+        self.screening = AsyncScreening(self)
+        self.watchlists = AsyncWatchlists(self)
+        self.webhooks = AsyncWebhooks(self)
+        self.exports = AsyncExports(self)
+        self.ai = AsyncAi(self)
+        self.api_keys = AsyncApiKeys(self)
+        self.credits = AsyncCredits(self)
+        self.billing = AsyncBilling(self)
+        self.teams = AsyncTeams(self)
+        self.changes = AsyncChanges(self)
+        self.persons = AsyncPersons(self)
+        self.analytics = AsyncAnalytics(self)
+        self.dossiers = AsyncDossiers(self)
+        self.graph = AsyncGraph(self)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request with retry logic."""
+        url = self._url(path)
+        last_exc: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = await self._http.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                )
+            except httpx.HTTPError as e:
+                last_exc = e
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._retry_delay(attempt))
+                    continue
+                raise
+
+            if self._should_retry(resp.status_code) and attempt < self.max_retries:
+                delay = self._retry_delay(attempt, resp.headers)
+                await asyncio.sleep(delay)
+                continue
+
+            return resp
+
+        raise last_exc  # type: ignore[misc]
+
+    async def _request_model(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+        response_type: type[T],
+    ) -> Response[T]:
+        resp = await self._request(method, path, params=params, json=json)
+        return self._handle_response(resp, response_type)
+
+    async def _request_empty(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> ResponseMeta:
+        resp = await self._request(method, path, params=params, json=json)
+        return self._handle_empty_response(resp)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+class Client(BaseClientConfig):
+    """Sync client for the VynCo API.
+
+    Uses httpx.Client under the hood. Supports ``with`` for automatic cleanup.
+
+    Example::
+
+        with vynco.Client("vc_live_xxx") as client:
+            result = client.companies.list(query="Novartis")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = httpx.Client(
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        self.health = Health(self)
+        self.companies = Companies(self)
+        self.auditors = Auditors(self)
+        self.dashboard = Dashboard(self)
+        self.screening = Screening(self)
+        self.watchlists = Watchlists(self)
+        self.webhooks = Webhooks(self)
+        self.exports = Exports(self)
+        self.ai = Ai(self)
+        self.api_keys = ApiKeys(self)
+        self.credits = Credits(self)
+        self.billing = Billing(self)
+        self.teams = Teams(self)
+        self.changes = Changes(self)
+        self.persons = Persons(self)
+        self.analytics = Analytics(self)
+        self.dossiers = Dossiers(self)
+        self.graph = Graph(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request with retry logic."""
+        import time
+
+        url = self._url(path)
+        last_exc: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self._http.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                )
+            except httpx.HTTPError as e:
+                last_exc = e
+                if attempt < self.max_retries:
+                    time.sleep(self._retry_delay(attempt))
+                    continue
+                raise
+
+            if self._should_retry(resp.status_code) and attempt < self.max_retries:
+                delay = self._retry_delay(attempt, resp.headers)
+                time.sleep(delay)
+                continue
+
+            return resp
+
+        raise last_exc  # type: ignore[misc]
+
+    def _request_model(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+        response_type: type[T],
+    ) -> Response[T]:
+        resp = self._request(method, path, params=params, json=json)
+        return self._handle_response(resp, response_type)
+
+    def _request_empty(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json: Any = None,
+    ) -> ResponseMeta:
+        resp = self._request(method, path, params=params, json=json)
+        return self._handle_empty_response(resp)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

vynco/_constants.py

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

vynco/_errors.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+
+class VyncoError(Exception):
+    """Base exception for all VynCo SDK errors."""
+
+    def __init__(self, detail: str = "", message: str = "", status: int = 0) -> None:
+        self.detail = detail or message
+        self.message = message or detail
+        self.status = status
+        super().__init__(self.detail)
+
+
+class AuthenticationError(VyncoError):
+    """401 — Invalid or missing API key."""
+
+
+class InsufficientCreditsError(VyncoError):
+    """402 — Not enough credits for this operation."""
+
+
+class ForbiddenError(VyncoError):
+    """403 — Insufficient permissions."""
+
+
+class NotFoundError(VyncoError):
+    """404 — Resource not found."""
+
+
+class ValidationError(VyncoError):
+    """400/422 — Invalid request parameters."""
+
+
+class RateLimitError(VyncoError):
+    """429 — Too many requests."""
+
+
+class ConflictError(VyncoError):
+    """409 — Request conflicts with existing state."""
+
+
+class ServerError(VyncoError):
+    """5xx — Server-side error."""
+
+
+class ServiceUnavailableError(ServerError):
+    """503 — API temporarily unavailable."""
+
+
+class ConfigError(VyncoError):
+    """Client misconfiguration."""
+
+
+class DeserializationError(VyncoError):
+    """Failed to parse API response."""
+
+
+STATUS_ERROR_MAP: dict[int, type[VyncoError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}