feat: introduce FileStatus enum for type-safe status handling

Add FileStatus backed enum to provide compile-time type safety for file
status values. This replaces the previous int-based approach with a
proper enum that:

- Eliminates the need for default fallback in match expressions
- Provides IDE autocomplete for all valid status values
- Throws ValueError for invalid status codes instead of silently
  returning unknown status
- Accepts both int and FileStatus for backward compatibility

Updated getTextOfStatus() to use FileStatus enum with automatic
conversion from int via FileStatus::from(). Removed null return type
as status column is NOT NULL in database, ensuring statusText is
always a string.

This improves code maintainability and prevents invalid status values
from being used throughout the codebase.

Signed-off-by: Vitor Mattos <[email protected]>

Author: vitormattos

lib/Db/FileMapper.php

@@ -8,6 +8,7 @@
 
 namespace OCA\Libresign\Db;
 
+use OCA\Libresign\Enum\FileStatus;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Db\QBMapper;
 use OCP\Comments\ICommentsManager;
@@ -245,21 +246,23 @@ public function getFileType(int $id): string {
 		return 'not_libresign_file';
 	}
 
-	public function getTextOfStatus(int $status): ?string {
+	public function getTextOfStatus(int|FileStatus $status): string {
+		if (is_int($status)) {
+			$status = FileStatus::from($status);
+		}
 		return match ($status) {
 			// TRANSLATORS Name of the status when document is not a LibreSign file
-			File::STATUS_NOT_LIBRESIGN_FILE => $this->l->t('not LibreSign file'),
+			FileStatus::NOT_LIBRESIGN_FILE => $this->l->t('not LibreSign file'),
 			// TRANSLATORS Name of the status that the document is still as a draft
-			File::STATUS_DRAFT => $this->l->t('draft'),
+			FileStatus::DRAFT => $this->l->t('draft'),
 			// TRANSLATORS Name of the status that the document can be signed
-			File::STATUS_ABLE_TO_SIGN => $this->l->t('available for signature'),
+			FileStatus::ABLE_TO_SIGN => $this->l->t('available for signature'),
 			// TRANSLATORS Name of the status when the document has already been partially signed
-			File::STATUS_PARTIAL_SIGNED => $this->l->t('partially signed'),
+			FileStatus::PARTIAL_SIGNED => $this->l->t('partially signed'),
 			// TRANSLATORS Name of the status when the document has been completely signed
-			File::STATUS_SIGNED => $this->l->t('signed'),
+			FileStatus::SIGNED => $this->l->t('signed'),
 			// TRANSLATORS Name of the status when the document was deleted
-			File::STATUS_DELETED => $this->l->t('deleted'),
-			default => '',
+			FileStatus::DELETED => $this->l->t('deleted'),
 		};
 	}
 

lib/Db/IdDocsMapper.php

@@ -303,7 +303,7 @@ private function getIdDocStatusText(int $status): string {
 		return match ($status) {
 			File::STATUS_ABLE_TO_SIGN => $this->l10n->t('waiting for approval'),
 			File::STATUS_SIGNED => $this->l10n->t('approved'),
-			default => $this->fileMapper->getTextOfStatus($status) ?? '',
+			default => $this->fileMapper->getTextOfStatus($status),
 		};
 	}
 }

lib/Enum/FileStatus.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Enum;
+
+/**
+ * File status enum
+ *
+ * Represents all possible states a LibreSign file can be in
+ */
+enum FileStatus: int {
+	case NOT_LIBRESIGN_FILE = -1;
+	case DRAFT = 0;
+	case ABLE_TO_SIGN = 1;
+	case PARTIAL_SIGNED = 2;
+	case SIGNED = 3;
+	case DELETED = 4;
+}

lib/ResponseDefinitions.php

@@ -42,7 +42,7 @@
  * }
  * @psalm-type LibresignNextcloudFile = array{
  *     message: string,
- *     name: string,
+ *     name: non-falsy-string,
  *     id: int,
  *     status: int,
  *     statusText: string,