chore: implement serice interface changes

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

lib/Providers/Mail/MessageProperties.php

@@ -23,91 +23,91 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
 	 */
 	public function fromJmap(array $parameters): static {
 
-		if (isset($parameters['messageId'])) {
-			$this->data['urid'] = $parameters['messageId'][0];
-		}
 		if (isset($parameters['size'])) {
-			$this->data['size'] = $parameters['size'];
+			$this->data[static::PROPERTY_SIZE] = $parameters['size'];
 		}
+
+		if (isset($parameters['headers']) && is_array($parameters['headers'])) {
+			$this->data[static::PROPERTY_HEADERS] = $parameters['headers'];
+		}
+
+		if (isset($parameters['messageId'])) {
+			$this->data[static::PROPERTY_URID] = $parameters['messageId'][0];
+		}
+
 		if (isset($parameters['receivedAt'])) {
-			$this->data['received'] = $parameters['receivedAt'];
+			$this->data[static::PROPERTY_RECEIVED] = $parameters['receivedAt'];
 		}
+
 		if (isset($parameters['sentAt'])) {
-			$this->data['date'] = $parameters['sentAt'];
+			$this->data[static::PROPERTY_SENT] = $parameters['sentAt'];
 		}
+		
 		if (isset($parameters['inReplyTo'])) {
-			$this->data['inReplyTo'] = $parameters['inReplyTo'];
+			$this->data[static::PROPERTY_IN_REPLY_TO] = $parameters['inReplyTo'];
 		}
+		
 		if (isset($parameters['references'])) {
-			$this->data['references'] = is_array($parameters['references']) ? $parameters['references'] : [];
+			$this->data[static::PROPERTY_REFERENCES] = is_array($parameters['references']) ? $parameters['references'] : [];
-		}
-		if (isset($parameters['subject'])) {
-			$this->data['subject'] = $parameters['subject'];
-		}
-		if (isset($parameters['preview'])) {
-			$this->data['snippet'] = $parameters['preview'];
 		}
+
 		if (isset($parameters['sender'])) {
-			$this->data['sender'] = $parameters['sender'];
+			$this->data[static::PROPERTY_SENDER] = $parameters['sender'];
 		}
+
 		if (isset($parameters['from']) && is_array($parameters['from']) && !empty($parameters['from'])) {
-			$this->data['from'] = [
+			$this->data[static::PROPERTY_FROM] = [
 				'address' => $parameters['from'][0]['email'] ?? '',
 				'label' => $parameters['from'][0]['name'] ?? null
 			];
 		}
-		if (isset($parameters['to']) && is_array($parameters['to'])) {
+
-			$this->data['to'] = [];
-			foreach ($parameters['to'] as $addr) {
-				$this->data['to'][] = [
-					'address' => $addr['email'] ?? '',
-					'label' => $addr['name'] ?? null
-				];
-			}
-		}
-		if (isset($parameters['cc']) && is_array($parameters['cc'])) {
-			$this->data['cc'] = [];
-			foreach ($parameters['cc'] as $addr) {
-				$this->data['cc'][] = [
-					'address' => $addr['email'] ?? '',
-					'label' => $addr['name'] ?? null
-				];
-			}
-		}
-		if (isset($parameters['bcc']) && is_array($parameters['bcc'])) {
-			$this->data['bcc'] = [];
-			foreach ($parameters['bcc'] as $addr) {
-				$this->data['bcc'][] = [
-					'address' => $addr['email'] ?? '',
-					'label' => $addr['name'] ?? null
-				];
-			}
-		}
 		if (isset($parameters['replyTo']) && is_array($parameters['replyTo'])) {
-			$this->data['replyTo'] = [];
+			$this->data[static::PROPERTY_REPLY_TO] = [];
 			foreach ($parameters['replyTo'] as $addr) {
-				$this->data['replyTo'][] = [
+				$this->data[static::PROPERTY_REPLY_TO][] = [
 					'address' => $addr['email'] ?? '',
 					'label' => $addr['name'] ?? null
 				];
 			}
 		}
-		if (isset($parameters['keywords']) && is_array($parameters['keywords'])) {
+
-			$this->data['flags'] = [];
+		if (isset($parameters['to']) && is_array($parameters['to'])) {
-			foreach ($parameters['keywords'] as $keyword => $value) {
+			$this->data[static::PROPERTY_TO] = [];
-				$flag = match($keyword) {
+			foreach ($parameters['to'] as $addr) {
-					'$seen' => 'read',
+				$this->data[static::PROPERTY_TO][] = [
-					'$flagged' => 'flagged',
+					'address' => $addr['email'] ?? '',
-					'$answered' => 'answered',
+					'label' => $addr['name'] ?? null
-					'$draft' => 'draft',
+				];
-					'$deleted' => 'deleted',
-					default => $keyword
-				};
-				$this->data['flags'][$flag] = $value;
 			}
 		}
+
+		if (isset($parameters['cc']) && is_array($parameters['cc'])) {
+			$this->data[static::PROPERTY_CC] = [];
+			foreach ($parameters['cc'] as $addr) {
+				$this->data[static::PROPERTY_CC][] = [
+					'address' => $addr['email'] ?? '',
+					'label' => $addr['name'] ?? null
+				];
+			}
+		}
+
+		if (isset($parameters['bcc']) && is_array($parameters['bcc'])) {
+			$this->data[static::PROPERTY_BCC] = [];
+			foreach ($parameters['bcc'] as $addr) {
+				$this->data[static::PROPERTY_BCC][] = [
+					'address' => $addr['email'] ?? '',
+					'label' => $addr['name'] ?? null
+				];
+			}
+		}
+
+		if (isset($parameters['subject'])) {
+			$this->data[static::PROPERTY_SUBJECT] = $parameters['subject'];
+		}
+
 		if (isset($parameters['bodyStructure'])) {
-			$this->data['body'] = $parameters['bodyStructure'];
+			$this->data[static::PROPERTY_BODY] = $parameters['bodyStructure'];
 			// Recursively add content from bodyValues to matching parts
 			if (isset($parameters['bodyValues']) && is_array($parameters['bodyValues'])) {
 				$addContentToParts = function(&$structure, $bodyValues) use (&$addContentToParts) {
@@ -123,14 +123,27 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
 					}
 				};
 				
-				$addContentToParts($this->data['body'], $parameters['bodyValues']);
+				$addContentToParts($this->data[static::PROPERTY_BODY], $parameters['bodyValues']);
 			}
 		}
-		if (isset($parameters['headers']) && is_array($parameters['headers'])) {
+
-			$this->data['headers'] = $parameters['headers'];
-		}
 		if (isset($parameters['attachments'])) {
-			$this->data['attachments'] = $parameters['attachments'];
+			$this->data[static::PROPERTY_ATTACHMENTS] = $parameters['attachments'];
+		}
+
+		if (isset($parameters['keywords']) && is_array($parameters['keywords'])) {
+			$this->data[static::PROPERTY_FLAGS] = [];
+			foreach ($parameters['keywords'] as $keyword => $value) {
+				$flag = match($keyword) {
+					'$seen' => 'read',
+					'$flagged' => 'flagged',
+					'$answered' => 'answered',
+					'$draft' => 'draft',
+					'$deleted' => 'deleted',
+					default => $keyword
+				};
+				$this->data[static::PROPERTY_FLAGS][$flag] = $value;
+			}
 		}
 
 		return $this;

lib/Providers/Mail/Provider.php

@@ -14,6 +14,7 @@ use KTXF\Mail\Provider\ProviderServiceDiscoverInterface;
 use KTXF\Mail\Provider\ProviderServiceMutateInterface;
 use KTXF\Mail\Provider\ProviderServiceTestInterface;
 use KTXF\Mail\Service\ServiceBaseInterface;
+use KTXF\Mail\Service\ServiceMutableInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
 use KTXF\Resource\Provider\ResourceServiceMutateInterface;
 use KTXM\ProviderJmapc\Service\Discovery;
@@ -23,10 +24,9 @@ use KTXM\ProviderJmapc\Stores\ServiceStore;
 /**
  * JMAP Mail Provider
  */
-class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
+class Provider implements ProviderBaseInterface, ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
 {
 
-    public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
     protected const PROVIDER_IDENTIFIER = 'jmap';
 	protected const PROVIDER_LABEL = 'JMAP Mail Provider';
 	protected const PROVIDER_DESCRIPTION = 'Provides mail services via JMAP protocol (RFC 8620)';
@@ -155,7 +155,7 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
         }
 
         $updated = $this->serviceStore->modify($tenantId, $userId, $service);
-        return (string) $updated['id'];
+        return (string) $updated['sid'];
     }
 
     public function serviceDestroy(string $tenantId, string $userId, ResourceServiceMutateInterface $service): bool
@@ -180,7 +180,8 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
         return $discovery->discover($identity, $location, $secret, $verifySSL);
     }
 
-    public function serviceTest(ServiceBaseInterface $service, array $options = []): array {
+    public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array
+    {
         $startTime = microtime(true);
 
         try {
@@ -199,8 +200,7 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
                     . ' (Account ID: ' . ($session->username() ?? 'N/A') . ')'
                     . ' (Latency: ' . $latency . ' ms)',
             ];
-        } catch (\Exception $e) {
+        } catch (\Throwable $e) {
-            $latency = round((microtime(true) - $startTime) * 1000);
             return [
                 'success' => false,
                 'message' => 'Test failed: ' . $e->getMessage(),

lib/Providers/Mail/Service.php

@@ -13,13 +13,16 @@ use Generator;
 use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Collection\CollectionRoles;
 use KTXF\Mail\Collection\CollectionMutableInterface;
+use KTXF\Mail\Collection\CollectionPropertiesBaseInterface;
 use KTXF\Mail\Object\Address;
 use KTXF\Mail\Object\AddressInterface;
+use KTXF\Mail\Object\MessagePropertiesMutableInterface;
 use KTXF\Mail\Service\ServiceBaseInterface;
 use KTXF\Mail\Service\ServiceCollectionMutableInterface;
 use KTXF\Mail\Service\ServiceConfigurableInterface;
 use KTXF\Mail\Service\ServiceEntityMutableInterface;
 use KTXF\Mail\Service\ServiceMutableInterface;
+use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Provider\ResourceServiceIdentityInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
 use KTXF\Resource\Delta\Delta;
@@ -27,6 +30,7 @@ use KTXF\Resource\Filter\Filter;
 use KTXF\Resource\Filter\IFilter;
 use KTXF\Resource\Identifier\CollectionIdentifier;
 use KTXF\Resource\Identifier\EntityIdentifier;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXF\Resource\Range\IRange;
 use KTXF\Resource\Range\Range;
 use KTXF\Resource\Range\RangeType;
@@ -37,9 +41,8 @@ use KTXM\ProviderJmapc\Providers\ServiceLocation;
 use KTXM\ProviderJmapc\Service\Remote\RemoteMailService;
 use KTXM\ProviderJmapc\Service\Remote\RemoteService;
 
-class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceConfigurableInterface, ServiceCollectionMutableInterface
+class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceConfigurableInterface, ServiceCollectionMutableInterface, ServiceEntityMutableInterface
 {
-    public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
 
     private const PROVIDER_IDENTIFIER = 'jmap';
 
@@ -48,7 +51,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     private ?string $serviceIdentifier = null;
     private ?string $serviceLabel = null;
 	private bool $serviceEnabled = false;
-    private bool $serviceDebug = false;
     private string $primaryAddress = '';
     private array $secondaryAddresses = [];
     private ?ServiceLocation $location = null;
@@ -58,18 +60,20 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     private array $serviceAbilities = [
 		self::CAPABILITY_COLLECTION_LIST => true,
 		self::CAPABILITY_COLLECTION_LIST_FILTER => [
-            self::CAPABILITY_COLLECTION_FILTER_LABEL => 's:100:256:256',
+            self::CAPABILITY_COLLECTION_FILTER_LABEL => 's:128:256:256',
-            self::CAPABILITY_COLLECTION_FILTER_ROLE => 's:100:256:256',
+            self::CAPABILITY_COLLECTION_FILTER_ROLE => 's:32:1:1',
+            self::CAPABILITY_COLLECTION_FILTER_SUBSCRIBED => 'b:0:1:1',
 		],
 		self::CAPABILITY_COLLECTION_LIST_SORT => [
             self::CAPABILITY_COLLECTION_SORT_LABEL,
             self::CAPABILITY_COLLECTION_SORT_RANK,
 		],
-		self::CAPABILITY_COLLECTION_EXTANT => true,
 		self::CAPABILITY_COLLECTION_FETCH => true,
+        self::CAPABILITY_COLLECTION_EXTANT => true,
         self::CAPABILITY_COLLECTION_CREATE => true,
         self::CAPABILITY_COLLECTION_UPDATE => true,
         self::CAPABILITY_COLLECTION_DELETE => true,
+        self::CAPABILITY_COLLECTION_MOVE => true,
 		self::CAPABILITY_ENTITY_LIST => true,
 		self::CAPABILITY_ENTITY_LIST_FILTER => [
 			self::CAPABILITY_ENTITY_FILTER_ALL => 's:200:256:256',
@@ -95,11 +99,14 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 		self::CAPABILITY_ENTITY_LIST_RANGE => [
 			'tally' => ['absolute', 'relative']
 		],
-		self::CAPABILITY_ENTITY_DELTA => true,
-		self::CAPABILITY_ENTITY_EXTANT => true,
 		self::CAPABILITY_ENTITY_FETCH => true,
-        //self::CAPABILITY_ENTITY_DELETE => true,
+        self::CAPABILITY_ENTITY_EXTANT => true,
-        //self::CAPABILITY_ENTITY_MOVE => true,
+        self::CAPABILITY_ENTITY_CREATE => false,
+        self::CAPABILITY_ENTITY_MODIFY => false,
+        self::CAPABILITY_ENTITY_PATCH => true,
+        self::CAPABILITY_ENTITY_DELETE => true,
+        self::CAPABILITY_ENTITY_MOVE => true,
+        self::CAPABILITY_ENTITY_COPY => false,
 	];
 
     private readonly RemoteMailService $mailService;
@@ -107,21 +114,22 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     public function __construct(
     ) {}
 
-    private function initialize(): void {
+    private function initialize(): void
+    {
         if (!isset($this->mailService)) {
             $client = RemoteService::freshClient($this);
             $this->mailService = RemoteService::mailService($client);
         }
     }
 
-    public function toStore(): array {
+    public function toStore(): array
+    {
         return array_filter([
             'tid' => $this->serviceTenantId,
             'uid' => $this->serviceUserId,
             'sid' => $this->serviceIdentifier,
-            'label' => $this->serviceLabel,
             'enabled' => $this->serviceEnabled,
-            'debug' => $this->serviceDebug,
+            'label' => $this->serviceLabel,
             'primaryAddress' => $this->primaryAddress,
             'secondaryAddresses' => $this->secondaryAddresses,
             'location' => $this->location?->toStore(),
@@ -130,13 +138,13 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         ], fn($v) => $v !== null);
     }
 
-    public function fromStore(array $data): static {
+    public function fromStore(array $data): static
+    {
         $this->serviceTenantId = $data['tid'] ?? null;
         $this->serviceUserId = $data['uid'] ?? null;
         $this->serviceIdentifier = $data['sid'];
         $this->serviceLabel = $data['label'] ?? '';
         $this->serviceEnabled = $data['enabled'] ?? false;
-        $this->serviceDebug = $data['debug'] ?? false;
 
         if (isset($data['primaryAddress'])) {
             $this->primaryAddress = $data['primaryAddress'];
@@ -159,7 +167,8 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    public function jsonSerialize(): array {
+    public function jsonSerialize(): array
+    {
         return array_filter([
             self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
             self::JSON_PROPERTY_PROVIDER => self::PROVIDER_IDENTIFIER,
@@ -175,17 +184,18 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         ], fn($v) => $v !== null);
     }
 
-    public function jsonDeserialize(array|string $data, bool $delta = false): static {
+    public function jsonDeserialize(array|string $data, bool $delta = false): static
+    {
         if (is_string($data)) {
             $data = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
         }
 
-        if (isset($data[self::JSON_PROPERTY_LABEL])) {
-            $this->setLabel($data[self::JSON_PROPERTY_LABEL]);
-        }
         if (isset($data[self::JSON_PROPERTY_ENABLED])) {
             $this->setEnabled($data[self::JSON_PROPERTY_ENABLED]);
         }
+        if (isset($data[self::JSON_PROPERTY_LABEL])) {
+            $this->setLabel($data[self::JSON_PROPERTY_LABEL]);
+        }
         if (isset($data[self::JSON_PROPERTY_LOCATION])) {
             $this->setLocation($this->freshLocation(null, $data[self::JSON_PROPERTY_LOCATION]));
         }
@@ -213,7 +223,8 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return isset($this->serviceAbilities[$value]);
     }
 
-	public function capabilities(): array {
+	public function capabilities(): array
+    {
 		return $this->serviceAbilities;
 	}
 
@@ -326,12 +337,12 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 
     public function getDebug(): bool
     {
-        return $this->serviceDebug;
+        return ($this->auxiliary['debug'] ?? false) === true;
     }
 
     public function setDebug(bool $debug): static
     {
-        $this->serviceDebug = $debug;
+        $this->auxiliary['debug'] = $debug;
         return $this;
     }
 
@@ -346,8 +357,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    // Collection operations
-
     public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array
     {
         $this->initialize();
@@ -382,82 +391,132 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this->mailService->collectionExtant(...$identifiers);
     }
 
-    public function collectionFetch(string|int $identifier): ?CollectionBaseInterface
+    public function collectionFetch(string|int $identifier): ?CollectionResource
     {
         $this->initialize();
         
-        $collection = $this->mailService->collectionFetch($identifier);
+        $mailbox = $this->mailService->collectionFetch($identifier);
         
-        if (is_array($collection) && isset($collection['id'])) {
+        if (!is_array($mailbox) || !isset($mailbox['id'])) {
-            $object = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+            return null;
-            $object->fromJmap($collection);
-            $collection = $object;
         }
 
+        $collection = $this->collectionFresh();
+        $collection->fromJmap($mailbox);
+
         return $collection;
     }
 
-    public function collectionFresh(): CollectionMutableInterface
+    public function collectionFresh(): CollectionResource
     {
-        return new CollectionResource(provider: $this->provider(), service: $this->identifier());
+        return new CollectionResource($this->provider(), $this->identifier());
     }
 
-    public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface
+    public function collectionCreate(CollectionIdentifier|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface
     {
         $this->initialize();
 
-        if ($collection instanceof CollectionResource === false) {
+        if ($properties instanceof CollectionProperties === false) {
-            $object = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+            $native = new CollectionProperties([]);
-            $object->jsonDeserialize($collection->jsonSerialize());
+            $native->jsonDeserialize($properties->jsonSerialize());
-            $collection = $object;
+        } else {
+            $native = $properties;
         }
 
-        $collection = $collection->toJmap();
+        $collection = $native->toJmap();
-        $collection = $this->mailService->collectionCreate($location, $collection, $options);
+        $collection = $this->mailService->collectionCreate($target?->collection(), $collection, $options);
 
-        $object = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+        $object = $this->collectionFresh();
         $object->fromJmap($collection);
 
         return $object;
     }
 
-    public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface
+    public function collectionUpdate(CollectionIdentifier $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface
     {
         $this->initialize();
 
-        if ($collection instanceof CollectionResource === false) {
+        if ($properties instanceof CollectionProperties === false) {
-            $object = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+            $native = new CollectionProperties([]);
-            $object->jsonDeserialize($collection->jsonSerialize());
+            $native->jsonDeserialize($properties->jsonSerialize());
-            $collection = $object;
+        } else {
+            $native = $properties;
         }
 
-        $collection = $collection->toJmap();
+        $collection = $native->toJmap();
-        $collection = $this->mailService->collectionModify($identifier, $collection);
+        $collection = $this->mailService->collectionModify($target->collection(), $collection);
 
-        $object = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+        $object = $this->collectionFresh();
         $object->fromJmap($collection);
 
         return $object;
     }
 
-    public function collectionDelete(string|int $identifier, bool $force = false, bool $recursive = false): bool
+    public function collectionDelete(CollectionIdentifier $target, bool $force = false): CollectionBaseInterface | true
     {
         $this->initialize();
 
-        return $this->mailService->collectionDestroy($identifier, $force, $recursive) !== null;
+        $deleteMode = $this->auxiliary['deleteMode'] ?? 'soft';
+        $deleteTarget = $this->auxiliary['deleteTarget'] ?? null;
+
+        if ($deleteMode !== 'soft' && $deleteMode !== 'hard') {
+            throw new \InvalidArgumentException("Invalid delete mode: $deleteMode");
+        }
+
+        // Move to target collection (e.g. Trash) instead of deleting
+        if ($deleteMode === 'soft' && $deleteTarget !== null) {
+            return $this->collectionMove(new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget), $target);
+        }
+
+        if ($deleteMode === 'soft' && $deleteTarget === null) {
+            $filter = $this->collectionListFilter();
+            $filter->condition('role', CollectionRoles::Trash->value);
+
+            $mailboxes = iterator_to_array($this->mailService->collectionList(null, $filter, null));
+            if (empty($mailboxes)) {
+                throw new \RuntimeException('No Trash collection configured or found for deletion');
+            }
+            
+            $deleteTarget = key($mailboxes);
+        }
+
+        // we need to determine if the folder being deleted is already in the trash
+        if (str_starts_with((string) $target->collection(), (string) $deleteTarget)) {
+            // if so, we should hard delete instead of moving to avoid duplicates in the trash
+            $deleteMode = 'hard';
+        }
+
+        $result = match ($deleteMode) {
+            'soft' => $this->collectionMove(new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget), $target),
+            'hard' => $this->mailService->collectionDestroy($target->collection(), $force),
+        };
+        return $result;
     }
 
-    public function collectionMove(string|int $identifier, string|int|null $targetLocation): CollectionBaseInterface
+    public function collectionMove(CollectionIdentifier $target, CollectionIdentifier $source): CollectionBaseInterface
     {
-        // TODO: Implement collection move
         $this->initialize();
-        $collection = new CollectionResource(provider: $this->provider(), service: $this->identifier());
+
+        $sourceMailbox = $this->mailService->collectionFetch((string) $source->collection());
+        $targetMailbox = $this->mailService->collectionFetch((string) $target->collection());
+        if ($sourceMailbox === null) {
+             throw new \RuntimeException('Source collection not found for move operation');
+        }
+        if ($targetMailbox === null) {
+            throw new \RuntimeException('Target collection not found for move operation');
+        }
+
+        $mutation['parentId'] = $targetMailbox['id'];
+        $mutation = $this->mailService->collectionModify($sourceMailbox['id'], $mutation);
+        $mutation = array_merge($sourceMailbox, $mutation);
+
+        $collection = $this->collectionFresh();
+        $collection->fromJmap($mutation);
+
         return $collection;
     }
 
-    // Entity operations
+    public function entityListBulk(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array
-
-    public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array
     {
         $this->initialize();
         
@@ -466,9 +525,9 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         $list = [];
         foreach ($result['list'] as $index => $entry) {
             if (is_array($entry) && isset($entry['id'])) {
-                $object = new EntityResource(provider: $this->provider(), service: $this->identifier());
+                $object = $this->entityFresh();
                 $object->fromJmap($entry);
-                $list[$object->identifier()] = $object;
+                $list[$object->urn()] = $object;
             }
             unset($result['list'][$index]);
         }
@@ -478,17 +537,8 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 
     public function entityListStream(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator
     {
-        $this->initialize();
+        foreach ($this->entityListBulk($collection, $filter, $sort, $range, $properties) as $urn => $entity) {
-        
+            yield $urn => $entity;
-        $result = $this->mailService->entityList($collection, $filter, $sort, $range, $properties);
-
-        foreach ($result['list'] as $index => $entry) {
-            if (is_array($entry) && isset($entry['id'])) {
-                $object = new EntityResource(provider: $this->provider(), service: $this->identifier());
-                $object->fromJmap($entry);
-                yield $object;
-            }
-            unset($result['list'][$index]);
         }
     }
 
@@ -507,6 +557,45 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return new Range();
     }
 
+    public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array
+    {
+        $this->initialize();
+
+        $ids = [];
+        foreach ($identifiers as $identifier) {
+            $ids[] = $identifier->entity();
+        }
+
+        $entities = $this->mailService->entityFetch(...$ids);
+        
+        $list = [];
+        foreach ($entities as $entity) {
+            if (is_array($entity) && isset($entity['id'])) {
+                $object = $this->entityFresh();
+                $object->fromJmap($entity);
+                $list[$object->urn()] = $object;
+            }
+        }
+
+        return $list;
+    }
+
+    public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator
+    {
+        foreach ($this->entityFetchBulk(...$identifiers) as $urn => $entity) {
+            yield $urn => $entity;
+        }
+    }
+
+    public function entityDownload(EntityIdentifierInterface $target, array|null $part): BinaryResource
+    {
+        $this->initialize();
+
+        $blobId = isset($part['blobId']) ? (string) $part['blobId'] : null;
+
+        return $this->mailService->entityDownload($target->entity(), $blobId);
+    }
+
     public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta
     {
         $this->initialize();
@@ -521,53 +610,159 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this->mailService->entityExtant(...$identifiers);
     }
 
-    public function entityFetch(string|int $collection, string|int ...$identifiers): array
+    public function entityFresh(): EntityResource
     {
-        $this->initialize();
+        return new EntityResource($this->provider(), $this->identifier());
-
-        $entities = $this->mailService->entityFetch(...$identifiers);
-        
-        foreach ($entities as &$entity) {
-            if (is_array($entity) && isset($entity['id'])) {
-                $object = new EntityResource(provider: $this->provider(), service: $this->identifier());
-                $object->fromJmap($entity);
-                $entity = $object;
-            }
-        }
-
-        return $entities;
     }
 
-    public function entityDelete(EntityIdentifier ...$identifiers): array
+    public function entityCreate(CollectionIdentifier $target, MessagePropertiesMutableInterface $properties, array $options = []): EntityResource
+    {
+        // TODO: Implement entity create
+        return $this->entityFresh();
+    }
+
+    public function entityModify(EntityIdentifier $identifier, MessagePropertiesMutableInterface $properties): EntityResource
+    {
+        // TODO: Implement entity modify
+        return $this->entityFresh();
+    }
+
+    public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
     {
         // validate identifiers and construct ID list
-        $ids = [];
+        $targets = $this->mapEntities(...$targets);
-        foreach ($identifiers as $identifier) {
-            if ($identifier->provider() !== $this->provider() || $identifier->service() !== (string)$this->identifier()) {
-                throw new \InvalidArgumentException('Entity identifier does not belong to this service: ' . (string)$identifier);
-            }
-            $ids[] = $identifier->entity();
-        }
 
+        // move entities on remote store and construct result map
         $this->initialize();
 
-        $deleteMode = strtolower(trim((string) ($this->getAuxiliary()['deleteMode'] ?? 'soft')));
+        $patch = $this->mailService->entityFresh();
-        if ($deleteMode === 'soft') {
+        $flags = $properties->getFlags();
-            $filter = $this->collectionListFilter();
+        foreach ($flags as $flag => $value) {
-            $filter->condition('role', 'trash');
+			$patch->keyword($flag, $value);
-            $targets = $this->collectionList(null, $filter);
+		}
 
-            if (empty($targets)) {
+        $dispositions = $this->mailService->entityPatch($patch, ...array_keys($targets));
-                throw new \RuntimeException('No trash collection found for soft delete');
+
+        $list = [];
+        foreach ($targets as $target) {
+            $entityId = $target->entity();
+            // if the source entity ID is not in the dispositions, it means an unknown error occurred during the move operation for that entity
+            if (!isset($dispositions[$entityId])) {
+                $list[(string)$target] = [
+                    'disposition' => 'error',
+                    'error' => 'Unknown error occurred during move operation',
+                ];
+                continue;
+            }
+            // if the disposition for the entity ID is not true, it means the move operation failed for that entity with a known error
+            if ($dispositions[$entityId] !== true) {
+                $list[(string)$target] = [
+                    'disposition' => 'error',
+                    'error' => $dispositions[$entityId] ?? 'Unknown error occurred during move operation',
+                ];
+                continue;
             }
 
-            return $this->mailService->entityMove(reset($targets)->identifier(), ...$ids);
+            $list[(string)$target] = [
+                'disposition' => 'patched'
+            ];
+            unset($targets[$entityId]);
         }
 
-        return $this->mailService->entityDelete(...$ids);
+        return $list;
     }
 
-    public function entityMove(CollectionIdentifier $target, EntityIdentifier ...$identifiers): array
+    public function entityDelete(EntityIdentifier ...$targets): array
+    {
+        // validate identifiers and construct ID list
+        $targets = $this->mapEntities(...$targets);
+
+        // determine delete mode and target collection (e.g. Trash) if applicable
+        $deleteMode = $this->auxiliary['deleteMode'] ?? 'soft';
+        $deleteTarget = $this->auxiliary['deleteTarget'] ?? null;
+        
+        if ($deleteMode !== 'soft' && $deleteMode !== 'hard') {
+            throw new \InvalidArgumentException("Invalid delete mode: $deleteMode");
+        }
+        
+        // connect to remote store
+        $this->initialize();
+
+        // attempt to find a target collection for soft deletion if none was specified
+        if ($deleteMode === 'soft' && $deleteTarget === null) {
+            $filter = $this->collectionListFilter();
+            $filter->condition('role', CollectionRoles::Trash->value);
+
+            $mailboxes = iterator_to_array($this->mailService->collectionList(null, $filter, null));
+            if (empty($mailboxes)) {
+                throw new \RuntimeException('No Trash collection configured or found for deletion');
+            }
+
+            $targetMailbox = reset($mailboxes);
+            if ($targetMailbox === false) {
+                throw new \RuntimeException('No Trash collection configured or found for deletion');
+            }
+
+            $deleteTargetNative = $targetMailbox->id();
+            $deleteTargetIdentifier = new CollectionIdentifier($this->provider(), (string) $this->identifier(), $deleteTargetNative);
+        } else {
+            $deleteTargetNative = $deleteTarget;
+            $deleteTargetIdentifier = new CollectionIdentifier($this->provider(), (string) $this->identifier(), $deleteTargetNative);
+        }
+
+        // if all targets are already in the delete target collection, we should hard delete instead of moving to avoid duplicates in the trash
+        $targetCollections = [];
+        foreach ($targets as $target) {
+            $targetCollections[$target->collection()] = true;
+        }
+        if (array_keys($targetCollections) === [$deleteTargetNative]) {
+            $deleteMode = 'hard';
+        }
+
+        // move or delete target entities on remote store and construct result map
+        $dispositions = match ($deleteMode) {
+            'soft' => $this->mailService->entityMove($deleteTargetNative, ...array_keys($targets)),
+            'hard' => $this->mailService->entityDelete(...array_keys($targets)),
+        };
+
+        $list = [];
+        foreach ($targets as $target) {
+            $entityId = $target->entity();
+            // if the source entity ID is not in the dispositions, it means an unknown error occurred during the move operation for that entity
+            if (!isset($dispositions[$entityId])) {
+                $list[(string)$target] = [
+                    'disposition' => 'error',
+                    'error' => 'Unknown error occurred during move operation',
+                ];
+                continue;
+            }
+            // if the disposition for the entity ID is not true, it means the move operation failed for that entity with a known error
+            if ($dispositions[$entityId] !== true) {
+                $list[(string)$target] = [
+                    'disposition' => 'error',
+                    'error' => $dispositions[$entityId] ?? 'Unknown error occurred during move operation',
+                ];
+                continue;
+            }
+            
+            if ($deleteMode === 'soft') {
+                $list[(string)$target] = [
+                    'disposition' => 'moved',
+                    'destination' => $deleteTargetIdentifier,
+                    'mutation' => new EntityIdentifier($this->provider(), $this->identifier(), $target->collection(), $entityId),
+                ];
+            } else {
+                $list[(string)$target] = [
+                    'disposition' => 'deleted',
+                ];
+            }
+            unset($targets[$entityId]);
+        }
+
+        return $list;
+    }
+
+    public function entityMove(CollectionIdentifier $target, EntityIdentifier ...$sources): array
     {
         // validate target belongs to this service
         if ($target->provider() !== $this->provider() || $target->service() !== (string)$this->identifier()) {
@@ -575,16 +770,59 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         }
 
         // validate identifiers and construct ID list
-        $ids = [];
+        $sources = $this->mapEntities(...$sources);
+
+        // move entities on remote store and construct result map
+        $this->initialize();
+
+        $dispositions = $this->mailService->entityMove($target->collection(), ...array_keys($sources));
+
+        $list = [];
+        foreach ($sources as $source) {
+            $entityId = $source->entity();
+            // if the source entity ID is not in the dispositions, it means an unknown error occurred during the move operation for that entity
+            if (!isset($dispositions[$entityId])) {
+                $list[(string)$source] = [
+                    'disposition' => 'error',
+                    'error' => 'Unknown error occurred during move operation',
+                ];
+                continue;
+            }
+            // if the disposition for the entity ID is not true, it means the move operation failed for that entity with a known error
+            if ($dispositions[$entityId] !== true) {
+                $list[(string)$source] = [
+                    'disposition' => 'error',
+                    'error' => $dispositions[$entityId] ?? 'Unknown error occurred during move operation',
+                ];
+                continue;
+            }
+
+            $list[(string)$source] = [
+                'disposition' => 'moved',
+                'destination' => $target,
+                'mutation' => new EntityIdentifier($this->provider(), $this->identifier(), $target->collection(), $entityId),
+            ];
+            unset($sources[$entityId]);
+        }
+
+        return $list;
+    }
+
+    public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$sources): array
+    {
+        // TODO: Implement entity copy
+        return [];
+    }
+
+    private function mapEntities(EntityIdentifier ...$identifiers): array
+    {
+        $list = [];
         foreach ($identifiers as $identifier) {
             if ($identifier->provider() !== $this->provider() || $identifier->service() !== (string)$this->identifier()) {
                 throw new \InvalidArgumentException('Entity identifier does not belong to this service: ' . (string)$identifier);
             }
-            $ids[] = $identifier->entity();
+            $list[$identifier->entity()] = $identifier;
         }
-
+        return $list;
-        $this->initialize();
-
-        return $this->mailService->entityMove($target->collection(), ...$ids);
     }
 }

lib/Service/Remote/RemoteMailService.php

@@ -11,8 +11,6 @@ namespace KTXM\ProviderJmapc\Service\Remote;
 
 use Exception;
 use JmapClient\Client;
-use JmapClient\Requests\Blob\BlobGet;
-use JmapClient\Requests\Blob\BlobSet;
 use JmapClient\Requests\Mail\MailboxGet;
 use JmapClient\Requests\Mail\MailboxParameters as MailboxParametersRequest;
 use JmapClient\Requests\Mail\MailboxQuery;
@@ -25,17 +23,16 @@ use JmapClient\Requests\Mail\MailQuery;
 use JmapClient\Requests\Mail\MailQueryChanges;
 use JmapClient\Requests\Mail\MailSet;
 use JmapClient\Requests\Mail\MailSubmissionSet;
-use JmapClient\Requests\RequestBundle;
 use JmapClient\Responses\Mail\MailboxParameters as MailboxParametersResponse;
+use JmapClient\Responses\Mail\MailPart;
 use JmapClient\Responses\Mail\MailParameters as MailParametersResponse;
 use JmapClient\Responses\ResponseException;
+use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Delta\Delta;
 use KTXF\Resource\Delta\DeltaCollection;
 use KTXF\Resource\Filter\Filter;
 use KTXF\Resource\Filter\IFilter;
 use KTXF\Resource\Range\IRange;
-use KTXF\Resource\Range\IRangeTally;
-use KTXF\Resource\Range\Range;
 use KTXF\Resource\Range\RangeAnchorType;
 use KTXF\Resource\Range\RangeTally;
 use KTXF\Resource\Sort\ISort;
@@ -496,6 +493,103 @@ class RemoteMailService {
 		return new RangeTally();
 	}
 
+	/**
+	 * retrieve entity from remote storage
+	 *
+	 * @since Release 1.0.0
+	 */
+	public function entityFetch(string ...$identifiers): ?array {
+		// construct request
+		$r0 = new MailGet($this->dataAccount, null, $this->resourceNamespace, $this->resourceEntityLabel);
+		$r0->target(...$identifiers);
+		// select properties to return
+		$r0->property(...$this->defaultMailProperties);
+		$r0->bodyAll(true);
+		// transceive
+		$bundle = $this->dataStore->perform([$r0]);
+		// extract response
+		$response = $bundle->response(0);
+		// convert json objects to message objects
+		$list = [];
+		foreach ($response->objects() as $so) {
+			if (!$so instanceof MailParametersResponse) {
+				continue;
+			}
+			$id = $so->id();
+			$list[$id] = $so->parametersRaw();
+			$list[$id]['signature'] = $response->state();
+		}
+		// return message collection
+		return $list;
+	}
+
+	public function entityDownload(string $identifier, string|null $blobId = null): BinaryResource {
+
+		// construct request
+		$r0 = new MailGet($this->dataAccount, null, $this->resourceNamespace, $this->resourceEntityLabel);
+		$r0->target($identifier);
+		// select properties to return
+		$r0->property(...['id', 'blobId', 'bodyStructure']);
+		// transceive
+		$bundle = $this->dataStore->perform([$r0]);
+		// extract response
+		$response = $bundle->response(0);
+
+		$parameters = $response->object(0);
+		if (!$parameters instanceof MailParametersResponse) {
+			throw new Exception('Unexpected response type received from server.', 1);
+		}
+
+		if ($blobId === null) {
+			$blobId = $parameters->blob();
+			$filename = 'message.eml';
+			$mimeType = 'text/plain';
+		} else {
+			$walk = function (?MailPart $part) use (&$walk, $blobId): ?MailPart {
+				if ($part === null) {
+					return null;
+				}
+
+				if ($part->blob() === $blobId) {
+					return $part;
+				}
+
+				foreach ($part->parts() ?? [] as $subPart) {
+					$subPartResult = $walk($subPart);
+					if ($subPartResult !== null) {
+						return $subPartResult;
+					}
+				}
+
+				return null;
+			};
+
+			$part = $walk($parameters->bodyPartStructure());
+			$filename = $part->name() ?? 'file.bin';
+			$mimeType = $part->type() ?? 'application/octet-stream';
+		}
+
+		$streamResource = $this->dataStore->downloadStream($this->dataAccount, $blobId, $mimeType, $filename);
+
+		$stream = (function () use ($streamResource): \Generator {
+			try {
+				while (!$streamResource->eof()) {
+					$chunk = $streamResource->read(8192);
+					if ($chunk === '' && !$streamResource->eof()) {
+						throw new Exception('Unable to read from download stream.', 1);
+					}
+					if ($chunk !== '') {
+						yield $chunk;
+					}
+				}
+			} finally {
+				$streamResource->close();
+			}
+		})();
+
+		return new BinaryResource($filename, $mimeType, $stream);
+	}
+
 	/**
 	 * check existence of entities in remote storage
 	 *
@@ -624,34 +718,8 @@ class RemoteMailService {
 		return $delta;
 	}
 
-	/**
+	public function entityFresh(): MailParametersRequest {
-	 * retrieve entity from remote storage
+		return new MailParametersRequest();
-	 *
-	 * @since Release 1.0.0
-	 */
-	public function entityFetch(string ...$identifiers): ?array {
-		// construct request
-		$r0 = new MailGet($this->dataAccount, null, $this->resourceNamespace, $this->resourceEntityLabel);
-		$r0->target(...$identifiers);
-		// select properties to return
-		$r0->property(...$this->defaultMailProperties);
-		$r0->bodyAll(true);
-		// transceive
-		$bundle = $this->dataStore->perform([$r0]);
-		// extract response
-		$response = $bundle->response(0);
-		// convert json objects to message objects
-		$list = [];
-		foreach ($response->objects() as $so) {
-			if (!$so instanceof MailParametersResponse) {
-				continue;
-			}
-			$id = $so->id();
-			$list[$id] = $so->parametersRaw();
-			$list[$id]['signature'] = $response->state();
-		}
-		// return message collection
-		return $list;
 	}
 
 	/**
@@ -724,6 +792,37 @@ class RemoteMailService {
 		return null;
 	}
 
+	public function entityPatch(MailParametersRequest $properties, string ...$identifiers): ?array {
+		// construct request
+		$r0 = new MailSet($this->dataAccount);
+		foreach ($identifiers as $id) {
+			$r0->patch($id, $properties);
+		}
+		// transceive
+		$bundle = $this->dataStore->perform([$r0]);
+		// extract response
+		$response = $bundle->first();
+		// check for command error
+		if ($response instanceof ResponseException) {
+			if ($response->type() === 'unknownMethod') {
+				throw new JmapUnknownMethod($response->description(), 1);
+			} else {
+				throw new Exception($response->type() . ': ' . $response->description(), 1);
+			}
+		}
+		$results = [];
+		// check for success
+		foreach ($response->updateSuccesses() as $id => $data) {
+			$results[$id] = true;
+		}
+		// check for failure
+		foreach ($response->updateFailures() as $id => $data) {
+			$results[$id] = $data['type'] ?? 'unknownError';
+		}
+
+		return $results;
+	}
+
 	/**
 	 * delete entities from remote storage
 	 *
@@ -761,16 +860,6 @@ class RemoteMailService {
 		return $results;
 	}
 
-	/**
-	 * copy entity in remote storage
-	 *
-	 * @since Release 1.0.0
-	 *
-	 */
-	public function entityCopy(string $target, string ...$identifiers): array {
-		return [];
-	}
-
 	/**
 	 * move entity in remote storage
 	 *
@@ -808,6 +897,16 @@ class RemoteMailService {
 		return $results;
 	}
 
+	/**
+	 * copy entity in remote storage
+	 *
+	 * @since Release 1.0.0
+	 *
+	 */
+	public function entityCopy(string $target, string ...$identifiers): array {
+		return [];
+	}
+
 	/**
 	 * send entity
 	 *