<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Object;

use KTXF\Json\JsonSerializable;

/**
 * Message Part Interface
 * 
 * Represents a MIME part of a message (body, attachment, etc.)
 * 
 * @since 2025.05.01
 */
interface MessagePartInterface extends JsonSerializable {

    public const PROPERTY_PART_ID = 'partId';
    public const PROPERTY_BLOB_ID = 'blobId';
    public const PROPERTY_BLOB_IDSIZE = 'size';
    public const PROPERTY_NAME = 'name';
    public const PROPERTY_TYPE = 'type';
    public const PROPERTY_CHARSET = 'charset';
    public const PROPERTY_DISPOSITION = 'disposition';
    public const PROPERTY_CONTENT_ID = 'cid';
    public const PROPERTY_LANGUAGE = 'language';
    public const PROPERTY_LOCATION = 'location';
    public const PROPERTY_CONTENT = 'content';
    public const PROPERTY_SUB_PARTS = 'subParts';

    /**
     * Gets the blob identifier
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getBlobId(): ?string;

    /**
     * Gets the part identifier
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getId(): ?string;

    /**
     * Gets the part size in bytes
     *
     * @since 2026.06.15
     *
     * @return int|null
     */
    public function getSize(): ?int;

    /**
     * Gets the MIME type
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getType(): ?string;

    /**
     * Gets the content disposition (inline, attachment)
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getDisposition(): ?string;

    /**
     * Gets the Content-ID for inline parts
     *
     * @since 2026.06.15
     *
     * @return string|null
     */
    public function getContentId(): ?string;

    /**
     * Gets the part name
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getName(): ?string;

    /**
     * Gets the character set
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getCharset(): ?string;

    /**
     * Gets the language
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getLanguage(): ?string;

    /**
     * Gets the location
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getLocation(): ?string;

    /**
     * Gets the decoded part content
     *
     * @since 2026.06.15
     *
     * @return string|null
     */
    public function getContent(): ?string;

    /**
     * Gets the sub-parts
     *
     * @since 2025.05.01
     *
     * @return array<int,MessagePartInterface>
     */
    public function getParts(): array;

}