<?php
/**
 * FinoviaPay Telegram Bot - Virtual Card Receipt Upload Flow
 * File: bot_virtual_card_receipts.php
 *
 * Integration in bot.php, after $message/$callback/$chat_id are prepared and before other generic routes:
 *
 * if (
 *     strpos((string)($callbackData ?? ''), 'vcard_receipts_') === 0 ||
 *     botVcrHasActiveFlow($pdo, (string)$chat_id)
 * ) {
 *     require __DIR__ . '/bot_virtual_card_receipts.php';
 *     exit;
 * }
 *
 * Optional: after successful customer login / main menu display, call:
 * botVcrSendPendingActionNotice($pdo, $chat_id);
 */

if (!function_exists('botVcrLog')) {
    function botVcrLog(string $message): void
    {
        @file_put_contents(__DIR__ . '/bot_virtual_card_receipts.log', '[' . date('Y-m-d H:i:s') . '] ' . $message . PHP_EOL, FILE_APPEND);
    }
}

if (!function_exists('botVcrSendMessage')) {
    function botVcrSendMessage($chatId, string $text, ?array $replyMarkup = null): void
    {
        if (function_exists('sendMessage')) {
            sendMessage($chatId, $text, $replyMarkup);
            return;
        }

        global $token;
        if (empty($token)) {
            botVcrLog('Telegram token missing. Message not sent.');
            return;
        }

        $payload = [
            'chat_id' => $chatId,
            'text' => $text,
            'parse_mode' => 'HTML'
        ];
        if ($replyMarkup) {
            $payload['reply_markup'] = json_encode($replyMarkup, JSON_UNESCAPED_UNICODE);
        }

        $ch = curl_init("https://api.telegram.org/bot{$token}/sendMessage");
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $payload,
            CURLOPT_CONNECTTIMEOUT => 15,
            CURLOPT_TIMEOUT => 25,
            CURLOPT_SSL_VERIFYPEER => false,
            CURLOPT_SSL_VERIFYHOST => false,
        ]);
        $res = curl_exec($ch);
        if ($res === false) botVcrLog('sendMessage curl error: ' . curl_error($ch));
        curl_close($ch);
    }
}

if (!function_exists('botVcrAnswerCallback')) {
    function botVcrAnswerCallback(?string $callbackId, string $text = ''): void
    {
        if (!$callbackId) return;
        if (function_exists('answerCallbackQuery')) {
            answerCallbackQuery($callbackId, $text);
            return;
        }
        global $token;
        if (empty($token)) return;
        $ch = curl_init("https://api.telegram.org/bot{$token}/answerCallbackQuery");
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => ['callback_query_id' => $callbackId, 'text' => $text],
            CURLOPT_CONNECTTIMEOUT => 10,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_SSL_VERIFYPEER => false,
            CURLOPT_SSL_VERIFYHOST => false,
        ]);
        curl_exec($ch);
        curl_close($ch);
    }
}

if (!function_exists('botVcrHasActiveFlow')) {
    function botVcrHasActiveFlow(PDO $pdo, string $chatId): bool
    {
        try {
            $stmt = $pdo->prepare("SELECT COUNT(*) FROM bot_virtual_card_receipt_flow_state WHERE customer_telegram_id = ? AND flow_step IN ('awaiting_receipt_upload','review_item')");
            $stmt->execute([$chatId]);
            return (int)$stmt->fetchColumn() > 0;
        } catch (Throwable $e) {
            return false;
        }
    }
}

if (!function_exists('botVcrGetPendingRequest')) {
    function botVcrGetPendingRequest(PDO $pdo, $chatId, ?int $requestId = null): ?array
    {
        $sql = "SELECT * FROM bot_virtual_card_receipt_requests
                WHERE customer_telegram_id = :chat_id
                  AND status IN ('pending_customer_upload','partially_uploaded','reupload_required')";
        $params = [':chat_id' => $chatId];
        if ($requestId !== null && $requestId > 0) {
            $sql .= " AND id = :request_id";
            $params[':request_id'] = $requestId;
        }
        $sql .= " ORDER BY id DESC LIMIT 1";
        $stmt = $pdo->prepare($sql);
        $stmt->execute($params);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        return $row ?: null;
    }
}

