Update README.md

README.md

@@ -18,62 +18,82 @@ pinned: false
 
 ## 🇷🇺 Прокси Telegram Bot API с расширенными инструментами
 
-Этот Space запускает локальный сервер Telegram Bot API и предоставляет многофункциональное Node.js приложение-прокси с дополнительными инструментами. Посетите корневой URL вашего Space для интерактивной документации.
+Этот Space запускает локальный сервер Telegram Bot API (на основе официальной сборки TDLib) и предоставляет многофункциональное Node.js приложение-прокси с дополнительными инструментами для управления файлами и генерации ссылок.
 
-### 1. Основные возможности
+**Посетите корневой URL вашего Space для интерактивной документации по API.**
 
-*   **Проксирование Telegram Bot API**: Доступ к локальному API через ваш Space URL.
-*   **Расширенные ответы API**: Автоматическое добавление прямых и зашифрованных ссылок на скачивание/удаление файлов в ответы методов API, возвращающих информацию о файлах (например, `getMe`, `getFile`, `sendPhoto` и т.д.).
-*   **Управление файлами**:
-    *   Статистика по файлам (количество, общий размер).
-    *   Скачивание файлов по ID или пути.
-    *   Удаление файлов по ID или пути.
-    *   Листинг файлов для конкретного бота.
-*   **Зашифрованные ссылки с истечением срока действия**: Генерация временных, защищенных ссылок на скачивание.
-*   **Автоматическая очистка кэша (TTL)**: Удаление старых файлов.
-*   **Интеграция с GitHub Gist**: Сохранение информации о Space и URL инструментов в Gist.
+### 1. Конфигурация
 
-### 2. Настройка
+#### 1.1. Секреты (Обязательные и Опциональные)
 
-#### 2.1. Необходимые секреты
+Эти переменные должны быть установлены как "Secrets" в настройках вашего Hugging Face Space (`Settings -> Secrets`).
 
-Добавьте следующие секреты в настройках вашего Space (`Settings -> Secrets`):
+| Переменная                  | Обязательность | Описание                                                                                                                               | Пример значения                     |
+| :-------------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
+| `TELEGRAM_API_ID`           | **Обязательно** | Ваш API ID, полученный от Telegram (my.telegram.org).                                                                                  | `1234567`                           |
+| `TELEGRAM_API_HASH`         | **Обязательно** | Ваш API Hash, полученный от Telegram.                                                                                                  | `0123456789abcdef0123456789abcdef` |
+| `GITHUB_TOKEN`              | Опционально    | Персональный токен доступа GitHub с правом `gist`. Необходим для автоматического обновления Gist с информацией о Space.                 | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+| `ENV_GIST_ID`               | Опционально    | ID существующего GitHub Gist, в который будет записываться информация. Требуется, если указан `GITHUB_TOKEN`.                          | `abcdef0123456789abcdef0123456789` |
+| `LINK_ENCRYPTION_KEY`       | Опционально    | Секретная фраза для шифрования полезной нагрузки в ссылках `/downloadEncrypted`. Если не указана, генерация зашифрованных ссылок отключена. | `ОченьДлинныйИСлучайныйКлюч123!`    |
+| `GITHUB_USERNAME`           | Опционально    | Ваш логин на GitHub. Используется для формирования ссылки на Gist. Если не указан, но `GITHUB_TOKEN` и `ENV_GIST_ID` есть, Gist все равно будет обновляться. | `ваш_логин_github`                 |
 
-*   `TELEGRAM_API_ID`: Ваш API ID от Telegram.
-*   `TELEGRAM_API_HASH`: Ваш API Hash от Telegram.
-*   `GITHUB_USERNAME`: Ваш логин на GitHub (для обновления Gist).
-*   `GITHUB_TOKEN`: Ваш Personal Access Token от GitHub с правом `gist`.
-*   `ENV_GIST_ID`: ID вашего GitHub Gist для сохранения информации.
-*   `LINK_ENCRYPTION_KEY`: Секретная фраза для шифрования ссылок (рекомендуется длинная случайная строка).
-*   `DEFAULT_LINK_EXPIRY_HOURS` (опционально): Время жизни зашифрованных ссылок по умолчанию в часах (например, `24`). Значение `-1` означает бессрочные ссылки. По умолчанию: `24`.
+#### 1.2. Переменные Окружения (Настраиваемые с Значениями по Умолчанию)
 
