<?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\Resource\Provider\ResourceServiceLocationInterface;

/**
 * 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 {

    /**
     * Attempts to discover service configuration using provider-specific methods.
     * 
     * @since 2025.05.01
     * 
     * @param string $tenantId Tenant identifier
     * @param string $userId User identifier
     * @param string $identity Identity to discover configuration for (e.g., email address)
     * @param string|null $location Optional hostname to test directly (bypasses DNS lookup)
     * @param string|null $secret Optional password/token to validate discovered service
     * 
     * @return ResourceServiceLocationInterface|null Discovered location or null if not found
     */
    public function serviceDiscover(
        string $tenantId, 
        string $userId, 
        string $identity,
        ?string $location = null,
        ?string $secret = null
    ): ResourceServiceLocationInterface|null;

}