<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Provider;

use KTXF\Mail\Service\ServiceBaseInterface;

/**
 * Mail Provider Service Test Interface
 * 
 * Optional interface for mail 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',
     *   'details' => [
     *     'connected' => bool,               // Socket/HTTP connection succeeded
     *     'authenticated' => bool,            // Authentication succeeded
     *     'capabilities' => ['IMAP4rev1', ...],  // Server capabilities (if applicable)
     *     'serverInfo' => 'Server version/banner',
     *     'latency' => 123,                   // Connection time in milliseconds
     *     'protocols' => [
     *       'inbound' => [
     *         'connected' => bool,
     *         'authenticated' => bool,
     *         'error' => 'error message if failed'
     *       ],
     *       'outbound' => [                   // For split-socket (IMAP+SMTP)
     *         'connected' => bool,
     *         'authenticated' => bool,
     *         'error' => 'error message if failed'
     *       ]
     *     ],
     *     'errors' => ['Error 1', 'Error 2'],  // List of errors encountered
     *   ]
     * ]
     */
    public function serviceTest(ServiceBaseInterface $service, array $options = []): array;

}