<?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;

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

    public const JSON_TYPE = 'mail:provider';

    /**
     * Reserved user identifier for system-owned mail services
     *
     * Services stored under this user id belong to the tenant itself rather
     * than any real user (e.g. accounts used to deliver system-generated
     * messages such as verification codes and password resets).
     *
     * @since 2026.07.01
     */
    public const USER_SYSTEM = 'system';
    
    /**
     * 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;

}