-#### 2.2. Переменные окружения (можно переопределить через секреты)
+Эти переменные можно переопределить, добавив их в "Secrets" вашего Space. Если они не переопределены, используются значения по умолчанию.
 
-*   `INTERNAL_TELEGRAM_API_PORT`: Внутренний порт для `telegram-bot-api` (по умолчанию: `8081`).
-*   `TELEGRAM_DATA_DIR`: Каталог данных для `telegram-bot-api` (по умолчанию: `/var/lib/telegram-bot-api`).
-*   `FILES_TTL`: Время жизни кэшированных файлов в часах для автоудаления (по умолчанию: `-1`, отключено).
-*   `PROXY_TELEGRAM_PATH_PREFIX`: Префикс URL для проксирования Telegram API (по умолчанию: `/tg`).
+| Переменная                     | По умолчанию             | Описание                                                                                                                                                                                             |
+| :----------------------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INTERNAL_TELEGRAM_API_PORT`   | `8081`                   | Внутренний порт, на котором запускается сам процесс `telegram-bot-api`. Node.js приложение проксирует запросы на этот порт.                                                                             |
+| `TELEGRAM_DATA_DIR`            | `/var/lib/telegram-bot-api` | Директория на сервере, где `telegram-bot-api` хранит свои данные, включая кэшированные файлы.                                                                                                       |
+| `FILES_TTL`                    | `-1`                     | Время жизни (TTL) для файлов в кэше `TELEGRAM_DATA_DIR` в часах. Файлы старше этого времени будут периодически удаляться. Значение `-1` отключает автоматическую очистку.                               |
+| `PROXY_TELEGRAM_PATH_PREFIX`   | `/tg`                    | URL-префикс, по которому будет доступен "чистый" прокси к Telegram Bot API. Например, `https://[SPACE_URL]/tg/bot<TOKEN>/METHOD`.                                                                      |
+| `DEFAULT_LINK_EXPIRY_HOURS`    | `24`                     | Время жизни по умолчанию в часах для генерируемых зашифрованных ссылок (через эндпоинт `/file/.../getFile` или при автоматическом расширении ответов). Значение `-1` означает бессрочные ссылки.         |
 
-### 3. Использование API
+### 2. Основные возможности и эндпоинты
 
-**Посетите корневой URL вашего Space (`https://[YOUR_SPACE_URL]/`) для интерактивной документации по API.**
+**Посетите корневой URL вашего Space (`https://[YOUR_SPACE_URL]/`) для интерактивной HTML-документации по всем эндпоинтам.**
 
-Краткое описание:
+Ниже приведено краткое описание:
 
-#### 3.1. Прокси Telegram Bot API
+#### 2.1. "Чистый" Прокси Telegram Bot API
 
 *   **URL**: `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>`
-*   **Описание**: ��спользуйте этот URL вместо стандартного `api.telegram.org`. Ответы API, содержащие информацию о файлах, будут автоматически дополнены полезными ссылками (прямые, зашифрованные, на удаление).
-*   **Управление сроком действия ссылок**: Добавьте параметр `?link_expiry_hours=N` к URL проксируемого запроса.
+*   **Описание**: Прямое проксирование запросов к вашему локальному экземпляру Telegram Bot API. Возвращает **неизмененный** ответ от API. Используйте этот эндпоинт, если вам нужен стандартный ответ API без каких-либо дополнений.
 
-#### 3.2. Инструменты управления
+#### 2.2. Расширенные Инструменты и Операции с Файлами
 
-*   **Статистика**: `https://[YOUR_SPACE_URL]/stats`
-*   **Операции с файлами**: Базовый путь `https://[YOUR_SPACE_URL]/file` (см. документацию на корневом URL для деталей по эндпоинтам `/list`, `/<BOT_TOKEN>/getFile`, `/<BOT_TOKEN>/downloadFile`, и т.д.).
+##### Базовый путь для файловых операций: `https://[YOUR_SPACE_URL]/file`
 
