<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Entity;

use JsonSerializable;

/**
 * Mail Attachment Interface
 * 
 * Represents a file attachment on a mail message.
 * 
 * @since 2025.05.01
 */
interface IAttachment extends JsonSerializable {

    public const JSON_PROPERTY_ID = 'id';
    public const JSON_PROPERTY_NAME = 'name';
    public const JSON_PROPERTY_MIME_TYPE = 'mimeType';
    public const JSON_PROPERTY_SIZE = 'size';
    public const JSON_PROPERTY_CONTENT_ID = 'contentId';
    public const JSON_PROPERTY_INLINE = 'inline';

    /**
     * Gets the attachment identifier
     *
     * @since 2025.05.01
     *
     * @return string|null Attachment ID or null for new attachments
     */
    public function getId(): ?string;

    /**
     * Gets the file name
     *
     * @since 2025.05.01
     *
     * @return string File name (e.g., "document.pdf")
     */
    public function getName(): string;

    /**
     * Gets the MIME type
     *
     * @since 2025.05.01
     *
     * @return string MIME type (e.g., "application/pdf")
     */
    public function getMimeType(): string;

    /**
     * Gets the file size in bytes
     *
     * @since 2025.05.01
     *
     * @return int|null Size in bytes or null if unknown
     */
    public function getSize(): ?int;

    /**
     * Gets the Content-ID for inline attachments
     *
     * @since 2025.05.01
     *
     * @return string|null Content-ID for referencing in HTML body (e.g., "cid:image1")
     */
    public function getContentId(): ?string;

    /**
     * Checks if this is an inline attachment (embedded in body)
     *
     * @since 2025.05.01
     *
     * @return bool True if inline, false if regular attachment
     */
    public function isInline(): bool;

    /**
     * Gets the attachment content
     *
     * @since 2025.05.01
     *
     * @return string Binary content of the attachment
     */
    public function getContent(): string;

}