telegram-signer 1.0.0__tar.gz

telegram-signer-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Amchii
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

telegram-signer-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.1
+Name: telegram-signer
+Version: 1.0.0
+Summary: Telegram check-in scheduler with keyboard clicks and optional AI-assisted captcha handling.
+Author: Telegram Signer Contributors
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/git-buster/telegram-signer
+Project-URL: Repository, https://github.com/git-buster/telegram-signer
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Telegram Signer
+
+Telegram Signer is a Python CLI tool for scheduled Telegram check-ins. It can send
+configured check-in messages, click inline keyboard buttons, handle topic IDs, keep
+SQLite check-in records, and optionally use an OpenAI-compatible API for image or
+math-style verification steps.
+
+This fork is intentionally focused on check-ins only. It does not include extra
+dashboard or message-watching features.
+
+## Features
+
+- Required account name in every command: `telegram-signer <account> ...`
+- Scheduled check-in tasks with cron-style or time-style schedules
+- Legacy config compatibility for existing signer `config.json` files
+- SQLite check-in record storage with lazy migration from `sign_record.json`
+- Telegram forum topic support through `message_thread_id`
+- Action flow support:
+  - send text
+  - send dice
+  - click a button by text
+  - choose an option by image through an LLM
+  - reply to a calculation prompt through an LLM
+  - click captcha buttons according to a slot-machine dice result
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```sh
+pip install -U telegram-signer
+```
+
+## Command Format
+
+The account name is required and comes before the command:
+
+```sh
+telegram-signer account_a login
+telegram-signer account_a logout
+telegram-signer account_a run task_name
+```
+
+Run multiple accounts with your shell by starting separate processes. Keep this to
+five accounts or fewer:
+
+```sh
+telegram-signer account_a run task_a &
+telegram-signer account_b run task_b &
+telegram-signer account_c run task_c &
+```
+
+## Common Commands
+
+```sh
+telegram-signer account_a login
+telegram-signer account_a logout
+telegram-signer account_a list
+telegram-signer account_a reconfig task_name
+telegram-signer account_a run task_name
+telegram-signer account_a run-force task_name
+telegram-signer account_a list-records task_name
+telegram-signer account_a migrate-records
+telegram-signer account_a llm-config
+```
+
+Global options must be placed before the account name:
+
+```sh
+telegram-signer --workdir .signer account_a run task_name
+```
+
+## Config Compatibility
+
+Existing signer configs remain supported. The default path is:
+
+```text
+<workdir>/telegram-signer/config/<task_name>/config.json
+```
+
+Older signer config versions are still migrated through the existing compatibility
+chain. Existing configs from the older path are still read and copied to the new
+path when loaded:
+
+```text
+<workdir>/signs/<task_name>/config.json
+```
+
+Check-in records use SQLite at:
+
+```text
+<workdir>/data.sqlite3
+```
+
+Legacy record files are still readable and can be migrated:
+
+```text
+<workdir>/signs/<task_name>/<user_id>/sign_record.json
+<workdir>/signs/<task_name>/sign_record.json
+```
+
+## Example Config
+
+```json
+{
+  "chats": [
+    {
+      "chat_id": "@target_bot_or_group",
+      "message_thread_id": null,
+      "name": "daily check-in",
+      "delete_after": null,
+      "actions": [
+        {"action": 1, "text": "/checkin"},
+        {"action": 3, "text": "Check in"},
+        {"action": 6, "if_dice_emoji": "🎰"}
+      ],
+      "action_interval": 1
+    }
+  ],
+  "sign_at": "0 6 * * *",
+  "random_seconds": 0,
+  "sign_interval": 1
+}
+```
+
+Action IDs:
+
+| ID | Action |
+| --- | --- |
+| 1 | send text |
+| 2 | send dice |
+| 3 | click keyboard button by text |
+| 4 | choose option by image |
+| 5 | reply to calculation prompt |
+| 6 | solve slot-machine captcha buttons when an `if_*` condition matches |
+
+Slot-machine captcha solving is intentionally conditional. Add at least one of
+these fields to an `action: 6` step:
+
+```json
+{"action": 6, "if_dice_emoji": "🎰"}
+{"action": 6, "if_text": "choose the symbols"}
+{"action": 6, "if_regex": "slot|captcha|verification"}
+```
+
+If no `if_*` condition is present, the action is skipped.
+
+## LLM Configuration
+
+LLM-backed actions read configuration from either environment variables or the
+workdir config file created by `llm-config`.
+
+Environment variables:
+
+```text
+OPENAI_API_KEY
+OPENAI_BASE_URL
+OPENAI_MODEL
+```
+
+Persistent workdir file:
+
+```text
+<workdir>/.openai_config.json
+```
+
+Do not commit sessions, session strings, `.env` files, `.openai_config.json`, logs,
+or local SQLite databases.

