Metadata-Version: 2.5
Name: vardast
Version: 0.1.0
Summary: Official Python SDK for the Vardast Public API
Project-URL: Homepage, https://github.com/technicalvardast/vardast-python
Project-URL: Documentation, https://vardast.chat/docs/public-api
Project-URL: Repository, https://github.com/technicalvardast/vardast-python
Project-URL: Issues, https://github.com/technicalvardast/vardast-python/issues
Author-email: Vardast <hello@vardast.chat>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,chat,messenger,sdk,vardast
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.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.27
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# Vardast Python SDK

Official Python client for the [Vardast Public API](https://vardast.chat/docs/public-api).

Package name on PyPI: **`vardast`**  
GitHub: [technicalvardast/vardast-python](https://github.com/technicalvardast/vardast-python)

## Install

```bash
pip install vardast
```

Requires Python 3.9+.

## Setup

1. Create or copy a Public API key from the Vardast panel (channel settings / Public API).
2. Pass it to the client as `api_key`. The SDK sends it on every request as the `X-API-Key` header.
3. Default base URL (override only for a private gateway):

```text
https://apigw.vardast.chat/uaa/public
```

```python
from vardast import Vardast

client = Vardast(
    api_key="your-api-key",
    # base_url="https://apigw.vardast.chat/uaa/public",  # default
)
```

Prefer a context manager so the HTTP client closes cleanly:

```python
with Vardast(api_key="your-api-key") as client:
    channels = client.list_channels()
```

Async support is available via `AsyncVardast`.

## Quickstart

```python
from vardast import Vardast

with Vardast(api_key="your-api-key") as client:
    channels = client.list_channels()
    channel = channels[0]

    result = client.process_message(
        message="Hello",
        channel_id=channel.id,
        contact_id="contact-uuid",
    )
    print(result.response)
```

See `examples/quickstart.py` and `examples/list_assistants.py`.

## Method reference

Methods map 1:1 to the documented Public API surface.

| Method | HTTP | Path |
| --- | --- | --- |
| `process_message(...)` | `POST` | `/messenger/api/chat/public/process` |
| `list_messages(channel_id, contact_id, page=1, size=20)` | `GET` | `/messenger/api/chat/{channel_id}/{contact_id}/` |
| `list_contacts(page=1, size=20, channel_ids=None, platform=None)` | `GET` | `/messenger/api/chat/contacts/` |
| `list_channels()` | `GET` | `/messenger/api/channel/` |
| `list_assistants()` | `GET` | `/messenger/api/assistants/` |
| `create_assistant(...)` | `POST` | `/messenger/api/assistants/` |
| `create_prompt(...)` | `POST` | `/messenger/api/prompts/` |
| `get_prompt(prompt_id)` | `GET` | `/messenger/api/prompts/{prompt_id}` |
| `list_channel_contacts(channel_id, id=None, page=1, page_size=20)` | `GET` | `/report/channel/{channel_id}/contacts` |
| `list_channel_orders(channel_id, order_id=None, page=1, page_size=20)` | `GET` | `/report/channel/{channel_id}/orders` |
| `get_usage_info()` | `GET` | `/payment/get-usage-info/` |
| `get_usage_activity(feature=..., ...)` | `GET` | `/payment/get-usage-activity/` |

`channel_ids` may be a comma-separated string or a sequence of IDs.  
`get_usage_activity` requires `feature` in `{id, date, mode, period}` plus the matching query fields from the docs.

Responses are typed Pydantic models (`Message`, `Channel`, `Assistant`, `Paginated[...]`, and so on). Extra JSON fields from the API are preserved.

### Errors

| Exception | When |
| --- | --- |
| `AuthenticationError` | HTTP 401 |
| `NotFoundError` | HTTP 404 |
| `ValidationError` | HTTP 400 / 422 |
| `RateLimitError` | HTTP 429 |
| `ServerError` | HTTP 5xx |
| `VardastAPIError` | Other API failures |
| `VardastError` | Client configuration errors |

API error bodies of the form `{"detail": "..."}` are surfaced on `exc.message` / `exc.detail`.

## Development

```bash
cd vardast-python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Publish to PyPI

### One-time Trusted Publisher setup (recommended)

1. Use the GitHub repository `technicalvardast/vardast-python`.
2. On [PyPI](https://pypi.org/manage/account/publishing/), add a Trusted Publisher:
   - Owner: `technicalvardast`
   - Repository: `vardast-python`
   - Workflow: `publish.yml`
   - Environment: `pypi` (optional but recommended)
3. Create a GitHub Environment named `pypi` if you scoped the publisher that way.

### Release with a version tag

```bash
# bump version in pyproject.toml and src/vardast/__init__.py
git commit -am "Release v0.1.0"
git tag v0.1.0
git push origin main --tags
```

Pushing a tag matching `v*` runs `.github/workflows/publish.yml`, which builds the sdist/wheel and uploads to PyPI via OIDC (Trusted Publisher). No long-lived PyPI token is required.

### Manual / token publish (fallback)

```bash
pip install build twine
python -m build
TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... twine upload dist/*
```

Store the token as the `PYPI_API_TOKEN` repository secret if you switch the publish workflow to token auth.

## License

MIT — see [LICENSE](LICENSE).

## Docs

- Public API: https://vardast.chat/docs/public-api
- Product (merchant catalog) API is separate and **not** covered by this SDK.
