<?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\Json\JsonDeserializable;
use KTXF\Mail\Service\IServiceBase;

/**
 * Mail Provider Service Mutate Interface
 * 
 * Optional interface for providers that support service CRUD operations.
 * 
 * @since 2025.05.01
 */
interface IProviderServiceMutate extends JsonDeserializable {

    public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
    public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
    public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
    public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';

    /**
     * Creates a new blank service instance for configuration
     *
     * @since 2025.05.01
     *
     * @return IServiceBase Fresh service object
     */
    public function serviceFresh(): IServiceBase;

    /**
     * Creates a new service configuration
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId Owner user ID (null for system services)
     * @param IServiceBase $service Service configuration to create
     *
     * @return string|int Created service identifier
     */
    public function serviceCreate(string $tenantId, ?string $userId, IServiceBase $service): string|int;

    /**
     * Modifies an existing service configuration
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId User identifier for authorization context
     * @param IServiceBase $service Service configuration to update
     *
     * @return string|int Updated service identifier
     */
    public function serviceModify(string $tenantId, ?string $userId, IServiceBase $service): string|int;

    /**
     * Destroys a service configuration
     *
     * @since 2025.05.01
     *
     * @param string $tenantId Tenant identifier
     * @param string|null $userId User identifier for authorization context
     * @param IServiceBase $service Service to destroy
     *
     * @return bool True if destroyed, false if not found
     */
    public function serviceDestroy(string $tenantId, ?string $userId, IServiceBase $service): bool;

}