kctl-telegram 0.6.3__tar.gz

kctl_telegram-0.6.3/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_telegram-0.6.3/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-telegram
+Version: 0.6.3
+Summary: Kodemeio Telegram CLI — bot platform management
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.8.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_telegram-0.6.3/README.md

@@ -0,0 +1,71 @@
+# kctl-telegram
+
+Kodemeio Telegram CLI — manage the multi-bot Telegram notification platform.
+
+## Installation
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+```bash
+kctl-telegram config init
+kctl-telegram health
+kctl-telegram dashboard
+kctl-telegram bots list
+```
+
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `config` | Manage CLI configuration and profiles |
+| `health` | Health checks and diagnostics |
+| `dashboard` | System overview dashboard |
+| `bots` | Manage Telegram bots |
+| `groups` | Manage Telegram groups |
+| `messages` | Send and manage messages |
+| `chatwoot` | Manage Chatwoot integrations |
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--quiet` | `-q` | Suppress info messages |
+| `--format` | `-f` | Output format: pretty, json, csv, yaml |
+| `--no-header` | | Suppress table headers (csv) |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--api-key` | | API key override |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `telegram` service key.
+
+```bash
+# Initialize default profile
+kctl-telegram config init
+
+# Add a named profile
+kctl-telegram config add prod \
+  --url https://telegram-api.example.com \
+  --api-key $TELEGRAM_API_KEY
+
+# Switch active profile
+kctl-telegram config use prod
+
+# Show current profile (key masked)
+kctl-telegram config show
+```
+
+## Development
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check src/
+uv run mypy src/
+```

kctl_telegram-0.6.3/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-telegram"
+version = "0.6.3"
+description = "Kodemeio Telegram CLI — bot platform management"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.8.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-telegram = "kctl_telegram.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_telegram.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_telegram"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_telegram-0.6.3/skills/telegram-admin/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: telegram-admin
+description: >
+  Kodemeio Telegram bot platform administration. Supports multiple instances
+  via profiles. Covers multi-bot management, group tracking, message sending/
+  broadcasting/scheduling, Chatwoot inbox integration, health monitoring,
+  and dashboard overview. Use when working with kctl-telegram CLI or managing
+  the kodemeio-telegram FastAPI service.
+version: 1.0.0
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Telegram Administration
+
+## Managed Instances
+
+kctl-telegram supports multiple instances via profiles:
+
+| Profile | URL | Use |
+|---|---|---|
+| `kodemeio` | https://telegram.kodeme.io | Kodemeio notification bots |
+
+```bash
+# Target a specific instance
+kctl-telegram -p kodemeio bots list
+kctl-telegram -p kodemeio health
+
+# Switch default profile
+kctl-telegram config use kodemeio
+```
+
+Config: `~/.config/kodemeio/config.yaml`
+
+## CLI Tool: kctl-telegram
+
+Installed globally via `uv tool install ./cli`. Run `kctl-telegram` from anywhere.
+
+### Global Options
+
+```bash
+kctl-telegram [--json] [--quiet] [--profile NAME] [--url URL] [--api-key KEY] <command>
+```
+
+- `--profile / -p`: target a specific instance
+- `--url`: override API base URL
+- `--api-key`: override API key
+- `--json`: output as JSON (for scripting/piping)
+- `--quiet / -q`: suppress info messages
+
+## Multi-Instance Management
+
+```bash
+kctl-telegram config init                                          # Interactive setup
+kctl-telegram config add <name> --url <url> [--api-key KEY]        # Add/update profile
+kctl-telegram config use <name>                                    # Switch default
+kctl-telegram config remove <name> [--service-only] [--force]      # Remove profile
+kctl-telegram config profiles                                      # List all with status
+kctl-telegram config current                                       # Show active + connection
+kctl-telegram config show                                          # Full config (masked)
+kctl-telegram config set <key> <value>                             # Edit config
+kctl-telegram config test                                          # Test connection
+kctl-telegram config migrate                                       # Migrate flat -> scoped format
+```
+
+## Health & Dashboard
+
+```bash
+kctl-telegram health [--watch] [--interval 10]                     # Health score (0-100)
+kctl-telegram dashboard [--watch] [--interval 10] [--compact]      # System overview
+```
+
+Health scoring: API health (30pts) + readiness (30pts) + bots exist (20pts) + groups exist (20pts).
+
+## Bot Management
+
+```bash
+kctl-telegram bots list                                            # All registered bots
+kctl-telegram bots get <id>                                        # Bot details
+kctl-telegram bots add --token <BOT_TOKEN> [--display-name NAME]   # Register new bot
+kctl-telegram bots update <id> [--display-name] [--is-active]      # Update bot
+kctl-telegram bots remove <id> [--force]                           # Deactivate bot
+```
+
+## Group Management
+
+```bash
+kctl-telegram groups list                                          # All tracked groups
+kctl-telegram groups get <id>                                      # Group details
+kctl-telegram groups update <id> --field <f> --value <v>           # Update group settings
+```
+
+## Message Operations
+
+```bash
+kctl-telegram messages send --chat-id ID --text "msg" [--bot-id] [--parse-mode]   # Send message
+kctl-telegram messages broadcast --text "msg" [--bot-id] [--parse-mode]            # Broadcast to all groups
+kctl-telegram messages schedule --text "msg" --target-id ID --at "ISO" [--bot-id]  # Schedule
+kctl-telegram messages scheduled                                                    # List pending
+kctl-telegram messages cancel <id>                                                  # Cancel scheduled
+```
+
+## Chatwoot Integration
+
+```bash
+kctl-telegram chatwoot list                                        # List Chatwoot inboxes
+kctl-telegram chatwoot add --bot-id ID --inbox-id ID --base-url URL --api-token TK  # Add inbox
+kctl-telegram chatwoot remove <id> [--force]                       # Remove inbox mapping
+```
+
+## API Structure
+
+The CLI talks to the kodemeio-telegram FastAPI service:
+
+- **Base URL**: `https://telegram.kodeme.io/api/v1`
+- **Auth**: `X-Api-Key` header
+- **Resources**: bots, groups, messages, chatwoot/inboxes
+- **Health**: GET /api/v1/health, GET /api/v1/ready
+
+## Architecture
+
+- **FastAPI** + python-telegram-bot (multi-bot, webhook mode)
+- **PostgreSQL** (shared via kodemeio-postgres-16)
+- **Redis** (rate limiting, caching)
+- **BotManager** orchestrates multiple bots
+- **APScheduler** for scheduled messages
+- **Chatwoot/Odoo** integrations via webhook relay
+
+## Troubleshooting
+
+```bash
+# Check health
+kctl-telegram health
+
+# Watch health continuously
+kctl-telegram health --watch
+
+# Test connection
+kctl-telegram config test
+
+# Check bot status
+kctl-telegram bots list
+
+# JSON output for debugging
+kctl-telegram --json bots list | jq .
+```

