telefire 0.1.0__tar.gz

telefire-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

telefire-0.1.0/.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Telethon session
+*.session
+*.session-journal
+
+# Vim stuff
+*.swp
+
+# Intellij
+.idea/
+
+# VS Code
+.vscode/
+
+*.pkl
+matrix.jpeg
+matrix.png
+matrix.webm
+matrix.webp
+guamei_*.jpeg
+all_chats
+data.csv
+matrix_all_chats
+matrix_media_decrypt.py
+test.py
+plugins/yvlu/
+src/telefire/plugins/yvlu/
+.pdm-python
+.python-version
+
+# Legacy flat layout (now in src/telefire/)
+/plugins/
+/utils.py
+/telefire.py
+/util/
+
+# pdm
+pdm.lock

telefire-0.1.0/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.8-slim
+
+RUN apt-get update && apt-get install gcc -y && apt-get clean
+
+RUN mkdir -p /tg
+WORKDIR /tg
+
+COPY requirements.txt requirements.txt
+RUN pip install -r requirements.txt
+

telefire-0.1.0/LICENSE

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

telefire-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: telefire
+Version: 0.1.0
+Summary: CLI tool for Telegram automation via user account
+Author-email: Lei Shi <me@leishi.io>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fire>=0.5.0
+Requires-Dist: jieba>=0.42.1
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: mautrix>=0.20.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: telethon>=1.40.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: wordcloud>=1.9.0
+Provides-Extra: ai
+Requires-Dist: g4f>=0.3.8; extra == 'ai'

telefire-0.1.0/README.md

