v1.0.0-alpha.5

👑 Tueen Telegram Bot SDK v1.0.0-alpha.5

Release v1.0.0-alpha.5 brings crucial reliability, authentication, and stability fixes for the high-level zero-config App mode and its Royal Web Dashboard (WebDashboard), eliminating request collision between dashboard form submissions and Telegram webhook updates.

---

🐛 Bug Fixes & Reliability Improvements

• Dashboard & Webhook Traffic Isolation (App::isDashboardRequest):

  • Fixed an issue where form submissions to the Web Dashboard (such as entering setup passwords or updating tokens) without an explicit query parameter were mistakenly routed to $bot->run() as incoming Telegram Webhook payloads, triggering Invalid JSON payload in webhook exceptions.
  • Added App::isDashboardRequest() to strictly isolate browser GET requests and dashboard management POST actions.

• Hardened Password Gate & Session Authentication:

  • Added explicit action="?action=login" and autocomplete="current-password" to the authentication gate form.
  • Replaced plaintext comparisons with timing-safe hash_equals().
  • Added clear error alerts on invalid password entry (⚠️ Invalid dashboard password. Please try again.) without breaking the UI.

• Post-Redirect-Get (PRG) & Flash Session Notices:

  • Implemented HTTP 303 PRG pattern for login, setup wizard, setting webhooks, and deleting webhooks.
  • Eliminates browser "Confirm Form Resubmission" popups when refreshing the dashboard while preserving notice and error messages across requests.

• 🔒 Dashboard Logout Feature:

  • Added a Logout button to the dashboard header and handled ?action=logout to cleanly destroy authentication sessions.

• Full .env & Proxy Integration:

  • Added support for SETUP_PASSWORD, TELEGRAM_SETUP_PASSWORD, and DASHBOARD_PASSWORD in .env.
  • The setup wizard now inherits configured proxy settings (TELEGRAM_PROXY, HTTPS_PROXY, HTTP_PROXY) and custom Telegram Bot API servers (TELEGRAM_API_SERVER) when validating tokens via getMe().

• Config Preservation & Optional Webhook URL:

  • saveConfig() now preserves existing custom options in config.php (such as custom middlewares, timeouts, or controllers).
  • Made the Webhook URL field optional in the setup wizard, enabling local development via Long-Polling without requiring a public HTTPS URL.

---

🧪 Quality Assurance & Test Coverage

• Added 17 new unit tests in WebDashboardTest.php covering password gate security, local vs. remote access, session authentication, logout, config preservation, and PRG redirects.
• 100% Passing Test Suite: 253 tests and 1,191 assertions passed with zero errors or warnings (OK (253 tests, 1191 assertions)).
• Fully validated with composer lint across all 776 source files.

---

📦 Installation / Update

composer require tueen/telegram:1.0.0-alpha.5

v1.0.0-alpha.4

👑 Tueen Telegram Bot SDK v1.0.0-alpha.4

Welcome to v1.0.0-alpha.4 of tueen/telegram — The Royal Telegram Bot SDK for Modern PHP.
This release introduces native architectural support for Single-Screen Interactive Flows and a dedicated replaceFlow() API, preventing redundant menu messages in chat history when switching or restarting flows.

---

🌟 What's New

1. #[SingleScreen] Attribute & InteractiveFlow Integration

In interactive Telegram bots using InteractiveFlow, users frequently invoke navigation commands (like /start, /tasks, /settings) while already viewing an active screen.

You can now annotate any InteractiveFlow with #[SingleScreen] to automatically terminate and clean up the previous active screen message:

use Tueen\Telegram\Flow\Attributes\SingleScreen;
use Tueen\Telegram\Flow\InteractiveFlow;
use Tueen\Telegram\Flow\Screen;

#[SingleScreen]
class DashboardFlow extends InteractiveFlow
{
    public function render(): Screen
    {
        return Screen::make("👑 *Main Dashboard*")
            ->inline(...);
    }
}

• Safe Message Deletion: Tueen safely issues deleteMessage(chatId, previousMessageId) before rendering the new screen. Any deletion rejections (e.g., user deleted the message manually or the 48-hour edit window expired) are silently suppressed.
• Granular Control: Supports #[SingleScreen(clearPrevious: false)] or overriding via protected property protected bool $clearPreviousScreen = true;.

---

2. Dedicated $bot->replaceFlow() API

