telebot-py 1.5.0__tar.gz

telebot_py-1.5.0/.gitignore

@@ -0,0 +1,47 @@
+node_modules/
+dist/
+coverage/
+docs/
+python-telegram-bot/
+**/.DS_Store
+*.log
+.env*
+.idea/
+.vscode/
+.claude/
+
+# SQLite test databases & artifacts
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.db
+*.tsbuildinfo
+
+# CodeGraph generated index (SQLite db, daemon socket/pid)
+.codegraph/
+
+# Release pipeline artifact (written by semantic-release successCmd in CI)
+RELEASE_VERSION
+
+# Python (packages/python)
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+# Sphinx output is ignored, but the docs SOURCE must stay tracked
+!packages/python/docs/
+packages/python/docs/_build/
+
+# Go (packages/go)
+*.exe
+*.test
+*.out
+

telebot_py-1.5.0/LICENSE

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

telebot_py-1.5.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: telebot-py
+Version: 1.5.0
+Summary: Async-first Telegram Bot framework for Python, mirroring python-telegram-bot's API
+Project-URL: Homepage, https://github.com/Nam088/telegram-bot-node
+Project-URL: Repository, https://github.com/Nam088/telegram-bot-node
+Project-URL: Issues, https://github.com/Nam088/telegram-bot-node/issues
+Project-URL: Changelog, https://github.com/Nam088/telegram-bot-node/releases
+Author: Nam088
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bot,framework,python-telegram-bot,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: sphinx>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# telebot-py
+
+> Async-first Telegram Bot Framework for Python, mirroring [python-telegram-bot](https://python-telegram-bot.org)'s public API.
+
+<!-- Badges: activate once the package is published and CI workflows are live.
+[![PyPI version](https://img.shields.io/pypi/v/telebot-py)](https://pypi.org/project/telebot-py/)
+[![Python](https://img.shields.io/pypi/pyversions/telebot-py)](https://pypi.org/project/telebot-py/)
+[![CI](https://github.com/Nam088/telegram-bot-node/actions/workflows/ci.yml/badge.svg)](https://github.com/Nam088/telegram-bot-node/actions/workflows/ci.yml)
+-->
+
+`telebot-py` is the third language implementation of this repository's Telegram bot
+framework, alongside [`telebot-ts`](../node) (TypeScript) and
+[`telebot-go`](../go) (Go). It is built from scratch in native Python
+(asyncio-first) and mirrors the python-telegram-bot API in native snake_case,
+including native `&` / `|` / `~` filter operators.
+
+## Features
+
+- **Bot client** over `httpx` (the single required runtime dependency) with retry
+  semantics (429/5xx exponential backoff, `retry_after` honored) and a pluggable
+  transport for offline testing.
+- **Application kernel**: builder, dispatcher with ordered handler groups,
+  long polling and webhook modes, full lifecycle management.
+- **Handlers**: command, message, callback query, conversation
+  (standard/linear/async forms), and the extended handler set.
+- **Composable filters** with native Python operators.
+- **Scheduler**: `JobQueue` with one-shot, repeating, and RRule schedules.
+- **Persistence**: memory, JSON file, and SQLite backends behind one contract.
+- **Plugins** with hooks, ordering, and built-in i18n; **components** for menus
+  and keyboards.
+
+## Installation
+
+Requires Python 3.10+. telebot-py is versioned in lockstep with telebot-ts and
+telebot-go (currently `1.4.0`). Install from PyPI:
+
+```bash
+pip install telebot-py
+```
+
+Or from source:
+
+```bash
+pip install packages/python          # from the repo root
+```
+
+## Quick Start
+
+```python
+from telebot_py import ApplicationBuilder, CallbackContext, CommandHandler, MessageHandler, filters
+from telebot_py.types import Update
+
+
+async def start(update: Update, context: CallbackContext) -> None:
+    await context.bot.send_message(chat_id=update.effective_chat.id, text="Hello!")
+
+
+async def echo(update: Update, context: CallbackContext) -> None:
+    await context.bot.send_message(
+        chat_id=update.effective_chat.id, text=update.effective_message.text
+    )
+
+
+app = ApplicationBuilder().token("YOUR_BOT_TOKEN").build()
+app.add_handler(CommandHandler("start", start))
+app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
+app.run_polling()
+```
+
+## Documentation
+
+Full API reference (kernel, bot, routing, filters, scheduler, storage, plugins,
+components, types) lives in [`docs/`](docs/) and is generated with Sphinx from
+the in-source docstrings. The published site is served by GitHub Pages at
+`https://nam088.github.io/telegram-bot-node/python/` (see the combined
+[docs site](https://nam088.github.io/telegram-bot-node/)).
+
+Build the docs locally (requires the `[dev]` extra):
+
+```bash
+cd packages/python
+source .venv/bin/activate
+sphinx-build -W --keep-going docs docs/_build
+open docs/_build/index.html   # macOS
+```
+
+`-W --keep-going` treats warnings as errors, matching CI. `docs/_build/` is
+gitignored and never committed.
+
+## Development
+
+```bash
+cd packages/python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check src tests scripts && ruff format --check src tests scripts
+mypy --strict src
+pytest --cov=telebot_py --cov-fail-under=80
+python scripts/parity_audit.py   # node/go/python API parity (CI-enforced)
+```
+
+Tests that need a live bot are marked `@pytest.mark.live` and auto-skip unless
+`TEST_BOT_TOKEN` is set. The default suite runs fully offline.
+
+## Releasing
+
+Releases are automated: pushing a tag of the form `packages/python/vX.Y.Z`
+triggers [`python-release.yml`](../../.github/workflows/python-release.yml),
+which builds the package, generates changelog notes from conventional commits
+via [git-cliff](https://git-cliff.org) (scoped to `packages/python/*` in
+[`cliff.toml`](cliff.toml)), creates a GitHub Release, and publishes to PyPI
+using trusted publishing (OIDC — no stored API tokens).
+
+To cut a release locally and verify it before tagging:
+
+```bash
+cd packages/python
+source .venv/bin/activate
+
+python -m build            # produces dist/telebot_py-X.Y.Z.tar.gz + .whl
+twine check dist/*         # validates metadata/README rendering
+sphinx-build -W --keep-going docs docs/_build   # docs gate
+
+git tag packages/python/vX.Y.Z
+git push origin packages/python/vX.Y.Z
+```
+
+Pre-release checklist (manual steps, not automatable offline):
+
+1. Confirm the PyPI name is still available: `pip index versions telebot-py`
+   or browse <https://pypi.org/project/telebot-py/>. If squatted, the fallback
+   name is `telebot-python` (update `pyproject.toml` `[project].name` and the
+   workflow `packages-dir` accordingly).
+2. Bump `version` in [`pyproject.toml`](pyproject.toml) — `docs/conf.py` and
+   the build backend both read it from there.
+3. Ensure CI (`ci.yml`) and the parity audit are green on the commit to tag.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

telebot_py-1.5.0/README.md

@@ -0,0 +1,141 @@
+# telebot-py
+
+> Async-first Telegram Bot Framework for Python, mirroring [python-telegram-bot](https://python-telegram-bot.org)'s public API.
+
+<!-- Badges: activate once the package is published and CI workflows are live.
+[![PyPI version](https://img.shields.io/pypi/v/telebot-py)](https://pypi.org/project/telebot-py/)
+[![Python](https://img.shields.io/pypi/pyversions/telebot-py)](https://pypi.org/project/telebot-py/)
+[![CI](https://github.com/Nam088/telegram-bot-node/actions/workflows/ci.yml/badge.svg)](https://github.com/Nam088/telegram-bot-node/actions/workflows/ci.yml)
+-->
+
+`telebot-py` is the third language implementation of this repository's Telegram bot
+framework, alongside [`telebot-ts`](../node) (TypeScript) and
+[`telebot-go`](../go) (Go). It is built from scratch in native Python
+(asyncio-first) and mirrors the python-telegram-bot API in native snake_case,
+including native `&` / `|` / `~` filter operators.
+
+## Features
+
+- **Bot client** over `httpx` (the single required runtime dependency) with retry
+  semantics (429/5xx exponential backoff, `retry_after` honored) and a pluggable
+  transport for offline testing.
+- **Application kernel**: builder, dispatcher with ordered handler groups,
+  long polling and webhook modes, full lifecycle management.
+- **Handlers**: command, message, callback query, conversation
+  (standard/linear/async forms), and the extended handler set.
+- **Composable filters** with native Python operators.
+- **Scheduler**: `JobQueue` with one-shot, repeating, and RRule schedules.
+- **Persistence**: memory, JSON file, and SQLite backends behind one contract.
+- **Plugins** with hooks, ordering, and built-in i18n; **components** for menus
+  and keyboards.
+
+## Installation
+
+Requires Python 3.10+. telebot-py is versioned in lockstep with telebot-ts and
+telebot-go (currently `1.4.0`). Install from PyPI:
+
+```bash
+pip install telebot-py
+```
+
+Or from source:
+
+```bash
+pip install packages/python          # from the repo root
+```
+
+## Quick Start
+
+```python
+from telebot_py import ApplicationBuilder, CallbackContext, CommandHandler, MessageHandler, filters
+from telebot_py.types import Update
+
+
+async def start(update: Update, context: CallbackContext) -> None:
+    await context.bot.send_message(chat_id=update.effective_chat.id, text="Hello!")
+
+
+async def echo(update: Update, context: CallbackContext) -> None:
+    await context.bot.send_message(
+        chat_id=update.effective_chat.id, text=update.effective_message.text
+    )
+
+
+app = ApplicationBuilder().token("YOUR_BOT_TOKEN").build()
+app.add_handler(CommandHandler("start", start))
+app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
+app.run_polling()
+```
+
+## Documentation
+
+Full API reference (kernel, bot, routing, filters, scheduler, storage, plugins,
+components, types) lives in [`docs/`](docs/) and is generated with Sphinx from
+the in-source docstrings. The published site is served by GitHub Pages at
+`https://nam088.github.io/telegram-bot-node/python/` (see the combined
+[docs site](https://nam088.github.io/telegram-bot-node/)).
+
+Build the docs locally (requires the `[dev]` extra):
+
+```bash
+cd packages/python
+source .venv/bin/activate
+sphinx-build -W --keep-going docs docs/_build
+open docs/_build/index.html   # macOS
+```
+
+`-W --keep-going` treats warnings as errors, matching CI. `docs/_build/` is
+gitignored and never committed.
+
+## Development
+
+```bash
+cd packages/python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check src tests scripts && ruff format --check src tests scripts
+mypy --strict src
+pytest --cov=telebot_py --cov-fail-under=80
+python scripts/parity_audit.py   # node/go/python API parity (CI-enforced)
+```
+
+Tests that need a live bot are marked `@pytest.mark.live` and auto-skip unless
+`TEST_BOT_TOKEN` is set. The default suite runs fully offline.
+
+## Releasing
+
+Releases are automated: pushing a tag of the form `packages/python/vX.Y.Z`
+triggers [`python-release.yml`](../../.github/workflows/python-release.yml),
+which builds the package, generates changelog notes from conventional commits
+via [git-cliff](https://git-cliff.org) (scoped to `packages/python/*` in
+[`cliff.toml`](cliff.toml)), creates a GitHub Release, and publishes to PyPI
+using trusted publishing (OIDC — no stored API tokens).
+
+To cut a release locally and verify it before tagging:
+
+```bash
+cd packages/python
+source .venv/bin/activate
+
+python -m build            # produces dist/telebot_py-X.Y.Z.tar.gz + .whl
+twine check dist/*         # validates metadata/README rendering
+sphinx-build -W --keep-going docs docs/_build   # docs gate
+
+git tag packages/python/vX.Y.Z
+git push origin packages/python/vX.Y.Z
+```
+
+Pre-release checklist (manual steps, not automatable offline):
+
+1. Confirm the PyPI name is still available: `pip index versions telebot-py`
+   or browse <https://pypi.org/project/telebot-py/>. If squatted, the fallback
+   name is `telebot-python` (update `pyproject.toml` `[project].name` and the
+   workflow `packages-dir` accordingly).
+2. Bump `version` in [`pyproject.toml`](pyproject.toml) — `docs/conf.py` and
+   the build backend both read it from there.
+3. Ensure CI (`ci.yml`) and the parity audit are green on the commit to tag.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

telebot_py-1.5.0/examples/conversation.py

@@ -0,0 +1,212 @@
+"""telebot_py conversations demo (L2): all three conversation forms, one bot.
+
+Run with a bot token from @BotFather::
+
+    export TELEGRAM_BOT_TOKEN="123456:ABC..."
+    python examples/conversation.py
+
+Commands:
+    /signup   State-machine conversation (ConversationHandler): name -> age ->
+              confirm, persisted in SQLite; restart the bot mid-flow and it
+              resumes where it left off (SC-005).
+    /survey   Linear conversation (LinearConversationHandler): three ordered
+              steps that advance automatically, one matching reply per step.
+    /profile  Async conversation (AsyncConversationHandler): one ``async def``
+              flow reading answers with ``await conv.ask(...)``.
+    /cancel   Aborts the signup/survey conversations from any step.
+
+Press Ctrl+C for a graceful shutdown; conversation state survives in
+``conversation_demo.db``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from telebot_py import (
+    Application,
+    AsyncConversationHandler,
+    CallbackContext,
+    CommandHandler,
+    ConversationHandler,
+    LinearConversationHandler,
+    MessageHandler,
+    filters,
+)
+from telebot_py.routing import END, AsyncConversation
+from telebot_py.storage import SQLitePersistence
+from telebot_py.types import Update
+
+logging.basicConfig(format="%(asctime)s %(name)s %(levelname)s %(message)s", level=logging.INFO)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logger = logging.getLogger("conversation_demo")
+
+NAME, AGE, CONFIRM = range(3)
+
+
+async def signup_entry(update: Update, context: CallbackContext) -> int:
+    """Start the signup conversation by asking for a name."""
+    chat = update.effective_chat
+    if chat is not None:
+        await context.bot.send_message(chat_id=chat.id, text="What is your name?")
+    return NAME
+
+
+async def signup_name(update: Update, context: CallbackContext) -> int:
+    """Store the name and move on to the age question."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None or context.user_data is None:
+        return NAME
+    context.user_data["name"] = message.text
+    await context.bot.send_message(chat_id=chat.id, text=f"Nice to meet you, {message.text}! Age?")
+    return AGE
+
+
+async def signup_age(update: Update, context: CallbackContext) -> int:
+    """Store the age and ask for confirmation."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None or context.user_data is None:
+        return AGE
+    context.user_data["age"] = message.text
+    await context.bot.send_message(chat_id=chat.id, text="Save this? Reply yes or no.")
+    return CONFIRM
+
+
+async def signup_confirm_yes(update: Update, context: CallbackContext) -> int:
+    """Confirm and close the conversation."""
+    chat = update.effective_chat
+    data = context.user_data or {}
+    if chat is not None:
+        await context.bot.send_message(
+            chat_id=chat.id,
+            text=f"Saved: {data.get('name')}, age {data.get('age')}. Thanks!",
+        )
+    return END
+
+
+async def signup_confirm_no(update: Update, context: CallbackContext) -> int:
+    """Reject the entered data and ask for the age again."""
+    chat = update.effective_chat
+    if chat is not None:
+        await context.bot.send_message(chat_id=chat.id, text="Alright, how old are you?")
+    return AGE
+
+
+async def signup_cancel(update: Update, context: CallbackContext) -> int:
+    """Abort the conversation from any state."""
+    chat = update.effective_chat
+    if chat is not None:
+        await context.bot.send_message(chat_id=chat.id, text="Cancelled. Send /signup to retry.")
+    return END
+
+
+def build_signup_handler() -> ConversationHandler:
+    """Persistent state-machine conversation: name -> age -> confirm."""
+    return ConversationHandler(
+        entry_points=[CommandHandler("signup", signup_entry)],
+        states={
+            NAME: [MessageHandler(filters.TEXT & ~filters.COMMAND, signup_name)],
+            AGE: [MessageHandler(filters.TEXT & ~filters.COMMAND, signup_age)],
+            CONFIRM: [
+                MessageHandler(filters.Regex(r"(?i)^yes$"), signup_confirm_yes),
+                MessageHandler(filters.Regex(r"(?i)^no$"), signup_confirm_no),
+            ],
+        },
+        fallbacks=[CommandHandler("cancel", signup_cancel)],
+        name="signup",
+        persistent=True,
+    )
+
+
+async def survey_intro(update: Update, context: CallbackContext) -> None:
+    """Announce the survey before the first step runs."""
+    chat = update.effective_chat
+    if chat is not None:
+        await context.bot.send_message(chat_id=chat.id, text="Survey time! Favourite colour?")
+
+
+async def survey_colour(update: Update, context: CallbackContext) -> None:
+    """Record the colour answer; the step index advances automatically."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None or context.user_data is None:
+        return
+    context.user_data["colour"] = message.text
+    await context.bot.send_message(chat_id=chat.id, text="Rate this bot from 1 to 5:")
+
+
+async def survey_rating(update: Update, context: CallbackContext) -> None:
+    """Record the numeric rating answer."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None or context.user_data is None:
+        return
+    context.user_data["rating"] = message.text
+    await context.bot.send_message(chat_id=chat.id, text="Any final words?")
+
+
+async def survey_comment(update: Update, context: CallbackContext) -> None:
+    """Record the closing comment; the flow ends after this last step."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None or context.user_data is None:
+        return
+    context.user_data["comment"] = message.text
+    await context.bot.send_message(chat_id=chat.id, text="Thanks for taking the survey!")
+
+
+def build_survey_handler() -> LinearConversationHandler:
+    """Persistent linear conversation advancing exactly one step per reply."""
+    return LinearConversationHandler(
+        entry_points=[CommandHandler("survey", survey_intro)],
+        steps=[
+            [MessageHandler(filters.TEXT & ~filters.COMMAND, survey_colour)],
+            [MessageHandler(filters.Regex(r"^[1-5]$"), survey_rating)],
+            [MessageHandler(filters.TEXT & ~filters.COMMAND, survey_comment)],
+        ],
+        fallbacks=[CommandHandler("cancel", signup_cancel)],
+        name="survey",
+        persistent=True,
+    )
+
+
+async def profile_flow(conv: AsyncConversation, context: CallbackContext) -> None:
+    """Ask-and-wait conversation written as one straight-line coroutine."""
+    name = await conv.ask("What should I call you?")
+    age = await conv.ask(f"Hi {name}! How old are you?")
+    chat_id = conv.chat_id if conv.chat_id is not None else conv.user_id
+    if chat_id is not None:
+        await context.bot.send_message(chat_id=chat_id, text=f"Saved {name}, {age}.")
+
+
+async def on_error(update: Update | None, context: CallbackContext) -> None:
+    """Log handler errors; the polling loop keeps running (FR-013)."""
+    logger.error("Error while processing update %r: %r", update, context.error)
+
+
+def main() -> None:
+    """Build the application with SQLite persistence and poll until Ctrl+C."""
+    token = os.environ.get("TELEGRAM_BOT_TOKEN") or os.environ.get("TEST_BOT_TOKEN")
+    if not token:
+        raise SystemExit("Set TELEGRAM_BOT_TOKEN to a bot token from @BotFather first.")
+
+    app = (
+        Application.builder()
+        .token(token)
+        .persistence(SQLitePersistence("conversation_demo.db"))
+        .build()
+    )
+    app.add_handler(build_signup_handler())
+    app.add_handler(build_survey_handler())
+    app.add_handler(AsyncConversationHandler(profile_flow, entry_command="profile", name="profile"))
+    app.add_error_handler(on_error)
+
+    logger.info("Conversation demo is up; try /signup, /survey, or /profile.")
+    app.run_polling()
+
+
+if __name__ == "__main__":
+    main()

telebot_py-1.5.0/examples/echo_bot.py

@@ -0,0 +1,69 @@
+"""telebot_py quickstart (L1): a live echo bot.
+
+Run with a bot token from @BotFather::
+
+    export TELEGRAM_BOT_TOKEN="123456:ABC..."
+    python examples/echo_bot.py
+
+Send ``/start`` for a greeting; any other text message is echoed back.
+Press Ctrl+C for a clean, graceful shutdown (run_polling installs the
+SIGINT/SIGTERM handlers, drains in-flight updates, and closes the client).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from telebot_py import Application, CallbackContext, CommandHandler, MessageHandler, filters
+from telebot_py.types import Update
+
+logging.basicConfig(format="%(asctime)s %(name)s %(levelname)s %(message)s", level=logging.INFO)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logger = logging.getLogger("echo_bot")
+
+
+async def start(update: Update, context: CallbackContext) -> None:
+    """Reply with a greeting when the user sends ``/start``."""
+    user = update.effective_user
+    chat = update.effective_chat
+    if chat is None:
+        return
+    name = user.first_name if user is not None else "there"
+    await context.bot.send_message(
+        chat_id=chat.id,
+        text=f"Hi {name}! Send me any text and I will echo it back.",
+    )
+
+
+async def echo(update: Update, context: CallbackContext) -> None:
+    """Echo every non-command text message back to its chat."""
+    message = update.effective_message
+    chat = update.effective_chat
+    if message is None or message.text is None or chat is None:
+        return
+    await context.bot.send_message(chat_id=chat.id, text=message.text)
+
+
+async def on_error(update: Update | None, context: CallbackContext) -> None:
+    """Log handler errors; the polling loop keeps running (FR-013)."""
+    logger.error("Error while processing update %r: %r", update, context.error)
+
+
+def main() -> None:
+    """Build the application, register handlers, and poll until Ctrl+C."""
+    token = os.environ.get("TELEGRAM_BOT_TOKEN") or os.environ.get("TEST_BOT_TOKEN")
+    if not token:
+        raise SystemExit("Set TELEGRAM_BOT_TOKEN to a bot token from @BotFather first.")
+
+    app = Application.builder().token(token).build()
+    app.add_handler(CommandHandler("start", start))
+    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
+    app.add_error_handler(on_error)
+
+    logger.info("Echo bot is up; press Ctrl+C to stop.")
+    app.run_polling()
+
+
+if __name__ == "__main__":
+    main()