threecommon 0.1.0__py3-none-any.whl

threecommon/client.py

@@ -0,0 +1,184 @@
+"""SDK clients: [ThreeCommon][] (sync) and [AsyncThreeCommon][] (async).
+
+Construct once per process; both classes are safe to share across threads and
+tasks. Each instance owns one underlying ``httpx`` client unless you supply
+your own via the ``http_client`` / ``async_http_client`` kwarg.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+from threecommon._core.http_client import (
+    AsyncHTTPClient,
+    HTTPClient,
+    HTTPClientOptions,
+)
+from threecommon._core.retry import RetryPolicy
+from threecommon._core.telemetry import Telemetry
+from threecommon.config import RetryDelay, resolve_config
+from threecommon.events.service import AsyncEventsService, EventsService
+from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
+
+if TYPE_CHECKING:  # pragma: no cover
+    import logging
+
+    import httpx
+
+
+class ThreeCommon:
+    """Synchronous entry point.
+
+    Construct with at minimum an API key, then call any resource method.
+    Closing is optional but recommended for short-lived scripts:
+
+        client = ThreeCommon(api_key="3co_...")
+        try:
+            result = client.events.list()
+        finally:
+            client.close()
+
+    Or use as a context manager:
+
+        with ThreeCommon(api_key="3co_...") as client:
+            result = client.events.list()
+    """
+
+    events: EventsService
+    """Events resource — ``GET /v1/events``, ``GET /v1/events/{id}``, ``PATCH /v1/events/{id}``."""
+
+    invoices: InvoicesService
+    """Invoices resource — list, retrieve, create, update, finalize, void, record_payment."""
+
+    _http: HTTPClient
+    _telemetry: Telemetry
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        timeout_seconds: float | None = None,
+        max_retries: int | None = None,
+        retry_delay: RetryDelay | None = None,
+        http_client: httpx.Client | None = None,
+        logger: logging.Logger | None = None,
+        telemetry: bool | None = None,
+    ) -> None:
+        cfg = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            http_client=http_client,
+            logger=logger,
+            telemetry=telemetry,
+        )
+        self._telemetry = Telemetry(enabled=cfg.telemetry)
+        self._http = HTTPClient(
+            HTTPClientOptions(
+                api_key=cfg.api_key,
+                base_url=cfg.base_url,
+                api_version=cfg.api_version,
+                timeout_seconds=cfg.timeout_seconds,
+                retry=RetryPolicy.from_delay(cfg.max_retries, cfg.retry_delay),
+                telemetry=self._telemetry,
+                logger=cfg.logger,
+                httpx_client=cfg.http_client,
+            )
+        )
+        self.events = EventsService(self._http)
+        self.invoices = InvoicesService(self._http)
+
+    def close(self) -> None:
+        """Close the underlying httpx client (no-op if you supplied your own)."""
+        self._http.close()
+
+    def disable_telemetry(self) -> None:
+        """Stop sending the ``Threecommon-Client-Telemetry`` header at runtime."""
+        self._telemetry.disable()
+
+    def __enter__(self) -> ThreeCommon:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        del exc_type, exc, tb
+        self.close()
+
+
+class AsyncThreeCommon:
+    """Asynchronous entry point. Same surface as [ThreeCommon] with `await`-able methods."""
+
+    events: AsyncEventsService
+    invoices: AsyncInvoicesService
+
+    _http: AsyncHTTPClient
+    _telemetry: Telemetry
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        timeout_seconds: float | None = None,
+        max_retries: int | None = None,
+        retry_delay: RetryDelay | None = None,
+        async_http_client: httpx.AsyncClient | None = None,
+        logger: logging.Logger | None = None,
+        telemetry: bool | None = None,
+    ) -> None:
+        cfg = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            async_http_client=async_http_client,
+            logger=logger,
+            telemetry=telemetry,
+        )
+        self._telemetry = Telemetry(enabled=cfg.telemetry)
+        self._http = AsyncHTTPClient(
+            HTTPClientOptions(
+                api_key=cfg.api_key,
+                base_url=cfg.base_url,
+                api_version=cfg.api_version,
+                timeout_seconds=cfg.timeout_seconds,
+                retry=RetryPolicy.from_delay(cfg.max_retries, cfg.retry_delay),
+                telemetry=self._telemetry,
+                logger=cfg.logger,
+                async_httpx_client=cfg.async_http_client,
+            )
+        )
+        self.events = AsyncEventsService(self._http)
+        self.invoices = AsyncInvoicesService(self._http)
+
+    async def aclose(self) -> None:
+        """Close the underlying async httpx client."""
+        await self._http.aclose()
+
+    def disable_telemetry(self) -> None:
+        self._telemetry.disable()
+
+    async def __aenter__(self) -> AsyncThreeCommon:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        del exc_type, exc, tb
+        await self.aclose()

threecommon/config.py

@@ -0,0 +1,140 @@
+"""Resolved client configuration.
+
+User do not construct [ClientConfig][threecommon.config.ClientConfig]
+directly — they pass keyword arguments to [ThreeCommon][threecommon.ThreeCommon]
+or [AsyncThreeCommon][threecommon.AsyncThreeCommon], which build a
+``ClientConfig`` internally after validation.
+
+This module also exposes the named defaults so the public docs can reference
+them.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from threecommon.api_version import API_VERSION
+from threecommon.errors.classes import ValidationError
+
+if TYPE_CHECKING:  # pragma: no cover
+    import logging
+
+    import httpx
+
+
+#: Default API base URL.
+DEFAULT_BASE_URL = "https://api.3common.com"
+
+#: Default per-request deadline.
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+#: Default number of retry attempts for idempotent requests on retryable
+#: failures (408, 425, 429, 5xx, network errors).
+DEFAULT_MAX_RETRIES = 3
+
+#: Environment variable consulted when ``api_key`` is not passed explicitly.
+ENV_VAR_API_KEY = "THREECOMMON_API_KEY"
+
+
+@dataclass(frozen=True, slots=True)
+class RetryDelay:
+    """Exponential-backoff schedule.
+
+    Backoff doubles each attempt, capped at :attr:`max_seconds`. When
+    :attr:`jitter` is true the SDK picks a random value in
+    ``[0, capped]`` for the actual sleep.
+    """
+
+    initial_seconds: float = 0.5
+    max_seconds: float = 8.0
+    jitter: bool = True
+
+
+#: Default backoff schedule applied when ``retry_delay`` isn't passed.
+DEFAULT_RETRY_DELAY = RetryDelay()
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """Internal frozen view of the resolved client configuration.
+
+    Construct via :func:`resolve_config` rather than directly.
+    """
+
+    api_key: str
+    base_url: str
+    api_version: str
+    timeout_seconds: float
+    max_retries: int
+    retry_delay: RetryDelay
+    http_client: httpx.Client | None = None
+    async_http_client: httpx.AsyncClient | None = None
+    logger: logging.Logger | None = None
+    telemetry: bool = True
+    user_agent_extra: str | None = field(default=None, repr=False)
+
+
+def resolve_config(
+    *,
+    api_key: str | None,
+    base_url: str | None,
+    api_version: str | None,
+    timeout_seconds: float | None,
+    max_retries: int | None,
+    retry_delay: RetryDelay | None,
+    http_client: httpx.Client | None = None,
+    async_http_client: httpx.AsyncClient | None = None,
+    logger: logging.Logger | None = None,
+    telemetry: bool | None = None,
+) -> ClientConfig:
+    """Validate constructor kwargs and return a frozen [ClientConfig].
+
+    Raises [ValidationError][threecommon.ValidationError] for missing API
+    key or invalid numeric ranges; the message names the exact field so
+    customers don't have to read a stack trace.
+    """
+    resolved_key = api_key or os.environ.get(ENV_VAR_API_KEY, "")
+    if not resolved_key:
+        raise ValidationError(
+            code="missing_api_key",
+            message=(
+                "An API key is required. Pass `api_key` to the ThreeCommon "
+                f"constructor, or set the {ENV_VAR_API_KEY} environment variable."
+            ),
+        )
+
+    resolved_base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    if not resolved_base.startswith(("http://", "https://")):
+        raise ValidationError(
+            code="invalid_base_url",
+            message=f"base_url must start with http:// or https://; got {base_url!r}.",
+        )
+
+    resolved_timeout = timeout_seconds if timeout_seconds is not None else DEFAULT_TIMEOUT_SECONDS
+    if resolved_timeout <= 0:
+        raise ValidationError(
+            code="invalid_timeout",
+            message=f"timeout_seconds must be positive; got {resolved_timeout!r}.",
+        )
+
+    resolved_retries = max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+    if resolved_retries < 0:
+        raise ValidationError(
+            code="invalid_max_retries",
+            message=f"max_retries must be non-negative; got {resolved_retries!r}.",
+        )
+
+    return ClientConfig(
+        api_key=resolved_key,
+        base_url=resolved_base,
+        api_version=api_version or API_VERSION,
+        timeout_seconds=resolved_timeout,
+        max_retries=resolved_retries,
+        retry_delay=retry_delay or DEFAULT_RETRY_DELAY,
+        http_client=http_client,
+        async_http_client=async_http_client,
+        logger=logger,
+        telemetry=True if telemetry is None else telemetry,
+    )

