<?php

declare(strict_types=1);

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

namespace KTXF\People\Provider;

use KTXF\Mail\Service\ServiceBaseInterface;

/**
 * Provider Service Test Interface
 * 
 * Optional interface for providers that support testing service connections
 * 
 * @since 2025.05.01
 */
interface ProviderServiceTestInterface {

    /**
     * Test a service connection
     * 
     * Tests connectivity, authentication, and capabilities of a service
     * 
     * @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;

}