<?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;
use KTXF\Resource\Provider\ResourceProviderBaseInterface;

/**
 * Mail Provider Base Interface
 * 
 * Core interface for mail providers with context-aware service discovery.
 * 
 * @since 2025.05.01
 */
interface ProviderBaseInterface extends ResourceProviderBaseInterface{

    public const JSON_TYPE = 'mail.provider';
    
    /**
     * Finds a service that handles a specific email address
     * 
     * Searches within the appropriate scope based on userId context.
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string $userId User identifier
     * @param string $address Email address to find service for
     *
     * @return ServiceBaseInterface|null Service handling the address, or null
     */
    public function serviceFindByAddress(string $tenantId, string $userId, string $address): ?ServiceBaseInterface;

}