telegram-signer-1.0.0/README.md

@@ -0,0 +1,168 @@
+# Telegram Signer
+
+Telegram Signer is a Python CLI tool for scheduled Telegram check-ins. It can send
+configured check-in messages, click inline keyboard buttons, handle topic IDs, keep
+SQLite check-in records, and optionally use an OpenAI-compatible API for image or
+math-style verification steps.
+
+This fork is intentionally focused on check-ins only. It does not include extra
+dashboard or message-watching features.
+
+## Features
+
+- Required account name in every command: `telegram-signer <account> ...`
+- Scheduled check-in tasks with cron-style or time-style schedules
+- Legacy config compatibility for existing signer `config.json` files
+- SQLite check-in record storage with lazy migration from `sign_record.json`
+- Telegram forum topic support through `message_thread_id`
+- Action flow support:
+  - send text
+  - send dice
+  - click a button by text
+  - choose an option by image through an LLM
+  - reply to a calculation prompt through an LLM
+  - click captcha buttons according to a slot-machine dice result
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```sh
+pip install -U telegram-signer
+```
+
+## Command Format
+
+The account name is required and comes before the command:
+
+```sh
+telegram-signer account_a login
+telegram-signer account_a logout
+telegram-signer account_a run task_name
+```
+
+Run multiple accounts with your shell by starting separate processes. Keep this to
+five accounts or fewer:
+
+```sh
+telegram-signer account_a run task_a &
+telegram-signer account_b run task_b &
+telegram-signer account_c run task_c &
+```
+
+## Common Commands
+
+```sh
+telegram-signer account_a login
+telegram-signer account_a logout
+telegram-signer account_a list
+telegram-signer account_a reconfig task_name
+telegram-signer account_a run task_name
+telegram-signer account_a run-force task_name
+telegram-signer account_a list-records task_name
+telegram-signer account_a migrate-records
+telegram-signer account_a llm-config
+```
+
+Global options must be placed before the account name:
+
+```sh
+telegram-signer --workdir .signer account_a run task_name
+```
+
+## Config Compatibility
+
+Existing signer configs remain supported. The default path is:
+
+```text
+<workdir>/telegram-signer/config/<task_name>/config.json
+```
+
+Older signer config versions are still migrated through the existing compatibility
+chain. Existing configs from the older path are still read and copied to the new
+path when loaded:
+
+```text
+<workdir>/signs/<task_name>/config.json
+```
+
+Check-in records use SQLite at:
+
+```text
+<workdir>/data.sqlite3
+```
+
+Legacy record files are still readable and can be migrated:
+
+```text
+<workdir>/signs/<task_name>/<user_id>/sign_record.json
+<workdir>/signs/<task_name>/sign_record.json
+```
+
+## Example Config
+
+```json
+{
+  "chats": [
+    {
+      "chat_id": "@target_bot_or_group",
+      "message_thread_id": null,
+      "name": "daily check-in",
+      "delete_after": null,
+      "actions": [
+        {"action": 1, "text": "/checkin"},
+        {"action": 3, "text": "Check in"},
+        {"action": 6, "if_dice_emoji": "🎰"}
+      ],
+      "action_interval": 1
+    }
+  ],
+  "sign_at": "0 6 * * *",
+  "random_seconds": 0,
+  "sign_interval": 1
+}
+```
+
+Action IDs:
+
+| ID | Action |
+| --- | --- |
+| 1 | send text |
+| 2 | send dice |
+| 3 | click keyboard button by text |
+| 4 | choose option by image |
+| 5 | reply to calculation prompt |
+| 6 | solve slot-machine captcha buttons when an `if_*` condition matches |
+
+Slot-machine captcha solving is intentionally conditional. Add at least one of
+these fields to an `action: 6` step:
+
+```json
+{"action": 6, "if_dice_emoji": "🎰"}
+{"action": 6, "if_text": "choose the symbols"}
+{"action": 6, "if_regex": "slot|captcha|verification"}
+```
+
+If no `if_*` condition is present, the action is skipped.
+
+## LLM Configuration
+
+LLM-backed actions read configuration from either environment variables or the
+workdir config file created by `llm-config`.
+
+Environment variables:
+
+```text
+OPENAI_API_KEY
+OPENAI_BASE_URL
+OPENAI_MODEL
+```
+
+Persistent workdir file:
+
+```text
+<workdir>/.openai_config.json
+```
+
+Do not commit sessions, session strings, `.env` files, `.openai_config.json`, logs,
+or local SQLite databases.

