<?php

declare(strict_types=1);

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

namespace KTXF\Documents\Provider;

use KTXF\Documents\Service\ServiceBaseInterface;
use KTXF\Documents\Service\ServiceMutableInterface;

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

    public const CAPABILITY_SERVICE_TEST = 'ServiceTest';

    /**
     * Test a service connection
     *
     * Tests connectivity, authentication, and capabilities of a service
     *
     * @since 2025.05.01
     *
     * @param ServiceBaseInterface|ServiceMutableInterface $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)
     *
     * @return array Test results in the format:
     * [
     *   'disposition' => 'Success' | 'Failure' | 'Warning',
     *   'message' => 'Connection successful' | 'Error message',
     * ]
     */
    public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array;

}