<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Exception;

use Exception;

/**
 * Mail Send Exception
 * 
 * Exception thrown when mail delivery fails.
 * 
 * @since 2025.05.01
 */
class SendException extends Exception {

    /**
     * @param string $message Error message
     * @param int $code Error code
     * @param Exception|null $previous Previous exception
     * @param string|null $recipient Specific recipient that failed (if applicable)
     * @param bool $permanent Whether this is a permanent failure (no retry)
     */
    public function __construct(
        string $message,
        int $code = 0,
        ?Exception $previous = null,
        public readonly ?string $recipient = null,
        public readonly bool $permanent = false,
    ) {
        parent::__construct($message, $code, $previous);
    }

    /**
     * Creates a permanent failure exception (no retry)
     * 
     * @since 2025.05.01
     * 
     * @param string $message
     * @param string|null $recipient
     * 
     * @return self
     */
    public static function permanent(string $message, ?string $recipient = null): self {
        return new self($message, 0, null, $recipient, true);
    }

    /**
     * Creates a temporary failure exception (will retry)
     * 
     * @since 2025.05.01
     * 
     * @param string $message
     * @param Exception|null $previous
     * 
     * @return self
     */
    public static function temporary(string $message, ?Exception $previous = null): self {
        return new self($message, 0, $previous, null, false);
    }

}