tg-ringer 0.1.0__tar.gz

tg_ringer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check tg_caller tests
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package + test deps
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q
+      - name: Import smoke check
+        run: python -c "import tg_caller; print(tg_caller.__version__)"
+      - name: CLI smoke check
+        run: tg-caller --help
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build + validate distribution
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

tg_ringer-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# SECRETS — never commit
+*.session
+*.session-journal
+.login_state.json
+env
+.env
+config
+*.token
+
+# python
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# os
+.DS_Store

tg_ringer-0.1.0/LICENSE

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

tg_ringer-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: tg-ringer
+Version: 0.1.0
+Summary: Ring (call) and message any Telegram user from your own account — urgent alerts via a real Telegram call.
+Project-URL: Homepage, https://github.com/jdp5949/tg-ringer
+Project-URL: Documentation, https://jdp5949.github.io/tg-ringer/
+Project-URL: Repository, https://github.com/jdp5949/tg-ringer
+Project-URL: Issues, https://github.com/jdp5949/tg-ringer/issues
+Author: jdp5949
+License: MIT
+License-File: LICENSE
+Keywords: alert,call,mtproto,notification,telegram,telethon,userbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Requires-Dist: telethon<2,>=1.36
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tg-ringer
+
+Ring (call) and message **any Telegram user from your own account** — a lightweight
+[Telethon](https://github.com/LonamiWebs/Telethon) userbot for **urgent alerts**.
+
+It places a real **private Telegram call** so the target's phone *rings* (no audio
+is streamed — the ring itself is the alert), then hangs up. It can also send direct
+account-to-account messages.
+
+> **This is a userbot (your real account), not a bot.** That is the point — bots
+> cannot place calls. See [⚠️ ToS & bans](#️-tos--bans) before using.
+
+---
+
+## When to use it
+
+| You want… | Use this? |
+|-----------|-----------|
+| Phone to **ring** on a critical event (build failed, server down, prod alert) | ✅ yes |
+| A free alternative to paid call APIs, and you already live in Telegram | ✅ yes |
+| Account-to-account DM from a script (faster than Bot API on a warm connection) | ✅ yes |
+| Spoken/TTS audio in the call | ❌ no — ring only (see [limitations](#limitations)) |
+| Reach someone with **no internet** (real cellular call) | ❌ no — Telegram is VoIP; use Twilio/PSTN |
+| Mass messaging / spam | ❌ absolutely not — instant ban |
+
+---
+
+## Install
+
+```bash
+pip install tg-ringer
+```
+
+Requires Python 3.9+.
+
+---
+
+## Setup (one time)
+
+1. **Get API credentials** at <https://my.telegram.org> → *API development tools* →
+   create an app. Copy the **`api_id`** (number) and **`api_hash`** (string).
+
+2. **Configure.** Either export env vars or write a config file:
+
+   ```bash
+   mkdir -p ~/.config/tg-ringer
+   cat > ~/.config/tg-ringer/config <<'EOF'
+   TG_API_ID=1234567
+   TG_API_HASH=0123456789abcdef0123456789abcdef
+   TG_TARGET=+15551234567      # optional default target
+   RING_SECONDS=20             # optional
+   EOF
+   ```
+
+3. **Log in** (interactive — sends a code to your Telegram app):
+
+   ```bash
+   tg-ringer login
+   ```
+
+   Enter the **userbot account's** phone number, then the login code (delivered
+   *inside Telegram*, not SMS), and a 2FA password if you have one. This creates a
+   session file so future calls run unattended.
+
+> Use a **separate account** as the userbot — not the one you want to ring. You
+> cannot call yourself.
+
+---
+
+## CLI usage
+
+```bash
+# Ring a number (or @username, or numeric id) — phone rings, then hangs up
+tg-ringer call +15551234567
+tg-ringer call @someuser --seconds 30
+tg-ringer call                       # uses TG_TARGET
+
+# Send a direct message
+tg-ringer msg +15551234567 "deploy finished"
+echo "piped body" | tg-ringer msg @someuser
+
+# Who am I logged in as?
+tg-ringer whoami
+```
+
+### In scripts
+
+```bash
+long_task && tg-ringer msg "$ALERT" "✅ done" || tg-ringer call "$ALERT"
+```
+
+---
+
+## Library usage
+
+```python
+import asyncio
+from tg_ringer import TgCaller
+
+async def main():
+    async with TgCaller(api_id=1234567, api_hash="...", session="userbot") as tg:
+        await tg.ring("+15551234567", seconds=20)     # phone rings 20s
+        await tg.message("+15551234567", "heads up")   # direct message
+
+asyncio.run(main())
+```
+
+`TgCaller` methods (all async):
+
+| Method | Does |
+|--------|------|
+| `ring(target, seconds=20)` | Place a private call; phone rings then hangs up. Returns call id. |
+| `message(target, text)` | Send a direct message. Returns message id. |
+| `resolve(target)` | Resolve a `@username`, numeric id, or `+phone` to an entity. |
+| `whoami()` | Return the logged-in account. |
+
+`target` may be a `@username`, a numeric user id, or a `+E164` phone number. A
+phone number is imported as a temporary contact so it can be reached.
+
+---
+
+## Limitations
+
+- **Ring only, no audio.** Playing TTS/sound needs the full encrypted call to
+  connect (WebRTC/Opus). `pytgcalls` covers *group* voice chats, not private 1-to-1
+  calls; private-call audio needs the old `libtgvoip` stack (fragile). For a spoken
+  message, use a PSTN provider (e.g. Twilio).
+- **Internet required on the receiver.** Telegram calls are VoIP.
+- **Calls only land if Telegram lets them.** New accounts, and especially **VoIP
+  numbers**, hit anti-spam (`PeerFloodError`). Best results when caller and target
+  are **mutual contacts**.
+
+---
+
+## ⚠️ ToS & bans
+
+Automating a **user** account (userbot) is a **gray area** under Telegram's Terms of
+Service. Risks you accept by using this:
+
+- Accounts can be **limited or banned**, especially VoIP numbers, new accounts, or
+  any account making automated calls/messages to non-contacts.
+- Keep volume low. Make the caller and target **mutual contacts**. Do **not** spam.
+- Use a throwaway/secondary account as the userbot.
+
+You are responsible for how you use this. See `@SpamBot` in Telegram to check an
+account's restriction status.
+
+---
+
+## Security
+
+- Your `api_hash` and the `*.session` file grant **full access to the userbot
+  account**. Never commit or share them. The config and session live under
+  `~/.config/tg-ringer/` and are git-ignored in this repo.
+- Revoke a leaked session from any Telegram client: *Settings → Devices → Terminate*.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `PeerFloodError` | Account anti-spam limited. Make caller+target mutual contacts; check `@SpamBot`; wait; or use a non-VoIP number. |
+| `session not authorized` | Run `tg-ringer login`. |
+| Login code never arrives | It's delivered **in the Telegram app** ("Telegram" service chat), not SMS. The userbot number must be logged into a Telegram client. |
+| Target not on Telegram | `+phone` must belong to a Telegram account. |
+| No notification but message sent | Receiver chat is muted / OS notifications off. |
+
+---
+
+## License
+
+MIT © jdp5949

tg_ringer-0.1.0/README.md

@@ -0,0 +1,173 @@
+# tg-ringer
+
+Ring (call) and message **any Telegram user from your own account** — a lightweight
+[Telethon](https://github.com/LonamiWebs/Telethon) userbot for **urgent alerts**.
+
+It places a real **private Telegram call** so the target's phone *rings* (no audio
+is streamed — the ring itself is the alert), then hangs up. It can also send direct
+account-to-account messages.
+
+> **This is a userbot (your real account), not a bot.** That is the point — bots
+> cannot place calls. See [⚠️ ToS & bans](#️-tos--bans) before using.
+
+---
+
+## When to use it
+
+| You want… | Use this? |
+|-----------|-----------|
+| Phone to **ring** on a critical event (build failed, server down, prod alert) | ✅ yes |
+| A free alternative to paid call APIs, and you already live in Telegram | ✅ yes |
+| Account-to-account DM from a script (faster than Bot API on a warm connection) | ✅ yes |
+| Spoken/TTS audio in the call | ❌ no — ring only (see [limitations](#limitations)) |
+| Reach someone with **no internet** (real cellular call) | ❌ no — Telegram is VoIP; use Twilio/PSTN |
+| Mass messaging / spam | ❌ absolutely not — instant ban |
+
+---
+
+## Install
+
+```bash
+pip install tg-ringer
+```
+
+Requires Python 3.9+.
+
+---
+
+## Setup (one time)
+
+1. **Get API credentials** at <https://my.telegram.org> → *API development tools* →
+   create an app. Copy the **`api_id`** (number) and **`api_hash`** (string).
+
+2. **Configure.** Either export env vars or write a config file:
+
+   ```bash
+   mkdir -p ~/.config/tg-ringer
+   cat > ~/.config/tg-ringer/config <<'EOF'
+   TG_API_ID=1234567
+   TG_API_HASH=0123456789abcdef0123456789abcdef
+   TG_TARGET=+15551234567      # optional default target
+   RING_SECONDS=20             # optional
+   EOF
+   ```
+
+3. **Log in** (interactive — sends a code to your Telegram app):
+
+   ```bash
+   tg-ringer login
+   ```
+
+   Enter the **userbot account's** phone number, then the login code (delivered
+   *inside Telegram*, not SMS), and a 2FA password if you have one. This creates a
+   session file so future calls run unattended.
+
+> Use a **separate account** as the userbot — not the one you want to ring. You
+> cannot call yourself.
+
+---
+
+## CLI usage
+
+```bash
+# Ring a number (or @username, or numeric id) — phone rings, then hangs up
+tg-ringer call +15551234567
+tg-ringer call @someuser --seconds 30
+tg-ringer call                       # uses TG_TARGET
+
+# Send a direct message
+tg-ringer msg +15551234567 "deploy finished"
+echo "piped body" | tg-ringer msg @someuser
+
+# Who am I logged in as?
+tg-ringer whoami
+```
+
+### In scripts
+
+```bash
+long_task && tg-ringer msg "$ALERT" "✅ done" || tg-ringer call "$ALERT"
+```
+
+---
+
+## Library usage
+
+```python
+import asyncio
+from tg_ringer import TgCaller
+
+async def main():
+    async with TgCaller(api_id=1234567, api_hash="...", session="userbot") as tg:
+        await tg.ring("+15551234567", seconds=20)     # phone rings 20s
+        await tg.message("+15551234567", "heads up")   # direct message
+
+asyncio.run(main())
+```
+
+`TgCaller` methods (all async):
+
+| Method | Does |
+|--------|------|
+| `ring(target, seconds=20)` | Place a private call; phone rings then hangs up. Returns call id. |
+| `message(target, text)` | Send a direct message. Returns message id. |
+| `resolve(target)` | Resolve a `@username`, numeric id, or `+phone` to an entity. |
+| `whoami()` | Return the logged-in account. |
+
+`target` may be a `@username`, a numeric user id, or a `+E164` phone number. A
+phone number is imported as a temporary contact so it can be reached.
+
+---
+
+## Limitations
+
+- **Ring only, no audio.** Playing TTS/sound needs the full encrypted call to
+  connect (WebRTC/Opus). `pytgcalls` covers *group* voice chats, not private 1-to-1
+  calls; private-call audio needs the old `libtgvoip` stack (fragile). For a spoken
+  message, use a PSTN provider (e.g. Twilio).
+- **Internet required on the receiver.** Telegram calls are VoIP.
+- **Calls only land if Telegram lets them.** New accounts, and especially **VoIP
+  numbers**, hit anti-spam (`PeerFloodError`). Best results when caller and target
+  are **mutual contacts**.
+
+---
+
+## ⚠️ ToS & bans
+
+Automating a **user** account (userbot) is a **gray area** under Telegram's Terms of
+Service. Risks you accept by using this:
+
+- Accounts can be **limited or banned**, especially VoIP numbers, new accounts, or
+  any account making automated calls/messages to non-contacts.
+- Keep volume low. Make the caller and target **mutual contacts**. Do **not** spam.
+- Use a throwaway/secondary account as the userbot.
+
+You are responsible for how you use this. See `@SpamBot` in Telegram to check an
+account's restriction status.
+
+---
+
+## Security
+
+- Your `api_hash` and the `*.session` file grant **full access to the userbot
+  account**. Never commit or share them. The config and session live under
+  `~/.config/tg-ringer/` and are git-ignored in this repo.
+- Revoke a leaked session from any Telegram client: *Settings → Devices → Terminate*.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `PeerFloodError` | Account anti-spam limited. Make caller+target mutual contacts; check `@SpamBot`; wait; or use a non-VoIP number. |
+| `session not authorized` | Run `tg-ringer login`. |
+| Login code never arrives | It's delivered **in the Telegram app** ("Telegram" service chat), not SMS. The userbot number must be logged into a Telegram client. |
+| Target not on Telegram | `+phone` must belong to a Telegram account. |
+| No notification but message sent | Receiver chat is muted / OS notifications off. |
+
+---
+
+## License
+
+MIT © jdp5949

tg_ringer-0.1.0/config.example

@@ -0,0 +1,10 @@
+# Copy to ~/.config/tg-ringer/config and fill in.
+# Get TG_API_ID / TG_API_HASH at https://my.telegram.org (API development tools).
+
+TG_API_ID=1234567
+TG_API_HASH=0123456789abcdef0123456789abcdef
+
+# Optional:
+# TG_SESSION=/Users/you/.config/tg-ringer/userbot   # session file path (no .session)
+# TG_TARGET=+15551234567                             # default target
+# RING_SECONDS=20                                    # default ring duration

tg_ringer-0.1.0/docs/_config.yml

@@ -0,0 +1,4 @@
+title: tg-ringer
+description: Ring and message any Telegram user from your own account — urgent alerts via a real Telegram call.
+theme: jekyll-theme-cayman
+show_downloads: false

tg_ringer-0.1.0/docs/index.md

@@ -0,0 +1,99 @@
+# tg-ringer
+
+**Ring (call) and message any Telegram user from your own account.**
+A tiny [Telethon](https://github.com/LonamiWebs/Telethon) userbot for **urgent alerts** —
+it places a real private Telegram call so your phone *rings*, then hangs up.
+
+[⭐ GitHub repo](https://github.com/jdp5949/tg-ringer) ·
+[📦 PyPI](https://pypi.org/project/tg-ringer/)
+
+---
+
+## Why
+
+Telegram **bots cannot place calls**. A *userbot* (your own account, via MTProto)
+can. When a build fails or prod goes down at 3am, a silent push is easy to miss — a
+**ringing phone** is not. `tg-ringer` turns any script event into a phone ring, for
+free, using Telegram you already have.
+
+---
+
+## When to use it
+
+✅ Phone should **ring** on a critical event (CI failure, server down, prod alert)
+✅ Free alternative to paid call APIs, if you already use Telegram
+✅ Account-to-account DMs from scripts
+
+❌ Spoken/TTS audio in the call — *ring only* (use Twilio for voice)
+❌ Reaching someone with **no internet** — Telegram is VoIP (use PSTN)
+❌ Mass messaging / spam — instant ban
+
+---
+
+## Quick start
+
+```bash
+pip install tg-ringer
+```
+
+1. Get `api_id` / `api_hash` at <https://my.telegram.org>.
+2. Put them in `~/.config/tg-ringer/config`:
+
+   ```ini
+   TG_API_ID=1234567
+   TG_API_HASH=0123456789abcdef0123456789abcdef
+   TG_TARGET=+15551234567
+   ```
+
+3. Log in once (use a **separate** account as the userbot — you can't call yourself):
+
+   ```bash
+   tg-ringer login
+   ```
+
+4. Ring it:
+
+   ```bash
+   tg-ringer call +15551234567
+   tg-ringer msg  +15551234567 "deploy done"
+   ```
+
+---
+
+## In scripts
+
+```bash
+long_task && tg-ringer msg "$ALERT" "✅ done" || tg-ringer call "$ALERT"
+```
+
+## In Python
+
+```python
+import asyncio
+from tg_ringer import TgCaller
+
+async def main():
+    async with TgCaller(api_id, api_hash, "userbot") as tg:
+        await tg.ring("+15551234567", seconds=20)
+        await tg.message("+15551234567", "heads up")
+
+asyncio.run(main())
+```
+
+---
+
+## ⚠️ Heads up
+
+- **ToS gray area.** Userbots can be **limited or banned** — especially VoIP numbers
+  and new accounts placing automated calls. Keep volume low, make caller + target
+  **mutual contacts**, use a throwaway account, never spam.
+- **Ring only** — no audio. Receiver needs internet (Telegram is VoIP).
+- `PeerFloodError`? Anti-spam limit. Mutual contacts + `@SpamBot` check + patience,
+  or use a non-VoIP number.
+
+Full docs & troubleshooting: see the
+[README](https://github.com/jdp5949/tg-ringer#readme).
+
+---
+
+<sub>MIT © jdp5949 · This is an independent project, not affiliated with Telegram.</sub>

tg_ringer-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tg-ringer"
+version = "0.1.0"
+description = "Ring (call) and message any Telegram user from your own account — urgent alerts via a real Telegram call."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "jdp5949" }]
+keywords = ["telegram", "call", "alert", "notification", "userbot", "mtproto", "telethon"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Telephony",
+    "Topic :: Communications :: Chat",
+]
+dependencies = ["telethon>=1.36,<2"]
+
+[project.urls]
+Homepage = "https://github.com/jdp5949/tg-ringer"
+Documentation = "https://jdp5949.github.io/tg-ringer/"
+Repository = "https://github.com/jdp5949/tg-ringer"
+Issues = "https://github.com/jdp5949/tg-ringer/issues"
+
+[project.scripts]
+tg-ringer = "tg_ringer.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tg_ringer"]
+
+[project.optional-dependencies]
+dev = ["ruff", "pytest", "build", "twine"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tg_ringer-0.1.0/tests/test_smoke.py

@@ -0,0 +1,41 @@
+"""Offline smoke tests — no network, no Telegram credentials required."""
+
+import pytest
+
+import tg_ringer
+from tg_ringer import TgCaller, cli
+
+
+def test_version():
+    assert isinstance(tg_ringer.__version__, str)
+    assert tg_ringer.__version__.count(".") >= 2
+
+
+def test_exports_client():
+    assert TgCaller is tg_ringer.TgCaller
+
+
+def test_client_constructs(tmp_path):
+    # Building the client must not connect or require valid creds.
+    tg = TgCaller(12345, "0" * 32, session=str(tmp_path / "s"))
+    assert tg.client is not None
+
+
+def test_cli_help_exits_zero(capsys):
+    with pytest.raises(SystemExit) as exc:
+        cli.main(["--help"])
+    assert exc.value.code == 0
+    assert "tg-ringer" in capsys.readouterr().out
+
+
+def test_cli_requires_subcommand():
+    with pytest.raises(SystemExit) as exc:
+        cli.main([])
+    assert exc.value.code != 0
+
+
+@pytest.mark.parametrize("sub", ["login", "call", "msg", "whoami"])
+def test_subcommand_help(sub, capsys):
+    with pytest.raises(SystemExit) as exc:
+        cli.main([sub, "--help"])
+    assert exc.value.code == 0

tg_ringer-0.1.0/tg_ringer/__init__.py

@@ -0,0 +1,23 @@
+"""tg-ringer — ring and message any Telegram user from your own account (userbot).
+
+Account-to-account (MTProto), not a bot. The userbot places a real private
+Telegram call so the target's phone *rings* (use as an urgent alert), or sends
+a direct message.
+
+Basic use:
+
+    import asyncio
+    from tg_ringer import TgCaller
+
+    async def main():
+        async with TgCaller(api_id, api_hash, "userbot") as tg:
+            await tg.ring("+15551234567", seconds=20)
+            await tg.message("+15551234567", "heads up")
+
+    asyncio.run(main())
+"""
+
+from .client import TgCaller
+
+__all__ = ["TgCaller"]
+__version__ = "0.1.0"

tg_ringer-0.1.0/tg_ringer/cli.py

@@ -0,0 +1,154 @@
+"""Command-line interface for tg-ringer.
+
+Commands:
+    tg-ringer login                 one-time interactive login (phone + code)
+    tg-ringer call  TARGET [-s N]   ring a user/number for N seconds
+    tg-ringer msg   TARGET TEXT     send a direct message
+    tg-ringer whoami                show the logged-in userbot account
+
+Config (env vars, or ~/.config/tg-ringer/config as KEY=VALUE lines):
+    TG_API_ID      required
+    TG_API_HASH    required
+    TG_SESSION     session file path (default ~/.config/tg-ringer/userbot)
+    TG_TARGET      default target for call/msg when none is given
+    RING_SECONDS   default ring duration (default 20)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+CONFIG_DIR = Path(
+    os.environ.get("TG_RINGER_HOME", Path.home() / ".config" / "tg-ringer")
+)
+CONFIG_FILE = CONFIG_DIR / "config"
+
+
+def _load_config() -> None:
+    """Load KEY=VALUE lines from the config file into os.environ (no override)."""
+    if not CONFIG_FILE.exists():
+        return
+    for line in CONFIG_FILE.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        os.environ.setdefault(key.strip(), val.strip().strip('"').strip("'"))
+
+
+def _creds() -> tuple[int, str]:
+    _load_config()
+    try:
+        return int(os.environ["TG_API_ID"]), os.environ["TG_API_HASH"]
+    except KeyError:
+        sys.exit(
+            "missing TG_API_ID / TG_API_HASH (env or config file). "
+            "Get them at https://my.telegram.org"
+        )
+
+
+def _session() -> str:
+    sess = os.environ.get("TG_SESSION")
+    if sess:
+        return sess
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    return str(CONFIG_DIR / "userbot")
+
+
+def _target(arg: str | None) -> str:
+    t = arg or os.environ.get("TG_TARGET")
+    if not t:
+        sys.exit("no target: pass one or set TG_TARGET")
+    return t
+
+
+def cmd_login(_args) -> None:
+    # Telethon's sync context manager runs the interactive login (phone, code,
+    # optional 2FA password) via stdin prompts.
+    from telethon.sync import TelegramClient
+
+    api_id, api_hash = _creds()
+    with TelegramClient(_session(), api_id, api_hash) as client:
+        me = client.get_me()
+        print(f"Logged in as {me.first_name} (id {me.id}, @{me.username})")
+        print(f"Session: {_session()}.session")
+
+
+def _run(coro):
+    from .client import TgCaller
+
+    api_id, api_hash = _creds()
+
+    async def runner():
+        async with TgCaller(api_id, api_hash, _session()) as tg:
+            return await coro(tg)
+
+    return asyncio.run(runner())
+
+
+def cmd_call(args) -> None:
+    target = _target(args.target)
+    seconds = args.seconds or int(os.environ.get("RING_SECONDS", "20"))
+
+    async def go(tg):
+        print(f"ringing {target} for {seconds}s ...")
+        cid = await tg.ring(target, seconds=seconds)
+        print(f"done (call id {cid})")
+
+    _run(go)
+
+
+def cmd_msg(args) -> None:
+    target = _target(args.target)
+    text = " ".join(args.text) if args.text else sys.stdin.read()
+
+    async def go(tg):
+        mid = await tg.message(target, text)
+        print(f"sent (msg id {mid})")
+
+    _run(go)
+
+
+def cmd_whoami(_args) -> None:
+    async def go(tg):
+        me = await tg.whoami()
+        print(f"{me.first_name} (id {me.id}, @{me.username})")
+
+    _run(go)
+
+
+def main(argv=None) -> None:
+    p = argparse.ArgumentParser(
+        prog="tg-ringer",
+        description="Ring/message Telegram users from your own account.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("login", help="one-time interactive login").set_defaults(
+        func=cmd_login
+    )
+
+    pc = sub.add_parser("call", help="ring a user/number")
+    pc.add_argument("target", nargs="?", help="username, id, or +phone")
+    pc.add_argument("-s", "--seconds", type=int, help="ring duration")
+    pc.set_defaults(func=cmd_call)
+
+    pm = sub.add_parser("msg", help="send a direct message")
+    pm.add_argument("target", help="username, id, or +phone")
+    pm.add_argument("text", nargs="*", help="message text (or pipe via stdin)")
+    pm.set_defaults(func=cmd_msg)
+
+    sub.add_parser("whoami", help="show logged-in account").set_defaults(
+        func=cmd_whoami
+    )
+
+    args = p.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

tg_ringer-0.1.0/tg_ringer/client.py

@@ -0,0 +1,117 @@
+"""Core async client: resolve targets, ring (private call), and message."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import secrets
+
+from telethon import TelegramClient
+from telethon.tl.functions.contacts import ImportContactsRequest
+from telethon.tl.functions.messages import GetDhConfigRequest
+from telethon.tl.functions.phone import DiscardCallRequest, RequestCallRequest
+from telethon.tl.types import (
+    InputPhoneCall,
+    InputPhoneContact,
+    PhoneCallDiscardReasonHangup,
+    PhoneCallProtocol,
+)
+
+
+class TgCaller:
+    """Userbot wrapper around Telethon for ringing and messaging users.
+
+    Args:
+        api_id: Telegram API id (https://my.telegram.org).
+        api_hash: Telegram API hash.
+        session: Telethon session name or path (a ``.session`` file).
+    """
+
+    def __init__(self, api_id: int, api_hash: str, session: str = "tgcaller"):
+        self.client = TelegramClient(session, api_id, api_hash)
+
+    async def __aenter__(self) -> TgCaller:
+        await self.client.connect()
+        if not await self.client.is_user_authorized():
+            raise RuntimeError("session not authorized — run `tg-ringer login` first")
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.client.disconnect()
+
+    async def resolve(self, target):
+        """Resolve a username, numeric id, or +phone number to an entity.
+
+        A ``+phone`` is imported as a temporary contact so it can be reached;
+        this is what lets you ring a number you have not chatted with before.
+        """
+        if isinstance(target, str) and target.startswith("+"):
+            res = await self.client(
+                ImportContactsRequest(
+                    [
+                        InputPhoneContact(
+                            client_id=0,
+                            phone=target,
+                            first_name="alert",
+                            last_name="target",
+                        )
+                    ]
+                )
+            )
+            if not res.users:
+                raise ValueError(f"{target} is not on Telegram / not resolvable")
+            return res.users[0]
+        return await self.client.get_input_entity(target)
+
+    async def ring(self, target, seconds: int = 20) -> int:
+        """Place a private call so ``target``'s phone rings, then hang up.
+
+        No audio is streamed — the *ring* is the alert. Returns the call id.
+        """
+        peer = await self.resolve(target)
+
+        dh = await self.client(GetDhConfigRequest(version=0, random_length=256))
+        p = int.from_bytes(dh.p, "big")
+        g = dh.g
+        a = int.from_bytes(secrets.token_bytes(256), "big") % p
+        g_a = pow(g, a, p)
+        g_a_hash = hashlib.sha256(g_a.to_bytes(256, "big")).digest()
+
+        protocol = PhoneCallProtocol(
+            min_layer=65,
+            max_layer=92,
+            udp_p2p=True,
+            udp_reflector=True,
+            library_versions=["4.0.0"],
+        )
+        res = await self.client(
+            RequestCallRequest(
+                user_id=peer,
+                random_id=secrets.randbelow(2**31),
+                g_a_hash=g_a_hash,
+                protocol=protocol,
+            )
+        )
+        call = res.phone_call
+        try:
+            await asyncio.sleep(seconds)
+        finally:
+            await self.client(
+                DiscardCallRequest(
+                    peer=InputPhoneCall(id=call.id, access_hash=call.access_hash),
+                    duration=0,
+                    reason=PhoneCallDiscardReasonHangup(),
+                    connection_id=0,
+                )
+            )
+        return call.id
+
+    async def message(self, target, text: str) -> int:
+        """Send a direct message to ``target``. Returns the message id."""
+        peer = await self.resolve(target)
+        msg = await self.client.send_message(peer, text)
+        return msg.id
+
+    async def whoami(self):
+        """Return the logged-in userbot account (Telethon User)."""
+        return await self.client.get_me()