financechatbotkit 2.0.0__py3-none-any.whl

telebotkit/__init__.py

@@ -0,0 +1,51 @@
+"""TeleBotKit public package."""
+
+from telebotkit.bot import (
+    CommandMatch,
+    Reply,
+    Router,
+    SECTION_DIVIDER,
+    escape_markdown,
+    format_krw_amount,
+    safe_call,
+)
+from telebotkit.firestore import (
+    DocumentStore,
+    LeaseStore,
+    SharedDocumentStore,
+    get_client,
+    upload_typed_rows_json,
+    upload_typed_rows_payload,
+)
+from telebotkit.sheets import (
+    build_typed_rows_payload,
+    build_typed_rows_payload_from_xlsx,
+    load_typed_rows_json,
+    read_rows_from_xlsx,
+    save_typed_rows_payload_json,
+    validate_typed_rows_payload,
+)
+
+__all__ = [
+    "CommandMatch",
+    "DocumentStore",
+    "LeaseStore",
+    "Reply",
+    "Router",
+    "SECTION_DIVIDER",
+    "SharedDocumentStore",
+    "build_typed_rows_payload",
+    "build_typed_rows_payload_from_xlsx",
+    "bot",
+    "escape_markdown",
+    "firestore",
+    "format_krw_amount",
+    "get_client",
+    "load_typed_rows_json",
+    "read_rows_from_xlsx",
+    "safe_call",
+    "save_typed_rows_payload_json",
+    "upload_typed_rows_json",
+    "upload_typed_rows_payload",
+    "validate_typed_rows_payload",
+]

telebotkit/bot/__init__.py

@@ -0,0 +1,38 @@
+"""Bot-facing TeleBotKit helpers."""
+
+from telebotkit.bot.client import (
+    SendResult,
+    TelegramApiError,
+    TelegramBot,
+    TelegramSendError,
+)
+from telebotkit.bot.reply import DEFAULT_PARSE_MODE, Reply
+from telebotkit.bot.router import (
+    CommandHandler,
+    CommandMatch,
+    CommandRoute,
+    Router,
+)
+from telebotkit.bot.safety import safe_call
+from telebotkit.bot.telegram import (
+    SECTION_DIVIDER,
+    escape_markdown,
+    format_krw_amount,
+)
+
+__all__ = [
+    "CommandHandler",
+    "CommandMatch",
+    "CommandRoute",
+    "DEFAULT_PARSE_MODE",
+    "Reply",
+    "Router",
+    "SendResult",
+    "SECTION_DIVIDER",
+    "TelegramApiError",
+    "TelegramBot",
+    "TelegramSendError",
+    "escape_markdown",
+    "format_krw_amount",
+    "safe_call",
+]

telebotkit/bot/client.py

