refactor: docs

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

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 {

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 {

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) {

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

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:

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.
+ * Optional interface for providers that support service CRUD operations
- * 
- * Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
  * 
  * @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
 
 }

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.
+ * Optional interface for 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
  */
@@ -33,12 +26,7 @@ interface ProviderServiceTestInterface {
     /**
      * Test a service connection
      * 
-     * Tests connectivity, authentication, and capabilities of a service.
+     * 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
      * 
@@ -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;

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.)
+ * Minimum interface for a service, providing read-only access to collections and entities.
- * Provides identity, addressing, capability information, and collection/message operations.
  * 
  * @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<string|int,CollectionBaseInterface> Collections indexed by ID
+     * @return array<string|int,CollectionBaseInterface> 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<string|int,bool> Map of ID => exists
+     * @return array<string|int,bool> 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<string,EntityBaseInterface> Messages indexed by Urn
+     * @return array<string,EntityBaseInterface> 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|int $collection Collection identifier
-     * @param string $signature Sync token from previous sync
+     * @param string $signature Token from previous delta
-     * @param string $detail Detail level: 'ids', 'minimal', 'full'
      *
      * @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 $collection Collection identifier
-     * @param string|int ...$identifiers Message IDs to check
+     * @param string|int ...$identifiers Entity identifiers to check
      *
-     * @return array<string|int,bool> Map of ID => exists
+     * @return array<string|int,bool> 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<string,EntityBaseInterface> Messages indexed by Urn
+     * @return array<string,EntityBaseInterface> 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<string,EntityBaseInterface> Yields messages one by one
+     * @return Generator<string,EntityBaseInterface> 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

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.
+ * Optional interface for services that support collection CRUD operations
- * Provides mailbox/folder creation, modification, deletion, and moving.
  * 
  * @since 2025.05.01
  */

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.
+ * Extends base service interface with setter methods for mutable properties
- * Used for service configuration and updates.
  * 
  * @since 2025.05.01
  */

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.
+ * Optional interface for services that support entity CRUD operations
- * Provides entity creation, modification, deletion, copying, moving, and flag management.
  * 
  * @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<string, array{
+     *     disposition: 'patched'|'error'
+     * }> 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<string, array{
-     *     disposition: 'patched'|'error'
-     * }> Results keyed by source entity identifier
-     */
-    public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array;
-
     /**
      * Moves entities to another collection
      *

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.
+ * Extends base service interface with setter methods for mutable properties
- * Used for service configuration and updates.
  * 
  * @since 2025.05.01
  */