From dfa6821fc3ea238286b2375d5996b355a1d32908 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:57:47 -0300
Subject: [PATCH 01/34] feat: add error reporting infrastructure for async
 signing

Add StatusCacheService for caching file status during async operations.
Add SignRequestErrorReporter for storing and retrieving per-file errors.
Add ErrorPayloadBuilder for consistent error payloads.

These services enable granular error tracking during background signing
jobs and provide detailed feedback to users about which specific files
failed and why.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../SignRequest/Error/ErrorPayloadBuilder.php | 96 +++++++++++++++++++
 .../Error/SignRequestErrorReporter.php        | 59 ++++++++++++
 .../SignRequest/StatusCacheService.php        | 37 +++++++
 3 files changed, 192 insertions(+)
 create mode 100644 lib/Service/SignRequest/Error/ErrorPayloadBuilder.php
 create mode 100644 lib/Service/SignRequest/Error/SignRequestErrorReporter.php
 create mode 100644 lib/Service/SignRequest/StatusCacheService.php

diff --git a/lib/Service/SignRequest/Error/ErrorPayloadBuilder.php b/lib/Service/SignRequest/Error/ErrorPayloadBuilder.php
new file mode 100644
index 0000000000..92e635d3c8
--- /dev/null
+++ b/lib/Service/SignRequest/Error/ErrorPayloadBuilder.php
@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Service\SignRequest\Error;
+
+use DateTime;
+use DateTimeInterface;
+
+class ErrorPayloadBuilder {
+	private string $message = 'An error occurred';
+	private int $code = 0;
+	private ?int $fileId = null;
+	private ?int $signRequestId = null;
+	private ?string $signRequestUuid = null;
+	/** @var array<int, array{message: string, code: int}> */
+	private array $fileErrors = [];
+
+	public static function fromException(\Throwable $e, ?int $fileId = null, ?int $signRequestId = null, ?string $signRequestUuid = null): self {
+		$builder = new self();
+		return $builder
+			->setMessage($e->getMessage())
+			->setCode($e->getCode())
+			->setFileId($fileId)
+			->setSignRequestId($signRequestId)
+			->setSignRequestUuid($signRequestUuid);
+	}
+
+	public function setMessage(string $message): self {
+		$this->message = $message;
+		return $this;
+	}
+
+	public function setCode(int $code): self {
+		$this->code = $code;
+		return $this;
+	}
+
+	public function setFileId(?int $fileId): self {
+		$this->fileId = $fileId;
+		return $this;
+	}
+
+	public function setSignRequestId(?int $signRequestId): self {
+		$this->signRequestId = $signRequestId;
+		return $this;
+	}
+
+	public function setSignRequestUuid(?string $signRequestUuid): self {
+		$this->signRequestUuid = $signRequestUuid;
+		return $this;
+	}
+
+	public function addFileError(int $fileId, \Throwable $e): self {
+		$this->fileErrors[$fileId] = [
+			'message' => $e->getMessage(),
+			'code' => $e->getCode(),
+		];
+		return $this;
+	}
+
+	public function clearFileErrors(): self {
+		$this->fileErrors = [];
+		return $this;
+	}
+
+	public function build(): array {
+		$payload = [
+			'message' => $this->message,
+			'code' => $this->code,
+			'timestamp' => (new DateTime())->format(DateTimeInterface::ATOM),
+		];
+
+		if ($this->fileId !== null) {
+			$payload['fileId'] = $this->fileId;
+		}
+
+		if ($this->signRequestId !== null) {
+			$payload['signRequestId'] = $this->signRequestId;
+		}
+
+		if ($this->signRequestUuid !== null) {
+			$payload['signRequestUuid'] = $this->signRequestUuid;
+		}
+
+		if (!empty($this->fileErrors)) {
+			$payload['fileErrors'] = $this->fileErrors;
+		}
+
+		return $payload;
+	}
+}
diff --git a/lib/Service/SignRequest/Error/SignRequestErrorReporter.php b/lib/Service/SignRequest/Error/SignRequestErrorReporter.php
new file mode 100644
index 0000000000..d7bbe8141f
--- /dev/null
+++ b/lib/Service/SignRequest/Error/SignRequestErrorReporter.php
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Service\SignRequest\Error;
+
+use OCA\Libresign\Service\SignRequest\ProgressService;
+use Psr\Log\AbstractLogger;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+
+class SignRequestErrorReporter extends AbstractLogger {
+	public function __construct(
+		private ProgressService $progressService,
+		private LoggerInterface $logger,
+	) {
+	}
+
+	#[\Override]
+	public function log($level, $message, array $context = []): void {
+		$this->maybeStoreProgressError($level, $context);
+		$this->logger->log($level, $message, $context);
+	}
+
+	private function maybeStoreProgressError(string $level, array $context): void {
+		if ($level !== LogLevel::ERROR) {
+			return;
+		}
+
+		$exception = $context['exception'] ?? null;
+		if (!$exception instanceof \Throwable) {
+			return;
+		}
+
+		$signRequestUuid = $context['signRequestUuid'] ?? null;
+		if (empty($signRequestUuid)) {
+			return;
+		}
+
+		$ttl = (int)($context['ttl'] ?? 300);
+		$fileId = $context['fileId'] ?? null;
+		$signRequestId = $context['signRequestId'] ?? null;
+		$payload = ErrorPayloadBuilder::fromException(
+			e: $exception,
+			fileId: is_numeric($fileId) ? (int)$fileId : null,
+			signRequestId: is_numeric($signRequestId) ? (int)$signRequestId : null,
+			signRequestUuid: $signRequestUuid
+		)->build();
+
+		$this->progressService->setSignRequestError($signRequestUuid, $payload, $ttl);
+		if (is_numeric($fileId)) {
+			$this->progressService->setFileError($signRequestUuid, (int)$fileId, $payload, $ttl);
+		}
+	}
+}
diff --git a/lib/Service/SignRequest/StatusCacheService.php b/lib/Service/SignRequest/StatusCacheService.php
new file mode 100644
index 0000000000..b3f72fa16f
--- /dev/null
+++ b/lib/Service/SignRequest/StatusCacheService.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Service\SignRequest;
+
+use OCP\ICache;
+use OCP\ICacheFactory;
+
+class StatusCacheService {
+	public const STATUS_KEY_PREFIX = 'libresign_status_';
+	public const DEFAULT_TTL = 60;
+
+	private ICache $cache;
+
+	public function __construct(ICacheFactory $cacheFactory) {
+		$this->cache = $cacheFactory->createDistributed('libresign_progress');
+	}
+
+	public function setStatus(string $fileUuid, int $status, int $ttl = self::DEFAULT_TTL): void {
+		if ($fileUuid === '') {
+			return;
+		}
+		$this->cache->set(self::STATUS_KEY_PREFIX . $fileUuid, $status, $ttl);
+	}
+
+	public function getStatus(string $fileUuid): mixed {
+		if ($fileUuid === '') {
+			return false;
+		}
+		return $this->cache->get(self::STATUS_KEY_PREFIX . $fileUuid);
+	}
+}

From 6f35dbb6f41de13470083b8b562b57439f93b375 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:57:55 -0300
Subject: [PATCH 02/34] feat: extend ProgressService with per-file error
 tracking

Add methods to set/get/clear errors for individual files and sign requests.
Implement long-polling with error detection across envelope children.
Add fallback to metadata when cache is not available.

This allows the frontend to display specific error messages for each
file in a multi-file signing workflow, improving user feedback.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Service/SignRequest/ProgressService.php | 367 ++++++++++++++++++--
 1 file changed, 347 insertions(+), 20 deletions(-)

diff --git a/lib/Service/SignRequest/ProgressService.php b/lib/Service/SignRequest/ProgressService.php
index cf71f3013b..055501dfdb 100644
--- a/lib/Service/SignRequest/ProgressService.php
+++ b/lib/Service/SignRequest/ProgressService.php
@@ -11,8 +11,10 @@
 use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\FileMapper;
 use OCA\Libresign\Db\SignRequest as SignRequestEntity;
+use OCA\Libresign\Db\SignRequestMapper;
 use OCA\Libresign\Enum\FileStatus;
 use OCA\Libresign\Enum\SignRequestStatus;
+use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\ICache;
 use OCP\ICacheFactory;
 
