vardast 0.1.0__tar.gz

vardast-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Secrets / local
+.env
+.env.*
+!.env.example
+*.pem
+
+# Packaging
+pip-wheel-metadata/

vardast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vardast
+
+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.

vardast-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+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.

vardast-0.1.0/README.md

@@ -0,0 +1,151 @@
+# 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.

vardast-0.1.0/examples/list_assistants.py

@@ -0,0 +1,32 @@
+"""List assistants and usage for the authenticated account."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from vardast import Vardast
+
+
+def main() -> int:
+    api_key = os.environ.get("VARDAST_API_KEY")
+    if not api_key:
+        print("Set VARDAST_API_KEY to your Public API key.", file=sys.stderr)
+        return 1
+
+    with Vardast(api_key=api_key) as client:
+        for assistant in client.list_assistants():
+            print(f"- {assistant.assistant_name} ({assistant.id}) model={assistant.model}")
+
+        usage = client.get_usage_info()
+        if usage.response:
+            print(
+                f"credits: chat={usage.response.chat_credit} "
+                f"contacts={usage.response.contact_credit} "
+                f"allowed={usage.response.is_allowed}"
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vardast-0.1.0/examples/quickstart.py

@@ -0,0 +1,58 @@
+"""Quickstart: list channels and process a chat message.
+
+Set ``VARDAST_API_KEY`` in your environment before running::
+
+    export VARDAST_API_KEY=your-key
+    python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from vardast import AuthenticationError, Vardast
+
+
+def main() -> int:
+    api_key = os.environ.get("VARDAST_API_KEY")
+    if not api_key:
+        print("Set VARDAST_API_KEY to your Public API key.", file=sys.stderr)
+        return 1
+
+    with Vardast(api_key=api_key) as client:
+        try:
+            channels = client.list_channels()
+        except AuthenticationError as exc:
+            print(f"Authentication failed: {exc}", file=sys.stderr)
+            return 1
+
+        if not channels:
+            print("No channels found for this account.")
+            return 0
+
+        channel = channels[0]
+        print(f"Using channel {channel.name!r} ({channel.id}) on {channel.platform}")
+
+        # Replace contact_id with a real contact from your account before sending.
+        contact_id = os.environ.get("VARDAST_CONTACT_ID")
+        if not contact_id:
+            print("Set VARDAST_CONTACT_ID to process a message against a contact.")
+            return 0
+
+        result = client.process_message(
+            message="Hello from the Vardast Python SDK",
+            channel_id=channel.id,
+            contact_id=contact_id,
+        )
+        print(f"status={result.status}")
+        if result.response:
+            print(result.response)
+        if result.error:
+            print(f"error={result.error}", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vardast-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vardast"
+version = "0.1.0"
+description = "Official Python SDK for the Vardast Public API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "Vardast", email = "hello@vardast.chat" },
+]
+keywords = ["vardast", "api", "sdk", "chat", "messenger", "ai"]
+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.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.6,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/technicalvardast/vardast-python"
+Documentation = "https://vardast.chat/docs/public-api"
+Repository = "https://github.com/technicalvardast/vardast-python"
+Issues = "https://github.com/technicalvardast/vardast-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vardast"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/examples",
+  "/README.md",
+  "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

vardast-0.1.0/src/vardast/__init__.py

@@ -0,0 +1,62 @@
+"""Official Python SDK for the Vardast Public API."""
+
+from vardast.client import AsyncVardast, Vardast
+from vardast.exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    VardastAPIError,
+    VardastError,
+    ValidationError,
+)
+from vardast.models import (
+    Assistant,
+    AssistantCreate,
+    Channel,
+    ChannelContact,
+    ChannelOrder,
+    Contact,
+    Message,
+    OrderItem,
+    Paginated,
+    ProcessChatResponse,
+    Prompt,
+    PromptCreate,
+    PromptCreateResponse,
+    UsageActivity,
+    UsageActivityPeriodItem,
+    UsageInfo,
+    UsageInfoData,
+)
+
+__all__ = [
+    "Assistant",
+    "AssistantCreate",
+    "AsyncVardast",
+    "AuthenticationError",
+    "Channel",
+    "ChannelContact",
+    "ChannelOrder",
+    "Contact",
+    "Message",
+    "NotFoundError",
+    "OrderItem",
+    "Paginated",
+    "ProcessChatResponse",
+    "Prompt",
+    "PromptCreate",
+    "PromptCreateResponse",
+    "RateLimitError",
+    "ServerError",
+    "UsageActivity",
+    "UsageActivityPeriodItem",
+    "UsageInfo",
+    "UsageInfoData",
+    "ValidationError",
+    "Vardast",
+    "VardastAPIError",
+    "VardastError",
+]
+
+__version__ = "0.1.0"