teamver-sdk-core 0.1.0__tar.gz

teamver_sdk_core-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+node_modules/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+.next/
+/out/
+out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+dist/
+
+# vite build output
+examples/react-ai-app/dist/
+
+# python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/

teamver_sdk_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog — teamver-sdk-core
+
+All notable changes to this package are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] - 2026-07-23
+
+### Added
+- Initial greenfield core shared by all Teamver SDKs (16-1 §4, §13).
+- `TeamverAsyncTransport`: httpx-based async transport with retry, error
+  normalization, and request-context header propagation.
+- Unified exception tree rooted at `TeamverSDKError`
+  (`Authentication`/`Authorization`/`NotFound`/`Conflict`/`RateLimit`/
+  `TemporaryUnavailable`/`Transport` + idempotency/version conflict subtypes).
+- `error_for_status` / `parse_error_body` normalize Main `error`, FastAPI
+  `detail`, and legacy shapes into one model while preserving status/code/request_id.
+- `RetryPolicy` with idempotency-aware retry (non-idempotent POST retried only
+  when an `Idempotency-Key` is supplied).
+- `RequestContext` for `request_id` / `correlation_id` propagation.
+- `iterate_pages` cursor pagination helper and `extract_page`.
+- `mask_secrets` / `mask_headers` for token/Bearer/internal-key redaction.

teamver_sdk_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Neural Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

teamver_sdk_core-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: teamver-sdk-core
+Version: 0.1.0
+Summary: Shared core for Teamver SDKs: async transport, unified errors, retry, context, pagination, masking
+Project-URL: Homepage, https://teamver.com
+Project-URL: Documentation, https://github.com/NeuralStudioKr/ns-teamver-packages/tree/main/packages/python/teamver-sdk-core-python
+Project-URL: Repository, https://github.com/NeuralStudioKr/ns-teamver-packages
+Project-URL: Issues, https://github.com/NeuralStudioKr/ns-teamver-packages/issues
+Project-URL: Changelog, https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-sdk-core-python/CHANGELOG.md
+Author-email: Teamver <dev@teamver.com>
+Maintainer-email: Teamver <dev@teamver.com>
+License: MIT
+License-File: LICENSE
+Keywords: async,httpx,retry,sdk,teamver,transport
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<0.28,>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# teamver-sdk-core
+
+Shared **async HTTP core** for Teamver Python SDKs: transport, unified errors, retry,
+request context, pagination, and secret masking.
+
+Used by `teamver-mail-agent`, `teamver-agent-sdk`, and other Teamver packages.
+
+## Install
+
+```bash
+pip install teamver-sdk-core
+```
+
+Python **≥ 3.11**.
+
+## Quick start
+
+```python
+import asyncio
+from teamver_sdk_core import (
+    TeamverAsyncTransport,
+    TransportConfig,
+    RequestContext,
+    TeamverSDKError,
+)
+
+async def main():
+    config = TransportConfig(base_url="https://api.teamver.com", token="tv_ak_…")
+    async with TeamverAsyncTransport(config) as transport:
+        ctx = RequestContext(workspace_id="WS-…")
+        try:
+            resp = await transport.request("GET", "/api/v2/collab/channels", context=ctx)
+            print(resp.json)
+        except TeamverSDKError as exc:
+            print(exc.code, exc.status_code, exc.request_id)
+
+asyncio.run(main())
+```
+
+## Features
+
+| Module | Role |
+| --- | --- |
+| `transport` | `TeamverAsyncTransport` — httpx async requests, retry, error normalization |
+| `errors` | `TeamverSDKError` tree + `error_for_status` / `parse_error_body` |
+| `retry` | `RetryPolicy` — safe retries (non-idempotent POST needs `idempotency_key`) |
+| `context` | `RequestContext` — `request_id` / `correlation_id` |
+| `pagination` | cursor `iterate_pages` |
+| `masking` | mask tokens / Bearer / internal keys in logs |
+
+## Error tree
+
+```
+TeamverSDKError
+├─ ConfigurationError
+├─ AuthenticationError        (401)
+├─ AuthorizationError         (403)
+├─ NotFoundError              (404)
+├─ ConflictError              (409)
+│  ├─ IdempotencyConflictError
+│  └─ VersionConflictError
+├─ RateLimitError             (429)
+├─ TemporaryUnavailableError  (502/503/504)
+└─ TransportError
+```
+
+## Retry rules
+
+- Retried: transport failure, `429`, `502`, `503`, `504`
+- `GET/HEAD/PUT/DELETE` — treated as idempotent
+- `POST/PATCH` — retried only when `idempotency_key` is set
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

teamver_sdk_core-0.1.0/README.md

