zalobot-python 0.1.3__tar.gz → 0.2.0__tar.gz

zalobot_python-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.3
+Name: zalobot-python
+Version: 0.2.0
+Summary: Python SDK for the Zalo Bot API
+Author: NovaH00
+Author-email: NovaH00 <trantay2006super@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: requests>=2.32.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+[Tiếng Việt](README-vi.md)
+# ZaloBot Python SDK (Work in Progress)
+
+A modern, fully-typed, and asynchronous Python SDK for the ZaloBot API. This library was built as a more ergonomic and developer-friendly alternative to the official SDK.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Fully Typed & Documented** | Complete type hints and docstrings. No need to dig through source code to figure out expected data types. |
+| **Pydantic Data Modeling** | All API responses are validated and converted into Pydantic models. This improves Developer Experience (DX) and significantly reduces errors related to raw JSON parsing. |
+| **True Asynchronous Execution** | Non-blocking async operations designed to avoid runtime errors, even when used within applications where the main thread is fully occupied. |
+| **Ergonomic Webhooks** | Simplified webhook configuration and event dispatching mechanisms. |
+
+## Installation
+
+You can install the SDK using your preferred package manager:
+
+**Using uv:**
+~~~bash
+uv add zalobot_python
+~~~
+
+**Using pip:**
+~~~bash
+pip install zalobot_python
+~~~
+
+## API Coverage
+
+Methods formatted in `camelCase` directly map to the equivalent Zalo API endpoints.
+
+| Method | Zalo Endpoint | Status |
+|--------|---------------|--------|
+| `getMe()` | `/getMe` | Implemented |
+| `getUpdates()` | `/getUpdates` | Implemented |
+| `setWebhook()` | `/setWebhook` | Implemented |
+| `deleteWebhook()` | `/deleteWebhook` | Implemented |
+| `getWebhookInfo()` | `/getWebhookInfo` | Implemented |
+| `sendMessage()` | `/sendMessage` | Implemented |
+| `sendPhoto()` | `/sendPhoto` | Planned |
+| `sendSticker()` | `/sendSticker` | Planned |
+| `sendChatAction()` | `/sendChatAction` | Planned |
+
+## Usage
+
+### Basic Usage
+
+The simplest way to use the bot is to instantiate it with your token and call the available endpoint methods.
+
+~~~python
+import asyncio
+from zalobot_python import ZaloBot, BotInfo 
+
+bot = ZaloBot(BOT_TOKEN="<BOT_TOKEN>")
+
+async def main():
+    bot_info: BotInfo = await bot.getMe()
+    
+    print(f"Bot ID: {bot_info.id}")
+    print(f"Bot Name: {bot_info.display_name}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+~~~
+
+### Webhook Usage
+
+While you can technically poll `.getUpdates()` to receive new events, using a webhook is significantly more efficient. The SDK provides built-in mechanisms to easily configure and handle webhooks.
+
+~~~python
+from zalobot_python import ZaloBot, Context, AsyncWebhookHandler, ZaloAPIResponse, Event 
+
+# 1. Initialize the standard bot
+normal_bot = ZaloBot("<BOT_TOKEN>")
+
+# 2. Define your webhook handlers
+async def echo(ctx: Context):
+    message_info = await ctx.reply(f"You sent: {ctx.text}")
+    print("Sent message ID:", message_info.message_id)
+
+async def log_event(ctx: Context):
+    if ctx.is_text:
+        print("Chat ID:", ctx.chat_id)
+        print("Message:", ctx.text)
+
+async def main():
+    # Convert the standard bot into a webhook-enabled bot
+    # (All previously available endpoint methods remain usable)
+    webhook_bot = await normal_bot.configure_webhook("https://your-domain.com/webhook")
+    
+    # Retrieve the auto-generated secret token. 
+    # Use this to validate the X-Bot-Api-Secret-Token header in incoming requests.
+    secret_token = webhook_bot.get_secret_token() 
+    
+    # Register handlers
+    webhook_bot.add_webhook_handler(echo)
+    webhook_bot.add_webhook_handler(log_event)
+
+    # Note: The request handling flow below should be implemented 
+    # inside your web framework's endpoint (e.g., FastAPI, Flask).
+~~~
+
+#### Request Handling Flow (For Web Frameworks)
+
+When implementing the actual route in your web framework, follow these steps to process incoming events:
+
+1. **Parse the payload:** Parse the incoming JSON body into a `ZaloAPIResponse[Event]`. The actual payload resides in the `result` field.
+~~~python
+parsed: ZaloAPIResponse[Event] = ZaloAPIResponse.model_validate(request.json())
+~~~
+
+2. **Extract the event:**
+~~~python
+event = parsed.result
+~~~
+
+3. **Dispatch the event:** Pass the event to your registered handlers.
+~~~python
+await webhook_bot.dispatch_webhook_handlers(event)
+~~~
+
+## Architecture Note: Webhook State Management
+
+To ensure strict type safety, the `ZaloBot` class is a generic that relies on two specific states: 
+
+| State | Description |
+|-------|-------------|
+| `UnconfiguredWebhook` | The default state when `ZaloBot` is instantiated. |
+| `ConfiguredWebhook` | The state returned after calling `.configure_webhook()`. |
+
+**Why does this matter?**
+All helper methods written in `snake_case` (such as `add_webhook_handler`) are specific to webhook operations. Because of the generic state design, static analyzers (like Pyright or MyPy) will flag an error if you attempt to call a `snake_case` method on an unconfigured bot (`ZaloBot[UnconfiguredWebhook]`). These methods are only exposed and valid on instances of `ZaloBot[ConfiguredWebhook]`.

zalobot_python-0.2.0/README.md

@@ -0,0 +1,133 @@
+[Tiếng Việt](README-vi.md)
+# ZaloBot Python SDK (Work in Progress)
+
+A modern, fully-typed, and asynchronous Python SDK for the ZaloBot API. This library was built as a more ergonomic and developer-friendly alternative to the official SDK.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Fully Typed & Documented** | Complete type hints and docstrings. No need to dig through source code to figure out expected data types. |
+| **Pydantic Data Modeling** | All API responses are validated and converted into Pydantic models. This improves Developer Experience (DX) and significantly reduces errors related to raw JSON parsing. |
+| **True Asynchronous Execution** | Non-blocking async operations designed to avoid runtime errors, even when used within applications where the main thread is fully occupied. |
+| **Ergonomic Webhooks** | Simplified webhook configuration and event dispatching mechanisms. |
+
+## Installation
+
+You can install the SDK using your preferred package manager:
+
+**Using uv:**
+~~~bash
+uv add zalobot_python
+~~~
+
+**Using pip:**
+~~~bash
+pip install zalobot_python
+~~~
+
+## API Coverage
+
+Methods formatted in `camelCase` directly map to the equivalent Zalo API endpoints.
+
+| Method | Zalo Endpoint | Status |
+|--------|---------------|--------|
+| `getMe()` | `/getMe` | Implemented |
+| `getUpdates()` | `/getUpdates` | Implemented |
+| `setWebhook()` | `/setWebhook` | Implemented |
+| `deleteWebhook()` | `/deleteWebhook` | Implemented |
+| `getWebhookInfo()` | `/getWebhookInfo` | Implemented |
+| `sendMessage()` | `/sendMessage` | Implemented |
+| `sendPhoto()` | `/sendPhoto` | Planned |
+| `sendSticker()` | `/sendSticker` | Planned |
+| `sendChatAction()` | `/sendChatAction` | Planned |
+
+## Usage
+
+### Basic Usage
+
+The simplest way to use the bot is to instantiate it with your token and call the available endpoint methods.
+
+~~~python
+import asyncio
+from zalobot_python import ZaloBot, BotInfo 
+
+bot = ZaloBot(BOT_TOKEN="<BOT_TOKEN>")
+
+async def main():
+    bot_info: BotInfo = await bot.getMe()
+    
+    print(f"Bot ID: {bot_info.id}")
+    print(f"Bot Name: {bot_info.display_name}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+~~~
+
+### Webhook Usage
+
+While you can technically poll `.getUpdates()` to receive new events, using a webhook is significantly more efficient. The SDK provides built-in mechanisms to easily configure and handle webhooks.
+
+~~~python
+from zalobot_python import ZaloBot, Context, AsyncWebhookHandler, ZaloAPIResponse, Event 
+
+# 1. Initialize the standard bot
+normal_bot = ZaloBot("<BOT_TOKEN>")
+
+# 2. Define your webhook handlers
+async def echo(ctx: Context):
+    message_info = await ctx.reply(f"You sent: {ctx.text}")
+    print("Sent message ID:", message_info.message_id)
+
+async def log_event(ctx: Context):
+    if ctx.is_text:
+        print("Chat ID:", ctx.chat_id)
+        print("Message:", ctx.text)
+
+async def main():
+    # Convert the standard bot into a webhook-enabled bot
+    # (All previously available endpoint methods remain usable)
+    webhook_bot = await normal_bot.configure_webhook("https://your-domain.com/webhook")
+    
+    # Retrieve the auto-generated secret token. 
+    # Use this to validate the X-Bot-Api-Secret-Token header in incoming requests.
+    secret_token = webhook_bot.get_secret_token() 
+    
+    # Register handlers
+    webhook_bot.add_webhook_handler(echo)
+    webhook_bot.add_webhook_handler(log_event)
+
+    # Note: The request handling flow below should be implemented 
+    # inside your web framework's endpoint (e.g., FastAPI, Flask).
+~~~
+
+#### Request Handling Flow (For Web Frameworks)
+
+When implementing the actual route in your web framework, follow these steps to process incoming events:
+
+1. **Parse the payload:** Parse the incoming JSON body into a `ZaloAPIResponse[Event]`. The actual payload resides in the `result` field.
+~~~python
+parsed: ZaloAPIResponse[Event] = ZaloAPIResponse.model_validate(request.json())
+~~~
+
+2. **Extract the event:**
+~~~python
+event = parsed.result
+~~~
+
+3. **Dispatch the event:** Pass the event to your registered handlers.
+~~~python
+await webhook_bot.dispatch_webhook_handlers(event)
+~~~
+
+## Architecture Note: Webhook State Management
+
+To ensure strict type safety, the `ZaloBot` class is a generic that relies on two specific states: 
+
+| State | Description |
+|-------|-------------|
+| `UnconfiguredWebhook` | The default state when `ZaloBot` is instantiated. |
+| `ConfiguredWebhook` | The state returned after calling `.configure_webhook()`. |
+
+**Why does this matter?**
+All helper methods written in `snake_case` (such as `add_webhook_handler`) are specific to webhook operations. Because of the generic state design, static analyzers (like Pyright or MyPy) will flag an error if you attempt to call a `snake_case` method on an unconfigured bot (`ZaloBot[UnconfiguredWebhook]`). These methods are only exposed and valid on instances of `ZaloBot[ConfiguredWebhook]`.

{zalobot_python-0.1.3 → zalobot_python-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zalobot-python"
-version = "0.1.3"
+version = "0.2.0"
 description = "Python SDK for the Zalo Bot API"
 readme = "README.md"
 authors = [

{zalobot_python-0.1.3 → zalobot_python-0.2.0}/src/zalobot_python/__init__.py

@@ -1,5 +1,5 @@
-from .zalobot import ZaloBot, WebhookHandler
-from .models import (
+from .zalobot import ZaloBot, Context, AsyncWebhookHandler  
+from .types import (
     SuccessfulResponse,
     ErrorResponse,
     ZaloAPIResponse,
@@ -19,7 +19,8 @@ __all__ = [
     "ErrorResponse",
     "ZaloAPIResponse",
     "ZaloBot",
-    "WebhookHandler",
+    "Context",
+    "AsyncWebhookHandler",
     "BotInfo",
     "WebhookInfo",
     "MessageInfo",

zalobot_python-0.2.0/src/zalobot_python/types/__init__.py

@@ -0,0 +1,33 @@
+from .responses import (
+    ZaloAPIResponse,
+    SuccessfulResponse,
+    ErrorResponse, 
+    Result
+)
+from .entities import (
+    BotInfo,
+    MessageInfo,
+    WebhookInfo,
+    EventName,
+    From,
+    Chat,
+    Message,
+    Event
+)
+from .errors import ZaloAPIError
+
+__all__ = [
+    "SuccessfulResponse",
+    "ErrorResponse",
+    "ZaloAPIResponse",
+    "Result",
+    "BotInfo",
+    "WebhookInfo",
+    "MessageInfo",
+    "EventName",
+    "From",
+    "Chat",
+    "Message",
+    "Event",
+    "ZaloAPIError"
+]

zalobot_python-0.2.0/src/zalobot_python/types/entities.py

@@ -0,0 +1,47 @@
+from enum import StrEnum 
+from pydantic import BaseModel, Field
+
+from .responses import Result
+
+class BotInfo(Result):
+    id: str  
+    account_name: str 
+    account_type: str 
+    can_join_groups: bool
+    display_name: str
+
+class WebhookInfo(Result):
+    url: str 
+    updated_at: int 
+
+class MessageInfo(Result):
+    message_id: str
+    date: int
+
+class EventName(StrEnum):
+    TEXT_RECEIVED        = "message.text.received"
+    IMAGE_RECEIVED       = "message.image.received"
+    STICKER_RECEIVED     = "message.sticker.received"
+    UNSUPPORTED_RECEIVED = "message.unsupported.received"
+
+class From(BaseModel):
+    """Sender information"""
+    id: str
+    display_name: str
+    is_bot: bool
+
+class Chat(BaseModel):
+    """Current chat information"""
+    id: str
+    chat_type: str
+
+class Message(BaseModel):
+    sender: From = Field(alias="from")
+    chat: Chat
+    text: str
+    message_id: str
+    date: int
+
+class Event(Result):
+    event_name: EventName
+    message: Message

zalobot_python-0.2.0/src/zalobot_python/types/errors.py

@@ -0,0 +1,13 @@
+from typing import override
+
+class ZaloAPIError(BaseException):
+    """Exception when using the Zalo API"""
+    def __init__(self, error_code: int, description: str):
+        self.error_code: int = error_code
+        self.description: str = description
+        super().__init__()
+
+    @override
+    def __str__(self):
+        return f"error_code: {self.error_code}; description: {self.description}"
+

zalobot_python-0.2.0/src/zalobot_python/types/responses.py

@@ -0,0 +1,21 @@
+from typing import Literal, Annotated
+from pydantic import BaseModel, Field
+
+class Result(BaseModel):
+    """Represents the result field in the Zalo API successful response"""
+
+class SuccessfulResponse[T: Result](BaseModel):
+    """Represents the successful response of the Zalo API"""
+    ok: Literal[True] = True
+    result: T = Field(description="The result when the API call is successful.")
+
+class ErrorResponse(BaseModel):
+    """Represents the error response of Zalo API"""
+    ok: Literal[False] = False
+    description: str = Field(description="The description of the error")
+    error_code: int = Field(description="The error code")
+
+type ZaloAPIResponse[T: Result] = Annotated[
+    SuccessfulResponse[T] | ErrorResponse,
+    "Represents the response of the Zalo API"
+]

zalobot_python-0.2.0/src/zalobot_python/zalobot/__init__.py

@@ -0,0 +1,8 @@
+from .context import Context
+from .core import ZaloBot, AsyncWebhookHandler
+
+__all__ = [
+    "Context",
+    "ZaloBot",
+    "AsyncWebhookHandler"
+]

zalobot_python-0.2.0/src/zalobot_python/zalobot/context.py

@@ -0,0 +1,52 @@
+from typing import final 
+from ..types import Event, EventName, MessageInfo, From, Chat
+from .interfaces import ZaloBotAPI
+
+@final
+class Context:
+    def __init__(self, *, _update: Event, _bot: ZaloBotAPI):
+        self._update = _update
+        self._bot = _bot
+
+    async def reply(self, text: str) -> MessageInfo:
+        return await self._bot.sendMessage(self.chat_id, text) 
+
+    @property
+    def chat_id(self) -> str:
+        return self._update.message.chat.id 
+
+    @property
+    def user_id(self) -> str:
+        return self._update.message.sender.id
+
+    @property
+    def text(self) -> str:
+        return self._update.message.text
+
+    @property
+    def message_id(self) -> str:
+        return self._update.message.message_id
+
+    @property
+    def sender(self) -> From:
+        return self._update.message.sender
+    
+    @property
+    def chat(self) -> Chat:
+        return self._update.message.chat
+
+    @property
+    def is_text(self) -> bool:
+        return self._update.event_name == EventName.TEXT_RECEIVED 
+
+    @property
+    def is_image(self) -> bool:
+        return self._update.event_name == EventName.IMAGE_RECEIVED
+
+    @property
+    def is_sticker(self) -> bool:
+        return self._update.event_name == EventName.STICKER_RECEIVED
+
+    @property
+    def is_unsupported(self) -> bool:
+        return self._update.event_name == EventName.UNSUPPORTED_RECEIVED

zalobot_python-0.1.3/src/zalobot_python/zalobot.py → zalobot_python-0.2.0/src/zalobot_python/zalobot/core.py

@@ -1,9 +1,8 @@
-from typing import Any, Literal, Protocol
-import httpx
+import secrets
+from typing import Annotated, Protocol
 
-from .models import (
+from ..types import (
     ZaloAPIResponse,
-    SuccessfulResponse,
     ErrorResponse,
     ZaloAPIError,
     BotInfo,  
@@ -11,50 +10,46 @@ from .models import (
     MessageInfo,
     Event
 )
-from .config import ZaloAPIConfig
-
-async def fetch[T](
-    url: str,
-    *,
-    method: Literal["GET", "POST"] = "GET",
-    body: dict[str, Any] | None = None,
-) -> ZaloAPIResponse[T]:
-    async with httpx.AsyncClient() as client:
-
-        if method == "GET":
-            response = await client.get(url)
-
-        elif method == "POST":
-            response = await client.post(url, json=body)
-
-        response_json = response.json()
-
-        if response_json.get("ok"):
-            return SuccessfulResponse(**response_json)
-
-        return ErrorResponse(**response_json)
+from ..config import ZaloAPIConfig
+from .http import fetch
+from .context import Context
+
+class UnconfiguredWebhook: 
+    """Represents the state of the bot where webhook have not yet configured"""
+class ConfiguredWebhook:
+    """Represents the state of the bot where webhook is configured"""
+type BotStates = Annotated[
+    UnconfiguredWebhook | ConfiguredWebhook,
+    "Represents the states of the bot"
+]
 
 class AsyncWebhookHandler(Protocol):
-    async def __call__(self, update_event: Event, bot: ZaloBot) -> None: ...
+    async def __call__(self, ctx: Context) -> None: ...
 
-class ZaloBot:
-    def __init__(self, BOT_TOKEN: str):
+class ZaloBot[S: BotStates = UnconfiguredWebhook]:
+    def __init__(
+        self,
+        BOT_TOKEN: str,
+        *,
+        _secret_token: str | None = None
+    ):
         self._BOT_TOKEN: str = BOT_TOKEN
         self._base_url: str = f"{ZaloAPIConfig.BASE_URL}/bot{BOT_TOKEN}"
         self._webhook_handlers: list[AsyncWebhookHandler] = [] 
+        if _secret_token is not None:
+            self._secret_token: str = _secret_token
 
     async def getMe(self) -> BotInfo:
         url = f"{self._base_url}/getMe" 
         
-        res: ZaloAPIResponse[BotInfo] = await fetch(url)
-        
+        res = await fetch(url, result_schema=BotInfo)
+
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
                 res.error_code,
                 res.description
             ) 
         
-       
         return res.result
                       
     async def getUpdates(self, timeout: int = 30) -> Event:
@@ -64,7 +59,7 @@ class ZaloBot:
             "timeout": timeout
         }
 
-        res: ZaloAPIResponse[Event] = await fetch(url, method="POST", body=payload)
+        res = await fetch(url, result_schema=Event, method="POST", body=payload, timeout=timeout)
 
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
@@ -75,7 +70,7 @@ class ZaloBot:
         return res.result
 
     async def setWebhook(
-        self,
+        self: ZaloBot[UnconfiguredWebhook],
         url: str,
         secret_token: str,
     ) -> WebhookInfo:
@@ -86,7 +81,7 @@ class ZaloBot:
             "secret_token": secret_token
         }
 
-        res: ZaloAPIResponse[WebhookInfo] = await fetch(url, method="POST", body=payload)
+        res = await fetch(url, result_schema=WebhookInfo, method="POST", body=payload)
 
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
@@ -99,7 +94,7 @@ class ZaloBot:
     async def deleteWebhook(self) -> WebhookInfo:
         url = f"{self._base_url}/deleteWebhook"
         
-        res: ZaloAPIResponse[WebhookInfo] = await fetch(url)
+        res = await fetch(url, result_schema=WebhookInfo)
 
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
@@ -112,7 +107,7 @@ class ZaloBot:
     async def getWebhookInfo(self) -> WebhookInfo:
         url = f"{self._base_url}/getWebhookInfo"
         
-        res: ZaloAPIResponse[WebhookInfo] = await fetch(url)
+        res = await fetch(url, result_schema=WebhookInfo)
 
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
@@ -122,15 +117,6 @@ class ZaloBot:
 
         return res.result
     
-    def on_webhook_update(self, handler: AsyncWebhookHandler) -> None:
-        """Registers a handler to handle on webhook event update"""
-        self._webhook_handlers.append(handler)
-
-    async def dispatch_webhook_handlers(self, update_event: Event) -> None:
-        """Run all handlers given a webhook event"""
-        for handler in self._webhook_handlers:
-            await handler(update_event, self)
-
     async def sendMessage(self, chat_id: str, text: str) -> MessageInfo:
         url = f"{self._base_url}/sendMessage"
         
@@ -138,7 +124,7 @@ class ZaloBot:
             "chat_id": chat_id,
             "text": text
         }
-        res: ZaloAPIResponse[MessageInfo] = await fetch(url, method="POST", body=payload)
+        res = await fetch(url, result_schema=MessageInfo, method="POST", body=payload)
 
         if isinstance(res, ErrorResponse):
             raise ZaloAPIError(
@@ -157,3 +143,31 @@ class ZaloBot:
 
     async def sendChatAction(self, chat_id: str, action: str) -> None:
         raise NotImplementedError()
+
+    async def configure_webhook(
+        self: ZaloBot[UnconfiguredWebhook],
+        url: str
+    ) -> ZaloBot[ConfiguredWebhook]:
+        
+        secret_token = secrets.token_urlsafe(192)
+        _ = await self.setWebhook(url, secret_token)
+        
+        return ZaloBot(self._BOT_TOKEN, _secret_token = secret_token)
+    
+    def get_secret_token(self: ZaloBot[ConfiguredWebhook]):
+        return self._secret_token
+
+    def add_webhook_handler(
+        self: ZaloBot[ConfiguredWebhook],
+        handler: AsyncWebhookHandler
+    ) -> None:
+        """Registers a handler to handle on webhook event update"""
+        self._webhook_handlers.append(handler)
+
+    async def dispatch_webhook_handlers(
+        self: ZaloBot[ConfiguredWebhook],
+        update_event: Event
+    ) -> None:
+        """Run all handlers given a webhook event"""
+        for handler in self._webhook_handlers:
+            await handler(Context(_update=update_event, _bot=self))

zalobot_python-0.2.0/src/zalobot_python/zalobot/http.py

@@ -0,0 +1,36 @@
+from typing import Literal, Any
+
+import httpx
+
+from ..types import ZaloAPIResponse, Result, SuccessfulResponse, ErrorResponse
+
+async def fetch[T: Result](
+    url: str,
+    *,
+    result_schema: type[T],
+    method: Literal["GET", "POST"] = "GET",
+    body: dict[str, Any] | None = None,
+    timeout: int = 30,
+) -> ZaloAPIResponse[T]:
+    """Ultility function to fetch the data from the Zalo API asynchronously"""
+    async with httpx.AsyncClient(timeout=timeout) as client:
+
+        if method == "GET":
+            response = await client.get(url)
+
+        elif method == "POST":
+            response = await client.post(url, json=body)
+
+        response_json = response.json()
+
+        if response_json.get("ok"):
+            return SuccessfulResponse(
+                ok=True,
+                result=result_schema.model_validate(response_json.get("result"))
+            )
+
+        return ErrorResponse(
+            ok=False,
+            description=response_json.get("description"),
+            error_code=response_json.get("error_code")
+        )

zalobot_python-0.2.0/src/zalobot_python/zalobot/interfaces.py

@@ -0,0 +1,8 @@
+from typing import Protocol
+from ..types import MessageInfo
+
+class ZaloBotAPI(Protocol):
+    async def sendMessage(self, chat_id: str, text: str) -> MessageInfo: ...
+    async def sendPhoto(self, chat_id: str, caption: str, photo_url: str) -> None: ...
+    async def sendSticker(self, chat_id: str, sticker: str) -> None: ...
+    async def sendChatAction(self, chat_id: str, action: str) -> None: ...

zalobot_python-0.1.3/PKG-INFO

@@ -1,39 +0,0 @@
-Metadata-Version: 2.3
-Name: zalobot-python
-Version: 0.1.3
-Summary: Python SDK for the Zalo Bot API
-Author: NovaH00
-Author-email: NovaH00 <trantay2006super@gmail.com>
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: requests>=2.32.5
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-
-# WIP: Python SDK for the ZaloBot API
-
-## Installation
-For uv-astral  
-```bash
-uv add zalobot_python
-```
-For pip  
-```bash
-pip install zalobot_python
-```
-
-Usage
-```python
-import asyncio
-from zalobot_python import ZaloBot, BotInfo 
-
-bot = ZaloBot(BOT_TOKEN="<BOT TOKEN>")
-
-async def main():
-    bot_info: BotInfo = await bot.getMe()
-
-    print(f"Bot ID: {bot_info.id}")
-    print(f"Bot Name: {bot_info.display_name}")
-
-asyncio.run(main())
-```

zalobot_python-0.1.3/README.md

@@ -1,27 +0,0 @@
-# WIP: Python SDK for the ZaloBot API
-
-## Installation
-For uv-astral  
-```bash
-uv add zalobot_python
-```
-For pip  
-```bash
-pip install zalobot_python
-```
-
-Usage
-```python
-import asyncio
-from zalobot_python import ZaloBot, BotInfo 
-
-bot = ZaloBot(BOT_TOKEN="<BOT TOKEN>")
-
-async def main():
-    bot_info: BotInfo = await bot.getMe()
-
-    print(f"Bot ID: {bot_info.id}")
-    print(f"Bot Name: {bot_info.display_name}")
-
-asyncio.run(main())
-```

zalobot_python-0.1.3/src/zalobot_python/models.py

@@ -1,78 +0,0 @@
-from enum import StrEnum 
-from typing import Literal, TypeVar, override, Annotated
-from pydantic import BaseModel, Field
-
-class Result(BaseModel):
-    """Represents the result field in the Zalo API successful response"""
-    pass
-
-T = TypeVar("T", bound=Result)
-class SuccessfulResponse[T](BaseModel):
-    """Represents the successful response of the Zalo API"""
-    ok: Literal[True] = True
-    result: T = Field(description="The result when the API call is successful.")
-
-class ErrorResponse(BaseModel):
-    """Represents the error response of Zalo API"""
-    ok: Literal[False] = False
-    description: str = Field(description="The description of the error")
-    error_code: int = Field(description="The error code")
-
-type ZaloAPIResponse[T] = Annotated[
-    SuccessfulResponse[T] | ErrorResponse,
-    "Represents the response of the Zalo API"
-]
-
-class ZaloAPIError(BaseException):
-    """Exception when using the Zalo API"""
-    def __init__(self, error_code: int, description: str):
-        self.error_code: int = error_code
-        self.description: str = description
-        super().__init__()
-
-    @override
-    def __str__(self):
-        return f"error_code: {self.error_code}; description: {self.description}"
-
-class BotInfo(Result):
-    id: str  
-    account_name: str 
-    account_type: str 
-    can_join_groups: bool
-    display_name: str
-
-class WebhookInfo(Result):
-    url: str 
-    updated_at: int 
-
-class MessageInfo(Result):
-    message_id: str
-    date: int
-
-class EventName(StrEnum):
-    TEXT_RECEIVED        = "message.text.received"
-    IMAGE_RECEIVED       = "message.image.received"
-    STICKER_RECEIVED     = "message.sticker.received"
-    UNSUPPORTED_RECEIVED = "message.unsupported.received"
-
-class From(BaseModel):
-    """Sender information"""
-    id: str
-    display_name: str
-    is_bot: bool
-
-class Chat(BaseModel):
-    """Current chat information"""
-    id: str
-    chat_type: str
-
-class Message(BaseModel):
-    sender: From = Field(alias="from")
-    chat: Chat
-    text: str
-    message_id: str
-    date: int
-
-class Event(BaseModel):
-    event_name: EventName
-    message: Message