resource provider and service improvements

2026-01-03 13:18:04 -05:00
parent 74f9278749
commit 8f35442335
36 changed files with 1447 additions and 1086 deletions
--- a/shared/lib/Mail/Service/ServiceMessageMutableInterface.php
+++ b/shared/lib/Mail/Service/ServiceMessageMutableInterface.php
@@ -0,0 +1,119 @@
+<?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\Entity\IMessageBase;
+use KTXF\Mail\Entity\IMessageMutable;
+
+/**
+ * Mail Service Message Mutable Interface
+ * 
+ * Optional interface for services that support message CRUD operations.
+ * Provides message creation, modification, deletion, copying, moving, and flag management.
+ * 
+ * @since 2025.05.01
+ */
+interface ServiceMessageMutableInterface extends ServiceBaseInterface {
+
+    public const CAPABILITY_MESSAGE_CREATE = 'MessageCreate';
+    public const CAPABILITY_MESSAGE_MODIFY = 'MessageModify';
+    public const CAPABILITY_MESSAGE_DESTROY = 'MessageDestroy';
+    public const CAPABILITY_MESSAGE_COPY = 'MessageCopy';
+    public const CAPABILITY_MESSAGE_MOVE = 'MessageMove';
+    public const CAPABILITY_MESSAGE_FLAG = 'MessageFlag';
+
+    /**
+     * Creates a fresh message instance for composition
+     *
+     * @since 2025.05.01
+     *
+     * @return IMessageMutable Fresh message object
+     */
+    public function messageFresh(): IMessageMutable;
+
+    /**
+     * Creates/imports a message into a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $collection Target collection ID
+     * @param IMessageMutable $message Message to create
+     * @param array $options Protocol-specific options (e.g., flags, keywords)
+     *
+     * @return IMessageBase Created message with assigned ID
+     */
+    public function messageCreate(string|int $collection, IMessageMutable $message, array $options = []): IMessageBase;
+
+    /**
+     * Modifies an existing message
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $collection Collection ID
+     * @param string|int $identifier Message ID
+     * @param IMessageMutable $message Updated message data
+     *
+     * @return IMessageBase Modified message
+     */
+    public function messageModify(string|int $collection, string|int $identifier, IMessageMutable $message): IMessageBase;
+
+    /**
+     * Destroys one or more messages
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $collection Collection ID
+     * @param string|int ...$identifiers Message IDs to destroy
+     *
+     * @return array<string|int,bool> Map of ID => destroyed
+     */
+    public function messageDestroy(string|int $collection, string|int ...$identifiers): array;
+
+    /**
+     * Copies messages to another collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $sourceCollection Source collection ID
+     * @param string|int $targetCollection Target collection ID
+     * @param string|int ...$identifiers Message IDs to copy
+     *
+     * @return array<string|int,string|int> Map of source ID => new ID
+     */
+    public function messageCopy(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
+
+    /**
+     * Moves messages to another collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $sourceCollection Source collection ID
+     * @param string|int $targetCollection Target collection ID
+     * @param string|int ...$identifiers Message IDs to move
+     *
+     * @return array<string|int,bool> Map of ID => moved
+     */
+    public function messageMove(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
+
+    /**
+     * Sets flags on messages
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int $collection Collection ID
+     * @param array $flags Flags to set (e.g., ['\Seen', '\Flagged'])
+     * @param bool $value True to add flags, false to remove
+     * @param string|int ...$identifiers Message IDs
+     *
+     * @return array<string|int,bool> Map of ID => success
+     */
+    public function messageFlag(string|int $collection, array $flags, bool $value, string|int ...$identifiers): array;
+
+}