Nodarx/server
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Projects Releases Activity

refactor: docs

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-06-20 19:04:05 -04:00
parent a3443b1e54
commit 802849a60d
12 changed files with 76 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shared/lib/Mail/Entity/EntityBaseAbstract.php
+3 -3
View File
@@ -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
+3 -3
View File
@@ -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
+1 -1
View File
@@ -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
+3 -3
View File
@@ -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
+3 -3
View File
@@ -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
+2 -5
View File
@@ -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
}
shared/lib/Mail/Provider/ProviderServiceTestInterface.php
+4 -36
View File
@@ -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;
shared/lib/Mail/Service/ServiceBaseInterface.php
+35 -37
View File
@@ -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<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 $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<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
+2 -3
View File
@@ -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
*/
shared/lib/Mail/Service/ServiceConfigurableInterface.php
+2 -3
View File
@@ -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
*/
shared/lib/Mail/Service/ServiceEntityMutableInterface.php
+16 -17
View File
@@ -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<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
+2 -3
View File
@@ -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
*/