<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Selector;

use JsonSerializable;
use KTXF\Mail\Service\ServiceScope;

/**
 * Mail Service Selector
 * 
 * Filter criteria for selecting mail services from providers.
 * 
 * @since 2025.05.01
 */
class ServiceSelector implements JsonSerializable {

    private ?ServiceScope $scope = null;
    private ?string $owner = null;
    private ?string $address = null;
    private ?array $capabilities = null;
    private ?bool $enabled = null;

    /**
     * Filter by service scope
     * 
     * @since 2025.05.01
     * 
     * @param ServiceScope|null $scope
     * 
     * @return self
     */
    public function setScope(?ServiceScope $scope): self {
        $this->scope = $scope;
        return $this;
    }

    /**
     * Gets the scope filter
     * 
     * @since 2025.05.01
     * 
     * @return ServiceScope|null
     */
    public function getScope(): ?ServiceScope {
        return $this->scope;
    }

    /**
     * Filter by owner user ID
     * 
     * @since 2025.05.01
     * 
     * @param string|null $owner
     * 
     * @return self
     */
    public function setOwner(?string $owner): self {
        $this->owner = $owner;
        return $this;
    }

    /**
     * Gets the owner filter
     * 
     * @since 2025.05.01
     * 
     * @return string|null
     */
    public function getOwner(): ?string {
        return $this->owner;
    }

    /**
     * Filter by email address (matches primary or secondary)
     * 
     * @since 2025.05.01
     * 
     * @param string|null $address
     * 
     * @return self
     */
    public function setAddress(?string $address): self {
        $this->address = $address;
        return $this;
    }

    /**
     * Gets the address filter
     * 
     * @since 2025.05.01
     * 
     * @return string|null
     */
    public function getAddress(): ?string {
        return $this->address;
    }

    /**
     * Filter by required capabilities
     * 
     * @since 2025.05.01
     * 
     * @param array<string>|null $capabilities
     * 
     * @return self
     */
    public function setCapabilities(?array $capabilities): self {
        $this->capabilities = $capabilities;
        return $this;
    }

    /**
     * Gets the capabilities filter
     * 
     * @since 2025.05.01
     * 
     * @return array<string>|null
     */
    public function getCapabilities(): ?array {
        return $this->capabilities;
    }

    /**
     * Filter by enabled status
     * 
     * @since 2025.05.01
     * 
     * @param bool|null $enabled
     * 
     * @return self
     */
    public function setEnabled(?bool $enabled): self {
        $this->enabled = $enabled;
        return $this;
    }

    /**
     * Gets the enabled filter
     * 
     * @since 2025.05.01
     * 
     * @return bool|null
     */
    public function getEnabled(): ?bool {
        return $this->enabled;
    }

    /**
     * Checks if any filter criteria are set
     * 
     * @since 2025.05.01
     * 
     * @return bool
     */
    public function hasFilters(): bool {
        return $this->scope !== null
            || $this->owner !== null
            || $this->address !== null
            || $this->capabilities !== null
            || $this->enabled !== null;
    }

    /**
     * @inheritDoc
     */
    public function jsonSerialize(): array {
        return array_filter([
            'scope' => $this->scope?->value,
            'owner' => $this->owner,
            'address' => $this->address,
            'capabilities' => $this->capabilities,
            'enabled' => $this->enabled,
        ], fn($v) => $v !== null);
    }

}