@@ -0,0 +1,82 @@
+# teamver-sdk-core
+
+Shared **async HTTP core** for Teamver Python SDKs: transport, unified errors, retry,
+request context, pagination, and secret masking.
+
+Used by `teamver-mail-agent`, `teamver-agent-sdk`, and other Teamver packages.
+
+## Install
+
+```bash
+pip install teamver-sdk-core
+```
+
+Python **≥ 3.11**.
+
+## Quick start
+
+```python
+import asyncio
+from teamver_sdk_core import (
+    TeamverAsyncTransport,
+    TransportConfig,
+    RequestContext,
+    TeamverSDKError,
+)
+
+async def main():
+    config = TransportConfig(base_url="https://api.teamver.com", token="tv_ak_…")
+    async with TeamverAsyncTransport(config) as transport:
+        ctx = RequestContext(workspace_id="WS-…")
+        try:
+            resp = await transport.request("GET", "/api/v2/collab/channels", context=ctx)
+            print(resp.json)
+        except TeamverSDKError as exc:
+            print(exc.code, exc.status_code, exc.request_id)
+
+asyncio.run(main())
+```
+
+## Features
+
+| Module | Role |
+| --- | --- |
+| `transport` | `TeamverAsyncTransport` — httpx async requests, retry, error normalization |
+| `errors` | `TeamverSDKError` tree + `error_for_status` / `parse_error_body` |
+| `retry` | `RetryPolicy` — safe retries (non-idempotent POST needs `idempotency_key`) |
+| `context` | `RequestContext` — `request_id` / `correlation_id` |
+| `pagination` | cursor `iterate_pages` |
+| `masking` | mask tokens / Bearer / internal keys in logs |
+
+## Error tree
+
+```
+TeamverSDKError
+├─ ConfigurationError
+├─ AuthenticationError        (401)
+├─ AuthorizationError         (403)
+├─ NotFoundError              (404)
+├─ ConflictError              (409)
+│  ├─ IdempotencyConflictError
+│  └─ VersionConflictError
+├─ RateLimitError             (429)
+├─ TemporaryUnavailableError  (502/503/504)
+└─ TransportError
+```
+
+## Retry rules
+
+- Retried: transport failure, `429`, `502`, `503`, `504`
+- `GET/HEAD/PUT/DELETE` — treated as idempotent
+- `POST/PATCH` — retried only when `idempotency_key` is set
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

teamver_sdk_core-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "teamver-sdk-core"
+version = "0.1.0"
+description = "Shared core for Teamver SDKs: async transport, unified errors, retry, context, pagination, masking"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Teamver", email = "dev@teamver.com" },
+]
+maintainers = [
+  { name = "Teamver", email = "dev@teamver.com" },
+]
+keywords = [
+  "teamver",
+  "sdk",
+  "httpx",
+  "async",
+  "transport",
+  "retry",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0,<0.28",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Homepage = "https://teamver.com"
+Documentation = "https://github.com/NeuralStudioKr/ns-teamver-packages/tree/main/packages/python/teamver-sdk-core-python"
+Repository = "https://github.com/NeuralStudioKr/ns-teamver-packages"
+Issues = "https://github.com/NeuralStudioKr/ns-teamver-packages/issues"
+Changelog = "https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-sdk-core-python/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["teamver_sdk_core"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/teamver_sdk_core",
+  "/tests",
+  "/README.md",
+  "/CHANGELOG.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

teamver_sdk_core-0.1.0/teamver_sdk_core/__init__.py

@@ -0,0 +1,88 @@
+"""teamver-sdk-core — Teamver SDK 공통 코어 (16-1 SDK 재설계 §4, §13).
+
+하위 SDK(be-sdk / mail-agent / agent-sdk / apps-auth)가 공유하는 building block:
+
+- ``TeamverAsyncTransport`` : httpx 기반 async 요청 + 재시도 + 오류 정규화 + context 전파
+- 통합 예외 트리(``TeamverSDKError`` 이하)
+- ``RequestContext`` : request_id / correlation_id 전파
+- ``RetryPolicy`` : 멱등 안전 재시도 정책
+- pagination / masking 유틸
+"""
+
+from teamver_sdk_core.config import TransportConfig
+from teamver_sdk_core.context import (
+    HEADER_CORRELATION_ID,
+    HEADER_IDEMPOTENCY_KEY,
+    HEADER_REQUEST_ID,
+    HEADER_WORKSPACE_ID,
+    RequestContext,
+    new_correlation_id,
+    new_request_id,
+)
+from teamver_sdk_core.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConfigurationError,
+    ConflictError,
+    IdempotencyConflictError,
+    NotFoundError,
+    RateLimitError,
+    TeamverSDKError,
+    TemporaryUnavailableError,
+    TransportError,
+    VersionConflictError,
+    error_for_status,
+    parse_error_body,
+)
+from teamver_sdk_core.masking import mask_headers, mask_secrets
+from teamver_sdk_core.pagination import extract_page, iterate_pages
+from teamver_sdk_core.retry import (
+    RETRYABLE_STATUS,
+    RetryPolicy,
+    is_retryable_request,
+    should_retry,
+)
+from teamver_sdk_core.transport import TeamverAsyncTransport
+from teamver_sdk_core.typing import TeamverResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # transport / config
+    "TeamverAsyncTransport",
+    "TransportConfig",
+    "TeamverResponse",
+    # context
+    "RequestContext",
+    "new_request_id",
+    "new_correlation_id",
+    "HEADER_REQUEST_ID",
+    "HEADER_CORRELATION_ID",
+    "HEADER_WORKSPACE_ID",
+    "HEADER_IDEMPOTENCY_KEY",
+    # retry
+    "RetryPolicy",
+    "RETRYABLE_STATUS",
+    "should_retry",
+    "is_retryable_request",
+    # errors
+    "TeamverSDKError",
+    "ConfigurationError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ConflictError",
+    "IdempotencyConflictError",
+    "VersionConflictError",
+    "RateLimitError",
+    "TemporaryUnavailableError",
+    "TransportError",
+    "error_for_status",
+    "parse_error_body",
+    # pagination / masking
+    "iterate_pages",
+    "extract_page",
+    "mask_secrets",
+    "mask_headers",
+]

