server/shared/lib/Mail/Service/ServiceBaseInterface.php

<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Service;

use KTXF\Mail\Collection\ICollectionBase;
use KTXF\Mail\Entity\IAddress;
use KTXF\Mail\Entity\IMessageBase;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;

/**
 * Mail Service Base Interface
 * 
 * Core interface for mail services with full protocol support (IMAP, JMAP, EWS, ActiveSync, Gmail API, etc.)
 * Provides identity, addressing, capability information, and collection/message operations.
 * 
 * @since 2025.05.01
 */
interface ServiceBaseInterface extends ResourceServiceBaseInterface {

    // Collection capabilities
    public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
    public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
    public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
    public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
    public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
    // Message capabilities
    public const CAPABILITY_ENTITY_LIST = 'EntityList';
    public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
    public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
    public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
    public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
    public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
    public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
    // Filter capabilities
    public const CAPABILITY_FILTER_ID = 'id';
    public const CAPABILITY_FILTER_SUBJECT = 'subject';
    public const CAPABILITY_FILTER_FROM = 'from';
    public const CAPABILITY_FILTER_TO = 'to';
    public const CAPABILITY_FILTER_DATE = 'date';
    public const CAPABILITY_FILTER_FLAG = 'flag';
    public const CAPABILITY_FILTER_SIZE = 'size';
    public const CAPABILITY_FILTER_BODY = 'body';
    // Sort capabilities
    public const CAPABILITY_SORT_DATE = 'date';
    public const CAPABILITY_SORT_SUBJECT = 'subject';
    public const CAPABILITY_SORT_FROM = 'from';
    public const CAPABILITY_SORT_SIZE = 'size';

    public const JSON_TYPE = 'mail.service';
    public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
    public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';

    /**
     * Gets the primary mailing address for this service
     *
     * @since 2025.05.01
     *
     * @return IAddress
     */
    public function getPrimaryAddress(): IAddress;

    /**
     * Gets the secondary mailing addresses (aliases) for this service
     *
     * @since 2025.05.01
     *
     * @return array<int, IAddress>
     */
    public function getSecondaryAddresses(): array;

    /**
     * Checks if this service handles a specific email address
     * 
     * @since 2025.05.01
     * 
     * @param string $address Email address to check
     * 
     * @return bool True if address matches primary or any secondary address
     */
    public function handlesAddress(string $address): bool;

    /**
     * Lists all collections in this service
     *
     * @since 2025.05.01
     *
     * @param IFilter|null $filter Optional filter criteria
     * @param ISort|null $sort Optional sort order
     *
     * @return array<string|int,ICollectionBase> Collections indexed by ID
     */
    public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array;

    /**
     * Creates a filter builder for collections
     *
     * @since 2025.05.01
     *
     * @return IFilter
     */
    public function collectionListFilter(): IFilter;

    /**
     * Creates a sort builder for collections
     *
     * @since 2025.05.01
     *
     * @return ISort
     */
    public function collectionListSort(): ISort;

    /**
     * Checks if collections exist
     *
     * @since 2025.05.01
     *
     * @param string|int ...$identifiers Collection IDs to check
     *
     * @return array<string|int,bool> Map of ID => exists
     */
    public function collectionExtant(string|int ...$identifiers): array;

    /**
     * Fetches a single collection
     *
     * @since 2025.05.01
     *
     * @param string|int $identifier Collection ID
     *
     * @return ICollectionBase|null Collection or null if not found
     */
    public function collectionFetch(string|int $identifier): ?ICollectionBase;

    /**
     * Lists messages in a collection
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection ID
     * @param IFilter|null $filter Optional filter criteria
     * @param ISort|null $sort Optional sort order
     * @param IRange|null $range Optional pagination
     * @param array|null $properties Optional message properties to fetch
     *
     * @return array<string|int,IMessageBase> Messages indexed by ID
     */
    public function messageList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;

    /**
     * Creates a filter builder for messages
     *
     * @since 2025.05.01
     *
     * @return IFilter
     */
    public function messageListFilter(): IFilter;

    /**
     * Creates a sort builder for messages
     *
     * @since 2025.05.01
     *
     * @return ISort
     */
    public function messageListSort(): ISort;

    /**
     * Creates a range builder for messages
     *
     * @since 2025.05.01
     *
     * @param RangeType $type Range type (offset, cursor, etc.)
     *
     * @return IRange
     */
    public function messageListRange(RangeType $type): IRange;

    /**
     * Gets incremental changes since last sync
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection ID
     * @param string $signature Sync token from previous sync
     * @param string $detail Detail level: 'ids', 'minimal', 'full'
     *
     * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
     */
    public function messageDelta(string|int $collection, string $signature, string $detail = 'ids'): array;

    /**
     * Checks if messages exist
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection ID
     * @param string|int ...$identifiers Message IDs to check
     *
     * @return array<string|int,bool> Map of ID => exists
     */
    public function messageExtant(string|int $collection, string|int ...$identifiers): array;

    /**
     * Fetches one or more messages
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection ID
     * @param string|int ...$identifiers Message IDs to fetch
     *
     * @return array<string|int,IMessageBase> Messages indexed by ID
     */
    public function messageFetch(string|int $collection, string|int ...$identifiers): array;

}