@@ -0,0 +1,121 @@
+<p align="center">
+    <h2 align="center">Telethon X Fire - TeleFire</h2>
+</p>
+
+<p align="center">A set of userful command line tools to interact with telegram.</p>
+
+<p align="center">
+    <b><a href="#what-has-inside">What has inside</a></b>
+    |
+    <b><a href="#how">How</a></b>
+    |
+    <b><a href="#docker">Docker</a></b>
+</p>
+
+
+## What is inside
+
+- :flags:<a href="#get_all_chats">get_all_chats</a>: Fetches all the chat IDs and names.
+- :bookmark_tabs:<a href="#list_messages">list_messages</a>: List messages in a certain chat.
+- :mag:<a href="#search_messages">search_messages</a>: Search messages in a certain chat.
+- :skull:<a href="#delete_all">delete_all</a>: Delete all the messages that you have permission to delete in a certain chat.
+- :question:<a href="#plus_mode">plus_mode</a>: Delete certain messages after certain time.
+- :speech_balloon:<a href="#words_to_ifttt">words_to_ifttt</a>: Send an event to IFTTT when somebody said some words
+  you interested.
+- :heart_eyes:<a href="#other-commands">special_attention_mode</a>: Get notified when someone in special attention mode said something.
+
+## Usage
+
+### Setup
+
+0. [Login to your Telegram account](https://my.telegram.org/auth) with the phone number of the account you wish to use.
+1. Click **API Development tools**.
+2. A `Create new application` window will appear if you didn't create one. Go head and create one.
+3. Once you finish creation, get the `api_id` and `api_hash`, you will use it later.
+
+
+### get_all_chats
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py get_all_chats
+
+-100XXXXXXXXXX: CHANNEL_NAME0
+    XXXXXXXXXX: CHANNEL_NAME1
+```
+Those negative IDs start with `-100` are private groups, that's the only way you can access to these groups. For public groups, you can either use id, public url, username to access to it.
+
+
+### list_messages
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py list_messages --chat [CHAT_IDENTIFIER] [Optional: --user USER_IDENTIFIER]
+```
+For `CHAT_IDENTIFIER`, it can be a chat ID you got from <a href="#get_all_chats">get_all_chats</a>, or it can be something like `t.me/LGTMer` or `LGTMer`.
+
+For `USER_IDENTIFIER`, it can be the user's ID or username.
+
+
+### search_messages
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py search_messages --peer [PEER_IDENTIFIER] --query [QUERY_STRING]
+```
+This command comes with some optional parameters that you can custom:
+- `--slow`: Whether to use telegram's search API or iterate through whole message history to do the search. The later can be comprehensive if you are searching UTF-8 characters such as Chinese.
+- `--limit [INTEGER]`: Set the limit of search result, default `100`.
+- `--from_id [USER_IDENTIFIER]`: The id/username of the message sender.
+
+### delete_all
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py delete_all --chat [CHAT_IDENTIFIER] [Optional: --query QUERY_STRING]
+```
+For `CHAT_IDENTIFIER`, smiliar to `CHAT_IDENTIFIER` in <a href="#get_all_chats">get_all_chats</a>, or it can be something like `t.me/LGTMer` or `LGTMer`.
+
+You can also using the `--query` to specify only messages containing certain string will be deleted.
+
+### plus_mode
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py plus_mode
+```
+It's a command you have to keep it running in the backgroud to use it. It's my personal favorite command! It includes several functions that's interesting and useful:
+- `Auto delete mode`: Add `\[NUMBER][s|m|h|d] ` before the message you want to auto delete after certain time, for example, add `\10s `(notice the space), then this message will be deleted automately after 10 seconds. you can also specify  minutes(`m`), hours(`h`) and days(`d`) as the message experation time.
+- `Shiny mode`: just try it, add `\shiny ` to your original message!.
+- `Search mode`: \search [CHAT] [USERNAME] [Optional: QUERY]
+
+
+### words_to_ifttt
+
+```shell
+TELEGRAM_API_ID=[YOUR_API_ID] TELEGRAM_API_HASH=[YOUR_API_HASH] python telefire.py words_to_ifttt --event [IFTTT EVENT] --key [IFTTT WEBHOOK KEY] [WORDS YOU INTERESTED]
+```
+
+Like `auto_delete`, you need to keep this command running to make it work. For the `event` and `key`, you can get it from [here](https://ifttt.com/maker_webhooks). For `WORDS YOU INTERESTED`, it can be something like `telefire "telefire is so cool"`, then whenever anybody said **telefire** or **telefire is so cool**, an IFTTT event will be sent and you can create an applet to do whatever you like on IFTTT, such as sending notifications, turn on a light, etc.
+
+### Other commands
+
+For all the others commands I didn't methtion or simply too lazy to add docs for it:  
+```shell
+python telefire.py --help
+```
+to get a list of all the available commands. And:
+```shell
+python telefire.py COMMAND - --help
+```
+to learn how to use it.
+
+
+## Docker
+
+This project also come with a `Dockerfile` so that you don't need to setup any python environment, just run the following command:
+```shell
+docker build . -t telefire
+docker run -ti --rm -v $(pwd)/telefire.py:/tg/telefire.py telefire python telefire.py [COMMAND] [OPTIONS]
+```
+And that's it, enjoy!
+
+## TODO
+
+- :heavy_check_mark: For deleting messages, add an option to delete messages based on time instead of always delete all.
+- :heavy_check_mark: A long-running service that will notify user if someone said something contains some interested words.

telefire-0.1.0/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: telefire
+description: Use when the user asks to interact with Telegram — listing chats, searching messages, fetching history, deleting messages, monitoring keywords, generating word clouds, or running any Telegram automation from the CLI
+---
+
+# Telefire
+
+CLI tool for Telegram automation via user account. Built on Telethon + python-fire.
+
+**Install:** `uv tool install telefire` or `pip install telefire`
+**Run pattern:** `telefire <command> --arg1=val1 --arg2=val2`
+
+**IMPORTANT:** All arguments must use named flags (`--chat=X`, `--user=X`). Bare positional args do NOT work with python-fire in this codebase.
+
+## Before Running Any Command
+
+**You MUST verify setup before executing telefire commands.** Follow this checklist:
+
+1. **Check config exists:** `cat ~/.telefire/config.toml`
+   - If missing or empty → run `telefire init` (interactive, needs user input)
+   - Needs `[telegram]` section with `api_id` and `api_hash`
+2. **Check session exists:** `ls ~/.telefire/test.session` or `ls ./test.session`
+   - If missing → run any telefire command (e.g. `telefire get_all_chats`), it will prompt for phone number + verification code (needs user input)
+3. **Check session is valid:** `telefire get_all_chats 2>&1 | head -3`
+   - If it outputs chat list → ready to use
+   - If `ValueError: Please set TELEGRAM_API_ID` → config is missing, go to step 1
+   - If `SessionPasswordNeededError` or auth error → session expired, delete `~/.telefire/test.session` and re-authenticate
+   - If `ConnectionError` → network issue, retry
+
+Credentials can also be set via env vars (`TELEGRAM_API_ID`, `TELEGRAM_API_HASH`) or `.env` file.
+
+## Start Here
+
+Always run `get_all_chats` first to find chat IDs/usernames:
+```bash
+telefire get_all_chats
+```
+Most commands take `--chat=` (username, numeric ID, or display name).
+
+**`--user=` must be a Telegram username or numeric user ID.** Display names do NOT work — they fail with `ValueError: Cannot find any entity`. Use `find_user` to resolve:
+```bash
+telefire find_user --chat=coder_ot --name='风扇'
+# Output: ID: 567376438, Name: 风扇滑翔翼, Username: Fangliding
+```
+
+## Quick Reference
+
+### One-Shot Commands (run and exit)
+
+| Command | Usage | Purpose |
+|---------|-------|---------|
+| `get_all_chats` | `get_all_chats` | List all chats with IDs |
+| `get_entity` | `get_entity --entity=X` | Resolve user/chat info |
+| `find_user` | `find_user --chat=X --name=X [--limit=500]` | Find username/ID from display name |
+| `search_messages` | `search_messages --chat=X --query=X [--user=X] [--slow=True] [--limit=100] [--before=DATE] [--after=DATE]` | Search messages. Fast=server-side (default), slow=full scan |
+| `list_messages` | `list_messages --chat=X [--user=X] [--output=log] [--print_stat=True] [--cut=True] [--before=DATE] [--after=DATE]` | List all messages from a user. `--print_stat` shows hourly distribution, `--cut` enables jieba segmentation |
+| `get_messages_by_ids` | `get_messages_by_ids --chat=X --ids=ID1,ID2` | Fetch specific messages |
+| `summary_messages` | `summary_messages --chat=X [--user=X] [--limit=10]` | Recent messages from user |
+| `list_deleted_user_messages` | `list_deleted_user_messages --chat=X` | Messages from deleted accounts |
+| `delete_all` | `delete_all --chat=X [--before=DATE] [--after=DATE] [--query=X]` | Delete own messages (irreversible, no dry-run) |
+| `word_cloud` | `word_cloud --chat=X [--user=X] [--start=DATE] [--end=DATE]` | Generate word cloud image |
+
+### Long-Running Commands (event listeners, run in tmux/screen)
+
+| Command | Usage | Purpose |
+|---------|-------|---------|
+| `plus_mode` | `plus_mode` | Advanced mode: auto-delete, markdown, search, AI summary |
+| `auto_reply` | `auto_reply --regex=X --reply=X [--chat=X] [--from_sender=X]` | Auto-reply on regex match |
+| `auto_repeat` | `auto_repeat --chat=X` | Repeat when 2 users send same text |
+| `auto_reaction` | `auto_reaction --chat=X --user=X` | Auto-react to user's messages |
+| `words_to_ifttt` | `words_to_ifttt --event=X --key=X WORD1 [WORD2]...` | IFTTT notification on keyword (all chats) |
+| `words_to_pushbullet` | `words_to_pushbullet --token=X --device=X WORD1 [WORD2]...` | Pushbullet notification on keyword (all chats) |
+| `words_notify` | `words_notify --chats=X WORD1 [WORD2]...` | Forward keyword matches to debug channel (specific chats) |
+| `special_attention_mode` | `special_attention_mode --event=X --key=X PERSON1...` | IFTTT notification when specific people speak |
+| `log_chat` | `log_chat` | Log all incoming messages |
+| `wordcloud` | `wordcloud [--db=PATH]` | In-chat word cloud generation (triggered by "wordcloud" message) |
+| `chat_to_redis` | `chat_to_redis [--db=PATH]` | Stream all messages to SQLite |
+
+### Matrix Commands
+
+| Command | Usage | Purpose |
+|---------|-------|---------|
+| `matrix_list_rooms` | `matrix_list_rooms` | List joined Matrix rooms |
+| `matrix_plus_mode` | `matrix_plus_mode` | Matrix plus mode |
+| `matrix_chengyu_bot` | `matrix_chengyu_bot --chat=X [--dry_run=True]` | Chinese idiom game bot |
+
+## Common Workflows
+
+**List messages with hourly stats:**
+```bash
+telefire list_messages --chat=coder_ot --user=Fangliding --print_stat=True
+```
+
+**Search messages from a specific user:**
+```bash
+telefire search_messages --chat=coder_ot --query='keyword' --user=username --limit=500
+```
+
+**Monitor keywords with phone notifications:**
+```bash
+# Pushbullet (direct push) — monitors ALL chats
+telefire words_to_pushbullet --token=TOKEN --device=DEVICE_ID outage alert
+
+# IFTTT webhook — monitors ALL chats
+telefire words_to_ifttt --event=event-name --key=webhook-key outage alert
+
+# Forward to Telegram channel — monitors SPECIFIC chats
+telefire words_notify --chats=chat-id keyword1 keyword2
+```
+
+**Safe message deletion (preview first):**
+```bash
+# Step 1: Preview with list_messages (no delete)
+telefire list_messages --chat=chat-name --user=your-username
+
+# Step 2: Delete (irreversible)
+telefire delete_all --chat=chat-name --before='2024-01-01'
+```
+
+**Plus mode sub-commands** (send as Telegram messages while plus_mode is running):
+- `/Ns MESSAGE` — auto-delete after N seconds (e.g., `/30s hello`)
+- `/Nm`, `/Nh`, `/Nd` — minutes, hours, days
+- `/md` — markdown mode
+- `/search user=X chat=Y query=Z` — search and create results channel
+- `/summary user=X count=N [prompt]` — AI summarize recent messages
+- `/getid` — get user ID (reply to their message)
+- `-paolu` — delete all own messages in current chat
+
+## Known Limitations
+
+- **`--user=` requires username or numeric ID** — display names fail. Use the lookup snippet above to resolve.
+- `delete_all` has **no dry-run mode** — always preview with `list_messages` first
+- `words_to_ifttt` and `words_to_pushbullet` monitor **all chats** — no chat filter (use `words_notify` for specific chats, but it forwards to Telegram, not phone)
+- Log output does **not include message dates** (date line is commented out in base.py)
+- `search_messages` fast mode uses Telegram's server-side `SearchRequest` — **performs poorly with Chinese text**. Use `--slow=True` for Chinese searches (iterates all messages client-side with substring match)
+- `list_messages` and `search_messages` support `--before` and `--after` date filters (parsed by dateutil, e.g. `2024-01-01`, `last week`)
+- Plugins that need storage accept `--db=PATH` for custom SQLite path (defaults to `~/.telefire/data.db`)