Update README.md

README.md

@@ -4,20 +4,28 @@ emoji: 🛠️
 colorFrom: green
 colorTo: blue
 sdk: docker
-app_port: 7860 # Основной порт Telegram Bot API
+app_port: 7860
 pinned: false
 ---
 
-## Telegram Bot API с расширенными инструментами и туннелем
+## Telegram Bot API с расширенными инструментами и прокси (Русский)
 
-Этот Space запускает локальный сервер Telegram Bot API и предоставляет дополнительные инструменты через Node.js Express приложение, доступное по туннелю `localhost.run`:
+Этот Space запускает локальный сервер Telegram Bot API и предоставляет расширенное приложение Node.js Express, доступное по URL-адресу вашего Space, предлагая:
 
-1.  **Статистика по файлам**: Количество файлов и общий размер в директории данных Telegram Bot API.
-2.  **Скачивание файлов**: Возможность скачивать файлы (например, аватарки пользователей), пути к которым возвращает локальный Telegram Bot API.
-3.  **Очистка старых файлов (TTL)**: Автоматическое удаление старых файлов из кэша Telegram Bot API.
-4.  **Обновление Gist**: Информация о Space и URL туннеля к инструментам сохраняется в GitHub Gist.
+1.  **Проксированный Telegram Bot API**: Доступ к вашему локальному Telegram Bot API через `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>`.
+2.  **Статистика файлов**: Получение количества и общего размера файлов в каталоге данных Telegram Bot API через `https://[YOUR_SPACE_URL]/stats`.
+3.  **Расширенные операции с файлами (через префикс `/file/`)**:
+    *   **Список файлов**: `.../file/list?token=<BOT_TOKEN>` - Список всех файлов для указанного бота, включая размеры отдельных файлов и общий размер перечисленных файлов.
+    *   **Получение информации о файле и ссылок**: `.../file/<BOT_TOKEN>/getFile?file_id=<FILE_ID>` - Возвращает ответ `getFile` от Telegram, дополненный прямыми ссылками для скачивания (по пути, по ID и зашифрованной версией).
+    *   **Скачивание по ID**: `.../file/<BOT_TOKEN>/downloadFile?file_id=<FILE_ID>` - Прямое скачивание файла.
+    *   **Скачивание по пути**: `.../file/<BOT_TOKEN_AS_DIR>/<PATH_TO_FILE_INSIDE_BOT_DIR>` - Скачивание, если известен точный относительный путь (например, `.../file/bot123:abc/photos/file_0.jpg`).
+    *   **Зашифрованное скачивание**: `.../file/downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>` - Скачивание с использованием полезной нагрузки из эндпоинта `getFile` (скрывает токен бота и ID файла из прямого URL).
+    *   **Удаление файла по пути**: `.../file/deleteFile?file=<BOT_TOKEN_AS_DIR>/<PATH_TO_FILE_INSIDE_BOT_DIR>` - Удаление файла из кэша с использованием его прямого пути.
+    *   **Удаление файла по ID**: `.../file/<BOT_TOKEN>/deleteById?file_id=<FILE_ID>` - Удаление файла из кэша с использованием токена бота и ID файла (внутренне вызывает `getFile` для определения пути).
+4.  **Очистка кэша (TTL)**: Автоматическое удаление старых файлов из кэша Telegram Bot API.
+5.  **Агрегированное обновление Gist**: Информация об этом Space (включая URL-адреса инструментов) сохраняется в указанный GitHub Gist, агрегируя информацию, если несколько Space указывают на один и тот же файл Gist.
 
-### Необходимые секреты
+### Необходимые секреты (Русский)
 
 Добавьте следующие секреты в настройках вашего Space (`Settings -> Secrets`):
 
@@ -25,21 +33,88 @@ pinned: false
 *   `TELEGRAM_API_HASH`: Ваш API Hash от Telegram.
 *   `GITHUB_USERNAME`: Ваш логин на GitHub (для обновления Gist).
 *   `GITHUB_TOKEN`: Ваш Personal Access Token от GitHub с правом `gist` (для обновления Gist).
-*   `ENV_GIST_ID`: ID вашего GitHub Gist, куда будет сохраняться информация о Space и URL туннеля. Создайте пустой Gist и скопируйте его ID из URL.
+*   `ENV_GIST_ID`: ID вашего GitHub Gist, куда будет сохраняться/обновляться информация о Space. Создайте пустой Gist и скопируйте его ID из URL.
+*   `LINK_ENCRYPTION_KEY`: Секретная фраза (например, длинная случайная строка), используемая для генерации зашифрованных ссылок на скачивание. Если не установлена, зашифрованные ссылки генерироваться не будут.
 
-### Переменные окружения (можно переопределить через секреты)
+### Переменные окружения (можно переопределить через секреты) (Русский)
 
