<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Provider;

/**
 * Mail Provider Autodiscovery Interface
 * 
 * Optional interface for mail providers that support automatic service discovery
 * from email addresses or domains. Providers implementing this interface can
 * discover mail service configurations using various methods specific to their
 * protocol or provider type.
 * 
 * Examples:
 * - IMAP/SMTP providers: Mozilla Autoconfig, DNS SRV, well-known URIs
 * - JMAP providers: Well-known JMAP endpoint discovery
 * - Provider-specific: Gmail, Outlook, etc. with known configurations
 * 
 * @since 2025.05.01
 */
interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {

    /**
     * Discover service configuration
     * 
     * Attempts to discover service configuration using provider-specific methods.
     * Each provider may use different discovery mechanisms:
     * - IMAP/SMTP: config database, DNS SRV, well-known URIs, common patterns
     * - JMAP: Well-known JMAP session discovery
     * - Provider-specific: Known configurations for popular providers
     * 
     * @since 2025.05.01
     * 
     * @param string $identity Identity to discover configuration for
     * @param array $options Provider-specific options (e.g., preferred protocols, timeout)
     * 
     * @return array Discovery results in the format:
     * [
     *   'domain' => 'example.com',
     *   'provider' => 'gmail|outlook|generic|etc',  // Optional detected provider
     *   'results' => [
     *     [
     *       'protocol' => 'imap|smtp|jmap|etc',
     *       'host' => 'imap.example.com',
     *       'port' => 993,
     *       'security' => 'ssl|tls|starttls|none',
     *       'authentication' => ['plain', 'login', 'oauth2'],  // Supported auth methods
     *       'confidence' => 'high|medium|low',
     *       'source' => 'mozilla|srv|wellknown|common|verified',  // Discovery method used
     *     ],
     *     // ... more protocol results
     *   ]
     * ]
     * 
     * Returns empty results array if no configuration could be discovered.
     */
    public function serviceDiscover(string $identity, array $options = []): array;

}