In update and command controllers (e.g. #[OnCommand('start')]), you can now use $bot->replaceFlow() to terminate the existing session, delete its active screen message, and start a fresh flow atomically:

use Tueen\Telegram\Routing\Attributes\OnCommand;
use Tueen\Telegram\Telegram;

#[OnCommand('start')]
public function handleStart(Telegram $bot): void
{
    // Atomically finishes old flow, deletes its screen message, and starts DashboardFlow
    $bot->replaceFlow(DashboardFlow::class);
}

To preserve the previous message in chat history while resetting the session state, pass deletePreviousScreen: false:

$bot->replaceFlow(DashboardFlow::class, deletePreviousScreen: false);

Available on:

• Tueen\Telegram\Telegram::replaceFlow()
• Tueen\Telegram\Flow\FlowManager::replaceFlow()
• Tueen\Telegram\Flow\FlowSession::replaceFlow()

---

3. Call-Time Override in startFlow()

startFlow() now accepts an optional parameter ?bool $clearPreviousScreen = null:

// Force-clear previous screen even if the flow does not have #[SingleScreen]
$bot->startFlow(SettingsFlow::class, clearPreviousScreen: true);

// Preserve previous screen even if the flow is annotated with #[SingleScreen]
$bot->startFlow(DashboardFlow::class, clearPreviousScreen: false);

---

4. Zero Breaking Changes for Linear Flows

Standard textual Flow classes remain unaffected. Linear flows without #[SingleScreen] never issue unintended deleteMessage requests.

---

🧪 Quality & Test Suite

• 100% Test Pass Rate: 236 tests, 1,152 assertions passing cleanly.
• Syntax & Style Validation: 776 files validated with 0 syntax errors.
• LLM Context & Documentation Sync: Updated docs/guide/flow/interactive-screens.md, llms.txt, llms-full.txt, and offline agent skill package (tueen-telegram-bot-api-sdk.zip).

---

📦 Installation & Upgrade

composer require tueen/telegram:1.0.0-alpha.4

v1.0.0-alpha.3

Tueen Telegram Bot SDK v1.0.0-alpha.3

The Royal Telegram Bot SDK for Modern PHP — Release v1.0.0-alpha.3 brings essential running mode fixes and lifecycle safety improvements when starting long-polling in CLI mode.

---

🚀 What's New & Fixed

1. Direct Running Mode Configuration on Telegram Facade

• Implemented usePollingMode(...) and useWebhookMode(...) directly on Tueen\Telegram\Telegram alongside the existing useAutoMode(...).
• Resolves the issue where unknown method fallback (__call) inadvertently forwarded usePollingMode to Telegram Bot API endpoint (POST /bot<token>/usePollingMode), causing a 404 Not Found crash.

2. Auto Webhook Cleanup in CLI Polling

• In CliHandler::startPolling(...), the runner now respects the auto_delete_webhook and drop_pending_updates application configuration and clears any active webhook before starting polling. This prevents 409 Conflict errors from Telegram Bot API when transitioning from webhook to polling.

3. Test Coverage

• Added dedicated unit tests verifying $bot->usePollingMode(...) and $bot->useWebhookMode(...) fluent behavior and parameter mapping in RunningModesTest.

---

📦 Installation & Upgrade

composer require tueen/telegram:^1.0.0-alpha.3

Full Changelog: v1.0.0-alpha.2...v1.0.0-alpha.3

v1.0.0-alpha.2

🚀 What's New in v1.0.0-alpha.2

This release introduces flexible SSL verification configuration across HTTP transports (GuzzleHttpClient and CurlHttpClient), making it easier to work in environments with self-signed certificates, corporate proxies, or custom CA bundles.

---

✨ Features & Improvements

• SSL Verification Option (verify_ssl / verifySsl):
  • Added verifySsl configuration to Config and ConfigBuilder.
  • Supports both bool and string types:
    • false (default): Disables SSL certificate validation (useful for local development, corporate proxies, or restricted networks).
    • true: Enables standard SSL verification against system CA certificates.
    • string: Path to a custom CA bundle file (e.g. /path/to/cacert.pem).
• HTTP Transport Integration:
  • Guzzle: Configured via 'verify' => $config->verifySsl ?? false.
  • cURL: Sets CURLOPT_SSL_VERIFYPEER / CURLOPT_SSL_VERIFYHOST and applies CURLOPT_CAINFO when a CA bundle path is provided.
• Application Orchestrator Support:
  • Added verify_ssl key support in App configuration array and .env.
• Documentation & LLM Hub:
  • Updated API catalog cards in docs/guide/configuration.md.
  • Regenerated llms-full.txt and downloadable offline skill package (tueen-telegram-bot-api-sdk.zip).
• Test Suite:
  • Added dedicated unit tests in GuzzleHttpClientTest and updated TelegramClientTest / Php85FeaturesTest.

---

💻 Usage Example

use Tueen\Telegram\Telegram;

// 1. Disable SSL verification (default behavior)
$bot = Telegram::create('YOUR_BOT_TOKEN')
    ->withVerifySsl(false)
    ->client();

// 2. Enable standard SSL verification
$bot = Telegram::create('YOUR_BOT_TOKEN')
    ->withVerifySsl(true)
    ->client();

// 3. Use a custom CA bundle file
$bot = Telegram::create('YOUR_BOT_TOKEN')
    ->withVerifySsl('/etc/ssl/certs/custom-ca.pem')
    ->client();

Or via direct configuration / config.php:

return [
    'token' => 'YOUR_BOT_TOKEN',
    'verify_ssl' => false, // bool or path string
];

📦 Full Changelog

Full Changelog: https://github.com/tueen/telegram/compare/v1.0.0-alpha.1...v1.0.0-alpha.2

v1.0.0-alpha.1

docs(llms): add GitHub repository fallback reference across LLM skill…