<?php

declare(strict_types=1);

namespace App\Domain\MailServer\Contracts;

/**
 * Mail server adapter interface.
 *
 * Hosting panelinin kendi mail bildirimlerini (parola sıfırlama, fatura,
 * 2FA setup, sistem uyarıları) göndermesi için.
 *
 * Adapter'lar:
 *   - PostfixAdapter:        Yerel Postfix SMTP server (önerilen — install.sh ile kurulur)
 *   - EximAdapter:           cPanel migration uyumluluğu için
 *   - ExternalRelayAdapter:  Mailgun / SES / SendGrid / SMTP relay
 *   - NoneAdapter:           Mail gönderme yok (log driver — sadece test/dev)
 */
interface MailServerAdapter
{
    // ─── Meta ──────────────────────────────────────────────────────────────

    public function name(): string;

    public function key(): string;

    public function description(): string;

    /**
     * Paket yöneticisi adı (postfix, exim, vb). Boş = manuel/external.
     */
    public function packageName(): string;

    /**
     * Systemd service adı (postfix, exim). Boş = service yok.
     */
    public function serviceName(): string;

    /**
     * UI'da kart açıklamasında gösterilecek güçlü yanlar.
     * @return array<int, string>
     */
    public function strengths(): array;

    /**
     * Tahmini başarı / hız skoru (0-100, marketing amaçlı).
     */
    public function performanceScore(): int;

    // ─── Lifecycle ─────────────────────────────────────────────────────────

    public function isInstalled(): bool;

    public function isRunning(): bool;

    public function isEnabled(): bool;

    public function version(): string;

    /**
     * @return array{ok: bool, output: string, error?: string}
     */
    public function install(): array;

    /**
     * @return array{ok: bool, output: string}
     */
    public function uninstall(): array;

    public function start(): void;

    public function stop(): void;

    public function reload(): void;

    public function restart(): void;

    public function enable(): void;

    public function disable(): void;

    // ─── Mail ──────────────────────────────────────────────────────────────

    /**
     * Test mail gönder.
     * @throws \RuntimeException Mail gönderilemediğinde
     */
    public function sendTestMail(string $to, string $from): void;

    /**
     * Mail queue durumu.
     * @return array{count: int, oldest_seconds: int|null, frozen: int}
     */
    public function queueStatus(): array;

    /**
     * Queue'u flush et.
     */
    public function flushQueue(): void;

    /**
     * Laravel mail config (env değerleri).
     * @return array<string, mixed>
     */
    public function laravelConfig(): array;
}
