chatops-bridge 0.1.0__tar.gz

chatops_bridge-0.1.0/LICENSE

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

chatops_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: chatops-bridge
+Version: 0.1.0
+Summary: Reusable Telegram and Discord ChatOps utilities for Python projects
+Author: ChatOps Bridge Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/trunghvbk-afataw/chatops
+Project-URL: Repository, https://github.com/trunghvbk-afataw/chatops
+Project-URL: Issues, https://github.com/trunghvbk-afataw/chatops/issues
+Keywords: telegram,discord,webhook,chatops,notifications
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: awesome-notify-bridge>=0.1.5
+Provides-Extra: discord-bot
+Requires-Dist: discord.py>=2.4.0; extra == "discord-bot"
+Dynamic: license-file
+
+# chatops-bridge
+
+Reusable Telegram and Discord utilities for Python applications.
+
+This package was extracted from production automation code and generalized for multi-purpose ChatOps use.
+Transport-level Telegram/Discord sending is reused from `awesome-notify-bridge`.
+
+## Features
+
+- Telegram send/poll helpers:
+  - send text and images
+  - split long text by Telegram limit
+  - poll updates and extract message text
+  - robust chat id matching
+- Discord webhook sender:
+  - send message chunks safely
+  - upload image files
+- Discord slash bot:
+  - register any slash commands dynamically
+  - optional owner and guild restriction
+- Plain text formatter helpers for chat-friendly output
+
+## Install
+
+Requires Python 3.9+.
+
+```bash
+pip install chatops-bridge
+```
+
+For slash-bot support:
+
+```bash
+pip install "chatops-bridge[discord-bot]"
+```
+
+Install from GitHub:
+
+```bash
+pip install git+https://github.com/<your-org>/chatops-bridge.git
+```
+
+## Quick Start
+
+### Telegram
+
+```python
+from chatops_bridge.telegram import send_telegram_message
+
+send_telegram_message(
+    chat_id="123456789",
+    token="<telegram-bot-token>",
+    text="Hello from chatops-bridge",
+)
+```
+
+Send with images:
+
+```python
+send_telegram_message(
+  chat_id="123456789",
+  token="<telegram-bot-token>",
+  text="Report attached",
+  image_paths=["./charts/btc.png", "./charts/eth.png"],
+)
+```
+
+### Discord webhook
+
+```python
+from chatops_bridge.discord import send_discord_message
+
+send_discord_message(
+    webhook_url="https://discord.com/api/webhooks/...",
+    content="Hello from chatops-bridge",
+)
+```
+
+Return value is `True` on success and `False` on failure.
+
+### Discord env-based channel
+
+```python
+from chatops_bridge.discord_channels import send_to_discord_env_channel
+
+# export DISCORD_ALERT_WEBHOOK_URL=...
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered")
+
+# strict mode: fail fast if env var is missing
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered", strict_env=True)
+```
+
+Useful when you want channel routing from environment variables instead of hardcoding webhook URLs.
+
+## Telegram Update Polling
+
+```python
+from chatops_bridge.telegram import fetch_telegram_updates, extract_update_text
+
+updates = fetch_telegram_updates(
+    token="<telegram-bot-token>",
+    offset=None,
+    timeout_seconds=10,
+    allowed_updates=["message", "edited_message"],
+)
+
+for update in updates:
+    text, message = extract_update_text(update)
+    if text:
+        print("message:", text)
+```
+
+## Discord Slash Bot
+
+`chatops_bridge.discord_bot.start_discord_bot(...)` starts a background thread for a Discord bot using your command list.
+
+```python
+import discord
+
+from chatops_bridge.discord_bot import DiscordBotConfig, SlashCommandSpec, start_discord_bot
+
+def ping() -> str:
+  return "pong"
+
+def report() -> dict:
+  return {"text": "Report done", "image_paths": ["./out/chart.png"]}
+
+start_discord_bot(
+  token="<discord-bot-token>",
+  commands=[
+    SlashCommandSpec(name="ping", description="Health check", handler=ping),
+    SlashCommandSpec(name="report", description="Generate report", handler=report),
+  ],
+  config=DiscordBotConfig(
+    intents=discord.Intents(guilds=True),
+    allow_dm_commands=False,
+    leave_unexpected_guild=True,
+    response_chunk_limit=1900,
+    max_images_per_response=10,
+    defer_thinking=True,
+  ),
+  guild_id=None,
+  owner_user_id=None,
+  instance_key="primary",
+)
+```
+
+You can also run the bot with `commands=[]` (or omit `commands`) when your app only needs Discord client events/background tasks.
+
+`instance_key` is used to manage bot thread instances by key. Calling `start_discord_bot` again with the same key returns the existing live thread.
+
+## Slash Bot Example
+
+See [examples/discord_bot_example.py](examples/discord_bot_example.py).
+
+## Telegram Poller Bot
+
+`chatops_bridge.telegram_poller.start_telegram_poller(...)` starts a background polling thread that automatically handles Telegram updates and dispatches them to your command handlers.
+
+```python
+from chatops_bridge.telegram_poller import TelegramCommandSpec, TelegramPollerConfig, start_telegram_poller
+
+def handle_status(args: list[str]) -> str:
+    return "Status: OK"
+
+def handle_trade(args: list[str]) -> str:
+    amount = float(args[0]) if args else 100.0
+    return f"Trading {amount} units"
+
+start_telegram_poller(
+    token="<telegram-bot-token>",
+    commands=[
+        TelegramCommandSpec(
+            name="status",
+            description="Get bot status",
+            handler=handle_status,
+        ),
+        TelegramCommandSpec(
+            name="trade",
+            description="Execute trade",
+            handler=handle_trade,
+        ),
+    ],
+    config=TelegramPollerConfig(
+        poll_timeout_seconds=30,
+        max_retries=3,
+        retry_delay_seconds=5,
+        allowed_updates=["message", "edited_message"],
+        offset_file="/tmp/telegram_offset.txt",  # Persist offset on restart
+    ),
+    logger=print,  # Optional logger
+)
+```
+
+The poller:
+- Runs in background thread(s)
+- Automatically saves offset to persist progress across restarts
+- Retries on network errors with configurable backoff
+- Filters update types (e.g., messages only, skip reactions)
+- Parses `/command arg1 arg2` style messages
+- Dispatches to appropriate handler
+- Sends response back to the originating chat
+
+Handlers receive a list of arguments and return `str` or `dict` (JSON-serialized if dict).
+
+## Telegram Poller Example
+
+See [examples/telegram_poller_example.py](examples/telegram_poller_example.py).
+
+## Common Environment Variables
+
+- `DISCORD_BOT_TOKEN`: bot token used by the slash-bot example.
+- `DISCORD_BOT_GUILD_ID`: optional guild restriction.
+- `DISCORD_BOT_OWNER_USER_ID`: optional owner-only restriction.
+- `TELEGRAM_BOT_TOKEN`: polling bot token.
+- `TELEGRAM_BOT_OFFSET_FILE`: optional path to persist polling offset (for restart safety).
+- Custom webhook URL variables (for env-based routing), for example:
+  - `DISCORD_ALERT_WEBHOOK_URL`
+  - `DISCORD_SIGNAL_WEBHOOK_URL`
+
+## License
+
+MIT
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Making changes and submitting PRs
+- Release procedures
+
+For questions, open an issue on [GitHub](https://github.com/trunghvbk-afataw/chatops/issues).

chatops_bridge-0.1.0/README.md

@@ -0,0 +1,232 @@
+# chatops-bridge
+
+Reusable Telegram and Discord utilities for Python applications.
+
+This package was extracted from production automation code and generalized for multi-purpose ChatOps use.
+Transport-level Telegram/Discord sending is reused from `awesome-notify-bridge`.
+
+## Features
+
+- Telegram send/poll helpers:
+  - send text and images
+  - split long text by Telegram limit
+  - poll updates and extract message text
+  - robust chat id matching
+- Discord webhook sender:
+  - send message chunks safely
+  - upload image files
+- Discord slash bot:
+  - register any slash commands dynamically
+  - optional owner and guild restriction
+- Plain text formatter helpers for chat-friendly output
+
+## Install
+
+Requires Python 3.9+.
+
+```bash
+pip install chatops-bridge
+```
+
+For slash-bot support:
+
+```bash
+pip install "chatops-bridge[discord-bot]"
+```
+
+Install from GitHub:
+
+```bash
+pip install git+https://github.com/<your-org>/chatops-bridge.git
+```
+
+## Quick Start
+
+### Telegram
+
+```python
+from chatops_bridge.telegram import send_telegram_message
+
+send_telegram_message(
+    chat_id="123456789",
+    token="<telegram-bot-token>",
+    text="Hello from chatops-bridge",
+)
+```
+
+Send with images:
+
+```python
+send_telegram_message(
+  chat_id="123456789",
+  token="<telegram-bot-token>",
+  text="Report attached",
+  image_paths=["./charts/btc.png", "./charts/eth.png"],
+)
+```
+
+### Discord webhook
+
+```python
+from chatops_bridge.discord import send_discord_message
+
+send_discord_message(
+    webhook_url="https://discord.com/api/webhooks/...",
+    content="Hello from chatops-bridge",
+)
+```
+
+Return value is `True` on success and `False` on failure.
+
+### Discord env-based channel
+
+```python
+from chatops_bridge.discord_channels import send_to_discord_env_channel
+
+# export DISCORD_ALERT_WEBHOOK_URL=...
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered")
+
+# strict mode: fail fast if env var is missing
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered", strict_env=True)
+```
+
+Useful when you want channel routing from environment variables instead of hardcoding webhook URLs.
+
+## Telegram Update Polling
+
+```python
+from chatops_bridge.telegram import fetch_telegram_updates, extract_update_text
+
+updates = fetch_telegram_updates(
+    token="<telegram-bot-token>",
+    offset=None,
+    timeout_seconds=10,
+    allowed_updates=["message", "edited_message"],
+)
+
+for update in updates:
+    text, message = extract_update_text(update)
+    if text:
+        print("message:", text)
+```
+
+## Discord Slash Bot
+
+`chatops_bridge.discord_bot.start_discord_bot(...)` starts a background thread for a Discord bot using your command list.
+
+```python
+import discord
+
+from chatops_bridge.discord_bot import DiscordBotConfig, SlashCommandSpec, start_discord_bot
+
+def ping() -> str:
+  return "pong"
+
+def report() -> dict:
+  return {"text": "Report done", "image_paths": ["./out/chart.png"]}
+
+start_discord_bot(
+  token="<discord-bot-token>",
+  commands=[
+    SlashCommandSpec(name="ping", description="Health check", handler=ping),
+    SlashCommandSpec(name="report", description="Generate report", handler=report),
+  ],
+  config=DiscordBotConfig(
+    intents=discord.Intents(guilds=True),
+    allow_dm_commands=False,
+    leave_unexpected_guild=True,
+    response_chunk_limit=1900,
+    max_images_per_response=10,
+    defer_thinking=True,
+  ),
+  guild_id=None,
+  owner_user_id=None,
+  instance_key="primary",
+)
+```
+
+You can also run the bot with `commands=[]` (or omit `commands`) when your app only needs Discord client events/background tasks.
+
+`instance_key` is used to manage bot thread instances by key. Calling `start_discord_bot` again with the same key returns the existing live thread.
+
+## Slash Bot Example
+
+See [examples/discord_bot_example.py](examples/discord_bot_example.py).
+
+## Telegram Poller Bot
+
+`chatops_bridge.telegram_poller.start_telegram_poller(...)` starts a background polling thread that automatically handles Telegram updates and dispatches them to your command handlers.
+
+```python
+from chatops_bridge.telegram_poller import TelegramCommandSpec, TelegramPollerConfig, start_telegram_poller
+
+def handle_status(args: list[str]) -> str:
+    return "Status: OK"
+
+def handle_trade(args: list[str]) -> str:
+    amount = float(args[0]) if args else 100.0
+    return f"Trading {amount} units"
+
+start_telegram_poller(
+    token="<telegram-bot-token>",
+    commands=[
+        TelegramCommandSpec(
+            name="status",
+            description="Get bot status",
+            handler=handle_status,
+        ),
+        TelegramCommandSpec(
+            name="trade",
+            description="Execute trade",
+            handler=handle_trade,
+        ),
+    ],
+    config=TelegramPollerConfig(
+        poll_timeout_seconds=30,
+        max_retries=3,
+        retry_delay_seconds=5,
+        allowed_updates=["message", "edited_message"],
+        offset_file="/tmp/telegram_offset.txt",  # Persist offset on restart
+    ),
+    logger=print,  # Optional logger
+)
+```
+
+The poller:
+- Runs in background thread(s)
+- Automatically saves offset to persist progress across restarts
+- Retries on network errors with configurable backoff
+- Filters update types (e.g., messages only, skip reactions)
+- Parses `/command arg1 arg2` style messages
+- Dispatches to appropriate handler
+- Sends response back to the originating chat
+
+Handlers receive a list of arguments and return `str` or `dict` (JSON-serialized if dict).
+
+## Telegram Poller Example
+
+See [examples/telegram_poller_example.py](examples/telegram_poller_example.py).
+
+## Common Environment Variables
+
+- `DISCORD_BOT_TOKEN`: bot token used by the slash-bot example.
+- `DISCORD_BOT_GUILD_ID`: optional guild restriction.
+- `DISCORD_BOT_OWNER_USER_ID`: optional owner-only restriction.
+- `TELEGRAM_BOT_TOKEN`: polling bot token.
+- `TELEGRAM_BOT_OFFSET_FILE`: optional path to persist polling offset (for restart safety).
+- Custom webhook URL variables (for env-based routing), for example:
+  - `DISCORD_ALERT_WEBHOOK_URL`
+  - `DISCORD_SIGNAL_WEBHOOK_URL`
+
+## License
+
+MIT
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Making changes and submitting PRs
+- Release procedures
+
+For questions, open an issue on [GitHub](https://github.com/trunghvbk-afataw/chatops/issues).

chatops_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatops-bridge"
+version = "0.1.0"
+description = "Reusable Telegram and Discord ChatOps utilities for Python projects"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "ChatOps Bridge Contributors" }
+]
+keywords = ["telegram", "discord", "webhook", "chatops", "notifications"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Chat",
+  "Topic :: Software Development :: Libraries"
+]
+dependencies = [
+  "awesome-notify-bridge>=0.1.5"
+]
+
+[project.optional-dependencies]
+discord-bot = [
+  "discord.py>=2.4.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/trunghvbk-afataw/chatops"
+Repository = "https://github.com/trunghvbk-afataw/chatops"
+Issues = "https://github.com/trunghvbk-afataw/chatops/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

chatops_bridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chatops_bridge-0.1.0/src/chatops_bridge/__init__.py

@@ -0,0 +1,23 @@
+"""chatops_bridge public API."""
+
+from .discord import send_discord_message
+from .discord_channels import send_to_discord_env_channel
+from .discord_bot import DiscordBotConfig, SlashCommandSpec
+from .telegram import chat_id_matches, extract_update_text, fetch_telegram_updates, send_telegram_message
+from .telegram_commands import parse_telegram_command
+from .telegram_poller import TelegramCommandSpec, TelegramPollerConfig, start_telegram_poller
+
+__all__ = [
+    "chat_id_matches",
+    "extract_update_text",
+    "fetch_telegram_updates",
+    "parse_telegram_command",
+    "DiscordBotConfig",
+    "SlashCommandSpec",
+    "TelegramCommandSpec",
+    "TelegramPollerConfig",
+    "send_discord_message",
+    "send_telegram_message",
+    "send_to_discord_env_channel",
+    "start_telegram_poller",
+]

chatops_bridge-0.1.0/src/chatops_bridge/discord.py

@@ -0,0 +1,3 @@
+from notify_bridge.discord import send_discord_message
+
+__all__ = ["send_discord_message"]

chatops_bridge-0.1.0/src/chatops_bridge/discord_bot.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Union
+
+import discord
+from discord import app_commands
+
+ResponseHandler = Callable[[], Union[str, dict]]
+
+
+@dataclass(frozen=True)
+class SlashCommandSpec:
+    name: str
+    description: str
+    handler: ResponseHandler
+
+@dataclass
+class DiscordBotConfig:
+    intents: discord.Intents | None = None
+    allow_dm_commands: bool = False
+    leave_unexpected_guild: bool = True
+    response_chunk_limit: int = 1900
+    max_images_per_response: int = 10
+    defer_thinking: bool = True
+    thread_name_prefix: str = "discord-bot"
+
+
+_BOT_THREADS: dict[str, threading.Thread] = {}
+_BOT_LOCK = threading.Lock()
+
+
+def _split_response_text(text: str, limit: int = 1900) -> list[str]:
+    if len(text) <= limit:
+        return [text]
+    chunks: list[str] = []
+    while text:
+        if len(text) <= limit:
+            chunks.append(text)
+            break
+        cut = text.rfind("\n", 0, limit)
+        if cut <= 0:
+            cut = limit
+        chunks.append(text[:cut])
+        text = text[cut:].lstrip("\n")
+    return chunks
+
+
+class DiscordSlashBot(discord.Client):
+    def __init__(
+        self,
+        *,
+        token: str,
+        commands: list[SlashCommandSpec],
+        config: DiscordBotConfig,
+        guild_id: int | None = None,
+        owner_user_id: int | None = None,
+        logger: Callable[[str], None] | None = None,
+    ) -> None:
+        intents = config.intents
+        if intents is None:
+            intents = discord.Intents.none()
+            intents.guilds = True
+        super().__init__(intents=intents)
+        self.tree = app_commands.CommandTree(self)
+        self._token = token
+        self._config = config
+        self._guild_id = guild_id
+        self._owner_user_id = owner_user_id
+        self._commands = commands
+        self._logger = logger or (lambda _msg: None)
+        self._register_commands()
+
+    def _register_commands(self) -> None:
+        for spec in self._commands:
+            self._add_command(spec)
+
+    def _add_command(self, spec: SlashCommandSpec) -> None:
+        @self.tree.command(name=spec.name, description=spec.description)
+        async def _command(interaction: discord.Interaction) -> None:
+            await self._run_command(interaction, spec.handler)
+
+    async def setup_hook(self) -> None:
+        if self._guild_id is not None:
+            guild = discord.Object(id=self._guild_id)
+            self.tree.copy_global_to(guild=guild)
+            synced = await self.tree.sync(guild=guild)
+            self._logger(f"Discord commands synced to guild {self._guild_id}: {len(synced)}")
+            return
+        synced = await self.tree.sync()
+        self._logger(f"Discord global commands synced: {len(synced)}")
+
+    async def on_ready(self) -> None:
+        self._logger(f"Discord bot connected as {self.user}")
+
+    async def on_guild_join(self, guild: discord.Guild) -> None:
+        if self._guild_id is not None and guild.id != self._guild_id and self._config.leave_unexpected_guild:
+            self._logger(f"Joined unexpected guild '{guild.name}' ({guild.id}), leaving.")
+            await guild.leave()
+
+    async def _run_command(self, interaction: discord.Interaction, handler: ResponseHandler) -> None:
+        if self._owner_user_id is not None and interaction.user.id != self._owner_user_id:
+            await interaction.response.send_message("Unauthorized.", ephemeral=True)
+            return
+        if interaction.guild_id is None and not self._config.allow_dm_commands:
+            await interaction.response.send_message("Use this command in the bot server.", ephemeral=True)
+            return
+        if self._guild_id is not None and interaction.guild_id != self._guild_id:
+            await interaction.response.send_message("This bot is not available in this server.", ephemeral=True)
+            return
+        await interaction.response.defer(thinking=self._config.defer_thinking)
+        try:
+            response = await asyncio.to_thread(handler)
+        except Exception as exc:
+            self._logger(f"Discord command failed: {exc}")
+            await interaction.followup.send(f"Command failed: {exc}")
+            return
+        await self._send_response(interaction, response)
+
+    async def _send_response(self, interaction: discord.Interaction, response: str | dict) -> None:
+        text = "Done"
+        image_paths: list[str] = []
+        if isinstance(response, dict):
+            text = str(response.get("text") or response.get("message") or "Done")
+            raw_images = response.get("image_paths") or []
+            if isinstance(raw_images, list):
+                image_paths = [str(path) for path in raw_images if path]
+        else:
+            text = str(response)
+
+        chunks = _split_response_text(text or "Done", limit=max(1, int(self._config.response_chunk_limit)))
+        for chunk in chunks:
+            await interaction.followup.send(chunk)
+
+        valid_files = [
+            discord.File(Path(p), filename=Path(p).name)
+            for p in image_paths[: max(0, int(self._config.max_images_per_response))]
+            if Path(p).exists()
+        ]
+        if valid_files:
+            await interaction.followup.send(files=valid_files)
+
+    def run_bot(self) -> None:
+        self.run(self._token, log_handler=None)
+
+
+def start_discord_bot(
+    *,
+    token: str,
+    commands: list[SlashCommandSpec] | None = None,
+    config: DiscordBotConfig | None = None,
+    guild_id: int | None = None,
+    owner_user_id: int | None = None,
+    instance_key: str = "default",
+    logger: Callable[[str], None] | None = None,
+) -> threading.Thread:
+    resolved_commands = commands or []
+    resolved_config = config or DiscordBotConfig()
+    key = (instance_key or "default").strip() or "default"
+
+    def _run() -> None:
+        bot = DiscordSlashBot(
+            token=token,
+            commands=resolved_commands,
+            config=resolved_config,
+            guild_id=guild_id,
+            owner_user_id=owner_user_id,
+            logger=logger,
+        )
+        bot.run_bot()
+
+    with _BOT_LOCK:
+        existing = _BOT_THREADS.get(key)
+        if existing is not None and existing.is_alive():
+            return existing
+        thread_name = f"{resolved_config.thread_name_prefix}:{key}"
+        thread = threading.Thread(target=_run, name=thread_name, daemon=True)
+        thread.start()
+        _BOT_THREADS[key] = thread
+        return thread

chatops_bridge-0.1.0/src/chatops_bridge/discord_channels.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import os
+from typing import Callable
+
+from .discord import send_discord_message
+
+LoggerFn = Callable[[str], None]
+
+
+def send_to_discord_env_channel(
+    channel_env_var: str,
+    content: str,
+    *,
+    image_paths: list[str] | None = None,
+    logger: LoggerFn | None = None,
+    strict_env: bool = False,
+) -> bool:
+    """Send a message to a Discord webhook URL stored in an environment variable."""
+    webhook_url = os.getenv(channel_env_var, "").strip()
+    if strict_env and not webhook_url:
+        raise ValueError(f"Environment variable '{channel_env_var}' is missing or empty")
+    return send_discord_message(webhook_url, content, image_paths=image_paths, logger=logger)

chatops_bridge-0.1.0/src/chatops_bridge/telegram.py

@@ -0,0 +1,8 @@
+from notify_bridge.telegram import chat_id_matches, extract_update_text, fetch_telegram_updates, send_telegram_message
+
+__all__ = [
+    "chat_id_matches",
+    "extract_update_text",
+    "fetch_telegram_updates",
+    "send_telegram_message",
+]

chatops_bridge-0.1.0/src/chatops_bridge/telegram_commands.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+def parse_telegram_command(text: str) -> tuple[str, list[str]]:
+    """Parse /command args from Telegram message text.
+
+    Supports bot mentions such as /status@my_bot.
+    """
+    raw = (text or "").strip()
+    if not raw.startswith("/"):
+        return "", []
+    parts = raw.split()
+    if not parts:
+        return "", []
+    cmd_token = parts[0][1:].strip().lower()
+    cmd = cmd_token.split("@", 1)[0]
+    args = parts[1:]
+    return cmd, args

chatops_bridge-0.1.0/src/chatops_bridge/telegram_format.py

@@ -0,0 +1,39 @@
+"""Helpers to format text for Telegram plain-text messages."""
+
+from __future__ import annotations
+
+import re
+
+
+def to_plain_text(text: str) -> str:
+    """Convert markdown-like content into plain text for Telegram readability."""
+    if not text:
+        return ""
+
+    out = text
+    out = out.replace("\\r\\n", "\n").replace("\\n", "\n").replace("\\t", "\t")
+
+    out = re.sub(r"```(?:\\w+)?\n", "", out)
+    out = out.replace("```", "")
+    out = re.sub(r"^#{1,6}\\s*", "", out, flags=re.MULTILINE)
+    out = re.sub(r"\\*\\*(.*?)\\*\\*", r"\\1", out, flags=re.DOTALL)
+    out = re.sub(r"__(.*?)__", r"\\1", out, flags=re.DOTALL)
+    out = re.sub(r"`([^`]+)`", r"\\1", out)
+    out = re.sub(r"\\[([^\\]]+)\\]\\(([^)]+)\\)", r"\\1 (\\2)", out)
+    out = re.sub(r"^>\\s?", "", out, flags=re.MULTILINE)
+    out = re.sub(r"^[ \\t]*[-*+]\\s+", "- ", out, flags=re.MULTILINE)
+    out = re.sub(r"\n{3,}", "\n\n", out)
+    return out.strip()
+
+
+def section(title: str, body: str) -> str:
+    """Build a simple titled section for Telegram plain text."""
+    clean_body = to_plain_text(body)
+    if not clean_body:
+        return title
+    return f"{title}:\n{clean_body}"
+
+
+def compact_lines(lines: list[str]) -> str:
+    cleaned = [line for line in lines if line is not None and str(line).strip() != ""]
+    return "\n".join(cleaned).strip()

chatops_bridge-0.1.0/src/chatops_bridge/telegram_poller.py

@@ -0,0 +1,210 @@
+"""Telegram bot poller with background thread management."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Union
+
+from .telegram import fetch_telegram_updates, send_telegram_message, chat_id_matches
+from .telegram_commands import parse_telegram_command
+
+TelegramCommandHandler = Callable[[list[str]], Union[str, dict]]
+
+
+@dataclass
+class TelegramCommandSpec:
+    """Specification for a Telegram bot command."""
+
+    name: str
+    """Command name (e.g., "status", "trade")."""
+
+    description: str
+    """Human-readable description."""
+
+    handler: TelegramCommandHandler
+    """Function that handles the command. Receives list of args, returns response."""
+
+
+@dataclass
+class TelegramPollerConfig:
+    """Configuration for Telegram polling behavior."""
+
+    poll_timeout_seconds: int = 30
+    """Timeout for long polling (0-based)."""
+
+    max_retries: int = 3
+    """Max retries on network error before giving up for that cycle."""
+
+    retry_delay_seconds: int = 5
+    """Delay between retries."""
+
+    allowed_updates: list[str] | None = None
+    """Filter updates (e.g., ["message", "callback_query"]). None = all."""
+
+    offset_file: str | None = None
+    """Path to file for persisting offset (auto-created if missing)."""
+
+    thread_name_prefix: str = "telegram-poller"
+    """Prefix for thread naming."""
+
+
+_TELEGRAM_POLLERS: dict[str, threading.Thread] = {}
+"""Map of instance_key -> polling thread."""
+
+
+def _load_offset(offset_file: str | None) -> int:
+    """Load saved offset from file, or 0 if missing."""
+    if not offset_file:
+        return 0
+    path = Path(offset_file)
+    if path.exists():
+        try:
+            return int(path.read_text().strip())
+        except (ValueError, OSError):
+            return 0
+    return 0
+
+
+def _save_offset(offset_file: str | None, offset: int) -> None:
+    """Save offset to file."""
+    if not offset_file:
+        return
+    path = Path(offset_file)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(str(offset))
+    except OSError:
+        pass
+
+
+def _run_telegram_poller(
+    token: str,
+    commands: list[TelegramCommandSpec],
+    config: TelegramPollerConfig,
+    logger: Callable[[str], None] | None = None,
+    stop_event: threading.Event | None = None,
+) -> None:
+    """Background polling loop for Telegram updates."""
+
+    def log(msg: str) -> None:
+        if logger:
+            logger(f"[telegram-poller] {msg}")
+
+    offset = _load_offset(config.offset_file)
+    log(f"Starting polling with offset={offset}")
+
+    command_map: dict[str, TelegramCommandHandler] = {cmd.name: cmd.handler for cmd in commands}
+
+    while not (stop_event and stop_event.is_set()):
+        try:
+            updates = fetch_telegram_updates(
+                token=token,
+                timeout=config.poll_timeout_seconds,
+                allowed_updates=config.allowed_updates,
+                offset=offset,
+                retries=config.max_retries,
+                retry_delay=config.retry_delay_seconds,
+            )
+
+            for update in updates:
+                try:
+                    message = update.get("message", {})
+                    if not message:
+                        continue
+
+                    text = message.get("text", "").strip()
+                    chat_id = message.get("chat", {}).get("id")
+
+                    if not text or not chat_id:
+                        continue
+
+                    # Parse command
+                    cmd, args = parse_telegram_command(text)
+                    if not cmd:
+                        continue
+
+                    # Dispatch to handler
+                    handler = command_map.get(cmd)
+                    if not handler:
+                        log(f"Unknown command: /{cmd} from chat {chat_id}")
+                        continue
+
+                    log(f"Handling /{cmd} with args {args} from chat {chat_id}")
+                    response = handler(args)
+
+                    # Send response
+                    if isinstance(response, dict):
+                        response_text = json.dumps(response)
+                    else:
+                        response_text = str(response)
+
+                    send_telegram_message(token, chat_id, response_text)
+
+                except Exception as e:
+                    log(f"Error handling update {update.get('update_id')}: {e}")
+                    continue
+
+                # Update offset after successful processing
+                offset = update.get("update_id", offset) + 1
+                _save_offset(config.offset_file, offset)
+
+        except Exception as e:
+            log(f"Polling error: {e}")
+            time.sleep(config.retry_delay_seconds)
+
+
+def start_telegram_poller(
+    *,
+    token: str,
+    commands: list[TelegramCommandSpec],
+    config: TelegramPollerConfig | None = None,
+    logger: Callable[[str], None] | None = None,
+    instance_key: str = "default",
+) -> threading.Thread:
+    """
+    Start a background Telegram polling thread.
+
+    Args:
+        token: Telegram bot token.
+        commands: List of TelegramCommandSpec for command handlers.
+        config: TelegramPollerConfig for polling behavior. Defaults to TelegramPollerConfig().
+        logger: Optional logger function.
+        instance_key: Unique key for this poller instance (allows multiple pollers per process).
+
+    Returns:
+        The polling thread (already started).
+
+    Raises:
+        ValueError: If instance_key is already in use (to prevent duplicate pollers).
+
+    Example:
+        >>> config = TelegramPollerConfig(poll_timeout_seconds=30, offset_file="/tmp/tg_offset")
+        >>> commands = [
+        ...     TelegramCommandSpec("status", "Get status", handler=on_status),
+        ...     TelegramCommandSpec("trade", "Execute trade", handler=on_trade),
+        ... ]
+        >>> thread = start_telegram_poller(token=token, commands=commands, config=config)
+        >>> # Thread is now running in background
+    """
+    if config is None:
+        config = TelegramPollerConfig()
+
+    if instance_key in _TELEGRAM_POLLERS:
+        raise ValueError(f"Telegram poller with instance_key='{instance_key}' already running")
+
+    stop_event = threading.Event()
+    thread = threading.Thread(
+        name=f"{config.thread_name_prefix}-{instance_key}",
+        target=_run_telegram_poller,
+        args=(token, commands, config, logger, stop_event),
+        daemon=True,
+    )
+    thread.start()
+    _TELEGRAM_POLLERS[instance_key] = thread
+
+    return thread

chatops_bridge-0.1.0/src/chatops_bridge.egg-info/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: chatops-bridge
+Version: 0.1.0
+Summary: Reusable Telegram and Discord ChatOps utilities for Python projects
+Author: ChatOps Bridge Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/trunghvbk-afataw/chatops
+Project-URL: Repository, https://github.com/trunghvbk-afataw/chatops
+Project-URL: Issues, https://github.com/trunghvbk-afataw/chatops/issues
+Keywords: telegram,discord,webhook,chatops,notifications
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: awesome-notify-bridge>=0.1.5
+Provides-Extra: discord-bot
+Requires-Dist: discord.py>=2.4.0; extra == "discord-bot"
+Dynamic: license-file
+
+# chatops-bridge
+
+Reusable Telegram and Discord utilities for Python applications.
+
+This package was extracted from production automation code and generalized for multi-purpose ChatOps use.
+Transport-level Telegram/Discord sending is reused from `awesome-notify-bridge`.
+
+## Features
+
+- Telegram send/poll helpers:
+  - send text and images
+  - split long text by Telegram limit
+  - poll updates and extract message text
+  - robust chat id matching
+- Discord webhook sender:
+  - send message chunks safely
+  - upload image files
+- Discord slash bot:
+  - register any slash commands dynamically
+  - optional owner and guild restriction
+- Plain text formatter helpers for chat-friendly output
+
+## Install
+
+Requires Python 3.9+.
+
+```bash
+pip install chatops-bridge
+```
+
+For slash-bot support:
+
+```bash
+pip install "chatops-bridge[discord-bot]"
+```
+
+Install from GitHub:
+
+```bash
+pip install git+https://github.com/<your-org>/chatops-bridge.git
+```
+
+## Quick Start
+
+### Telegram
+
+```python
+from chatops_bridge.telegram import send_telegram_message
+
+send_telegram_message(
+    chat_id="123456789",
+    token="<telegram-bot-token>",
+    text="Hello from chatops-bridge",
+)
+```
+
+Send with images:
+
+```python
+send_telegram_message(
+  chat_id="123456789",
+  token="<telegram-bot-token>",
+  text="Report attached",
+  image_paths=["./charts/btc.png", "./charts/eth.png"],
+)
+```
+
+### Discord webhook
+
+```python
+from chatops_bridge.discord import send_discord_message
+
+send_discord_message(
+    webhook_url="https://discord.com/api/webhooks/...",
+    content="Hello from chatops-bridge",
+)
+```
+
+Return value is `True` on success and `False` on failure.
+
+### Discord env-based channel
+
+```python
+from chatops_bridge.discord_channels import send_to_discord_env_channel
+
+# export DISCORD_ALERT_WEBHOOK_URL=...
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered")
+
+# strict mode: fail fast if env var is missing
+send_to_discord_env_channel("DISCORD_ALERT_WEBHOOK_URL", "Alert triggered", strict_env=True)
+```
+
+Useful when you want channel routing from environment variables instead of hardcoding webhook URLs.
+
+## Telegram Update Polling
+
+```python
+from chatops_bridge.telegram import fetch_telegram_updates, extract_update_text
+
+updates = fetch_telegram_updates(
+    token="<telegram-bot-token>",
+    offset=None,
+    timeout_seconds=10,
+    allowed_updates=["message", "edited_message"],
+)
+
+for update in updates:
+    text, message = extract_update_text(update)
+    if text:
+        print("message:", text)
+```
+
+## Discord Slash Bot
+
+`chatops_bridge.discord_bot.start_discord_bot(...)` starts a background thread for a Discord bot using your command list.
+
+```python
+import discord
+
+from chatops_bridge.discord_bot import DiscordBotConfig, SlashCommandSpec, start_discord_bot
+
+def ping() -> str:
+  return "pong"
+
+def report() -> dict:
+  return {"text": "Report done", "image_paths": ["./out/chart.png"]}
+
+start_discord_bot(
+  token="<discord-bot-token>",
+  commands=[
+    SlashCommandSpec(name="ping", description="Health check", handler=ping),
+    SlashCommandSpec(name="report", description="Generate report", handler=report),
+  ],
+  config=DiscordBotConfig(
+    intents=discord.Intents(guilds=True),
+    allow_dm_commands=False,
+    leave_unexpected_guild=True,
+    response_chunk_limit=1900,
+    max_images_per_response=10,
+    defer_thinking=True,
+  ),
+  guild_id=None,
+  owner_user_id=None,
+  instance_key="primary",
+)
+```
+
+You can also run the bot with `commands=[]` (or omit `commands`) when your app only needs Discord client events/background tasks.
+
+`instance_key` is used to manage bot thread instances by key. Calling `start_discord_bot` again with the same key returns the existing live thread.
+
+## Slash Bot Example
+
+See [examples/discord_bot_example.py](examples/discord_bot_example.py).
+
+## Telegram Poller Bot
+
+`chatops_bridge.telegram_poller.start_telegram_poller(...)` starts a background polling thread that automatically handles Telegram updates and dispatches them to your command handlers.
+
+```python
+from chatops_bridge.telegram_poller import TelegramCommandSpec, TelegramPollerConfig, start_telegram_poller
+
+def handle_status(args: list[str]) -> str:
+    return "Status: OK"
+
+def handle_trade(args: list[str]) -> str:
+    amount = float(args[0]) if args else 100.0
+    return f"Trading {amount} units"
+
+start_telegram_poller(
+    token="<telegram-bot-token>",
+    commands=[
+        TelegramCommandSpec(
+            name="status",
+            description="Get bot status",
+            handler=handle_status,
+        ),
+        TelegramCommandSpec(
+            name="trade",
+            description="Execute trade",
+            handler=handle_trade,
+        ),
+    ],
+    config=TelegramPollerConfig(
+        poll_timeout_seconds=30,
+        max_retries=3,
+        retry_delay_seconds=5,
+        allowed_updates=["message", "edited_message"],
+        offset_file="/tmp/telegram_offset.txt",  # Persist offset on restart
+    ),
+    logger=print,  # Optional logger
+)
+```
+
+The poller:
+- Runs in background thread(s)
+- Automatically saves offset to persist progress across restarts
+- Retries on network errors with configurable backoff
+- Filters update types (e.g., messages only, skip reactions)
+- Parses `/command arg1 arg2` style messages
+- Dispatches to appropriate handler
+- Sends response back to the originating chat
+
+Handlers receive a list of arguments and return `str` or `dict` (JSON-serialized if dict).
+
+## Telegram Poller Example
+
+See [examples/telegram_poller_example.py](examples/telegram_poller_example.py).
+
+## Common Environment Variables
+
+- `DISCORD_BOT_TOKEN`: bot token used by the slash-bot example.
+- `DISCORD_BOT_GUILD_ID`: optional guild restriction.
+- `DISCORD_BOT_OWNER_USER_ID`: optional owner-only restriction.
+- `TELEGRAM_BOT_TOKEN`: polling bot token.
+- `TELEGRAM_BOT_OFFSET_FILE`: optional path to persist polling offset (for restart safety).
+- Custom webhook URL variables (for env-based routing), for example:
+  - `DISCORD_ALERT_WEBHOOK_URL`
+  - `DISCORD_SIGNAL_WEBHOOK_URL`
+
+## License
+
+MIT
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Making changes and submitting PRs
+- Release procedures
+
+For questions, open an issue on [GitHub](https://github.com/trunghvbk-afataw/chatops/issues).

chatops_bridge-0.1.0/src/chatops_bridge.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/chatops_bridge/__init__.py
+src/chatops_bridge/discord.py
+src/chatops_bridge/discord_bot.py
+src/chatops_bridge/discord_channels.py
+src/chatops_bridge/telegram.py
+src/chatops_bridge/telegram_commands.py
+src/chatops_bridge/telegram_format.py
+src/chatops_bridge/telegram_poller.py
+src/chatops_bridge.egg-info/PKG-INFO
+src/chatops_bridge.egg-info/SOURCES.txt
+src/chatops_bridge.egg-info/dependency_links.txt
+src/chatops_bridge.egg-info/requires.txt
+src/chatops_bridge.egg-info/top_level.txt

chatops_bridge-0.1.0/src/chatops_bridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chatops_bridge-0.1.0/src/chatops_bridge.egg-info/requires.txt

@@ -0,0 +1,4 @@
+awesome-notify-bridge>=0.1.5
+
+[discord-bot]
+discord.py>=2.4.0

chatops_bridge-0.1.0/src/chatops_bridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+chatops_bridge