threecommon/errors/__init__.py

@@ -0,0 +1,35 @@
+"""Errors module — re-exports the base [APIError][threecommon.APIError] and
+every typed subtype.
+
+Customers usually catch via the root re-exports::
+
+    from threecommon import NotFoundError
+
+but importing the submodule directly also works::
+
+    from threecommon.errors import NotFoundError
+"""
+
+from threecommon.errors.base import APIError
+from threecommon.errors.classes import (
+    AuthError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = (
+    "APIError",
+    "AuthError",
+    "ConflictError",
+    "ConnectionError",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+)

threecommon/errors/base.py

@@ -0,0 +1,81 @@
+"""Base exception type carried by every error the SDK raises.
+
+The HTTP-status-specific subtypes ([AuthError][threecommon.AuthError],
+[NotFoundError][threecommon.NotFoundError], ...) all inherit from
+[APIError][threecommon.APIError]. Branch on the subtype with a normal
+`except` clause:
+
+    try:
+        client.events.retrieve("evt_missing")
+    except threecommon.NotFoundError as e:
+        log.warning("missing event %s", e.request_id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class APIError(Exception):
+    """Base class for every error raised by the SDK.
+
+    Every field is best-effort: ``http_status`` is ``None`` for connection
+    errors, ``request_id`` is ``None`` when the server didn't return one,
+    ``raw_response`` is empty for non-text responses.
+    """
+
+    code: str
+    """Stable string matching the API's error.code field, e.g. ``not_found``."""
+
+    message: str
+    """Human-readable description. Safe to surface to end users."""
+
+    http_status: int | None
+    """Response status, or ``None`` if the error originated before any response."""
+
+    request_id: str | None
+    """Value of the ``X-Request-ID`` response header, when present."""
+
+    details: dict[str, Any] | None
+    """Parsed API ``error.details`` payload, when present."""
+
+    raw_response: str | None
+    """Raw response body, retained for debugging."""
+
+    __cause__: BaseException | None
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        http_status: int | None = None,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        raw_response: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(self._format(code, message, request_id))
+        self.code = code
+        self.message = message
+        self.http_status = http_status
+        self.request_id = request_id
+        self.details = details
+        self.raw_response = raw_response
+        if cause is not None:
+            self.__cause__ = cause
+
+    @staticmethod
+    def _format(code: str, message: str, request_id: str | None) -> str:
+        if request_id:
+            return f"[{code}] {message} (request_id={request_id})"
+        return f"[{code}] {message}"
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"code={self.code!r}, "
+            f"message={self.message!r}, "
+            f"http_status={self.http_status!r}, "
+            f"request_id={self.request_id!r})"
+        )

