clawops 0.1.0__py3-none-any.whl

clawops/__init__.py

@@ -0,0 +1,62 @@
+"""ClawOps Voice API의 공식 Python SDK.
+
+Example::
+
+    from clawops import ClawOps
+
+    client = ClawOps(api_key="sk_...", account_id="AC1a2b3c4d")
+    call = client.calls.create(
+        to="01012345678", from_="07052358010",
+        url="https://my-app.com/twiml",
+    )
+    print(call.call_id)
+"""
+
+from ._client import AsyncClawOps, ClawOps
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ClawOpsError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    ServiceUnavailableError,
+    UnprocessableEntityError,
+)
+from ._version import __version__
+from .webhooks import WebhookVerificationError
+
+__all__ = [
+    "ClawOps",
+    "AsyncClawOps",
+    "ClawOpsError",
+    "APIError",
+    "APIStatusError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIResponseValidationError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+    "WebhookVerificationError",
+    "__version__",
+]
+
+_locals = locals()
+for _name in __all__:
+    if not _name.startswith("__"):
+        try:
+            _locals[_name].__module__ = "clawops"
+        except (TypeError, AttributeError):
+            pass

clawops/_base_client.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+import time
+from random import random
+from typing import Any, TypeVar
+
+import httpx
+import pydantic
+
+from ._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CONNECTION_LIMITS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    INITIAL_RETRY_DELAY,
+    MAX_RETRY_DELAY,
+)
+from ._exceptions import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APITimeoutError,
+    _make_status_error,
+)
+from ._version import __version__
+
+_T = TypeVar("_T", bound=pydantic.BaseModel)
+
+
+class SyncAPIClient:
+    """동기 HTTP 클라이언트 베이스. httpx.Client를 래핑하며 인증, 재시도, 타임아웃, 에러 매핑을 처리합니다."""
+
+    _client: httpx.Client
+    _api_key: str
+    _base_url: str
+    _max_retries: int
+    _timeout: httpx.Timeout
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+
+        if isinstance(timeout, (int, float)):
+            self._timeout = httpx.Timeout(timeout)
+        else:
+            self._timeout = timeout
+
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                timeout=self._timeout,
+                limits=DEFAULT_CONNECTION_LIMITS,
+            )
+
+    def _build_headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"clawops-python/{__version__}",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        extra_query: dict[str, object] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> _T | None:
+        headers = self._build_headers(extra_headers)
+
+        params = query.copy() if query else {}
+        if extra_query:
+            params.update(extra_query)
+
+        req_timeout = timeout if timeout is not None else self._timeout
+        if isinstance(req_timeout, (int, float)):
+            req_timeout = httpx.Timeout(req_timeout)
+
+        retries_left = self._max_retries
+
+        while True:
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=path,
+                    json=body,
+                    params=params if params else None,
+                    headers=headers,
+                    timeout=req_timeout,
+                )
+            except httpx.TimeoutException as e:
+                if retries_left > 0:
+                    retries_left -= 1
+                    time.sleep(self._retry_delay(self._max_retries - retries_left))
+                    continue
+                raise APITimeoutError(request=httpx.Request(method, self._base_url + path)) from e
+            except httpx.ConnectError as e:
+                if retries_left > 0:
+                    retries_left -= 1
+                    time.sleep(self._retry_delay(self._max_retries - retries_left))
+                    continue
+                raise APIConnectionError(request=httpx.Request(method, self._base_url + path)) from e
+
+            if response.is_success:
+                if response.status_code == 204 or cast_to is None:
+                    return None
+                try:
+                    return cast_to.model_validate(response.json())
+                except pydantic.ValidationError as e:
+                    raise APIResponseValidationError(response=response) from e
+
+            if retries_left > 0 and self._should_retry(response):
+                retries_left -= 1
+                time.sleep(self._retry_delay(self._max_retries - retries_left))
+                continue
+
+            raise _make_status_error(response=response)
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        if response.status_code in (408, 409, 429):
+            return True
+        if response.status_code >= 500:
+            return True
+        return False
+
+    def _retry_delay(self, retries_taken: int) -> float:
+        delay = min(INITIAL_RETRY_DELAY * (2 ** retries_taken), MAX_RETRY_DELAY)
+        return delay * (1 + random())
+
+    def _get(self, path: str, *, cast_to: type[_T], query: dict[str, Any] | None = None,
+             extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+             timeout: float | httpx.Timeout | None = None) -> _T:
+        result = self._request("GET", path, cast_to=cast_to, query=query,
+                               extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    def _post(self, path: str, *, body: dict[str, Any] | None = None, cast_to: type[_T],
+              extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+              timeout: float | httpx.Timeout | None = None) -> _T:
+        result = self._request("POST", path, body=body, cast_to=cast_to,
+                               extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    def _put(self, path: str, *, body: dict[str, Any] | None = None, cast_to: type[_T],
+             extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+             timeout: float | httpx.Timeout | None = None) -> _T:
+        result = self._request("PUT", path, body=body, cast_to=cast_to,
+                               extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    def _delete(self, path: str, *, extra_headers: dict[str, str] | None = None,
+                timeout: float | httpx.Timeout | None = None) -> None:
+        self._request("DELETE", path, cast_to=None, extra_headers=extra_headers, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> SyncAPIClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncAPIClient:
+    """비동기 HTTP 클라이언트 베이스. SyncAPIClient의 async 버전."""
+
+    _client: httpx.AsyncClient
+    _api_key: str
+    _base_url: str
+    _max_retries: int
+    _timeout: httpx.Timeout
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+
+        if isinstance(timeout, (int, float)):
+            self._timeout = httpx.Timeout(timeout)
+        else:
+            self._timeout = timeout
+
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._timeout,
+                limits=DEFAULT_CONNECTION_LIMITS,
+            )
+
+    def _build_headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"clawops-python/{__version__}",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        cast_to: type[_T] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        extra_query: dict[str, object] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> _T | None:
+        import asyncio
+
+        headers = self._build_headers(extra_headers)
+        params = query.copy() if query else {}
+        if extra_query:
+            params.update(extra_query)
+
+        req_timeout = timeout if timeout is not None else self._timeout
+        if isinstance(req_timeout, (int, float)):
+            req_timeout = httpx.Timeout(req_timeout)
+
+        retries_left = self._max_retries
+
+        while True:
+            try:
+                response = await self._client.request(
+                    method=method, url=path, json=body,
+                    params=params if params else None,
+                    headers=headers, timeout=req_timeout,
+                )
+            except httpx.TimeoutException as e:
+                if retries_left > 0:
+                    retries_left -= 1
+                    await asyncio.sleep(self._retry_delay(self._max_retries - retries_left))
+                    continue
+                raise APITimeoutError(request=httpx.Request(method, self._base_url + path)) from e
+            except httpx.ConnectError as e:
+                if retries_left > 0:
+                    retries_left -= 1
+                    await asyncio.sleep(self._retry_delay(self._max_retries - retries_left))
+                    continue
+                raise APIConnectionError(request=httpx.Request(method, self._base_url + path)) from e
+
+            if response.is_success:
+                if response.status_code == 204 or cast_to is None:
+                    return None
+                try:
+                    return cast_to.model_validate(response.json())
+                except pydantic.ValidationError as e:
+                    raise APIResponseValidationError(response=response) from e
+
+            if retries_left > 0 and self._should_retry(response):
+                retries_left -= 1
+                await asyncio.sleep(self._retry_delay(self._max_retries - retries_left))
+                continue
+
+            raise _make_status_error(response=response)
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        if response.status_code in (408, 409, 429):
+            return True
+        if response.status_code >= 500:
+            return True
+        return False
+
+    def _retry_delay(self, retries_taken: int) -> float:
+        delay = min(INITIAL_RETRY_DELAY * (2 ** retries_taken), MAX_RETRY_DELAY)
+        return delay * (1 + random())
+
+    async def _get(self, path: str, *, cast_to: type[_T], query: dict[str, Any] | None = None,
+                   extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+                   timeout: float | httpx.Timeout | None = None) -> _T:
+        result = await self._request("GET", path, cast_to=cast_to, query=query,
+                                     extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    async def _post(self, path: str, *, body: dict[str, Any] | None = None, cast_to: type[_T],
+                    extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+                    timeout: float | httpx.Timeout | None = None) -> _T:
+        result = await self._request("POST", path, body=body, cast_to=cast_to,
+                                     extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    async def _put(self, path: str, *, body: dict[str, Any] | None = None, cast_to: type[_T],
+                   extra_headers: dict[str, str] | None = None, extra_query: dict[str, object] | None = None,
+                   timeout: float | httpx.Timeout | None = None) -> _T:
+        result = await self._request("PUT", path, body=body, cast_to=cast_to,
+                                     extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        assert result is not None
+        return result
+
+    async def _delete(self, path: str, *, extra_headers: dict[str, str] | None = None,
+                      timeout: float | httpx.Timeout | None = None) -> None:
+        await self._request("DELETE", path, cast_to=None, extra_headers=extra_headers, timeout=timeout)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAPIClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

clawops/_client.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from ._base_client import AsyncAPIClient, SyncAPIClient
+from ._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from ._exceptions import ClawOpsError
+from .resources.accounts import AccountContext, AsyncAccountContext
+from .resources.calls import AsyncCalls, Calls
+from .resources.numbers import AsyncNumbers, Numbers
+from .resources.sip import AsyncSip, Sip
+from .webhooks import Webhooks
+
+
+class ClawOps(SyncAPIClient):
+    """ClawOps Voice API의 동기 클라이언트.
+
+    Example::
+
+        from clawops import ClawOps
+
+        client = ClawOps(api_key="sk_...", account_id="AC1a2b3c4d")
+
+        call = client.calls.create(
+            to="01012345678", from_="07052358010",
+            url="https://my-app.com/twiml",
+        )
+
+        other = client.accounts("AC_other")
+        other.calls.list()
+
+    Args:
+        api_key: API 키 (sk_...). 생략 시 CLAWOPS_API_KEY 환경변수 사용.
+        account_id: 기본 계정 ID (AC...). 생략 시 CLAWOPS_ACCOUNT_ID 환경변수 사용.
+        base_url: API 기본 URL. 기본값: https://api.claw-ops.com
+        timeout: 요청 타임아웃 (초 또는 httpx.Timeout). 기본값: 600초.
+        max_retries: 최대 재시도 횟수. 기본값: 2.
+        http_client: 커스텀 httpx.Client 인스턴스.
+        default_headers: 모든 요청에 포함할 기본 HTTP 헤더.
+    """
+
+    _default_account_id: str
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        account_id: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        if api_key is None:
+            api_key = os.environ.get("CLAWOPS_API_KEY")
+        if api_key is None:
+            raise ClawOpsError("api_key를 지정하거나 CLAWOPS_API_KEY 환경변수를 설정하세요.")
+
+        if account_id is None:
+            account_id = os.environ.get("CLAWOPS_ACCOUNT_ID")
+        if account_id is None:
+            raise ClawOpsError("account_id를 지정하거나 CLAWOPS_ACCOUNT_ID 환경변수를 설정하세요.")
+
+        if base_url is None:
+            base_url = os.environ.get("CLAWOPS_BASE_URL", DEFAULT_BASE_URL)
+
+        self._default_account_id = account_id
+
+        super().__init__(
+            api_key=api_key, base_url=base_url, timeout=timeout,
+            max_retries=max_retries, http_client=http_client, default_headers=default_headers,
+        )
+
+    @property
+    def calls(self) -> Calls:
+        """통화(Calls) 리소스에 접근합니다."""
+        return Calls(client=self, account_id=self._default_account_id)
+
+    @property
+    def numbers(self) -> Numbers:
+        """전화번호(Numbers) 리소스에 접근합니다."""
+        return Numbers(client=self, account_id=self._default_account_id)
+
+    @property
+    def sip(self) -> Sip:
+        """SIP 리소스에 접근합니다."""
+        return Sip(client=self, account_id=self._default_account_id)
+
+    @property
+    def webhooks(self) -> Webhooks:
+        """Webhook 서명 검증 유틸리티."""
+        return Webhooks()
+
+    def accounts(self, account_id: str) -> AccountContext:
+        """다른 계정의 리소스에 접근합니다.
+
+        Args:
+            account_id: 접근할 계정 ID.
+
+        Returns:
+            해당 계정에 바인딩된 AccountContext 객체.
+        """
+        return AccountContext(client=self, account_id=account_id)
+
+
+class AsyncClawOps(AsyncAPIClient):
+    """ClawOps Voice API의 비동기 클라이언트.
+
+    Example::
+
+        async with AsyncClawOps(api_key="sk_...", account_id="AC...") as client:
+            call = await client.calls.create(
+                to="01012345678", from_="07052358010",
+                url="https://my-app.com/twiml",
+            )
+    """
+
+    _default_account_id: str
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        account_id: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        if api_key is None:
+            api_key = os.environ.get("CLAWOPS_API_KEY")
+        if api_key is None:
+            raise ClawOpsError("api_key를 지정하거나 CLAWOPS_API_KEY 환경변수를 설정하세요.")
+
+        if account_id is None:
+            account_id = os.environ.get("CLAWOPS_ACCOUNT_ID")
+        if account_id is None:
+            raise ClawOpsError("account_id를 지정하거나 CLAWOPS_ACCOUNT_ID 환경변수를 설정하세요.")
+
+        if base_url is None:
+            base_url = os.environ.get("CLAWOPS_BASE_URL", DEFAULT_BASE_URL)
+
+        self._default_account_id = account_id
+
+        super().__init__(
+            api_key=api_key, base_url=base_url, timeout=timeout,
+            max_retries=max_retries, http_client=http_client, default_headers=default_headers,
+        )
+
+    @property
+    def calls(self) -> AsyncCalls:
+        return AsyncCalls(client=self, account_id=self._default_account_id)
+
+    @property
+    def numbers(self) -> AsyncNumbers:
+        return AsyncNumbers(client=self, account_id=self._default_account_id)
+
+    @property
+    def sip(self) -> AsyncSip:
+        return AsyncSip(client=self, account_id=self._default_account_id)
+
+    @property
+    def webhooks(self) -> Webhooks:
+        return Webhooks()
+
+    def accounts(self, account_id: str) -> AsyncAccountContext:
+        return AsyncAccountContext(client=self, account_id=account_id)

clawops/_constants.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import httpx
+
+DEFAULT_TIMEOUT = httpx.Timeout(timeout=600.0, connect=5.0)
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_BASE_URL = "https://api.claw-ops.com"
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0
+DEFAULT_CONNECTION_LIMITS = httpx.Limits(
+    max_connections=1000,
+    max_keepalive_connections=100,
+)