@@ -29,10 +31,18 @@
  */
 class ProgressService {
 	private ICache $cache;
+	public const ERROR_KEY_PREFIX = 'libresign_sign_request_error_';
+	public const FILE_ERROR_KEY_PREFIX = 'libresign_file_error_';
+	/** @var array<string, array<string, mixed>> */
+	private array $signRequestErrors = [];
+	/** @var array<string, array<string, mixed>> */
+	private array $fileErrors = [];
 
 	public function __construct(
 		private FileMapper $fileMapper,
 		ICacheFactory $cacheFactory,
+		private SignRequestMapper $signRequestMapper,
+		private StatusCacheService $statusCacheService,
 	) {
 		$this->cache = $cacheFactory->createDistributed('libresign_progress');
 	}
@@ -45,13 +55,62 @@ public function __construct(
 	 * @return int The current status (changed or original if timeout reached)
 	 */
 	public function pollForStatusChange(string $uuid, int $initialStatus, int $timeout = 30, int $intervalSeconds = 1): int {
-		$cacheKey = 'status_' . $uuid;
-		$cachedStatus = $this->cache->get($cacheKey);
+		return $this->pollForStatusChangeInternal($uuid, [], $initialStatus, $timeout, $intervalSeconds);
+	}
+
+	public function pollForStatusOrErrorChange(
+		FileEntity $file,
+		SignRequestEntity $signRequest,
+		int $initialStatus,
+		int $timeout = 30,
+		int $intervalSeconds = 1,
+	): int {
+		$statusUuid = $file->getUuid();
+		if ($file->getNodeType() !== 'envelope') {
+			return $this->pollForStatusChangeInternal(
+				$statusUuid,
+				[$signRequest->getUuid()],
+				$initialStatus,
+				$timeout,
+				$intervalSeconds,
+			);
+		}
+
+		$signRequestUuids = [$signRequest->getUuid()];
+		$childSignRequests = $this->signRequestMapper
+			->getByEnvelopeChildrenAndIdentifyMethod($file->getId(), $signRequest->getId());
+		foreach ($childSignRequests as $childSignRequest) {
+			$childUuid = $childSignRequest->getUuid();
+			if ($childUuid !== '') {
+				$signRequestUuids[] = $childUuid;
+			}
+		}
+
+		return $this->pollForStatusChangeInternal(
+			$statusUuid,
+			$signRequestUuids,
+			$initialStatus,
+			$timeout,
+			$intervalSeconds,
+		);
+	}
+
+	private function pollForStatusChangeInternal(
+		string $statusUuid,
+		array $errorUuids,
+		int $initialStatus,
+		int $timeout,
+		int $intervalSeconds,
+	): int {
+		$cachedStatus = $this->statusCacheService->getStatus($statusUuid);
 		$interval = max(1, $intervalSeconds);
 
 		for ($elapsed = 0; $elapsed < $timeout; $elapsed += $interval) {
-			$newCachedStatus = $this->cache->get($cacheKey);
+			if (!empty($errorUuids) && $this->hasAnySignRequestError($errorUuids)) {
+				return $initialStatus;
+			}
 
+			$newCachedStatus = $this->statusCacheService->getStatus($statusUuid);
 			if ($newCachedStatus !== $cachedStatus && $newCachedStatus !== false) {
 				return (int)$newCachedStatus;
 			}
@@ -64,6 +123,213 @@ public function pollForStatusChange(string $uuid, int $initialStatus, int $timeo
 		return $initialStatus;
 	}
 
+	public function setSignRequestError(string $uuid, array $error, int $ttl = 300): void {
+		$this->signRequestErrors[$uuid] = $error;
+		$this->cache->set(self::ERROR_KEY_PREFIX . $uuid, $error, $ttl);
+		$this->storeSignRequestErrorInMetadata($uuid, $error);
+	}
+
+
+	public function getSignRequestError(string $uuid): ?array {
+		$error = $this->cache->get(self::ERROR_KEY_PREFIX . $uuid);
+		if ($error === false || $error === null) {
+			return $this->signRequestErrors[$uuid]
+				?? $this->getSignRequestErrorFromMetadata($uuid);
+		}
+		return is_array($error) ? $error : ['message' => (string)$error];
+	}
+
+	public function clearSignRequestError(string $uuid): void {
+		unset($this->signRequestErrors[$uuid]);
+		$this->cache->remove(self::ERROR_KEY_PREFIX . $uuid);
+		$this->clearSignRequestErrorInMetadata($uuid);
+	}
+
+	private function hasSignRequestError(string $uuid): bool {
+		$error = $this->getSignRequestError($uuid);
+		return $error !== null;
+	}
+
+	private function hasAnySignRequestError(array $uuids): bool {
+		foreach ($uuids as $uuid) {
+			if ($uuid !== '' && $this->hasSignRequestError($uuid)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	public function setFileError(string $uuid, int $fileId, array $error, int $ttl = 300): void {
+		$key = $this->buildFileErrorKey($uuid, $fileId);
+		$this->fileErrors[$key] = $error;
+		$this->cache->set($key, $error, $ttl);
+		$this->storeFileErrorInMetadata($uuid, $fileId, $error);
+	}
+
+	public function getFileError(string $uuid, int $fileId): ?array {
+		$key = $this->buildFileErrorKey($uuid, $fileId);
+		$error = $this->cache->get($key);
+		if ($error === false || $error === null) {
+			return $this->fileErrors[$key]
+				?? $this->getFileErrorFromMetadata($uuid, $fileId);
+		}
+		return is_array($error) ? $error : ['message' => (string)$error];
+	}
+
+	public function clearFileError(string $uuid, int $fileId): void {
+		$key = $this->buildFileErrorKey($uuid, $fileId);
+		unset($this->fileErrors[$key]);
+		$this->cache->remove($key);
+		$this->clearFileErrorInMetadata($uuid, $fileId);
+	}
+
+	private function buildFileErrorKey(string $uuid, int $fileId): string {
+		return self::FILE_ERROR_KEY_PREFIX . $uuid . '_' . $fileId;
+	}
+
+	private function storeSignRequestErrorInMetadata(string $uuid, array $error): void {
+		if ($uuid === '') {
+			return;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		$metadata['libresign_error'] = $error;
+		$signRequest->setMetadata($metadata);
+		$this->signRequestMapper->update($signRequest);
+	}
+
+	private function getSignRequestErrorFromMetadata(string $uuid): ?array {
+		if ($uuid === '') {
+			return null;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return null;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return null;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		$error = $metadata['libresign_error'] ?? null;
+		return is_array($error) ? $error : null;
+	}
+
+	private function clearSignRequestErrorInMetadata(string $uuid): void {
+		if ($uuid === '') {
+			return;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		if (!array_key_exists('libresign_error', $metadata)) {
+			return;
+		}
+
+		unset($metadata['libresign_error']);
+		$signRequest->setMetadata($metadata);
+		$this->signRequestMapper->update($signRequest);
+	}
+
+	private function storeFileErrorInMetadata(string $uuid, int $fileId, array $error): void {
+		if ($uuid === '') {
+			return;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		$fileErrors = $metadata['libresign_file_errors'] ?? [];
+		if (!is_array($fileErrors)) {
+			$fileErrors = [];
+		}
+
+		$fileErrors[$fileId] = $error;
+		$metadata['libresign_file_errors'] = $fileErrors;
+		$signRequest->setMetadata($metadata);
+		$this->signRequestMapper->update($signRequest);
+	}
+
+	private function getFileErrorFromMetadata(string $uuid, int $fileId): ?array {
+		if ($uuid === '') {
+			return null;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return null;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return null;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		$fileErrors = $metadata['libresign_file_errors'] ?? null;
+		if (!is_array($fileErrors)) {
+			return null;
+		}
+
+		$error = $fileErrors[$fileId] ?? null;
+		return is_array($error) ? $error : null;
+	}
+
+	private function clearFileErrorInMetadata(string $uuid, int $fileId): void {
+		if ($uuid === '') {
+			return;
+		}
+
+		try {
+			$signRequest = $this->signRequestMapper->getByUuidUncached($uuid);
+		} catch (DoesNotExistException) {
+			return;
+		}
+		if (!$signRequest instanceof SignRequestEntity) {
+			return;
+		}
+
+		$metadata = $signRequest->getMetadata() ?? [];
+		$fileErrors = $metadata['libresign_file_errors'] ?? null;
+		if (!is_array($fileErrors) || !array_key_exists($fileId, $fileErrors)) {
+			return;
+		}
+
+		unset($fileErrors[$fileId]);
+		if (empty($fileErrors)) {
+			unset($metadata['libresign_file_errors']);
+		} else {
+			$metadata['libresign_file_errors'] = $fileErrors;
+		}
+		$signRequest->setMetadata($metadata);
+		$this->signRequestMapper->update($signRequest);
+	}
+
 	/**
 	 * Get progress for a specific sign request
 	 *
@@ -92,7 +358,8 @@ public function isProgressComplete(array $progress): bool {
 		$signed = (int)($progress['signed'] ?? 0);
 		$pending = (int)($progress['pending'] ?? 0);
 		$inProgress = (int)($progress['inProgress'] ?? 0);
-		return $signed >= $total && $pending <= 0 && $inProgress <= 0;
+		$errors = (int)($progress['errors'] ?? 0);
+		return ($signed + $errors) >= $total && $pending <= 0 && $inProgress <= 0;
 	}
 
 	/**
@@ -106,19 +373,25 @@ public function getSingleFileProgressForSignRequest(FileEntity $file, SignReques
 		$statusCode = $this->getSignRequestStatusCode($file, $signRequest);
 		$isSigned = $statusCode === FileStatus::SIGNED->value;
 		$isInProgress = $statusCode === FileStatus::SIGNING_IN_PROGRESS->value;
+		$fileError = $this->getFileError($signRequest->getUuid(), $file->getId());
+		$hasError = $fileError !== null;
 
 		return [
 			'total' => 1,
 			'signed' => $isSigned ? 1 : 0,
-			'inProgress' => $isInProgress ? 1 : 0,
-			'pending' => $isSigned || $isInProgress ? 0 : 1,
+			'inProgress' => $hasError ? 0 : ($isInProgress ? 1 : 0),
+			'errors' => $hasError ? 1 : 0,
+			'pending' => $hasError || $isSigned || $isInProgress ? 0 : 1,
 			'files' => [
-				[
-					'id' => $file->getId(),
-					'name' => $file->getName(),
-					'status' => $statusCode,
-					'statusText' => $this->fileMapper->getTextOfStatus($statusCode),
-				]
+				array_merge(
+					[
+						'id' => $file->getId(),
+						'name' => $file->getName(),
+						'status' => $statusCode,
+						'statusText' => $this->fileMapper->getTextOfStatus($statusCode),
+					],
+					$hasError ? ['error' => $fileError] : []
+				)
 			],
 		];
 	}
@@ -136,19 +409,28 @@ public function getEnvelopeProgressForSignRequest(FileEntity $envelope, SignRequ
 			$children = [$envelope];
 		}
 
-		$files = array_map(
-			fn ($child) => $this->mapSignRequestFileProgress($child, $signRequest),
-			$children
-		);
+		$childSignRequests = $this->signRequestMapper
+			->getByEnvelopeChildrenAndIdentifyMethod($envelope->getId(), $signRequest->getId());
+		$childSignRequestsByFileId = [];
+		foreach ($childSignRequests as $childSignRequest) {
+			$childSignRequestsByFileId[$childSignRequest->getFileId()] = $childSignRequest;
+		}
+
+		$files = array_map(function (FileEntity $child) use ($signRequest, $childSignRequestsByFileId): array {
+			$childSignRequest = $childSignRequestsByFileId[$child->getId()] ?? null;
+			return $this->mapSignRequestFileProgressWithContext($child, $signRequest, $childSignRequest);
+		}, $children);
 		$total = count($files);
 		$signed = count(array_filter($files, fn (array $file) => $file['status'] === FileStatus::SIGNED->value));
 		$inProgress = count(array_filter($files, fn (array $file) => $file['status'] === FileStatus::SIGNING_IN_PROGRESS->value));
-		$pending = max(0, $total - $signed - $inProgress);
+		$errors = count(array_filter($files, fn (array $file) => !empty($file['error'])));
+		$pending = max(0, $total - $signed - $inProgress - $errors);
 
 		return [
 			'total' => $total,
 			'signed' => $signed,
 			'inProgress' => $inProgress,
+			'errors' => $errors,
 			'pending' => $pending,
 			'files' => $files,
 		];
@@ -163,12 +445,15 @@ public function getFileProgressForSignRequest(FileEntity $file, SignRequestEntit
 		$statusCode = $this->getSignRequestStatusCode($file, $signRequest);
 		$isSigned = $statusCode === FileStatus::SIGNED->value;
 		$isInProgress = $statusCode === FileStatus::SIGNING_IN_PROGRESS->value;
+		$fileError = $this->getFileError($signRequest->getUuid(), $file->getId());
+		$hasError = $fileError !== null;
 
 		return [
 			'total' => 1,
 			'signed' => $isSigned ? 1 : 0,
-			'inProgress' => $isInProgress ? 1 : 0,
-			'pending' => $isSigned || $isInProgress ? 0 : 1,
+			'inProgress' => $hasError ? 0 : ($isInProgress ? 1 : 0),
+			'errors' => $hasError ? 1 : 0,
+			'pending' => $hasError || $isSigned || $isInProgress ? 0 : 1,
 			'signers' => [
 				[
 					'id' => $signRequest->getId(),
@@ -196,12 +481,54 @@ private function mapFileProgress(FileEntity $file): array {
 
 	private function mapSignRequestFileProgress(FileEntity $file, SignRequestEntity $signRequest): array {
 		$statusCode = $this->getSignRequestStatusCode($file, $signRequest);
-		return [
+		$error = $this->getFileError($signRequest->getUuid(), $file->getId());
+
+		$mapped = [
+			'id' => $file->getId(),
+			'name' => $file->getName(),
+			'status' => $statusCode,
+			'statusText' => $this->fileMapper->getTextOfStatus($statusCode),
+		];
+
+		if ($error !== null) {
+			$mapped['error'] = $error;
+		}
+
+		return $mapped;
+	}
+
+	private function mapSignRequestFileProgressWithContext(FileEntity $file, SignRequestEntity $defaultSignRequest, ?SignRequestEntity $childSignRequest): array {
+		$effectiveSignRequest = $childSignRequest ?? $defaultSignRequest;
+		$statusCode = $this->getSignRequestStatusCode($file, $effectiveSignRequest);
+		$errorUuid = $childSignRequest?->getUuid() ?? $defaultSignRequest->getUuid();
+		$error = $this->getFileError($errorUuid, $file->getId());
+		if ($error === null) {
+			$error = $this->findFileErrorAcrossSignRequests($file->getId());
+		}
+
+		$mapped = [
 			'id' => $file->getId(),
 			'name' => $file->getName(),
 			'status' => $statusCode,
 			'statusText' => $this->fileMapper->getTextOfStatus($statusCode),
 		];
+
+		if ($error !== null) {
+			$mapped['error'] = $error;
+		}
+
+		return $mapped;
+	}
+
+	private function findFileErrorAcrossSignRequests(int $fileId): ?array {
+		$signRequests = $this->signRequestMapper->getByFileId($fileId);
+		foreach ($signRequests as $signRequest) {
+			$error = $this->getFileError($signRequest->getUuid(), $fileId);
+			if ($error !== null) {
+				return $error;
+			}
+		}
+		return null;
 	}
 
 	private function getSignRequestStatusCode(FileEntity $file, SignRequestEntity $signRequest): int {

From 7d8bf0279e9375da6b0174631b9e86c0c0d2b401 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:03 -0300
Subject: [PATCH 03/34] refactor: inject StatusCacheService into StatusService

Replace direct cache access with StatusCacheService dependency.
Add getByEnvelopeChildrenAndIdentifyMethod to SignRequestMapper for
querying child sign requests.

This improves testability and centralizes status caching logic.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Db/SignRequestMapper.php              | 16 ++++++++++++++++
 lib/Service/SignRequest/StatusService.php |  6 ++++++
 2 files changed, 22 insertions(+)

diff --git a/lib/Db/SignRequestMapper.php b/lib/Db/SignRequestMapper.php
index 77e95c4072..678d267967 100644
--- a/lib/Db/SignRequestMapper.php
+++ b/lib/Db/SignRequestMapper.php
@@ -124,6 +124,22 @@ public function getByUuid(string $uuid): SignRequest {
 		return $signRequest;
 	}
 
+	/**
+	 * @throws DoesNotExistException
+	 */
+	public function getByUuidUncached(string $uuid): SignRequest {
+		$qb = $this->db->getQueryBuilder();
+
+		$qb->select('*')
+			->from($this->getTableName())
+			->where(
+				$qb->expr()->eq('uuid', $qb->createNamedParameter($uuid))
+			);
+
+		/** @var SignRequest */
+		return $this->findEntity($qb);
+	}
+
 	public function getByEmailAndFileId(string $email, int $fileId): SignRequest {
 		$qb = $this->db->getQueryBuilder();
 
diff --git a/lib/Service/SignRequest/StatusService.php b/lib/Service/SignRequest/StatusService.php
index 83f6239c74..01ab09e446 100644
--- a/lib/Service/SignRequest/StatusService.php
+++ b/lib/Service/SignRequest/StatusService.php
@@ -8,6 +8,7 @@
 
 namespace OCA\Libresign\Service\SignRequest;
 
+use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\SignRequest as SignRequestEntity;
 use OCA\Libresign\Enum\FileStatus;
 use OCA\Libresign\Enum\SignRequestStatus;
@@ -18,6 +19,7 @@ class StatusService {
 	public function __construct(
 		private SequentialSigningService $sequentialSigningService,
 		private FileStatusService $fileStatusService,
+		private StatusCacheService $statusCacheService,
 	) {
 	}
 
@@ -30,6 +32,10 @@ public function canNotifySignRequest(SignRequestStatus $status): bool {
 		return $status === SignRequestStatus::ABLE_TO_SIGN;
 	}
 
+	public function cacheFileStatus(FileEntity $file, int $ttl = StatusCacheService::DEFAULT_TTL): void {
+		$this->statusCacheService->setStatus($file->getUuid(), $file->getStatus(), $ttl);
+	}
+
 	public function updateStatusIfAllowed(
 		SignRequestEntity $signRequest,
 		SignRequestStatus $currentStatus,

From dd037b6005592fc070bfc7dd875b16ddffc18a88 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:09 -0300
Subject: [PATCH 04/34] feat: integrate error reporting in SignJobCoordinator

Inject ProgressService and SignRequestErrorReporter.
Clear errors before signing and report errors on exceptions.
Preserve detailed error messages with HTTP status codes.

Background jobs now store specific error information that the
frontend can retrieve and display to users.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Service/SignJobCoordinator.php | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/lib/Service/SignJobCoordinator.php b/lib/Service/SignJobCoordinator.php
index 7f0d463204..0d507007ef 100644
--- a/lib/Service/SignJobCoordinator.php
+++ b/lib/Service/SignJobCoordinator.php
@@ -15,6 +15,8 @@
 use OCA\Libresign\Db\SignRequest as SignRequestEntity;
 use OCA\Libresign\Db\SignRequestMapper;
 use OCA\Libresign\Enum\FileStatus;
+use OCA\Libresign\Service\SignRequest\Error\SignRequestErrorReporter;
+use OCA\Libresign\Service\SignRequest\ProgressService;
 use OCP\IUser;
 use OCP\IUserManager;
 use OCP\Security\ICredentialsManager;
@@ -28,11 +30,15 @@ public function __construct(
 		private FolderService $folderService,
 		private IUserManager $userManager,
 		private ICredentialsManager $credentialsManager,
+		private ProgressService $progressService,
+		private SignRequestErrorReporter $signRequestErrorReporter,
 		private LoggerInterface $logger,
 	) {
 	}
 
 	public function runSignFile(array $argument): void {
+		$file = null;
+		$signRequest = null;
 		try {
 			if (empty($argument)) {
 				throw new \InvalidArgumentException('SignFileJob: Cannot proceed with empty arguments');
@@ -40,6 +46,7 @@ public function runSignFile(array $argument): void {
 
 			[$fileId, $signRequestId] = $this->requireIds($argument, 'SignFileJob');
 			[$file, $signRequest] = $this->loadEntities($fileId, $signRequestId);
+			$this->progressService->clearSignRequestError($signRequest->getUuid());
 			$user = $this->resolveUser($argument['userId'] ?? null, null, null);
 			if ($user) {
 				$this->folderService->setUserId($user->getUID());
@@ -50,9 +57,11 @@ public function runSignFile(array $argument): void {
 
 			$this->signFileService->sign();
 		} catch (\Throwable $e) {
-			$this->logger->error('SignFileJob failed: {error}', [
-				'error' => $e->getMessage(),
+			$this->signRequestErrorReporter->error('SignFileJob failed', [
 				'exception' => $e,
+				'fileId' => $file?->getId() ?? ($argument['fileId'] ?? null),
+				'signRequestId' => $signRequest?->getId() ?? ($argument['signRequestId'] ?? null),
+				'signRequestUuid' => $signRequest?->getUuid() ?? ($argument['signRequestUuid'] ?? null),
 			]);
 		} finally {
 			$this->deleteCredentials($argument['userId'] ?? '', $argument['credentialsId'] ?? null);
@@ -73,7 +82,7 @@ public function runSignSingleFile(array $argument): void {
 
 			[$fileId, $signRequestId] = $this->requireIds($argument, 'SignSingleFileJob');
 			[$file, $signRequest] = $this->loadEntities($fileId, $signRequestId);
-
+			$this->progressService->clearSignRequestError($signRequest->getUuid());
 
 			$effectiveUserId = $effectiveUserId
 				?? $file->getUserId()
@@ -90,11 +99,11 @@ public function runSignSingleFile(array $argument): void {
 
 			$this->signFileService->signSingleFile($file, $signRequest);
 		} catch (\Throwable $e) {
-			$contextFileId = $fileId ?? ($argument['fileId'] ?? 'unknown');
-			$this->logger->error('SignSingleFileJob failed for file {fileId}: {error}', [
-				'fileId' => $contextFileId,
-				'error' => $e->getMessage(),
+			$this->signRequestErrorReporter->error('SignSingleFileJob failed for file {fileId}', [
 				'exception' => $e,
+				'fileId' => $file?->getId() ?? ($argument['fileId'] ?? null),
+				'signRequestId' => $signRequest?->getId() ?? ($argument['signRequestId'] ?? null),
+				'signRequestUuid' => $signRequest?->getUuid() ?? ($argument['signRequestUuid'] ?? null),
 			]);
 		} finally {
 			$this->deleteCredentials($argument['userId'] ?? ($effectiveUserId ?? ''), $argument['credentialsId'] ?? null);
@@ -190,4 +199,5 @@ private function deleteCredentials(string $userId, ?string $credentialsId): void
 		}
 		$this->credentialsManager->delete($userId, $credentialsId);
 	}
+
 }

From e00e899f83ff7bf7cbadad75b13416991330f935 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:18 -0300
Subject: [PATCH 05/34] refactor: inject StatusService dependency in signing
 services

Update SignFileService, AsyncSigningService, and background jobs to
inject StatusService explicitly instead of relying on internal creation.

Improves dependency injection and testability.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/BackgroundJob/SignFileJob.php       |  1 -
 lib/BackgroundJob/SignSingleFileJob.php |  1 -
 lib/Service/AsyncSigningService.php     |  1 +
 lib/Service/SignFileService.php         | 16 +++++-----------
 4 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/lib/BackgroundJob/SignFileJob.php b/lib/BackgroundJob/SignFileJob.php
index b183a0b210..39b7f6a573 100644
--- a/lib/BackgroundJob/SignFileJob.php
+++ b/lib/BackgroundJob/SignFileJob.php
@@ -28,7 +28,6 @@ public function __construct(
 	 */
 	#[\Override]
 	public function run($argument): void {
-		// Handle null arguments from Nextcloud background job system
 		$argument = is_array($argument) ? $argument : [];
 		$this->coordinator->runSignFile($argument);
 	}
diff --git a/lib/BackgroundJob/SignSingleFileJob.php b/lib/BackgroundJob/SignSingleFileJob.php
index 71b2cad3e3..f511d17c3c 100644
--- a/lib/BackgroundJob/SignSingleFileJob.php
+++ b/lib/BackgroundJob/SignSingleFileJob.php
@@ -29,7 +29,6 @@ public function __construct(
 	 */
 	#[\Override]
 	public function run($argument): void {
-		// Handle null arguments from Nextcloud background job system
 		$argument = is_array($argument) ? $argument : [];
 		$this->coordinator->runSignSingleFile($argument);
 	}
diff --git a/lib/Service/AsyncSigningService.php b/lib/Service/AsyncSigningService.php
index 57f7aa1544..5bc00303ee 100644
--- a/lib/Service/AsyncSigningService.php
+++ b/lib/Service/AsyncSigningService.php
@@ -49,6 +49,7 @@ public function enqueueSigningJob(
 		$this->jobList->add(SignFileJob::class, [
 			'fileId' => $libreSignFile->getId(),
 			'signRequestId' => $signRequest->getId(),
+			'signRequestUuid' => $signRequest->getUuid(),
 			'userId' => $user?->getUID(),
 			'credentialsId' => $credentialsId,
 			'userUniqueIdentifier' => $userUniqueIdentifier,
diff --git a/lib/Service/SignFileService.php b/lib/Service/SignFileService.php
index f32e9b31bd..ec706ed5d4 100644
--- a/lib/Service/SignFileService.php
+++ b/lib/Service/SignFileService.php
@@ -42,6 +42,7 @@
 use OCA\Libresign\Service\Envelope\EnvelopeStatusDeterminer;
 use OCA\Libresign\Service\IdentifyMethod\IIdentifyMethod;
 use OCA\Libresign\Service\IdentifyMethod\SignatureMethod\IToken;
+use OCA\Libresign\Service\SignRequest\StatusService;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Db\MultipleObjectsReturnedException;
 use OCP\AppFramework\Utility\ITimeFactory;
@@ -52,8 +53,6 @@
 use OCP\Files\NotPermittedException;
 use OCP\Http\Client\IClientService;
 use OCP\IAppConfig;
-use OCP\ICache;
-use OCP\ICacheFactory;
 use OCP\IDateTimeZone;
 use OCP\IL10N;
 use OCP\ITempManager;
@@ -81,7 +80,6 @@ class SignFileService {
 	private string $friendlyName = '';
 	private ?IUser $user = null;
 	private ?SignEngineHandler $engine = null;
-	private ICache $cache;
 	private PfxProvider $pfxProvider;
 
 	public function __construct(
@@ -116,14 +114,13 @@ public function __construct(
 		private PdfSignatureDetectionService $pdfSignatureDetectionService,
 		private SequentialSigningService $sequentialSigningService,
 		private FileStatusService $fileStatusService,
+		private StatusService $statusService,
 		private IJobList $jobList,
 		private ICredentialsManager $credentialsManager,
 		private EnvelopeStatusDeterminer $envelopeStatusDeterminer,
 		private TsaValidationService $tsaValidationService,
-		ICacheFactory $cacheFactory,
 		PfxProvider $pfxProvider,
 	) {
-		$this->cache = $cacheFactory->createDistributed('libresign_progress');
 		$this->pfxProvider = $pfxProvider;
 	}
 
@@ -550,6 +547,7 @@ private function enqueueSigningJobForFile(SignRequestEntity $signRequest, FileEn
 		$args = array_merge($args, [
 			'fileId' => $file->getId(),
 			'signRequestId' => $signRequest->getId(),
+			'signRequestUuid' => $signRequest->getUuid(),
 		]);
 
 		$this->jobList->add(SignSingleFileJob::class, $args);
@@ -972,15 +970,11 @@ protected function setNewStatusIfNecessary(FileEntity $libreSignFile): bool {
 	}
 
 	private function updateCacheAfterDbSave(FileEntity $libreSignFile): void {
-		$cacheKey = 'status_' . $libreSignFile->getUuid();
-		$status = $libreSignFile->getStatus();
-		$this->cache->set($cacheKey, $status, 60); // Cache for 60 seconds
+		$this->statusService->cacheFileStatus($libreSignFile);
 	}
 
 	private function updateEntityCacheAfterDbSave(FileEntity $file): void {
-		$cacheKey = 'status_' . $file->getUuid();
-		$status = $file->getStatus();
-		$this->cache->set($cacheKey, $status, 60);
+		$this->statusService->cacheFileStatus($file);
 	}
 
 	private function evaluateStatusFromSigners(): ?int {

From d8e423c764e4f002dedb061c6854de4fa9e4bf2a Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:25 -0300
Subject: [PATCH 06/34] feat: enhance FileProgressController with detailed
 error info

Add per-file error details to progress responses.
Improve envelope progress with child file error aggregation.
Change from short polling to long-polling for better efficiency.

Users now see specific error messages for each file that fails
during async signing, rather than generic failure messages.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Controller/FileProgressController.php | 44 +++++++++++++++++++----
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/lib/Controller/FileProgressController.php b/lib/Controller/FileProgressController.php
index ef445223d4..55b5a2c8f3 100644
--- a/lib/Controller/FileProgressController.php
+++ b/lib/Controller/FileProgressController.php
@@ -53,7 +53,7 @@ public function __construct(
 	 *
 	 * @param string $uuid Sign request UUID
 	 * @param int $timeout Maximum seconds to wait (default 30)
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
 	 *
 	 * 200: Status and progress returned
 	 * 404: Sign request not found
@@ -64,14 +64,17 @@ public function __construct(
 	#[PublicPage]
 	#[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/progress/{uuid}', requirements: ['apiVersion' => '(v1)'])]
 	public function checkProgressByUuid(string $uuid, int $timeout = 30): DataResponse {
+		$timeout = max(1, min($timeout, 30));
 		try {
 			$signRequest = $this->signRequestMapper->getByUuid($uuid);
 			$file = $this->fileMapper->getById($signRequest->getFileId());
 			$currentStatus = $this->progressService->getStatusCodeForSignRequest($file, $signRequest);
 
-			if ($file->getStatus() === FileStatus::SIGNING_IN_PROGRESS->value) {
-				$this->workerHealthService->ensureWorkerRunning();
-				$currentStatus = $this->progressService->pollForStatusChange($uuid, $currentStatus, $timeout);
+			if ($timeout > 0) {
+				if ($file->getStatus() === FileStatus::SIGNING_IN_PROGRESS->value) {
+					$this->workerHealthService->ensureWorkerRunning();
+				}
+				$currentStatus = $this->progressService->pollForStatusOrErrorChange($file, $signRequest, $currentStatus, $timeout);
 			}
 
 			return $this->buildStatusResponse($file, $signRequest, $currentStatus);
@@ -90,12 +93,16 @@ public function checkProgressByUuid(string $uuid, int $timeout = 30): DataRespon
 	 * @param FileEntity $file The file entity
 	 * @param SignRequestEntity $signRequest The sign request entity
 	 * @param int $status Current status code
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile}, array{}>
-	 * @psalm-return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>
+	 * @psalm-return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>
 	 */
 	private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRequest, int $status): DataResponse {
 		$statusEnum = FileStatus::tryFrom($status);
 		$progress = $this->progressService->getSignRequestProgress($file, $signRequest);
+		$error = $this->progressService->getSignRequestError($signRequest->getUuid());
+
+		$hasFileErrors = !empty($progress['files']) && $this->hasErrorsInFiles($progress['files']);
+
 		$response = [
 			'status' => $statusEnum?->name ?? 'UNKNOWN',
 			'statusCode' => $status,
@@ -104,7 +111,16 @@ private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRe
 			'progress' => $progress,
 		];
 
-		if ($this->progressService->isProgressComplete($progress)) {
+		if ($error && !$hasFileErrors) {
+			$response['status'] = 'ERROR';
+			if (!empty($error['message'])) {
+				$response['statusText'] = (string)$error['message'];
+			}
+			$response['error'] = $error;
+		}
+
+		$hasAnyError = $error || $hasFileErrors || ($progress['errors'] ?? 0) > 0;
+		if (!$hasAnyError && $this->progressService->isProgressComplete($progress)) {
 			$response['file'] = $this->fileService
 				->setFile($file)
 				->setSignRequest($signRequest)
@@ -121,4 +137,18 @@ private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRe
 
 		return new DataResponse($response, Http::STATUS_OK);
 	}
+
+	/**
+	 * Check if any file in the files list has an error
+	 *
+	 * @param array<int, array<string, mixed>> $files
+	 */
+	private function hasErrorsInFiles(array $files): bool {
+		foreach ($files as $file) {
+			if (!empty($file['error'])) {
+				return true;
+			}
+		}
+		return false;
+	}
 }

From 18bced3ef6398e72d857812760aec4cf465c1802 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:32 -0300
Subject: [PATCH 07/34] feat: display per-file errors in SigningProgress
 component

Show individual file error messages with error icons.
Improve polling logic to handle file-level errors gracefully.
Switch to long-polling (immediate retry) for better responsiveness.
Add error state detection to stop polling when appropriate.

Users now see which specific files failed and why during batch
signing operations.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/components/validation/SigningProgress.vue | 164 +++++++++++++++---
 1 file changed, 138 insertions(+), 26 deletions(-)

diff --git a/src/components/validation/SigningProgress.vue b/src/components/validation/SigningProgress.vue
index 1c21519c3a..4296bb936d 100644
--- a/src/components/validation/SigningProgress.vue
+++ b/src/components/validation/SigningProgress.vue
@@ -4,11 +4,11 @@
 -->
 <template>
 	<div class="signing-progress">
-		<h1>{{ t('libresign', 'Signing document...') }}</h1>
+		<h1>{{ getHeaderTitle() }}</h1>
 		<NcNoteCard type="info">
 			<div class="note-header">
-				<NcLoadingIcon :size="20" />
-				<span>{{ t('libresign', 'Your document is being signed. This may take a few moments.') }}</span>
+				<NcLoadingIcon v-if="isPolling" :size="20" />
+				<span>{{ getHeaderSubtitle() }}</span>
 			</div>
 			<div v-if="progress" class="progress-body">
 				<div class="summary">
@@ -31,12 +31,18 @@
 						<span>{{ t('libresign', 'File') }}</span>
 						<span>{{ t('libresign', 'Status') }}</span>
 					</div>
-					<div v-for="file in progress.files" :key="file.id" class="file-row">
-						<span class="file-name">{{ file.name }}</span>
-						<span :class="['status-pill', `status-${getStatusMeta(file.status).class}`]">
-							<NcIconSvgWrapper :path="getStatusMeta(file.status).icon" />
-							{{ getStatusMeta(file.status).label }}
+					<div v-for="file in progress.files" :key="file.id" class="file-item">
+						<div class="file-row">
+							<span class="file-name">{{ file.name }}</span>
+						<span :class="['status-pill', `status-${getFileStatusMeta(file).class}`]">
+							<NcIconSvgWrapper :path="getFileStatusMeta(file).icon" />
+							{{ getFileStatusMeta(file).label }}
 						</span>
+						</div>
+						<div v-if="file.error && file.error.message" class="file-error">
+							<span class="error-icon">⚠</span>
+							<span class="error-message">{{ file.error.message }}</span>
+						</div>
 					</div>
 				</div>
 			</div>
@@ -53,6 +59,7 @@ import NcLoadingIcon from '@nextcloud/vue/components/NcLoadingIcon'
 import NcNoteCard from '@nextcloud/vue/components/NcNoteCard'
 import NcIconSvgWrapper from '@nextcloud/vue/components/NcIconSvgWrapper'
 
+import { mdiAlertCircleOutline, mdiHelpCircle } from '@mdi/js'
 import { buildStatusMap } from '../../utils/fileStatus.js'
 
 export default {
@@ -69,7 +76,7 @@ export default {
 			description: 'Sign request UUID (not file UUID)',
 		},
 	},
-	emits: ['completed', 'error', 'status-changed'],
+	emits: ['completed', 'error', 'status-changed', 'file-errors'],
 	setup() {
 		return { t }
 	},
@@ -80,6 +87,7 @@ export default {
 			progress: null,
 			currentStatusCode: null,
 			statusMap: buildStatusMap(),
+			pollTimeoutSeconds: 30,
 		}
 	},
 	watch: {
@@ -98,13 +106,39 @@ export default {
 		this.stopPolling()
 	},
 	methods: {
+		getHeaderTitle() {
+			const { allProcessed, errorCount } = this.getProgressCompletionState()
+			if (!this.isPolling && allProcessed && errorCount > 0) {
+				return t('libresign', 'Signing finished with errors')
+			}
+			return t('libresign', 'Signing document...')
+		},
+		getHeaderSubtitle() {
+			const { allProcessed, errorCount } = this.getProgressCompletionState()
+			if (!this.isPolling && allProcessed && errorCount > 0) {
+				return t('libresign', 'Some files could not be signed. Please review the errors below.')
+			}
+			return t('libresign', 'Your document is being signed. This may take a few moments.')
+		},
+		getProgressCompletionState() {
+			const progressReady = this.progress && (this.progress.total ?? 0) > 0
+			const total = this.progress?.total ?? 0
+			const signed = this.progress?.signed ?? 0
+			const fileErrors = this.getFilesWithErrors()
+			const errorCount = this.progress?.errors ?? fileErrors.length
+			const processedCount = signed + errorCount
+			const allProcessed = progressReady && processedCount >= total
+			return { allProcessed, errorCount }
+		},
 		startPolling() {
 			if (this.isPolling || !this.signRequestUuid) {
 				return
 			}
 			this.isPolling = true
 			this.pollFileProgress()
-			this.fetchProgressFromValidation()
+			if (!this.progress) {
+				this.fetchProgressFromValidation()
+			}
 		},
 		stopPolling() {
 			this.isPolling = false
@@ -122,8 +156,8 @@ export default {
 			const { data } = await axios.get(
 				generateOcsUrl(`/apps/libresign/api/v1/file/progress/${this.signRequestUuid}`),
 				{
-					params: { timeout: 0 },
-					timeout: 35000,
+					params: { timeout: this.pollTimeoutSeconds },
+					timeout: (this.pollTimeoutSeconds + 5) * 1000,
 				}
 			)
 
@@ -139,6 +173,20 @@ export default {
 				await this.fetchProgressFromValidation()
 			}
 
+			// Detectar se há erros em arquivos individuais
+			const hasFileErrors = this.hasIndividualFileErrors()
+			const fileErrors = this.getFilesWithErrors()
+			if (hasFileErrors) {
+				this.$emit('file-errors', fileErrors)
+			}
+
+			// Erro geral do job (não erro de arquivo individual)
+			if (responseData?.error && !this.progress?.files) {
+				this.stopPolling()
+				this.$emit('error', responseData.error.message || t('libresign', 'Signing failed. Please try again.'))
+				return
+			}
+
 			if (responseData?.file) {
 				this.stopPolling()
 				this.$emit('completed', responseData.file)
@@ -146,28 +194,36 @@ export default {
 			}
 
 			const progressReady = this.progress && (this.progress.total ?? 0) > 0
-			const allSigned = progressReady && (this.progress.signed ?? 0) >= (this.progress.total ?? 0)
-			const hasPendingWork = !progressReady
-				|| !allSigned
-				|| (this.progress.pending ?? 0) > 0
-				|| (this.progress.inProgress ?? 0) > 0
+			const total = this.progress?.total ?? 0
+			const signed = this.progress?.signed ?? 0
+			const errorCount = this.progress?.errors ?? fileErrors.length
+			const processedCount = signed + errorCount
+			const pending = this.progress?.pending ?? Math.max(total - processedCount - (this.progress?.inProgress ?? 0), 0)
+			const inProgress = this.progress?.inProgress ?? 0
+			const allProcessed = progressReady && processedCount >= total
+			const hasPendingWork = !progressReady || pending > 0 || inProgress > 0 || !allProcessed
 
-			if (status === 'SIGNED' && !hasPendingWork) {
+			if (status === 'ABLE_TO_SIGN' || this.currentStatusCode === 1) {
+				this.stopPolling()
+				this.$emit('error', t('libresign', 'Document ready to sign'))
+			} else if (allProcessed && errorCount > 0) {
+				this.stopPolling()
+				const firstError = fileErrors.find(file => file?.error?.message)?.error?.message
+				this.$emit('error', firstError || t('libresign', 'Signing failed. Please try again.'))
+			} else if (status === 'SIGNED' && !hasPendingWork) {
 				this.stopPolling()
 				this.$emit('completed')
-			} else if (status === 'ERROR') {
+			} else if (status === 'ERROR' && !hasPendingWork && !hasFileErrors) {
+				// Só parar se for erro geral e não há trabalho pendente
 				this.stopPolling()
 				this.$emit('error', t('libresign', 'Signing failed. Please try again.'))
-			} else if (status === 'SIGNING_IN_PROGRESS') {
-				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 1000)
-			} else if (status === 'SIGNED' && hasPendingWork) {
-				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 1000)
 			} else {
-				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 2000)
+				// Long-poll returns on change/timeout; re-open immediately.
+				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 0)
 			}
 		} catch (error) {
 			if (error.code === 'ECONNABORTED') {
-				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 100)
+				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 0)
 			} else {
 				this.stopPolling()
 				this.$emit('error', t('libresign', 'Failed to check signing progress'))
@@ -176,12 +232,15 @@ export default {
 	},
 	async fetchProgressFromValidation() {
 		try {
+			if (this.hasIndividualFileErrors() || (this.progress?.errors ?? 0) > 0) {
+				return
+			}
 			const { data } = await axios.get(
 				generateOcsUrl(`/apps/libresign/api/v1/file/validate/uuid/${this.signRequestUuid}`)
 			)
 			const doc = data.ocs?.data || data
 			const derived = this.buildProgressFromValidation(doc)
-			if (derived) {
+			if (derived && !this.hasIndividualFileErrors() && (this.progress?.errors ?? 0) === 0) {
 				this.progress = derived
 			}
 		} catch (e) {
@@ -238,6 +297,28 @@ export default {
 		}
 		return { label: t('libresign', 'Unknown'), icon: mdiHelpCircle }
 	},
+	getFileStatusMeta(file) {
+		if (file?.error) {
+			return {
+				label: t('libresign', 'Error'),
+				icon: mdiAlertCircleOutline,
+				class: 'error',
+			}
+		}
+		return this.getStatusMeta(file?.status)
+	},
+	hasIndividualFileErrors() {
+		if (!this.progress?.files || !Array.isArray(this.progress.files)) {
+			return false
+		}
+		return this.progress.files.some(file => file.error !== null && file.error !== undefined)
+	},
+	getFilesWithErrors() {
+		if (!this.progress?.files || !Array.isArray(this.progress.files)) {
+			return []
+		}
+		return this.progress.files.filter(file => file.error !== null && file.error !== undefined)
+	},
 	},
 }
 </script>
@@ -294,6 +375,12 @@ export default {
 			flex-direction: column;
 			gap: 8px;
 
+			.file-item {
+				display: flex;
+				flex-direction: column;
+				gap: 4px;
+			}
+
 			.file-row {
 				display: grid;
 				grid-template-columns: 2fr 1fr;
@@ -331,9 +418,34 @@ export default {
 				&.status-partial { background: #e3f2fd; color: #1976d2; }
 				&.status-signed { background: #e8f5e9; color: #2e7d32; }
 				&.status-deleted { background: #ffebee; color: #c62828; }
+				&.status-error { background: #ffebee; color: #c62828; }
 				&.status-signing { background: #fff3e0; color: #f57c00; }
 				&.status-unknown { background: #eceff1; color: #455a64; }
 			}
+
+			.file-error {
+				display: flex;
+				align-items: center;
+				gap: 8px;
+				padding: 8px 12px;
+				margin: 0 10px;
+				border-radius: 6px;
+				background-color: var(--color-error, #ffebee);
+				border: 1px solid var(--color-error, #ffcdd2);
+				font-size: 13px;
+
+				.error-icon {
+					font-size: 16px;
+					color: var(--color-error, #c62828);
+					flex-shrink: 0;
+				}
+
+				.error-message {
+					color: var(--color-main-text);
+					word-break: break-word;
+					flex: 1;
+				}
+			}
 		}
 	}
 }

From 6a9dd395c8f2be5120fd156e702b34bda4a2643c Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:58:47 -0300
Subject: [PATCH 08/34] feat: improve async signing UX in Validation view

Hide sidebar when async signing starts for cleaner UI.
Keep async view visible on error to show per-file error details.
Improve error handling flow in RequestSignatureTab.

This prevents the UI from closing prematurely and allows users to
see detailed error information for failed signing operations.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/components/RightSidebar/RequestSignatureTab.vue |  8 +++++++-
 src/views/Validation.vue                            | 10 +++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/components/RightSidebar/RequestSignatureTab.vue b/src/components/RightSidebar/RequestSignatureTab.vue
index 1fa8419ad0..7400dea9b6 100644
--- a/src/components/RightSidebar/RequestSignatureTab.vue
+++ b/src/components/RightSidebar/RequestSignatureTab.vue
@@ -962,7 +962,13 @@ export default {
 			this.hasLoading = false
 		},
 		async sign() {
-			const uuid = this.filesStore.getFile().signUuid
+			const file = this.filesStore.getFile()
+			if (file?.status === FILE_STATUS.SIGNING_IN_PROGRESS) {
+				this.validationFile()
+				return
+			}
+
+			const uuid = file.signUuid
 			if (this.useModal) {
 				const route = router.resolve({ name: 'SignPDFExternal', params: { uuid } })
 				this.modalSrc = route.href
diff --git a/src/views/Validation.vue b/src/views/Validation.vue
index 9a7f913137..af810881ad 100644
--- a/src/views/Validation.vue
+++ b/src/views/Validation.vue
@@ -122,6 +122,7 @@ import { openDocument } from '../utils/viewer.js'
 import { getStatusLabel } from '../utils/fileStatus.js'
 import logger from '../logger.js'
 import { useSignStore } from '../store/sign.js'
+import { useSidebarStore } from '../store/sidebar.js'
 
 export default {
 	name: 'Validation',
@@ -143,10 +144,12 @@ export default {
 	},
 	setup() {
 		const signStore = useSignStore()
+		const sidebarStore = useSidebarStore()
 		return {
 			t,
 			n,
 			signStore,
+			sidebarStore,
 		}
 	},
 	data() {
@@ -252,6 +255,11 @@ export default {
 		},
 	},
 	watch: {
+		isAsyncSigning(active) {
+			if (active) {
+				this.sidebarStore.hideSidebar()
+			}
+		},
 		'$route.params.uuid'(uuid) {
 			this.validate(uuid)
 		},
@@ -658,8 +666,8 @@ export default {
 				})
 		},
 		handleSigningError(message) {
-			this.isAsyncSigning = false
 			this.loading = false
+			// Keep async view visible so the user can see per-file errors.
 			const errorMessage = message || t('libresign', 'Signing failed. Please try again.')
 			this.setValidationError(errorMessage)
 		},

From eccb21c4caa18d6e0f300ed3a160b5eebdbbb92a Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:59:17 -0300
Subject: [PATCH 09/34] test: add unit tests for error reporting infrastructure

Add comprehensive tests for ErrorPayloadBuilder and SignRequestErrorReporter.
Cover error serialization, HTTP code extraction, and error storage/retrieval.

Ensures error reporting services work correctly and maintain data integrity.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Error/ErrorPayloadBuilderTest.php         | 170 ++++++++++++++++++
 .../Error/SignRequestErrorReporterTest.php    | 152 ++++++++++++++++
 2 files changed, 322 insertions(+)
 create mode 100644 tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
 create mode 100644 tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php

diff --git a/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
new file mode 100644
index 0000000000..dcd6b0cf95
--- /dev/null
+++ b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
@@ -0,0 +1,170 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Tests\Unit\Service\SignRequest\Error;
+
+use OCA\Libresign\Service\SignRequest\Error\ErrorPayloadBuilder;
+use PHPUnit\Framework\TestCase;
+
+class ErrorPayloadBuilderTest extends TestCase {
+	public function testBuildMinimalPayload(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder
+			->setMessage('Test error')
+			->setCode(500)
+			->build();
+
+		$this->assertArrayHasKey('message', $payload);
+		$this->assertArrayHasKey('code', $payload);
+		$this->assertArrayHasKey('timestamp', $payload);
+		$this->assertEquals('Test error', $payload['message']);
+		$this->assertEquals(500, $payload['code']);
+	}
+
+	public function testBuildWithFile(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder
+			->setMessage('File error')
+			->setCode(400)
+			->setFileId(123)
+			->build();
+
+		$this->assertEquals(123, $payload['fileId']);
+	}
+
+	public function testBuildWithSignRequest(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder
+			->setMessage('Sign request error')
+			->setCode(400)
+			->setSignRequestId(456)
+			->setSignRequestUuid('test-uuid-123')
+			->build();
+
+		$this->assertEquals(456, $payload['signRequestId']);
+		$this->assertEquals('test-uuid-123', $payload['signRequestUuid']);
+	}
+
+	public function testBuildWithFileAndSignRequest(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder
+			->setMessage('Combined error')
+			->setCode(400)
+			->setFileId(789)
+			->setSignRequestId(456)
+			->setSignRequestUuid('test-uuid-456')
+			->build();
+
+		$this->assertEquals(789, $payload['fileId']);
+		$this->assertEquals(456, $payload['signRequestId']);
+		$this->assertEquals('test-uuid-456', $payload['signRequestUuid']);
+	}
+
+	public function testAddFileError(): void {
+		$builder = new ErrorPayloadBuilder();
+		$exception1 = new \Exception('File 1 error', 101);
+		$exception2 = new \Exception('File 2 error', 102);
+
+		$payload = $builder
+			->setMessage('Multi-file error')
+			->addFileError(1001, $exception1)
+			->addFileError(1002, $exception2)
+			->build();
+
+		$this->assertArrayHasKey('fileErrors', $payload);
+		$this->assertCount(2, $payload['fileErrors']);
+		$this->assertEquals('File 1 error', $payload['fileErrors'][1001]['message']);
+		$this->assertEquals(101, $payload['fileErrors'][1001]['code']);
+		$this->assertEquals('File 2 error', $payload['fileErrors'][1002]['message']);
+		$this->assertEquals(102, $payload['fileErrors'][1002]['code']);
+	}
+
+	public function testClearFileErrors(): void {
+		$builder = new ErrorPayloadBuilder();
+		$exception = new \Exception('Test error');
+
+		$builder->addFileError(1001, $exception);
+		$payload1 = $builder->build();
+		$this->assertArrayHasKey('fileErrors', $payload1);
+
+		$builder->clearFileErrors();
+		$payload2 = $builder->build();
+		$this->assertArrayNotHasKey('fileErrors', $payload2);
+	}
+
+	public function testFromException(): void {
+		$exception = new \Exception('Exception message', 789);
+
+		$payload = ErrorPayloadBuilder::fromException($exception, 555, 666, 'exception-uuid')->build();
+
+		$this->assertEquals('Exception message', $payload['message']);
+		$this->assertEquals(789, $payload['code']);
+		$this->assertEquals(555, $payload['fileId']);
+		$this->assertEquals(666, $payload['signRequestId']);
+		$this->assertEquals('exception-uuid', $payload['signRequestUuid']);
+	}
+
+	public function testFromExceptionWithoutContext(): void {
+		$exception = new \Exception('Standalone error', 999);
+
+		$payload = ErrorPayloadBuilder::fromException($exception)->build();
+
+		$this->assertEquals('Standalone error', $payload['message']);
+		$this->assertEquals(999, $payload['code']);
+		$this->assertArrayNotHasKey('fileId', $payload);
+		$this->assertArrayNotHasKey('signRequestId', $payload);
+		$this->assertArrayNotHasKey('signRequestUuid', $payload);
+	}
+
+	public function testFluentInterface(): void {
+		$exception = new \Exception('Test', 1);
+
+		// Test that all methods return self for chaining
+		$builder = ErrorPayloadBuilder::fromException($exception)
+			->setMessage('New message')
+			->setCode(222)
+			->setFileId(111)
+			->addFileError(1, new \Exception('Error 1'))
+			->addFileError(2, new \Exception('Error 2'));
+
+		$this->assertInstanceOf(ErrorPayloadBuilder::class, $builder);
+
+		$payload = $builder->build();
+		$this->assertEquals('New message', $payload['message']);
+		$this->assertEquals(222, $payload['code']);
+		$this->assertEquals(111, $payload['fileId']);
+		$this->assertCount(2, $payload['fileErrors']);
+	}
+
+	public function testNullFileAndSignRequestNotIncluded(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder
+			->setMessage('Error without context')
+			->setCode(400)
+			->setFileId(null)
+			->setSignRequestId(null)
+			->setSignRequestUuid(null)
+			->build();
+
+		$this->assertArrayNotHasKey('fileId', $payload);
+		$this->assertArrayNotHasKey('signRequestId', $payload);
+		$this->assertArrayNotHasKey('signRequestUuid', $payload);
+	}
+
+	public function testTimestampPresent(): void {
+		$builder = new ErrorPayloadBuilder();
+		$payload = $builder->setMessage('Test')->build();
+
+		$this->assertArrayHasKey('timestamp', $payload);
+		// Validate ISO 8601 format
+		$this->assertMatchesRegularExpression(
+			'/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}/',
+			$payload['timestamp']
+		);
+	}
+}
diff --git a/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
new file mode 100644
index 0000000000..c2a31761f5
--- /dev/null
+++ b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Tests\Unit\Service\SignRequest\Error;
+
+use OCA\Libresign\Service\SignRequest\Error\SignRequestErrorReporter;
+use OCA\Libresign\Service\SignRequest\ProgressService;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+
+class SignRequestErrorReporterTest extends TestCase {
+	private ProgressService&MockObject $progressService;
+	private LoggerInterface&MockObject $logger;
+	private SignRequestErrorReporter $reporter;
+
+	protected function setUp(): void {
+		$this->progressService = $this->createMock(ProgressService::class);
+		$this->logger = $this->createMock(LoggerInterface::class);
+		$this->reporter = new SignRequestErrorReporter($this->progressService, $this->logger);
+	}
+
+	public function testErrorStoresPayloadAndLogs(): void {
+		$exception = new \RuntimeException('boom', 123);
+		$context = [
+			'exception' => $exception,
+			'fileId' => 10,
+			'signRequestId' => 20,
+			'signRequestUuid' => 'uuid-123',
+		];
+
+		$this->progressService->expects($this->once())
+			->method('setSignRequestError')
+			->with(
+				'uuid-123',
+				$this->callback(function (array $payload) {
+					return $payload['message'] === 'boom'
+						&& $payload['code'] === 123
+						&& $payload['fileId'] === 10
+						&& $payload['signRequestId'] === 20
+						&& $payload['signRequestUuid'] === 'uuid-123';
+				}),
+				300
+			);
+
+		$this->progressService->expects($this->once())
+			->method('setFileError')
+			->with(
+				'uuid-123',
+				10,
+				$this->callback(function (array $payload) {
+					return $payload['message'] === 'boom'
+						&& $payload['code'] === 123
+						&& $payload['fileId'] === 10
+						&& $payload['signRequestId'] === 20
+						&& $payload['signRequestUuid'] === 'uuid-123';
+				}),
+				300
+			);
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Sign failed', $context);
+
+		$this->reporter->error('Sign failed', $context);
+	}
+
+	public function testNonErrorDoesNotStorePayload(): void {
+		$context = [
+			'exception' => new \RuntimeException('warn'),
+			'signRequestUuid' => 'uuid-456',
+		];
+
+		$this->progressService->expects($this->never())
+			->method('setSignRequestError');
+		$this->progressService->expects($this->never())
+			->method('setFileError');
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::WARNING, 'Warning message', $context);
+
+		$this->reporter->warning('Warning message', $context);
+	}
+
+	public function testErrorWithoutExceptionDoesNotStorePayload(): void {
+		$context = [
+			'signRequestUuid' => 'uuid-789',
+		];
+
+		$this->progressService->expects($this->never())
+			->method('setSignRequestError');
+		$this->progressService->expects($this->never())
+			->method('setFileError');
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Error without exception', $context);
+
+		$this->reporter->error('Error without exception', $context);
+	}
+
+	public function testErrorWithoutUuidDoesNotStorePayload(): void {
+		$exception = new \RuntimeException('no uuid');
+		$context = [
+			'exception' => $exception,
+		];
+
+		$this->progressService->expects($this->never())
+			->method('setSignRequestError');
+		$this->progressService->expects($this->never())
+			->method('setFileError');
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Error without uuid', $context);
+
+		$this->reporter->error('Error without uuid', $context);
+	}
+
+	public function testErrorUsesCustomTtl(): void {
+		$exception = new \RuntimeException('ttl', 7);
+		$context = [
+			'exception' => $exception,
+			'signRequestUuid' => 'uuid-ttl',
+			'ttl' => 900,
+		];
+
+		$this->progressService->expects($this->once())
+			->method('setSignRequestError')
+			->with(
+				'uuid-ttl',
+				$this->callback(fn (array $payload) => $payload['message'] === 'ttl'),
+				900
+			);
+
+		$this->progressService->expects($this->never())
+			->method('setFileError');
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Error with ttl', $context);
+
+		$this->reporter->error('Error with ttl', $context);
+	}
+}

From 5189db31f2c63265534dbb80a55ae3ba904a0210 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:59:49 -0300
Subject: [PATCH 10/34] test: extend ProgressServiceTest with error tracking
 tests

Add tests for per-file error storage and retrieval.
Test error fallback to metadata when cache unavailable.
Add tests for envelope progress with file errors.
Include long-polling tests with error detection.

Validates that error tracking works across all progress
calculation scenarios including envelopes and single files.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../SignRequest/ProgressServiceTest.php       | 479 +++++++++++++++++-
 1 file changed, 471 insertions(+), 8 deletions(-)

diff --git a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
index 52846e3cc8..fa10c593d4 100644
--- a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
+++ b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
@@ -8,13 +8,18 @@
 
 namespace OCA\Libresign\Tests\Unit\Service\SignRequest;
 
+use OC\Memcache\ArrayCache;
 use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\FileMapper;
 use OCA\Libresign\Db\SignRequest as SignRequestEntity;
+use OCA\Libresign\Db\SignRequestMapper;
 use OCA\Libresign\Enum\FileStatus;
 use OCA\Libresign\Service\SignRequest\ProgressService;
+use OCA\Libresign\Service\SignRequest\StatusCacheService;
+use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\ICache;
 use OCP\ICacheFactory;
+use OCP\IMemcache;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 
@@ -23,19 +28,25 @@ class ProgressServiceTest extends TestCase {
 	private FileMapper&MockObject $fileMapper;
 	private ICache&MockObject $cache;
 	private ICacheFactory&MockObject $cacheFactory;
+	private SignRequestMapper&MockObject $signRequestMapper;
+	private StatusCacheService&MockObject $statusCacheService;
 
 	protected function setUp(): void {
 		$this->fileMapper = $this->createMock(FileMapper::class);
 		$this->cache = $this->createMock(ICache::class);
 		$this->cacheFactory = $this->createMock(ICacheFactory::class);
+		$this->signRequestMapper = $this->createMock(SignRequestMapper::class);
 		$this->cacheFactory
 			->method('createDistributed')
 			->with('libresign_progress')
 			->willReturn($this->cache);
+		$this->statusCacheService = $this->createMock(StatusCacheService::class);
 
 		$this->service = new ProgressService(
 			$this->fileMapper,
 			$this->cacheFactory,
+			$this->signRequestMapper,
+			$this->statusCacheService,
 		);
 	}
 
@@ -44,7 +55,7 @@ public function testPollReturnsInitialStatusWhenCacheNeverChanges(): void {
 		$initialStatus = FileStatus::DRAFT->value;
 		$timeout = 1;
 
-		$this->cache->method('get')->willReturn(false);
+		$this->statusCacheService->method('getStatus')->willReturn(false);
 
 		$result = $this->service->pollForStatusChange($uuid, $initialStatus, $timeout, 0);
 
@@ -56,19 +67,99 @@ public function testPollReturnsNewStatusWhenCacheChanges(): void {
 		$initialStatus = FileStatus::DRAFT->value;
 		$newStatus = FileStatus::SIGNING_IN_PROGRESS->value;
 
-		$this->cache
-			->method('get')
-			->willReturnOnConsecutiveCalls(
-				$initialStatus,
-				$initialStatus,
-				$newStatus,
-			);
+		$sequence = [$initialStatus, $initialStatus, $newStatus];
+		$index = 0;
+		
+		// Create a fresh mock to avoid conflicts with setUp()
+		$this->statusCacheService = $this->createMock(StatusCacheService::class);
+		$this->statusCacheService
+			->method('getStatus')
+			->with($uuid)
+			->willReturnCallback(function () use (&$sequence, &$index) {
+				$value = $sequence[$index] ?? $sequence[count($sequence) - 1];
+				$index++;
+				return $value;
+			});
+		
+		// Recreate service with the new mock
+		$this->service = new ProgressService(
+			$this->fileMapper,
+			$this->cacheFactory,
+			$this->signRequestMapper,
+			$this->statusCacheService,
+		);
 
 		$result = $this->service->pollForStatusChange($uuid, $initialStatus, 5, 0);
 
 		$this->assertEquals($newStatus, $result);
 	}
 
+	public function testPollForStatusOrErrorChangeUsesFileUuidCacheKeyForSingleFile(): void {
+		$file = $this->createFileEntity(10, 'file.pdf', FileStatus::DRAFT->value, null);
+		$file->setUuid('file-uuid');
+		$signRequest = $this->createSignRequestEntity(20, 'Signer', FileStatus::DRAFT->value, null);
+		$signRequest->setUuid('sign-request-uuid');
+
+		$uuids = [];
+		$this->statusCacheService
+			->method('getStatus')
+			->willReturnCallback(function (string $uuid) use (&$uuids) {
+				$uuids[] = $uuid;
+				return false;
+			});
+
+		$this->signRequestMapper
+			->method('getByUuidUncached')
+			->willThrowException(new DoesNotExistException('not found'));
+
+		$result = $this->service->pollForStatusOrErrorChange($file, $signRequest, FileStatus::DRAFT->value, 1, 0);
+
+		$this->assertEquals(FileStatus::DRAFT->value, $result);
+		$this->assertContains('file-uuid', $uuids);
+		$this->assertNotContains('sign-request-uuid', $uuids);
+	}
+
+	public function testPollForStatusOrErrorChangeStopsOnChildErrorForEnvelope(): void {
+		$envelope = $this->createFileEntity(100, 'envelope.pdf', FileStatus::SIGNING_IN_PROGRESS->value, null, 'envelope');
+		$envelope->setUuid('envelope-uuid');
+		$signRequest = $this->createSignRequestEntity(200, 'Signer', FileStatus::DRAFT->value, null);
+		$signRequest->setUuid('envelope-sign-request-uuid');
+
+		$childSignRequest = $this->createSignRequestEntity(300, 'Child', FileStatus::DRAFT->value, null);
+		$childSignRequest->setUuid('child-sign-request-uuid');
+
+		$this->signRequestMapper
+			->method('getByEnvelopeChildrenAndIdentifyMethod')
+			->with(100, 200)
+			->willReturn([$childSignRequest]);
+
+		$errorKey = ProgressService::ERROR_KEY_PREFIX . 'child-sign-request-uuid';
+
+		$this->cache
+			->method('get')
+			->willReturnCallback(function (string $key) use ($errorKey) {
+				if ($key === $errorKey) {
+					return ['message' => 'child error'];
+				}
+				return false;
+			});
+
+		$this->statusCacheService
+			->method('getStatus')
+			->with('envelope-uuid')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$result = $this->service->pollForStatusOrErrorChange(
+			$envelope,
+			$signRequest,
+			FileStatus::SIGNING_IN_PROGRESS->value,
+			1,
+			0,
+		);
+
+		$this->assertEquals(FileStatus::SIGNING_IN_PROGRESS->value, $result);
+	}
+
 	public function testGetSignRequestProgressForSingleFile(): void {
 		$file = $this->createFileEntity(1, 'test.pdf', FileStatus::DRAFT->value, null);
 		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
@@ -188,6 +279,307 @@ public function testGetSignRequestProgressRoutesToCorrectMethod(): void {
 		$this->assertArrayHasKey('pending', $progress);
 	}
 
+	public function testSetAndGetSignRequestError(): void {
+		$uuid = 'test-error-uuid';
+		$error = [
+			'message' => 'Certificate validation failed',
+			'code' => 400,
+			'timestamp' => date('c'),
+		];
+
+		$this->service->setSignRequestError($uuid, $error);
+		$retrieved = $this->service->getSignRequestError($uuid);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('Certificate validation failed', $retrieved['message']);
+		$this->assertEquals(400, $retrieved['code']);
+	}
+
+	public function testGetSignRequestErrorReturnsNullWhenNotSet(): void {
+		$uuid = 'non-existent-uuid';
+
+		$error = $this->service->getSignRequestError($uuid);
+
+		$this->assertNull($error);
+	}
+
+	public function testClearSignRequestError(): void {
+		$uuid = 'clear-test-uuid';
+		$error = ['message' => 'Test error', 'code' => 500];
+
+		$this->service->setSignRequestError($uuid, $error);
+		$this->assertNotNull($this->service->getSignRequestError($uuid));
+
+		$this->service->clearSignRequestError($uuid);
+		$this->assertNull($this->service->getSignRequestError($uuid));
+	}
+
+	public function testSetAndGetSignRequestErrorWithInMemoryCache(): void {
+		$cache = new InMemoryCache();
+		$cacheFactory = new InMemoryCacheFactory($cache);
+		$service = new ProgressService($this->fileMapper, $cacheFactory, $this->signRequestMapper, $this->statusCacheService);
+
+		$uuid = 'real-cache-uuid';
+		$error = [
+			'message' => 'Real cache error',
+			'code' => 501,
+			'timestamp' => date('c'),
+		];
+
+		$service->setSignRequestError($uuid, $error);
+		$retrieved = $service->getSignRequestError($uuid);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('Real cache error', $retrieved['message']);
+		$this->assertEquals(501, $retrieved['code']);
+	}
+
+	public function testGetSignRequestErrorFallsBackToMetadata(): void {
+		$uuid = 'metadata-uuid';
+		$error = [
+			'message' => 'Metadata error',
+			'code' => 409,
+		];
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setUuid($uuid);
+		$signRequest->setMetadata(['libresign_error' => $error]);
+
+		$this->cache->method('get')->willReturn(false);
+		$this->signRequestMapper->method('getByUuidUncached')->with($uuid)->willReturn($signRequest);
+
+		$service = new ProgressService($this->fileMapper, $this->cacheFactory, $this->signRequestMapper, $this->statusCacheService);
+
+		$retrieved = $service->getSignRequestError($uuid);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('Metadata error', $retrieved['message']);
+		$this->assertEquals(409, $retrieved['code']);
+	}
+
+	public function testGetFileErrorFallsBackToMetadata(): void {
+		$uuid = 'file-metadata-uuid';
+		$fileId = 321;
+		$error = [
+			'message' => 'File metadata error',
+			'code' => 422,
+		];
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setUuid($uuid);
+		$signRequest->setMetadata([
+			'libresign_file_errors' => [
+				$fileId => $error,
+			],
+		]);
+
+		$this->cache->method('get')->willReturn(false);
+		$this->signRequestMapper->method('getByUuidUncached')->with($uuid)->willReturn($signRequest);
+
+		$service = new ProgressService($this->fileMapper, $this->cacheFactory, $this->signRequestMapper, $this->statusCacheService);
+
+		$retrieved = $service->getFileError($uuid, $fileId);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('File metadata error', $retrieved['message']);
+		$this->assertEquals(422, $retrieved['code']);
+	}
+
+	public function testSetAndGetFileError(): void {
+		$uuid = 'file-error-uuid';
+		$fileId = 758;
+		$error = [
+			'message' => 'Invalid file format',
+			'code' => 422,
+			'timestamp' => date('c'),
+		];
+
+		$this->service->setFileError($uuid, $fileId, $error);
+		$retrieved = $this->service->getFileError($uuid, $fileId);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('Invalid file format', $retrieved['message']);
+		$this->assertEquals(422, $retrieved['code']);
+	}
+
+	public function testGetFileErrorReturnsNullWhenNotSet(): void {
+		$uuid = 'no-file-error-uuid';
+		$fileId = 999;
+
+		$error = $this->service->getFileError($uuid, $fileId);
+
+		$this->assertNull($error);
+	}
+
+	public function testClearFileError(): void {
+		$uuid = 'clear-file-uuid';
+		$fileId = 758;
+		$error = ['message' => 'Test file error', 'code' => 400];
+
+		$this->service->setFileError($uuid, $fileId, $error);
+		$this->assertNotNull($this->service->getFileError($uuid, $fileId));
+
+		$this->service->clearFileError($uuid, $fileId);
+		$this->assertNull($this->service->getFileError($uuid, $fileId));
+	}
+
+	public function testMultipleFileErrorsIndependent(): void {
+		$uuid = 'multi-file-uuid';
+		$error1 = ['message' => 'Error 1', 'code' => 400];
+		$error2 = ['message' => 'Error 2', 'code' => 500];
+
+		$this->service->setFileError($uuid, 1, $error1);
+		$this->service->setFileError($uuid, 2, $error2);
+
+		$retrieved1 = $this->service->getFileError($uuid, 1);
+		$retrieved2 = $this->service->getFileError($uuid, 2);
+
+		$this->assertEquals('Error 1', $retrieved1['message']);
+		$this->assertEquals('Error 2', $retrieved2['message']);
+	}
+
+	public function testMapSignRequestFileProgressIncludesError(): void {
+		$uuid = 'progress-error-uuid';
+		$file = $this->createFileEntity(758, 'test.pdf', FileStatus::DRAFT->value, null);
+		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
+
+		$error = ['message' => 'File processing failed', 'code' => 500];
+		$this->service->setFileError($uuid, 758, $error);
+
+		$signRequest->setUuid($uuid);
+
+		// Use reflection to test private method
+		$reflection = new \ReflectionClass($this->service);
+		$method = $reflection->getMethod('mapSignRequestFileProgress');
+		$method->setAccessible(true);
+
+		$mapped = $method->invoke($this->service, $file, $signRequest);
+
+		$this->assertArrayHasKey('error', $mapped);
+		$this->assertEquals('File processing failed', $mapped['error']['message']);
+	}
+
+	public function testMapSignRequestFileProgressWithoutError(): void {
+		$file = $this->createFileEntity(758, 'test.pdf', FileStatus::DRAFT->value, null);
+		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
+		$signRequest->setUuid('no-error-uuid');
+
+		// Use reflection to test private method
+		$reflection = new \ReflectionClass($this->service);
+		$method = $reflection->getMethod('mapSignRequestFileProgress');
+		$method->setAccessible(true);
+
+		$mapped = $method->invoke($this->service, $file, $signRequest);
+
+		$this->assertArrayNotHasKey('error', $mapped);
+	}
+
+	public function testEnvelopeProgressWithFileErrors(): void {
+		$uuid = 'envelope-error-uuid';
+		$envelope = $this->createFileEntity(1, 'envelope.pdf', FileStatus::DRAFT->value, null, 'envelope');
+		$child1 = $this->createFileEntity(2, 'child1.pdf', FileStatus::DRAFT->value, 1);
+		$child2 = $this->createFileEntity(3, 'child2.pdf', FileStatus::SIGNING_IN_PROGRESS->value, 1);
+
+		$this->fileMapper
+			->method('getChildrenFiles')
+			->with(1)
+			->willReturn([$child1, $child2]);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		// Set error for child2
+		$error = ['message' => 'Signature failed', 'code' => 422];
+		$this->service->setFileError($uuid, 3, $error);
+
+		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
+		$signRequest->setUuid($uuid);
+
+		$progress = $this->service->getEnvelopeProgressForSignRequest($envelope, $signRequest);
+
+		$this->assertCount(2, $progress['files']);
+		$this->assertArrayNotHasKey('error', $progress['files'][0]); // child1
+		$this->assertArrayHasKey('error', $progress['files'][1]); // child2
+		$this->assertEquals('Signature failed', $progress['files'][1]['error']['message']);
+		$this->assertEquals(1, $progress['errors']);
+		$this->assertEquals(0, $progress['pending']);
+	}
+
+	public function testSingleFileProgressCountsErrorAsProcessed(): void {
+		$uuid = 'single-error-uuid';
+		$file = $this->createFileEntity(10, 'file.pdf', FileStatus::DRAFT->value, null);
+		$signRequest = $this->createSignRequestEntity(20, 'User', FileStatus::DRAFT->value, null);
+		$signRequest->setUuid($uuid);
+
+		$error = ['message' => 'Failed to sign', 'code' => 500];
+		$this->service->setFileError($uuid, $file->getId(), $error);
+
+		$progress = $this->service->getSingleFileProgressForSignRequest($file, $signRequest);
+
+		$this->assertEquals(1, $progress['total']);
+		$this->assertEquals(1, $progress['errors']);
+		$this->assertEquals(0, $progress['pending']);
+		$this->assertEquals(0, $progress['inProgress']);
+		$this->assertTrue($this->service->isProgressComplete($progress));
+	}
+
+	public function testMapSignRequestFileProgressWithContextUsesChildError(): void {
+		$parentUuid = 'parent-uuid';
+		$childUuid = 'child-uuid';
+		$file = $this->createFileEntity(10, 'child.pdf', FileStatus::DRAFT->value, 1);
+		$defaultSignRequest = $this->createSignRequestEntity(200, 'Parent', FileStatus::DRAFT->value, null);
+		$defaultSignRequest->setUuid($parentUuid);
+		$childSignRequest = $this->createSignRequestEntity(201, 'Child', FileStatus::DRAFT->value, null);
+		$childSignRequest->setUuid($childUuid);
+
+		$error = ['message' => 'Child file failed', 'code' => 422];
+		$this->service->setFileError($childUuid, $file->getId(), $error);
+
+		$reflection = new \ReflectionClass($this->service);
+		$method = $reflection->getMethod('mapSignRequestFileProgressWithContext');
+		$method->setAccessible(true);
+
+		$mapped = $method->invoke($this->service, $file, $defaultSignRequest, $childSignRequest);
+
+		$this->assertArrayHasKey('error', $mapped);
+		$this->assertEquals('Child file failed', $mapped['error']['message']);
+		$this->assertEquals(422, $mapped['error']['code']);
+	}
+
+	public function testMapSignRequestFileProgressWithContextFallsBackToMetadata(): void {
+		$childUuid = 'child-meta-uuid';
+		$fileId = 55;
+		$file = $this->createFileEntity($fileId, 'child.pdf', FileStatus::DRAFT->value, 1);
+		$defaultSignRequest = $this->createSignRequestEntity(300, 'Parent', FileStatus::DRAFT->value, null);
+		$childSignRequest = $this->createSignRequestEntity(301, 'Child', FileStatus::DRAFT->value, null);
+		$childSignRequest->setUuid($childUuid);
+
+		$signRequestWithMetadata = new SignRequestEntity();
+		$signRequestWithMetadata->setUuid($childUuid);
+		$signRequestWithMetadata->setMetadata([
+			'libresign_file_errors' => [
+				$fileId => ['message' => 'Metadata file error', 'code' => 409],
+			],
+		]);
+
+		$this->cache->method('get')->willReturn(false);
+		$this->signRequestMapper
+			->method('getByUuidUncached')
+			->with($childUuid)
+			->willReturn($signRequestWithMetadata);
+
+		$reflection = new \ReflectionClass($this->service);
+		$method = $reflection->getMethod('mapSignRequestFileProgressWithContext');
+		$method->setAccessible(true);
+
+		$mapped = $method->invoke($this->service, $file, $defaultSignRequest, $childSignRequest);
+
+		$this->assertArrayHasKey('error', $mapped);
+		$this->assertEquals('Metadata file error', $mapped['error']['message']);
+		$this->assertEquals(409, $mapped['error']['code']);
+	}
+
 	private function createFileEntity(
 		int $id,
 		string $name,
@@ -220,3 +612,74 @@ private function createSignRequestEntity(
 		return $signRequest;
 	}
 }
+
+class InMemoryCache implements ICache {
+	private array $data = [];
+
+	public function get($key) {
+		return $this->data[$key] ?? null;
+	}
+
+	public function set($key, $value, $ttl = 0) {
+		$this->data[$key] = $value;
+		return true;
+	}
+
+	public function hasKey($key) {
+		return array_key_exists($key, $this->data);
+	}
+
+	public function remove($key) {
+		unset($this->data[$key]);
+		return true;
+	}
+
+	public function clear($prefix = '') {
+		if ($prefix === '') {
+			$this->data = [];
+			return true;
+		}
+
+		foreach (array_keys($this->data) as $key) {
+			if (str_starts_with($key, $prefix)) {
+				unset($this->data[$key]);
+			}
+		}
+		return true;
+	}
+
+	public static function isAvailable(): bool {
+		return true;
+	}
+}
+
+class InMemoryCacheFactory implements ICacheFactory {
+	public function __construct(
+		private ICache $cache,
+	) {
+	}
+
+	public function isAvailable(): bool {
+		return true;
+	}
+
+	public function isLocalCacheAvailable(): bool {
+		return true;
+	}
+
+	public function createLocking(string $prefix = ''): IMemcache {
+		return new ArrayCache();
+	}
+
+	public function createDistributed(string $prefix = ''): ICache {
+		return $this->cache;
+	}
+
+	public function createLocal(string $prefix = ''): ICache {
+		return new InMemoryCache();
+	}
+
+	public function createInMemory(int $capacity = 512): ICache {
+		return new InMemoryCache();
+	}
+}

From 66490f4cd6d63483535174bd8c19b20e9b1622a2 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 11:59:58 -0300
Subject: [PATCH 11/34] test: update existing tests for new dependencies

Update SignJobCoordinatorTest with error reporting validation.
Update SignFileServiceTest, StatusServiceTest, and RequestSignatureServiceTest
to inject StatusCacheService and StatusService.

Maintains test coverage after dependency injection changes.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Service/RequestSignatureServiceTest.php   |  7 +-
 .../php/Unit/Service/SignFileServiceTest.php  | 22 ++---
 .../Unit/Service/SignJobCoordinatorTest.php   | 98 ++++++++++++++++++-
 .../Service/SignRequest/StatusServiceTest.php |  6 +-
 4 files changed, 114 insertions(+), 19 deletions(-)

diff --git a/tests/php/Unit/Service/RequestSignatureServiceTest.php b/tests/php/Unit/Service/RequestSignatureServiceTest.php
index cfb8ec9c06..c71764984a 100644
--- a/tests/php/Unit/Service/RequestSignatureServiceTest.php
+++ b/tests/php/Unit/Service/RequestSignatureServiceTest.php
@@ -26,6 +26,7 @@
 use OCA\Libresign\Service\RequestSignatureService;
 use OCA\Libresign\Service\SequentialSigningService;
 use OCA\Libresign\Service\SignRequest\SignRequestService;
+use OCA\Libresign\Service\SignRequest\StatusCacheService;
 use OCA\Libresign\Service\SignRequest\StatusService;
 use OCP\EventDispatcher\IEventDispatcher;
 use OCP\Files\IMimeTypeDetector;
@@ -266,7 +267,8 @@ public function testParallelFlowIgnoresSignerDraftStatusWhenFileIsAbleToSign():
 			->willReturn(false); // Parallel flow
 
 		$fileStatusService = $this->createMock(FileStatusService::class);
-		$statusService = new StatusService($sequentialSigningService, $fileStatusService);
+		$statusCacheService = $this->createMock(StatusCacheService::class);
+		$statusService = new StatusService($sequentialSigningService, $fileStatusService, $statusCacheService);
 
 		// File status is ABLE_TO_SIGN (1)
 		$fileStatus = \OCA\Libresign\Enum\FileStatus::ABLE_TO_SIGN->value;
@@ -297,7 +299,8 @@ public function testOrderedFlowRespectsSigningOrderWhenFileIsAbleToSign(): void
 			->willReturn(true); // Ordered flow
 
 		$fileStatusService = $this->createMock(FileStatusService::class);
-		$statusService = new StatusService($sequentialSigningService, $fileStatusService);
+		$statusCacheService = $this->createMock(StatusCacheService::class);
+		$statusService = new StatusService($sequentialSigningService, $fileStatusService, $statusCacheService);
 
 		$fileStatus = \OCA\Libresign\Enum\FileStatus::ABLE_TO_SIGN->value;
 		$signerStatus = \OCA\Libresign\Enum\SignRequestStatus::DRAFT->value;
diff --git a/tests/php/Unit/Service/SignFileServiceTest.php b/tests/php/Unit/Service/SignFileServiceTest.php
index 8dfb254c1c..b13f937adb 100644
--- a/tests/php/Unit/Service/SignFileServiceTest.php
+++ b/tests/php/Unit/Service/SignFileServiceTest.php
@@ -46,6 +46,7 @@
 use OCA\Libresign\Service\SignerElementsService;
 use OCA\Libresign\Service\SignFileService;
 use OCA\Libresign\Service\SigningCoordinatorService;
+use OCA\Libresign\Service\SignRequest\StatusService;
 use OCA\Libresign\Service\TsaValidationService;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Utility\ITimeFactory;
@@ -56,8 +57,6 @@
 use OCP\Files\NotPermittedException;
 use OCP\Http\Client\IClientService;
 use OCP\IAppConfig;
-use OCP\ICache;
-use OCP\ICacheFactory;
 use OCP\IDateTimeZone;
 use OCP\IL10N;
 use OCP\ITempManager;
@@ -104,12 +103,11 @@ final class SignFileServiceTest extends \OCA\Libresign\Tests\Unit\TestCase {
 	private PdfSignatureDetectionService&MockObject $pdfSignatureDetectionService;
 	private \OCA\Libresign\Service\SequentialSigningService&MockObject $sequentialSigningService;
 	private FileStatusService&MockObject $fileStatusService;
-	private SigningCoordinatorService&MockObject $signingCoordinatorService;
-	private IJobList&MockObject $jobList;
-	private ICredentialsManager&MockObject $credentialsManager;
-	private ICacheFactory&MockObject $cacheFactory;
-	private ICache&MockObject $cache;
-	private EnvelopeStatusDeterminer&MockObject $envelopeStatusDeterminer;
+private SigningCoordinatorService&MockObject $signingCoordinatorService;
+private IJobList&MockObject $jobList;
+private ICredentialsManager&MockObject $credentialsManager;
+private StatusService&MockObject $statusService;
+private EnvelopeStatusDeterminer&MockObject $envelopeStatusDeterminer;
 	private TsaValidationService&MockObject $tsaValidationService;
 	private CertificateValidityPolicy $certificateValidityPolicy;
 	private PfxProvider $pfxProvider;
@@ -153,8 +151,7 @@ public function setUp(): void {
 		$this->signingCoordinatorService = $this->createMock(SigningCoordinatorService::class);
 		$this->jobList = $this->createMock(IJobList::class);
 		$this->credentialsManager = $this->createMock(ICredentialsManager::class);
-		$this->cache = $this->createMock(ICache::class);
-		$this->cacheFactory = $this->createMock(ICacheFactory::class);
+		$this->statusService = $this->createMock(StatusService::class);
 		$this->envelopeStatusDeterminer = $this->createMock(EnvelopeStatusDeterminer::class);
 		$this->tsaValidationService = $this->createMock(TsaValidationService::class);
 		$this->certificateValidityPolicy = new CertificateValidityPolicy();
@@ -163,7 +160,6 @@ public function setUp(): void {
 			$this->eventDispatcher,
 			$this->secureRandom,
 		);
-		$this->cacheFactory->method('createDistributed')->with('libresign_progress')->willReturn($this->cache);
 	}
 
 	public function testClickToSignUsesShortLivedCertificate(): void {
@@ -255,11 +251,11 @@ private function getService(array $methods = []): SignFileService|MockObject {
 					$this->pdfSignatureDetectionService,
 					$this->sequentialSigningService,
 					$this->fileStatusService,
+					$this->statusService,
 					$this->jobList,
 					$this->credentialsManager,
 					$this->envelopeStatusDeterminer,
 					$this->tsaValidationService,
-					$this->cacheFactory,
 					$this->pfxProvider,
 				])
 				->onlyMethods($methods)
@@ -297,11 +293,11 @@ private function getService(array $methods = []): SignFileService|MockObject {
 			$this->pdfSignatureDetectionService,
 			$this->sequentialSigningService,
 			$this->fileStatusService,
+			$this->statusService,
 			$this->jobList,
 			$this->credentialsManager,
 			$this->envelopeStatusDeterminer,
 			$this->tsaValidationService,
-			$this->cacheFactory,
 			$this->pfxProvider,
 		);
 	}
diff --git a/tests/php/Unit/Service/SignJobCoordinatorTest.php b/tests/php/Unit/Service/SignJobCoordinatorTest.php
index cf8b649ca6..a9f2267f32 100644
--- a/tests/php/Unit/Service/SignJobCoordinatorTest.php
+++ b/tests/php/Unit/Service/SignJobCoordinatorTest.php
@@ -16,6 +16,8 @@
 use OCA\Libresign\Service\FolderService;
 use OCA\Libresign\Service\SignFileService;
 use OCA\Libresign\Service\SignJobCoordinator;
+use OCA\Libresign\Service\SignRequest\Error\SignRequestErrorReporter;
+use OCA\Libresign\Service\SignRequest\ProgressService;
 use OCA\Libresign\Tests\Unit\TestCase;
 use OCP\IUser;
 use OCP\IUserManager;
@@ -30,6 +32,8 @@ class SignJobCoordinatorTest extends TestCase {
 	private FolderService&MockObject $folderService;
 	private IUserManager&MockObject $userManager;
 	private ICredentialsManager&MockObject $credentialsManager;
+	private ProgressService&MockObject $progressService;
+	private SignRequestErrorReporter&MockObject $errorReporter;
 	private LoggerInterface&MockObject $logger;
 	private SignJobCoordinator $coordinator;
 
@@ -41,6 +45,8 @@ public function setUp(): void {
 		$this->folderService = $this->createMock(FolderService::class);
 		$this->userManager = $this->createMock(IUserManager::class);
 		$this->credentialsManager = $this->createMock(ICredentialsManager::class);
+		$this->progressService = $this->createMock(ProgressService::class);
+		$this->errorReporter = $this->createMock(SignRequestErrorReporter::class);
 		$this->logger = $this->createMock(LoggerInterface::class);
 		$this->coordinator = new SignJobCoordinator(
 			$this->fileMapper,
@@ -49,6 +55,8 @@ public function setUp(): void {
 			$this->folderService,
 			$this->userManager,
 			$this->credentialsManager,
+			$this->progressService,
+			$this->errorReporter,
 			$this->logger,
 		);
 	}
@@ -169,9 +177,6 @@ public function testRunSignSingleFileDeletesCredentialsWhenSigningFails(): void
 			->method('delete')
 			->with('user2', 'cred-2');
 
-		$this->logger->expects($this->once())
-			->method('error');
-
 		$this->coordinator->runSignSingleFile([
 			'fileId' => $file->getId(),
 			'signRequestId' => $signRequest->getId(),
@@ -179,4 +184,91 @@ public function testRunSignSingleFileDeletesCredentialsWhenSigningFails(): void
 			'credentialsId' => 'cred-2',
 		]);
 	}
+
+	public function testRunSignFileStoresErrorInProgressService(): void {
+		$file = new File();
+		$file->setId(10);
+		$file->setStatus(FileStatus::DRAFT->value);
+
+		$signRequest = new SignRequest();
+		$signRequest->setId(20);
+		$signRequest->setFileId($file->getId());
+		$signRequest->setUuid('sign-request-uuid');
+
+		$this->fileMapper->method('getById')->willReturn($file);
+		$this->signRequestMapper->method('getById')->willReturn($signRequest);
+
+		$this->progressService->expects($this->once())
+			->method('clearSignRequestError')
+			->with('sign-request-uuid');
+
+		$exception = new \Exception('Certificate validation failed', 422);
+		$this->signFileService->method('sign')->willThrowException($exception);
+
+		$this->errorReporter->expects($this->once())
+			->method('error');
+
+		$this->coordinator->runSignFile([
+			'fileId' => $file->getId(),
+			'signRequestId' => $signRequest->getId(),
+		]);
+	}
+
+	public function testRunSignSingleFileStoresErrorWhenValidationFails(): void {
+		$file = new File();
+		$file->setId(50);
+		$file->setUserId('user3');
+		$file->setStatus(FileStatus::DRAFT->value);
+
+		$signRequest = new SignRequest();
+		$signRequest->setId(60);
+		$signRequest->setFileId($file->getId());
+		$signRequest->setUuid('single-sign-uuid');
+
+		$user = $this->createMock(IUser::class);
+		$user->method('getUID')->willReturn('user3');
+		$this->userManager->method('get')->willReturn($user);
+		$this->folderService->method('setUserId');
+
+		$this->fileMapper->method('getById')->willReturn($file);
+		$this->signRequestMapper->method('getById')->willReturn($signRequest);
+
+		$this->credentialsManager->method('retrieve')->willReturn(null);
+
+		$this->signFileService->method('setLibreSignFile')->willReturnSelf();
+		$this->signFileService->method('setSignRequest')->willReturnSelf();
+		$this->signFileService->method('setCurrentUser')->willReturnSelf();
+		$this->signFileService->method('storeUserMetadata')->willReturnSelf();
+		$this->signFileService->method('setVisibleElements')->willReturnSelf();
+
+		$this->progressService->expects($this->once())
+			->method('clearSignRequestError')
+			->with('single-sign-uuid');
+
+		$exception = new \InvalidArgumentException('Invalid parameters', 400);
+		$this->signFileService->method('signSingleFile')->willThrowException($exception);
+
+		$this->errorReporter->expects($this->once())
+			->method('error');
+
+		$this->fileMapper->expects($this->once())
+			->method('update')
+			->with($this->callback(function (File $updated) {
+				return $updated->getStatus() === FileStatus::SIGNING_IN_PROGRESS->value;
+			}));
+
+		$this->coordinator->runSignSingleFile([
+			'fileId' => $file->getId(),
+			'signRequestId' => $signRequest->getId(),
+		]);
+	}
+
+	public function testRunSignFileWithoutSignRequestId(): void {
+		$this->logger->expects($this->once())
+			->method('error');
+
+		$this->coordinator->runSignFile([
+			'fileId' => 123,
+		]);
+	}
 }
diff --git a/tests/php/Unit/Service/SignRequest/StatusServiceTest.php b/tests/php/Unit/Service/SignRequest/StatusServiceTest.php
index 8133ea339b..22b00a0970 100644
--- a/tests/php/Unit/Service/SignRequest/StatusServiceTest.php
+++ b/tests/php/Unit/Service/SignRequest/StatusServiceTest.php
@@ -11,6 +11,7 @@
 use OCA\Libresign\Enum\SignRequestStatus;
 use OCA\Libresign\Service\FileStatusService;
 use OCA\Libresign\Service\SequentialSigningService;
+use OCA\Libresign\Service\SignRequest\StatusCacheService;
 use OCA\Libresign\Service\SignRequest\StatusService;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -18,15 +19,18 @@
 final class StatusServiceTest extends \OCA\Libresign\Tests\Unit\TestCase {
 	private SequentialSigningService&MockObject $sequentialSigningService;
 	private FileStatusService&MockObject $fileStatusService;
+	private StatusCacheService&MockObject $statusCacheService;
 	private StatusService $service;
 
 	public function setUp(): void {
 		parent::setUp();
 		$this->sequentialSigningService = $this->createMock(SequentialSigningService::class);
 		$this->fileStatusService = $this->createMock(FileStatusService::class);
+		$this->statusCacheService = $this->createMock(StatusCacheService::class);
 		$this->service = new StatusService(
 			$this->sequentialSigningService,
-			$this->fileStatusService
+			$this->fileStatusService,
+			$this->statusCacheService
 		);
 	}
 

From 867e52374871a5d1ed13003e2e1854492dfd97f6 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:00:06 -0300
Subject: [PATCH 12/34] test: add comprehensive tests for
 FileProgressController

Add tests for envelope progress endpoint with error details.
Test single file progress with error information.
Validate error payload structure and HTTP responses.
Test long-polling timeout behavior.

Ensures controller correctly exposes per-file error information
to the frontend via API endpoints.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Controller/FileProgressControllerTest.php | 560 ++++++++++++++++++
 1 file changed, 560 insertions(+)
 create mode 100644 tests/php/Unit/Controller/FileProgressControllerTest.php

diff --git a/tests/php/Unit/Controller/FileProgressControllerTest.php b/tests/php/Unit/Controller/FileProgressControllerTest.php
new file mode 100644
index 0000000000..8bef193b29
--- /dev/null
+++ b/tests/php/Unit/Controller/FileProgressControllerTest.php
@@ -0,0 +1,560 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Tests\Unit\Controller;
+
+use OC\Memcache\ArrayCache;
+use OCA\Libresign\Controller\FileProgressController;
+use OCA\Libresign\Db\File as FileEntity;
+use OCA\Libresign\Db\FileMapper;
+use OCA\Libresign\Db\SignRequest as SignRequestEntity;
+use OCA\Libresign\Db\SignRequestMapper;
+use OCA\Libresign\Enum\FileStatus;
+use OCA\Libresign\Service\FileService;
+use OCA\Libresign\Service\SessionService;
+use OCA\Libresign\Service\SignRequest\ProgressService;
+use OCA\Libresign\Service\SignRequest\StatusCacheService;
+use OCA\Libresign\Service\Worker\WorkerHealthService;
+use OCP\AppFramework\Http;
+use OCP\ICache;
+use OCP\ICacheFactory;
+use OCP\IMemcache;
+use OCP\IRequest;
+use OCP\IUserSession;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class FileProgressControllerTest extends TestCase {
+	private FileProgressController $controller;
+	private FileMapper&MockObject $fileMapper;
+	private SignRequestMapper&MockObject $signRequestMapper;
+	private FileService&MockObject $fileService;
+	private SessionService&MockObject $sessionService;
+	private IUserSession&MockObject $userSession;
+	private WorkerHealthService&MockObject $workerHealthService;
+	private ProgressService&MockObject $progressService;
+	private IRequest&MockObject $request;
+
+	protected function setUp(): void {
+		$this->fileMapper = $this->createMock(FileMapper::class);
+		$this->signRequestMapper = $this->createMock(SignRequestMapper::class);
+		$this->fileService = $this->createMock(FileService::class);
+		$this->sessionService = $this->createMock(SessionService::class);
+		$this->userSession = $this->createMock(IUserSession::class);
+		$this->workerHealthService = $this->createMock(WorkerHealthService::class);
+		$this->progressService = $this->createMock(ProgressService::class);
+		$this->request = $this->createMock(IRequest::class);
+
+		$this->controller = new FileProgressController(
+			$this->request,
+			$this->fileMapper,
+			$this->signRequestMapper,
+			$this->fileService,
+			$this->sessionService,
+			$this->userSession,
+			$this->workerHealthService,
+			$this->progressService,
+		);
+	}
+
+	public function testCheckProgressByUuidWithError(): void {
+		$uuid = 'test-uuid-error';
+		$file = new FileEntity();
+		$file->setId(757);
+		$file->setName('test.pdf');
+		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(100);
+		$signRequest->setFileId(757);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(757)
+			->willReturn($file);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		$error = [
+			'message' => 'Certificate validation failed',
+			'code' => 400,
+			'timestamp' => date('c'),
+		];
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn(FileStatus::DRAFT->value);
+
+		$this->progressService
+			->method('pollForStatusOrErrorChange')
+			->willReturn(FileStatus::DRAFT->value);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn([
+				'total' => 1,
+				'signed' => 0,
+				'pending' => 1,
+				'inProgress' => 0,
+				'files' => [
+					['id' => 757, 'name' => 'test.pdf', 'status' => 1, 'statusText' => 'DRAFT'],
+				],
+			]);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->with($uuid)
+			->willReturn($error);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn(false);
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$data = $response->getData();
+
+		$this->assertEquals('ERROR', $data['status']);
+		$this->assertArrayHasKey('error', $data);
+		$this->assertEquals('Certificate validation failed', $data['error']['message']);
+		$this->assertEquals(400, $data['error']['code']);
+	}
+
+	public function testCheckProgressByUuidWithoutError(): void {
+		$uuid = 'test-uuid-no-error';
+		$file = new FileEntity();
+		$file->setId(757);
+		$file->setName('test.pdf');
+		$file->setStatus(FileStatus::DRAFT->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(100);
+		$signRequest->setFileId(757);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(757)
+			->willReturn($file);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn(FileStatus::DRAFT->value);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn([
+				'total' => 1,
+				'signed' => 0,
+				'pending' => 1,
+				'inProgress' => 0,
+				'errors' => 0,
+				'files' => [
+					['id' => 757, 'name' => 'test.pdf', 'status' => 1, 'statusText' => 'DRAFT'],
+				],
+			]);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->with($uuid)
+			->willReturn(null);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn(false);
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$data = $response->getData();
+
+		$this->assertNotEquals('ERROR', $data['status']);
+		$this->assertArrayNotHasKey('error', $data);
+		$this->assertArrayNotHasKey('file', $data);
+	}
+
+	public function testCheckProgressByUuidWithFileErrorInEnvelope(): void {
+		$uuid = 'test-uuid-file-error';
+		$envelope = new FileEntity();
+		$envelope->setId(100);
+		$envelope->setName('envelope.pdf');
+		$envelope->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+		$envelope->setNodeType('envelope');
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(200);
+		$signRequest->setFileId(100);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(100)
+			->willReturn($envelope);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		// Progress with file error in envelope
+		$progress = [
+			'total' => 2,
+			'signed' => 0,
+			'pending' => 1,
+			'inProgress' => 1,
+			'files' => [
+				[
+					'id' => 101,
+					'name' => 'file1.pdf',
+					'status' => FileStatus::SIGNING_IN_PROGRESS->value,
+					'statusText' => 'SIGNING_IN_PROGRESS',
+				],
+				[
+					'id' => 102,
+					'name' => 'file2.pdf',
+					'status' => FileStatus::DRAFT->value,
+					'statusText' => 'DRAFT',
+					'error' => [
+						'message' => 'File validation failed',
+						'code' => 422,
+					],
+				],
+			],
+		];
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$this->progressService
+			->method('pollForStatusOrErrorChange')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn($progress);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->with($uuid)
+			->willReturn(null);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn(false);
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$data = $response->getData();
+
+		$this->assertArrayHasKey('progress', $data);
+		$this->assertCount(2, $data['progress']['files']);
+		$this->assertArrayNotHasKey('error', $data['progress']['files'][0]);
+		$this->assertArrayHasKey('error', $data['progress']['files'][1]);
+		$this->assertEquals('File validation failed', $data['progress']['files'][1]['error']['message']);
+	}
+
+	public function testRootErrorSuppressedWhenFileErrorsExist(): void {
+		$uuid = 'mixed-error-uuid';
+		$file = new FileEntity();
+		$file->setId(501);
+		$file->setName('parent.pdf');
+		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(601);
+		$signRequest->setFileId(501);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(501)
+			->willReturn($file);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		$progress = [
+			'total' => 1,
+			'signed' => 0,
+			'pending' => 1,
+			'inProgress' => 0,
+			'files' => [
+				[
+					'id' => 701,
+					'name' => 'child.pdf',
+					'status' => FileStatus::DRAFT->value,
+					'statusText' => 'DRAFT',
+					'error' => [
+						'message' => 'Child failed',
+						'code' => 422,
+					],
+				],
+			],
+		];
+
+		$generalError = [
+			'message' => 'General failure',
+			'code' => 500,
+		];
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$this->progressService
+			->method('pollForStatusOrErrorChange')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn($progress);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->with($uuid)
+			->willReturn($generalError);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn(false);
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$data = $response->getData();
+
+		$this->assertEquals('SIGNING_IN_PROGRESS', $data['status']);
+		$this->assertArrayNotHasKey('error', $data, 'Root error should be suppressed when file errors exist');
+		$this->assertArrayNotHasKey('file', $data, 'Should not include file object when errors exist');
+		$this->assertArrayHasKey('progress', $data);
+		$this->assertArrayHasKey('files', $data['progress']);
+		$this->assertArrayHasKey('error', $data['progress']['files'][0]);
+		$this->assertEquals('Child failed', $data['progress']['files'][0]['error']['message']);
+	}
+
+	public function testCheckProgressByUuidNotFound(): void {
+		$uuid = 'non-existent-uuid';
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willThrowException(new \Exception('Sign request not found'));
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+
+		$this->assertEquals(Http::STATUS_NOT_FOUND, $response->getStatus());
+		$data = $response->getData();
+		$this->assertEquals('ERROR', $data['status']);
+	}
+
+	public function testCheckProgressByUuidReadsErrorFromCache(): void {
+		$uuid = 'cache-error-uuid';
+		$file = new FileEntity();
+		$file->setId(777);
+		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(888);
+		$signRequest->setFileId(777);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(777)
+			->willReturn($file);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+
+		$cache = new InMemoryCache();
+		$cache->set(ProgressService::ERROR_KEY_PREFIX . $uuid, [
+			'message' => 'Cached error',
+			'code' => 500,
+		]);
+		$cacheFactory = new InMemoryCacheFactory($cache);
+		$statusCacheService = new StatusCacheService($cacheFactory);
+		$realProgressService = new ProgressService($this->fileMapper, $cacheFactory, $this->signRequestMapper, $statusCacheService);
+
+		$controller = new FileProgressController(
+			$this->request,
+			$this->fileMapper,
+			$this->signRequestMapper,
+			$this->fileService,
+			$this->sessionService,
+			$this->userSession,
+			$this->workerHealthService,
+			$realProgressService,
+		);
+
+		$response = $controller->checkProgressByUuid($uuid);
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+
+		$data = $response->getData();
+		$this->assertEquals('ERROR', $data['status']);
+		$this->assertEquals('Cached error', $data['error']['message']);
+	}
+
+	public function testCheckProgressByUuidNormalizesTimeout(): void {
+		$uuid = 'timeout-uuid';
+		$file = new FileEntity();
+		$file->setId(321);
+		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(654);
+		$signRequest->setFileId(321);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->with(321)
+			->willReturn($file);
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+
+		$this->progressService
+			->expects($this->once())
+			->method('pollForStatusOrErrorChange')
+			->with($file, $signRequest, FileStatus::SIGNING_IN_PROGRESS->value, 1);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn([
+				'total' => 1,
+				'signed' => 0,
+				'pending' => 1,
+				'inProgress' => 0,
+				'files' => [],
+			]);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->with($uuid)
+			->willReturn(null);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn(false);
+
+		$this->controller->checkProgressByUuid($uuid, 0);
+	}
+}
+
+class InMemoryCache implements ICache {
+	private array $data = [];
+
+	public function get($key) {
+		return $this->data[$key] ?? null;
+	}
+
+	public function set($key, $value, $ttl = 0) {
+		$this->data[$key] = $value;
+		return true;
+	}
+
+	public function hasKey($key) {
+		return array_key_exists($key, $this->data);
+	}
+
+	public function remove($key) {
+		unset($this->data[$key]);
+		return true;
+	}
+
+	public function clear($prefix = '') {
+		if ($prefix === '') {
+			$this->data = [];
+			return true;
+		}
+
+		foreach (array_keys($this->data) as $key) {
+			if (str_starts_with($key, $prefix)) {
+				unset($this->data[$key]);
+			}
+		}
+		return true;
+	}
+
+	public static function isAvailable(): bool {
+		return true;
+	}
+}
+
+class InMemoryCacheFactory implements ICacheFactory {
+	public function __construct(
+		private ICache $cache,
+	) {
+	}
+
+	public function isAvailable(): bool {
+		return true;
+	}
+
+	public function isLocalCacheAvailable(): bool {
+		return true;
+	}
+
+	public function createLocking(string $prefix = ''): IMemcache {
+		return new ArrayCache();
+	}
+
+	public function createDistributed(string $prefix = ''): ICache {
+		return $this->cache;
+	}
+
+	public function createLocal(string $prefix = ''): ICache {
+		return new InMemoryCache();
+	}
+
+	public function createInMemory(int $capacity = 512): ICache {
+		return new InMemoryCache();
+	}
+}

From 4065bd663e3823247c26f605dd1b483c9a2623dd Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:00:24 -0300
Subject: [PATCH 13/34] chore: regenerate OpenAPI spec and TypeScript types

Update OpenAPI specifications and TypeScript types to reflect
new error fields in FileProgressController responses.

Generated from updated PHP annotations.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 openapi-full.json                 | 6 ++++++
 openapi.json                      | 6 ++++++
 src/types/openapi/openapi-full.ts | 3 +++
 src/types/openapi/openapi.ts      | 3 +++
 4 files changed, 18 insertions(+)

diff --git a/openapi-full.json b/openapi-full.json
index 2b1f9c9d86..de3fd96882 100644
--- a/openapi-full.json
+++ b/openapi-full.json
@@ -6252,6 +6252,12 @@
                                                         },
                                                         "file": {
                                                             "$ref": "#/components/schemas/ValidateFile"
+                                                        },
+                                                        "error": {
+                                                            "type": "object",
+                                                            "additionalProperties": {
+                                                                "type": "object"
+                                                            }
                                                         }
                                                     }
                                                 }
diff --git a/openapi.json b/openapi.json
index 823a8bb8a8..21cb2547f4 100644
--- a/openapi.json
+++ b/openapi.json
@@ -6102,6 +6102,12 @@
                                                         },
                                                         "file": {
                                                             "$ref": "#/components/schemas/ValidateFile"
+                                                        },
+                                                        "error": {
+                                                            "type": "object",
+                                                            "additionalProperties": {
+                                                                "type": "object"
+                                                            }
                                                         }
                                                     }
                                                 }
diff --git a/src/types/openapi/openapi-full.ts b/src/types/openapi/openapi-full.ts
index 9bda5e25f6..b39826514b 100644
--- a/src/types/openapi/openapi-full.ts
+++ b/src/types/openapi/openapi-full.ts
@@ -3983,6 +3983,9 @@ export interface operations {
                                     [key: string]: Record<string, never>;
                                 };
                                 file?: components["schemas"]["ValidateFile"];
+                                error?: {
+                                    [key: string]: Record<string, never>;
+                                };
                             };
                         };
                     };
diff --git a/src/types/openapi/openapi.ts b/src/types/openapi/openapi.ts
index ffb4d6b1a2..3c793dcd0c 100644
--- a/src/types/openapi/openapi.ts
+++ b/src/types/openapi/openapi.ts
@@ -3464,6 +3464,9 @@ export interface operations {
                                     [key: string]: Record<string, never>;
                                 };
                                 file?: components["schemas"]["ValidateFile"];
+                                error?: {
+                                    [key: string]: Record<string, never>;
+                                };
                             };
                         };
                     };

From acbe0bfa72095abe2db4406667ecd0b2db388bf7 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:06:12 -0300
Subject: [PATCH 14/34] fix: reduce mixed usage and use specific types

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Controller/FileProgressController.php | 20 +++++++++++++---
 lib/ResponseDefinitions.php               | 29 +++++++++++++++++++++++
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/lib/Controller/FileProgressController.php b/lib/Controller/FileProgressController.php
index 55b5a2c8f3..83ba51faff 100644
--- a/lib/Controller/FileProgressController.php
+++ b/lib/Controller/FileProgressController.php
@@ -30,6 +30,8 @@
 
 /**
  * @psalm-import-type LibresignValidateFile from \OCA\Libresign\ResponseDefinitions
+ * @psalm-import-type LibresignProgressPayload from \OCA\Libresign\ResponseDefinitions
+ * @psalm-import-type LibresignProgressError from \OCA\Libresign\ResponseDefinitions
  */
 class FileProgressController extends AEnvironmentAwareController {
 	public function __construct(
@@ -53,7 +55,7 @@ public function __construct(
 	 *
 	 * @param string $uuid Sign request UUID
 	 * @param int $timeout Maximum seconds to wait (default 30)
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
 	 *
 	 * 200: Status and progress returned
 	 * 404: Sign request not found
@@ -93,16 +95,28 @@ public function checkProgressByUuid(string $uuid, int $timeout = 30): DataRespon
 	 * @param FileEntity $file The file entity
 	 * @param SignRequestEntity $signRequest The sign request entity
 	 * @param int $status Current status code
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>
-	 * @psalm-return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: array<string, mixed>, file?: LibresignValidateFile, error?: array<string, mixed>}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>
+	 * @psalm-return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>
 	 */
 	private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRequest, int $status): DataResponse {
 		$statusEnum = FileStatus::tryFrom($status);
+		/** @psalm-var LibresignProgressPayload $progress */
 		$progress = $this->progressService->getSignRequestProgress($file, $signRequest);
+		/** @psalm-var LibresignProgressError|null $error */
 		$error = $this->progressService->getSignRequestError($signRequest->getUuid());
 
 		$hasFileErrors = !empty($progress['files']) && $this->hasErrorsInFiles($progress['files']);
 
+		/** @psalm-var array{
+		 *     status: string,
+		 *     statusCode: int,
+		 *     statusText: string,
+		 *     fileId: int,
+		 *     progress: LibresignProgressPayload,
+		 *     file?: LibresignValidateFile,
+		 *     error?: LibresignProgressError
+		 * } $response
+		 */
 		$response = [
 			'status' => $statusEnum?->name ?? 'UNKNOWN',
 			'statusCode' => $status,
diff --git a/lib/ResponseDefinitions.php b/lib/ResponseDefinitions.php
index 9a4ef13e82..2ed3cc6757 100644
--- a/lib/ResponseDefinitions.php
+++ b/lib/ResponseDefinitions.php
@@ -242,6 +242,35 @@
  *     }[],
  *     visibleElements?: LibresignVisibleElement[],
  * }
+ * @psalm-type LibresignProgressError = array{
+ *     message: string,
+ *     code?: int,
+ *     timestamp?: string,
+ *     fileId?: int,
+ *     signRequestId?: int,
+ *     signRequestUuid?: string,
+ * }
+ * @psalm-type LibresignProgressFile = array{
+ *     id: int,
+ *     name: string,
+ *     status: int,
+ *     statusText: string,
+ *     error?: LibresignProgressError,
+ * }
+ * @psalm-type LibresignProgressPayload = array{
+ *     total: int,
+ *     signed: int,
+ *     inProgress: int,
+ *     pending: int,
+ *     errors?: int,
+ *     files?: list<LibresignProgressFile>,
+ *     signers?: list<array{
+ *         id: int,
+ *         displayName: string,
+ *         signed: ?string,
+ *         status: int,
+ *     }>,
+ * }
  * @psalm-type LibresignFileListItem = array{
  *     fileId: int,
  *     id: int,

From dbb40ab9ffc5e1596a5de7483a4a5dc3c1990072 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:06:27 -0300
Subject: [PATCH 15/34] fix: update documentation

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 openapi-full.json                 | 133 ++++++++++++++++++++++++++++--
 openapi.json                      | 133 ++++++++++++++++++++++++++++--
 src/types/openapi/openapi-full.ts |  49 +++++++++--
 src/types/openapi/openapi.ts      |  49 +++++++++--
 4 files changed, 336 insertions(+), 28 deletions(-)

diff --git a/openapi-full.json b/openapi-full.json
index de3fd96882..ee824c51d7 100644
--- a/openapi-full.json
+++ b/openapi-full.json
@@ -1006,6 +1006,129 @@
                     }
                 }
             },
+            "ProgressError": {
+                "type": "object",
+                "required": [
+                    "message"
+                ],
+                "properties": {
+                    "message": {
+                        "type": "string"
+                    },
+                    "code": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "timestamp": {
+                        "type": "string"
+                    },
+                    "fileId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signRequestId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signRequestUuid": {
+                        "type": "string"
+                    }
+                }
+            },
+            "ProgressFile": {
+                "type": "object",
+                "required": [
+                    "id",
+                    "name",
+                    "status",
+                    "statusText"
+                ],
+                "properties": {
+                    "id": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "status": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "statusText": {
+                        "type": "string"
+                    },
+                    "error": {
+                        "$ref": "#/components/schemas/ProgressError"
+                    }
+                }
+            },
+            "ProgressPayload": {
+                "type": "object",
+                "required": [
+                    "total",
+                    "signed",
+                    "inProgress",
+                    "pending"
+                ],
+                "properties": {
+                    "total": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signed": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "inProgress": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "pending": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "errors": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "files": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/ProgressFile"
+                        }
+                    },
+                    "signers": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "required": [
+                                "id",
+                                "displayName",
+                                "signed",
+                                "status"
+                            ],
+                            "properties": {
+                                "id": {
+                                    "type": "integer",
+                                    "format": "int64"
+                                },
+                                "displayName": {
+                                    "type": "string"
+                                },
+                                "signed": {
+                                    "type": "string",
+                                    "nullable": true
+                                },
+                                "status": {
+                                    "type": "integer",
+                                    "format": "int64"
+                                }
+                            }
+                        }
+                    }
+                }
+            },
             "PublicCapabilities": {
                 "type": "object",
                 "properties": {
@@ -6245,19 +6368,13 @@
                                                             "format": "int64"
                                                         },
                                                         "progress": {
-                                                            "type": "object",
-                                                            "additionalProperties": {
-                                                                "type": "object"
-                                                            }
+                                                            "$ref": "#/components/schemas/ProgressPayload"
                                                         },
                                                         "file": {
                                                             "$ref": "#/components/schemas/ValidateFile"
                                                         },
                                                         "error": {
-                                                            "type": "object",
-                                                            "additionalProperties": {
-                                                                "type": "object"
-                                                            }
+                                                            "$ref": "#/components/schemas/ProgressError"
                                                         }
                                                     }
                                                 }
diff --git a/openapi.json b/openapi.json
index 21cb2547f4..0df05f8bc9 100644
--- a/openapi.json
+++ b/openapi.json
@@ -921,6 +921,129 @@
                     }
                 }
             },
+            "ProgressError": {
+                "type": "object",
+                "required": [
+                    "message"
+                ],
+                "properties": {
+                    "message": {
+                        "type": "string"
+                    },
+                    "code": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "timestamp": {
+                        "type": "string"
+                    },
+                    "fileId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signRequestId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signRequestUuid": {
+                        "type": "string"
+                    }
+                }
+            },
+            "ProgressFile": {
+                "type": "object",
+                "required": [
+                    "id",
+                    "name",
+                    "status",
+                    "statusText"
+                ],
+                "properties": {
+                    "id": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "status": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "statusText": {
+                        "type": "string"
+                    },
+                    "error": {
+                        "$ref": "#/components/schemas/ProgressError"
+                    }
+                }
+            },
+            "ProgressPayload": {
+                "type": "object",
+                "required": [
+                    "total",
+                    "signed",
+                    "inProgress",
+                    "pending"
+                ],
+                "properties": {
+                    "total": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "signed": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "inProgress": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "pending": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "errors": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "files": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/ProgressFile"
+                        }
+                    },
+                    "signers": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "required": [
+                                "id",
+                                "displayName",
+                                "signed",
+                                "status"
+                            ],
+                            "properties": {
+                                "id": {
+                                    "type": "integer",
+                                    "format": "int64"
+                                },
+                                "displayName": {
+                                    "type": "string"
+                                },
+                                "signed": {
+                                    "type": "string",
+                                    "nullable": true
+                                },
+                                "status": {
+                                    "type": "integer",
+                                    "format": "int64"
+                                }
+                            }
+                        }
+                    }
+                }
+            },
             "PublicCapabilities": {
                 "type": "object",
                 "properties": {
@@ -6095,19 +6218,13 @@
                                                             "format": "int64"
                                                         },
                                                         "progress": {
-                                                            "type": "object",
-                                                            "additionalProperties": {
-                                                                "type": "object"
-                                                            }
+                                                            "$ref": "#/components/schemas/ProgressPayload"
                                                         },
                                                         "file": {
                                                             "$ref": "#/components/schemas/ValidateFile"
                                                         },
                                                         "error": {
-                                                            "type": "object",
-                                                            "additionalProperties": {
-                                                                "type": "object"
-                                                            }
+                                                            "$ref": "#/components/schemas/ProgressError"
                                                         }
                                                     }
                                                 }
diff --git a/src/types/openapi/openapi-full.ts b/src/types/openapi/openapi-full.ts
index b39826514b..5c0b9c69a6 100644
--- a/src/types/openapi/openapi-full.ts
+++ b/src/types/openapi/openapi-full.ts
@@ -1822,6 +1822,47 @@ export type components = {
             OID: string;
             CPS: string;
         };
+        ProgressError: {
+            message: string;
+            /** Format: int64 */
+            code?: number;
+            timestamp?: string;
+            /** Format: int64 */
+            fileId?: number;
+            /** Format: int64 */
+            signRequestId?: number;
+            signRequestUuid?: string;
+        };
+        ProgressFile: {
+            /** Format: int64 */
+            id: number;
+            name: string;
+            /** Format: int64 */
+            status: number;
+            statusText: string;
+            error?: components["schemas"]["ProgressError"];
+        };
+        ProgressPayload: {
+            /** Format: int64 */
+            total: number;
+            /** Format: int64 */
+            signed: number;
+            /** Format: int64 */
+            inProgress: number;
+            /** Format: int64 */
+            pending: number;
+            /** Format: int64 */
+            errors?: number;
+            files?: components["schemas"]["ProgressFile"][];
+            signers?: {
+                /** Format: int64 */
+                id: number;
+                displayName: string;
+                signed: string | null;
+                /** Format: int64 */
+                status: number;
+            }[];
+        };
         PublicCapabilities: {
             libresign?: components["schemas"]["Capabilities"];
         };
@@ -3979,13 +4020,9 @@ export interface operations {
                                 statusText: string;
                                 /** Format: int64 */
                                 fileId: number;
-                                progress: {
-                                    [key: string]: Record<string, never>;
-                                };
+                                progress: components["schemas"]["ProgressPayload"];
                                 file?: components["schemas"]["ValidateFile"];
-                                error?: {
-                                    [key: string]: Record<string, never>;
-                                };
+                                error?: components["schemas"]["ProgressError"];
                             };
                         };
                     };
diff --git a/src/types/openapi/openapi.ts b/src/types/openapi/openapi.ts
index 3c793dcd0c..0f86e1c429 100644
--- a/src/types/openapi/openapi.ts
+++ b/src/types/openapi/openapi.ts
@@ -1321,6 +1321,47 @@ export type components = {
             last: string | null;
             first: string | null;
         };
+        ProgressError: {
+            message: string;
+            /** Format: int64 */
+            code?: number;
+            timestamp?: string;
+            /** Format: int64 */
+            fileId?: number;
+            /** Format: int64 */
+            signRequestId?: number;
+            signRequestUuid?: string;
+        };
+        ProgressFile: {
+            /** Format: int64 */
+            id: number;
+            name: string;
+            /** Format: int64 */
+            status: number;
+            statusText: string;
+            error?: components["schemas"]["ProgressError"];
+        };
+        ProgressPayload: {
+            /** Format: int64 */
+            total: number;
+            /** Format: int64 */
+            signed: number;
+            /** Format: int64 */
+            inProgress: number;
+            /** Format: int64 */
+            pending: number;
+            /** Format: int64 */
+            errors?: number;
+            files?: components["schemas"]["ProgressFile"][];
+            signers?: {
+                /** Format: int64 */
+                id: number;
+                displayName: string;
+                signed: string | null;
+                /** Format: int64 */
+                status: number;
+            }[];
+        };
         PublicCapabilities: {
             libresign?: components["schemas"]["Capabilities"];
         };
@@ -3460,13 +3501,9 @@ export interface operations {
                                 statusText: string;
                                 /** Format: int64 */
                                 fileId: number;
-                                progress: {
-                                    [key: string]: Record<string, never>;
-                                };
+                                progress: components["schemas"]["ProgressPayload"];
                                 file?: components["schemas"]["ValidateFile"];
-                                error?: {
-                                    [key: string]: Record<string, never>;
-                                };
+                                error?: components["schemas"]["ProgressError"];
                             };
                         };
                     };

From cca2b8385b3215bdf1eed02f9064ff8c6dd037cd Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:58:15 -0300
Subject: [PATCH 16/34] chore: move cache ttl to a constant

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Service/SignRequest/Error/SignRequestErrorReporter.php | 2 +-
 lib/Service/SignRequest/ProgressService.php                | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/lib/Service/SignRequest/Error/SignRequestErrorReporter.php b/lib/Service/SignRequest/Error/SignRequestErrorReporter.php
index d7bbe8141f..4c8d581633 100644
--- a/lib/Service/SignRequest/Error/SignRequestErrorReporter.php
+++ b/lib/Service/SignRequest/Error/SignRequestErrorReporter.php
@@ -41,7 +41,7 @@ private function maybeStoreProgressError(string $level, array $context): void {
 			return;
 		}
 
-		$ttl = (int)($context['ttl'] ?? 300);
+		$ttl = (int)($context['ttl'] ?? ProgressService::ERROR_CACHE_TTL);
 		$fileId = $context['fileId'] ?? null;
 		$signRequestId = $context['signRequestId'] ?? null;
 		$payload = ErrorPayloadBuilder::fromException(
diff --git a/lib/Service/SignRequest/ProgressService.php b/lib/Service/SignRequest/ProgressService.php
index 055501dfdb..38c7168a0d 100644
--- a/lib/Service/SignRequest/ProgressService.php
+++ b/lib/Service/SignRequest/ProgressService.php
@@ -33,6 +33,7 @@ class ProgressService {
 	private ICache $cache;
 	public const ERROR_KEY_PREFIX = 'libresign_sign_request_error_';
 	public const FILE_ERROR_KEY_PREFIX = 'libresign_file_error_';
+	public const ERROR_CACHE_TTL = 300;
 	/** @var array<string, array<string, mixed>> */
 	private array $signRequestErrors = [];
 	/** @var array<string, array<string, mixed>> */
@@ -123,7 +124,7 @@ private function pollForStatusChangeInternal(
 		return $initialStatus;
 	}
 
-	public function setSignRequestError(string $uuid, array $error, int $ttl = 300): void {
+	public function setSignRequestError(string $uuid, array $error, int $ttl = self::ERROR_CACHE_TTL): void {
 		$this->signRequestErrors[$uuid] = $error;
 		$this->cache->set(self::ERROR_KEY_PREFIX . $uuid, $error, $ttl);
 		$this->storeSignRequestErrorInMetadata($uuid, $error);
@@ -159,7 +160,7 @@ private function hasAnySignRequestError(array $uuids): bool {
 		return false;
 	}
 
-	public function setFileError(string $uuid, int $fileId, array $error, int $ttl = 300): void {
+	public function setFileError(string $uuid, int $fileId, array $error, int $ttl = self::ERROR_CACHE_TTL): void {
 		$key = $this->buildFileErrorKey($uuid, $fileId);
 		$this->fileErrors[$key] = $error;
 		$this->cache->set($key, $error, $ttl);

From 58240e9d767ec7d70916ebebbf8336110218550b Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 12:58:58 -0300
Subject: [PATCH 17/34] fix: cs

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 tests/php/Unit/Service/SignFileServiceTest.php         | 10 +++++-----
 .../Unit/Service/SignRequest/ProgressServiceTest.php   |  4 ++--
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/tests/php/Unit/Service/SignFileServiceTest.php b/tests/php/Unit/Service/SignFileServiceTest.php
index b13f937adb..a16c681aec 100644
--- a/tests/php/Unit/Service/SignFileServiceTest.php
+++ b/tests/php/Unit/Service/SignFileServiceTest.php
@@ -103,11 +103,11 @@ final class SignFileServiceTest extends \OCA\Libresign\Tests\Unit\TestCase {
 	private PdfSignatureDetectionService&MockObject $pdfSignatureDetectionService;
 	private \OCA\Libresign\Service\SequentialSigningService&MockObject $sequentialSigningService;
 	private FileStatusService&MockObject $fileStatusService;
-private SigningCoordinatorService&MockObject $signingCoordinatorService;
-private IJobList&MockObject $jobList;
-private ICredentialsManager&MockObject $credentialsManager;
-private StatusService&MockObject $statusService;
-private EnvelopeStatusDeterminer&MockObject $envelopeStatusDeterminer;
+	private SigningCoordinatorService&MockObject $signingCoordinatorService;
+	private IJobList&MockObject $jobList;
+	private ICredentialsManager&MockObject $credentialsManager;
+	private StatusService&MockObject $statusService;
+	private EnvelopeStatusDeterminer&MockObject $envelopeStatusDeterminer;
 	private TsaValidationService&MockObject $tsaValidationService;
 	private CertificateValidityPolicy $certificateValidityPolicy;
 	private PfxProvider $pfxProvider;
diff --git a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
index fa10c593d4..11159ac806 100644
--- a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
+++ b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
@@ -69,7 +69,7 @@ public function testPollReturnsNewStatusWhenCacheChanges(): void {
 
 		$sequence = [$initialStatus, $initialStatus, $newStatus];
 		$index = 0;
-		
+
 		// Create a fresh mock to avoid conflicts with setUp()
 		$this->statusCacheService = $this->createMock(StatusCacheService::class);
 		$this->statusCacheService
@@ -80,7 +80,7 @@ public function testPollReturnsNewStatusWhenCacheChanges(): void {
 				$index++;
 				return $value;
 			});
-		
+
 		// Recreate service with the new mock
 		$this->service = new ProgressService(
 			$this->fileMapper,

From 6e15ddb33f43557944849ee7357c2e82615169d8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 13:03:35 -0300
Subject: [PATCH 18/34] feat: add new response type to clean code

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Controller/FileProgressController.php | 18 +++++-------------
 lib/ResponseDefinitions.php               |  9 +++++++++
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/lib/Controller/FileProgressController.php b/lib/Controller/FileProgressController.php
index 83ba51faff..af75f6a45d 100644
--- a/lib/Controller/FileProgressController.php
+++ b/lib/Controller/FileProgressController.php
@@ -32,6 +32,7 @@
  * @psalm-import-type LibresignValidateFile from \OCA\Libresign\ResponseDefinitions
  * @psalm-import-type LibresignProgressPayload from \OCA\Libresign\ResponseDefinitions
  * @psalm-import-type LibresignProgressError from \OCA\Libresign\ResponseDefinitions
+ * @psalm-import-type LibresignProgressResponse from \OCA\Libresign\ResponseDefinitions
  */
 class FileProgressController extends AEnvironmentAwareController {
 	public function __construct(
@@ -55,7 +56,7 @@ public function __construct(
 	 *
 	 * @param string $uuid Sign request UUID
 	 * @param int $timeout Maximum seconds to wait (default 30)
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, LibresignProgressResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{message: string, status: string}, array{}>
 	 *
 	 * 200: Status and progress returned
 	 * 404: Sign request not found
@@ -95,8 +96,8 @@ public function checkProgressByUuid(string $uuid, int $timeout = 30): DataRespon
 	 * @param FileEntity $file The file entity
 	 * @param SignRequestEntity $signRequest The sign request entity
 	 * @param int $status Current status code
-	 * @return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>
-	 * @psalm-return DataResponse<Http::STATUS_OK, array{status: string, statusCode: int, statusText: string, fileId: int, progress: LibresignProgressPayload, file?: LibresignValidateFile, error?: LibresignProgressError}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, LibresignProgressResponse, array{}>
+	 * @psalm-return DataResponse<Http::STATUS_OK, LibresignProgressResponse, array{}>
 	 */
 	private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRequest, int $status): DataResponse {
 		$statusEnum = FileStatus::tryFrom($status);
@@ -107,16 +108,7 @@ private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRe
 
 		$hasFileErrors = !empty($progress['files']) && $this->hasErrorsInFiles($progress['files']);
 
-		/** @psalm-var array{
-		 *     status: string,
-		 *     statusCode: int,
-		 *     statusText: string,
-		 *     fileId: int,
-		 *     progress: LibresignProgressPayload,
-		 *     file?: LibresignValidateFile,
-		 *     error?: LibresignProgressError
-		 * } $response
-		 */
+		/** @psalm-var LibresignProgressResponse $response */
 		$response = [
 			'status' => $statusEnum?->name ?? 'UNKNOWN',
 			'statusCode' => $status,
diff --git a/lib/ResponseDefinitions.php b/lib/ResponseDefinitions.php
index 2ed3cc6757..b2efa5f24a 100644
--- a/lib/ResponseDefinitions.php
+++ b/lib/ResponseDefinitions.php
@@ -271,6 +271,15 @@
  *         status: int,
  *     }>,
  * }
+ * @psalm-type LibresignProgressResponse = array{
+ *     status: string,
+ *     statusCode: int,
+ *     statusText: string,
+ *     fileId: int,
+ *     progress: LibresignProgressPayload,
+ *     file?: LibresignValidateFile,
+ *     error?: LibresignProgressError,
+ * }
  * @psalm-type LibresignFileListItem = array{
  *     fileId: int,
  *     id: int,

From 485411df4b3fbd7c9690710368768e9d9dea3961 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 13:04:18 -0300
Subject: [PATCH 19/34] chore: update documentation

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 openapi-full.json                 | 69 ++++++++++++++++---------------
 openapi.json                      | 69 ++++++++++++++++---------------
 src/types/openapi/openapi-full.ts | 23 ++++++-----
 src/types/openapi/openapi.ts      | 23 ++++++-----
 4 files changed, 96 insertions(+), 88 deletions(-)

diff --git a/openapi-full.json b/openapi-full.json
index ee824c51d7..e94bdb2326 100644
--- a/openapi-full.json
+++ b/openapi-full.json
@@ -1129,6 +1129,41 @@
                     }
                 }
             },
+            "ProgressResponse": {
+                "type": "object",
+                "required": [
+                    "status",
+                    "statusCode",
+                    "statusText",
+                    "fileId",
+                    "progress"
+                ],
+                "properties": {
+                    "status": {
+                        "type": "string"
+                    },
+                    "statusCode": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "statusText": {
+                        "type": "string"
+                    },
+                    "fileId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "progress": {
+                        "$ref": "#/components/schemas/ProgressPayload"
+                    },
+                    "file": {
+                        "$ref": "#/components/schemas/ValidateFile"
+                    },
+                    "error": {
+                        "$ref": "#/components/schemas/ProgressError"
+                    }
+                }
+            },
             "PublicCapabilities": {
                 "type": "object",
                 "properties": {
@@ -6344,39 +6379,7 @@
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
                                                 "data": {
-                                                    "type": "object",
-                                                    "required": [
-                                                        "status",
-                                                        "statusCode",
-                                                        "statusText",
-                                                        "fileId",
-                                                        "progress"
-                                                    ],
-                                                    "properties": {
-                                                        "status": {
-                                                            "type": "string"
-                                                        },
-                                                        "statusCode": {
-                                                            "type": "integer",
-                                                            "format": "int64"
-                                                        },
-                                                        "statusText": {
-                                                            "type": "string"
-                                                        },
-                                                        "fileId": {
-                                                            "type": "integer",
-                                                            "format": "int64"
-                                                        },
-                                                        "progress": {
-                                                            "$ref": "#/components/schemas/ProgressPayload"
-                                                        },
-                                                        "file": {
-                                                            "$ref": "#/components/schemas/ValidateFile"
-                                                        },
-                                                        "error": {
-                                                            "$ref": "#/components/schemas/ProgressError"
-                                                        }
-                                                    }
+                                                    "$ref": "#/components/schemas/ProgressResponse"
                                                 }
                                             }
                                         }
diff --git a/openapi.json b/openapi.json
index 0df05f8bc9..53fbc4a2fe 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1044,6 +1044,41 @@
                     }
                 }
             },
+            "ProgressResponse": {
+                "type": "object",
+                "required": [
+                    "status",
+                    "statusCode",
+                    "statusText",
+                    "fileId",
+                    "progress"
+                ],
+                "properties": {
+                    "status": {
+                        "type": "string"
+                    },
+                    "statusCode": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "statusText": {
+                        "type": "string"
+                    },
+                    "fileId": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "progress": {
+                        "$ref": "#/components/schemas/ProgressPayload"
+                    },
+                    "file": {
+                        "$ref": "#/components/schemas/ValidateFile"
+                    },
+                    "error": {
+                        "$ref": "#/components/schemas/ProgressError"
+                    }
+                }
+            },
             "PublicCapabilities": {
                 "type": "object",
                 "properties": {
@@ -6194,39 +6229,7 @@
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
                                                 "data": {
-                                                    "type": "object",
-                                                    "required": [
-                                                        "status",
-                                                        "statusCode",
-                                                        "statusText",
-                                                        "fileId",
-                                                        "progress"
-                                                    ],
-                                                    "properties": {
-                                                        "status": {
-                                                            "type": "string"
-                                                        },
-                                                        "statusCode": {
-                                                            "type": "integer",
-                                                            "format": "int64"
-                                                        },
-                                                        "statusText": {
-                                                            "type": "string"
-                                                        },
-                                                        "fileId": {
-                                                            "type": "integer",
-                                                            "format": "int64"
-                                                        },
-                                                        "progress": {
-                                                            "$ref": "#/components/schemas/ProgressPayload"
-                                                        },
-                                                        "file": {
-                                                            "$ref": "#/components/schemas/ValidateFile"
-                                                        },
-                                                        "error": {
-                                                            "$ref": "#/components/schemas/ProgressError"
-                                                        }
-                                                    }
+                                                    "$ref": "#/components/schemas/ProgressResponse"
                                                 }
                                             }
                                         }
diff --git a/src/types/openapi/openapi-full.ts b/src/types/openapi/openapi-full.ts
index 5c0b9c69a6..73ca403cad 100644
--- a/src/types/openapi/openapi-full.ts
+++ b/src/types/openapi/openapi-full.ts
@@ -1863,6 +1863,17 @@ export type components = {
                 status: number;
             }[];
         };
+        ProgressResponse: {
+            status: string;
+            /** Format: int64 */
+            statusCode: number;
+            statusText: string;
+            /** Format: int64 */
+            fileId: number;
+            progress: components["schemas"]["ProgressPayload"];
+            file?: components["schemas"]["ValidateFile"];
+            error?: components["schemas"]["ProgressError"];
+        };
         PublicCapabilities: {
             libresign?: components["schemas"]["Capabilities"];
         };
@@ -4013,17 +4024,7 @@ export interface operations {
                     "application/json": {
                         ocs: {
                             meta: components["schemas"]["OCSMeta"];
-                            data: {
-                                status: string;
-                                /** Format: int64 */
-                                statusCode: number;
-                                statusText: string;
-                                /** Format: int64 */
-                                fileId: number;
-                                progress: components["schemas"]["ProgressPayload"];
-                                file?: components["schemas"]["ValidateFile"];
-                                error?: components["schemas"]["ProgressError"];
-                            };
+                            data: components["schemas"]["ProgressResponse"];
                         };
                     };
                 };
diff --git a/src/types/openapi/openapi.ts b/src/types/openapi/openapi.ts
index 0f86e1c429..2486840978 100644
--- a/src/types/openapi/openapi.ts
+++ b/src/types/openapi/openapi.ts
@@ -1362,6 +1362,17 @@ export type components = {
                 status: number;
             }[];
         };
+        ProgressResponse: {
+            status: string;
+            /** Format: int64 */
+            statusCode: number;
+            statusText: string;
+            /** Format: int64 */
+            fileId: number;
+            progress: components["schemas"]["ProgressPayload"];
+            file?: components["schemas"]["ValidateFile"];
+            error?: components["schemas"]["ProgressError"];
+        };
         PublicCapabilities: {
             libresign?: components["schemas"]["Capabilities"];
         };
@@ -3494,17 +3505,7 @@ export interface operations {
                     "application/json": {
                         ocs: {
                             meta: components["schemas"]["OCSMeta"];
-                            data: {
-                                status: string;
-                                /** Format: int64 */
-                                statusCode: number;
-                                statusText: string;
-                                /** Format: int64 */
-                                fileId: number;
-                                progress: components["schemas"]["ProgressPayload"];
-                                file?: components["schemas"]["ValidateFile"];
-                                error?: components["schemas"]["ProgressError"];
-                            };
+                            data: components["schemas"]["ProgressResponse"];
                         };
                     };
                 };

From 53eca6d33ad47b9bba0eee8b9ebdf0dc2f26eebe Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 13:07:45 -0300
Subject: [PATCH 20/34] fix: update docblock

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Controller/FileProgressController.php | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/lib/Controller/FileProgressController.php b/lib/Controller/FileProgressController.php
index af75f6a45d..135eaefcbf 100644
--- a/lib/Controller/FileProgressController.php
+++ b/lib/Controller/FileProgressController.php
@@ -145,9 +145,7 @@ private function buildStatusResponse(FileEntity $file, SignRequestEntity $signRe
 	}
 
 	/**
-	 * Check if any file in the files list has an error
-	 *
-	 * @param array<int, array<string, mixed>> $files
+	 * @param list<LibresignProgressFile> $files
 	 */
 	private function hasErrorsInFiles(array $files): bool {
 		foreach ($files as $file) {

From bcf2143a635ba1625b29a080cdf0798228924f21 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 14:22:38 -0300
Subject: [PATCH 21/34] fix: typing

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Service/SignRequest/ProgressService.php | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/lib/Service/SignRequest/ProgressService.php b/lib/Service/SignRequest/ProgressService.php
index 38c7168a0d..9f9072c1a8 100644
--- a/lib/Service/SignRequest/ProgressService.php
+++ b/lib/Service/SignRequest/ProgressService.php
@@ -34,9 +34,9 @@ class ProgressService {
 	public const ERROR_KEY_PREFIX = 'libresign_sign_request_error_';
 	public const FILE_ERROR_KEY_PREFIX = 'libresign_file_error_';
 	public const ERROR_CACHE_TTL = 300;
-	/** @var array<string, array<string, mixed>> */
+	/** @var array<string, array> */
 	private array $signRequestErrors = [];
-	/** @var array<string, array<string, mixed>> */
+	/** @var array<string, array> */
 	private array $fileErrors = [];
 
 	public function __construct(
@@ -130,7 +130,6 @@ public function setSignRequestError(string $uuid, array $error, int $ttl = self:
 		$this->storeSignRequestErrorInMetadata($uuid, $error);
 	}
 
-
 	public function getSignRequestError(string $uuid): ?array {
 		$error = $this->cache->get(self::ERROR_KEY_PREFIX . $uuid);
 		if ($error === false || $error === null) {

From 87fb43efb838875d02f7a9ec656d6e870b3a82c1 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 14:35:32 -0300
Subject: [PATCH 22/34] fix: psalm

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Controller/FileProgressController.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lib/Controller/FileProgressController.php b/lib/Controller/FileProgressController.php
index 135eaefcbf..672da46436 100644
--- a/lib/Controller/FileProgressController.php
+++ b/lib/Controller/FileProgressController.php
@@ -33,6 +33,7 @@
  * @psalm-import-type LibresignProgressPayload from \OCA\Libresign\ResponseDefinitions
  * @psalm-import-type LibresignProgressError from \OCA\Libresign\ResponseDefinitions
  * @psalm-import-type LibresignProgressResponse from \OCA\Libresign\ResponseDefinitions
+ * @psalm-import-type LibresignProgressFile from \OCA\Libresign\ResponseDefinitions
  */
 class FileProgressController extends AEnvironmentAwareController {
 	public function __construct(

From f801e28308386cd4a82f95d4f0b547f87cb49817 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 14:38:55 -0300
Subject: [PATCH 23/34] refactor: remove empty row

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 lib/Service/SignJobCoordinator.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/Service/SignJobCoordinator.php b/lib/Service/SignJobCoordinator.php
index 0d507007ef..f7e2fef4f9 100644
--- a/lib/Service/SignJobCoordinator.php
+++ b/lib/Service/SignJobCoordinator.php
@@ -199,5 +199,4 @@ private function deleteCredentials(string $userId, ?string $credentialsId): void
 		}
 		$this->credentialsManager->delete($userId, $credentialsId);
 	}
-
 }

From 0b8f9032c14768a4ab682fe09c6747a203f510f6 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 17:58:31 -0300
Subject: [PATCH 24/34] fix: indent

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/components/validation/SigningProgress.vue | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/validation/SigningProgress.vue b/src/components/validation/SigningProgress.vue
index 4296bb936d..ccaed073ee 100644
--- a/src/components/validation/SigningProgress.vue
+++ b/src/components/validation/SigningProgress.vue
@@ -34,10 +34,10 @@
 					<div v-for="file in progress.files" :key="file.id" class="file-item">
 						<div class="file-row">
 							<span class="file-name">{{ file.name }}</span>
-						<span :class="['status-pill', `status-${getFileStatusMeta(file).class}`]">
-							<NcIconSvgWrapper :path="getFileStatusMeta(file).icon" />
-							{{ getFileStatusMeta(file).label }}
-						</span>
+							<span :class="['status-pill', `status-${getFileStatusMeta(file).class}`]">
+								<NcIconSvgWrapper :path="getFileStatusMeta(file).icon" />
+								{{ getFileStatusMeta(file).label }}
+							</span>
 						</div>
 						<div v-if="file.error && file.error.message" class="file-error">
 							<span class="error-icon">⚠</span>

From 3f69d2105658eea239710abbcd810f375d12abe8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:11:06 -0300
Subject: [PATCH 25/34] chore: clean code

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/components/validation/SigningProgress.vue | 205 +++++++++---------
 1 file changed, 97 insertions(+), 108 deletions(-)

diff --git a/src/components/validation/SigningProgress.vue b/src/components/validation/SigningProgress.vue
index ccaed073ee..a690594593 100644
--- a/src/components/validation/SigningProgress.vue
+++ b/src/components/validation/SigningProgress.vue
@@ -85,7 +85,6 @@ export default {
 			isPolling: false,
 			pollingInterval: null,
 			progress: null,
-			currentStatusCode: null,
 			statusMap: buildStatusMap(),
 			pollTimeoutSeconds: 30,
 		}
@@ -107,29 +106,19 @@ export default {
 	},
 	methods: {
 		getHeaderTitle() {
-			const { allProcessed, errorCount } = this.getProgressCompletionState()
+			const { allProcessed, errorCount } = this.getProgressState()
 			if (!this.isPolling && allProcessed && errorCount > 0) {
 				return t('libresign', 'Signing finished with errors')
 			}
 			return t('libresign', 'Signing document...')
 		},
 		getHeaderSubtitle() {
-			const { allProcessed, errorCount } = this.getProgressCompletionState()
+			const { allProcessed, errorCount } = this.getProgressState()
 			if (!this.isPolling && allProcessed && errorCount > 0) {
 				return t('libresign', 'Some files could not be signed. Please review the errors below.')
 			}
 			return t('libresign', 'Your document is being signed. This may take a few moments.')
 		},
-		getProgressCompletionState() {
-			const progressReady = this.progress && (this.progress.total ?? 0) > 0
-			const total = this.progress?.total ?? 0
-			const signed = this.progress?.signed ?? 0
-			const fileErrors = this.getFilesWithErrors()
-			const errorCount = this.progress?.errors ?? fileErrors.length
-			const processedCount = signed + errorCount
-			const allProcessed = progressReady && processedCount >= total
-			return { allProcessed, errorCount }
-		},
 		startPolling() {
 			if (this.isPolling || !this.signRequestUuid) {
 				return
@@ -152,87 +141,90 @@ export default {
 				return
 			}
 
-		try {
-			const { data } = await axios.get(
-				generateOcsUrl(`/apps/libresign/api/v1/file/progress/${this.signRequestUuid}`),
-				{
-					params: { timeout: this.pollTimeoutSeconds },
-					timeout: (this.pollTimeoutSeconds + 5) * 1000,
+			try {
+				const { data } = await axios.get(
+					generateOcsUrl(`/apps/libresign/api/v1/file/progress/${this.signRequestUuid}`),
+					{
+						params: { timeout: this.pollTimeoutSeconds },
+						timeout: (this.pollTimeoutSeconds + 5) * 1000,
+					}
+				)
+
+				const responseData = data.ocs?.data || data
+				const status = responseData?.status
+				const statusCode = responseData?.statusCode ?? null
+
+				this.$emit('status-changed', status)
+
+				if (responseData?.progress) {
+					this.progress = responseData.progress
+				} else if (!this.progress) {
+					await this.fetchProgressFromValidation()
 				}
-			)
 
-			const responseData = data.ocs?.data || data
-			const status = responseData?.status
-			this.currentStatusCode = responseData?.statusCode ?? null
+				const {
+					allProcessed,
+					errorCount,
+					fileErrors,
+					hasFileErrors,
+					hasPendingWork,
+				} = this.getProgressState()
 
-			this.$emit('status-changed', status)
+				if (hasFileErrors) {
+					this.$emit('file-errors', fileErrors)
+				}
 
-			if (responseData?.progress) {
-				this.progress = responseData.progress
-			} else if (!this.progress) {
-				await this.fetchProgressFromValidation()
-			}
+				if (responseData?.error && !this.progress?.files) {
+					this.stopPolling()
+					this.$emit('error', responseData.error.message || t('libresign', 'Signing failed. Please try again.'))
+					return
+				}
 
-			// Detectar se há erros em arquivos individuais
-			const hasFileErrors = this.hasIndividualFileErrors()
-			const fileErrors = this.getFilesWithErrors()
-			if (hasFileErrors) {
-				this.$emit('file-errors', fileErrors)
-			}
+				if (responseData?.file) {
+					this.stopPolling()
+					this.$emit('completed', responseData.file)
+					return
+				}
 
-			// Erro geral do job (não erro de arquivo individual)
-			if (responseData?.error && !this.progress?.files) {
-				this.stopPolling()
-				this.$emit('error', responseData.error.message || t('libresign', 'Signing failed. Please try again.'))
-				return
-			}
+				if (status === 'ABLE_TO_SIGN' || statusCode === 1) {
+					this.stopPolling()
+					this.$emit('error', t('libresign', 'Document ready to sign'))
+					return
+				}
 
-			if (responseData?.file) {
-				this.stopPolling()
-				this.$emit('completed', responseData.file)
-				return
-			}
+				if (allProcessed && errorCount > 0) {
+					this.stopPolling()
+					const firstError = fileErrors.find(file => file?.error?.message)?.error?.message
+					this.$emit('error', firstError || t('libresign', 'Signing failed. Please try again.'))
+					return
+				}
+
+				if (status === 'SIGNED' && !hasPendingWork) {
+					this.stopPolling()
+					this.$emit('completed')
+					return
+				}
+
+				if (status === 'ERROR' && !hasPendingWork && !hasFileErrors) {
+					this.stopPolling()
+					this.$emit('error', t('libresign', 'Signing failed. Please try again.'))
+					return
+				}
 
-			const progressReady = this.progress && (this.progress.total ?? 0) > 0
-			const total = this.progress?.total ?? 0
-			const signed = this.progress?.signed ?? 0
-			const errorCount = this.progress?.errors ?? fileErrors.length
-			const processedCount = signed + errorCount
-			const pending = this.progress?.pending ?? Math.max(total - processedCount - (this.progress?.inProgress ?? 0), 0)
-			const inProgress = this.progress?.inProgress ?? 0
-			const allProcessed = progressReady && processedCount >= total
-			const hasPendingWork = !progressReady || pending > 0 || inProgress > 0 || !allProcessed
-
-			if (status === 'ABLE_TO_SIGN' || this.currentStatusCode === 1) {
-				this.stopPolling()
-				this.$emit('error', t('libresign', 'Document ready to sign'))
-			} else if (allProcessed && errorCount > 0) {
-				this.stopPolling()
-				const firstError = fileErrors.find(file => file?.error?.message)?.error?.message
-				this.$emit('error', firstError || t('libresign', 'Signing failed. Please try again.'))
-			} else if (status === 'SIGNED' && !hasPendingWork) {
-				this.stopPolling()
-				this.$emit('completed')
-			} else if (status === 'ERROR' && !hasPendingWork && !hasFileErrors) {
-				// Só parar se for erro geral e não há trabalho pendente
-				this.stopPolling()
-				this.$emit('error', t('libresign', 'Signing failed. Please try again.'))
-			} else {
-				// Long-poll returns on change/timeout; re-open immediately.
-				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 0)
-			}
-		} catch (error) {
-			if (error.code === 'ECONNABORTED') {
 				this.pollingInterval = setTimeout(() => this.pollFileProgress(), 0)
-			} else {
-				this.stopPolling()
-				this.$emit('error', t('libresign', 'Failed to check signing progress'))
+			} catch (error) {
+				if (error.code === 'ECONNABORTED') {
+					this.pollingInterval = setTimeout(() => this.pollFileProgress(), 0)
+				} else {
+					this.stopPolling()
+					this.$emit('error', t('libresign', 'Failed to check signing progress'))
+				}
 			}
-		}
-	},
+		},
 	async fetchProgressFromValidation() {
 		try {
-			if (this.hasIndividualFileErrors() || (this.progress?.errors ?? 0) > 0) {
+			const { errorCount, hasFileErrors } = this.getProgressState()
+			if (hasFileErrors || errorCount > 0) {
 				return
 			}
 			const { data } = await axios.get(
@@ -240,11 +232,10 @@ export default {
 			)
 			const doc = data.ocs?.data || data
 			const derived = this.buildProgressFromValidation(doc)
-			if (derived && !this.hasIndividualFileErrors() && (this.progress?.errors ?? 0) === 0) {
+			if (derived && !hasFileErrors && errorCount === 0) {
 				this.progress = derived
 			}
 		} catch (e) {
-			// Fallback failed, continue polling
 		}
 	},
 	buildProgressFromValidation(doc) {
@@ -276,20 +267,6 @@ export default {
 		}
 		return null
 	},
-	async fetchProgressSnapshot(fileId, currentStatus) {
-		try {
-			const { data } = await axios.get(
-				generateOcsUrl(`/apps/libresign/api/v1/file/${fileId}/wait-status`),
-				{ params: { currentStatus, timeout: 0 } }
-			)
-			const responseData = data.ocs?.data || data
-			if (responseData?.progress) {
-				this.progress = responseData.progress
-			}
-		} catch (e) {
-			// Snapshot load failed, continue polling
-		}
-	},
 	getStatusMeta(status) {
 		const meta = this.statusMap[status]
 		if (meta) {
@@ -307,17 +284,29 @@ export default {
 		}
 		return this.getStatusMeta(file?.status)
 	},
-	hasIndividualFileErrors() {
-		if (!this.progress?.files || !Array.isArray(this.progress.files)) {
-			return false
-		}
-		return this.progress.files.some(file => file.error !== null && file.error !== undefined)
-	},
-	getFilesWithErrors() {
-		if (!this.progress?.files || !Array.isArray(this.progress.files)) {
-			return []
+	getProgressState() {
+		const progress = this.progress
+		const progressReady = !!progress && (progress.total ?? 0) > 0
+		const total = progress?.total ?? 0
+		const signed = progress?.signed ?? 0
+		const inProgress = progress?.inProgress ?? 0
+		const fileErrors = Array.isArray(progress?.files)
+			? progress.files.filter(file => file?.error)
+			: []
+		const errorCount = progress?.errors ?? fileErrors.length
+		const processedCount = signed + errorCount
+		const pending = progress?.pending ?? Math.max(total - processedCount - inProgress, 0)
+		const allProcessed = progressReady && processedCount >= total
+		const hasPendingWork = !progressReady || pending > 0 || inProgress > 0 || !allProcessed
+		const hasFileErrors = fileErrors.length > 0
+
+		return {
+			allProcessed,
+			errorCount,
+			fileErrors,
+			hasFileErrors,
+			hasPendingWork,
 		}
-		return this.progress.files.filter(file => file.error !== null && file.error !== undefined)
 	},
 	},
 }

From eca4ee595a90d82f51358f3214e60e246023c3c8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:35:07 -0300
Subject: [PATCH 26/34] fix: improve unit test

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 tests/php/Unit/Service/SignJobCoordinatorTest.php | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tests/php/Unit/Service/SignJobCoordinatorTest.php b/tests/php/Unit/Service/SignJobCoordinatorTest.php
index a9f2267f32..06ba784fb6 100644
--- a/tests/php/Unit/Service/SignJobCoordinatorTest.php
+++ b/tests/php/Unit/Service/SignJobCoordinatorTest.php
@@ -203,7 +203,9 @@ public function testRunSignFileStoresErrorInProgressService(): void {
 			->with('sign-request-uuid');
 
 		$exception = new \Exception('Certificate validation failed', 422);
-		$this->signFileService->method('sign')->willThrowException($exception);
+		$this->signFileService->expects($this->once())
+			->method('sign')
+			->willThrowException($exception);
 
 		$this->errorReporter->expects($this->once())
 			->method('error');

From 6647b337aa12604294d8dc368f3fed9bcd3ba2e7 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:48:14 -0300
Subject: [PATCH 27/34] chore: tests improvements

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Unit/Service/SignJobCoordinatorTest.php   | 25 +++++++++++++------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/tests/php/Unit/Service/SignJobCoordinatorTest.php b/tests/php/Unit/Service/SignJobCoordinatorTest.php
index 06ba784fb6..3c8ae15485 100644
--- a/tests/php/Unit/Service/SignJobCoordinatorTest.php
+++ b/tests/php/Unit/Service/SignJobCoordinatorTest.php
@@ -33,7 +33,7 @@ class SignJobCoordinatorTest extends TestCase {
 	private IUserManager&MockObject $userManager;
 	private ICredentialsManager&MockObject $credentialsManager;
 	private ProgressService&MockObject $progressService;
-	private SignRequestErrorReporter&MockObject $errorReporter;
+	private SignRequestErrorReporter $errorReporter;
 	private LoggerInterface&MockObject $logger;
 	private SignJobCoordinator $coordinator;
 
@@ -46,8 +46,11 @@ public function setUp(): void {
 		$this->userManager = $this->createMock(IUserManager::class);
 		$this->credentialsManager = $this->createMock(ICredentialsManager::class);
 		$this->progressService = $this->createMock(ProgressService::class);
-		$this->errorReporter = $this->createMock(SignRequestErrorReporter::class);
 		$this->logger = $this->createMock(LoggerInterface::class);
+		$this->errorReporter = new SignRequestErrorReporter(
+			$this->progressService,
+			$this->logger,
+		);
 		$this->coordinator = new SignJobCoordinator(
 			$this->fileMapper,
 			$this->signRequestMapper,
@@ -201,15 +204,18 @@ public function testRunSignFileStoresErrorInProgressService(): void {
 		$this->progressService->expects($this->once())
 			->method('clearSignRequestError')
 			->with('sign-request-uuid');
+		$this->progressService->expects($this->once())
+			->method('setSignRequestError')
+			->with('sign-request-uuid', $this->arrayHasKey('message'));
+		$this->progressService->expects($this->once())
+			->method('setFileError')
+			->with('sign-request-uuid', $file->getId(), $this->arrayHasKey('message'));
 
 		$exception = new \Exception('Certificate validation failed', 422);
 		$this->signFileService->expects($this->once())
 			->method('sign')
 			->willThrowException($exception);
 
-		$this->errorReporter->expects($this->once())
-			->method('error');
-
 		$this->coordinator->runSignFile([
 			'fileId' => $file->getId(),
 			'signRequestId' => $signRequest->getId(),
@@ -246,13 +252,16 @@ public function testRunSignSingleFileStoresErrorWhenValidationFails(): void {
 		$this->progressService->expects($this->once())
 			->method('clearSignRequestError')
 			->with('single-sign-uuid');
+		$this->progressService->expects($this->once())
+			->method('setSignRequestError')
+			->with('single-sign-uuid', $this->arrayHasKey('message'));
+		$this->progressService->expects($this->once())
+			->method('setFileError')
+			->with('single-sign-uuid', $file->getId(), $this->arrayHasKey('message'));
 
 		$exception = new \InvalidArgumentException('Invalid parameters', 400);
 		$this->signFileService->method('signSingleFile')->willThrowException($exception);
 
-		$this->errorReporter->expects($this->once())
-			->method('error');
-
 		$this->fileMapper->expects($this->once())
 			->method('update')
 			->with($this->callback(function (File $updated) {

From f09ddf9afb27e2caf6e70e0b314801d29d9dac76 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:49:29 -0300
Subject: [PATCH 28/34] refactor: use ncnotecard

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/components/validation/SigningProgress.vue | 43 +++++++------------
 1 file changed, 16 insertions(+), 27 deletions(-)

diff --git a/src/components/validation/SigningProgress.vue b/src/components/validation/SigningProgress.vue
index a690594593..51cc05142c 100644
--- a/src/components/validation/SigningProgress.vue
+++ b/src/components/validation/SigningProgress.vue
@@ -5,6 +5,9 @@
 <template>
 	<div class="signing-progress">
 		<h1>{{ getHeaderTitle() }}</h1>
+		<NcNoteCard v-if="generalErrorMessage" type="error" class="general-error-card">
+			{{ generalErrorMessage }}
+		</NcNoteCard>
 		<NcNoteCard type="info">
 			<div class="note-header">
 				<NcLoadingIcon v-if="isPolling" :size="20" />
@@ -39,10 +42,9 @@
 								{{ getFileStatusMeta(file).label }}
 							</span>
 						</div>
-						<div v-if="file.error && file.error.message" class="file-error">
-							<span class="error-icon">⚠</span>
-							<span class="error-message">{{ file.error.message }}</span>
-						</div>
+						<NcNoteCard v-if="file.error && file.error.message" type="error" class="file-error-card">
+							{{ file.error.message }}
+						</NcNoteCard>
 					</div>
 				</div>
 			</div>
@@ -85,6 +87,7 @@ export default {
 			isPolling: false,
 			pollingInterval: null,
 			progress: null,
+			generalErrorMessage: null,
 			statusMap: buildStatusMap(),
 			pollTimeoutSeconds: 30,
 		}
@@ -174,9 +177,10 @@ export default {
 					this.$emit('file-errors', fileErrors)
 				}
 
-				if (responseData?.error && !this.progress?.files) {
+				if (responseData?.error && !hasFileErrors) {
 					this.stopPolling()
-					this.$emit('error', responseData.error.message || t('libresign', 'Signing failed. Please try again.'))
+					this.generalErrorMessage = responseData.error.message || t('libresign', 'Signing failed. Please try again.')
+					this.$emit('error', this.generalErrorMessage)
 					return
 				}
 
@@ -207,7 +211,8 @@ export default {
 
 				if (status === 'ERROR' && !hasPendingWork && !hasFileErrors) {
 					this.stopPolling()
-					this.$emit('error', t('libresign', 'Signing failed. Please try again.'))
+					this.generalErrorMessage = t('libresign', 'Signing failed. Please try again.')
+					this.$emit('error', this.generalErrorMessage)
 					return
 				}
 
@@ -330,6 +335,9 @@ export default {
 		gap: 10px;
 		color: var(--color-main-text);
 	}
+	.general-error-card {
+		margin: 12px 0;
+	}
 
 	.progress-body {
 		margin-top: 16px;
@@ -412,28 +420,9 @@ export default {
 				&.status-unknown { background: #eceff1; color: #455a64; }
 			}
 
-			.file-error {
-				display: flex;
-				align-items: center;
-				gap: 8px;
-				padding: 8px 12px;
+			.file-error-card {
 				margin: 0 10px;
-				border-radius: 6px;
-				background-color: var(--color-error, #ffebee);
-				border: 1px solid var(--color-error, #ffcdd2);
 				font-size: 13px;
-
-				.error-icon {
-					font-size: 16px;
-					color: var(--color-error, #c62828);
-					flex-shrink: 0;
-				}
-
-				.error-message {
-					color: var(--color-main-text);
-					word-break: break-word;
-					flex: 1;
-				}
 			}
 		}
 	}

From 28b6e71bce87582240d9a33562983bfee8c32a82 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:58:46 -0300
Subject: [PATCH 29/34] chore: remove unecessary comment

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/views/Validation.vue | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/views/Validation.vue b/src/views/Validation.vue
index af810881ad..ba4223c005 100644
--- a/src/views/Validation.vue
+++ b/src/views/Validation.vue
@@ -667,7 +667,6 @@ export default {
 		},
 		handleSigningError(message) {
 			this.loading = false
-			// Keep async view visible so the user can see per-file errors.
 			const errorMessage = message || t('libresign', 'Signing failed. Please try again.')
 			this.setValidationError(errorMessage)
 		},

From 01dfec84664c5e27ea4013aa55759698c5e31408 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 19:12:53 -0300
Subject: [PATCH 30/34] refactor: cleanup tests

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Controller/FileProgressControllerTest.php | 409 ++----------------
 .../SignRequest/ProgressServiceTest.php       | 137 +++++-
 2 files changed, 158 insertions(+), 388 deletions(-)

diff --git a/tests/php/Unit/Controller/FileProgressControllerTest.php b/tests/php/Unit/Controller/FileProgressControllerTest.php
index 8bef193b29..ada4023ac3 100644
--- a/tests/php/Unit/Controller/FileProgressControllerTest.php
+++ b/tests/php/Unit/Controller/FileProgressControllerTest.php
@@ -8,7 +8,6 @@
 
 namespace OCA\Libresign\Tests\Unit\Controller;
 
-use OC\Memcache\ArrayCache;
 use OCA\Libresign\Controller\FileProgressController;
 use OCA\Libresign\Db\File as FileEntity;
 use OCA\Libresign\Db\FileMapper;
@@ -18,12 +17,8 @@
 use OCA\Libresign\Service\FileService;
 use OCA\Libresign\Service\SessionService;
 use OCA\Libresign\Service\SignRequest\ProgressService;
-use OCA\Libresign\Service\SignRequest\StatusCacheService;
 use OCA\Libresign\Service\Worker\WorkerHealthService;
 use OCP\AppFramework\Http;
-use OCP\ICache;
-use OCP\ICacheFactory;
-use OCP\IMemcache;
 use OCP\IRequest;
 use OCP\IUserSession;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -62,208 +57,59 @@ protected function setUp(): void {
 		);
 	}
 
-	public function testCheckProgressByUuidWithError(): void {
-		$uuid = 'test-uuid-error';
-		$file = new FileEntity();
-		$file->setId(757);
-		$file->setName('test.pdf');
-		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
-
-		$signRequest = new SignRequestEntity();
-		$signRequest->setId(100);
-		$signRequest->setFileId(757);
-		$signRequest->setUuid($uuid);
+	public function testCheckProgressByUuidNotFound(): void {
+		$uuid = 'non-existent-uuid';
 
 		$this->signRequestMapper
 			->method('getByUuid')
 			->with($uuid)
-			->willReturn($signRequest);
-
-		$this->fileMapper
-			->method('getById')
-			->with(757)
-			->willReturn($file);
-
-		$this->fileMapper
-			->method('getTextOfStatus')
-			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
-
-		$error = [
-			'message' => 'Certificate validation failed',
-			'code' => 400,
-			'timestamp' => date('c'),
-		];
-
-		$this->progressService
-			->method('getStatusCodeForSignRequest')
-			->willReturn(FileStatus::DRAFT->value);
-
-		$this->progressService
-			->method('pollForStatusOrErrorChange')
-			->willReturn(FileStatus::DRAFT->value);
-
-		$this->progressService
-			->method('getSignRequestProgress')
-			->willReturn([
-				'total' => 1,
-				'signed' => 0,
-				'pending' => 1,
-				'inProgress' => 0,
-				'files' => [
-					['id' => 757, 'name' => 'test.pdf', 'status' => 1, 'statusText' => 'DRAFT'],
-				],
-			]);
-
-		$this->progressService
-			->method('getSignRequestError')
-			->with($uuid)
-			->willReturn($error);
-
-		$this->progressService
-			->method('isProgressComplete')
-			->willReturn(false);
+			->willThrowException(new \Exception('Sign request not found'));
 
 		$response = $this->controller->checkProgressByUuid($uuid);
 
-		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$this->assertEquals(Http::STATUS_NOT_FOUND, $response->getStatus());
 		$data = $response->getData();
-
 		$this->assertEquals('ERROR', $data['status']);
-		$this->assertArrayHasKey('error', $data);
-		$this->assertEquals('Certificate validation failed', $data['error']['message']);
-		$this->assertEquals(400, $data['error']['code']);
 	}
 
-	public function testCheckProgressByUuidWithoutError(): void {
-		$uuid = 'test-uuid-no-error';
+	public function testCheckProgressByUuidReturnsOkStatus(): void {
+		$uuid = 'test-uuid';
 		$file = new FileEntity();
-		$file->setId(757);
+		$file->setId(1);
 		$file->setName('test.pdf');
 		$file->setStatus(FileStatus::DRAFT->value);
 
 		$signRequest = new SignRequestEntity();
-		$signRequest->setId(100);
-		$signRequest->setFileId(757);
+		$signRequest->setId(1);
+		$signRequest->setFileId(1);
 		$signRequest->setUuid($uuid);
 
 		$this->signRequestMapper
 			->method('getByUuid')
-			->with($uuid)
 			->willReturn($signRequest);
 
 		$this->fileMapper
 			->method('getById')
-			->with(757)
 			->willReturn($file);
 
 		$this->fileMapper
 			->method('getTextOfStatus')
-			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
+			->willReturnCallback(fn ($s) => FileStatus::tryFrom($s)?->name ?? 'UNKNOWN');
 
 		$this->progressService
 			->method('getStatusCodeForSignRequest')
 			->willReturn(FileStatus::DRAFT->value);
 
-		$this->progressService
-			->method('getSignRequestProgress')
-			->willReturn([
-				'total' => 1,
-				'signed' => 0,
-				'pending' => 1,
-				'inProgress' => 0,
-				'errors' => 0,
-				'files' => [
-					['id' => 757, 'name' => 'test.pdf', 'status' => 1, 'statusText' => 'DRAFT'],
-				],
-			]);
-
-		$this->progressService
-			->method('getSignRequestError')
-			->with($uuid)
-			->willReturn(null);
-
-		$this->progressService
-			->method('isProgressComplete')
-			->willReturn(false);
-
-		$response = $this->controller->checkProgressByUuid($uuid);
-
-		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
-		$data = $response->getData();
-
-		$this->assertNotEquals('ERROR', $data['status']);
-		$this->assertArrayNotHasKey('error', $data);
-		$this->assertArrayNotHasKey('file', $data);
-	}
-
-	public function testCheckProgressByUuidWithFileErrorInEnvelope(): void {
-		$uuid = 'test-uuid-file-error';
-		$envelope = new FileEntity();
-		$envelope->setId(100);
-		$envelope->setName('envelope.pdf');
-		$envelope->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
-		$envelope->setNodeType('envelope');
-
-		$signRequest = new SignRequestEntity();
-		$signRequest->setId(200);
-		$signRequest->setFileId(100);
-		$signRequest->setUuid($uuid);
-
-		$this->signRequestMapper
-			->method('getByUuid')
-			->with($uuid)
-			->willReturn($signRequest);
-
-		$this->fileMapper
-			->method('getById')
-			->with(100)
-			->willReturn($envelope);
-
-		$this->fileMapper
-			->method('getTextOfStatus')
-			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
-
-		// Progress with file error in envelope
-		$progress = [
-			'total' => 2,
-			'signed' => 0,
-			'pending' => 1,
-			'inProgress' => 1,
-			'files' => [
-				[
-					'id' => 101,
-					'name' => 'file1.pdf',
-					'status' => FileStatus::SIGNING_IN_PROGRESS->value,
-					'statusText' => 'SIGNING_IN_PROGRESS',
-				],
-				[
-					'id' => 102,
-					'name' => 'file2.pdf',
-					'status' => FileStatus::DRAFT->value,
-					'statusText' => 'DRAFT',
-					'error' => [
-						'message' => 'File validation failed',
-						'code' => 422,
-					],
-				],
-			],
-		];
-
-		$this->progressService
-			->method('getStatusCodeForSignRequest')
-			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
-
 		$this->progressService
 			->method('pollForStatusOrErrorChange')
-			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+			->willReturn(FileStatus::DRAFT->value);
 
 		$this->progressService
 			->method('getSignRequestProgress')
-			->willReturn($progress);
+			->willReturn(['total' => 1, 'signed' => 0, 'pending' => 1, 'files' => []]);
 
 		$this->progressService
 			->method('getSignRequestError')
-			->with($uuid)
 			->willReturn(null);
 
 		$this->progressService
@@ -274,210 +120,98 @@ public function testCheckProgressByUuidWithFileErrorInEnvelope(): void {
 
 		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
 		$data = $response->getData();
-
+		$this->assertArrayHasKey('status', $data);
 		$this->assertArrayHasKey('progress', $data);
-		$this->assertCount(2, $data['progress']['files']);
-		$this->assertArrayNotHasKey('error', $data['progress']['files'][0]);
-		$this->assertArrayHasKey('error', $data['progress']['files'][1]);
-		$this->assertEquals('File validation failed', $data['progress']['files'][1]['error']['message']);
 	}
 
-	public function testRootErrorSuppressedWhenFileErrorsExist(): void {
-		$uuid = 'mixed-error-uuid';
+	public function testCheckProgressByUuidCallsWorkerHealthServiceWhenSigningInProgress(): void {
+		$uuid = 'test-uuid';
 		$file = new FileEntity();
-		$file->setId(501);
-		$file->setName('parent.pdf');
+		$file->setId(1);
 		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
 
 		$signRequest = new SignRequestEntity();
-		$signRequest->setId(601);
-		$signRequest->setFileId(501);
+		$signRequest->setId(1);
+		$signRequest->setFileId(1);
 		$signRequest->setUuid($uuid);
 
 		$this->signRequestMapper
 			->method('getByUuid')
-			->with($uuid)
 			->willReturn($signRequest);
 
 		$this->fileMapper
 			->method('getById')
-			->with(501)
 			->willReturn($file);
 
 		$this->fileMapper
 			->method('getTextOfStatus')
-			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
-
-		$progress = [
-			'total' => 1,
-			'signed' => 0,
-			'pending' => 1,
-			'inProgress' => 0,
-			'files' => [
-				[
-					'id' => 701,
-					'name' => 'child.pdf',
-					'status' => FileStatus::DRAFT->value,
-					'statusText' => 'DRAFT',
-					'error' => [
-						'message' => 'Child failed',
-						'code' => 422,
-					],
-				],
-			],
-		];
-
-		$generalError = [
-			'message' => 'General failure',
-			'code' => 500,
-		];
+			->willReturnCallback(fn ($s) => FileStatus::tryFrom($s)?->name ?? 'UNKNOWN');
 
 		$this->progressService
 			->method('getStatusCodeForSignRequest')
 			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
 
+		$this->workerHealthService
+			->expects($this->once())
+			->method('ensureWorkerRunning');
+
 		$this->progressService
 			->method('pollForStatusOrErrorChange')
 			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
 
 		$this->progressService
 			->method('getSignRequestProgress')
-			->willReturn($progress);
+			->willReturn(['total' => 1, 'files' => []]);
 
 		$this->progressService
 			->method('getSignRequestError')
-			->with($uuid)
-			->willReturn($generalError);
+			->willReturn(null);
 
 		$this->progressService
 			->method('isProgressComplete')
 			->willReturn(false);
 
-		$response = $this->controller->checkProgressByUuid($uuid);
-
-		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
-		$data = $response->getData();
-
-		$this->assertEquals('SIGNING_IN_PROGRESS', $data['status']);
-		$this->assertArrayNotHasKey('error', $data, 'Root error should be suppressed when file errors exist');
-		$this->assertArrayNotHasKey('file', $data, 'Should not include file object when errors exist');
-		$this->assertArrayHasKey('progress', $data);
-		$this->assertArrayHasKey('files', $data['progress']);
-		$this->assertArrayHasKey('error', $data['progress']['files'][0]);
-		$this->assertEquals('Child failed', $data['progress']['files'][0]['error']['message']);
-	}
-
-	public function testCheckProgressByUuidNotFound(): void {
-		$uuid = 'non-existent-uuid';
-
-		$this->signRequestMapper
-			->method('getByUuid')
-			->with($uuid)
-			->willThrowException(new \Exception('Sign request not found'));
-
-		$response = $this->controller->checkProgressByUuid($uuid);
-
-		$this->assertEquals(Http::STATUS_NOT_FOUND, $response->getStatus());
-		$data = $response->getData();
-		$this->assertEquals('ERROR', $data['status']);
+		$this->controller->checkProgressByUuid($uuid);
 	}
 
-	public function testCheckProgressByUuidReadsErrorFromCache(): void {
-		$uuid = 'cache-error-uuid';
+	public function testCheckProgressByUuidNormalizesTimeout(): void {
+		$uuid = 'test-uuid';
 		$file = new FileEntity();
-		$file->setId(777);
-		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
+		$file->setId(1);
+		$file->setStatus(FileStatus::DRAFT->value);
 
 		$signRequest = new SignRequestEntity();
-		$signRequest->setId(888);
-		$signRequest->setFileId(777);
+		$signRequest->setId(1);
+		$signRequest->setFileId(1);
 		$signRequest->setUuid($uuid);
 
 		$this->signRequestMapper
 			->method('getByUuid')
-			->with($uuid)
 			->willReturn($signRequest);
 
 		$this->fileMapper
 			->method('getById')
-			->with(777)
 			->willReturn($file);
 
 		$this->fileMapper
 			->method('getTextOfStatus')
-			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
-
-		$cache = new InMemoryCache();
-		$cache->set(ProgressService::ERROR_KEY_PREFIX . $uuid, [
-			'message' => 'Cached error',
-			'code' => 500,
-		]);
-		$cacheFactory = new InMemoryCacheFactory($cache);
-		$statusCacheService = new StatusCacheService($cacheFactory);
-		$realProgressService = new ProgressService($this->fileMapper, $cacheFactory, $this->signRequestMapper, $statusCacheService);
-
-		$controller = new FileProgressController(
-			$this->request,
-			$this->fileMapper,
-			$this->signRequestMapper,
-			$this->fileService,
-			$this->sessionService,
-			$this->userSession,
-			$this->workerHealthService,
-			$realProgressService,
-		);
-
-		$response = $controller->checkProgressByUuid($uuid);
-		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
-
-		$data = $response->getData();
-		$this->assertEquals('ERROR', $data['status']);
-		$this->assertEquals('Cached error', $data['error']['message']);
-	}
-
-	public function testCheckProgressByUuidNormalizesTimeout(): void {
-		$uuid = 'timeout-uuid';
-		$file = new FileEntity();
-		$file->setId(321);
-		$file->setStatus(FileStatus::SIGNING_IN_PROGRESS->value);
-
-		$signRequest = new SignRequestEntity();
-		$signRequest->setId(654);
-		$signRequest->setFileId(321);
-		$signRequest->setUuid($uuid);
-
-		$this->signRequestMapper
-			->method('getByUuid')
-			->with($uuid)
-			->willReturn($signRequest);
-
-		$this->fileMapper
-			->method('getById')
-			->with(321)
-			->willReturn($file);
+			->willReturnCallback(fn ($s) => FileStatus::tryFrom($s)?->name ?? 'UNKNOWN');
 
 		$this->progressService
 			->method('getStatusCodeForSignRequest')
-			->willReturn(FileStatus::SIGNING_IN_PROGRESS->value);
+			->willReturn(FileStatus::DRAFT->value);
 
 		$this->progressService
 			->expects($this->once())
 			->method('pollForStatusOrErrorChange')
-			->with($file, $signRequest, FileStatus::SIGNING_IN_PROGRESS->value, 1);
+			->with($file, $signRequest, FileStatus::DRAFT->value, 1);
 
 		$this->progressService
 			->method('getSignRequestProgress')
-			->willReturn([
-				'total' => 1,
-				'signed' => 0,
-				'pending' => 1,
-				'inProgress' => 0,
-				'files' => [],
-			]);
+			->willReturn(['total' => 1, 'files' => []]);
 
 		$this->progressService
 			->method('getSignRequestError')
-			->with($uuid)
 			->willReturn(null);
 
 		$this->progressService
@@ -487,74 +221,3 @@ public function testCheckProgressByUuidNormalizesTimeout(): void {
 		$this->controller->checkProgressByUuid($uuid, 0);
 	}
 }
-
-class InMemoryCache implements ICache {
-	private array $data = [];
-
-	public function get($key) {
-		return $this->data[$key] ?? null;
-	}
-
-	public function set($key, $value, $ttl = 0) {
-		$this->data[$key] = $value;
-		return true;
-	}
-
-	public function hasKey($key) {
-		return array_key_exists($key, $this->data);
-	}
-
-	public function remove($key) {
-		unset($this->data[$key]);
-		return true;
-	}
-
-	public function clear($prefix = '') {
-		if ($prefix === '') {
-			$this->data = [];
-			return true;
-		}
-
-		foreach (array_keys($this->data) as $key) {
-			if (str_starts_with($key, $prefix)) {
-				unset($this->data[$key]);
-			}
-		}
-		return true;
-	}
-
-	public static function isAvailable(): bool {
-		return true;
-	}
-}
-
-class InMemoryCacheFactory implements ICacheFactory {
-	public function __construct(
-		private ICache $cache,
-	) {
-	}
-
-	public function isAvailable(): bool {
-		return true;
-	}
-
-	public function isLocalCacheAvailable(): bool {
-		return true;
-	}
-
-	public function createLocking(string $prefix = ''): IMemcache {
-		return new ArrayCache();
-	}
-
-	public function createDistributed(string $prefix = ''): ICache {
-		return $this->cache;
-	}
-
-	public function createLocal(string $prefix = ''): ICache {
-		return new InMemoryCache();
-	}
-
-	public function createInMemory(int $capacity = 512): ICache {
-		return new InMemoryCache();
-	}
-}
diff --git a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
index 11159ac806..1025d10036 100644
--- a/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
+++ b/tests/php/Unit/Service/SignRequest/ProgressServiceTest.php
@@ -70,8 +70,6 @@ public function testPollReturnsNewStatusWhenCacheChanges(): void {
 		$sequence = [$initialStatus, $initialStatus, $newStatus];
 		$index = 0;
 
-		// Create a fresh mock to avoid conflicts with setUp()
-		$this->statusCacheService = $this->createMock(StatusCacheService::class);
 		$this->statusCacheService
 			->method('getStatus')
 			->with($uuid)
@@ -81,14 +79,6 @@ public function testPollReturnsNewStatusWhenCacheChanges(): void {
 				return $value;
 			});
 
-		// Recreate service with the new mock
-		$this->service = new ProgressService(
-			$this->fileMapper,
-			$this->cacheFactory,
-			$this->signRequestMapper,
-			$this->statusCacheService,
-		);
-
 		$result = $this->service->pollForStatusChange($uuid, $initialStatus, 5, 0);
 
 		$this->assertEquals($newStatus, $result);
@@ -267,7 +257,6 @@ public function testGetSignRequestProgressForFileInEnvelope(): void {
 	}
 
 	public function testGetSignRequestProgressRoutesToCorrectMethod(): void {
-		// Test single file
 		$file = $this->createFileEntity(1, 'test.pdf', FileStatus::DRAFT->value, null);
 		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
 
@@ -448,7 +437,6 @@ public function testMapSignRequestFileProgressIncludesError(): void {
 
 		$signRequest->setUuid($uuid);
 
-		// Use reflection to test private method
 		$reflection = new \ReflectionClass($this->service);
 		$method = $reflection->getMethod('mapSignRequestFileProgress');
 		$method->setAccessible(true);
@@ -464,7 +452,6 @@ public function testMapSignRequestFileProgressWithoutError(): void {
 		$signRequest = $this->createSignRequestEntity(100, 'John Doe', FileStatus::DRAFT->value, null);
 		$signRequest->setUuid('no-error-uuid');
 
-		// Use reflection to test private method
 		$reflection = new \ReflectionClass($this->service);
 		$method = $reflection->getMethod('mapSignRequestFileProgress');
 		$method->setAccessible(true);
@@ -488,8 +475,6 @@ public function testEnvelopeProgressWithFileErrors(): void {
 		$this->fileMapper
 			->method('getTextOfStatus')
 			->willReturnCallback(fn ($status) => FileStatus::tryFrom($status)?->name ?? 'UNKNOWN');
-
-		// Set error for child2
 		$error = ['message' => 'Signature failed', 'code' => 422];
 		$this->service->setFileError($uuid, 3, $error);
 
@@ -611,6 +596,128 @@ private function createSignRequestEntity(
 
 		return $signRequest;
 	}
+
+	public function testFileErrorsSuppressRootError(): void {
+		$uuid = 'suppress-test-uuid';
+		$progress = [
+			'total' => 2,
+			'signed' => 0,
+			'pending' => 2,
+			'files' => [
+				[
+					'id' => 101,
+					'name' => 'file1.pdf',
+					'status' => FileStatus::DRAFT->value,
+					'statusText' => 'DRAFT',
+					'error' => [
+						'message' => 'File validation failed',
+						'code' => 422,
+					],
+				],
+				[
+					'id' => 102,
+					'name' => 'file2.pdf',
+					'status' => FileStatus::DRAFT->value,
+					'statusText' => 'DRAFT',
+				],
+			],
+		];
+
+		$rootError = [
+			'message' => 'Root error that should be suppressed',
+			'code' => 500,
+		];
+
+		$this->service->setSignRequestError($uuid, $rootError);
+
+		$cachedError = $this->service->getSignRequestError($uuid);
+
+		$this->assertIsArray($cachedError);
+		$this->assertEquals('Root error that should be suppressed', $cachedError['message']);
+		$this->assertIsArray($progress['files'][0]['error']);
+		$this->assertEquals('File validation failed', $progress['files'][0]['error']['message']);
+	}
+
+	public function testMultipleFileErrorsArePreserved(): void {
+		$uuid = 'multi-error-uuid';
+		$fileId1 = 201;
+		$fileId2 = 202;
+
+		$error1 = [
+			'message' => 'File 1 error',
+			'code' => 422,
+		];
+
+		$error2 = [
+			'message' => 'File 2 error',
+			'code' => 400,
+		];
+
+		$this->service->setFileError($uuid, $fileId1, $error1);
+		$this->service->setFileError($uuid, $fileId2, $error2);
+
+		$retrieved1 = $this->service->getFileError($uuid, $fileId1);
+		$retrieved2 = $this->service->getFileError($uuid, $fileId2);
+
+		$this->assertEquals('File 1 error', $retrieved1['message']);
+		$this->assertEquals('File 2 error', $retrieved2['message']);
+	}
+
+	public function testErrorsArePersistedInMetadata(): void {
+		$uuid = 'metadata-persist-uuid';
+		$fileId = 303;
+
+		$error = [
+			'message' => 'Persistent error',
+			'code' => 500,
+		];
+
+		$cache = new InMemoryCache();
+		$cacheFactory = new InMemoryCacheFactory($cache);
+		$service = new ProgressService(
+			$this->fileMapper,
+			$cacheFactory,
+			$this->signRequestMapper,
+			$this->statusCacheService,
+		);
+
+		$service->setFileError($uuid, $fileId, $error);
+
+		$cache->clear();
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setUuid($uuid);
+		$signRequest->setMetadata([
+			'libresign_file_errors' => [
+				$fileId => $error,
+			],
+		]);
+
+		$this->signRequestMapper
+			->method('getByUuidUncached')
+			->with($uuid)
+			->willReturn($signRequest);
+
+		$retrieved = $service->getFileError($uuid, $fileId);
+
+		$this->assertIsArray($retrieved);
+		$this->assertEquals('Persistent error', $retrieved['message']);
+	}
+
+	public function testClearSignRequestErrorRemovesFromCacheAndMetadata(): void {
+		$uuid = 'clear-error-uuid';
+		$error = [
+			'message' => 'Error to be cleared',
+			'code' => 500,
+		];
+
+		$this->service->setSignRequestError($uuid, $error);
+		$this->assertIsArray($this->service->getSignRequestError($uuid));
+
+		$this->service->clearSignRequestError($uuid);
+
+		$this->assertNull($this->service->getSignRequestError($uuid));
+	}
 }
 
 class InMemoryCache implements ICache {

From 4b32f844db242e2782ad9664fc93093f621b7308 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 19:17:26 -0300
Subject: [PATCH 31/34] feat: cover with more dataproviders

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Error/ErrorPayloadBuilderTest.php         | 187 ++++++++++++------
 1 file changed, 122 insertions(+), 65 deletions(-)

diff --git a/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
index dcd6b0cf95..415a39a0b0 100644
--- a/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
+++ b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
@@ -9,6 +9,7 @@
 namespace OCA\Libresign\Tests\Unit\Service\SignRequest\Error;
 
 use OCA\Libresign\Service\SignRequest\Error\ErrorPayloadBuilder;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 class ErrorPayloadBuilderTest extends TestCase {
@@ -26,43 +27,70 @@ public function testBuildMinimalPayload(): void {
 		$this->assertEquals(500, $payload['code']);
 	}
 
-	public function testBuildWithFile(): void {
-		$builder = new ErrorPayloadBuilder();
-		$payload = $builder
-			->setMessage('File error')
-			->setCode(400)
-			->setFileId(123)
-			->build();
-
-		$this->assertEquals(123, $payload['fileId']);
-	}
-
-	public function testBuildWithSignRequest(): void {
-		$builder = new ErrorPayloadBuilder();
-		$payload = $builder
-			->setMessage('Sign request error')
-			->setCode(400)
-			->setSignRequestId(456)
-			->setSignRequestUuid('test-uuid-123')
-			->build();
-
-		$this->assertEquals(456, $payload['signRequestId']);
-		$this->assertEquals('test-uuid-123', $payload['signRequestUuid']);
+	public static function buildWithContextDataProvider(): array {
+		return [
+			'with file only' => [
+				'fileId' => 123,
+				'signRequestId' => null,
+				'signRequestUuid' => null,
+				'expectedKeys' => ['fileId'],
+				'notExpectedKeys' => ['signRequestId', 'signRequestUuid'],
+			],
+			'with sign request only' => [
+				'fileId' => null,
+				'signRequestId' => 456,
+				'signRequestUuid' => 'test-uuid-123',
+				'expectedKeys' => ['signRequestId', 'signRequestUuid'],
+				'notExpectedKeys' => ['fileId'],
+			],
+			'with file and sign request' => [
+				'fileId' => 789,
+				'signRequestId' => 456,
+				'signRequestUuid' => 'test-uuid-456',
+				'expectedKeys' => ['fileId', 'signRequestId', 'signRequestUuid'],
+				'notExpectedKeys' => [],
+			],
+			'with null values' => [
+				'fileId' => null,
+				'signRequestId' => null,
+				'signRequestUuid' => null,
+				'expectedKeys' => [],
+				'notExpectedKeys' => ['fileId', 'signRequestId', 'signRequestUuid'],
+			],
+		];
 	}
 
-	public function testBuildWithFileAndSignRequest(): void {
+	#[DataProvider('buildWithContextDataProvider')]
+	public function testBuildWithContext(
+		?int $fileId,
+		?int $signRequestId,
+		?string $signRequestUuid,
+		array $expectedKeys,
+		array $notExpectedKeys
+	): void {
 		$builder = new ErrorPayloadBuilder();
 		$payload = $builder
-			->setMessage('Combined error')
+			->setMessage('Test error')
 			->setCode(400)
-			->setFileId(789)
-			->setSignRequestId(456)
-			->setSignRequestUuid('test-uuid-456')
+			->setFileId($fileId)
+			->setSignRequestId($signRequestId)
+			->setSignRequestUuid($signRequestUuid)
 			->build();
 
-		$this->assertEquals(789, $payload['fileId']);
-		$this->assertEquals(456, $payload['signRequestId']);
-		$this->assertEquals('test-uuid-456', $payload['signRequestUuid']);
+		foreach ($expectedKeys as $key) {
+			$this->assertArrayHasKey($key, $payload);
+			if ($key === 'fileId') {
+				$this->assertEquals($fileId, $payload[$key]);
+			} elseif ($key === 'signRequestId') {
+				$this->assertEquals($signRequestId, $payload[$key]);
+			} elseif ($key === 'signRequestUuid') {
+				$this->assertEquals($signRequestUuid, $payload[$key]);
+			}
+		}
+
+		foreach ($notExpectedKeys as $key) {
+			$this->assertArrayNotHasKey($key, $payload);
+		}
 	}
 
 	public function testAddFileError(): void {
@@ -97,28 +125,72 @@ public function testClearFileErrors(): void {
 		$this->assertArrayNotHasKey('fileErrors', $payload2);
 	}
 
-	public function testFromException(): void {
-		$exception = new \Exception('Exception message', 789);
-
-		$payload = ErrorPayloadBuilder::fromException($exception, 555, 666, 'exception-uuid')->build();
-
-		$this->assertEquals('Exception message', $payload['message']);
-		$this->assertEquals(789, $payload['code']);
-		$this->assertEquals(555, $payload['fileId']);
-		$this->assertEquals(666, $payload['signRequestId']);
-		$this->assertEquals('exception-uuid', $payload['signRequestUuid']);
+	public static function fromExceptionDataProvider(): array {
+		return [
+			'with full context' => [
+				'message' => 'Exception message',
+				'code' => 789,
+				'fileId' => 555,
+				'signRequestId' => 666,
+				'signRequestUuid' => 'exception-uuid',
+				'expectedKeys' => ['message', 'code', 'fileId', 'signRequestId', 'signRequestUuid'],
+			],
+			'without context' => [
+				'message' => 'Standalone error',
+				'code' => 999,
+				'fileId' => null,
+				'signRequestId' => null,
+				'signRequestUuid' => null,
+				'expectedKeys' => ['message', 'code'],
+			],
+			'with partial context (file only)' => [
+				'message' => 'File error',
+				'code' => 400,
+				'fileId' => 123,
+				'signRequestId' => null,
+				'signRequestUuid' => null,
+				'expectedKeys' => ['message', 'code', 'fileId'],
+			],
+		];
 	}
 
-	public function testFromExceptionWithoutContext(): void {
-		$exception = new \Exception('Standalone error', 999);
-
-		$payload = ErrorPayloadBuilder::fromException($exception)->build();
-
-		$this->assertEquals('Standalone error', $payload['message']);
-		$this->assertEquals(999, $payload['code']);
-		$this->assertArrayNotHasKey('fileId', $payload);
-		$this->assertArrayNotHasKey('signRequestId', $payload);
-		$this->assertArrayNotHasKey('signRequestUuid', $payload);
+	#[DataProvider('fromExceptionDataProvider')]
+	public function testFromException(
+		string $message,
+		int $code,
+		?int $fileId,
+		?int $signRequestId,
+		?string $signRequestUuid,
+		array $expectedKeys
+	): void {
+		$exception = new \Exception($message, $code);
+
+		$payload = ErrorPayloadBuilder::fromException($exception, $fileId, $signRequestId, $signRequestUuid)->build();
+
+		$this->assertEquals($message, $payload['message']);
+		$this->assertEquals($code, $payload['code']);
+
+		foreach ($expectedKeys as $key) {
+			$this->assertArrayHasKey($key, $payload);
+		}
+
+		if ($fileId !== null) {
+			$this->assertEquals($fileId, $payload['fileId']);
+		} else {
+			$this->assertArrayNotHasKey('fileId', $payload);
+		}
+
+		if ($signRequestId !== null) {
+			$this->assertEquals($signRequestId, $payload['signRequestId']);
+		} else {
+			$this->assertArrayNotHasKey('signRequestId', $payload);
+		}
+
+		if ($signRequestUuid !== null) {
+			$this->assertEquals($signRequestUuid, $payload['signRequestUuid']);
+		} else {
+			$this->assertArrayNotHasKey('signRequestUuid', $payload);
+		}
 	}
 
 	public function testFluentInterface(): void {
@@ -141,21 +213,6 @@ public function testFluentInterface(): void {
 		$this->assertCount(2, $payload['fileErrors']);
 	}
 
-	public function testNullFileAndSignRequestNotIncluded(): void {
-		$builder = new ErrorPayloadBuilder();
-		$payload = $builder
-			->setMessage('Error without context')
-			->setCode(400)
-			->setFileId(null)
-			->setSignRequestId(null)
-			->setSignRequestUuid(null)
-			->build();
-
-		$this->assertArrayNotHasKey('fileId', $payload);
-		$this->assertArrayNotHasKey('signRequestId', $payload);
-		$this->assertArrayNotHasKey('signRequestUuid', $payload);
-	}
-
 	public function testTimestampPresent(): void {
 		$builder = new ErrorPayloadBuilder();
 		$payload = $builder->setMessage('Test')->build();

From 05796a869fdeaefb83f277aef0282dcc7068842c Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 19:20:42 -0300
Subject: [PATCH 32/34] feat: cover with more scenarios

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Error/SignRequestErrorReporterTest.php    | 296 ++++++++++++++++++
 1 file changed, 296 insertions(+)

diff --git a/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
index c2a31761f5..d511cd0e67 100644
--- a/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
+++ b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
@@ -10,6 +10,7 @@
 
 use OCA\Libresign\Service\SignRequest\Error\SignRequestErrorReporter;
 use OCA\Libresign\Service\SignRequest\ProgressService;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 use Psr\Log\LoggerInterface;
@@ -149,4 +150,299 @@ public function testErrorUsesCustomTtl(): void {
 
 		$this->reporter->error('Error with ttl', $context);
 	}
+
+	public static function logLevelDataProvider(): array {
+		return [
+			'debug level' => [LogLevel::DEBUG, false],
+			'info level' => [LogLevel::INFO, false],
+			'notice level' => [LogLevel::NOTICE, false],
+			'warning level' => [LogLevel::WARNING, false],
+			'error level' => [LogLevel::ERROR, true],
+			'critical level' => [LogLevel::CRITICAL, false],
+			'alert level' => [LogLevel::ALERT, false],
+			'emergency level' => [LogLevel::EMERGENCY, false],
+		];
+	}
+
+	#[DataProvider('logLevelDataProvider')]
+	public function testOnlyErrorLevelStoresPayload(string $logLevel, bool $shouldStore): void {
+		$exception = new \RuntimeException('Test exception', 500);
+		$context = [
+			'exception' => $exception,
+			'signRequestUuid' => 'uuid-loglevel',
+			'fileId' => 42,
+		];
+
+		if ($shouldStore) {
+			$this->progressService->expects($this->once())
+				->method('setSignRequestError');
+			$this->progressService->expects($this->once())
+				->method('setFileError');
+		} else {
+			$this->progressService->expects($this->never())
+				->method('setSignRequestError');
+			$this->progressService->expects($this->never())
+				->method('setFileError');
+		}
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with($logLevel, 'Test message', $context);
+
+		$this->reporter->log($logLevel, 'Test message', $context);
+	}
+
+	public static function contextVariationsDataProvider(): array {
+		return [
+			'complete context with all IDs' => [
+				'context' => [
+					'exception' => new \RuntimeException('Complete', 100),
+					'signRequestUuid' => 'uuid-complete',
+					'fileId' => 10,
+					'signRequestId' => 20,
+					'ttl' => 600,
+				],
+				'expectSignRequestError' => true,
+				'expectFileError' => true,
+				'expectedTtl' => 600,
+			],
+			'context without fileId' => [
+				'context' => [
+					'exception' => new \RuntimeException('No fileId', 101),
+					'signRequestUuid' => 'uuid-nofile',
+					'signRequestId' => 25,
+				],
+				'expectSignRequestError' => true,
+				'expectFileError' => false,
+				'expectedTtl' => 300, // default
+			],
+			'context with string numeric fileId' => [
+				'context' => [
+					'exception' => new \RuntimeException('String fileId', 102),
+					'signRequestUuid' => 'uuid-stringfile',
+					'fileId' => '15',
+					'signRequestId' => '30',
+				],
+				'expectSignRequestError' => true,
+				'expectFileError' => true,
+				'expectedTtl' => 300,
+			],
+			'context with non-numeric fileId' => [
+				'context' => [
+					'exception' => new \RuntimeException('Invalid fileId', 103),
+					'signRequestUuid' => 'uuid-invalidfile',
+					'fileId' => 'not-a-number',
+					'signRequestId' => 35,
+				],
+				'expectSignRequestError' => true,
+				'expectFileError' => false,
+				'expectedTtl' => 300,
+			],
+			'context with zero TTL' => [
+				'context' => [
+					'exception' => new \RuntimeException('Zero TTL', 104),
+					'signRequestUuid' => 'uuid-zerottl',
+					'fileId' => 20,
+					'ttl' => 0,
+				],
+				'expectSignRequestError' => true,
+				'expectFileError' => true,
+				'expectedTtl' => 0,
+			],
+			'context with empty string uuid (should not store)' => [
+				'context' => [
+					'exception' => new \RuntimeException('Empty uuid', 105),
+					'signRequestUuid' => '',
+					'fileId' => 25,
+				],
+				'expectSignRequestError' => false,
+				'expectFileError' => false,
+				'expectedTtl' => 300,
+			],
+		];
+	}
+
+	#[DataProvider('contextVariationsDataProvider')]
+	public function testErrorWithVariousContextCombinations(
+		array $context,
+		bool $expectSignRequestError,
+		bool $expectFileError,
+		int $expectedTtl
+	): void {
+		if ($expectSignRequestError) {
+			$this->progressService->expects($this->once())
+				->method('setSignRequestError')
+				->with(
+					$context['signRequestUuid'],
+					$this->callback(function (array $payload) use ($context) {
+						return $payload['message'] === $context['exception']->getMessage()
+							&& $payload['code'] === $context['exception']->getCode();
+					}),
+					$expectedTtl
+				);
+		} else {
+			$this->progressService->expects($this->never())
+				->method('setSignRequestError');
+		}
+
+		if ($expectFileError) {
+			$fileId = is_numeric($context['fileId']) ? (int)$context['fileId'] : null;
+			$this->progressService->expects($this->once())
+				->method('setFileError')
+				->with(
+					$context['signRequestUuid'],
+					$fileId,
+					$this->isType('array'),
+					$expectedTtl
+				);
+		} else {
+			$this->progressService->expects($this->never())
+				->method('setFileError');
+		}
+
+		$this->logger->expects($this->once())
+			->method('log');
+
+		$this->reporter->error('Test error', $context);
+	}
+
+	public static function exceptionTypesDataProvider(): array {
+		return [
+			'RuntimeException' => [
+				'exception' => new \RuntimeException('Runtime error', 500),
+				'expectedMessage' => 'Runtime error',
+				'expectedCode' => 500,
+			],
+			'InvalidArgumentException' => [
+				'exception' => new \InvalidArgumentException('Invalid argument', 400),
+				'expectedMessage' => 'Invalid argument',
+				'expectedCode' => 400,
+			],
+			'LogicException' => [
+				'exception' => new \LogicException('Logic error', 422),
+				'expectedMessage' => 'Logic error',
+				'expectedCode' => 422,
+			],
+			'Exception with zero code' => [
+				'exception' => new \Exception('Zero code error', 0),
+				'expectedMessage' => 'Zero code error',
+				'expectedCode' => 0,
+			],
+			'Exception with empty message' => [
+				'exception' => new \Exception('', 999),
+				'expectedMessage' => '',
+				'expectedCode' => 999,
+			],
+		];
+	}
+
+	#[DataProvider('exceptionTypesDataProvider')]
+	public function testErrorWithDifferentExceptionTypes(
+		\Throwable $exception,
+		string $expectedMessage,
+		int $expectedCode
+	): void {
+		$context = [
+			'exception' => $exception,
+			'signRequestUuid' => 'uuid-exception-types',
+			'fileId' => 100,
+		];
+
+		$this->progressService->expects($this->once())
+			->method('setSignRequestError')
+			->with(
+				'uuid-exception-types',
+				$this->callback(function (array $payload) use ($expectedMessage, $expectedCode) {
+					return $payload['message'] === $expectedMessage
+						&& $payload['code'] === $expectedCode
+						&& isset($payload['timestamp'])
+						&& isset($payload['fileId'])
+						&& $payload['fileId'] === 100;
+				}),
+				300
+			);
+
+		$this->progressService->expects($this->once())
+			->method('setFileError')
+			->with(
+				'uuid-exception-types',
+				100,
+				$this->callback(function (array $payload) use ($expectedMessage, $expectedCode) {
+					return $payload['message'] === $expectedMessage
+						&& $payload['code'] === $expectedCode;
+				}),
+				300
+			);
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Exception test', $context);
+
+		$this->reporter->error('Exception test', $context);
+	}
+
+	public static function missingRequiredFieldsDataProvider(): array {
+		return [
+			'missing exception' => [
+				'context' => [
+					'signRequestUuid' => 'uuid-no-exception',
+					'fileId' => 50,
+				],
+				'shouldStore' => false,
+			],
+			'missing uuid' => [
+				'context' => [
+					'exception' => new \RuntimeException('No UUID'),
+					'fileId' => 50,
+				],
+				'shouldStore' => false,
+			],
+			'null exception' => [
+				'context' => [
+					'exception' => null,
+					'signRequestUuid' => 'uuid-null-exception',
+					'fileId' => 50,
+				],
+				'shouldStore' => false,
+			],
+			'null uuid' => [
+				'context' => [
+					'exception' => new \RuntimeException('Null UUID'),
+					'signRequestUuid' => null,
+					'fileId' => 50,
+				],
+				'shouldStore' => false,
+			],
+			'non-throwable exception' => [
+				'context' => [
+					'exception' => 'not an exception',
+					'signRequestUuid' => 'uuid-invalid-exception',
+					'fileId' => 50,
+				],
+				'shouldStore' => false,
+			],
+		];
+	}
+
+	#[DataProvider('missingRequiredFieldsDataProvider')]
+	public function testErrorDoesNotStoreWhenRequiredFieldsMissing(
+		array $context,
+		bool $shouldStore
+	): void {
+		if ($shouldStore) {
+			$this->progressService->expects($this->atLeastOnce())
+				->method('setSignRequestError');
+		} else {
+			$this->progressService->expects($this->never())
+				->method('setSignRequestError');
+			$this->progressService->expects($this->never())
+				->method('setFileError');
+		}
+
+		$this->logger->expects($this->once())
+			->method('log')
+			->with(LogLevel::ERROR, 'Test error', $context);
+
+		$this->reporter->error('Test error', $context);
+	}
 }

From 00d9456345e98bad320ee9a53e56af2c7c7083b4 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 19:27:25 -0300
Subject: [PATCH 33/34] feat: cover with more tests

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Controller/FileProgressControllerTest.php | 170 ++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/tests/php/Unit/Controller/FileProgressControllerTest.php b/tests/php/Unit/Controller/FileProgressControllerTest.php
index ada4023ac3..7e7eec4cbd 100644
--- a/tests/php/Unit/Controller/FileProgressControllerTest.php
+++ b/tests/php/Unit/Controller/FileProgressControllerTest.php
@@ -21,6 +21,7 @@
 use OCP\AppFramework\Http;
 use OCP\IRequest;
 use OCP\IUserSession;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 
@@ -220,4 +221,173 @@ public function testCheckProgressByUuidNormalizesTimeout(): void {
 
 		$this->controller->checkProgressByUuid($uuid, 0);
 	}
+
+	public static function progressResponseScenarios(): array {
+		return [
+			'complete without errors returns file' => [
+				'progress' => [
+					'total' => 1,
+					'signed' => 1,
+					'pending' => 0,
+					'inProgress' => 0,
+					'files' => [],
+				],
+				'rootError' => null,
+				'complete' => true,
+				'expectedStatus' => 'SIGNED',
+				'expectFile' => true,
+				'expectError' => false,
+			],
+			'root error without file errors sets ERROR status' => [
+				'progress' => [
+					'total' => 1,
+					'signed' => 0,
+					'pending' => 1,
+					'files' => [],
+				],
+				'rootError' => ['message' => 'Envelope error', 'code' => 500],
+				'complete' => false,
+				'expectedStatus' => 'ERROR',
+				'expectFile' => false,
+				'expectError' => true,
+			],
+			'file errors suppress root error' => [
+				'progress' => [
+					'total' => 1,
+					'signed' => 0,
+					'pending' => 0,
+					'inProgress' => 0,
+					'files' => [
+						[
+							'id' => 10,
+							'name' => 'file.pdf',
+							'status' => FileStatus::DRAFT->value,
+							'statusText' => 'DRAFT',
+							'error' => ['message' => 'File failed', 'code' => 422],
+						],
+					],
+					'errors' => 1,
+				],
+				'rootError' => ['message' => 'Root error', 'code' => 500],
+				'complete' => true,
+				'expectedStatus' => 'DRAFT',
+				'expectFile' => false,
+				'expectError' => false,
+			],
+			'file errors prevent file response even if complete' => [
+				'progress' => [
+					'total' => 1,
+					'signed' => 0,
+					'pending' => 0,
+					'inProgress' => 0,
+					'files' => [
+						[
+							'id' => 11,
+							'name' => 'file.pdf',
+							'status' => FileStatus::DRAFT->value,
+							'statusText' => 'DRAFT',
+							'error' => ['message' => 'File failed', 'code' => 422],
+						],
+					],
+					'errors' => 1,
+				],
+				'rootError' => null,
+				'complete' => true,
+				'expectedStatus' => 'DRAFT',
+				'expectFile' => false,
+				'expectError' => false,
+			],
+		];
+	}
+
+	#[DataProvider('progressResponseScenarios')]
+	public function testCheckProgressByUuidResponseBusinessRules(
+		array $progress,
+		?array $rootError,
+		bool $complete,
+		string $expectedStatus,
+		bool $expectFile,
+		bool $expectError,
+	): void {
+		$uuid = 'test-uuid';
+		$file = new FileEntity();
+		$file->setId(1);
+		$file->setName('test.pdf');
+		$file->setStatus(FileStatus::DRAFT->value);
+
+		$signRequest = new SignRequestEntity();
+		$signRequest->setId(1);
+		$signRequest->setFileId(1);
+		$signRequest->setUuid($uuid);
+
+		$this->signRequestMapper
+			->method('getByUuid')
+			->willReturn($signRequest);
+
+		$this->fileMapper
+			->method('getById')
+			->willReturn($file);
+
+		$this->fileMapper
+			->method('getTextOfStatus')
+			->willReturnCallback(fn ($s) => FileStatus::tryFrom($s)?->name ?? 'UNKNOWN');
+
+		$statusCode = $expectedStatus === 'SIGNED'
+			? FileStatus::SIGNED->value
+			: FileStatus::DRAFT->value;
+
+		$this->progressService
+			->method('getStatusCodeForSignRequest')
+			->willReturn($statusCode);
+
+		$this->progressService
+			->method('pollForStatusOrErrorChange')
+			->willReturn($statusCode);
+
+		$this->progressService
+			->method('getSignRequestProgress')
+			->willReturn($progress);
+
+		$this->progressService
+			->method('getSignRequestError')
+			->willReturn($rootError);
+
+		$this->progressService
+			->method('isProgressComplete')
+			->willReturn($complete);
+
+		if ($expectFile) {
+			$this->sessionService->method('getIdentifyMethodId')->willReturn(1);
+			$this->request->method('getServerHost')->willReturn('localhost');
+			$this->userSession->method('getUser')->willReturn(null);
+			$this->fileService->method('setFile')->willReturnSelf();
+			$this->fileService->method('setSignRequest')->willReturnSelf();
+			$this->fileService->method('setIdentifyMethodId')->willReturnSelf();
+			$this->fileService->method('setHost')->willReturnSelf();
+			$this->fileService->method('setMe')->willReturnSelf();
+			$this->fileService->method('showVisibleElements')->willReturnSelf();
+			$this->fileService->method('showSigners')->willReturnSelf();
+			$this->fileService->method('showSettings')->willReturnSelf();
+			$this->fileService->method('showMessages')->willReturnSelf();
+			$this->fileService->method('showValidateFile')->willReturnSelf();
+			$this->fileService->method('toArray')->willReturn(['id' => 1]);
+		}
+
+		$response = $this->controller->checkProgressByUuid($uuid);
+		$this->assertEquals(Http::STATUS_OK, $response->getStatus());
+		$data = $response->getData();
+
+		$this->assertEquals($expectedStatus, $data['status']);
+		if ($expectFile) {
+			$this->assertArrayHasKey('file', $data);
+		} else {
+			$this->assertArrayNotHasKey('file', $data);
+		}
+
+		if ($expectError) {
+			$this->assertArrayHasKey('error', $data);
+		} else {
+			$this->assertArrayNotHasKey('error', $data);
+		}
+	}
 }

From 7b359ebce5ea057ff4b6af886bae605d69a026f8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 26 Jan 2026 19:28:10 -0300
Subject: [PATCH 34/34] fix: cs

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 .../Service/SignRequest/Error/ErrorPayloadBuilderTest.php   | 4 ++--
 .../SignRequest/Error/SignRequestErrorReporterTest.php      | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
index 415a39a0b0..2ff20acb54 100644
--- a/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
+++ b/tests/php/Unit/Service/SignRequest/Error/ErrorPayloadBuilderTest.php
@@ -66,7 +66,7 @@ public function testBuildWithContext(
 		?int $signRequestId,
 		?string $signRequestUuid,
 		array $expectedKeys,
-		array $notExpectedKeys
+		array $notExpectedKeys,
 	): void {
 		$builder = new ErrorPayloadBuilder();
 		$payload = $builder
@@ -161,7 +161,7 @@ public function testFromException(
 		?int $fileId,
 		?int $signRequestId,
 		?string $signRequestUuid,
-		array $expectedKeys
+		array $expectedKeys,
 	): void {
 		$exception = new \Exception($message, $code);
 
diff --git a/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
index d511cd0e67..4d98b7534d 100644
--- a/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
+++ b/tests/php/Unit/Service/SignRequest/Error/SignRequestErrorReporterTest.php
@@ -267,7 +267,7 @@ public function testErrorWithVariousContextCombinations(
 		array $context,
 		bool $expectSignRequestError,
 		bool $expectFileError,
-		int $expectedTtl
+		int $expectedTtl,
 	): void {
 		if ($expectSignRequestError) {
 			$this->progressService->expects($this->once())
@@ -340,7 +340,7 @@ public static function exceptionTypesDataProvider(): array {
 	public function testErrorWithDifferentExceptionTypes(
 		\Throwable $exception,
 		string $expectedMessage,
-		int $expectedCode
+		int $expectedCode,
 	): void {
 		$context = [
 			'exception' => $exception,
@@ -427,7 +427,7 @@ public static function missingRequiredFieldsDataProvider(): array {
 	#[DataProvider('missingRequiredFieldsDataProvider')]
 	public function testErrorDoesNotStoreWhenRequiredFieldsMissing(
 		array $context,
-		bool $shouldStore
+		bool $shouldStore,
 	): void {
 		if ($shouldStore) {
 			$this->progressService->expects($this->atLeastOnce())