refactor: centralize LibresignAccountCapabilitySettings type

Define LibresignAccountCapabilitySettings as a shared Psalm type in
ResponseDefinitions.php. AccountSettingsProvider imports and uses it
as its return type. SettingsLoader imports LibresignSettings for the
getUserIdentificationSettings() return type annotation.

The OpenAPI schema now exposes AccountCapabilitySettings as a first-
class schema object with the three required boolean fields.

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

Author: vitormattos

lib/ResponseDefinitions.php

@@ -28,6 +28,11 @@
  *     needIdentificationDocuments: bool,
  *     identificationDocumentsWaitingApproval: bool,
  * }
+ * @psalm-type LibresignAccountCapabilitySettings = array{
+ *     canRequestSign: bool,
+ *     hasSignatureFile: bool,
+ *     isApprover: bool,
+ * }
  *
  * Request input contracts
  *

lib/Service/File/AccountSettingsProvider.php

@@ -15,6 +15,7 @@
 use OCP\Accounts\IAccountManager;
 use OCP\IUser;
 
+/** @psalm-import-type LibresignAccountCapabilitySettings from \OCA\Libresign\ResponseDefinitions */
 class AccountSettingsProvider {
 	public function __construct(
 		private IAccountManager $accountManager,
@@ -23,12 +24,15 @@ public function __construct(
 	) {
 	}
 
+	/** @psalm-return LibresignAccountCapabilitySettings */
 	public function getSettings(?IUser $user = null): array {
 		$canApproveIdDocs = $this->idDocsPolicyService->userCanApproveValidationDocuments($user, false);
-		$return['canRequestSign'] = $canApproveIdDocs;
-		$return['hasSignatureFile'] = $this->hasSignatureFile($user);
-		$return['isApprover'] = $canApproveIdDocs;
-		return $return;
+
+		return [
+			'canRequestSign' => $canApproveIdDocs,
+			'hasSignatureFile' => $this->hasSignatureFile($user),
+			'isApprover' => $canApproveIdDocs,
+		];
 	}
 
 	public function getPhoneNumber(IUser $user): string {

lib/Service/File/SettingsLoader.php

@@ -17,6 +17,7 @@
 use OCA\Libresign\Service\IdentifyMethodService;
 use OCP\IUser;
 
+/** @psalm-import-type LibresignSettings from \OCA\Libresign\ResponseDefinitions */
 class SettingsLoader {
 	public const IDENTIFICATION_DOCUMENTS_DISABLED = 0;
 	public const IDENTIFICATION_DOCUMENTS_NEED_SEND = 1;
@@ -125,7 +126,7 @@ private function calculateStatusFromFiles(?array $files): int {
 	 * Always returns complete settings payload with defaults.
 	 * Canonical API shape is documented as LibresignSettings in ResponseDefinitions.
 	 *
-	 * @return array<string, bool|string>
+	 * @psalm-return LibresignSettings
 	 */
 	public function getUserIdentificationSettings(?IUser $user, ?SignRequest $signRequest = null): array {
 		$status = $this->getIdentificationDocumentsStatus($user, $signRequest);

openapi-full.json

@@ -20,6 +20,25 @@
             }
         },
         "schemas": {
+            "AccountCapabilitySettings": {
+                "type": "object",
+                "required": [
+                    "canRequestSign",
+                    "hasSignatureFile",
+                    "isApprover"
+                ],
+                "properties": {
+                    "canRequestSign": {
+                        "type": "boolean"
+                    },
+                    "hasSignatureFile": {
+                        "type": "boolean"
+                    },
+                    "isApprover": {
+                        "type": "boolean"
+                    }
+                }
+            },
             "AccountMeResponse": {
                 "type": "object",
                 "required": [

src/types/openapi/openapi-full.ts

@@ -1610,6 +1610,11 @@ export type paths = {
 export type webhooks = Record<string, never>;
 export type components = {
     schemas: {
+        AccountCapabilitySettings: {
+            canRequestSign: boolean;
+            hasSignatureFile: boolean;
+            isApprover: boolean;
+        };
         AccountMeResponse: {
             account: {
                 uid: string;