Initial Version

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

shared/lib/Mail/Service/IServiceIdentity.php

@@ -0,0 +1,36 @@
+<?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;
+
+/**
+ * Mail Service Identity Interface
+ * 
+ * Base interface for authentication credentials used by mail services.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentity extends JsonSerializable {
+
+    public const TYPE_BASIC = 'basic';
+    public const TYPE_OAUTH = 'oauth';
+    public const TYPE_APIKEY = 'apikey';
+
+    /**
+     * Gets the identity/authentication type
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string One of: 'basic', 'oauth', 'apikey'
+     */
+    public function getType(): string;
+
+}

shared/lib/Mail/Service/IServiceIdentityApiKey.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service API Key Identity Interface
+ * 
+ * API key authentication for transactional mail services (SendGrid, Mailgun, etc.)
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityApiKey extends IServiceIdentity {
+
+    /**
+     * Gets the API key
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getApiKey(): string;
+
+    /**
+     * Gets the optional API key identifier/name
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getApiKeyId(): ?string;
+
+}

shared/lib/Mail/Service/IServiceIdentityBasic.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Basic Authentication Identity Interface
+ * 
+ * Username/password authentication for traditional mail services.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityBasic extends IServiceIdentity {
+
+    /**
+     * Gets the username/login identifier
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getUsername(): string;
+
+    /**
+     * Gets the password/secret
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getPassword(): string;
+
+}

shared/lib/Mail/Service/IServiceIdentityOAuth.php

@@ -0,0 +1,68 @@
+<?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 DateTimeImmutable;
+
+/**
+ * Mail Service OAuth Identity Interface
+ * 
+ * OAuth2 token-based authentication for modern mail APIs.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityOAuth extends IServiceIdentity {
+
+    /**
+     * Gets the OAuth access token
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getAccessToken(): string;
+
+    /**
+     * Gets the OAuth refresh token
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getRefreshToken(): ?string;
+
+    /**
+     * Gets the token expiration time
+     * 
+     * @since 2025.05.01
+     * 
+     * @return DateTimeImmutable|null
+     */
+    public function getExpiresAt(): ?DateTimeImmutable;
+
+    /**
+     * Gets the granted OAuth scopes
+     * 
+     * @since 2025.05.01
+     * 
+     * @return array<string>
+     */
+    public function getScopes(): array;
+
+    /**
+     * Checks if the access token has expired
+     * 
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function isExpired(): bool;
+
+}

shared/lib/Mail/Service/IServiceLocation.php

@@ -0,0 +1,105 @@
+<?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;
+
+/**
+ * Mail Service Location Interface
+ * 
+ * Unified interface supporting both URI-based (API services) and socket-based
+ * (traditional IMAP/SMTP) connection configurations.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceLocation extends JsonSerializable {
+
+    public const TYPE_URI = 'uri';
+    public const TYPE_SOCKET_SINGLE = 'socket-single';
+    public const TYPE_SOCKET_SPLIT = 'socket-split';
+
+    public const SECURITY_NONE = 'none';
+    public const SECURITY_SSL = 'ssl';
+    public const SECURITY_TLS = 'tls';
+    public const SECURITY_STARTTLS = 'starttls';
+
+    /**
+     * Gets the location type
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string One of: 'uri', 'socket-single', 'socket-split'
+     */
+    public function getType(): string;
+
+    /**
+     * Gets the URI for API-based services (JMAP, EWS, Graph API, HTTP relay)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null URI or null if not URI-based
+     */
+    public function getUri(): ?string;
+
+    /**
+     * Gets the inbound/primary host for socket-based services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null Hostname or null if URI-based
+     */
+    public function getInboundHost(): ?string;
+
+    /**
+     * Gets the inbound/primary port for socket-based services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return int|null Port number or null if URI-based
+     */
+    public function getInboundPort(): ?int;
+
+    /**
+     * Gets the inbound/primary security mode
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
+     */
+    public function getInboundSecurity(): ?string;
+
+    /**
+     * Gets the outbound host for split-socket services (e.g., SMTP separate from IMAP)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null Hostname or null if not split-socket
+     */
+    public function getOutboundHost(): ?string;
+
+    /**
+     * Gets the outbound port for split-socket services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return int|null Port number or null if not split-socket
+     */
+    public function getOutboundPort(): ?int;
+
+    /**
+     * Gets the outbound security mode for split-socket services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
+     */
+    public function getOutboundSecurity(): ?string;
+
+}