-### 4. Информация в Gist
+1.  **Получение информации о файле с дополнительными ссылками:**
+    *   **Эндпоинт**: `GET /file/<YOUR_BOT_TOKEN>/getFile?file_id=<FILE_ID>`
+    *   **Описание**: Делает запрос к локальному Telegram API (`getFile`), получает стандартный ответ и **дополняет** его следующими полями:
+        *   `direct_download_link_by_path`: Прямая ссылка для скачивания файла по его относительному пути в кэше.
+        *   `direct_download_link_by_id`: Прямая ссылка для скачивания файла через эндпоинт `/downloadFile`.
+        *   `delete_link_by_path`: Ссылка для удаления файла по его относительному пути в кэше.
+        *   `delete_link_by_id`: Ссылка для удаления файла по его ID.
+        *   `encrypted_download_link_by_path` (если `LINK_ENCRYPTION_KEY` установлен): Зашифрованная ссылка на скачивание по пути с ограниченным сроком действия.
+        *   `encrypted_download_link_by_id` (если `LINK_ENCRYPTION_KEY` установлен): Зашифрованная ссылка на скачивание по ID с ограниченным сроком действия.
+    *   **Параметр `link_expiry_hours`**: Можно добавить к запросу (например, `?file_id=...&link_expiry_hours=2`), чтобы указать время жизни для генерируемых зашифрованных ссылок (в часах, `-1` для бессрочных). По умолчанию используется `DEFAULT_LINK_EXPIRY_HOURS`.
 
-Если настроено, информация о вашем Space и полезные URL будут автоматически обновляться в указанном GitHub Gist (файл `hf_space_telegram_bot_api_proxy_info.json`).
+2.  **Другие файловые операции**:
+    *   `GET /stats`: Статистика по файлам в `TELEGRAM_DATA_DIR`.
+        *   Опциональный query-параметр `run_ttl_now=true` для немедленного запуска очистки старых файлов.
+    *   `GET /list?token=<YOUR_BOT_TOKEN>`: Список файлов для указанного бота с размерами.
+    *   `GET /<YOUR_BOT_TOKEN>/downloadFile?file_id=<FILE_ID>`: Скачать файл по ID.
+    *   `GET /<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Скачать файл по его полному относительному пути в кэше (например, `/bot123:abc/photos/file_0.jpg`).
+    *   `GET /downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>`: Скачать файл по зашифрованной полезной нагрузке (полученной из эндпоинта `getFile`).
+    *   `GET /deleteFile?file=<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Удалить файл по его полному относительному пути.
+    *   `GET /<YOUR_BOT_TOKEN>/deleteById?file_id=<FILE_ID>`: Удалить файл по ID.
+
+### 3. Информация в Gist
+
+Если настроены `GITHUB_TOKEN` и `ENV_GIST_ID`, информация о вашем Space (включая полезные URL) будет автоматически обн��вляться в указанном GitHub Gist (в файле с именем `hf_space_telegram_bot_api_proxy_info.json`).
+
+### 4. Важно о путях к файлам
+
+*   Локальный `telegram-bot-api` обычно сохраняет файлы в подкаталоге, названном в честь токена бота (например, `/var/lib/telegram-bot-api/bot123:abc/...`). Файлы в этом кэше могут не иметь расширений или иметь числовые суффиксы.
+*   Относительные пути, используемые в URL инструментов (например, для скачивания или удаления по пути), должны включать эту структуру каталога токена: `bot<TOKEN>/<category>/<filename_in_cache>`.
+*   При скачивании файлов приложение пытается установить корректный `Content-Disposition` и `Content-Type` для лучшего взаимодействия с браузером.
 
 ---
 <br>
@@ -81,59 +101,79 @@ pinned: false
 
 ## 🇬🇧 Telegram Bot API Proxy & Tools
 
-This Space runs a local Telegram Bot API server and provides a feature-rich Node.js proxy application with additional tools. Visit the root URL of your Space for interactive documentation.
+This Space runs a local Telegram Bot API server (based on the official TDLib build) and provides a feature-rich Node.js proxy application with additional tools for file management and link generation.
 
-### 1. Core Features
+**Visit the root URL of your Space for interactive API documentation.**
 
-*   **Telegram Bot API Proxying**: Access your local API via your Space URL.
-*   **Enhanced API Responses**: Automatically augments API method responses that return file information (e.g., `getMe`, `getFile`, `sendPhoto`, etc.) with direct and encrypted download/delete links.
-*   **File Management**:
-    *   File statistics (count, total size).
-    *   Download files by ID or path.
-    *   Delete files by ID or path.
-    *   List files for a specific bot.
-*   **Encrypted Links with Expiry**: Generate temporary, secure download links.
-*   **Automatic Cache Cleanup (TTL)**: Deletion of old files.
-*   **GitHub Gist Integration**: Saves Space information and tool URLs to a Gist.
+### 1. Configuration
 
-### 2. Setup
+#### 1.1. Secrets (Required and Optional)
 
