feat: collection move

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

lib/Manager.php

@@ -671,6 +671,42 @@ class Manager {
         return $service->collectionDelete($collectionId, $force);
     }
 
+    /**
+     * Move a specific collection to a new parent collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param CollectionIdentifier $target Target collection identifier (new parent)
+     * @param CollectionIdentifier $source Source collection identifier (collection to move)
+     *
+     * @return CollectionBaseInterface Moved collection
+     */
+    public function collectionMove(string $tenantId, ?string $userId, CollectionIdentifier $target, CollectionIdentifier $source): CollectionBaseInterface {
+        // validate that source and target are the same provider and service
+        if ($source->provider() !== $target->provider() || $source->service() !== $target->service()) {
+            throw new InvalidArgumentException("Source and target collections must belong to the same provider and service");
+        }
+        // Validate that source and target are not the same
+        if ($source->collection() === $target->collection()) {
+            throw new InvalidArgumentException("Source and target collections are the same");
+        }
+        // retrieve service
+        $service = $this->serviceFetch($tenantId, $userId, $source->provider(), $source->service());
+
+        // Check if service supports collection move
+        if (!($service instanceof ServiceCollectionMutableInterface)) {
+            throw new InvalidArgumentException("Service does not support collection mutations");
+        }
+        if (!$service->capable(ServiceCollectionMutableInterface::CAPABILITY_COLLECTION_MOVE)) {
+            throw new InvalidArgumentException("Service is not capable of moving collections");
+        }
+
+        // move collection
+        return $service->collectionMove($source->collection(), $target->collection());
+    }
+
     // ==================== Message Operations ====================
 
     /**