kctl_telegram-0.6.3/src/kctl_telegram/__init__.py

@@ -0,0 +1,5 @@
+"""Kodemeio Telegram CLI."""
+
+from __future__ import annotations
+
+__version__ = "0.6.3"

kctl_telegram-0.6.3/src/kctl_telegram/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running as python -m kctl_telegram."""
+
+from __future__ import annotations
+
+from kctl_telegram.cli import _run
+
+_run()

kctl_telegram-0.6.3/src/kctl_telegram/cli.py

@@ -0,0 +1,131 @@
+"""Main CLI entry point for kctl-telegram."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+
+from kctl_telegram import __version__
+from kctl_telegram.commands.bots import app as bots_app
+from kctl_telegram.commands.chatwoot import app as chatwoot_app
+from kctl_telegram.commands.config_cmd import app as config_app
+from kctl_telegram.commands.dashboard import app as dashboard_app
+from kctl_telegram.commands.groups import app as groups_app
+from kctl_telegram.commands.health import app as health_app
+from kctl_telegram.commands.messages import app as messages_app
+from kctl_telegram.core.callbacks import AppContext
+from kctl_telegram.core.exceptions import KctlError
+from kctl_telegram.commands.skill_cmd import app as skill_app
+from kctl_telegram.commands.doctor_cmd import app as doctor_app
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-telegram {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-telegram",
+    help="Kodemeio Telegram CLI - manage your Telegram bot gateway.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    format_: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty/json/csv/yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Suppress table headers (csv)")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="API key override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Telegram CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        format=format_,
+        no_header=no_header,
+        profile=profile,
+        url_override=url,
+        api_key_override=api_key,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-telegram", __version__)
+
+
+# Register all command groups
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(bots_app, name="bots")
+app.add_typer(groups_app, name="groups")
+app.add_typer(messages_app, name="messages")
+app.add_typer(chatwoot_app, name="chatwoot")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="telegram", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-telegram."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-telegram", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-telegram")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-telegram", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-telegram", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        from kctl_lib import handle_cli_error
+
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_telegram-0.6.3/src/kctl_telegram/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for kctl-telegram."""

kctl_telegram-0.6.3/src/kctl_telegram/commands/bots.py

@@ -0,0 +1,175 @@
+"""Bot management commands.
+
+List, inspect, create, update, and remove Telegram bots.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_telegram.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Telegram bots.")
+
+
+@app.command("list")
+def list_(ctx: typer.Context) -> None:
+    """List all registered bots."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    c = actx.client
+
+    data = c.get("bots")
+    bots = data.get("results", []) if isinstance(data, dict) else data if isinstance(data, list) else []
+
+    if not bots:
+        out.warn("No bots found.")
+        return
+
+    rows: list[list[str]] = []
+    json_data: list[dict] = []
+
+    for bot in bots:
+        bot_id = str(bot.get("id", ""))
+        username = bot.get("username", "")
+        display_name = bot.get("display_name", "")
+        is_active = bot.get("is_active", False)
+        status = "[green]active[/green]" if is_active else "[red]inactive[/red]"
+
+        rows.append([bot_id, f"@{username}" if username else "-", display_name, status])
+        json_data.append(bot)
+
+    out.table(
+        "Bots",
+        [("ID", "cyan"), ("Username", ""), ("Display Name", ""), ("Status", "")],
+        rows,
+        data_for_json=json_data,
+    )
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    bot_id: Annotated[int, typer.Argument(help="Bot ID")],
+) -> None:
+    """Show bot details."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    c = actx.client
+
+    bot = c.get(f"bots/{bot_id}")
+
+    sections: list[tuple[str, list[tuple[str, str]]]] = []
+
+    info_kvs: list[tuple[str, str]] = [
+        ("ID", str(bot.get("id", ""))),
+        ("Username", f"@{bot.get('username', '')}" if bot.get("username") else "-"),
+        ("Display Name", bot.get("display_name", "")),
+        ("Is Active", "[green]Yes[/green]" if bot.get("is_active") else "[red]No[/red]"),
+    ]
+
+    # Show token masked
+    token = bot.get("token", "")
+    if token:
+        masked = f"{token[:4]}{'*' * (len(token) - 8)}{token[-4:]}" if len(token) > 10 else "****"
+        info_kvs.append(("Token", masked))
+
+    sections.append(("Bot Info", info_kvs))
+
+    # Timestamps
+    ts_kvs: list[tuple[str, str]] = []
+    if bot.get("created_at"):
+        ts_kvs.append(("Created", bot["created_at"]))
+    if bot.get("updated_at"):
+        ts_kvs.append(("Updated", bot["updated_at"]))
+    if ts_kvs:
+        sections.append(("Timestamps", ts_kvs))
+
+    out.detail(f"Bot: {bot.get('display_name', bot.get('username', bot_id))}", sections, data_for_json=bot)
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    token: Annotated[str, typer.Option("--token", help="Telegram bot token from BotFather.")],
+    display_name: Annotated[str | None, typer.Option("--display-name", help="Friendly display name.")] = None,
+) -> None:
+    """Register a new Telegram bot."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    c = actx.client
+
+    payload: dict = {"token": token}
+    if display_name:
+        payload["display_name"] = display_name
+
+    bot = c.post("bots", json=payload)
+
+    out.success(f"Bot created: {bot.get('display_name', bot.get('username', ''))}")
+    out.kv("ID", str(bot.get("id", "")))
+    out.kv("Username", f"@{bot.get('username', '')}" if bot.get("username") else "-")
+    out.kv("Display Name", bot.get("display_name", ""))
+    out.kv("Active", str(bot.get("is_active", True)))
+
+    if actx.output.json_mode:
+        out.raw_json(bot)
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    bot_id: Annotated[int, typer.Argument(help="Bot ID")],
+    display_name: Annotated[str | None, typer.Option("--display-name", help="New display name.")] = None,
+    is_active: Annotated[bool | None, typer.Option("--is-active/--no-active", help="Enable or disable bot.")] = None,
+) -> None:
+    """Update a bot's settings."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    c = actx.client
+
+    payload: dict = {}
+    if display_name is not None:
+        payload["display_name"] = display_name
+    if is_active is not None:
+        payload["is_active"] = is_active
+
+    if not payload:
+        out.warn("No changes specified. Use --display-name or --is-active/--no-active.")
+        raise typer.Exit(1)
+
+    bot = c.patch(f"bots/{bot_id}", json=payload)
+
+    out.success(f"Bot {bot_id} updated")
+    out.kv("Display Name", bot.get("display_name", ""))
+    out.kv("Active", str(bot.get("is_active", "")))
+
+    if actx.output.json_mode:
+        out.raw_json(bot)
+
+
+@app.command()
+def remove(
+    ctx: typer.Context,
+    bot_id: Annotated[int, typer.Argument(help="Bot ID")],
+    force: Annotated[bool, typer.Option("--force", help="Skip confirmation")] = False,
+) -> None:
+    """Remove a bot."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    c = actx.client
+
+    if not force:
+        # Fetch bot info for confirmation
+        try:
+            bot = c.get(f"bots/{bot_id}")
+            name = bot.get("display_name", bot.get("username", str(bot_id)))
+        except Exception:
+            name = str(bot_id)
+
+        if not typer.confirm(f"Remove bot '{name}' (ID: {bot_id})?"):
+            raise typer.Exit(0)
+
+    c.delete(f"bots/{bot_id}")
+    out.success(f"Bot {bot_id} removed")