-#### 2.1. Necessary Secrets
+These variables must be set as "Secrets" in your Hugging Face Space settings (`Settings -> Secrets`).
 
-Add the following secrets in your Space settings (`Settings -> Secrets`):
+| Variable                    | Requirement    | Description                                                                                                                               | Example Value                       |
+| :-------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
+| `TELEGRAM_API_ID`           | **Required**   | Your API ID obtained from Telegram (my.telegram.org).                                                                                     | `1234567`                           |
+| `TELEGRAM_API_HASH`         | **Required**   | Your API Hash obtained from Telegram.                                                                                                     | `0123456789abcdef0123456789abcdef` |
+| `GITHUB_TOKEN`              | Optional       | GitHub Personal Access Token with `gist` scope. Needed for automatic Gist updates with Space information.                                 | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+| `ENV_GIST_ID`               | Optional       | ID of an existing GitHub Gist where information will be written. Required if `GITHUB_TOKEN` is provided.                                  | `abcdef0123456789abcdef0123456789` |
+| `LINK_ENCRYPTION_KEY`       | Optional       | Secret passphrase for encrypting payloads in `/downloadEncrypted` links. If not set, encrypted link generation is disabled.                 | `AVeryLongAndRandomKey123!`         |
+| `GITHUB_USERNAME`           | Optional       | Your GitHub username. Used for forming the Gist link. If not set, but `GITHUB_TOKEN` and `ENV_GIST_ID` are, Gist will still be updated. | `your_github_username`            |
 
-*   `TELEGRAM_API_ID`: Your API ID from Telegram.
-*   `TELEGRAM_API_HASH`: Your API Hash from Telegram.
-*   `GITHUB_USERNAME`: Your GitHub login (for Gist updates).
-*   `GITHUB_TOKEN`: Your GitHub Personal Access Token with `gist` scope.
-*   `ENV_GIST_ID`: ID of your GitHub Gist for storing information.
-*   `LINK_ENCRYPTION_KEY`: A secret passphrase for link encryption (a long random string is recommended).
-*   `DEFAULT_LINK_EXPIRY_HOURS` (optional): Default expiry time for encrypted links in hours (e.g., `24`). A value of `-1` means no expiry. Default: `24`.
+#### 1.2. Environment Variables (Configurable with Defaults)
 
-#### 2.2. Environment Variables (can be overridden via secrets)
+These variables can be overridden by adding them to your Space "Secrets". If not overridden, default values are used.
 
-*   `INTERNAL_TELEGRAM_API_PORT`: Internal port for `telegram-bot-api` (default: `8081`).
-*   `TELEGRAM_DATA_DIR`: Data directory for `telegram-bot-api` (default: `/var/lib/telegram-bot-api`).
-*   `FILES_TTL`: Time-to-live for cached files in hours for auto-deletion (default: `-1`, disabled).
-*   `PROXY_TELEGRAM_PATH_PREFIX`: URL prefix for proxying Telegram API calls (default: `/tg`).
+| Variable                       | Default Value            | Description                                                                                                                                                                                          |
+| :----------------------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INTERNAL_TELEGRAM_API_PORT`   | `8081`                   | The internal port on which the `telegram-bot-api` process itself runs. The Node.js application proxies requests to this port.                                                                        |
+| `TELEGRAM_DATA_DIR`            | `/var/lib/telegram-bot-api` | The directory on the server where `telegram-bot-api` stores its data, including cached files.                                                                                                      |
+| `FILES_TTL`                    | `-1`                     | Time-to-live (TTL) for files in the `TELEGRAM_DATA_DIR` cache, in hours. Files older than this will be periodically deleted. A value of `-1` disables automatic cleanup.                               |
+| `PROXY_TELEGRAM_PATH_PREFIX`   | `/tg`                    | The URL prefix where the "clean" proxy to the Telegram Bot API will be available. E.g., `https://[SPACE_URL]/tg/bot<TOKEN>/METHOD`.                                                                   |
+| `DEFAULT_LINK_EXPIRY_HOURS`    | `24`                     | Default lifetime in hours for generated encrypted links (via the `/file/.../getFile` endpoint or when auto-augmenting responses). A value of `-1` means links do not expire.                         |
 
-### 3. API Usage
+### 2. Core Features & Endpoints
 
-**Visit the root URL of your Space (`https://[YOUR_SPACE_URL]/`) for interactive API documentation.**
+**Visit the root URL of your Space (`https://[YOUR_SPACE_URL]/`) for interactive HTML documentation of all endpoints.**
 