-*   `EXPRESS_PORT`: Внутренний порт для Node.js Express приложения (по умолчанию `3001`).
-*   `TELEGRAM_DATA_DIR`: Директория данных для `telegram-bot-api` (по умолчанию `/var/lib/telegram-bot-api`).
-*   `FILES_TTL`: Время жизни файлов в часах. Старые файлы будут удаляться. Установите `-1` для отключения (по умолчанию `-1`).
+*   `INTERNAL_TELEGRAM_API_PORT`: Порт для внутреннего процесса `telegram-bot-api` (по умолчанию: `8081`). Приложение Node.js проксирует запросы на этот порт.
+*   `TELEGRAM_DATA_DIR`: Каталог данных для `telegram-bot-api` (по умолчанию: `/var/lib/telegram-bot-api`).
+*   `FILES_TTL`: Время жизни кэшированных файлов в часах. Старые файлы автоматически удаляются. Установите `-1` для отключения (по умолчанию: `-1`).
+*   `PROXY_TELEGRAM_PATH_PREFIX`: Префикс URL для проксирования вызовов Telegram API (по умолчанию: `/tg`).
 
-### Как использовать
+### Как использовать (Русский)
 
-1.  **Основной API**: Доступен через стандартный URL вашего Space на порту `7860`.
-2.  **Инструменты (статистика, файлы)**:
-    *   URL туннеля будет выведен в логах Space при запуске и сохранен в указанный `ENV_GIST_ID`.
-    *   **Статистика**: `[URL_туннеля]/stats`
-    *   **Скачивание файла**:
-        Если `telegram-bot-api` (например, в ответе `getMe` для поля `photo.small_file_id`) вернул локальный путь типа `/var/lib/telegram-bot-api/photos/12345/file_0.jpg`, то для его скачивания используйте:
-        `[URL_туннеля]/file/photos/12345/file_0.jpg`
-        **Важно**: Часть `/var/lib/telegram-bot-api/` из пути отбрасывается, используется только относительный путь внутри этой директории.
+1.  **Корневой эндпоинт**: `https://[YOUR_SPACE_URL]/` - Предоставляет JSON-список доступных основных эндпоинтов.
+2.  **Прокси Telegram Bot API**:
+    *   Используйте `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>` вместо стандартного URL `api.telegram.org`.
+3.  **Инструменты**:
+    *   **Статистика**: `https://[YOUR_SPACE_URL]/stats`
+    *   **Операции с файлами**: Все начинаются с `https://[YOUR_SPACE_URL]/file/`. Примеры:
+        *   **Список файлов для вашего бота**: `.../file/list?token=12345:ABCDEF...` (Ответ включает размеры отдельных файлов и общий размер файлов этого бота).
+        *   **Получение информации о файле**: `.../file/12345:ABCDEF.../getFile?file_id=SOME_FILE_ID`
+        *   **Скачивание файла напрямую по его пути**: `https://[YOUR_SPACE_URL]/file/bot12345:ABCDEF.../photos/file_0.jpg`
+        *   **Удаление файла по пути**: `https://[YOUR_SPACE_URL]/file/deleteFile?file=bot12345:ABCDEF.../photos/file_0.jpg`
+        *   **Удаление файла по ID**: `https://[YOUR_SPACE_URL]/file/12345:ABCDEF.../deleteById?file_id=SOME_FILE_ID`
+    *   Gist, указанный `ENV_GIST_ID`, будет содержать обновленный JSON-файл (`hf_space_tg_tools_info.json`) с URL-адресами, специфичными для вашего экземпляра Space.
+
+**Важные замечания о путях к файлам (Русский):**
+*   Когда `telegram-bot-api` сохраняет файлы, он обычно использует подкаталог, названный в честь токена бота (например, `/var/lib/telegram-bot-api/bot12345:ABCDEF.../`).
+*   Для эндпоинтов, таких как прямое скачивание по пути (`/file/<filepath>`) или удаление по пути (`/file/deleteFile?file=<filepath>`), часть `<filepath>` должна включать эту структуру каталогов токена бота, например, `bot12345:ABCDEF.../photos/file_0.jpg`.
+
+---
+<br>
+
+## Telegram Bot API with Enhanced Tools and Proxy (English)
+
+This Space runs a local Telegram Bot API server and provides an enhanced Node.js Express application, accessible via your Space URL, offering:
+
+1.  **Proxied Telegram Bot API**: Access your local Telegram Bot API via `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>`.
+2.  **File Statistics**: Get count and total size of files in the Telegram Bot API data directory via `https://[YOUR_SPACE_URL]/stats`.
+3.  **Advanced File Operations (via `/file/` prefix)**:
+    *   **List Files**: `.../file/list?token=<BOT_TOKEN>` - List all files for a specific bot, including individual file sizes and the total size of listed files.
+    *   **Get File Info & Links**: `.../file/<BOT_TOKEN>/getFile?file_id=<FILE_ID>` - Returns Telegram's `getFile` response, augmented with direct download links (by path, by ID, and an encrypted version).
+    *   **Download by ID**: `.../file/<BOT_TOKEN>/downloadFile?file_id=<FILE_ID>` - Directly downloads the file.
+    *   **Download by Path**: `.../file/<BOT_TOKEN_AS_DIR>/<PATH_TO_FILE_INSIDE_BOT_DIR>` - Downloads if you know the exact relative path (e.g., `.../file/bot123:abc/photos/file_0.jpg`).
+    *   **Encrypted Download**: `.../file/downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>` - Downloads using a payload from the `getFile` endpoint (hides bot token and file ID from the direct URL).
+    *   **Delete File by Path**: `.../file/deleteFile?file=<BOT_TOKEN_AS_DIR>/<PATH_TO_FILE_INSIDE_BOT_DIR>` - Deletes a file from the cache using its direct path.
+    *   **Delete File by ID**: `.../file/<BOT_TOKEN>/deleteById?file_id=<FILE_ID>` - Deletes a file from the cache using its bot token and file ID (internally calls `getFile` to find the path).
+4.  **Cache Cleanup (TTL)**: Automatic deletion of old files from the Telegram Bot API cache.
+5.  **Aggregated Gist Update**: Information about this Space (including tool URLs) is saved to a specified GitHub Gist, aggregating info if multiple spaces point to the same Gist file.
+
+### Necessary Secrets (English)
+
+Add the following secrets in your Space settings (`Settings -> Secrets`):
+
+*   `TELEGRAM_API_ID`: Your API ID from Telegram.
+*   `TELEGRAM_API_HASH`: Your API Hash from Telegram.
+*   `GITHUB_USERNAME`: Your GitHub login (for updating the Gist).
+*   `GITHUB_TOKEN`: Your GitHub Personal Access Token with `gist` scope.
+*   `ENV_GIST_ID`: ID of your GitHub Gist where Space info will be saved/updated. Create an empty Gist and copy its ID from the URL.
+*   `LINK_ENCRYPTION_KEY`: A secret passphrase (e.g., a long random string) used for generating encrypted download links. If not set, encrypted links will not be generated.
+
+### Environment Variables (can be overridden via secrets) (English)
+
+*   `INTERNAL_TELEGRAM_API_PORT`: Port for the internal `telegram-bot-api` process (default: `8081`). The Node.js app proxies to this.
+*   `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. Older files are auto-deleted. Set to `-1` to disable (default: `-1`).
+*   `PROXY_TELEGRAM_PATH_PREFIX`: URL prefix for proxying Telegram API calls (default: `/tg`).
+
+### How to Use (English)
+
+1.  **Root Endpoint**: `https://[YOUR_SPACE_URL]/` - Provides a JSON list of available main endpoints.
+2.  **Telegram Bot API Proxy**:
+    *   Use `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>` instead of the standard `api.telegram.org` URL.
+3.  **Tools**:
+    *   **Statistics**: `https://[YOUR_SPACE_URL]/stats`
+    *   **File Operations**: All start with `https://[YOUR_SPACE_URL]/file/`. Examples:
+        *   **List files for your bot**: `.../file/list?token=12345:ABCDEF...` (Response includes individual file sizes and total size for this bot's files).
+        *   **Get info for a file**: `.../file/12345:ABCDEF.../getFile?file_id=SOME_FILE_ID`
+        *   **Download a file directly using its path**: `https://[YOUR_SPACE_URL]/file/bot12345:ABCDEF.../photos/file_0.jpg`
+        *   **Delete a file by path**: `https://[YOUR_SPACE_URL]/file/deleteFile?file=bot12345:ABCDEF.../photos/file_0.jpg`
+        *   **Delete a file by ID**: `https://[YOUR_SPACE_URL]/file/12345:ABCDEF.../deleteById?file_id=SOME_FILE_ID`
+    *   The Gist specified by `ENV_GIST_ID` will contain an updated JSON file (`hf_space_tg_tools_info.json`) with URLs specific to your Space instance.
+
+**Important Notes on File Paths (English):**
+*   When `telegram-bot-api` saves files, it typically uses a subdirectory named after the bot token (e.g., `/var/lib/telegram-bot-api/bot12345:ABCDEF.../`).
+*   For endpoints like direct download by path (`/file/<filepath>`) or delete by path (`/file/deleteFile?file=<filepath>`), the `<filepath>` part must include this bot token directory structure, e.g., `bot12345:ABCDEF.../photos/file_0.jpg`.