threecommon/errors/classes.py

@@ -0,0 +1,75 @@
+"""HTTP-status-specific exception subtypes.
+
+All inherit from [APIError][threecommon.APIError]. Catch the subtype user care
+about; the order of `except` clauses can go from specific to general.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from threecommon.errors.base import APIError
+
+
+class AuthError(APIError):
+    """401 Unauthorized — invalid, missing, or expired API key."""
+
+
+class PermissionError(APIError):
+    """403 Forbidden — the API key lacks the scope required by the endpoint."""
+
+
+class NotFoundError(APIError):
+    """404 Not Found."""
+
+
+class ValidationError(APIError):
+    """400 Bad Request and 422 Unprocessable Entity — request validation failed."""
+
+
+class ConflictError(APIError):
+    """409 Conflict — the request conflicts with current resource state."""
+
+
+class RateLimitError(APIError):
+    """429 Too Many Requests.
+
+    [retry_after_seconds][threecommon.RateLimitError.retry_after_seconds]
+    carries the parsed ``Retry-After`` header so user can implement their
+    own backoff; it is ``None`` when the server did not provide one.
+    """
+
+    retry_after_seconds: float | None
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        http_status: int | None = None,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        raw_response: str | None = None,
+        cause: BaseException | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(
+            code=code,
+            message=message,
+            http_status=http_status,
+            request_id=request_id,
+            details=details,
+            raw_response=raw_response,
+            cause=cause,
+        )
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(APIError):
+    """5xx — the API returned an unexpected server-side failure."""
+
+
+class ConnectionError(APIError):
+    """The request never completed: DNS failure, TCP reset, TLS error,
+    timeout, etc. The original cause is available via ``__cause__``.
+    """

threecommon/events/__init__.py

@@ -0,0 +1,28 @@
+"""Events resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.events][threecommon.ThreeCommon] /
+[AsyncThreeCommon.events][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.events.service import AsyncEventsService, EventsService
+from threecommon.events.types import (
+    Event,
+    EventStatus,
+    ListEventsResponse,
+    ListParams,
+    RetrieveParams,
+    UpdateBody,
+)
+
+__all__ = (
+    "AsyncEventsService",
+    "Event",
+    "EventStatus",
+    "EventsService",
+    "ListEventsResponse",
+    "ListParams",
+    "RetrieveParams",
+    "UpdateBody",
+)