<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Collection;

use DateTimeImmutable;
use JsonSerializable;

/**
 * Mail Collection Base Interface
 * 
 * Represents a mailbox/folder in a mail service.
 * For future use with full mail providers (IMAP, JMAP, etc.)
 * 
 * @since 2025.05.01
 */
interface ICollectionBase extends JsonSerializable {

    public const JSON_TYPE = 'mail.collection';
    public const JSON_PROPERTY_TYPE = '@type';
    public const JSON_PROPERTY_PROVIDER = 'provider';
    public const JSON_PROPERTY_SERVICE = 'service';
    public const JSON_PROPERTY_IN = 'in';
    public const JSON_PROPERTY_ID = 'id';
    public const JSON_PROPERTY_LABEL = 'label';
    public const JSON_PROPERTY_ROLE = 'role';
    public const JSON_PROPERTY_TOTAL = 'total';
    public const JSON_PROPERTY_UNREAD = 'unread';

    /**
     * Gets the parent collection identifier (null for root)
     *
     * @since 2025.05.01
     *
     * @return string|int|null
     */
    public function in(): string|int|null;

    /**
     * Gets the collection identifier
     *
     * @since 2025.05.01
     *
     * @return string|int
     */
    public function id(): string|int;

    /**
     * Gets the collection label/name
     *
     * @since 2025.05.01
     *
     * @return string
     */
    public function getLabel(): string;

    /**
     * Gets the collection role
     *
     * @since 2025.05.01
     *
     * @return CollectionRoles
     */
    public function getRole(): CollectionRoles;

    /**
     * Gets the total message count
     *
     * @since 2025.05.01
     *
     * @return int|null
     */
    public function getTotal(): ?int;

    /**
     * Gets the unread message count
     *
     * @since 2025.05.01
     *
     * @return int|null
     */
    public function getUnread(): ?int;

    /**
     * Gets the collection signature/sync token
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getSignature(): ?string;

    /**
     * Gets the creation date
     *
     * @since 2025.05.01
     *
     * @return DateTimeImmutable|null
     */
    public function created(): ?DateTimeImmutable;

    /**
     * Gets the modification date
     *
     * @since 2025.05.01
     *
     * @return DateTimeImmutable|null
     */
    public function modified(): ?DateTimeImmutable;

}