@@ -0,0 +1,217 @@
+"""Telegram Bot API sending helpers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from telebotkit.bot.reply import DEFAULT_PARSE_MODE, Reply
+
+logger = logging.getLogger(__name__)
+
+
+class TelegramSendError(RuntimeError):
+    """Raised when a Telegram send request fails."""
+
+
+class TelegramApiError(TelegramSendError):
+    """Raised when Telegram responds with an error payload or status code."""
+
+    def __init__(self, *, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"Telegram API error ({status_code}): {detail}")
+
+
+@dataclass(frozen=True)
+class SendResult:
+    """Normalized result of a Telegram send request."""
+
+    ok: bool
+    chat_id: int
+    payload: dict[str, Any]
+    status_code: int
+    data: dict[str, Any]
+
+
+class TelegramBot:
+    """Small async client for Telegram Bot API `sendMessage`."""
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        timeout: float = 10.0,
+        base_url: str | None = None,
+        client_factory: Callable[[], httpx.AsyncClient] | None = None,
+    ) -> None:
+        self._token = token
+        self._timeout = timeout
+        self._base_url = (base_url or f"https://api.telegram.org/bot{token}").rstrip("/")
+        self._client_factory = client_factory or self._default_client_factory
+
+    async def send(self, *, chat_id: int, reply: Reply) -> SendResult:
+        payload = reply.to_payload(chat_id)
+        response = await self._post("sendMessage", payload)
+        data = self._parse_response_data(response)
+        return SendResult(
+            ok=True,
+            chat_id=chat_id,
+            payload=payload,
+            status_code=response.status_code,
+            data=data,
+        )
+
+    async def send_text(
+        self,
+        *,
+        chat_id: int,
+        text: str,
+        parse_mode: str | None = None,
+    ) -> SendResult:
+        reply = Reply(text=text, parse_mode=parse_mode or DEFAULT_PARSE_MODE)
+        return await self.send(chat_id=chat_id, reply=reply)
+
+    async def send_plain_text(self, *, chat_id: int, text: str) -> SendResult:
+        return await self.send(chat_id=chat_id, reply=Reply.plain(text))
+
+    async def send_markdown(self, *, chat_id: int, text: str) -> SendResult:
+        return await self.send(chat_id=chat_id, reply=Reply.md(text))
+
+    async def send_payload(self, payload: dict[str, Any]) -> SendResult:
+        chat_id = int(payload["chat_id"])
+        reply = Reply(
+            text=str(payload["text"]),
+            parse_mode=payload.get("parse_mode"),
+        )
+        return await self.send(chat_id=chat_id, reply=reply)
+
+    async def send_safe(
+        self,
+        *,
+        chat_id: int,
+        reply: Reply,
+        logger: logging.Logger | None = None,
+        success_log: str | None = None,
+        success_args: tuple[object, ...] = (),
+        failure_log: str | None = None,
+        failure_args: tuple[object, ...] = (),
+    ) -> SendResult | None:
+        active_logger = logger or globals()["logger"]
+        try:
+            result = await self.send(chat_id=chat_id, reply=reply)
+        except Exception:
+            if failure_log:
+                active_logger.exception(failure_log, *failure_args)
+            else:
+                active_logger.exception("Failed to send Telegram message to chat_id=%s", chat_id)
+            return None
+
+        if success_log:
+            active_logger.info(success_log, *success_args)
+        return result
+
+    async def send_plain_text_safe(
+        self,
+        *,
+        chat_id: int,
+        text: str,
+        logger: logging.Logger | None = None,
+        success_log: str | None = None,
+        success_args: tuple[object, ...] = (),
+        failure_log: str | None = None,
+        failure_args: tuple[object, ...] = (),
+    ) -> SendResult | None:
+        return await self.send_safe(
+            chat_id=chat_id,
+            reply=Reply.plain(text),
+            logger=logger,
+            success_log=success_log,
+            success_args=success_args,
+            failure_log=failure_log,
+            failure_args=failure_args,
+        )
+
+    async def send_markdown_safe(
+        self,
+        *,
+        chat_id: int,
+        text: str,
+        logger: logging.Logger | None = None,
+        success_log: str | None = None,
+        success_args: tuple[object, ...] = (),
+        failure_log: str | None = None,
+        failure_args: tuple[object, ...] = (),
+    ) -> SendResult | None:
+        return await self.send_safe(
+            chat_id=chat_id,
+            reply=Reply.md(text),
+            logger=logger,
+            success_log=success_log,
+            success_args=success_args,
+            failure_log=failure_log,
+            failure_args=failure_args,
+        )
+
+    async def set_webhook(
+        self,
+        *,
+        url: str,
+        secret_token: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"url": url}
+        if secret_token:
+            payload["secret_token"] = secret_token
+        response = await self._post("setWebhook", payload)
+        return self._parse_response_data(response)
+
+    async def delete_webhook(
+        self,
+        *,
+        drop_pending_updates: bool = False,
+    ) -> dict[str, Any]:
+        response = await self._post(
+            "deleteWebhook",
+            {"drop_pending_updates": drop_pending_updates},
+        )
+        return self._parse_response_data(response)
+
+    async def _post(self, method: str, payload: dict[str, Any] | None) -> httpx.Response:
+        async with self._client_factory() as client:
+            response = await client.post(f"{self._base_url}/{method}", json=payload)
+        if response.is_error:
+            raise TelegramApiError(
+                status_code=response.status_code,
+                detail=response.text,
+            )
+        return response
+
+    def _default_client_factory(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(timeout=self._timeout)
+
+    @staticmethod
+    def _parse_response_data(response: httpx.Response) -> dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise TelegramSendError("Telegram response was not valid JSON.") from exc
+        if not isinstance(data, dict):
+            raise TelegramSendError("Telegram response payload must be an object.")
+        if data.get("ok") is False:
+            raise TelegramApiError(
+                status_code=response.status_code,
+                detail=str(data.get("description") or "Telegram API returned ok=false."),
+            )
+        return data
+
+
+    __all__ = [
+    "SendResult",
+    "TelegramApiError",
+    "TelegramBot",
+    "TelegramSendError",
+]

telebotkit/bot/reply.py

@@ -0,0 +1,36 @@
+"""Telegram reply payload helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_PARSE_MODE = "MarkdownV2"
+
+
+@dataclass(frozen=True)
+class Reply:
+    """Simple outbound Telegram reply."""
+
+    text: str
+    parse_mode: str | None = DEFAULT_PARSE_MODE
+
+    @classmethod
+    def md(cls, text: str) -> "Reply":
+        return cls(text=text, parse_mode=DEFAULT_PARSE_MODE)
+
+    @classmethod
+    def plain(cls, text: str) -> "Reply":
+        return cls(text=text, parse_mode=None)
+
+    def to_payload(self, chat_id: int) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "chat_id": chat_id,
+            "text": self.text,
+        }
+        if self.parse_mode:
+            payload["parse_mode"] = self.parse_mode
+        return payload
+
+
+__all__ = ["DEFAULT_PARSE_MODE", "Reply"]

