Initial Version

2025-12-21 10:09:54 -05:00
commit 2fbddd7dbc
366 changed files with 41999 additions and 0 deletions
--- a/shared/lib/Mail/Service/IServiceBase.php
+++ b/shared/lib/Mail/Service/IServiceBase.php
@@ -0,0 +1,139 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use JsonSerializable;
+use KTXF\Mail\Entity\IAddress;
+
+/**
+ * Mail Service Base Interface
+ * 
+ * Core interface for mail services providing identity, addressing, and capability information.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceBase extends JsonSerializable {
+
+    public const JSON_TYPE = 'mail.service';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_PROVIDER = 'provider';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_LABEL = 'label';
+    public const JSON_PROPERTY_SCOPE = 'scope';
+    public const JSON_PROPERTY_OWNER = 'owner';
+    public const JSON_PROPERTY_ENABLED = 'enabled';
+    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
+    public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
+    public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';
+
+    /**
+     * Confirms if a specific capability is supported
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value Required capability e.g. 'Send'
+     *
+     * @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 of the provider this service belongs to
+     *
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function in(): string;
+
+    /**
+     * Gets the unique identifier for this service
+     *
+     * @since 2025.05.01
+     * 
+     * @return string|int
+     */
+    public function id(): string|int;
+
+    /**
+     * Gets the localized human-friendly name of this service
+     *
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getLabel(): string;
+
+    /**
+     * Gets the scope of this service (System or User)
+     *
+     * @since 2025.05.01
+     * 
+     * @return ServiceScope
+     */
+    public function getScope(): ServiceScope;
+
+    /**
+     * Gets the owner user ID for User-scoped services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null User ID or null for System scope
+     */
+    public function getOwner(): ?string;
+
+    /**
+     * Gets whether this service is enabled
+     *
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function getEnabled(): bool;
+
+    /**
+     * Gets the primary mailing address for this service
+     *
+     * @since 2025.05.01
+     *
+     * @return IAddress
+     */
+    public function getPrimaryAddress(): IAddress;
+
+    /**
+     * Gets the secondary mailing addresses (aliases) for this service
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAddress>
+     */
+    public function getSecondaryAddresses(): array;
+
+    /**
+     * Checks if this service handles a specific email address
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $address Email address to check
+     * 
+     * @return bool True if address matches primary or any secondary address
+     */
+    public function handlesAddress(string $address): bool;
+
+}