Metadata-Version: 2.4
Name: siptel
Version: 0.1.0
Summary: Official Python SDK for the SIPTEL REST API (voice, AI agents, SMS, numbers, SIP).
Project-URL: Homepage, https://siptel.ai
Project-URL: Documentation, https://siptel.ai/docs
Project-URL: Repository, https://github.com/siptel-ai/siptel-python
Author: SIPTEL
License-Expression: MIT
License-File: LICENSE
Keywords: api,sdk,siptel,sms,telephony,voice,voip
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Telephony
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests<3,>=2.28.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# SIPTEL Python SDK

Official Python client for the **[SIPTEL REST API](https://siptel.ai/docs)** — AI voice agents, programmable Voice API, SMS, phone numbers, and SIP trunks.

## Install

```bash
pip install siptel
```

## Quick start

Set your API key (from the [dashboard](https://siptel.ai/dashboard)):

```bash
export SIPTEL_API_KEY="sk_live_..."   # Linux/macOS
# set SIPTEL_API_KEY=sk_live_...      # Windows CMD
```

```python
from siptel import Client

client = Client()

# List AI agents
agents = client.agent.list_agents()

# Outbound AI agent call (see docs for all parameters)
result = client.agent.create_call(
    phone_number="+31612345678",
    caller_id="+31201234567",
    voice="Rachel",
    record=True,
    voicemail_action="hangup",
    greeting_message="Hello!",
    task_prompt="You are a helpful assistant.",
    language="en-US",
)

# Voice API
call = client.voice.retrieve_call("CA20251109171204335505")

# SMS
client.sms.send(
    app_id="...",
    phone_number="+31612345678",
    sender_id="SIPTEL",
    text="Hello from SIPTEL",
)

# Numbers
numbers = client.numbers.list()
```

## Authentication

All requests use **`Authorization: Bearer <api_key>`**. You can pass the key explicitly:

```python
client = Client(api_key="sk_live_...")
```

## Configuration

| Option | Environment variable | Default |
|--------|---------------------|---------|
| API key | `SIPTEL_API_KEY` | — |
| Base URL | `SIPTEL_BASE_URL` *(not auto-read; pass `base_url=`)* | `https://api.siptel.ai` |
| `User-Agent` | `SIPTEL_USER_AGENT` | `SiptelPythonSDK/0.1` |

```python
client = Client(
    api_key="sk_live_...",
    base_url="https://api.siptel.ai",
    timeout=60.0,
)
```

## Resource layout (Telnyx-style)

| Namespace | API area |
|-----------|----------|
| `client.agent` | AI agent calls, list/get agents |
| `client.voice` | Voice API (play, gather, transfer, hangup, call status) |
| `client.sip` | SIP users / trunks |
| `client.sms` | Send SMS, list SMS apps |
| `client.numbers` | List/search/purchase/assign numbers |

## Errors

The SDK raises typed exceptions on HTTP error responses:

```python
from siptel import (
    Client,
    AuthenticationError,
    InvalidRequestError,
    NotFoundError,
    PaymentRequiredError,
    RateLimitError,
    APIError,
)

try:
    client.sms.send(...)
except InvalidRequestError as e:
    print(e.status_code, e.response_body)
```

## Low-level API

For endpoints not yet wrapped, use the escape hatch:

```python
client.post("/v1/agent/call", json={...})
client.get("/v1/custom/path")
```

## Requirements

- Python 3.10+
- `requests`

## Development

```bash
cd sdk/siptel-python
pip install -e ".[dev]"
ruff check src
pytest
```

## GitHub

- **CI:** `.github/workflows/siptel-python-ci.yml` runs Ruff + pytest on changes under `sdk/siptel-python/`.
- **PyPI:** `.github/workflows/workflow.yml` publishes on tags `v*` (e.g. `v0.1.0`) using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no long-lived API token in GitHub secrets).

### `siptelai/siptel` repo

Push this repo (or mirror the SDK + workflows there). The publish workflow expects the layout **`sdk/siptel-python/`** at the repo root. PyPI pending publisher must list **workflow file:** `workflow.yml` and **repository:** `siptelai/siptel`.

### Standalone SDK-only repo

If the repo root *is* the Python package (no `sdk/` folder), change `working-directory` and `packages-dir` in `workflow.yml` to match (often `.` and `dist/`).

## Publishing to PyPI (manual)

1. Bump `version` in `pyproject.toml` and `siptel.__version__` in `src/siptel/__init__.py`.
2. Build: `python -m build`
3. Upload: `python -m twine upload dist/*` (PyPI API token as password, user `__token__`).

> **PyPI project name:** the distribution is named `siptel`. If that name is taken on PyPI, change `[project] name` in `pyproject.toml` (e.g. `siptel-ai`) while keeping `packages` / import name as needed.

## License

MIT — see [LICENSE](LICENSE).