telebotkit/bot/router.py

@@ -0,0 +1,125 @@
+"""Command parsing and routing helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar
+
+RequestT = TypeVar("RequestT")
+ServicesT = TypeVar("ServicesT")
+ResponseT = TypeVar("ResponseT")
+CommandHandler = Callable[[RequestT, ServicesT], ResponseT]
+
+
+@dataclass(frozen=True)
+class CommandMatch:
+    """Parsed slash-command payload."""
+
+    name: str
+    args: str
+    invoked_name: str
+
+
+@dataclass(frozen=True)
+class CommandRoute(Generic[RequestT, ServicesT, ResponseT]):
+    """Registered command route."""
+
+    name: str
+    aliases: tuple[str, ...]
+    handler: CommandHandler[RequestT, ServicesT, ResponseT]
+
+
+class Router(Generic[RequestT, ServicesT, ResponseT]):
+    """Register slash commands once and reuse for parse + dispatch."""
+
+    def __init__(self) -> None:
+        self._routes_by_command: dict[str, CommandRoute[RequestT, ServicesT, ResponseT]] = {}
+
+    def register(
+        self,
+        name: str,
+        handler: CommandHandler[RequestT, ServicesT, ResponseT],
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> None:
+        route = CommandRoute(
+            name=self._normalize_name(name),
+            aliases=tuple(self._normalize_name(alias) for alias in aliases),
+            handler=handler,
+        )
+        for command_name in (route.name, *route.aliases):
+            self._routes_by_command[command_name] = route
+
+    def add(
+        self,
+        name: str,
+        handler: CommandHandler[RequestT, ServicesT, ResponseT],
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> None:
+        self.register(name, handler, aliases=aliases)
+
+    def command(
+        self,
+        name: str,
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> Callable[
+        [CommandHandler[RequestT, ServicesT, ResponseT]],
+        CommandHandler[RequestT, ServicesT, ResponseT],
+    ]:
+        def _decorator(
+            handler: CommandHandler[RequestT, ServicesT, ResponseT],
+        ) -> CommandHandler[RequestT, ServicesT, ResponseT]:
+            self.register(name, handler, aliases=aliases)
+            return handler
+
+        return _decorator
+
+    def route(
+        self,
+        name: str,
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> Callable[
+        [CommandHandler[RequestT, ServicesT, ResponseT]],
+        CommandHandler[RequestT, ServicesT, ResponseT],
+    ]:
+        return self.command(name, aliases=aliases)
+
+    def parse(self, text: str) -> CommandMatch | None:
+        stripped = (text or "").strip()
+        if not stripped or not stripped.startswith("/"):
+            return None
+
+        parts = stripped.split(maxsplit=1)
+        command_text = parts[0][1:].lower()
+        invoked_name = self._normalize_name(command_text.split("@", 1)[0])
+        route = self._routes_by_command.get(invoked_name)
+        if route is None:
+            return None
+
+        args = parts[1].strip() if len(parts) > 1 else ""
+        return CommandMatch(name=route.name, args=args, invoked_name=invoked_name)
+
+    def dispatch(
+        self,
+        command_name: str,
+        request: RequestT,
+        services: ServicesT,
+    ) -> ResponseT | None:
+        route = self._routes_by_command.get(self._normalize_name(command_name))
+        if route is None:
+            return None
+        return route.handler(request, services)
+
+    @staticmethod
+    def _normalize_name(name: str) -> str:
+        return str(name or "").strip().lower()
+
+__all__ = [
+    "CommandHandler",
+    "CommandMatch",
+    "CommandRoute",
+    "Router",
+]

telebotkit/bot/safety.py

@@ -0,0 +1,28 @@
+"""Small helpers for safe handler execution."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TypeVar
+
+ResultT = TypeVar("ResultT")
+
+
+def safe_call(
+    *,
+    action: Callable[[], ResultT],
+    default: ResultT,
+    logger: logging.Logger,
+    log_message: str,
+    log_args: tuple[object, ...] = (),
+) -> ResultT:
+    """Run *action* and fall back with consistent exception logging."""
+
+    try:
+        return action()
+    except Exception:
+        logger.exception(log_message, *log_args)
+        return default
+
+__all__ = ["safe_call"]

