<?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 JsonSerializable;
use KTXF\Mail\Selector\ServiceSelector;
use KTXF\Mail\Service\IServiceBase;

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

    public const CAPABILITY_SERVICE_LIST = 'ServiceList';
    public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
    public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
    public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';

    public const JSON_TYPE = 'mail.provider';
    public const JSON_PROPERTY_TYPE = '@type';
    public const JSON_PROPERTY_ID = 'id';
    public const JSON_PROPERTY_LABEL = 'label';
    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';

    /**
     * Confirms if a specific capability is supported
     *
     * @since 2025.05.01
     *
     * @param string $value Required capability e.g. 'ServiceList'
     *
     * @return bool
     */
    public function capable(string $value): bool;

    /**
     * Lists all supported capabilities
     *
     * @since 2025.05.01
     *
     * @return array<string,bool>
     */
    public function capabilities(): array;

    /**
     * Gets the unique identifier for this provider
     *
     * @since 2025.05.01
     *
     * @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
     */
    public function id(): string;

    /**
     * Gets the localized human-friendly name of this provider
     *
     * @since 2025.05.01
     *
     * @return string Provider label (e.g., 'SMTP Mail Provider')
     */
    public function label(): string;

    /**
     * Lists services for a tenant, optionally filtered by user context
     * 
     * When userId is null, returns only System-scoped services.
     * When userId is provided, returns System-scoped services plus
     * User-scoped services owned by that user.
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId User identifier for context (null = system only)
     * @param ServiceSelector|null $selector Optional filter criteria
     *
     * @return array<string|int, IServiceBase>
     */
    public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;

    /**
     * Checks if specific services exist
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId User identifier for context
     * @param string|int ...$identifiers Service identifiers to check
     *
     * @return array<string|int, bool> Identifier => exists
     */
    public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;

    /**
     * Fetches a specific service by identifier
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId User identifier for context
     * @param string|int $identifier Service identifier
     *
     * @return IServiceBase|null
     */
    public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;

    /**
     * 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|null $userId User identifier for context
     * @param string $address Email address to find service for
     *
     * @return IServiceBase|null Service handling the address, or null
     */
    public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;

}