resource provider and service improvements

2026-01-03 13:18:04 -05:00
parent 74f9278749
commit 8f35442335
36 changed files with 1447 additions and 1086 deletions
--- a/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php
+++ b/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php
@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Provider;
+
+/**
+ * Mail Provider Autodiscovery Interface
+ * 
+ * Optional interface for mail providers that support automatic service discovery
+ * from email addresses or domains. Providers implementing this interface can
+ * discover mail service configurations using various methods specific to their
+ * protocol or provider type.
+ * 
+ * Examples:
+ * - IMAP/SMTP providers: Mozilla Autoconfig, DNS SRV, well-known URIs
+ * - JMAP providers: Well-known JMAP endpoint discovery
+ * - Provider-specific: Gmail, Outlook, etc. with known configurations
+ * 
+ * @since 2025.05.01
+ */
+interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {
+
+    public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';
+
+    /**
+     * Discover service configuration
+     * 
+     * Attempts to discover service configuration using provider-specific methods.
+     * Each provider may use different discovery mechanisms:
+     * - IMAP/SMTP: config database, DNS SRV, well-known URIs, common patterns
+     * - JMAP: Well-known JMAP session discovery
+     * - Provider-specific: Known configurations for popular providers
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $identity Identity to discover configuration for
+     * @param array $options Provider-specific options (e.g., preferred protocols, timeout)
+     * 
+     * @return array Discovery results in the format:
+     * [
+     *   'domain' => 'example.com',
+     *   'provider' => 'gmail|outlook|generic|etc',  // Optional detected provider
+     *   'results' => [
+     *     [
+     *       'protocol' => 'imap|smtp|jmap|etc',
+     *       'host' => 'imap.example.com',
+     *       'port' => 993,
+     *       'security' => 'ssl|tls|starttls|none',
+     *       'authentication' => ['plain', 'login', 'oauth2'],  // Supported auth methods
+     *       'confidence' => 'high|medium|low',
+     *       'source' => 'mozilla|srv|wellknown|common|verified',  // Discovery method used
+     *     ],
+     *     // ... more protocol results
+     *   ]
+     * ]
+     * 
+     * Returns empty results array if no configuration could be discovered.
+     */
+    public function serviceDiscover(string $identity, array $options = []): array;
+
+}