From 802849a60d52a70cd99868ac658674b4c79856c3 Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Sat, 20 Jun 2026 19:04:05 -0400 Subject: [PATCH] refactor: docs Signed-off-by: Sebastian Krupinski --- shared/lib/Mail/Entity/EntityBaseAbstract.php | 6 +- .../lib/Mail/Entity/EntityMutableAbstract.php | 6 +- .../Object/MessagePropertiesBaseAbstract.php | 2 +- .../Mail/Provider/ProviderBaseInterface.php | 6 +- .../ProviderServiceDiscoverInterface.php | 6 +- .../ProviderServiceMutateInterface.php | 7 +- .../Provider/ProviderServiceTestInterface.php | 40 ++--------- .../lib/Mail/Service/ServiceBaseInterface.php | 72 +++++++++---------- .../ServiceCollectionMutableInterface.php | 5 +- .../Service/ServiceConfigurableInterface.php | 5 +- .../Service/ServiceEntityMutableInterface.php | 33 +++++---- .../Mail/Service/ServiceMutableInterface.php | 5 +- 12 files changed, 76 insertions(+), 117 deletions(-) diff --git a/shared/lib/Mail/Entity/EntityBaseAbstract.php b/shared/lib/Mail/Entity/EntityBaseAbstract.php index ec46240..fdcc8b2 100644 --- a/shared/lib/Mail/Entity/EntityBaseAbstract.php +++ b/shared/lib/Mail/Entity/EntityBaseAbstract.php @@ -14,15 +14,15 @@ use KTXF\Resource\Identifier\EntityIdentifier; use KTXF\Resource\Provider\Node\NodeBaseAbstract; /** - * Abstract Mail Entity Base Class + * Abstract Entity Base Class * - * Provides common implementation for mail entities + * Provides common implementation for entities * * @since 2025.05.01 */ abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface { - protected string $type = 'mail.entity'; + protected string $type = 'mail:entity'; protected MessagePropertiesBaseInterface $properties; protected function nodeIdentifier(): EntityIdentifier { diff --git a/shared/lib/Mail/Entity/EntityMutableAbstract.php b/shared/lib/Mail/Entity/EntityMutableAbstract.php index 204f638..494e63d 100644 --- a/shared/lib/Mail/Entity/EntityMutableAbstract.php +++ b/shared/lib/Mail/Entity/EntityMutableAbstract.php @@ -15,15 +15,15 @@ use KTXF\Resource\Provider\Node\NodeMutableAbstract; use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface; /** - * Abstract Mail Entity Mutable Class + * Abstract Entity Mutable Class * - * Provides common implementation for mutable mail entities + * Provides common implementation for mutable entities * * @since 2025.05.01 */ abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface { - protected string $type = 'mail.entity'; + protected string $type = 'mail:entity'; protected MessagePropertiesMutableInterface $properties; protected function nodeIdentifier(): EntityIdentifier { diff --git a/shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php b/shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php index f975f59..624d54a 100644 --- a/shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php +++ b/shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php @@ -22,7 +22,7 @@ use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract; */ abstract class MessagePropertiesBaseAbstract extends NodePropertiesBaseAbstract implements MessagePropertiesBaseInterface { - protected string $type = 'mail.message'; + protected string $type = 'mail:message'; protected function extractBodyContent(?MessagePartInterface $part, string $type): ?string { if ($part === null) { diff --git a/shared/lib/Mail/Provider/ProviderBaseInterface.php b/shared/lib/Mail/Provider/ProviderBaseInterface.php index 42be2e3..9e15a4f 100644 --- a/shared/lib/Mail/Provider/ProviderBaseInterface.php +++ b/shared/lib/Mail/Provider/ProviderBaseInterface.php @@ -13,15 +13,15 @@ use KTXF\Mail\Service\ServiceBaseInterface; use KTXF\Resource\Provider\ResourceProviderBaseInterface; /** - * Mail Provider Base Interface + * Provider Base Interface * - * Core interface for mail providers with context-aware service discovery. + * Core interface for providers with context-aware service discovery. * * @since 2025.05.01 */ interface ProviderBaseInterface extends ResourceProviderBaseInterface{ - public const JSON_TYPE = 'mail.provider'; + public const JSON_TYPE = 'mail:provider'; /** * Finds a service that handles a specific email address diff --git a/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php b/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php index dc0ee84..e8c4f38 100644 --- a/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php +++ b/shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php @@ -12,11 +12,11 @@ namespace KTXF\Mail\Provider; use KTXF\Resource\Provider\ResourceServiceLocationInterface; /** - * Mail Provider Autodiscovery Interface + * Provider Autodiscovery Interface * - * Optional interface for mail providers that support automatic service discovery + * Optional interface for 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 + * discover service configurations using various methods specific to their * protocol or provider type. * * Examples: diff --git a/shared/lib/Mail/Provider/ProviderServiceMutateInterface.php b/shared/lib/Mail/Provider/ProviderServiceMutateInterface.php index ac0c426..10f4a43 100644 --- a/shared/lib/Mail/Provider/ProviderServiceMutateInterface.php +++ b/shared/lib/Mail/Provider/ProviderServiceMutateInterface.php @@ -12,11 +12,9 @@ namespace KTXF\Mail\Provider; use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface; /** - * Mail Provider Service Mutate Interface + * Provider Service Mutate Interface * - * Optional interface for providers that support service CRUD operations. - * - * Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface). + * Optional interface for providers that support service CRUD operations * * @since 2025.05.01 * @@ -28,6 +26,5 @@ use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface; interface ProviderServiceMutateInterface extends ResourceProviderServiceMutateInterface { // Methods inherited from ResourceProviderServiceMutateInterface - // Implementations should return/accept ServiceMutableInterface instances } diff --git a/shared/lib/Mail/Provider/ProviderServiceTestInterface.php b/shared/lib/Mail/Provider/ProviderServiceTestInterface.php index 32007fc..d8073e8 100644 --- a/shared/lib/Mail/Provider/ProviderServiceTestInterface.php +++ b/shared/lib/Mail/Provider/ProviderServiceTestInterface.php @@ -13,16 +13,9 @@ use KTXF\Mail\Service\ServiceBaseInterface; use KTXF\Mail\Service\ServiceMutableInterface; /** - * Mail Provider Service Test Interface + * 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) + * Optional interface for providers that support testing service connections * * @since 2025.05.01 */ @@ -33,12 +26,7 @@ interface ProviderServiceTestInterface { /** * 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. + * Tests connectivity, authentication, and capabilities of a service * * @since 2025.05.01 * @@ -51,28 +39,8 @@ interface ProviderServiceTestInterface { * * @return array Test results in the format: * [ - * 'success' => bool, + * 'disposition' => 'Success' | 'Failure' | 'Warning', * '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|ServiceMutableInterface $service, array $options = []): array; diff --git a/shared/lib/Mail/Service/ServiceBaseInterface.php b/shared/lib/Mail/Service/ServiceBaseInterface.php index 0d562c0..f7883b6 100644 --- a/shared/lib/Mail/Service/ServiceBaseInterface.php +++ b/shared/lib/Mail/Service/ServiceBaseInterface.php @@ -11,6 +11,7 @@ namespace KTXF\Mail\Service; use Generator; use KTXF\Mail\Collection\CollectionBaseInterface; +use KTXF\Mail\Entity\EntityBaseInterface; use KTXF\Mail\Object\AddressInterface; use KTXF\Resource\BinaryResource; use KTXF\Resource\Delta\Delta; @@ -22,10 +23,9 @@ use KTXF\Resource\Range\RangeType; use KTXF\Resource\Sort\ISort; /** - * Mail Service Base Interface + * Service Base Interface * - * Core interface for mail services with full protocol support (IMAP, JMAP, EWS, ActiveSync, Gmail API, etc.) - * Provides identity, addressing, capability information, and collection/message operations. + * Minimum interface for a service, providing read-only access to collections and entities. * * @since 2025.05.01 */ @@ -72,7 +72,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public const CAPABILITY_ENTITY_SORT_DATE_SENT = 'sent'; public const CAPABILITY_ENTITY_SORT_SIZE = 'size'; - public const JSON_TYPE = 'mail.service'; + public const JSON_TYPE = 'mail:service'; public const PROPERTY_PRIMARY_ADDRESS = 'primaryAddress'; public const PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses'; @@ -113,7 +113,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * - * @return array Collections indexed by ID + * @return array Collections indexed by identifier */ public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array; @@ -140,9 +140,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int ...$identifiers Collection IDs to check + * @param string|int ...$identifiers Collection identifiers to check * - * @return array Map of ID => exists + * @return array Map of identifier => exists */ public function collectionExtant(string|int $location, string|int ...$identifiers): array; @@ -151,44 +151,44 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { * * @since 2025.05.01 * - * @param string|int $identifier Collection ID + * @param string|int $identifier Collection identifier * * @return CollectionBaseInterface|null Collection or null if not found */ public function collectionFetch(string|int $identifier): ?CollectionBaseInterface; /** - * Lists messages in a collection + * Lists entities in a collection * * @since 2025.05.01 * - * @param string|int $collection Collection ID + * @param string|int $collection Collection identifier * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * @param IRange|null $range Optional pagination - * @param array|null $properties Optional message properties to fetch + * @param array|null $properties Optional entity properties to fetch * - * @return array Messages indexed by Urn + * @return array Entities indexed by Urn */ public function entityListBulk(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; /** - * Lists messages in a collection + * Lists entities in a collection * * @since 2025.05.01 * - * @param string|int $collection Collection ID + * @param string|int $collection Collection identifier * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * @param IRange|null $range Optional pagination - * @param array|null $properties Optional message properties to fetch + * @param array|null $properties Optional entity properties to fetch * - * @return Generator Yields messages one by one as EntityBaseInterface + * @return Generator Yields entities one by one as EntityBaseInterface */ public function entityListStream(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator; /** - * Creates a filter builder for messages + * Creates a filter builder for entities * * @since 2025.05.01 * @@ -197,7 +197,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListFilter(): IFilter; /** - * Creates a sort builder for messages + * Creates a sort builder for entities * * @since 2025.05.01 * @@ -206,7 +206,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListSort(): ISort; /** - * Creates a range builder for messages + * Creates a range builder for entities * * @since 2025.05.01 * @@ -217,59 +217,57 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface { public function entityListRange(RangeType $type): IRange; /** - * Gets incremental changes since last sync + * Gets incremental changes since last signature * * @since 2025.05.01 * - * @param string|int $collection Collection ID - * @param string $signature Sync token from previous sync - * @param string $detail Detail level: 'ids', 'minimal', 'full' + * @param string|int $collection Collection identifier + * @param string $signature Token from previous delta * * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array] */ - public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta; + public function entityDelta(string|int $collection, string $signature): Delta; /** - * Checks if messages exist + * Checks if entities exist * * @since 2025.05.01 * - * @param string|int $collection Collection ID - * @param string|int ...$identifiers Message IDs to check + * @param string|int $collection Collection identifier + * @param string|int ...$identifiers Entity identifiers to check * - * @return array Map of ID => exists + * @return array Map of identifier => exists */ public function entityExtant(string|int $collection, string|int ...$identifiers): array; /** - * Fetches one or more entities + * Fetches one or more entities as an array * * @since 2025.05.01 * - * @param EntityIdentifierInterface ...$identifiers Message identifiers to fetch + * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch * - * @return array Messages indexed by Urn + * @return array Entities indexed by Urn */ public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array; /** - * Fetches one or more entities + * Fetches one or more entities as a stream * * @since 2025.05.01 * - * @param EntityIdentifierInterface ...$identifiers Message identifiers to fetch + * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch * - * @return Generator Yields messages one by one + * @return Generator Yields entities one by one */ public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator; - /** - * Downloads a message or part of a message + * Downloads an entity or part of an entity * * @since 2025.05.01 * - * @param EntityIdentifierInterface $target Message identifier + * @param EntityIdentifierInterface $target Entity identifier * @param array|null $part Optional part to download * * @return BinaryResource diff --git a/shared/lib/Mail/Service/ServiceCollectionMutableInterface.php b/shared/lib/Mail/Service/ServiceCollectionMutableInterface.php index f17b45c..02d3b1a 100644 --- a/shared/lib/Mail/Service/ServiceCollectionMutableInterface.php +++ b/shared/lib/Mail/Service/ServiceCollectionMutableInterface.php @@ -15,10 +15,9 @@ use KTXF\Mail\Collection\CollectionPropertiesBaseInterface; use KTXF\Resource\Identifier\CollectionIdentifier; /** - * Mail Service Collection Mutable Interface + * Service Collection Mutable Interface * - * Optional interface for services that support collection CRUD operations. - * Provides mailbox/folder creation, modification, deletion, and moving. + * Optional interface for services that support collection CRUD operations * * @since 2025.05.01 */ diff --git a/shared/lib/Mail/Service/ServiceConfigurableInterface.php b/shared/lib/Mail/Service/ServiceConfigurableInterface.php index ca0e3c7..9568cdb 100644 --- a/shared/lib/Mail/Service/ServiceConfigurableInterface.php +++ b/shared/lib/Mail/Service/ServiceConfigurableInterface.php @@ -12,10 +12,9 @@ namespace KTXF\Mail\Service; use KTXF\Resource\Provider\ResourceServiceConfigureInterface; /** - * Mail Service Configurable Interface + * Service Configurable Interface * - * Extends base service interface with setter methods for mutable properties. - * Used for service configuration and updates. + * Extends base service interface with setter methods for mutable properties * * @since 2025.05.01 */ diff --git a/shared/lib/Mail/Service/ServiceEntityMutableInterface.php b/shared/lib/Mail/Service/ServiceEntityMutableInterface.php index 58fde5a..238bdb2 100644 --- a/shared/lib/Mail/Service/ServiceEntityMutableInterface.php +++ b/shared/lib/Mail/Service/ServiceEntityMutableInterface.php @@ -16,10 +16,9 @@ use KTXF\Resource\Identifier\CollectionIdentifier; use KTXF\Resource\Identifier\EntityIdentifier; /** - * Mail Service Entity Mutable Interface + * Service Entity Mutable Interface * - * Optional interface for services that support entity CRUD operations. - * Provides entity creation, modification, deletion, copying, moving, and flag management. + * Optional interface for services that support entity CRUD operations * * @since 2025.05.01 */ @@ -66,6 +65,20 @@ interface ServiceEntityMutableInterface { */ public function entityModify(EntityIdentifier $target, MessagePropertiesMutableInterface $properties): EntityBaseInterface; + /** + * Patches an existing entity(ies) with partial data + * + * @since 2025.05.01 + * + * @param MessagePropertiesMutableInterface $properties Partial entity properties + * @param EntityIdentifier ...$targets Source entities to patch + * + * @return array Results keyed by source entity identifier + */ + public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array; + /** * Deletes entities * @@ -81,20 +94,6 @@ interface ServiceEntityMutableInterface { */ public function entityDelete(EntityIdentifier ...$targets): array; - /** - * Patches an existing entity(ies) with partial data - * - * @since 2025.05.01 - * - * @param MessagePropertiesMutableInterface $properties Partial entity properties - * @param EntityIdentifier ...$targets Source entities to patch - * - * @return array Results keyed by source entity identifier - */ - public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array; - /** * Moves entities to another collection * diff --git a/shared/lib/Mail/Service/ServiceMutableInterface.php b/shared/lib/Mail/Service/ServiceMutableInterface.php index 701e2c5..018fbba 100644 --- a/shared/lib/Mail/Service/ServiceMutableInterface.php +++ b/shared/lib/Mail/Service/ServiceMutableInterface.php @@ -13,10 +13,9 @@ use KTXF\Mail\Object\AddressInterface; use KTXF\Resource\Provider\ResourceServiceMutateInterface; /** - * Mail Service Mutable Interface + * Service Mutable Interface * - * Extends base service interface with setter methods for mutable properties. - * Used for service configuration and updates. + * Extends base service interface with setter methods for mutable properties * * @since 2025.05.01 */