<?php

declare(strict_types=1);

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

namespace KTXM\DocumentsManager\Controllers;

use InvalidArgumentException;
use KTXC\Http\Response\JsonResponse;
use KTXC\SessionIdentity;
use KTXC\SessionTenant;
use KTXF\Controller\ControllerAbstract;
use KTXF\Resource\Selector\SourceSelector;
use KTXF\Routing\Attributes\AuthenticatedRoute;
use KTXM\DocumentsManager\Manager;
use Psr\Log\LoggerInterface;
use Throwable;

class DefaultController extends ControllerAbstract {

	private const ERR_MISSING_PROVIDER = 'Missing parameter: provider';
    private const ERR_MISSING_IDENTIFIER = 'Missing parameter: identifier';
    private const ERR_MISSING_SERVICE = 'Missing parameter: service';
    private const ERR_MISSING_COLLECTION = 'Missing parameter: collection';
    private const ERR_MISSING_DATA = 'Missing parameter: data';
    private const ERR_MISSING_SOURCES = 'Missing parameter: sources';
    private const ERR_MISSING_IDENTIFIERS = 'Missing parameter: identifiers';
    private const ERR_INVALID_OPERATION = 'Invalid operation: ';
    private const ERR_INVALID_PROVIDER = 'Invalid parameter: provider must be a string';
    private const ERR_INVALID_SERVICE = 'Invalid parameter: service must be a string';
    private const ERR_INVALID_IDENTIFIER = 'Invalid parameter: identifier must be a string';
    private const ERR_INVALID_COLLECTION = 'Invalid parameter: collection must be a string or integer';
    private const ERR_INVALID_SOURCES = 'Invalid parameter: sources must be an array';
    private const ERR_INVALID_IDENTIFIERS = 'Invalid parameter: identifiers must be an array';
    private const ERR_INVALID_DATA = 'Invalid parameter: data must be an array';

    public function __construct(
        private readonly SessionTenant $tenantIdentity,
        private readonly SessionIdentity $userIdentity,
        private readonly Manager $manager,
        private readonly LoggerInterface $logger
    ) {}
    
    #[AuthenticatedRoute('/v1', name: 'documents.manager.v1', methods: ['POST'])]
    public function index(
        int $version,
        string $transaction,
        string|null $operation = null,
        array|null $data = null,
        string|null $user = null
    ): JsonResponse {

        // authorize request
        $tenantId = $this->tenantIdentity->identifier();
        $userId = $this->userIdentity->identifier();

        try {
            
            if ($operation !== null) {
                $result = $this->process($tenantId, $userId, $operation, $data ?? [], []);
                return new JsonResponse([
                    'version' => $version,
                    'transaction' => $transaction,
                    'operation' => $operation,
                    'status' => 'success',
                    'data' => $result
                ], JsonResponse::HTTP_OK);
            }
            
            throw new InvalidArgumentException('Operation must be provided');
            
        } catch (Throwable $t) {
            $this->logger->error('Error processing request', ['exception' => $t]);
            return new JsonResponse([
                'version' => $version,
                'transaction' => $transaction,
                'operation' => $operation,
                'status' => 'error',
                'data' => [
                    'code' => $t->getCode(),
                    'message' => $t->getMessage()
                ]
            ], JsonResponse::HTTP_INTERNAL_SERVER_ERROR);
        }
    }