-Brief overview:
+Below is a brief overview:
 
-#### 3.1. Telegram Bot API Proxy
+#### 2.1. "Clean" Telegram Bot API Proxy
 
 *   **URL**: `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>`
-*   **Description**: Use this URL instead of the standard `api.telegram.org`. API responses containing file information will be automatically augmented with useful links (direct, encrypted, delete).
-*   **Link Expiry Management**: Add a `?link_expiry_hours=N` query parameter to the proxied request URL.
-
-#### 3.2. Management Tools
-
-*   **Statistics**: `https://[YOUR_SPACE_URL]/stats`
-*   **File Operations**: Base path `https://[YOUR_SPACE_URL]/file` (see documentation at the root URL for details on endpoints like `/list`, `/<BOT_TOKEN>/getFile`, `/<BOT_TOKEN>/downloadFile`, etc.).
-
-### 4. Gist Information
-
-If configured, information about your Space and useful URLs will be automatically updated in the specified GitHub Gist (file `hf_space_telegram_bot_api_proxy_info.json`).
+*   **Description**: Directly proxies requests to your local Telegram Bot API instance. Returns the **unmodified** response from the API. Use this endpoint if you need the standard API response without any additions.
+
+#### 2.2. Enhanced Tools & File Operations
+
+##### Base path for file operations: `https://[YOUR_SPACE_URL]/file`
+
+1.  **Get File Info with Augmented Links:**
+    *   **Endpoint**: `GET /file/<YOUR_BOT_TOKEN>/getFile?file_id=<FILE_ID>`
+    *   **Description**: Makes a request to the local Telegram API (`getFile`), gets the standard response, and then **augments** it with the following fields:
+        *   `direct_download_link_by_path`: Direct link to download the file by its relative path in the cache.
+        *   `direct_download_link_by_id`: Direct link to download the file via the `/downloadFile` endpoint.
+        *   `delete_link_by_path`: Link to delete the file by its relative path in the cache.
+        *   `delete_link_by_id`: Link to delete the file by its ID.
+        *   `encrypted_download_link_by_path` (if `LINK_ENCRYPTION_KEY` is set): Encrypted, time-limited download link by path.
+        *   `encrypted_download_link_by_id` (if `LINK_ENCRYPTION_KEY` is set): Encrypted, time-limited download link by ID.
+    *   **`link_expiry_hours` parameter**: Can be added to the request (e.g., `?file_id=...&link_expiry_hours=2`) to specify the lifetime for generated encrypted links (in hours, `-1` for indefinite). Defaults to `DEFAULT_LINK_EXPIRY_HOURS`.
+
+2.  **Other File Operations**:
+    *   `GET /stats`: Statistics for files in `TELEGRAM_DATA_DIR`.
+        *   Optional query parameter `run_ttl_now=true` to immediately trigger cleanup of old files.
+    *   `GET /list?token=<YOUR_BOT_TOKEN>`: List files for the specified bot with sizes.
+    *   `GET /<YOUR_BOT_TOKEN>/downloadFile?file_id=<FILE_ID>`: Download a file by its ID.
+    *   `GET /<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Download a file by its full relative path in the cache (e.g., `/bot123:abc/photos/file_0.jpg`).
+    *   `GET /downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>`: Download a file using an encrypted payload (obtained from the `getFile` endpoint).
+    *   `GET /deleteFile?file=<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Delete a file by its full relative path.
+    *   `GET /<YOUR_BOT_TOKEN>/deleteById?file_id=<FILE_ID>`: Delete a file by its ID.
+
+### 3. Gist Information
+
+If `GITHUB_TOKEN` and `ENV_GIST_ID` are configured, information about your Space (including useful URLs) will be automatically updated in the specified GitHub Gist (in a file named `hf_space_telegram_bot_api_proxy_info.json`).
+
+### 4. Important Notes on File Paths
+
+*   The local `telegram-bot-api` typically saves files in a subdirectory named after the bot token (e.g., `/var/lib/telegram-bot-api/bot123:abc/...`). Files in this cache may not have extensions or may have numerical suffixes.
+*   Relative paths used in tool URLs (e.g., for download or delete by path) must include this bot token directory structure: `bot<TOKEN>/<category>/<filename_in_cache>`.
+*   When downloading files, the application attempts to set correct `Content-Disposition` and `Content-Type` headers for better browser interaction.