teamver-sdk-core 0.1.1

Shared core for Teamver SDKs: async transport, unified errors, retry, context, pagination, masking

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

pip install teamver-sdk-core

Python ≥ 3.11.

Quick start

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_CHANNEL_API_BASE / 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

Development

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.