<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Chrono\Provider;

use KTXF\Mail\Service\ServiceBaseInterface;

/**
 * Chrono Provider Service Test Interface
 * 
 * Optional interface for chrono providers that support testing service connections.
 * Providers implementing this interface can validate connection parameters,
 * test authentication, and verify service availability before creating a
 * persistent service configuration.
 * 
 * Supports two testing modes:
 * 1. Testing an existing service (validate current configuration)
 * 2. Testing a fresh configuration (validate before saving)
 * 
 * @since 2025.05.01
 */
interface ProviderServiceTestInterface extends ProviderBaseInterface {

    /**
     * Test a service connection
     * 
     * Tests connectivity, authentication, and capabilities of a service.
     * 
     * For new services: use serviceFresh() to create a service, configure it with
     * setters, then pass it to this method for testing before persisting.
     * 
     * For existing services: fetch the service and pass it directly.
     * 
     * @since 2025.05.01
     * 
     * @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
     * @param array $options Provider-specific test options:
     *   - 'timeout' => int (seconds, default: 10)
     *   - 'verify_ssl' => bool (default: true)
     *   - 'test_send' => bool (attempt test send if capable, default: false)
     *   - 'test_receive' => bool (attempt mailbox access if capable, default: true)
     * 
     * @return array Test results in the format:
     * [
     *   'success' => bool,
     *   'message' => 'Connection successful' | 'Error message'
     * ]
     */
    public function serviceTest(ServiceBaseInterface $service, array $options = []): array;

}