clawops 0.1.0__tar.gz

clawops-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/ghyeok/Developments/clawops/**)",
+      "WebSearch",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs",
+      "Bash(git:*)",
+      "Bash(pip install:*)",
+      "Bash(pytest:*)",
+      "Bash(python:*)",
+      "Bash(mypy:*)",
+      "Bash(ruff check:*)"
+    ]
+  }
+}

clawops-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

clawops-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: clawops
+Version: 0.1.0
+Summary: The official Python library for the ClawOps Voice API
+Project-URL: Homepage, https://github.com/learners-superpumped/clawops-python
+Project-URL: Documentation, https://docs.claw-ops.com
+Project-URL: Repository, https://github.com/learners-superpumped/clawops-python
+Author-email: ClawOps <support@claw-ops.com>
+License-Expression: Apache-2.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.23.0
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: typing-extensions>=4.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ClawOps Python SDK
+
+[ClawOps Voice API](https://api.claw-ops.com/docs)의 공식 Python 라이브러리입니다.
+
+[![PyPI version](https://img.shields.io/pypi/v/clawops.svg)](https://pypi.org/project/clawops/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/clawops.svg)](https://pypi.org/project/clawops/)
+
+## 설치
+
+```bash
+pip install clawops
+```
+
+## 사용법
+
+```python
+from clawops import ClawOps
+
+client = ClawOps(
+    api_key="sk_...",          # 또는 CLAWOPS_API_KEY 환경변수 사용
+    account_id="AC1a2b3c4d",   # 또는 CLAWOPS_ACCOUNT_ID 환경변수 사용
+)
+```
+
+### 통화 (Calls)
+
+```python
+# 발신 전화 생성
+call = client.calls.create(
+    to="01012345678",
+    from_="07052358010",
+    url="https://my-app.com/twiml",
+    status_callback="https://my-app.com/status",
+    status_callback_event="initiated ringing answered completed",
+)
+print(call.call_id)
+
+# 통화 목록 조회 (페이지네이션)
+page = client.calls.list(status="completed", page=0, page_size=20)
+for call in page:
+    print(call.call_id, call.status)
+
+# 모든 통화를 자동으로 순회
+for call in client.calls.list().auto_paging_iter():
+    print(call.call_id)
+
+# 특정 통화 조회
+call = client.calls.get("CAabcdef1234567890")
+
+# 통화 종료
+call = client.calls.update("CAabcdef1234567890", status="completed")
+```
+
+### 전화번호 (Numbers)
+
+```python
+# 번호 구매
+number = client.numbers.create(source="pool")
+print(number.phone_number)
+
+# 번호 목록 조회
+numbers = client.numbers.list()
+
+# 웹훅 URL 변경
+number = client.numbers.update("07012340001", webhook_url="https://my-app.com/webhook")
+
+# 번호 해제
+client.numbers.delete("07012340001")
+```
+
+### SIP 자격증명 (SIP Credentials)
+
+```python
+# SIP 자격증명 생성
+cred = client.sip.credentials.create(display_name="Office Phone")
+print(cred.credential_id, cred.sip_username)
+
+# 자격증명 목록 조회
+creds = client.sip.credentials.list()
+
+# 특정 자격증명 조회
+cred = client.sip.credentials.get("clu1abc2def3ghi")
+
+# 자격증명 삭제
+client.sip.credentials.delete("clu1abc2def3ghi")
+```
+
+### 멀티 계정 접근
+
+```python
+# 다른 계정의 리소스에 접근
+other = client.accounts("AC_other_account_id")
+other.calls.list()
+other.numbers.list()
+```
+
+## 비동기 사용법
+
+```python
+from clawops import AsyncClawOps
+
+# async context manager 사용
+async with AsyncClawOps(api_key="sk_...", account_id="AC1a2b3c4d") as client:
+    call = await client.calls.create(
+        to="01012345678",
+        from_="07052358010",
+        url="https://my-app.com/twiml",
+    )
+    print(call.call_id)
+
+    # 모든 리소스 메서드는 비동기 버전을 제공합니다
+    page = await client.calls.list(status="completed")
+    async for call in page.auto_paging_iter():
+        print(call.call_id)
+```
+
+## 웹훅 서명 검증
+
+```python
+client.webhooks.verify(
+    url="https://my-app.com/webhook",
+    params={"CallId": "CA...", "CallStatus": "completed"},
+    signature=request.headers["X-Signature"],
+    signing_key="your_account_signing_key",
+)
+```
+
+서명이 유효하지 않으면 `WebhookVerificationError`가 발생합니다.
+
+## 에러 처리
+
+```python
+from clawops import ClawOps, BadRequestError, AuthenticationError, NotFoundError
+
+client = ClawOps()
+
+try:
+    call = client.calls.create(to="01012345678", from_="07052358010", url="https://...")
+except BadRequestError as e:
+    print(f"잘못된 요청: {e.status_code} - {e.body}")
+except AuthenticationError as e:
+    print(f"유효하지 않은 API 키: {e.status_code}")
+except NotFoundError as e:
+    print(f"리소스를 찾을 수 없음: {e.status_code}")
+```
+
+모든 에러는 `ClawOpsError`를 상속합니다. HTTP 에러는 `status_code`, `response`, `body`, `request` 속성을 제공합니다.
+
+| 에러                       | 상태 코드 |
+| -------------------------- | --------- |
+| `BadRequestError`          | 400       |
+| `AuthenticationError`      | 401       |
+| `PermissionDeniedError`    | 403       |
+| `NotFoundError`            | 404       |
+| `ConflictError`            | 409       |
+| `UnprocessableEntityError` | 422       |
+| `InternalServerError`      | 500+      |
+| `ServiceUnavailableError`  | 503       |
+
+## 설정
+
+### 재시도
+
+기본적으로 `408`, `409`, `429`, `500+` 에러 시 지수 백오프로 최대 2회 재시도합니다.
+
+```python
+client = ClawOps(max_retries=5)
+
+# 재시도 비활성화
+client = ClawOps(max_retries=0)
+```
+
+### 타임아웃
+
+기본 타임아웃은 600초 (연결 타임아웃 5초)입니다. 클라이언트 또는 요청 단위로 변경할 수 있습니다:
+
+```python
+# 클라이언트 단위
+client = ClawOps(timeout=30.0)
+
+# 요청 단위
+call = client.calls.create(..., timeout=10.0)
+```
+
+### 커스텀 HTTP 클라이언트
+
+프록시, 커스텀 인증서 등 고급 설정이 필요한 경우 `httpx.Client`를 직접 주입할 수 있습니다:
+
+```python
+import httpx
+
+client = ClawOps(
+    http_client=httpx.Client(proxies="http://proxy.example.com:8080"),
+)
+```
+
+## 환경변수
+
+| 변수                 | 설명                   | 필수 여부                                   |
+| -------------------- | ---------------------- | ------------------------------------------- |
+| `CLAWOPS_API_KEY`    | API 키 (`sk_...`)      | 예 (생성자에 전달하지 않은 경우)            |
+| `CLAWOPS_ACCOUNT_ID` | 기본 계정 ID (`AC...`) | 예 (생성자에 전달하지 않은 경우)            |
+| `CLAWOPS_BASE_URL`   | API 기본 URL           | 아니오 (기본값: `https://api.claw-ops.com`) |
+
+## 요구사항
+
+- Python 3.9+
+- `httpx` >= 0.23.0
+- `pydantic` >= 2.0.0
+
+## 라이선스
+
+Apache-2.0

clawops-0.1.0/README.md

@@ -0,0 +1,213 @@
+# ClawOps Python SDK
+
+[ClawOps Voice API](https://api.claw-ops.com/docs)의 공식 Python 라이브러리입니다.
+
+[![PyPI version](https://img.shields.io/pypi/v/clawops.svg)](https://pypi.org/project/clawops/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/clawops.svg)](https://pypi.org/project/clawops/)
+
+## 설치
+
+```bash
+pip install clawops
+```
+
+## 사용법
+
+```python
+from clawops import ClawOps
+
+client = ClawOps(
+    api_key="sk_...",          # 또는 CLAWOPS_API_KEY 환경변수 사용
+    account_id="AC1a2b3c4d",   # 또는 CLAWOPS_ACCOUNT_ID 환경변수 사용
+)
+```
+
+### 통화 (Calls)
+
+```python
+# 발신 전화 생성
+call = client.calls.create(
+    to="01012345678",
+    from_="07052358010",
+    url="https://my-app.com/twiml",
+    status_callback="https://my-app.com/status",
+    status_callback_event="initiated ringing answered completed",
+)
+print(call.call_id)
+
+# 통화 목록 조회 (페이지네이션)
+page = client.calls.list(status="completed", page=0, page_size=20)
+for call in page:
+    print(call.call_id, call.status)
+
+# 모든 통화를 자동으로 순회
+for call in client.calls.list().auto_paging_iter():
+    print(call.call_id)
+
+# 특정 통화 조회
+call = client.calls.get("CAabcdef1234567890")
+
+# 통화 종료
+call = client.calls.update("CAabcdef1234567890", status="completed")
+```
+
+### 전화번호 (Numbers)
+
+```python
+# 번호 구매
+number = client.numbers.create(source="pool")
+print(number.phone_number)
+
+# 번호 목록 조회
+numbers = client.numbers.list()
+
+# 웹훅 URL 변경
+number = client.numbers.update("07012340001", webhook_url="https://my-app.com/webhook")
+
+# 번호 해제
+client.numbers.delete("07012340001")
+```
+
+### SIP 자격증명 (SIP Credentials)
+
+```python
+# SIP 자격증명 생성
+cred = client.sip.credentials.create(display_name="Office Phone")
+print(cred.credential_id, cred.sip_username)
+
+# 자격증명 목록 조회
+creds = client.sip.credentials.list()
+
+# 특정 자격증명 조회
+cred = client.sip.credentials.get("clu1abc2def3ghi")
+
+# 자격증명 삭제
+client.sip.credentials.delete("clu1abc2def3ghi")
+```
+
+### 멀티 계정 접근
+
+```python
+# 다른 계정의 리소스에 접근
+other = client.accounts("AC_other_account_id")
+other.calls.list()
+other.numbers.list()
+```
+
+## 비동기 사용법
+
+```python
+from clawops import AsyncClawOps
+
+# async context manager 사용
+async with AsyncClawOps(api_key="sk_...", account_id="AC1a2b3c4d") as client:
+    call = await client.calls.create(
+        to="01012345678",
+        from_="07052358010",
+        url="https://my-app.com/twiml",
+    )
+    print(call.call_id)
+
+    # 모든 리소스 메서드는 비동기 버전을 제공합니다
+    page = await client.calls.list(status="completed")
+    async for call in page.auto_paging_iter():
+        print(call.call_id)
+```
+
+## 웹훅 서명 검증
+
+```python
+client.webhooks.verify(
+    url="https://my-app.com/webhook",
+    params={"CallId": "CA...", "CallStatus": "completed"},
+    signature=request.headers["X-Signature"],
+    signing_key="your_account_signing_key",
+)
+```
+
+서명이 유효하지 않으면 `WebhookVerificationError`가 발생합니다.
+
+## 에러 처리
+
+```python
+from clawops import ClawOps, BadRequestError, AuthenticationError, NotFoundError
+
+client = ClawOps()
+
+try:
+    call = client.calls.create(to="01012345678", from_="07052358010", url="https://...")
+except BadRequestError as e:
+    print(f"잘못된 요청: {e.status_code} - {e.body}")
+except AuthenticationError as e:
+    print(f"유효하지 않은 API 키: {e.status_code}")
+except NotFoundError as e:
+    print(f"리소스를 찾을 수 없음: {e.status_code}")
+```
+
+모든 에러는 `ClawOpsError`를 상속합니다. HTTP 에러는 `status_code`, `response`, `body`, `request` 속성을 제공합니다.
+
+| 에러                       | 상태 코드 |
+| -------------------------- | --------- |
+| `BadRequestError`          | 400       |
+| `AuthenticationError`      | 401       |
+| `PermissionDeniedError`    | 403       |
+| `NotFoundError`            | 404       |
+| `ConflictError`            | 409       |
+| `UnprocessableEntityError` | 422       |
+| `InternalServerError`      | 500+      |
+| `ServiceUnavailableError`  | 503       |
+
+## 설정
+
+### 재시도
+
+기본적으로 `408`, `409`, `429`, `500+` 에러 시 지수 백오프로 최대 2회 재시도합니다.
+
+```python
+client = ClawOps(max_retries=5)
+
+# 재시도 비활성화
+client = ClawOps(max_retries=0)
+```
+
+### 타임아웃
+
+기본 타임아웃은 600초 (연결 타임아웃 5초)입니다. 클라이언트 또는 요청 단위로 변경할 수 있습니다:
+
+```python
+# 클라이언트 단위
+client = ClawOps(timeout=30.0)
+
+# 요청 단위
+call = client.calls.create(..., timeout=10.0)
+```
+
+### 커스텀 HTTP 클라이언트
+
+프록시, 커스텀 인증서 등 고급 설정이 필요한 경우 `httpx.Client`를 직접 주입할 수 있습니다:
+
+```python
+import httpx
+
+client = ClawOps(
+    http_client=httpx.Client(proxies="http://proxy.example.com:8080"),
+)
+```
+
+## 환경변수
+
+| 변수                 | 설명                   | 필수 여부                                   |
+| -------------------- | ---------------------- | ------------------------------------------- |
+| `CLAWOPS_API_KEY`    | API 키 (`sk_...`)      | 예 (생성자에 전달하지 않은 경우)            |
+| `CLAWOPS_ACCOUNT_ID` | 기본 계정 ID (`AC...`) | 예 (생성자에 전달하지 않은 경우)            |
+| `CLAWOPS_BASE_URL`   | API 기본 URL           | 아니오 (기본값: `https://api.claw-ops.com`) |
+
+## 요구사항
+
+- Python 3.9+
+- `httpx` >= 0.23.0
+- `pydantic` >= 2.0.0
+
+## 라이선스
+
+Apache-2.0