shared/lib/Mail/Service/IServiceSend.php

@@ -0,0 +1,49 @@
+<?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 KTXF\Mail\Entity\IMessageMutable;
+use KTXF\Mail\Exception\SendException;
+
+/**
+ * Mail Service Send Interface
+ * 
+ * Interface for mail services capable of sending outbound messages.
+ * This is the minimum capability for an outbound-only mail service.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceSend extends IServiceBase {
+
+    public const CAPABILITY_SEND = 'Send';
+
+    /**
+     * Creates a new fresh message object
+     *
+     * @since 2025.05.01
+     *
+     * @return IMessageMutable Fresh message object for composing
+     */
+    public function messageFresh(): IMessageMutable;
+
+    /**
+     * Sends an outbound message
+     *
+     * @since 2025.05.01
+     *
+     * @param IMessageMutable $message Message to send
+     *
+     * @return string Message ID assigned by the transport
+     * 
+     * @throws SendException On delivery failure
+     */
+    public function messageSend(IMessageMutable $message): string;
+
+}

shared/lib/Mail/Service/ServiceIdentityApiKey.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service API Key Identity Implementation
+ * 
+ * API key authentication for transactional mail services.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceIdentityApiKey implements IServiceIdentityApiKey {
+
+    /**
+     * @param string $apiKey API key
+     * @param string|null $apiKeyId Optional API key identifier
+     */
+    public function __construct(
+        private string $apiKey,
+        private ?string $apiKeyId = null,
+    ) {}
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['apiKey'] ?? '',
+            $data['apiKeyId'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return self::TYPE_APIKEY;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getApiKey(): string {
+        return $this->apiKey;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getApiKeyId(): ?string {
+        return $this->apiKeyId;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            'type' => self::TYPE_APIKEY,
+            'apiKeyId' => $this->apiKeyId,
+            // API key intentionally omitted from serialization for security
+        ], fn($v) => $v !== null);
+    }
+
+}