telegram-signer-1.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telegram-signer"
+dynamic = ["version"]
+description = "Telegram check-in scheduler with keyboard clicks and optional AI-assisted captcha handling."
+authors = [
+    { name = "Telegram Signer Contributors" }
+]
+license = { text = "BSD-3-Clause" }
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only"
+]
+dependencies = [
+    "kurigram>=2.2.19,<2.3.0",
+    "click",
+    "pydantic",
+    "openai",
+    "croniter",
+    "json_repair",
+    "typing-extensions",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14.6",
+    "tox>=4.32.0",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/git-buster/telegram-signer"
+Repository = "https://github.com/git-buster/telegram-signer"
+
+[project.scripts]
+telegram-signer = "telegram_signer.__main__:signer"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = { attr = "telegram_signer.__version__" }
+
+[tool.setuptools.packages.find]
+exclude = ["tests*"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+extend-select = [
+    "I", # isort
+    "B", # flake8-bugbear
+    "W", # pycodestyle
+    "C4", # flake8-comprehensions
+]
+ignore = [
+    "E501", # line too long, handled by black
+    "B008", # do not perform function calls in argument defaults
+    "C901", # too complex
+    "W191", # indentation contains tabs
+    "B019", # Use of `functools.lru_cache` or `functools.cache` on methods can lead to memory leaks
+    "B904"  # raise without from inside except
+]
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"
+addopts = [
+    "-vv",
+    "-x",
+    "-W=ignore::DeprecationWarning:pyrogram.utils"
+]
+

telegram-signer-1.0.0/setup.cfg

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

telegram-signer-1.0.0/telegram_signer/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.0"
+

telegram-signer-1.0.0/telegram_signer/__main__.py

@@ -0,0 +1,10 @@
+__all__ = ("signer",)
+
+import sys
+
+
+def signer():
+    from telegram_signer import cli
+
+    sys.exit(cli.telegram_signer())
+

telegram-signer-1.0.0/telegram_signer/_kurigram/__init__.py

@@ -0,0 +1,4 @@
+from .methods import SafeGetForumTopics
+
+__all__ = ["SafeGetForumTopics"]
+

telegram-signer-1.0.0/telegram_signer/_kurigram/methods.py

@@ -0,0 +1,77 @@
+from typing import AsyncGenerator, Union
+
+import pyrogram
+from pyrogram import raw, types, utils
+
+
+class SafeGetForumTopics:
+    """Temporary workaround for Kurigram forum topic pagination.
+
+    Kurigram 2.2.19 may raise AttributeError when the last topic in a page has
+    no ``top_message``. Keep this patch isolated so it can be removed once the
+    upstream method is fixed.
+    """
+
+    async def get_forum_topics(
+        self: "pyrogram.Client",
+        chat_id: Union[int, str],
+        limit: int = 0,
+    ) -> AsyncGenerator["types.ForumTopic", None]:
+        current = 0
+        total = limit or (1 << 31) - 1
+        limit = min(100, total)
+
+        offset_date = 0
+        offset_id = 0
+        offset_topic = 0
+        seen_topic_ids = set()
+
+        while True:
+            result = await self.invoke(
+                raw.functions.messages.GetForumTopics(
+                    peer=await self.resolve_peer(chat_id),
+                    offset_date=offset_date,
+                    offset_id=offset_id,
+                    offset_topic=offset_topic,
+                    limit=limit,
+                )
+            )
+
+            users = {item.id: item for item in result.users}
+            chats = {item.id: item for item in result.chats}
+            messages = {}
+
+            for message in result.messages:
+                if isinstance(message, raw.types.MessageEmpty):
+                    continue
+                messages[message.id] = await types.Message._parse(
+                    self, message, users, chats
+                )
+
+            page_topics = []
+            for topic in result.topics:
+                parsed_topic = types.ForumTopic._parse(
+                    self, topic, messages, users, chats
+                )
+                if parsed_topic is None or parsed_topic.id in seen_topic_ids:
+                    continue
+                seen_topic_ids.add(parsed_topic.id)
+                page_topics.append(parsed_topic)
+
+            if not page_topics:
+                return
+
+            for topic in page_topics:
+                yield topic
+                current += 1
+                if current >= total:
+                    return
+
+            last_topic = page_topics[-1]
+            if last_topic.top_message is None or last_topic.top_message.date is None:
+                return
+
+            offset_id = last_topic.top_message.id
+            offset_date = utils.datetime_to_timestamp(last_topic.top_message.date)
+            offset_topic = last_topic.id
+