if (!function_exists('botVcrGetNextItem')) {
    function botVcrGetNextItem(PDO $pdo, int $requestId): ?array
    {
        $stmt = $pdo->prepare("SELECT * FROM bot_virtual_card_receipt_items
                               WHERE request_id = ?
                                 AND upload_status IN ('pending_upload','reupload_required','rejected')
                               ORDER BY item_number ASC, id ASC LIMIT 1");
        $stmt->execute([$requestId]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        return $row ?: null;
    }
}

if (!function_exists('botVcrUpsertFlow')) {
    function botVcrUpsertFlow(PDO $pdo, $chatId, int $requestId, ?int $itemId, string $step): void
    {
        $stmt = $pdo->prepare("INSERT INTO bot_virtual_card_receipt_flow_state
            (customer_telegram_id, request_id, current_item_id, flow_step, created_at, updated_at)
            VALUES (:chat_id, :request_id, :item_id, :step, NOW(), NOW())
            ON DUPLICATE KEY UPDATE request_id = VALUES(request_id), current_item_id = VALUES(current_item_id), flow_step = VALUES(flow_step), updated_at = NOW()");
        $stmt->execute([
            ':chat_id' => $chatId,
            ':request_id' => $requestId,
            ':item_id' => $itemId,
            ':step' => $step,
        ]);
    }
}

if (!function_exists('botVcrClearFlow')) {
    function botVcrClearFlow(PDO $pdo, $chatId): void
    {
        $stmt = $pdo->prepare("DELETE FROM bot_virtual_card_receipt_flow_state WHERE customer_telegram_id = ?");
        $stmt->execute([$chatId]);
    }
}

if (!function_exists('botVcrFormatItemPrompt')) {
    function botVcrFormatItemPrompt(array $request, array $item): string
    {
        $title = htmlspecialchars((string)($item['item_title'] ?? 'Required Receipt'), ENT_QUOTES, 'UTF-8');
        $merchant = htmlspecialchars((string)($item['merchant_name'] ?? 'Not specified'), ENT_QUOTES, 'UTF-8');
        $date = htmlspecialchars((string)($item['transaction_date'] ?? 'Not specified'), ENT_QUOTES, 'UTF-8');
        $amount = trim((string)($item['amount'] ?? ''));
        $currency = htmlspecialchars((string)($item['currency'] ?? 'EUR'), ENT_QUOTES, 'UTF-8');
        $amountLine = $amount !== '' ? htmlspecialchars($currency . ' ' . $amount, ENT_QUOTES, 'UTF-8') : 'Not specified';
        $d1 = trim((string)($item['description_1'] ?? ''));
        $d2 = trim((string)($item['description_2'] ?? ''));
        $instruction = trim((string)($item['upload_instruction'] ?? 'Please upload a clear image or PDF of the POS receipt for this transaction.'));
        $num = (int)($item['item_number'] ?? 1);
        $total = (int)($request['total_receipts_required'] ?? 0);
        $ref = htmlspecialchars((string)($request['request_reference'] ?? ''), ENT_QUOTES, 'UTF-8');

        $msg = "🧾 <b>Receipt {$num}" . ($total > 0 ? " of {$total}" : '') . "</b>\n\n";
        $msg .= "<b>Virtual Card Receipt Verification</b>\n";
        $msg .= "🆔 <b>Reference ID:</b> {$ref}\n\n";
        $msg .= "<b>Title:</b> {$title}\n";
        $msg .= "<b>Transaction Date:</b> {$date}\n";
        $msg .= "<b>Transaction Amount:</b> {$amountLine}\n";
        $msg .= "<b>Merchant Name:</b> {$merchant}\n\n";
        if ($d1 !== '') $msg .= "<b>Description 1:</b> " . htmlspecialchars($d1, ENT_QUOTES, 'UTF-8') . "\n";
        if ($d2 !== '') $msg .= "<b>Description 2:</b> " . htmlspecialchars($d2, ENT_QUOTES, 'UTF-8') . "\n";
        $msg .= "\n📌 <b>Instruction:</b>\n" . htmlspecialchars($instruction, ENT_QUOTES, 'UTF-8') . "\n\n";
        $msg .= "Please upload this receipt now as a clear photo, image document, or PDF file. Ensure date, amount, and merchant name are fully visible.";
        return $msg;
    }
}

if (!function_exists('botVcrSendNextPrompt')) {
    function botVcrSendNextPrompt(PDO $pdo, $chatId, int $requestId): void
    {
        $request = botVcrGetPendingRequest($pdo, $chatId, $requestId);
        if (!$request) {
            botVcrClearFlow($pdo, $chatId);
            botVcrSendMessage($chatId, "✅ No pending virtual card receipt request was found for your profile.");
            return;
        }

        $item = botVcrGetNextItem($pdo, $requestId);
        if (!$item) {
            $pdo->prepare("UPDATE bot_virtual_card_receipt_requests SET status = 'submitted_for_review', submitted_at = NOW(), updated_at = NOW() WHERE id = ?")
                ->execute([$requestId]);
            botVcrClearFlow($pdo, $chatId);
            $ref = htmlspecialchars((string)($request['request_reference'] ?? ''), ENT_QUOTES, 'UTF-8');
            botVcrSendMessage($chatId,
                "✅ <b>Submission Completed Successfully</b>\n\n" .
                "This is an automated secure banking notification from FinoviaPay.\n\n" .
                "Dear Valued Customer,\n\n" .
                "We confirm that all requested transaction receipts have been successfully submitted and securely recorded in our system.\n\n" .
                "🆔 <b>Submission Reference ID:</b>\n" . $ref . "\n\n" .
                "Your documents are now under review by our Card Control Department. You will be notified once the verification process has been completed.\n\n" .
                "⏳ <b>Estimated Review Time:</b>\n24 to 48 hours\n\n" .
                "📌 <b>Important Notice:</b>\nPlease retain this reference ID for future communication regarding this request.\n\n" .
                "We appreciate your cooperation and patience in maintaining a secure banking environment.\n\n" .
                "Kind regards,\nCard Control Department\nFinoviaPay"
            );
            return;
        }

        botVcrUpsertFlow($pdo, $chatId, $requestId, (int)$item['id'], 'awaiting_receipt_upload');
        botVcrSendMessage($chatId, botVcrFormatItemPrompt($request, $item), [
            'inline_keyboard' => [
                [['text' => '❌ Cancel Upload', 'callback_data' => 'vcard_receipts_cancel']]
            ]
        ]);
    }
}

if (!function_exists('botVcrSendPendingActionNotice')) {
    function botVcrSendPendingActionNotice(PDO $pdo, $chatId): void
    {
        $request = botVcrGetPendingRequest($pdo, $chatId);
        if (!$request) return;
        $title = htmlspecialchars((string)($request['request_title'] ?? 'Virtual Card Receipt Verification Required'), ENT_QUOTES, 'UTF-8');
        $total = (int)($request['total_receipts_required'] ?? 0);
        $uploaded = (int)($request['total_receipts_uploaded'] ?? 0);
        $ref = htmlspecialchars((string)($request['request_reference'] ?? ''), ENT_QUOTES, 'UTF-8');

        $msg = "⚠️ <b>Action Required</b>\n\n";
        $msg .= "This is an automated secure banking notification from FinoviaPay.\n\n";
        $msg .= "<b>{$title}</b>\n\n";
        $msg .= "Dear Valued Customer,\n\n";
        $msg .= "Your virtual card receipt verification is pending and requires your immediate attention.\n\n";
        $msg .= "🆔 <b>Reference ID:</b> {$ref}\n";
        $msg .= "📊 <b>Upload Progress:</b> {$uploaded} / {$total} receipts submitted\n\n";
        $msg .= "Please click below to securely upload the requested receipt(s) step by step.";

        botVcrSendMessage($chatId, $msg, [
            'inline_keyboard' => [
                [['text' => '📤 Upload Required Receipts', 'callback_data' => 'vcard_receipts_open_' . (int)$request['id']]]
            ]
        ]);
    }
}

if (!function_exists('botVcrExtractUploadedFile')) {
    function botVcrExtractUploadedFile(array $message): ?array
    {
        if (!empty($message['photo']) && is_array($message['photo'])) {
            $photo = end($message['photo']);
            return [
                'telegram_file_id' => (string)($photo['file_id'] ?? ''),
                'telegram_file_unique_id' => (string)($photo['file_unique_id'] ?? ''),
                'file_type' => 'photo',
                'original_file_name' => null,
                'mime_type' => 'image/jpeg',
                'file_size' => $photo['file_size'] ?? null,
                'caption' => (string)($message['caption'] ?? ''),
            ];
        }
        if (!empty($message['document']) && is_array($message['document'])) {
            $doc = $message['document'];
            $mime = strtolower((string)($doc['mime_type'] ?? ''));
            $fileType = 'document';
            if (strpos($mime, 'image/') === 0) $fileType = 'image';
            if ($mime === 'application/pdf') $fileType = 'pdf';
            return [
                'telegram_file_id' => (string)($doc['file_id'] ?? ''),
                'telegram_file_unique_id' => (string)($doc['file_unique_id'] ?? ''),
                'file_type' => $fileType,
                'original_file_name' => (string)($doc['file_name'] ?? ''),
                'mime_type' => (string)($doc['mime_type'] ?? ''),
                'file_size' => $doc['file_size'] ?? null,
                'caption' => (string)($message['caption'] ?? ''),
            ];
        }
        return null;
    }
}

if (!function_exists('botVcrHandleUpload')) {
    function botVcrHandleUpload(PDO $pdo, $chatId, array $message): bool
    {
        $stmt = $pdo->prepare("SELECT * FROM bot_virtual_card_receipt_flow_state WHERE customer_telegram_id = ? LIMIT 1");
        $stmt->execute([$chatId]);
        $flow = $stmt->fetch(PDO::FETCH_ASSOC);
        if (!$flow || (string)$flow['flow_step'] !== 'awaiting_receipt_upload') return false;

        $file = botVcrExtractUploadedFile($message);
        if (!$file || $file['telegram_file_id'] === '') {
            botVcrSendMessage($chatId, "⚠️ Please upload a clear receipt photo, image document, or PDF file for the requested transaction.");
            return true;
        }

        $requestId = (int)$flow['request_id'];
        $itemId = (int)$flow['current_item_id'];

        $pdo->beginTransaction();
        try {
            $insert = $pdo->prepare("INSERT INTO bot_virtual_card_receipt_uploads
                (request_id, item_id, customer_telegram_id, telegram_file_id, telegram_file_unique_id, file_type, original_file_name, mime_type, file_size, uploaded_caption, status, uploaded_at)
                VALUES (:request_id, :item_id, :chat_id, :file_id, :file_unique_id, :file_type, :file_name, :mime_type, :file_size, :caption, 'uploaded', NOW())");
            $insert->execute([
                ':request_id' => $requestId,
                ':item_id' => $itemId,
                ':chat_id' => $chatId,
                ':file_id' => $file['telegram_file_id'],
                ':file_unique_id' => $file['telegram_file_unique_id'],
                ':file_type' => $file['file_type'],
                ':file_name' => $file['original_file_name'],
                ':mime_type' => $file['mime_type'],
                ':file_size' => $file['file_size'],
                ':caption' => $file['caption'],
            ]);

            $pdo->prepare("UPDATE bot_virtual_card_receipt_items SET upload_status = 'uploaded', updated_at = NOW() WHERE id = ?")
                ->execute([$itemId]);

            $countStmt = $pdo->prepare("SELECT COUNT(*) FROM bot_virtual_card_receipt_items WHERE request_id = ? AND upload_status IN ('uploaded','approved')");
            $countStmt->execute([$requestId]);
            $uploadedCount = (int)$countStmt->fetchColumn();

            $totalStmt = $pdo->prepare("SELECT COUNT(*) FROM bot_virtual_card_receipt_items WHERE request_id = ?");
            $totalStmt->execute([$requestId]);
            $totalCount = (int)$totalStmt->fetchColumn();

            $newStatus = ($uploadedCount >= $totalCount && $totalCount > 0) ? 'submitted_for_review' : 'partially_uploaded';
            $pdo->prepare("UPDATE bot_virtual_card_receipt_requests
                           SET total_receipts_uploaded = ?, status = ?, submitted_at = IF(? = 'submitted_for_review', NOW(), submitted_at), updated_at = NOW()
                           WHERE id = ?")
                ->execute([$uploadedCount, $newStatus, $newStatus, $requestId]);

            $pdo->commit();
        } catch (Throwable $e) {
            $pdo->rollBack();
            botVcrLog('Upload save error: ' . $e->getMessage());
            botVcrSendMessage($chatId, "❌ We could not save this receipt at the moment. Please try again.");
            return true;
        }

        if ($newStatus === 'submitted_for_review') {
            botVcrClearFlow($pdo, $chatId);

            $refStmt = $pdo->prepare("SELECT request_reference FROM bot_virtual_card_receipt_requests WHERE id = ? LIMIT 1");
            $refStmt->execute([$requestId]);
            $finalRef = htmlspecialchars((string)$refStmt->fetchColumn(), ENT_QUOTES, 'UTF-8');

            botVcrSendMessage($chatId,
                "✅ <b>Submission Completed Successfully</b>\n\n" .
                "This is an automated secure banking notification from FinoviaPay.\n\n" .
                "Dear Valued Customer,\n\n" .
                "We confirm that all requested transaction receipts have been successfully submitted and securely recorded in our system.\n\n" .
                "🆔 <b>Submission Reference ID:</b>\n" . $finalRef . "\n\n" .
                "Your documents are now under review by our Card Control Department. You will be notified once the verification process has been completed.\n\n" .
                "⏳ <b>Estimated Review Time:</b>\n24 to 48 hours\n\n" .
                "📌 <b>Important Notice:</b>\nPlease retain this reference ID for future communication regarding this request.\n\n" .
                "We appreciate your cooperation and patience in maintaining a secure banking environment.\n\n" .
                "Kind regards,\nCard Control Department\nFinoviaPay"
            );
            return true;
        }

        botVcrSendMessage($chatId, "✅ <b>Receipt Uploaded Successfully</b>\n\nYour document has been received and securely recorded.\n\nPlease proceed with the next required receipt.");
        botVcrSendNextPrompt($pdo, $chatId, $requestId);
        return true;
    }
}


if (!function_exists('botVcrOpenCustomerMenu')) {
    function botVcrOpenCustomerMenu(PDO $pdo, $chatId): void
    {
        try {
            $stmt = $pdo->prepare("SELECT * FROM bot_virtual_card_receipt_requests
                WHERE customer_telegram_id = :chat_id
                ORDER BY id DESC
                LIMIT 5");
            $stmt->execute([':chat_id' => $chatId]);
            $requests = $stmt->fetchAll(PDO::FETCH_ASSOC);
        } catch (Throwable $e) {
            botVcrLog('Customer menu fetch error: ' . $e->getMessage());
            botVcrSendMessage($chatId, "❌ Receipt request menu is temporarily unavailable. Please try again shortly.");
            return;
        }

        $msg = "🧾 <b>Virtual Card Receipt Requests</b>\n\n";
        $msg .= "This is a secure FinoviaPay customer action menu.\n\n";
        $msg .= "Dear Valued Customer,\n\n";
        $msg .= "If you missed or ignored a previous receipt verification notification, you can use this menu to review your latest virtual card receipt request and continue the secure upload process.\n\n";

        $buttons = [];
        $hasPending = false;

        if (!$requests) {
            $msg .= "✅ <b>No Pending Action</b>\nThere is currently no virtual card receipt request pending for your profile.\n\n";
            $msg .= "If a new receipt verification is required in the future, it will appear here automatically.";
        } else {
            $msg .= "📌 <b>Your Latest Receipt Requests</b>\n";
            foreach ($requests as $index => $request) {
                $status = (string)($request['status'] ?? 'pending_customer_upload');
                $ref = htmlspecialchars((string)($request['request_reference'] ?? ''), ENT_QUOTES, 'UTF-8');
                $title = htmlspecialchars((string)($request['request_title'] ?? 'Virtual Card Receipt Verification'), ENT_QUOTES, 'UTF-8');
                $total = (int)($request['total_receipts_required'] ?? 0);
                $uploaded = (int)($request['total_receipts_uploaded'] ?? 0);

                $labelMap = [
                    'pending_customer_upload' => 'Pending Upload',
                    'partially_uploaded' => 'Upload In Progress',
                    'reupload_required' => 'Re-upload Required',
                    'submitted_for_review' => 'Submitted / Under Review',
                    'approved' => 'Approved',
                    'rejected' => 'Rejected',
                    'cancelled' => 'Cancelled',
                ];
                $label = $labelMap[$status] ?? ucwords(str_replace('_', ' ', $status));

                $msg .= "\n" . ($index + 1) . ". <b>{$title}</b>\n";
                $msg .= "🆔 <b>Reference ID:</b> {$ref}\n";
                $msg .= "📊 <b>Progress:</b> {$uploaded} / {$total}\n";
                $msg .= "📍 <b>Status:</b> " . htmlspecialchars($label, ENT_QUOTES, 'UTF-8') . "\n";

                if (in_array($status, ['pending_customer_upload', 'partially_uploaded', 'reupload_required'], true)) {
                    $hasPending = true;
                    $buttons[] = [[
                        'text' => '📤 Upload Receipts - ' . ($ref !== '' ? $ref : ('Request #' . (int)$request['id'])),
                        'callback_data' => 'vcard_receipts_open_' . (int)$request['id']
                    ]];
                }
            }

            if (!$hasPending) {
                $msg .= "\n✅ There is no receipt upload action pending at this time.";
            } else {
                $msg .= "\nPlease select the request below to continue uploading the required receipt(s).";
            }
        }

        $buttons[] = [['text' => '🔄 Refresh Receipt Menu', 'callback_data' => 'vcard_receipts_menu']];
        $buttons[] = [['text' => '↩️ Back to Main Menu', 'callback_data' => 'main_menu']];

        botVcrSendMessage($chatId, $msg, ['inline_keyboard' => $buttons]);
    }
}

if (!function_exists('botVirtualCardReceiptsHandle')) {
    function botVirtualCardReceiptsHandle(PDO $pdo, $chatId, ?array $message, ?string $callbackData, ?string $callbackId = null): bool
    {
        if ($callbackData && strpos($callbackData, 'vcard_receipts_') === 0) {
            botVcrAnswerCallback($callbackId);

            if ($callbackData === 'vcard_receipts_menu') {
                botVcrOpenCustomerMenu($pdo, $chatId);
                return true;
            }

            if ($callbackData === 'vcard_receipts_cancel') {
                botVcrClearFlow($pdo, $chatId);
                botVcrSendMessage($chatId, "Upload session cancelled. You can reopen the pending receipt request anytime from the action-required notice.");
                return true;
            }

            if (preg_match('/^vcard_receipts_open_(\d+)$/', $callbackData, $m)) {
                $requestId = (int)$m[1];
                $request = botVcrGetPendingRequest($pdo, $chatId, $requestId);
                if (!$request) {
                    botVcrClearFlow($pdo, $chatId);
                    botVcrSendMessage($chatId, "✅ This receipt request is no longer pending for upload.");
                    return true;
                }

                $title = htmlspecialchars((string)$request['request_title'], ENT_QUOTES, 'UTF-8');
                $msg = "📤 <b>Virtual Card Receipt Upload</b>\n\n";
                $msg .= "This is an automated secure banking notification from FinoviaPay.\n\n";
                $msg .= "Dear Valued Customer,\n\n";
                $msg .= "You are now required to upload the requested transaction receipts one by one.\n\n";
                $msg .= "<b>{$title}</b>\n";
                $msg .= "🆔 <b>Reference ID:</b> " . htmlspecialchars((string)$request['request_reference'], ENT_QUOTES, 'UTF-8') . "\n\n";
                $msg .= "📌 <b>Important Instructions:</b>\n• Ensure the receipt is clear and fully visible\n• Do not crop or edit the document\n• The transaction details must match the provided information\n• Accepted formats: Image / PDF / Document\n\n";
                $msg .= "Let us begin with the first required receipt.";
                botVcrSendMessage($chatId, $msg);
                botVcrSendNextPrompt($pdo, $chatId, $requestId);
                return true;
            }

            if ($callbackData === 'vcard_receipts_status') {
                botVcrSendPendingActionNotice($pdo, $chatId);
                return true;
            }
        }

        if ($message && botVcrHasActiveFlow($pdo, (string)$chatId)) {
            return botVcrHandleUpload($pdo, $chatId, $message);
        }

        return false;
    }
}


if (!function_exists('botOpenVirtualCardReceiptMenu')) {
    function botOpenVirtualCardReceiptMenu(PDO $pdo, $chatId): void
    {
        botVcrOpenCustomerMenu($pdo, $chatId);
    }
}

if (!function_exists('botCheckPendingVirtualCardReceipts')) {
    function botCheckPendingVirtualCardReceipts(PDO $pdo, $chatId): void
    {
        botVcrSendPendingActionNotice($pdo, $chatId);
    }
}

if (!function_exists('botHandleVirtualCardReceiptUpload')) {
    function botHandleVirtualCardReceiptUpload(PDO $pdo, $chatId, array $message): bool
    {
        return botVcrHandleUpload($pdo, $chatId, $message);
    }
}

if (!function_exists('botStartVirtualCardReceiptFlow')) {
    function botStartVirtualCardReceiptFlow(PDO $pdo, $chatId, string $callbackData): bool
    {
        return botVirtualCardReceiptsHandle($pdo, $chatId, null, $callbackData, null);
    }
}

// Auto-run when this file is required from bot.php routing.
try {
    if (isset($pdo, $chat_id)) {
        $handled = botVirtualCardReceiptsHandle(
            $pdo,
            $chat_id,
            $message ?? null,
            ($callbackData ?? $callback_data ?? null),
            ($callbackId ?? $callback_query_id ?? null)
        );
        if ($handled) {
            return;
        }

        // If module was routed because active flow exists, guide customer again.
        if (botVcrHasActiveFlow($pdo, (string)$chat_id)) {
            botVcrSendMessage($chat_id, "⚠️ Please upload the requested receipt file to continue.");
            return;
        }
    }
} catch (Throwable $e) {
    botVcrLog('Runtime error: ' . $e->getMessage());
    if (isset($chat_id)) {
        botVcrSendMessage($chat_id, "❌ Receipt upload service is temporarily unavailable. Please try again shortly.");
    }
    return;
}