Initial Version

shared/lib/Mail/Provider/ProviderBaseInterface.php

@@ -0,0 +1,41 @@
+<?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\Mail\Service\ServiceBaseInterface;
+use KTXF\Resource\Provider\ResourceProviderBaseInterface;
+
+/**
+ * Mail Provider Base Interface
+ * 
+ * Core interface for mail providers with context-aware service discovery.
+ * 
+ * @since 2025.05.01
+ */
+interface ProviderBaseInterface extends ResourceProviderBaseInterface{
+
+    public const JSON_TYPE = 'mail.provider';
+    
+    /**
+     * Finds a service that handles a specific email address
+     * 
+     * Searches within the appropriate scope based on userId context.
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string $userId User identifier
+     * @param string $address Email address to find service for
+     *
+     * @return ServiceBaseInterface|null Service handling the address, or null
+     */
+    public function serviceFindByAddress(string $tenantId, string $userId, string $address): ?ServiceBaseInterface;
+
+}

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;
+
+}

shared/lib/Mail/Provider/ProviderServiceMutateInterface.php

@@ -0,0 +1,35 @@
+<?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\ResourceProviderServiceMutateInterface;
+
+/**
+ * Mail Provider Service Mutate Interface
+ * 
+ * Optional interface for providers that support service CRUD operations.
+ * 
+ * Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
+ * 
+ * @since 2025.05.01
+ * 
+ * @method ServiceMutableInterface serviceFresh() Construct a new blank mail service instance
+ * @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a mail service configuration
+ * @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a mail service configuration
+ * @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a mail service configuration
+ */
+interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface {
+
+    public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
+
+	// Methods inherited from ResourceProviderServiceMutateInterface
+	// Implementations should return/accept ServiceMutableInterface instances
+
+}

shared/lib/Mail/Provider/ProviderServiceTestInterface.php

@@ -0,0 +1,77 @@
+<?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\Mail\Service\ServiceBaseInterface;
+
+/**
+ * Mail Provider Service Test Interface
+ * 
+ * Optional interface for mail providers that support testing service connections.
+ * Providers implementing this interface can validate connection parameters,
+ * test authentication, and verify service availability before creating a
+ * persistent service configuration.
+ * 
+ * Supports two testing modes:
+ * 1. Testing an existing service (validate current configuration)
+ * 2. Testing a fresh configuration (validate before saving)
+ * 
+ * @since 2025.05.01
+ */
+interface ProviderServiceTestInterface extends ProviderBaseInterface {
+
+    /**
+     * Test a service connection
+     * 
+     * Tests connectivity, authentication, and capabilities of a service.
+     * 
+     * For new services: use serviceFresh() to create a service, configure it with
+     * setters, then pass it to this method for testing before persisting.
+     * 
+     * For existing services: fetch the service and pass it directly.
+     * 
+     * @since 2025.05.01
+     * 
+     * @param ServiceBaseInterface $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)
+     *   - 'test_send' => bool (attempt test send if capable, default: false)
+     *   - 'test_receive' => bool (attempt mailbox access if capable, default: true)
+     * 
+     * @return array Test results in the format:
+     * [
+     *   'success' => bool,
+     *   'message' => 'Connection successful' | 'Error message',
+     *   'details' => [
+     *     'connected' => bool,               // Socket/HTTP connection succeeded
+     *     'authenticated' => bool,            // Authentication succeeded
+     *     'capabilities' => ['IMAP4rev1', ...],  // Server capabilities (if applicable)
+     *     'serverInfo' => 'Server version/banner',
+     *     'latency' => 123,                   // Connection time in milliseconds
+     *     'protocols' => [
+     *       'inbound' => [
+     *         'connected' => bool,
+     *         'authenticated' => bool,
+     *         'error' => 'error message if failed'
+     *       ],
+     *       'outbound' => [                   // For split-socket (IMAP+SMTP)
+     *         'connected' => bool,
+     *         'authenticated' => bool,
+     *         'error' => 'error message if failed'
+     *       ]
+     *     ],
+     *     'errors' => ['Error 1', 'Error 2'],  // List of errors encountered
+     *   ]
+     * ]
+     */
+    public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
+
+}