vardast 0.1.0__py3-none-any.whl

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"

vardast/client.py

@@ -0,0 +1,690 @@
+"""Synchronous and asynchronous clients for the Vardast Public API."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from types import TracebackType
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Type, Union
+
+import httpx
+
+from vardast.exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    VardastAPIError,
+    VardastError,
+)
+from vardast.models import (
+    Assistant,
+    AssistantCreate,
+    AssistantsResponse,
+    Channel,
+    ChannelContact,
+    ChannelOrder,
+    ChannelsResponse,
+    Contact,
+    Message,
+    Paginated,
+    ProcessChatRequest,
+    ProcessChatResponse,
+    Prompt,
+    PromptCreate,
+    PromptCreateResponse,
+    UsageActivity,
+    UsageActivityEnvelope,
+    UsageActivityPeriodItem,
+    UsageInfo,
+)
+
+DEFAULT_BASE_URL = "https://apigw.vardast.chat/uaa/public"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _extract_detail(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        if "detail" in payload:
+            return payload["detail"]
+        if "error" in payload:
+            return payload["error"]
+        if "message" in payload:
+            return payload["message"]
+    return payload
+
+
+def _format_detail(detail: Any) -> str:
+    if detail is None:
+        return "Request failed"
+    if isinstance(detail, str):
+        return detail
+    return str(detail)
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    try:
+        payload: Any = response.json()
+    except ValueError:
+        payload = response.text
+
+    detail = _extract_detail(payload)
+    message = _format_detail(detail)
+    status = response.status_code
+    kwargs = {"status_code": status, "detail": detail, "response": response}
+
+    if status in (400, 422):
+        raise ValidationError(message, **kwargs)
+    if status == 401:
+        raise AuthenticationError(message, **kwargs)
+    if status == 404:
+        raise NotFoundError(message, **kwargs)
+    if status == 429:
+        raise RateLimitError(message, **kwargs)
+    if status >= 500:
+        raise ServerError(message, **kwargs)
+    raise VardastAPIError(message, **kwargs)
+
+
+def _serialize_datetime(value: Union[str, datetime, date]) -> str:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+class _BaseClient:
+    """Shared configuration and request helpers."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        if not api_key or not str(api_key).strip():
+            raise VardastError("api_key is required")
+
+        self.api_key = str(api_key).strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._extra_headers = dict(headers or {})
+
+    def _default_headers(self) -> Dict[str, str]:
+        headers = {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": "vardast-python/0.1.0",
+        }
+        headers.update(self._extra_headers)
+        return headers
+
+
+class Vardast(_BaseClient):
+    """Synchronous client for the Vardast Public API.
+
+    Example::
+
+        from vardast import Vardast
+
+        client = Vardast(api_key="your-api-key")
+        channels = client.list_channels()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, headers=headers)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            base_url=f"{self.base_url}/",
+            headers=self._default_headers(),
+            timeout=self.timeout,
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Vardast":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+    ) -> Any:
+        url = path if path.startswith("http") else path.lstrip("/")
+        response = self._client.request(
+            method,
+            url,
+            params=_clean_params(params),
+            json=json,
+        )
+        _raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    # --- Chat ---
+
+    def process_message(
+        self,
+        *,
+        message: str,
+        channel_id: str,
+        contact_id: str,
+        assistant_id: Optional[str] = None,
+    ) -> ProcessChatResponse:
+        """Process a chat message and return the AI response.
+
+        Maps to ``POST /messenger/api/chat/public/process``.
+        """
+        body = ProcessChatRequest(
+            message=message,
+            channel_id=channel_id,
+            contact_id=contact_id,
+            assistant_id=assistant_id,
+        )
+        data = self.request(
+            "POST",
+            "/messenger/api/chat/public/process",
+            json=body.model_dump(exclude_none=True),
+        )
+        return ProcessChatResponse.model_validate(data)
+
+    def list_messages(
+        self,
+        channel_id: str,
+        contact_id: str,
+        *,
+        page: int = 1,
+        size: int = 20,
+    ) -> Paginated[Message]:
+        """List messages for a contact on a channel.
+
+        Maps to ``GET /messenger/api/chat/{channel_id}/{contact_id}/``.
+        """
+        data = self.request(
+            "GET",
+            f"/messenger/api/chat/{channel_id}/{contact_id}/",
+            params={"page": page, "size": size},
+        )
+        return Paginated[Message].model_validate(data)
+
+    def list_contacts(
+        self,
+        *,
+        page: int = 1,
+        size: int = 20,
+        channel_ids: Optional[Union[str, Sequence[str]]] = None,
+        platform: Optional[str] = None,
+    ) -> Paginated[Contact]:
+        """List contacts across channels.
+
+        Maps to ``GET /messenger/api/chat/contacts/``.
+        """
+        params: Dict[str, Any] = {"page": page, "size": size}
+        if channel_ids is not None:
+            params["channel_ids"] = (
+                channel_ids if isinstance(channel_ids, str) else ",".join(channel_ids)
+            )
+        if platform is not None:
+            params["platform"] = platform
+        data = self.request("GET", "/messenger/api/chat/contacts/", params=params)
+        return Paginated[Contact].model_validate(data)
+
+    # --- Channels ---
+
+    def list_channels(self) -> List[Channel]:
+        """List all channels for the authenticated account.
+
+        Maps to ``GET /messenger/api/channel/``.
+        """
+        data = self.request("GET", "/messenger/api/channel/")
+        if isinstance(data, list):
+            return [Channel.model_validate(item) for item in data]
+        return ChannelsResponse.model_validate(data).items
+
+    # --- Assistants ---
+
+    def list_assistants(self) -> List[Assistant]:
+        """List assistants sorted newest first.
+
+        Maps to ``GET /messenger/api/assistants/``.
+        """
+        data = self.request("GET", "/messenger/api/assistants/")
+        if isinstance(data, list):
+            return [Assistant.model_validate(item) for item in data]
+        return AssistantsResponse.model_validate(data).items
+
+    def create_assistant(
+        self,
+        *,
+        assistant_name: str,
+        model: str,
+        api_key: str,
+        kb_id: Optional[str] = None,
+        functions: Optional[Sequence[str]] = None,
+    ) -> Assistant:
+        """Create a new assistant.
+
+        Maps to ``POST /messenger/api/assistants/``.
+        """
+        body = AssistantCreate(
+            assistant_name=assistant_name,
+            model=model,
+            api_key=api_key,
+            kb_id=kb_id,
+            functions=list(functions) if functions is not None else None,
+        )
+        data = self.request(
+            "POST",
+            "/messenger/api/assistants/",
+            json=body.model_dump(exclude_none=True),
+        )
+        return Assistant.model_validate(data)
+
+    # --- Prompts ---
+
+    def create_prompt(
+        self,
+        *,
+        assistant_id: str,
+        text: str,
+        prompt_json: Mapping[str, Any],
+        language: str = "EN",
+        created_by: str,
+    ) -> PromptCreateResponse:
+        """Create a prompt for an assistant.
+
+        Maps to ``POST /messenger/api/prompts/``.
+        ``language`` defaults to ``\"EN\"`` (also accepts ``\"FA\"``).
+        """
+        body = PromptCreate(
+            assistant_id=assistant_id,
+            text=text,
+            prompt_json=dict(prompt_json),
+            language=language,
+            created_by=created_by,
+        )
+        data = self.request(
+            "POST",
+            "/messenger/api/prompts/",
+            json=body.model_dump(exclude_none=True),
+        )
+        return PromptCreateResponse.model_validate(data)
+
+    def get_prompt(self, prompt_id: str) -> Prompt:
+        """Fetch a prompt by ID.
+
+        Maps to ``GET /messenger/api/prompts/{prompt_id}``.
+        """
+        data = self.request("GET", f"/messenger/api/prompts/{prompt_id}")
+        return Prompt.model_validate(data)
+
+    # --- Reports ---
+
+    def list_channel_contacts(
+        self,
+        channel_id: str,
+        *,
+        id: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Paginated[ChannelContact]:
+        """List report contacts for a channel.
+
+        Maps to ``GET /report/channel/{channel_id}/contacts``.
+        """
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if id is not None:
+            params["id"] = id
+        data = self.request(
+            "GET",
+            f"/report/channel/{channel_id}/contacts",
+            params=params,
+        )
+        return Paginated[ChannelContact].model_validate(data)
+
+    def list_channel_orders(
+        self,
+        channel_id: str,
+        *,
+        order_id: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Paginated[ChannelOrder]:
+        """List report orders for a channel.
+
+        Maps to ``GET /report/channel/{channel_id}/orders``.
+        """
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if order_id is not None:
+            params["order_id"] = order_id
+        data = self.request(
+            "GET",
+            f"/report/channel/{channel_id}/orders",
+            params=params,
+        )
+        return Paginated[ChannelOrder].model_validate(data)
+
+    # --- Billing / usage ---
+
+    def get_usage_info(self) -> UsageInfo:
+        """Return account usage and credit information.
+
+        Maps to ``GET /payment/get-usage-info/``.
+        """
+        data = self.request("GET", "/payment/get-usage-info/")
+        return UsageInfo.model_validate(data)
+
+    def get_usage_activity(
+        self,
+        *,
+        feature: str,
+        activity_id: Optional[str] = None,
+        date: Optional[Union[str, datetime, date]] = None,
+        mode: Optional[str] = None,
+        start_date: Optional[Union[str, datetime, date]] = None,
+        end_date: Optional[Union[str, datetime, date]] = None,
+    ) -> Union[UsageActivity, List[UsageActivityPeriodItem]]:
+        """Fetch usage activity by id, date, mode, or period.
+
+        Maps to ``GET /payment/get-usage-activity/``.
+
+        ``feature`` must be one of ``id``, ``date``, ``mode``, or ``period``.
+        Required companion query params depend on ``feature`` as documented.
+        """
+        params: Dict[str, Any] = {"feature": feature}
+        if activity_id is not None:
+            params["activity_id"] = activity_id
+        if date is not None:
+            params["date"] = _serialize_datetime(date)
+        if mode is not None:
+            params["mode"] = mode
+        if start_date is not None:
+            params["start_date"] = _serialize_datetime(start_date)
+        if end_date is not None:
+            params["end_date"] = _serialize_datetime(end_date)
+
+        data = self.request("GET", "/payment/get-usage-activity/", params=params)
+        envelope = UsageActivityEnvelope.model_validate(data)
+        if envelope.response is None:
+            raise VardastAPIError("Usage activity response was empty", detail=data)
+        return envelope.response
+
+
+class AsyncVardast(_BaseClient):
+    """Asynchronous client for the Vardast Public API.
+
+    Example::
+
+        async with AsyncVardast(api_key="your-api-key") as client:
+            channels = await client.list_channels()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, headers=headers)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            base_url=f"{self.base_url}/",
+            headers=self._default_headers(),
+            timeout=self.timeout,
+        )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncVardast":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+    ) -> Any:
+        url = path if path.startswith("http") else path.lstrip("/")
+        response = await self._client.request(
+            method,
+            url,
+            params=_clean_params(params),
+            json=json,
+        )
+        _raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def process_message(
+        self,
+        *,
+        message: str,
+        channel_id: str,
+        contact_id: str,
+        assistant_id: Optional[str] = None,
+    ) -> ProcessChatResponse:
+        body = ProcessChatRequest(
+            message=message,
+            channel_id=channel_id,
+            contact_id=contact_id,
+            assistant_id=assistant_id,
+        )
+        data = await self.request(
+            "POST",
+            "/messenger/api/chat/public/process",
+            json=body.model_dump(exclude_none=True),
+        )
+        return ProcessChatResponse.model_validate(data)
+
+    async def list_messages(
+        self,
+        channel_id: str,
+        contact_id: str,
+        *,
+        page: int = 1,
+        size: int = 20,
+    ) -> Paginated[Message]:
+        data = await self.request(
+            "GET",
+            f"/messenger/api/chat/{channel_id}/{contact_id}/",
+            params={"page": page, "size": size},
+        )
+        return Paginated[Message].model_validate(data)
+
+    async def list_contacts(
+        self,
+        *,
+        page: int = 1,
+        size: int = 20,
+        channel_ids: Optional[Union[str, Sequence[str]]] = None,
+        platform: Optional[str] = None,
+    ) -> Paginated[Contact]:
+        params: Dict[str, Any] = {"page": page, "size": size}
+        if channel_ids is not None:
+            params["channel_ids"] = (
+                channel_ids if isinstance(channel_ids, str) else ",".join(channel_ids)
+            )
+        if platform is not None:
+            params["platform"] = platform
+        data = await self.request("GET", "/messenger/api/chat/contacts/", params=params)
+        return Paginated[Contact].model_validate(data)
+
+    async def list_channels(self) -> List[Channel]:
+        data = await self.request("GET", "/messenger/api/channel/")
+        if isinstance(data, list):
+            return [Channel.model_validate(item) for item in data]
+        return ChannelsResponse.model_validate(data).items
+
+    async def list_assistants(self) -> List[Assistant]:
+        data = await self.request("GET", "/messenger/api/assistants/")
+        if isinstance(data, list):
+            return [Assistant.model_validate(item) for item in data]
+        return AssistantsResponse.model_validate(data).items
+
+    async def create_assistant(
+        self,
+        *,
+        assistant_name: str,
+        model: str,
+        api_key: str,
+        kb_id: Optional[str] = None,
+        functions: Optional[Sequence[str]] = None,
+    ) -> Assistant:
+        body = AssistantCreate(
+            assistant_name=assistant_name,
+            model=model,
+            api_key=api_key,
+            kb_id=kb_id,
+            functions=list(functions) if functions is not None else None,
+        )
+        data = await self.request(
+            "POST",
+            "/messenger/api/assistants/",
+            json=body.model_dump(exclude_none=True),
+        )
+        return Assistant.model_validate(data)
+
+    async def create_prompt(
+        self,
+        *,
+        assistant_id: str,
+        text: str,
+        prompt_json: Mapping[str, Any],
+        language: str = "EN",
+        created_by: str,
+    ) -> PromptCreateResponse:
+        body = PromptCreate(
+            assistant_id=assistant_id,
+            text=text,
+            prompt_json=dict(prompt_json),
+            language=language,
+            created_by=created_by,
+        )
+        data = await self.request(
+            "POST",
+            "/messenger/api/prompts/",
+            json=body.model_dump(exclude_none=True),
+        )
+        return PromptCreateResponse.model_validate(data)
+
+    async def get_prompt(self, prompt_id: str) -> Prompt:
+        data = await self.request("GET", f"/messenger/api/prompts/{prompt_id}")
+        return Prompt.model_validate(data)
+
+    async def list_channel_contacts(
+        self,
+        channel_id: str,
+        *,
+        id: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Paginated[ChannelContact]:
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if id is not None:
+            params["id"] = id
+        data = await self.request(
+            "GET",
+            f"/report/channel/{channel_id}/contacts",
+            params=params,
+        )
+        return Paginated[ChannelContact].model_validate(data)
+
+    async def list_channel_orders(
+        self,
+        channel_id: str,
+        *,
+        order_id: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Paginated[ChannelOrder]:
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if order_id is not None:
+            params["order_id"] = order_id
+        data = await self.request(
+            "GET",
+            f"/report/channel/{channel_id}/orders",
+            params=params,
+        )
+        return Paginated[ChannelOrder].model_validate(data)
+
+    async def get_usage_info(self) -> UsageInfo:
+        data = await self.request("GET", "/payment/get-usage-info/")
+        return UsageInfo.model_validate(data)
+
+    async def get_usage_activity(
+        self,
+        *,
+        feature: str,
+        activity_id: Optional[str] = None,
+        date: Optional[Union[str, datetime, date]] = None,
+        mode: Optional[str] = None,
+        start_date: Optional[Union[str, datetime, date]] = None,
+        end_date: Optional[Union[str, datetime, date]] = None,
+    ) -> Union[UsageActivity, List[UsageActivityPeriodItem]]:
+        params: Dict[str, Any] = {"feature": feature}
+        if activity_id is not None:
+            params["activity_id"] = activity_id
+        if date is not None:
+            params["date"] = _serialize_datetime(date)
+        if mode is not None:
+            params["mode"] = mode
+        if start_date is not None:
+            params["start_date"] = _serialize_datetime(start_date)
+        if end_date is not None:
+            params["end_date"] = _serialize_datetime(end_date)
+
+        data = await self.request("GET", "/payment/get-usage-activity/", params=params)
+        envelope = UsageActivityEnvelope.model_validate(data)
+        if envelope.response is None:
+            raise VardastAPIError("Usage activity response was empty", detail=data)
+        return envelope.response
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    if params is None:
+        return None
+    return {key: value for key, value in params.items() if value is not None}

vardast/exceptions.py

@@ -0,0 +1,52 @@
+"""Exceptions raised by the Vardast SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class VardastError(Exception):
+    """Base exception for all Vardast SDK errors."""
+
+
+class VardastAPIError(VardastError):
+    """HTTP or API-level error returned by the Vardast Public API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        detail: Any = None,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.status_code is not None:
+            return f"{self.status_code}: {self.message}"
+        return self.message
+
+
+class AuthenticationError(VardastAPIError):
+    """Raised when authentication fails (HTTP 401)."""
+
+
+class NotFoundError(VardastAPIError):
+    """Raised when a resource is not found (HTTP 404)."""
+
+
+class ValidationError(VardastAPIError):
+    """Raised when the request is invalid (HTTP 400 / 422)."""
+
+
+class RateLimitError(VardastAPIError):
+    """Raised when the API rate limit is exceeded (HTTP 429)."""
+
+
+class ServerError(VardastAPIError):
+    """Raised when the API returns a server error (HTTP 5xx)."""

vardast/models.py

@@ -0,0 +1,210 @@
+"""Pydantic models for Vardast Public API request and response payloads."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Dict, Generic, List, Optional, TypeVar, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class APIModel(BaseModel):
+    """Base model with permissive parsing for evolving API fields."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class Paginated(APIModel, Generic[T]):
+    """Standard paginated list envelope used across messenger endpoints."""
+
+    items: List[T] = Field(default_factory=list)
+    total: int = 0
+    page: int = 1
+    size: int = 20
+    pages: int = 0
+
+
+class ProcessChatRequest(APIModel):
+    message: str
+    channel_id: str
+    contact_id: str
+    assistant_id: Optional[str] = None
+
+
+class ProcessChatResponse(APIModel):
+    status: str
+    message_id: Optional[str] = None
+    response: Optional[str] = None
+    error: Optional[str] = None
+
+
+class Message(APIModel):
+    id: str
+    text: Optional[str] = None
+    platform: Optional[str] = None
+    sender_id: Optional[str] = None
+    receiver_id: Optional[str] = None
+    is_output: Optional[bool] = None
+    ai_created: Optional[bool] = None
+    channel_id: Optional[str] = None
+    timestamp: Optional[datetime] = None
+    is_in_thread: Optional[bool] = None
+
+
+class Contact(APIModel):
+    id: str
+    name: Optional[str] = None
+    username: Optional[str] = None
+    identifier: Optional[str] = None
+    platform: Optional[str] = None
+    channel_id: Optional[str] = None
+    is_stopped: Optional[bool] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class Channel(APIModel):
+    id: str
+    name: Optional[str] = None
+    platform: Optional[str] = None
+    user_id: Optional[str] = None
+    identifier: Optional[str] = None
+    access_token: Optional[str] = None
+    assistant: Optional[str] = None
+    is_stopped: Optional[bool] = None
+    reply_to_story: Optional[bool] = None
+    reply_to_comments: Optional[bool] = None
+    account_id: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class ChannelsResponse(APIModel):
+    items: List[Channel] = Field(default_factory=list)
+
+
+class Assistant(APIModel):
+    id: str
+    assistant_name: Optional[str] = None
+    model: Optional[str] = None
+    api_key: Optional[str] = None
+    kb_id: Optional[str] = None
+    functions: Optional[List[str]] = None
+    user_id: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class AssistantsResponse(APIModel):
+    items: List[Assistant] = Field(default_factory=list)
+
+
+class AssistantCreate(APIModel):
+    assistant_name: str
+    model: str
+    api_key: str
+    kb_id: Optional[str] = None
+    functions: Optional[List[str]] = None
+
+
+class PromptCreate(APIModel):
+    assistant_id: str
+    text: str
+    prompt_json: Dict[str, Any]
+    language: str = "EN"
+    created_by: str
+
+
+class PromptCreateResponse(APIModel):
+    prompt_id: str
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    user_id: Optional[str] = None
+
+
+class Prompt(APIModel):
+    prompt_id: str
+    assistant_id: Optional[str] = None
+    text: Optional[str] = None
+    prompt_json: Optional[Dict[str, Any]] = None
+    language: Optional[str] = None
+    created_by: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    user_id: Optional[str] = None
+
+
+class OrderItem(APIModel):
+    product_name: str
+    quantity: int
+    variants: Optional[str] = None
+
+
+class ChannelContact(APIModel):
+    id: str
+    contact_id: Optional[str] = None
+    channel_id: Optional[str] = None
+    full_name: Optional[str] = None
+    phone_number: Optional[str] = None
+    detailed_address: Optional[str] = None
+    postal_code: Optional[str] = None
+    username: Optional[str] = None
+    platform: Optional[str] = None
+    comment: Optional[str] = None
+    order_list: Optional[List[OrderItem]] = None
+    created_at: Optional[datetime] = None
+
+
+class ChannelOrder(APIModel):
+    id: str
+    contact_id: Optional[str] = None
+    channel_id: Optional[str] = None
+    full_name: Optional[str] = None
+    phone_number: Optional[str] = None
+    detailed_address: Optional[str] = None
+    postal_code: Optional[str] = None
+    username: Optional[str] = None
+    platform: Optional[str] = None
+    comment: Optional[str] = None
+    order_list: Optional[List[OrderItem]] = None
+    created_at: Optional[datetime] = None
+
+
+class UsageInfoData(APIModel):
+    user_id: Optional[str] = None
+    mode: Optional[str] = None
+    active_features: Optional[Dict[str, bool]] = None
+    chat_credit: Optional[int] = None
+    all_chat_credit: Optional[int] = None
+    total_chats: Optional[int] = None
+    contact_credit: Optional[int] = None
+    total_contacts: Optional[int] = None
+    is_allowed: Optional[bool] = None
+    next_due_date: Optional[datetime] = None
+    time_credit: Optional[datetime] = None
+
+
+class UsageInfo(APIModel):
+    status: Optional[str] = None
+    response: Optional[UsageInfoData] = None
+
+
+class UsageActivity(APIModel):
+    id: Optional[str] = None
+    user_id: Optional[str] = None
+    date: Optional[Union[date, datetime, str]] = None
+    new_contacts: Optional[int] = None
+    message_requests: Optional[int] = None
+
+
+class UsageActivityPeriodItem(APIModel):
+    date: Optional[Union[date, datetime, str]] = None
+    total_new_contacts: Optional[int] = None
+    total_message_requests: Optional[int] = None
+
+
+class UsageActivityEnvelope(APIModel):
+    status: Optional[str] = None
+    response: Optional[Union[UsageActivity, List[UsageActivityPeriodItem]]] = None

vardast/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 typed package distribution.

vardast-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+vardast/__init__.py,sha256=DVj1L0gxLaf-gKP_kbkJiM1HndumdyJhmnVaSSS-prk,1185
+vardast/client.py,sha256=lgG8hWiVo1fQ0e9h6XvoI7XiKOGzCqjLPK9C320PxQ0,21200
+vardast/exceptions.py,sha256=op1GDt5jqd_BHmgbPJLmzJyOMOv4p0kIGvMu2Y91zvs,1327
+vardast/models.py,sha256=HUUqNiepGsY7jWlABWQAO27TOYMhbhhnBHlxt7x64Z0,5772
+vardast/py.typed,sha256=lMktV_2kqa2aDRWTF8a7dClMxxIUMAbf1PcXU0nilsk,49
+vardast-0.1.0.dist-info/METADATA,sha256=ku-Nvef031oHjiES2fAUituxMUgS7CRJ5N7vDeKypLw,6002
+vardast-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+vardast-0.1.0.dist-info/licenses/LICENSE,sha256=pe6mAA_r1Sg12HXoy5hKY5wYJIaTumzv_XqJd6GJkdE,1064
+vardast-0.1.0.dist-info/RECORD,,

vardast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

vardast-0.1.0.dist-info/licenses/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.