teamver_sdk_core-0.1.0/teamver_sdk_core/config.py

@@ -0,0 +1,25 @@
+"""Transport configuration (16-1 §4 config)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from teamver_sdk_core.retry import RetryPolicy
+
+
+@dataclass
+class TransportConfig:
+    base_url: str
+    token: str | None = None
+    # Authorization scheme; agent tokens use Bearer.
+    auth_scheme: str = "Bearer"
+    timeout_seconds: float = 30.0
+    retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
+    # Extra static headers (e.g. X-Teamver-Internal-Api-Key for M2M).
+    default_headers: dict[str, str] = field(default_factory=dict)
+    user_agent: str = "teamver-sdk-core/0.1.0"
+
+    def auth_header(self) -> dict[str, str]:
+        if not self.token:
+            return {}
+        return {"Authorization": f"{self.auth_scheme} {self.token}".strip()}

teamver_sdk_core-0.1.0/teamver_sdk_core/context.py

@@ -0,0 +1,52 @@
+"""Request context propagation (16-1 §4 Context; 15-1 §01 §6).
+
+SDK 가 ``request_id`` 를 생성하고 서비스가 downstream 으로 전달한다. 동일 correlation_id
+로 Job/Channel/Mail/VM 을 교차 추적한다(§12 §1).
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+HEADER_REQUEST_ID = "X-Teamver-Request-Id"
+HEADER_CORRELATION_ID = "X-Teamver-Correlation-Id"
+HEADER_WORKSPACE_ID = "X-Workspace-Id"
+HEADER_IDEMPOTENCY_KEY = "Idempotency-Key"
+
+
+def new_request_id() -> str:
+    return f"req_{uuid.uuid4().hex}"
+
+
+def new_correlation_id() -> str:
+    return f"corr_{uuid.uuid4().hex}"
+
+
+@dataclass
+class RequestContext:
+    request_id: str = field(default_factory=new_request_id)
+    correlation_id: Optional[str] = None
+    workspace_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    job_id: Optional[str] = None
+
+    def to_headers(self) -> dict[str, str]:
+        """컨텍스트 → HTTP 헤더(값이 있는 것만)."""
+        headers: dict[str, str] = {HEADER_REQUEST_ID: self.request_id}
+        if self.correlation_id:
+            headers[HEADER_CORRELATION_ID] = self.correlation_id
+        if self.workspace_id:
+            headers[HEADER_WORKSPACE_ID] = self.workspace_id
+        return headers
+
+    def child(self) -> "RequestContext":
+        """새 request_id, 동일 correlation_id 로 하위 요청 컨텍스트 생성."""
+        return RequestContext(
+            request_id=new_request_id(),
+            correlation_id=self.correlation_id or self.request_id,
+            workspace_id=self.workspace_id,
+            agent_id=self.agent_id,
+            job_id=self.job_id,
+        )

teamver_sdk_core-0.1.0/teamver_sdk_core/errors.py