shared/lib/Mail/Service/ServiceIdentityBasic.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Basic Identity Implementation
+ * 
+ * Username/password authentication credentials.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceIdentityBasic implements IServiceIdentityBasic {
+
+    /**
+     * @param string $username Login username
+     * @param string $password Login password
+     */
+    public function __construct(
+        private string $username,
+        private string $password,
+    ) {}
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['username'] ?? '',
+            $data['password'] ?? '',
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return self::TYPE_BASIC;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUsername(): string {
+        return $this->username;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getPassword(): string {
+        return $this->password;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return [
+            'type' => self::TYPE_BASIC,
+            'username' => $this->username,
+            // Password intentionally omitted from serialization for security
+        ];
+    }
+
+}

shared/lib/Mail/Service/ServiceLocation.php

@@ -0,0 +1,211 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Location Implementation
+ * 
+ * Unified implementation supporting URI-based and socket-based connections.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceLocation implements IServiceLocation {
+
+    /**
+     * @param string $type Location type (uri, socket-single, socket-split)
+     * @param string|null $uri URI for API-based services
+     * @param string|null $inboundHost Inbound/primary host
+     * @param int|null $inboundPort Inbound/primary port
+     * @param string|null $inboundSecurity Inbound security (none, ssl, tls, starttls)
+     * @param string|null $outboundHost Outbound host (for split-socket)
+     * @param int|null $outboundPort Outbound port (for split-socket)
+     * @param string|null $outboundSecurity Outbound security (for split-socket)
+     */
+    public function __construct(
+        private string $type,
+        private ?string $uri = null,
+        private ?string $inboundHost = null,
+        private ?int $inboundPort = null,
+        private ?string $inboundSecurity = null,
+        private ?string $outboundHost = null,
+        private ?int $outboundPort = null,
+        private ?string $outboundSecurity = null,
+    ) {}
+
+    /**
+     * Creates a URI-based location (for API services)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $uri
+     * 
+     * @return self
+     */
+    public static function uri(string $uri): self {
+        return new self(self::TYPE_URI, $uri);
+    }
+
+    /**
+     * Creates a single-socket location (e.g., SMTP only)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $host
+     * @param int $port
+     * @param string $security
+     * 
+     * @return self
+     */
+    public static function socket(string $host, int $port, string $security = self::SECURITY_TLS): self {
+        return new self(
+            self::TYPE_SOCKET_SINGLE,
+            null,
+            $host,
+            $port,
+            $security
+        );
+    }
+
+    /**
+     * Creates a split-socket location (IMAP + SMTP)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $inboundHost IMAP host
+     * @param int $inboundPort IMAP port
+     * @param string $inboundSecurity IMAP security
+     * @param string $outboundHost SMTP host
+     * @param int $outboundPort SMTP port
+     * @param string $outboundSecurity SMTP security
+     * 
+     * @return self
+     */
+    public static function splitSocket(
+        string $inboundHost,
+        int $inboundPort,
+        string $inboundSecurity,
+        string $outboundHost,
+        int $outboundPort,
+        string $outboundSecurity
+    ): self {
+        return new self(
+            self::TYPE_SOCKET_SPLIT,
+            null,
+            $inboundHost,
+            $inboundPort,
+            $inboundSecurity,
+            $outboundHost,
+            $outboundPort,
+            $outboundSecurity
+        );
+    }
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['type'] ?? self::TYPE_SOCKET_SINGLE,
+            $data['uri'] ?? null,
+            $data['inboundHost'] ?? $data['host'] ?? null,
+            $data['inboundPort'] ?? $data['port'] ?? null,
+            $data['inboundSecurity'] ?? $data['security'] ?? null,
+            $data['outboundHost'] ?? null,
+            $data['outboundPort'] ?? null,
+            $data['outboundSecurity'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return $this->type;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUri(): ?string {
+        return $this->uri;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundHost(): ?string {
+        return $this->inboundHost;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundPort(): ?int {
+        return $this->inboundPort;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundSecurity(): ?string {
+        return $this->inboundSecurity;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundHost(): ?string {
+        return $this->outboundHost ?? $this->inboundHost;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundPort(): ?int {
+        return $this->outboundPort ?? $this->inboundPort;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundSecurity(): ?string {
+        return $this->outboundSecurity ?? $this->inboundSecurity;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        $data = ['type' => $this->type];
+        
+        if ($this->type === self::TYPE_URI) {
+            $data['uri'] = $this->uri;
+        } else {
+            $data['inboundHost'] = $this->inboundHost;
+            $data['inboundPort'] = $this->inboundPort;
+            $data['inboundSecurity'] = $this->inboundSecurity;
+            
+            if ($this->type === self::TYPE_SOCKET_SPLIT) {
+                $data['outboundHost'] = $this->outboundHost;
+                $data['outboundPort'] = $this->outboundPort;
+                $data['outboundSecurity'] = $this->outboundSecurity;
+            }
+        }
+        
+        return array_filter($data, fn($v) => $v !== null);
+    }
+
+}

shared/lib/Mail/Service/ServiceScope.php

@@ -0,0 +1,37 @@
+<?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;
+
+/**
+ * Defines the scope/context of a mail service
+ * 
+ * @since 2025.05.01
+ */
+enum ServiceScope: string implements JsonSerializable {
+
+    /**
+     * System-level service for tenant-wide communications
+     * (e.g., notifications@, reports@, noreply@)
+     */
+    case System = 'system';
+
+    /**
+     * User-level service for personal mail accounts
+     * (e.g., user's own IMAP/SMTP accounts)
+     */
+    case User = 'user';
+
+    public function jsonSerialize(): string {
+        return $this->value;
+    }
+
+}