From 20b84e071c094f6d833af916aa4dd1630eb63ad1 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 598f90ac76e0b0b84b89e0e5e08f226e7d4322fa 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 66a50e4b05349e41ecc2600d8bb9bd6a0dbd983e 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 ba962777cf57c997d91e7cb7ccb9b432bd3f25cd 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 145eea911d5dcaddad88f7a2726ce6a1e09108f4 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 bd44877037157599a2621d59d688e5362cecbc10 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 a17fc610deadbbd0fc1c3c29a5998e90106c5daa 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 b8a6a4a00a815ad57cb8fc0f961307ead480876d 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 99b1359ccca879308705e3acf609e0bd7e27706a 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 63d715f4b680f76d467763ec38ef3bcb1a8f5645 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 5e387e0ab419f96b5c7d2432c563cc1efe1df0cf 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 b13b215f30276cc0e4bca781480aaa085bb1730f 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 8c8ae564c9d6101644445cc30e07a00e41efc25f 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 28e945784df2d4d232a8de596cbefcec023bd12a 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 0ae800bcd5e8932c912187d3a2db7a6b3d7d615a 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 a9d499c575f6e2c4a276f047720c704b09a28038 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 890210a53153a851d078740a16c8f9b71defcd32 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 a3418e7e6c3f453aca80c752e991e6144b285502 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 38dccd56a7231272f8222f4491f9773a491d6ce4 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 3ece2e19fee2458061a61441edb7ad99caf98650 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 394602978624774e930582b0d22feb7b00cdd06d 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 4e1a4c315253764a3120c8f0a80dfc27d964c7b4 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 c9b6940abf5e3a0fc950406545db274c5caca71d 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 4753c539f39f5212269dd1e089a0e6aa9a50f8cf 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 10d78e749d9af87570c8916ff2ea958eb934a05d 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 180e765afcd7e7c216e41faef4179ad05b1a3ddf 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 dd664f8307fe27b6fa695c66c3bd300fd902adc5 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 677a82f7e342dcd06f857e4b753ecefb57065138 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 3c9e3b22134aece223d367994ab4b2bebabf34c9 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 81153a2e8f87065275694eaa5296430f01937a31 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 68f087ab5da96d8294a4c139245f82c002ba2a4e 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 09bb9853e571ae3f49aaff4cf7079b8360007f2a 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 22f907c68400dc0f08d6ae0c0c79f6383250fd38 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 6e91822d2e0ba93473b1e85a4f7f1541a673f97b 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())