refactor: documents interfaces

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

shared/lib/Documents/Provider/ProviderServiceTestInterface.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Provider;
+
+use KTXF\Documents\Service\ServiceBaseInterface;
+use KTXF\Documents\Service\ServiceMutableInterface;
+
+/**
+ * Provider Service Test Interface
+ *
+ * Optional interface for providers that support testing service connections
+ *
+ * @since 2025.05.01
+ */
+interface ProviderServiceTestInterface {
+
+    public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
+
+    /**
+     * Test a service connection
+     *
+     * Tests connectivity, authentication, and capabilities of a service
+     *
+     * @since 2025.05.01
+     *
+     * @param ServiceBaseInterface|ServiceMutableInterface $service Service to test (can be fresh/unsaved or existing)
+     * @param array $options Provider-specific test options:
+     *   - 'timeout' => int (seconds, default: 10)
+     *   - 'verify_ssl' => bool (default: true)
+     *
+     * @return array Test results in the format:
+     * [
+     *   'disposition' => 'Success' | 'Failure' | 'Warning',
+     *   'message' => 'Connection successful' | 'Error message',
+     * ]
+     */
+    public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array;
+
+}