@@ -0,0 +1,161 @@
+"""Unified SDK exception hierarchy (16-1 SDK 재설계 §13).
+
+모든 하위 SDK(be-sdk / mail-agent / agent-sdk / apps-auth)는 원본 오류(Main ``error``,
+FastAPI ``detail``, legacy shape)를 아래 단일 트리로 **정규화**한다. 원본 status/code/
+request_id 를 보존한다(§13 "원본 status, code, request ID를 유지한다").
+
+```
+TeamverSDKError
+├─ ConfigurationError
+├─ AuthenticationError        (401)
+├─ AuthorizationError         (403)
+├─ NotFoundError              (404)
+├─ ConflictError              (409)
+│  ├─ IdempotencyConflictError
+│  └─ VersionConflictError
+├─ RateLimitError             (429)
+├─ TemporaryUnavailableError  (502/503/504)
+└─ TransportError             (네트워크/타임아웃)
+```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class TeamverSDKError(Exception):
+    """모든 SDK 예외의 루트. 원본 진단 정보를 보존한다."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+        retryable: bool = False,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+        self.retryable = retryable
+        self.details = details or {}
+
+    def __repr__(self) -> str:  # secret 노출 방지: message 만 요약.
+        return (
+            f"{type(self).__name__}(code={self.code!r}, status={self.status_code}, "
+            f"request_id={self.request_id!r})"
+        )
+
+
+class ConfigurationError(TeamverSDKError):
+    """필수 설정 누락(토큰/base URL 등)."""
+
+
+class AuthenticationError(TeamverSDKError):
+    """401 — 자격증명 오류(재시도 금지)."""
+
+
+class AuthorizationError(TeamverSDKError):
+    """403 — 권한/정책 오류(재시도 금지)."""
+
+
+class NotFoundError(TeamverSDKError):
+    """404."""
+
+
+class ConflictError(TeamverSDKError):
+    """409 계열 기본."""
+
+
+class IdempotencyConflictError(ConflictError):
+    """동일 idempotency key, 다른 body."""
+
+
+class VersionConflictError(ConflictError):
+    """optimistic lock 버전 충돌."""
+
+
+class RateLimitError(TeamverSDKError):
+    """429 — backoff 재시도 대상."""
+
+    def __init__(self, *args: Any, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class TemporaryUnavailableError(TeamverSDKError):
+    """502/503/504 — 제한적 재시도 대상."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(*args, **kwargs)
+
+
+class TransportError(TeamverSDKError):
+    """네트워크 실패/타임아웃 — 재시도 대상."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(*args, **kwargs)
+
+
+# HTTP status → 예외 클래스 매핑(409 은 code 로 세분).
+def error_for_status(
+    status_code: int,
+    *,
+    message: str,
+    code: Optional[str] = None,
+    request_id: Optional[str] = None,
+    details: Optional[dict[str, Any]] = None,
+    retry_after: Optional[float] = None,
+) -> TeamverSDKError:
+    """정규화된 오류 payload → 알맞은 예외 인스턴스."""
+    common = dict(code=code, status_code=status_code, request_id=request_id, details=details)
+    if status_code == 401:
+        return AuthenticationError(message, **common)
+    if status_code == 403:
+        return AuthorizationError(message, **common)
+    if status_code == 404:
+        return NotFoundError(message, **common)
+    if status_code == 409:
+        if code == "idempotency_conflict":
+            return IdempotencyConflictError(message, **common)
+        if code in ("version_conflict", "job_version_conflict"):
+            return VersionConflictError(message, **common)
+        return ConflictError(message, **common)
+    if status_code == 429:
+        return RateLimitError(message, retry_after=retry_after, **common)
+    if status_code in (502, 503, 504):
+        return TemporaryUnavailableError(message, **common)
+    return TeamverSDKError(message, **common)
+
+
+def parse_error_body(body: Any) -> tuple[Optional[str], str, dict[str, Any]]:
+    """Main ``error`` / FastAPI ``detail`` / legacy shape → (code, message, details).
+
+    16-1 §3 "오류 모델 불일치": Main 오류가 단일 schema 라고 가정하지 않는다.
+    """
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            return (
+                err.get("code"),
+                str(err.get("message") or err.get("code") or "request failed"),
+                err.get("details") or {},
+            )
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return (None, detail, {})
+        if isinstance(detail, dict):
+            return (detail.get("code"), str(detail.get("message") or "request failed"), detail)
+        if isinstance(detail, list):  # FastAPI validation errors
+            return ("validation_error", "request validation failed", {"errors": detail})
+        if body.get("message"):
+            return (body.get("code"), str(body["message"]), body)
+    return (None, "request failed", {} if not isinstance(body, dict) else body)