telebotkit/bot/telegram.py

@@ -0,0 +1,41 @@
+"""Telegram formatting helpers."""
+
+from __future__ import annotations
+
+SECTION_DIVIDER = "─" * 20
+TELEGRAM_MARKDOWN_V2_SPECIAL_CHARS = "_*[]()~`>#+-=|{}.!"
+
+
+def escape_markdown(text: str) -> str:
+    """Escape special Telegram MarkdownV2 characters."""
+
+    escaped = str(text)
+    for char in TELEGRAM_MARKDOWN_V2_SPECIAL_CHARS:
+        escaped = escaped.replace(char, f"\\{char}")
+    return escaped
+
+
+def format_krw_amount(amount: int) -> str:
+    """Format a KRW amount into a compact Korean-readable string."""
+
+    if amount < 0:
+        return f"-{format_krw_amount(-amount)}"
+
+    x_1t = 1_000_000_000_000
+    x_100m = 100_000_000
+    x_10k = 10_000
+
+    if amount >= x_1t:
+        return f"{amount / x_1t:,.2f}조"
+    if amount >= x_100m:
+        return f"{amount / x_100m:,.2f}억"
+    if amount >= x_10k:
+        return f"{amount / x_10k:,.2f}만"
+    return f"{amount:,}"
+
+__all__ = [
+    "SECTION_DIVIDER",
+    "TELEGRAM_MARKDOWN_V2_SPECIAL_CHARS",
+    "escape_markdown",
+    "format_krw_amount",
+]

telebotkit/firestore/__init__.py

@@ -0,0 +1,45 @@
+"""Firestore helpers for TeleBotKit."""
+
+from telebotkit.firestore.client import (
+    FirestoreClientProvider,
+    FirestoreClientFactory,
+    FirestoreQuotaError,
+    get_client,
+    load_service_account_info_from_env,
+    raise_if_quota_error,
+    reset_client,
+)
+from telebotkit.firestore.documents import (
+    DocumentStore,
+    SharedDocumentStore,
+)
+from telebotkit.firestore.fetch import (
+    FetchResult,
+    clear_document_cache,
+    fetch_document,
+    invalidate_document_cache,
+)
+from telebotkit.firestore.locks import LeaseStore
+from telebotkit.firestore.upload import (
+    upload_typed_rows_json,
+    upload_typed_rows_payload,
+)
+
+__all__ = [
+    "DocumentStore",
+    "FetchResult",
+    "FirestoreClientProvider",
+    "FirestoreClientFactory",
+    "FirestoreQuotaError",
+    "LeaseStore",
+    "SharedDocumentStore",
+    "clear_document_cache",
+    "fetch_document",
+    "get_client",
+    "invalidate_document_cache",
+    "load_service_account_info_from_env",
+    "raise_if_quota_error",
+    "reset_client",
+    "upload_typed_rows_json",
+    "upload_typed_rows_payload",
+]