Initial Version

shared/lib/Mail/Provider/IProviderBase.php

@@ -0,0 +1,132 @@
+<?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 JsonSerializable;
+use KTXF\Mail\Selector\ServiceSelector;
+use KTXF\Mail\Service\IServiceBase;
+
+/**
+ * Mail Provider Base Interface
+ * 
+ * Core interface for mail providers with context-aware service discovery.
+ * 
+ * @since 2025.05.01
+ */
+interface IProviderBase extends JsonSerializable {
+
+    public const CAPABILITY_SERVICE_LIST = 'ServiceList';
+    public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
+    public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
+    public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';
+
+    public const JSON_TYPE = 'mail.provider';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_LABEL = 'label';
+    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
+
+    /**
+     * Confirms if a specific capability is supported
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value Required capability e.g. 'ServiceList'
+     *
+     * @return bool
+     */
+    public function capable(string $value): bool;
+
+    /**
+     * Lists all supported capabilities
+     *
+     * @since 2025.05.01
+     *
+     * @return array<string,bool>
+     */
+    public function capabilities(): array;
+
+    /**
+     * Gets the unique identifier for this provider
+     *
+     * @since 2025.05.01
+     *
+     * @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
+     */
+    public function id(): string;
+
+    /**
+     * Gets the localized human-friendly name of this provider
+     *
+     * @since 2025.05.01
+     *
+     * @return string Provider label (e.g., 'SMTP Mail Provider')
+     */
+    public function label(): string;
+
+    /**
+     * Lists services for a tenant, optionally filtered by user context
+     * 
+     * When userId is null, returns only System-scoped services.
+     * When userId is provided, returns System-scoped services plus
+     * User-scoped services owned by that user.
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context (null = system only)
+     * @param ServiceSelector|null $selector Optional filter criteria
+     *
+     * @return array<string|int, IServiceBase>
+     */
+    public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;
+
+    /**
+     * Checks if specific services exist
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param string|int ...$identifiers Service identifiers to check
+     *
+     * @return array<string|int, bool> Identifier => exists
+     */
+    public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;
+
+    /**
+     * Fetches a specific service by identifier
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param string|int $identifier Service identifier
+     *
+     * @return IServiceBase|null
+     */
+    public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;
+
+    /**
+     * 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|null $userId User identifier for context
+     * @param string $address Email address to find service for
+     *
+     * @return IServiceBase|null Service handling the address, or null
+     */
+    public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;
+
+}

shared/lib/Mail/Provider/IProviderServiceMutate.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\Json\JsonDeserializable;
+use KTXF\Mail\Service\IServiceBase;
+
+/**
+ * Mail Provider Service Mutate Interface
+ * 
+ * Optional interface for providers that support service CRUD operations.
+ * 
+ * @since 2025.05.01
+ */
+interface IProviderServiceMutate extends JsonDeserializable {
+
+    public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
+    public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
+    public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
+    public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
+
+    /**
+     * Creates a new blank service instance for configuration
+     *
+     * @since 2025.05.01
+     *
+     * @return IServiceBase Fresh service object
+     */
+    public function serviceFresh(): IServiceBase;
+
+    /**
+     * Creates a new service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId Owner user ID (null for system services)
+     * @param IServiceBase $service Service configuration to create
+     *
+     * @return string|int Created service identifier
+     */
+    public function serviceCreate(string $tenantId, ?string $userId, IServiceBase $service): string|int;
+
+    /**
+     * Modifies an existing service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for authorization context
+     * @param IServiceBase $service Service configuration to update
+     *
+     * @return string|int Updated service identifier
+     */
+    public function serviceModify(string $tenantId, ?string $userId, IServiceBase $service): string|int;
+
+    /**
+     * Destroys a service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for authorization context
+     * @param IServiceBase $service Service to destroy
+     *
+     * @return bool True if destroyed, false if not found
+     */
+    public function serviceDestroy(string $tenantId, ?string $userId, IServiceBase $service): bool;
+
+}