<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Service;

use JsonSerializable;
use KTXF\Mail\Entity\IAddress;

/**
 * Mail Service Base Interface
 * 
 * Core interface for mail services providing identity, addressing, and capability information.
 * 
 * @since 2025.05.01
 */
interface IServiceBase extends JsonSerializable {

    public const JSON_TYPE = 'mail.service';
    public const JSON_PROPERTY_TYPE = '@type';
    public const JSON_PROPERTY_PROVIDER = 'provider';
    public const JSON_PROPERTY_ID = 'id';
    public const JSON_PROPERTY_LABEL = 'label';
    public const JSON_PROPERTY_SCOPE = 'scope';
    public const JSON_PROPERTY_OWNER = 'owner';
    public const JSON_PROPERTY_ENABLED = 'enabled';
    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
    public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
    public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';

    /**
     * Confirms if a specific capability is supported
     *
     * @since 2025.05.01
     *
     * @param string $value Required capability e.g. 'Send'
     *
     * @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 of the provider this service belongs to
     *
     * @since 2025.05.01
     * 
     * @return string
     */
    public function in(): string;

    /**
     * Gets the unique identifier for this service
     *
     * @since 2025.05.01
     * 
     * @return string|int
     */
    public function id(): string|int;

    /**
     * Gets the localized human-friendly name of this service
     *
     * @since 2025.05.01
     * 
     * @return string
     */
    public function getLabel(): string;

    /**
     * Gets the scope of this service (System or User)
     *
     * @since 2025.05.01
     * 
     * @return ServiceScope
     */
    public function getScope(): ServiceScope;

    /**
     * Gets the owner user ID for User-scoped services
     * 
     * @since 2025.05.01
     * 
     * @return string|null User ID or null for System scope
     */
    public function getOwner(): ?string;

    /**
     * Gets whether this service is enabled
     *
     * @since 2025.05.01
     * 
     * @return bool
     */
    public function getEnabled(): bool;

    /**
     * Gets the primary mailing address for this service
     *
     * @since 2025.05.01
     *
     * @return IAddress
     */
    public function getPrimaryAddress(): IAddress;

    /**
     * Gets the secondary mailing addresses (aliases) for this service
     *
     * @since 2025.05.01
     *
     * @return array<int, IAddress>
     */
    public function getSecondaryAddresses(): array;

    /**
     * Checks if this service handles a specific email address
     * 
     * @since 2025.05.01
     * 
     * @param string $address Email address to check
     * 
     * @return bool True if address matches primary or any secondary address
     */
    public function handlesAddress(string $address): bool;

}