Metadata-Version: 2.4
Name: teamver-sdk-core
Version: 0.1.2
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/teamver-sdk-docs/tree/main/sdk-core
Project-URL: Issues, https://github.com/NeuralStudioKr/teamver-sdk-docs/issues
Project-URL: Changelog, https://github.com/NeuralStudioKr/teamver-sdk-docs/blob/main/sdk-core/changelog.md
Author-email: NeuralStudio <dev@neuralstudio.kr>
Maintainer-email: NeuralStudio <dev@neuralstudio.kr>
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.

## 변경 이력

| 일시 (KST) | 변경 내용 |
|---|-----|
| 2026-08-02 22:55 | production API host defaults (`defaults.py`) 추가 |

## 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 |
| --- | --- |
| `defaults` | Production API hosts: `https://api.teamver.com`, `https://agent-api.teamver.com`, `https://mail-api.teamver.com` |
| `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 |

### Default API hosts (SSOT)

| Constant | Host | Used by |
| --- | --- | --- |
| `DEFAULT_MAIN_API_BASE` | `https://api.teamver.com` | channel/Drive/DM, be-sdk, app-sdk |
| `DEFAULT_AGENT_API_BASE` | `https://agent-api.teamver.com` | agent-sdk jobs/heartbeat |
| `DEFAULT_MAIL_API_BASE` | `https://mail-api.teamver.com` | mail-agent, agent-sdk mail |

No path suffix (`/api`, `/v1`). Override per package via env.

## 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

## Documentation

Public docs: [github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/sdk-core](https://github.com/NeuralStudioKr/teamver-sdk-docs/tree/main/sdk-core)

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT — see [LICENSE](./LICENSE).
