Metadata-Version: 2.1
Name: telegram-signer
Version: 1.0.5
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
Requires-Dist: kurigram <2.3.0,>=2.2.19
Requires-Dist: click
Requires-Dist: pydantic
Requires-Dist: openai
Requires-Dist: croniter
Requires-Dist: json_repair
Requires-Dist: typing-extensions
Description-Content-Type: text/markdown

# 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.
