Initial Version

shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Provider;
+
+use KTXF\Resource\Provider\ResourceServiceLocationInterface;
+
+/**
+ * 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 {
+
+    /**
+     * Attempts to discover service configuration using provider-specific methods.
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $tenantId Tenant identifier
+     * @param string $userId User identifier
+     * @param string $identity Identity to discover configuration for (e.g., email address)
+     * @param string|null $location Optional hostname to test directly (bypasses DNS lookup)
+     * @param string|null $secret Optional password/token to validate discovered service
+     * 
+     * @return ResourceServiceLocationInterface|null Discovered location or null if not found
+     */
+    public function serviceDiscover(
+        string $tenantId, 
+        string $userId, 
+        string $identity,
+        ?string $location = null,
+        ?string $secret = null
+    ): ResourceServiceLocationInterface|null;
+
+}