    /**
     * Process a single operation
     */
    private function process(string $tenantId, string $userId, string $operation, array $data): mixed {
        return match ($operation) {
            // Provider operations
            'provider.list' => $this->providerList($tenantId, $userId, $data),
            'provider.fetch' => $this->providerFetch($tenantId, $userId, $data),
            'provider.extant' => $this->providerExtant($tenantId, $userId, $data),

            // Service operations
            'service.list' => $this->serviceList($tenantId, $userId, $data),
            'service.extant' => $this->serviceExtant($tenantId, $userId, $data),
            'service.fetch' => $this->serviceFetch($tenantId, $userId, $data),
            'service.create' => $this->serviceCreate($tenantId, $userId, $data),
            'service.update' => $this->serviceUpdate($tenantId, $userId, $data),
            'service.delete' => $this->serviceDelete($tenantId, $userId, $data),
            'service.test' => $this->serviceTest($tenantId, $userId, $data),

            // Collection operations
            'collection.list' => $this->collectionList($tenantId, $userId, $data),
            'collection.extant' => $this->collectionExtant($tenantId, $userId, $data),
            'collection.fetch' => $this->collectionFetch($tenantId, $userId, $data),
            'collection.create' => $this->collectionCreate($tenantId, $userId, $data),
            'collection.update' => $this->collectionUpdate($tenantId, $userId, $data),
            'collection.delete' => $this->collectionDelete($tenantId, $userId, $data),
            'collection.copy' => $this->collectionCopy($tenantId, $userId, $data),
            'collection.move' => $this->collectionMove($tenantId, $userId, $data),

            // Entity operations
            'entity.list' => $this->entityList($tenantId, $userId, $data),
            'entity.delta' => $this->entityDelta($tenantId, $userId, $data),
            'entity.extant' => $this->entityExtant($tenantId, $userId, $data),
            'entity.fetch' => $this->entityFetch($tenantId, $userId, $data),
            'entity.create' => $this->entityCreate($tenantId, $userId, $data),
            'entity.update' => $this->entityUpdate($tenantId, $userId, $data),
            'entity.delete' => $this->entityDelete($tenantId, $userId, $data),
            'entity.copy' => $this->entityCopy($tenantId, $userId, $data),
            'entity.move' => $this->entityMove($tenantId, $userId, $data),
            'entity.read' => $this->entityRead($tenantId, $userId, $data),
            'entity.read.chunk' => $this->entityReadChunk($tenantId, $userId, $data),
            'entity.write' => $this->entityWrite($tenantId, $userId, $data),
            'entity.write.chunk' => $this->entityWriteChunk($tenantId, $userId, $data),
            
            // Node operations (unified recursive)
            'node.list' => $this->nodeList($tenantId, $userId, $data),
            'node.delta' => $this->nodeDelta($tenantId, $userId, $data),
            default => throw new InvalidArgumentException('Unknown operation: ' . $operation)
        };

    }

    // ==================== Provider Operations ====================

    private function providerList(string $tenantId, string $userId, array $data): mixed {

        $sources = null;
		if (isset($data['sources']) && is_array($data['sources'])) {
			$sources = new SourceSelector();
			$sources->jsonDeserialize($data['sources']);
		}
		
		return $this->manager->providerList($tenantId, $userId, $sources);

    }

    private function providerFetch(string $tenantId, string $userId, array $data): mixed {
        
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        
        return $this->manager->providerFetch($tenantId, $userId, $data['identifier']);
    }

    private function providerExtant(string $tenantId, string $userId, array $data): mixed {
        
        if (!isset($data['sources'])) {
			throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
		}
		if (!is_array($data['sources'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);	
		}
		$sources = new SourceSelector();
		$sources->jsonDeserialize($data['sources']);
		
		return $this->manager->providerExtant($tenantId, $userId, $sources);

    }

    // ==================== Service Operations =====================

    private function serviceList(string $tenantId, string $userId, array $data): mixed {

        $sources = null;
        if (isset($data['sources']) && is_array($data['sources'])) {
            $sources = new SourceSelector();
            $sources->jsonDeserialize($data['sources']);
        }

        return $this->manager->serviceList($tenantId, $userId, $sources);
    }

    private function serviceFetch(string $tenantId, string $userId, array $data): mixed {

        if (!isset($data['provider'])) {
			throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
		}
		if (!is_string($data['provider'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
		}
		if (!isset($data['identifier'])) {
			throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
		}
		if (!is_string($data['identifier'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
		}
        
        return $this->manager->serviceFetch($tenantId, $userId, $data['provider'], $data['identifier']);
    }

    private function serviceExtant(string $tenantId, string $userId, array $data): mixed {
        
        if (!isset($data['sources'])) {
			throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
		}
		if (!is_array($data['sources'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
		}
		$sources = new SourceSelector();
		$sources->jsonDeserialize($data['sources']);
		
		return $this->manager->serviceExtant($tenantId, $userId, $sources);
    }

    private function serviceCreate(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['data'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }
        if (!is_array($data['data'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
        }
        
        return $this->manager->serviceCreate(
            $tenantId,
            $userId,
            $data['provider'],
            $data['data']
        );
    }

    private function serviceUpdate(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        if (!isset($data['data'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }
        if (!is_array($data['data'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
        }
        
        return $this->manager->serviceUpdate(
            $tenantId,
            $userId,
            $data['provider'],
            $data['identifier'],
            $data['data']
        );
    }

    private function serviceDelete(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        
        return $this->manager->serviceDelete(
            $tenantId,
            $userId,
            $data['provider'],
            $data['identifier']
        );
    }

    private function serviceTest(string $tenantId, string $userId, array $data): mixed {
        
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        
        if (!isset($data['identifier']) && !isset($data['location']) && !isset($data['identity'])) {
            throw new InvalidArgumentException('Either a service identifier or location and identity must be provided for service test');
        }
        
        return $this->manager->serviceTest(
            $tenantId,
            $userId,
            $data['provider'],
            $data['identifier'] ?? null,
            $data['location'] ?? null,
            $data['identity'] ?? null,
        );
    }

    // ==================== Collection Operations ====================

    private function collectionList(string $tenantId, string $userId, array $data): mixed {
        $sources = null;
        if (isset($data['sources']) && is_array($data['sources'])) {
            $sources = new SourceSelector();
            $sources->jsonDeserialize($data['sources']);
        }
        
        $filter = $data['filter'] ?? null;
        $sort = $data['sort'] ?? null;
        
        return $this->manager->collectionList($tenantId, $userId, $sources, $filter, $sort);
    }

    private function collectionExtant(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
        }
        if (!is_array($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
        }
        
        $sources = new SourceSelector();
        $sources->jsonDeserialize($data['sources']);
        
        return $this->manager->collectionExtant($tenantId, $userId, $sources);
    }

    private function collectionFetch(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier']) && !is_int($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        
        return $this->manager->collectionFetch(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['identifier']
        );
    }

    private function collectionCreate(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (isset($data['collection']) && !is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['properties'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }
        if (!is_array($data['properties'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
        }
        
        return $this->manager->collectionCreate(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['collection'] ?? null,
            $data['properties']
        );
    }

    private function collectionUpdate(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier']) && !is_int($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['properties'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }
        if (!is_array($data['properties'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
        }
        
        return $this->manager->collectionUpdate(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['identifier'],
            $data['properties']
        );
    }

    private function collectionDelete(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier']) && !is_int($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        
        return $this->manager->collectionDelete(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['identifier'],
            $data['options'] ?? []
        );
    }

    private function collectionCopy(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider']) || !is_string($data['provider'])) {
            throw new InvalidArgumentException('Missing required parameter: provider');
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException('Missing required parameter: service');
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException('Missing required parameter: identifier');
        }
        
        $location = $data['location'] ?? null;
        
        return $this->manager->collectionCopy(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $data['identifier'], 
            $location
        );
    }

    private function collectionMove(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider']) || !is_string($data['provider'])) {
            throw new InvalidArgumentException('Missing required parameter: provider');
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException('Missing required parameter: service');
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException('Missing required parameter: identifier');
        }
        
        $location = $data['location'] ?? null;
        
        return $this->manager->collectionMove(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $data['identifier'], 
            $location
        );
    }

    // ==================== Entity Operations ====================

    private function entityList(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
        }
        if (!is_array($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
        }
        
        $sources = new SourceSelector();
        $sources->jsonDeserialize($data['sources']);
        
		$filter = $data['filter'] ?? null;
		$sort = $data['sort'] ?? null;
		$range = $data['range'] ?? null;

		return $this->manager->entityList($tenantId, $userId, $sources, $filter, $sort, $range);
    }

    private function entityFetch(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_COLLECTION);
        }
        if (!is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['identifiers'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIERS);
        }
        if (!is_array($data['identifiers'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIERS);
        }
        
        return $this->manager->entityFetch(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['collection'],
            $data['identifiers']
        );
    }

    private function entityExtant(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
        }
        if (!is_array($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
        }
        
        $sources = new SourceSelector();
        $sources->jsonDeserialize($data['sources']);
        
        return $this->manager->entityExtant($tenantId, $userId, $sources);
    }

	private function entityCreate(string $tenantId, string $userId, array $data = []): mixed {

		if (!isset($data['provider']) || !is_string($data['provider'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
		}
		if (!isset($data['service']) || !is_string($data['service'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
		}
		if (!isset($data['collection'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
		}
        $properties = $data['properties'] ?? $data['data'] ?? null;
        if (!is_array($properties)) {
            throw new InvalidArgumentException('Invalid parameter: properties must be an array');
        }
		$options = $data['options'] ?? [];

        return $this->manager->entityCreate($tenantId, $userId, $data['provider'], $data['service'], $data['collection'], $properties, $options);

	}

	private function entityUpdate(string $tenantId, string $userId, array $data = []): mixed {

		if (!isset($data['provider']) || !is_string($data['provider'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
		}
		if (!isset($data['service']) || !is_string($data['service'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
		}
		if (!isset($data['collection'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
		}
		if (!isset($data['identifier'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
		}
        $properties = $data['properties'] ?? $data['data'] ?? null;
        if (!is_array($properties)) {
            throw new InvalidArgumentException('Invalid parameter: properties must be an array');
        }

        return $this->manager->entityUpdate($tenantId, $userId, $data['provider'], $data['service'], $data['collection'], $data['identifier'], $properties);

	}

	private function entityDelete(string $tenantId, string $userId, array $data = []): mixed {

		if (!isset($data['provider']) || !is_string($data['provider'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
		}
		if (!isset($data['service']) || !is_string($data['service'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
		}
		if (!isset($data['collection'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
		}
		if (!isset($data['identifier'])) {
			throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
		}

		return $this->manager->entityDelete($tenantId, $userId, $data['provider'], $data['service'], $data['collection'], $data['identifier']);

	}

    private function entityDelta(string $tenantId, string $userId, array $data): mixed {
        if (!isset($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
        }
        if (!is_array($data['sources'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
        }
        
        $sources = new SourceSelector();
        $sources->jsonDeserialize($data['sources']);
        
        return $this->manager->entityDelta($tenantId, $userId, $sources);
    }

    private function entityCopy(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider']) || !is_string($data['provider'])) {
            throw new InvalidArgumentException('Missing required parameter: provider');
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException('Missing required parameter: service');
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException('Missing required parameter: identifier');
        }
        
        $collection = $data['collection'] ?? null;
        $destination = $data['destination'] ?? null;
        
        return $this->manager->entityCopy(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $collection,
            $data['identifier'], 
            $destination
        );
    }

    private function entityMove(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider']) || !is_string($data['provider'])) {
            throw new InvalidArgumentException('Missing required parameter: provider');
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException('Missing required parameter: service');
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException('Missing required parameter: identifier');
        }
        
        $collection = $data['collection'] ?? null;
        $destination = $data['destination'] ?? null;
        
        return $this->manager->entityMove(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $collection,
            $data['identifier'], 
            $destination
        );
    }

    private function entityRead(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_COLLECTION);
        }
        if (!is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        
        $content = $this->manager->entityRead(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $data['collection'],
            $data['identifier']
        );
        
        return [
            'content' => $content !== null ? base64_encode($content) : null,
            'encoding' => 'base64'
        ];
    }

    private function entityWrite(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_COLLECTION);
        }
        if (!is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        if (!isset($data['content'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }
        
        // Decode content if base64 encoded
        $content = $data['content'];
        if (isset($data['encoding']) && $data['encoding'] === 'base64') {
            $content = base64_decode($content);
            if ($content === false) {
                throw new InvalidArgumentException('Invalid base64 encoded content');
            }
        }
        
        $bytesWritten = $this->manager->entityWrite(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $data['collection'],
            $data['identifier'],
            $content
        );
        
        return [
            'bytesWritten' => $bytesWritten
        ];
    }

    private function entityReadChunk(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_COLLECTION);
        }
        if (!is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        if (!isset($data['offset']) || !is_int($data['offset'])) {
            throw new InvalidArgumentException('Missing parameter: offset');
        }
        if (!isset($data['length']) || !is_int($data['length'])) {
            throw new InvalidArgumentException('Missing parameter: length');
        }

        $chunk = $this->manager->entityReadChunk(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['collection'],
            $data['identifier'],
            $data['offset'],
            $data['length']
        );

        return [
            'content' => $chunk !== null ? base64_encode($chunk) : null,
            'encoding' => 'base64',
            'offset' => $data['offset'],
            'length' => $chunk !== null ? strlen($chunk) : 0,
        ];
    }

    private function entityWriteChunk(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }
        if (!isset($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_COLLECTION);
        }
        if (!is_string($data['collection']) && !is_int($data['collection'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_COLLECTION);
        }
        if (!isset($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
        }
        if (!is_string($data['identifier'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
        }
        if (!isset($data['offset']) || !is_int($data['offset'])) {
            throw new InvalidArgumentException('Missing parameter: offset');
        }
        if (!isset($data['content'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
        }

        // Decode content if base64 encoded
        $content = $data['content'];
        if (isset($data['encoding']) && $data['encoding'] === 'base64') {
            $content = base64_decode($content);
            if ($content === false) {
                throw new InvalidArgumentException('Invalid base64 encoded content');
            }
        }

        $bytesWritten = $this->manager->entityWriteChunk(
            $tenantId,
            $userId,
            $data['provider'],
            $data['service'],
            $data['collection'],
            $data['identifier'],
            $data['offset'],
            $content
        );

        return [
            'bytesWritten' => $bytesWritten,
            'offset' => $data['offset'],
        ];
    }

    // ==================== Node Operations (Unified/Recursive) ====================

    private function nodeList(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
        }
        if (!is_string($data['provider'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
        }
        if (!is_string($data['service'])) {
            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
        }

        $provider = $data['provider'];
        $service = $data['service'];
        $collection = $data['collection'] ?? null;
        $recursive = $data['recursive'] ?? false;
        $filter = $data['filter'] ?? null;
        $sort = $data['sort'] ?? null;
        $range = $data['range'] ?? null;
        
        return $this->manager->nodeList(
            $tenantId, 
            $userId,
            $provider,
            $service,
            $collection, 
            $recursive,
            $filter, 
            $sort, 
            $range
        );
    }

    private function nodeDelta(string $tenantId, string $userId, array $data = []): mixed {
        if (!isset($data['provider']) || !is_string($data['provider'])) {
            throw new InvalidArgumentException('Missing required parameter: provider');
        }
        if (!isset($data['service'])) {
            throw new InvalidArgumentException('Missing required parameter: service');
        }
        if (!isset($data['signature']) || !is_string($data['signature'])) {
            throw new InvalidArgumentException('Missing required parameter: signature');
        }
        
        $location = $data['location'] ?? null;
        $recursive = $data['recursive'] ?? false;
        $detail = $data['detail'] ?? 'ids';
        
        return $this->manager->nodeDelta(
            $tenantId, 
            $userId, 
            $data['provider'], 
            $data['service'], 
            $location, 
            $data['signature'],
            $recursive,
            $detail
        );
    }

}