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

Initial Version

Browse Source
This commit is contained in:
root
2025-12-21 10:09:54 -05:00
commit 4ae6befc7b
422 changed files with 47225 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
shared/lib/Mail/Collection/CollectionBaseAbstract.php Normal file
View File

@@ -0,0 +1,31 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Mail Collection Base Class
*
* Provides common implementation for mail collections
*
* @since 2025.05.01
*/
abstract class CollectionBase extends NodeBaseAbstract implements CollectionBaseInterface {
protected CollectionPropertiesBaseAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesBaseInterface {
return $this->properties;
}
}

30
shared/lib/Mail/Collection/CollectionBaseInterface.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
/**
* Mail Collection Base Interface
*
* Interface represents a mailbox/folder in a mail service
*
* @since 2025.05.01
*/
interface CollectionBaseInterface extends NodeBaseInterface {
/**
* Gets the collection properties
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesBaseInterface|CollectionPropertiesMutableInterface;
}

49
shared/lib/Mail/Collection/CollectionMutableAbstract.php Normal file
View File

@@ -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\Collection;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Mail Collection Mutable Class
*
* Provides common implementation for mutable mail collections
*
* @since 2025.05.01
*/
abstract class CollectionMutableAbstract extends NodeMutableAbstract implements CollectionMutableInterface {
protected CollectionPropertiesMutableAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof CollectionPropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement CollectionPropertiesMutableInterface');
}
// Copy all property values
$this->properties->setLabel($value->getLabel());
$this->properties->setRole($value->getRole());
$this->properties->setRank($value->getRank());
$this->properties->setSubscription($value->getSubscription());
return $this;
}
}

32
shared/lib/Mail/Collection/CollectionMutableInterface.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* Mail Collection Mutable Interface
*
* Interface for altering mailbox/folder properties in a mail service
*
* @since 2025.05.01
*
* @method static setProperties(CollectionPropertiesMutableInterface $value)
*/
interface CollectionMutableInterface extends CollectionBaseInterface, NodeMutableInterface {
/**
* Gets the collection properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesMutableInterface;
}

68
shared/lib/Mail/Collection/CollectionPropertiesBaseAbstract.php Normal file
View File

@@ -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\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
/**
* Abstract Mail Collection Properties Base Class
*
* Provides common implementation for mail collection properties
*
* @since 2025.05.01
*/
abstract class CollectionPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements CollectionPropertiesBaseInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function total(): int {
return $this->data['total'] ?? 0;
}
/**
* @inheritDoc
*/
public function unread(): int {
return $this->data['unread'] ?? 0;
}
/**
* @inheritDoc
*/
public function getLabel(): string {
return $this->data['label'] ?? '';
}
/**
* @inheritDoc
*/
public function getRole(): CollectionRoles {
return isset($this->data['role'])
? ($this->data['role'] instanceof CollectionRoles ? $this->data['role'] : CollectionRoles::from($this->data['role']))
: CollectionRoles::Custom;
}
/**
* @inheritDoc
*/
public function getRank(): int {
return $this->data['rank'] ?? 0;
}
/**
* @inheritDoc
*/
public function getSubscription(): bool {
return $this->data['subscribed'] ?? false;
}
}

35
shared/lib/Mail/Collection/CollectionPropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,35 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
interface CollectionPropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'mail.collection';
public const JSON_PROPERTY_TOTAL = 'total';
public const JSON_PROPERTY_UNREAD = 'unread';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_ROLE = 'role';
public const JSON_PROPERTY_RANK = 'rank';
public const JSON_PROPERTY_SUBSCRIPTION = 'subscription';
public function total(): int;
public function unread(): int;
public function getLabel(): string;
public function getRole(): CollectionRoles;
public function getRank(): int;
public function getSubscription(): bool;
}

65
shared/lib/Mail/Collection/CollectionPropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,65 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesMutableAbstract;
/**
* Abstract Mail Collection Properties Mutable Class
*/
abstract class CollectionPropertiesMutableAbstract extends CollectionPropertiesBaseAbstract implements CollectionPropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
$this->data = $data;
return $this;
}
/**
* @inheritDoc
*/
public function setLabel(string $value): static {
$this->data['label'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setRole(CollectionRoles $value): static {
$this->data['role'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setRank(int $value): static {
$this->data['rank'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSubscription(bool $value): static {
$this->data['subscription'] = $value;
return $this;
}
}

26
shared/lib/Mail/Collection/CollectionPropertiesMutableInterface.php Normal file
View File

@@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
interface CollectionPropertiesMutableInterface extends CollectionPropertiesBaseInterface, NodePropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
public function setLabel(string $value);
public function setRole(CollectionRoles $value): static;
public function setRank(int $value): static;
public function setSubscription(bool $value): static;
}

37
shared/lib/Mail/Collection/CollectionRoles.php Normal file
View File

@@ -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\Collection;
use JsonSerializable;
/**
* Mail Collection Roles
*
* Standard mailbox/folder roles for mail collections.
*
* @since 2025.05.01
*/
enum CollectionRoles: string implements JsonSerializable {
case Inbox = 'inbox';
case Drafts = 'drafts';
case Sent = 'sent';
case Trash = 'trash';
case Junk = 'junk';
case Archive = 'archive';
case Outbox = 'outbox';
case Queue = 'queue';
case Custom = 'custom';
public function jsonSerialize(): string {
return $this->value;
}
}

32
shared/lib/Mail/Entity/EntityBaseAbstract.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesBaseInterface;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Mail Entity Base Class
*
* Provides common implementation for mail entities
*
* @since 2025.05.01
*/
abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface {
protected MessagePropertiesBaseInterface $properties;
/**
* @inheritDoc
*/
public function getProperties(): MessagePropertiesBaseInterface {
return $this->properties;
}
}

27
shared/lib/Mail/Entity/EntityBaseInterface.php Normal file
View File

@@ -0,0 +1,27 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesBaseInterface;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
interface EntityBaseInterface extends NodeBaseInterface {
public const JSON_TYPE = 'mail.entity';
/**
* Gets the entity properties
*
* @since 2025.05.01
*/
public function getProperties(): MessagePropertiesBaseInterface|MessagePropertiesMutableInterface;
}

48
shared/lib/Mail/Entity/EntityMutableAbstract.php Normal file
View File

@@ -0,0 +1,48 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Mail Entity Mutable Class
*
* Provides common implementation for mutable mail entities
*
* @since 2025.05.01
*/
abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface {
public const JSON_TYPE = EntityMutableInterface::JSON_TYPE;
protected MessagePropertiesMutableInterface $properties;
/**
* @inheritDoc
*/
public function getProperties(): MessagePropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof MessagePropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement MessagePropertiesMutableInterface');
}
$this->properties = $value;
return $this;
}
}

29
shared/lib/Mail/Entity/EntityMutableInterface.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* @method static setProperties(MessagePropertiesMutableInterface $value)
*/
interface EntityMutableInterface extends EntityBaseInterface, NodeMutableInterface {
public const JSON_TYPE = EntityBaseInterface::JSON_TYPE;
/**
* Gets the entity properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): MessagePropertiesMutableInterface;
}

68
shared/lib/Mail/Exception/SendException.php Normal file
View File

@@ -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\Exception;
use Exception;
/**
* Mail Send Exception
*
* Exception thrown when mail delivery fails.
*
* @since 2025.05.01
*/
class SendException extends Exception {
/**
* @param string $message Error message
* @param int $code Error code
* @param Exception|null $previous Previous exception
* @param string|null $recipient Specific recipient that failed (if applicable)
* @param bool $permanent Whether this is a permanent failure (no retry)
*/
public function __construct(
string $message,
int $code = 0,
?Exception $previous = null,
public readonly ?string $recipient = null,
public readonly bool $permanent = false,
) {
parent::__construct($message, $code, $previous);
}
/**
* Creates a permanent failure exception (no retry)
*
* @since 2025.05.01
*
* @param string $message
* @param string|null $recipient
*
* @return self
*/
public static function permanent(string $message, ?string $recipient = null): self {
return new self($message, 0, null, $recipient, true);
}
/**
* Creates a temporary failure exception (will retry)
*
* @since 2025.05.01
*
* @param string $message
* @param Exception|null $previous
*
* @return self
*/
public static function temporary(string $message, ?Exception $previous = null): self {
return new self($message, 0, $previous, null, false);
}
}

127
shared/lib/Mail/Object/Address.php Normal file
View File

@@ -0,0 +1,127 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Address Implementation
*
* @since 2025.05.01
*/
class Address implements AddressInterface {
/**
* @param string $address Email address
* @param string|null $name Display name
*/
public function __construct(
private string $address = '',
private ?string $name = null,
) {}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ADDRESS => $this->address,
self::JSON_PROPERTY_LABEL => $this->name,
], fn($v) => $v !== null && $v !== '');
}
/**
* Creates an Address from a formatted string
*
* @since 2025.05.01
*
* @param string $value Formatted as "Name <address>" or just "address"
*
* @return self
*/
public static function fromString(string $value): self {
$value = trim($value);
// Match "Name <address>" format
if (preg_match('/^(.+?)\s*<([^>]+)>$/', $value, $matches)) {
return new self(trim($matches[2]), trim($matches[1], ' "\''));
}
// Match "<address>" format
if (preg_match('/^<([^>]+)>$/', $value, $matches)) {
return new self(trim($matches[1]));
}
// Assume plain address
return new self($value);
}
/**
* Creates an Address from an array
*
* @since 2025.05.01
*
* @param array $data Array with 'address' and optional 'name' keys
*
* @return self
*/
public static function fromArray(array $data): self {
return new self(
$data[self::JSON_PROPERTY_ADDRESS] ?? $data['address'] ?? '',
$data[self::JSON_PROPERTY_LABEL] ?? $data['name'] ?? null,
);
}
/**
* @inheritDoc
*/
public function getAddress(): string {
return $this->address;
}
/**
* @inheritDoc
*/
public function setAddress(string $address): static {
$this->address = $address;
return $this;
}
/**
* @inheritDoc
*/
public function getLabel(): ?string {
return $this->name;
}
/**
* @inheritDoc
*/
public function setLabel(?string $label): static {
$this->name = $label;
return $this;
}
/**
* @inheritDoc
*/
public function toString(): string {
if ($this->name !== null && $this->name !== '') {
return sprintf('"%s" <%s>', $this->name, $this->address);
}
return $this->address;
}
/**
* String representation
*/
public function __toString(): string {
return $this->toString();
}
}

63
shared/lib/Mail/Object/AddressInterface.php Normal file
View File

@@ -0,0 +1,63 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use KTXF\Json\JsonSerializable;
/**
* Address Interface
*
* Represents an email address with optional display name.
*
* @since 2025.05.01
*/
interface AddressInterface extends JsonSerializable {
public const JSON_PROPERTY_ADDRESS = 'address';
public const JSON_PROPERTY_LABEL = 'label';
/**
* Gets the email address
*
* @since 2025.05.01
*/
public function getAddress(): string;
/**
* Sets the email address
*
* @since 2025.05.01
*/
public function setAddress(string $value): static;
/**
* Gets the display name
*
* @since 2025.05.01
*/
public function getLabel(): ?string;
/**
* Sets the display name
*
* @since 2025.05.01
*/
public function setLabel(?string $value): static;
/**
* Gets the formatted address string
*
* @since 2025.05.01
*
* @return string Formatted as "Name <address>" or just "address" if no name
*/
public function toString(): string;
}

194
shared/lib/Mail/Object/Attachment.php Normal file
View File

@@ -0,0 +1,194 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Attachment Implementation
*
* @since 2025.05.01
*/
class Attachment implements AttachmentInterface {
/**
* @param string $name File name
* @param string $mimeType MIME type
* @param string $content Binary content
* @param string|null $id Attachment ID
* @param int|null $size Size in bytes
* @param string|null $contentId Content-ID for inline attachments
* @param bool $inline Whether inline attachment
*/
public function __construct(
private string $name,
private string $mimeType,
private string $content,
private ?string $id = null,
private ?int $size = null,
private ?string $contentId = null,
private bool $inline = false,
) {
if ($this->size === null) {
$this->size = strlen($this->content);
}
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ID => $this->id,
self::JSON_PROPERTY_NAME => $this->name,
self::JSON_PROPERTY_MIME_TYPE => $this->mimeType,
self::JSON_PROPERTY_SIZE => $this->size,
self::JSON_PROPERTY_CONTENT_ID => $this->contentId,
self::JSON_PROPERTY_INLINE => $this->inline ?: null,
'contentBase64' => $this->getContentBase64(),
], fn($v) => $v !== null);
}
/**
* Creates an attachment from a file path
*
* @since 2025.05.01
*
* @param string $path File path
* @param string|null $name Override file name
* @param string|null $mimeType Override MIME type
*
* @return self
*/
public static function fromFile(string $path, ?string $name = null, ?string $mimeType = null): self {
$content = file_get_contents($path);
$name = $name ?? basename($path);
$mimeType = $mimeType ?? mime_content_type($path) ?: 'application/octet-stream';
return new self($name, $mimeType, $content);
}
/**
* Creates an attachment from base64 encoded content
*
* @since 2025.05.01
*
* @param string $name File name
* @param string $mimeType MIME type
* @param string $base64Content Base64 encoded content
*
* @return self
*/
public static function fromBase64(string $name, string $mimeType, string $base64Content): self {
return new self($name, $mimeType, base64_decode($base64Content));
}
/**
* Creates an inline attachment for embedding in HTML
*
* @since 2025.05.01
*
* @param string $name File name
* @param string $mimeType MIME type
* @param string $content Binary content
* @param string $contentId Content-ID (without cid: prefix)
*
* @return self
*/
public static function inline(string $name, string $mimeType, string $content, string $contentId): self {
return new self($name, $mimeType, $content, null, null, $contentId, true);
}
/**
* Creates from array data
*
* @since 2025.05.01
*
* @param array $data
*
* @return self
*/
public static function fromArray(array $data): self {
$content = $data['content'] ?? '';
if (isset($data['contentBase64'])) {
$content = base64_decode($data['contentBase64']);
}
return new self(
$data[self::JSON_PROPERTY_NAME] ?? $data['name'] ?? '',
$data[self::JSON_PROPERTY_MIME_TYPE] ?? $data['mimeType'] ?? 'application/octet-stream',
$content,
$data[self::JSON_PROPERTY_ID] ?? $data['id'] ?? null,
$data[self::JSON_PROPERTY_SIZE] ?? $data['size'] ?? null,
$data[self::JSON_PROPERTY_CONTENT_ID] ?? $data['contentId'] ?? null,
$data[self::JSON_PROPERTY_INLINE] ?? $data['inline'] ?? false,
);
}
/**
* @inheritDoc
*/
public function getId(): ?string {
return $this->id;
}
/**
* @inheritDoc
*/
public function getName(): string {
return $this->name;
}
/**
* @inheritDoc
*/
public function getMimeType(): string {
return $this->mimeType;
}
/**
* @inheritDoc
*/
public function getSize(): ?int {
return $this->size;
}
/**
* @inheritDoc
*/
public function getContentId(): ?string {
return $this->contentId;
}
/**
* @inheritDoc
*/
public function isInline(): bool {
return $this->inline;
}
/**
* @inheritDoc
*/
public function getContent(): string {
return $this->content;
}
/**
* Gets the content as base64 encoded string
*
* @since 2025.05.01
*
* @return string
*/
public function getContentBase64(): string {
return base64_encode($this->content);
}
}

93
shared/lib/Mail/Object/AttachmentInterface.php Normal file
View File

@@ -0,0 +1,93 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use KTXF\Json\JsonSerializable;
/**
* Attachment Interface
*
* Represents a file attachment on a mail message.
*
* @since 2025.05.01
*/
interface AttachmentInterface extends JsonSerializable {
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_NAME = 'name';
public const JSON_PROPERTY_MIME_TYPE = 'mimeType';
public const JSON_PROPERTY_SIZE = 'size';
public const JSON_PROPERTY_CONTENT_ID = 'contentId';
public const JSON_PROPERTY_INLINE = 'inline';
/**
* Gets the attachment identifier
*
* @since 2025.05.01
*
* @return string|null Attachment ID or null for new attachments
*/
public function getId(): ?string;
/**
* Gets the file name
*
* @since 2025.05.01
*
* @return string File name (e.g., "document.pdf")
*/
public function getName(): string;
/**
* Gets the MIME type
*
* @since 2025.05.01
*
* @return string MIME type (e.g., "application/pdf")
*/
public function getMimeType(): string;
/**
* Gets the file size in bytes
*
* @since 2025.05.01
*
* @return int|null Size in bytes or null if unknown
*/
public function getSize(): ?int;
/**
* Gets the Content-ID for inline attachments
*
* @since 2025.05.01
*
* @return string|null Content-ID for referencing in HTML body (e.g., "cid:image1")
*/
public function getContentId(): ?string;
/**
* Checks if this is an inline attachment (embedded in body)
*
* @since 2025.05.01
*
* @return bool True if inline, false if regular attachment
*/
public function isInline(): bool;
/**
* Gets the attachment content
*
* @since 2025.05.01
*
* @return string Binary content of the attachment
*/
public function getContent(): string;
}

122
shared/lib/Mail/Object/MessagePartBaseAbstract.php Normal file
View File

@@ -0,0 +1,122 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Abstract Message Part Base Class
*
* Provides common implementation for message parts (read-only)
*
* @since 2025.05.01
*/
abstract class MessagePartBaseAbstract implements MessagePartInterface {
/**
* Internal data storage
*/
protected array $data = [];
/**
* Sub-parts storage
* @var array<int,MessagePartInterface>
*/
protected array $parts = [];
/**
* Constructor
*
* @param array &$data Reference to data array
*/
public function __construct(array &$data = null) {
if ($data === null) {
$data = [];
}
$this->data = &$data;
}
/**
* @inheritDoc
*/
public function getBlobId(): ?string {
return $this->data['blobId'] ?? null;
}
/**
* @inheritDoc
*/
public function getId(): ?string {
return $this->data['partId'] ?? null;
}
/**
* @inheritDoc
*/
public function getType(): ?string {
return $this->data['type'] ?? null;
}
/**
* @inheritDoc
*/
public function getDisposition(): ?string {
return $this->data['disposition'] ?? null;
}
/**
* @inheritDoc
*/
public function getName(): ?string {
return $this->data['name'] ?? null;
}
/**
* @inheritDoc
*/
public function getCharset(): ?string {
return $this->data['charset'] ?? null;
}
/**
* @inheritDoc
*/
public function getLanguage(): ?string {
return $this->data['language'] ?? null;
}
/**
* @inheritDoc
*/
public function getLocation(): ?string {
return $this->data['location'] ?? null;
}
/**
* @inheritDoc
*/
public function getParts(): array {
return $this->parts;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$result = $this->data;
if (!empty($this->parts)) {
$result['subParts'] = [];
foreach ($this->parts as $part) {
$result['subParts'][] = $part->jsonSerialize();
}
}
return $result;
}
}

104
shared/lib/Mail/Object/MessagePartInterface.php Normal file
View File

@@ -0,0 +1,104 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use KTXF\Json\JsonSerializable;
/**
* Message Part Interface
*
* Represents a MIME part of a message (body, attachment, etc.)
*
* @since 2025.05.01
*/
interface MessagePartInterface extends JsonSerializable {
/**
* Gets the blob identifier
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBlobId(): ?string;
/**
* Gets the part identifier
*
* @since 2025.05.01
*
* @return string|null
*/
public function getId(): ?string;
/**
* Gets the MIME type
*
* @since 2025.05.01
*
* @return string|null
*/
public function getType(): ?string;
/**
* Gets the content disposition (inline, attachment)
*
* @since 2025.05.01
*
* @return string|null
*/
public function getDisposition(): ?string;
/**
* Gets the part name
*
* @since 2025.05.01
*
* @return string|null
*/
public function getName(): ?string;
/**
* Gets the character set
*
* @since 2025.05.01
*
* @return string|null
*/
public function getCharset(): ?string;
/**
* Gets the language
*
* @since 2025.05.01
*
* @return string|null
*/
public function getLanguage(): ?string;
/**
* Gets the location
*
* @since 2025.05.01
*
* @return string|null
*/
public function getLocation(): ?string;
/**
* Gets the sub-parts
*
* @since 2025.05.01
*
* @return array<int,MessagePartInterface>
*/
public function getParts(): array;
}

146
shared/lib/Mail/Object/MessagePartMutableAbstract.php Normal file
View File

@@ -0,0 +1,146 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Abstract Message Part Mutable Class
*
* Provides common implementation for mutable message parts
*
* @since 2025.05.01
*/
abstract class MessagePartMutableAbstract extends MessagePartBaseAbstract {
/**
* Sets the blob identifier
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBlobId(string $value): static {
$this->data['blobId'] = $value;
return $this;
}
/**
* Sets the part identifier
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setId(string $value): static {
$this->data['partId'] = $value;
return $this;
}
/**
* Sets the MIME type
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setType(string $value): static {
$this->data['type'] = $value;
return $this;
}
/**
* Sets the content disposition
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setDisposition(string $value): static {
$this->data['disposition'] = $value;
return $this;
}
/**
* Sets the part name
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setName(string $value): static {
$this->data['name'] = $value;
return $this;
}
/**
* Sets the character set
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setCharset(string $value): static {
$this->data['charset'] = $value;
return $this;
}
/**
* Sets the language
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setLanguage(string $value): static {
$this->data['language'] = $value;
return $this;
}
/**
* Sets the location
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setLocation(string $value): static {
$this->data['location'] = $value;
return $this;
}
/**
* Sets the sub-parts
*
* @since 2025.05.01
*
* @param MessagePartInterface ...$value
*
* @return static
*/
public function setParts(MessagePartInterface ...$value): static {
$this->parts = $value;
return $this;
}
}

400
shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php Normal file
View File

@@ -0,0 +1,400 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
/**
* Abstract Message Properties Base Class
*
* Provides common implementation for message properties (read-only)
*
* @since 2025.05.01
*/
abstract class MessagePropertiesBaseAbstract extends NodePropertiesBaseAbstract implements MessagePropertiesBaseInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function version(): int {
return $this->data['version'] ?? 1;
}
/**
* @inheritDoc
*/
public function getHeaders(): array {
return $this->data['headers'] ?? [];
}
/**
* @inheritDoc
*/
public function getHeader(string $name): string|array|null {
return $this->data['headers'][$name] ?? null;
}
/**
* @inheritDoc
*/
public function getUrid(): ?string {
return $this->data['urid'] ?? null;
}
/**
* @inheritDoc
*/
public function getCreated(): ?DateTimeImmutable {
return $this->data['created'] ?? null;
}
/**
* @inheritDoc
*/
public function getModified(): ?DateTimeImmutable {
return $this->data['modified'] ?? null;
}
/**
* @inheritDoc
*/
public function getDate(): ?DateTimeImmutable {
return $this->data['date'] ?? null;
}
/**
* @inheritDoc
*/
public function getReceived(): ?DateTimeImmutable {
return $this->data['received'] ?? null;
}
/**
* @inheritDoc
*/
public function getSize(): ?int {
return $this->data['size'] ?? null;
}
/**
* @inheritDoc
*/
public function getSender(): ?AddressInterface {
return $this->data['sender'] ?? null;
}
/**
* @inheritDoc
*/
public function getFrom(): ?AddressInterface {
return $this->data['from'] ?? null;
}
/**
* @inheritDoc
*/
public function getReplyTo(): array {
return $this->data['replyTo'] ?? [];
}
/**
* @inheritDoc
*/
public function getTo(): array {
return $this->data['to'] ?? [];
}
/**
* @inheritDoc
*/
public function getCc(): array {
return $this->data['cc'] ?? [];
}
/**
* @inheritDoc
*/
public function getBcc(): array {
return $this->data['bcc'] ?? [];
}
/**
* @inheritDoc
*/
public function getInReplyTo(): ?string {
return $this->data['inReplyTo'] ?? null;
}
/**
* @inheritDoc
*/
public function getReferences(): array {
return $this->data['references'] ?? [];
}
/**
* @inheritDoc
*/
public function getSubject(): string {
return $this->data['subject'] ?? '';
}
/**
* @inheritDoc
*/
public function getSnippet(): ?string {
return $this->data['snippet'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyText(): ?string {
return $this->data['bodyText'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyTextCharset(): ?string {
return $this->data['bodyTextCharset'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyTextSize(): ?int {
return $this->data['bodyTextSize'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtml(): ?string {
return $this->data['bodyHtml'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtmlCharset(): ?string {
return $this->data['bodyHtmlCharset'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtmlSize(): ?int {
return $this->data['bodyHtmlSize'] ?? null;
}
/**
* @inheritDoc
*/
public function getAttachments(): array {
return $this->data['attachments'] ?? [];
}
/**
* @inheritDoc
*/
public function getFlags(): array {
return $this->data['flags'] ?? [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
/**
* @inheritDoc
*/
public function getFlag(string $name): bool {
return $this->data['flags'][$name] ?? false;
}
/**
* Gets message labels
*
* @since 2025.05.01
*
* @return array<int, string>
*/
public function getLabels(): array {
return $this->data['labels'] ?? [];
}
/**
* Gets message tags
*
* @since 2025.05.01
*
* @return array<int, string>
*/
public function getTags(): array {
return $this->data['tags'] ?? [];
}
/**
* Gets message priority
*
* @since 2025.05.01
*
* @return string
*/
public function getPriority(): string {
return $this->data['priority'] ?? 'normal';
}
/**
* Gets message sensitivity
*
* @since 2025.05.01
*
* @return string
*/
public function getSensitivity(): string {
return $this->data['sensitivity'] ?? 'normal';
}
/**
* Gets encryption information
*
* @since 2025.05.01
*
* @return array{method: string|null, signed: bool, encrypted: bool}
*/
public function getEncryption(): array {
return $this->data['encryption'] ?? [
'method' => null,
'signed' => false,
'encrypted' => false,
];
}
/**
* Checks if delivery receipt is requested
*
* @since 2025.05.01
*
* @return bool
*/
public function isDeliveryReceipt(): bool {
return $this->data['deliveryReceipt'] ?? false;
}
/**
* Checks if read receipt is requested
*
* @since 2025.05.01
*
* @return bool
*/
public function isReadReceipt(): bool {
return $this->data['readReceipt'] ?? false;
}
/**
* @inheritDoc
*/
public function hasRecipients(): bool {
return !empty($this->data['to']) || !empty($this->data['cc']) || !empty($this->data['bcc']);
}
/**
* @inheritDoc
*/
public function hasBody(): bool {
return ($this->data['bodyText'] !== null && $this->data['bodyText'] !== '')
|| ($this->data['bodyHtml'] !== null && $this->data['bodyHtml'] !== '');
}
/**
* @inheritDoc
*/
public function getBody(): ?MessagePartInterface {
return $this->data['body'] ?? null;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$data = [
self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
self::JSON_PROPERTY_VERSION => $this->data['version'] ?? 1,
];
if (!empty($this->data['headers'])) {
$data[self::JSON_PROPERTY_HEADERS] = $this->data['headers'];
}
if (isset($this->data['urid']) && $this->data['urid'] !== null) {
$data[self::JSON_PROPERTY_URID] = $this->data['urid'];
}
if (isset($this->data['date']) && $this->data['date'] !== null) {
$data[self::JSON_PROPERTY_DATE] = $this->data['date'] instanceof DateTimeImmutable
? $this->data['date']->format('c')
: $this->data['date'];
}
if (isset($this->data['received']) && $this->data['received'] !== null) {
$data[self::JSON_PROPERTY_RECEIVED] = $this->data['received'] instanceof DateTimeImmutable
? $this->data['received']->format('c')
: $this->data['received'];
}
if (isset($this->data['size']) && $this->data['size'] !== null) {
$data[self::JSON_PROPERTY_SIZE] = $this->data['size'];
}
if (isset($this->data['sender']) && $this->data['sender'] !== null) {
$data[self::JSON_PROPERTY_SENDER] = $this->data['sender'];
}
if (isset($this->data['from']) && $this->data['from'] !== null) {
$data[self::JSON_PROPERTY_FROM] = $this->data['from'];
}
if (!empty($this->data['replyTo'])) {
$data[self::JSON_PROPERTY_REPLY_TO] = $this->data['replyTo'];
}
if (!empty($this->data['to'])) {
$data[self::JSON_PROPERTY_TO] = $this->data['to'];
}
if (!empty($this->data['cc'])) {
$data[self::JSON_PROPERTY_CC] = $this->data['cc'];
}
if (!empty($this->data['bcc'])) {
$data[self::JSON_PROPERTY_BCC] = $this->data['bcc'];
}
if (isset($this->data['inReplyTo']) && $this->data['inReplyTo'] !== null) {
$data[self::JSON_PROPERTY_IN_REPLY_TO] = $this->data['inReplyTo'];
}
if (!empty($this->data['references'])) {
$data[self::JSON_PROPERTY_REFERENCES] = $this->data['references'];
}
if (isset($this->data['snippet']) && $this->data['snippet'] !== null) {
$data[self::JSON_PROPERTY_SNIPPET] = $this->data['snippet'];
}
if (!empty($this->data['attachments'])) {
$data[self::JSON_PROPERTY_ATTACHMENTS] = $this->data['attachments'];
}
$data[self::JSON_PROPERTY_SUBJECT] = $this->data['subject'] ?? null;
$data[self::JSON_PROPERTY_BODY] = $this->data['body'] ?? null;
return $data;
}
}

252
shared/lib/Mail/Object/MessagePropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,252 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
/**
* Message Properties Base Interface
*
* @since 2025.05.01
*/
interface MessagePropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'mail.message';
public const JSON_PROPERTY_HEADERS = 'headers';
public const JSON_PROPERTY_URID = 'urid';
public const JSON_PROPERTY_DATE = 'date';
public const JSON_PROPERTY_RECEIVED = 'received';
public const JSON_PROPERTY_SIZE = 'size';
public const JSON_PROPERTY_SENDER = 'sender';
public const JSON_PROPERTY_FROM = 'from';
public const JSON_PROPERTY_REPLY_TO = 'replyTo';
public const JSON_PROPERTY_TO = 'to';
public const JSON_PROPERTY_CC = 'cc';
public const JSON_PROPERTY_BCC = 'bcc';
public const JSON_PROPERTY_IN_REPLY_TO = 'inReplyTo';
public const JSON_PROPERTY_REFERENCES = 'references';
public const JSON_PROPERTY_SUBJECT = 'subject';
public const JSON_PROPERTY_SNIPPET = 'snippet';
public const JSON_PROPERTY_BODY = 'body';
public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
public const JSON_PROPERTY_TAGS = 'tags';
/**
* Gets custom headers
*
* @since 2025.05.01
*
* @return array<string,string> Header name => value
*/
public function getHeaders(): array;
/**
* Gets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
*
* @return string|array<int,string>|null Header value(s) or null if not set
*/
public function getHeader(string $name): string|array|null;
/**
* Gets the universal resource identifier (URN)
*
* @since 2025.05.01
*
* @return string|null
*/
public function getUrid(): ?string;
/**
* Gets the message date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getDate(): ?DateTimeImmutable;
/**
* Gets the received date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getReceived(): ?DateTimeImmutable;
/**
* Gets the message size in bytes
*
* @since 2025.05.01
*
* @return int|null
*/
public function getSize(): ?int;
/**
* Gets the sender address (actual sender, may differ from From)
*
* @since 2025.05.01
*
* @return AddressInterface|null
*/
public function getSender(): ?AddressInterface;
/**
* Gets the sender address
*
* @since 2025.05.01
*
* @return AddressInterface|null
*/
public function getFrom(): ?AddressInterface;
/**
* Gets the reply-to addresses
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getReplyTo(): array;
/**
* Gets the primary recipients (To)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getTo(): array;
/**
* Gets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getCc(): array;
/**
* Gets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getBcc(): array;
/**
* Gets the message ID this is replying to
*
* @since 2025.05.01
*
* @return string|null
*/
public function getInReplyTo(): ?string;
/**
* Gets the references (message IDs in thread)
*
* @since 2025.05.01
*
* @return array<int,string>
*/
public function getReferences(): array;
/**
* Gets the message subject
*
* @since 2025.05.01
*
* @return string
*/
public function getSubject(): string;
/**
* Gets the message snippet/preview
*
* @since 2025.05.01
*
* @return string|null
*/
public function getSnippet(): ?string;
/**
* Checks if the message has any body content
*
* @since 2025.05.01
*
* @return bool True if text or HTML body is set
*/
public function hasBody(): bool;
/**
* Gets the message body structure
*
* @since 2025.05.01
*
* @return MessagePartInterface|null The body structure or null if no body
*/
public function getBody(): ?MessagePartInterface;
/**
* Gets the plain text body content
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyText(): ?string;
/**
* Gets the HTML body content
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyHtml(): ?string;
/**
* Gets the attachments
*
* @since 2025.05.01
*
* @return array<int,AttachmentInterface>
*/
public function getAttachments(): array;
/**
* Gets message flags
*
* @since 2025.05.01
*
* @return array{read:bool,starred:bool,important:bool,answered:bool,forwarded:bool,draft:bool,deleted:bool,flagged:bool}
*/
public function getFlags(): array;
/**
* Gets a specific flag value
*
* @since 2025.05.01
*
* @param string $name Flag name (read, starred, important, answered, forwarded, draft, deleted, flagged)
*
* @return bool
*/
public function getFlag(string $name): bool;
}

455
shared/lib/Mail/Object/MessagePropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,455 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
/**
* Abstract Message Properties Mutable Class
*
* Provides common implementation for mutable message properties
*
* @since 2025.05.01
*/
abstract class MessagePropertiesMutableAbstract extends MessagePropertiesBaseAbstract implements MessagePropertiesMutableInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function setHeaders(array $value): static {
$this->data['headers'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setHeader(string $name, string|array $value): static {
$this->data['headers'][$name] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setUrid(?string $value): static {
$this->data['urid'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setCreated(DateTimeImmutable $value): static {
$this->data['created'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setModified(DateTimeImmutable $value): static {
$this->data['modified'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setDate(DateTimeImmutable $value): static {
$this->data['date'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReceived(?DateTimeImmutable $value): static {
$this->data['received'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSize(?int $value): static {
$this->data['size'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSender(?AddressInterface $value): static {
$this->data['sender'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setFrom(AddressInterface $value): static {
$this->data['from'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReplyTo(AddressInterface ...$value): static {
$this->data['replyTo'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setTo(AddressInterface ...$value): static {
$this->data['to'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setCc(AddressInterface ...$value): static {
$this->data['cc'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBcc(AddressInterface ...$value): static {
$this->data['bcc'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setInReplyTo(?string $value): static {
$this->data['inReplyTo'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReferences(string ...$value): static {
$this->data['references'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSubject(string $value): static {
$this->data['subject'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSnippet(?string $value): static {
$this->data['snippet'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBodyText(?string $value): static {
$this->data['bodyText'] = $value;
return $this;
}
/**
* Sets the plain text body charset
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBodyTextCharset(string $value): static {
$this->data['bodyTextCharset'] = $value;
return $this;
}
/**
* Sets the plain text body size
*
* @since 2025.05.01
*
* @param int $value
*
* @return static
*/
public function setBodyTextSize(int $value): static {
$this->data['bodyTextSize'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBodyHtml(?string $value): static {
$this->data['bodyHtml'] = $value;
return $this;
}
/**
* Sets the HTML body charset
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBodyHtmlCharset(string $value): static {
$this->data['bodyHtmlCharset'] = $value;
return $this;
}
/**
* Sets the HTML body size
*
* @since 2025.05.01
*
* @param int $value
*
* @return static
*/
public function setBodyHtmlSize(int $value): static {
$this->data['bodyHtmlSize'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setAttachments(AttachmentInterface ...$value): static {
$this->data['attachments'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function addAttachment(AttachmentInterface $value): static {
$this->data['attachments'][] = $value;
return $this;
}
/**
* Sets message flags
*
* @since 2025.05.01
*
* @param array $value
*
* @return static
*/
public function setFlags(array $value): static {
if (!isset($this->data['flags'])) {
$this->data['flags'] = [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
$this->data['flags'] = array_merge($this->data['flags'], $value);
return $this;
}
/**
* @inheritDoc
*/
public function setFlag(string $name, bool $value): static {
if (!isset($this->data['flags'])) {
$this->data['flags'] = [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
if (array_key_exists($name, $this->data['flags'])) {
$this->data['flags'][$name] = $value;
}
return $this;
}
/**
* Sets message labels
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return static
*/
public function setLabels(string ...$value): static {
$this->data['labels'] = $value;
return $this;
}
/**
* Adds a message label
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function addLabel(string $value): static {
$this->data['labels'][] = $value;
return $this;
}
/**
* Sets message tags
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return static
*/
public function setTags(string ...$value): static {
$this->data['tags'] = $value;
return $this;
}
/**
* Adds a message tag
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function addTag(string $value): static {
$this->data['tags'][] = $value;
return $this;
}
/**
* Sets message priority
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setPriority(string $value): static {
$this->data['priority'] = $value;
return $this;
}
/**
* Sets message sensitivity
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setSensitivity(string $value): static {
$this->data['sensitivity'] = $value;
return $this;
}
/**
* Sets encryption information
*
* @since 2025.05.01
*
* @param array $value
*
* @return static
*/
public function setEncryption(array $value): static {
if (!isset($this->data['encryption'])) {
$this->data['encryption'] = [
'method' => null,
'signed' => false,
'encrypted' => false,
];
}
$this->data['encryption'] = array_merge($this->data['encryption'], $value);
return $this;
}
/**
* Sets delivery receipt flag
*
* @since 2025.05.01
*
* @param bool $value
*
* @return static
*/
public function setDeliveryReceipt(bool $value): static {
$this->data['deliveryReceipt'] = $value;
return $this;
}
/**
* Sets read receipt flag
*
* @since 2025.05.01
*
* @param bool $value
*
* @return static
*/
public function setReadReceipt(bool $value): static {
$this->data['readReceipt'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
// Merge deserialized data into internal storage
foreach ($data as $key => $value) {
if (!in_array($key, ['collection', 'identifier', 'signature', 'created', 'modified'])) {
$this->data[$key] = $value;
}
}
return $this;
}
}

255
shared/lib/Mail/Object/MessagePropertiesMutableInterface.php Normal file
View File

@@ -0,0 +1,255 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Message Properties Mutable Interface
*
* @since 2025.05.01
*/
interface MessagePropertiesMutableInterface extends MessagePropertiesBaseInterface, NodePropertiesMutableInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* Sets custom headers
*
* @since 2025.05.01
*
* @param array<string,string|array<int,string>> $value Header name => value
*
* @return self
*/
public function setHeaders(array $value): static;
/**
* Sets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
* @param string|array<int,string> $value Header value(s)
*
* @return self
*/
public function setHeader(string $name, string|array $value): static;
/**
* Sets the universal resource identifier (URN)
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setUrid(?string $value): static;
/**
* Sets the message date
*
* @since 2025.05.01
*
* @param DateTimeImmutable $value
*
* @return self
*/
public function setDate(DateTimeImmutable $value): static;
/**
* Sets the received date
*
* @since 2025.05.01
*
* @param DateTimeImmutable|null $value
*
* @return self
*/
public function setReceived(?DateTimeImmutable $value): static;
/**
* Sets the message size in bytes
*
* @since 2025.05.01
*
* @param int|null $value
*
* @return self
*/
public function setSize(?int $value): static;
/**
* Sets the sender address (actual sender, may differ from From)
*
* @since 2025.05.01
*
* @param AddressInterface|null $value
*
* @return self
*/
public function setSender(?AddressInterface $value): static;
/**
* Sets the sender address
*
* @since 2025.05.01
*
* @param AddressInterface $value
*
* @return self
*/
public function setFrom(AddressInterface $value): static;
/**
* Sets the reply-to addresses
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setReplyTo(AddressInterface ...$value): static;
/**
* Sets the primary recipients (To)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setTo(AddressInterface ...$value): static;
/**
* Sets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setCc(AddressInterface ...$value): static;
/**
* Sets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setBcc(AddressInterface ...$value): static;
/**
* Sets the message ID this is replying to
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setInReplyTo(?string $value): static;
/**
* Sets the references (message IDs in thread)
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return self
*/
public function setReferences(string ...$value): static;
/**
* Sets the message subject
*
* @since 2025.05.01
*
* @param string $value
*
* @return self
*/
public function setSubject(string $value): static;
/**
* Sets the message snippet/preview
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setSnippet(?string $value): static;
/**
* Sets the plain text body content
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setBodyText(?string $value): static;
/**
* Sets the HTML body content
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setBodyHtml(?string $value): static;
/**
* Sets the attachments
*
* @since 2025.05.01
*
* @param AttachmentInterface ...$value
*
* @return self
*/
public function setAttachments(AttachmentInterface ...$value): static;
/**
* Adds an attachment
*
* @since 2025.05.01
*
* @param AttachmentInterface $value
*
* @return self
*/
public function addAttachment(AttachmentInterface $value): static;
/**
* Sets message tags
*
* @since 2025.05.01
*
* @param array{read: bool, starred: bool, important: bool, answered: bool, forwarded: bool, draft: bool, deleted: bool, flagged: bool} $value
*
* @return self
*/
public function setFlag(string $label, bool $value): static;
}

41
shared/lib/Mail/Provider/ProviderBaseInterface.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Mail\Service\ServiceBaseInterface;
use KTXF\Resource\Provider\ResourceProviderBaseInterface;
/**
* Mail Provider Base Interface
*
* Core interface for mail providers with context-aware service discovery.
*
* @since 2025.05.01
*/
interface ProviderBaseInterface extends ResourceProviderBaseInterface{
public const JSON_TYPE = 'mail.provider';
/**
* Finds a service that handles a specific email address
*
* Searches within the appropriate scope based on userId context.
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string $userId User identifier
* @param string $address Email address to find service for
*
* @return ServiceBaseInterface|null Service handling the address, or null
*/
public function serviceFindByAddress(string $tenantId, string $userId, string $address): ?ServiceBaseInterface;
}

52
shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php Normal file
View File

@@ -0,0 +1,52 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Resource\Provider\ResourceServiceLocationInterface;
/**
* Mail Provider Autodiscovery Interface
*
* Optional interface for mail 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
* protocol or provider type.
*
* Examples:
* - IMAP/SMTP providers: Mozilla Autoconfig, DNS SRV, well-known URIs
* - JMAP providers: Well-known JMAP endpoint discovery
* - Provider-specific: Gmail, Outlook, etc. with known configurations
*
* @since 2025.05.01
*/
interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {
/**
* Attempts to discover service configuration using provider-specific methods.
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string $userId User identifier
* @param string $identity Identity to discover configuration for (e.g., email address)
* @param string|null $location Optional hostname to test directly (bypasses DNS lookup)
* @param string|null $secret Optional password/token to validate discovered service
*
* @return ResourceServiceLocationInterface|null Discovered location or null if not found
*/
public function serviceDiscover(
string $tenantId,
string $userId,
string $identity,
?string $location = null,
?string $secret = null
): ResourceServiceLocationInterface|null;
}

35
shared/lib/Mail/Provider/ProviderServiceMutateInterface.php Normal file
View File

@@ -0,0 +1,35 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
/**
* Mail Provider Service Mutate Interface
*
* Optional interface for providers that support service CRUD operations.
*
* Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
*
* @since 2025.05.01
*
* @method ServiceMutableInterface serviceFresh() Construct a new blank mail service instance
* @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a mail service configuration
* @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a mail service configuration
* @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a mail service configuration
*/
interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface {
public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
// Methods inherited from ResourceProviderServiceMutateInterface
// Implementations should return/accept ServiceMutableInterface instances
}

77
shared/lib/Mail/Provider/ProviderServiceTestInterface.php Normal file
View File

@@ -0,0 +1,77 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Mail\Service\ServiceBaseInterface;
/**
* Mail 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)
*
* @since 2025.05.01
*/
interface ProviderServiceTestInterface extends ProviderBaseInterface {
/**
* 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.
*
* @since 2025.05.01
*
* @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
* @param array $options Provider-specific test options:
* - 'timeout' => int (seconds, default: 10)
* - 'verify_ssl' => bool (default: true)
* - 'test_send' => bool (attempt test send if capable, default: false)
* - 'test_receive' => bool (attempt mailbox access if capable, default: true)
*
* @return array Test results in the format:
* [
* 'success' => bool,
* '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 $service, array $options = []): array;
}

81
shared/lib/Mail/Queue/SendOptions.php Normal file
View File

@@ -0,0 +1,81 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Queue;
use JsonSerializable;
/**
* Mail Send Options
*
* Configuration options for message delivery behavior.
*
* @since 2025.05.01
*/
class SendOptions implements JsonSerializable {
/**
* @param bool $immediate Send immediately bypassing queue (for 2FA, etc.)
* @param int $priority Queue priority (-100 to 100, higher = sooner)
* @param int $retryCount Maximum retry attempts on failure
* @param int|null $delaySeconds Delay before first send attempt
*/
public function __construct(
public readonly bool $immediate = false,
public readonly int $priority = 0,
public readonly int $retryCount = 3,
public readonly ?int $delaySeconds = null,
) {}
/**
* Creates options for immediate delivery (bypasses queue)
*
* @since 2025.05.01
*
* @return self
*/
public static function immediate(): self {
return new self(immediate: true);
}
/**
* Creates options for high-priority queued delivery
*
* @since 2025.05.01
*
* @return self
*/
public static function highPriority(): self {
return new self(priority: 50);
}
/**
* Creates options for low-priority queued delivery (bulk mail)
*
* @since 2025.05.01
*
* @return self
*/
public static function lowPriority(): self {
return new self(priority: -50);
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return [
'immediate' => $this->immediate,
'priority' => $this->priority,
'retryCount' => $this->retryCount,
'delaySeconds' => $this->delaySeconds,
];
}
}

237
shared/lib/Mail/Service/ServiceBaseInterface.php Normal file
View File

@@ -0,0 +1,237 @@
<?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\Collection\CollectionBaseInterface;
use KTXF\Mail\Object\AddressInterface;
use KTXF\Resource\Delta\Delta;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;
/**
* Mail 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.
*
* @since 2025.05.01
*/
interface ServiceBaseInterface extends ResourceServiceBaseInterface {
// Collection capabilities
public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
// Collection Filter
public const CAPABILITY_COLLECTION_FILTER_LABEL = 'label';
public const CAPABILITY_COLLECTION_FILTER_ROLE = 'role';
// Collection Sort
public const CAPABILITY_COLLECTION_SORT_LABEL = 'label';
public const CAPABILITY_COLLECTION_SORT_RANK = 'rank';
// Entity capabilities
public const CAPABILITY_ENTITY_LIST = 'EntityList';
public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
// Filter capabilities
public const CAPABILITY_ENTITY_FILTER_ALL = '*';
public const CAPABILITY_ENTITY_FILTER_FROM = 'from';
public const CAPABILITY_ENTITY_FILTER_TO = 'to';
public const CAPABILITY_ENTITY_FILTER_CC = 'cc';
public const CAPABILITY_ENTITY_FILTER_BCC = 'bcc';
public const CAPABILITY_ENTITY_FILTER_SUBJECT = 'subject';
public const CAPABILITY_ENTITY_FILTER_BODY = 'body';
public const CAPABILITY_ENTITY_FILTER_DATE_BEFORE = 'before';
public const CAPABILITY_ENTITY_FILTER_DATE_AFTER = 'after';
public const CAPABILITY_ENTITY_FILTER_SIZE_MIN = 'min';
public const CAPABILITY_ENTITY_FILTER_SIZE_MAX = 'max';
// Sort capabilities
public const CAPABILITY_ENTITY_SORT_FROM = 'from';
public const CAPABILITY_ENTITY_SORT_TO = 'to';
public const CAPABILITY_ENTITY_SORT_SUBJECT = 'subject';
public const CAPABILITY_ENTITY_SORT_DATE_RECEIVED = 'received';
public const CAPABILITY_ENTITY_SORT_DATE_SENT = 'sent';
public const CAPABILITY_ENTITY_SORT_SIZE = 'size';
public const JSON_TYPE = 'mail.service';
public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';
/**
* Gets the primary mailing address for this service
*
* @since 2025.05.01
*
* @return AddressInterface
*/
public function getPrimaryAddress(): AddressInterface;
/**
* Gets the secondary mailing addresses (aliases) for this service
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
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 hasAddress(string $address): bool;
/**
* Lists all collections in this service
*
* @since 2025.05.01
*
* @param IFilter|null $filter Optional filter criteria
* @param ISort|null $sort Optional sort order
*
* @return array<string|int,CollectionBaseInterface> Collections indexed by ID
*/
public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array;
/**
* Creates a filter builder for collections
*
* @since 2025.05.01
*
* @return IFilter
*/
public function collectionListFilter(): IFilter;
/**
* Creates a sort builder for collections
*
* @since 2025.05.01
*
* @return ISort
*/
public function collectionListSort(): ISort;
/**
* Checks if collections exist
*
* @since 2025.05.01
*
* @param string|int ...$identifiers Collection IDs to check
*
* @return array<string|int,bool> Map of ID => exists
*/
public function collectionExtant(string|int $location, string|int ...$identifiers): array;
/**
* Fetches a single collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
*
* @return CollectionBaseInterface|null Collection or null if not found
*/
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface;
/**
* Lists messages in a collection
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @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
*
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
/**
* Creates a filter builder for messages
*
* @since 2025.05.01
*
* @return IFilter
*/
public function entityListFilter(): IFilter;
/**
* Creates a sort builder for messages
*
* @since 2025.05.01
*
* @return ISort
*/
public function entityListSort(): ISort;
/**
* Creates a range builder for messages
*
* @since 2025.05.01
*
* @param RangeType $type Range type (offset, cursor, etc.)
*
* @return IRange
*/
public function entityListRange(RangeType $type): IRange;
/**
* Gets incremental changes since last sync
*
* @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'
*
* @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
*/
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta;
/**
* Checks if messages exist
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to check
*
* @return array<string|int,bool> Map of ID => exists
*/
public function entityExtant(string|int $collection, string|int ...$identifiers): array;
/**
* Fetches one or more entities
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to fetch
*
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function entityFetch(string|int $collection, string|int ...$identifiers): array;
}

89
shared/lib/Mail/Service/ServiceCollectionMutableInterface.php Normal file
View File

@@ -0,0 +1,89 @@
<?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\Collection\CollectionBaseInterface;
use KTXF\Mail\Collection\CollectionMutableInterface;
/**
* Mail Service Collection Mutable Interface
*
* Optional interface for services that support collection CRUD operations.
* Provides mailbox/folder creation, modification, deletion, and moving.
*
* @since 2025.05.01
*/
interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
/**
* Creates a fresh collection instance for configuration
*
* @since 2025.05.01
*
* @return CollectionMutableInterface Fresh collection object
*/
public function collectionFresh(): CollectionMutableInterface;
/**
* Creates a new collection
*
* @since 2025.05.01
*
* @param string|int|null $location Parent collection ID (null for root)
* @param CollectionMutableInterface $collection Collection to create
* @param array $options Protocol-specific options
*
* @return CollectionBaseInterface Created collection with assigned ID
*/
public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface;
/**
* Modifies an existing collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param CollectionMutableInterface $collection Updated collection data
*
* @return CollectionBaseInterface Modified collection
*/
public function collectionModify(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface;
/**
* Destroys a collection
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param bool $force Force destruction even if not empty
* @param bool $recursive Recursively destroy contents
*
* @return bool True if destroyed
*/
public function collectionDestroy(string|int $identifier, bool $force = false, bool $recursive = false): bool;
/**
* Moves a collection to a new parent
*
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param string|int|null $targetLocation New parent ID (null for root)
*
* @return CollectionBaseInterface Moved collection
*/
public function collectionMove(string|int $identifier, string|int|null $targetLocation): CollectionBaseInterface;
}

26
shared/lib/Mail/Service/ServiceConfigurableInterface.php Normal file
View File

@@ -0,0 +1,26 @@
<?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\Resource\Provider\ResourceServiceConfigureInterface;
/**
* Mail Service Mutable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ServiceConfigurableInterface extends ServiceMutableInterface, ResourceServiceConfigureInterface {
public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
}

103
shared/lib/Mail/Service/ServiceEntityMutableInterface.php Normal file
View File

@@ -0,0 +1,103 @@
<?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\EntityBaseInterface;
use KTXF\Mail\Entity\EntityMutableInterface;
/**
* Mail Service Entity Mutable Interface
*
* Optional interface for services that support entity CRUD operations.
* Provides entity creation, modification, deletion, copying, moving, and flag management.
*
* @since 2025.05.01
*/
interface ServiceEntityMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
/**
* Creates a fresh entity instance for composition
*
* @since 2025.05.01
*
* @return EntityMutableInterface Fresh entity object
*/
public function entityFresh(): EntityMutableInterface;
/**
* Creates/imports an entity into a collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param EntityMutableInterface $entity Entity data
* @param array $options additional options
*
* @return EntityBaseInterface Created entity
*/
public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface;
/**
* Modifies an existing entity
*
* @since 2025.05.01
*
* @param string|int $collection Collection identifier
* @param string|int $identifier Entity identifier
* @param EntityMutableInterface $entity Entity data
*
* @return EntityBaseInterface Modified entity
*/
public function entityModify(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface;
/**
* Destroys one or more entities
*
* @since 2025.05.01
*
* @param string|int $collection Collection identifier
* @param string|int ...$identifiers Entity identifiers to destroy
*
* @return array<string|int,bool> List of destroyed entity identifiers
*/
public function entityDestroy(string|int $collection, string|int ...$identifiers): array;
/**
* Copies entities to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection identifier
* @param string|int $targetCollection Target collection identifier
* @param string|int ...$identifiers Entity identifiers to copy
*
* @return array<string|int,string|int> Map of source identifier => new identifier
*/
public function entityCopy(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
/**
* Moves entities to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection identifier
* @param string|int $targetCollection Target collection identifier
* @param string|int ...$identifiers Entity identifiers to move
*
* @return array<string|int,bool> List of moved entity identifiers
*/
public function entityMove(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
}

48
shared/lib/Mail/Service/ServiceEntityTransmitInterface.php Normal file
View File

@@ -0,0 +1,48 @@
<?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\EntityMutableInterface;
use KTXF\Mail\Exception\SendException;
/**
* Mail Service Transmit Interface
*
* Interface for mail services capable of transmitting outbound entities.
*
* @since 2025.05.01
*/
interface ServiceEntityTransmitInterface extends ServiceBaseInterface {
public const CAPABILITY_ENTITY_TRANSMIT = 'EntityTransmit';
/**
* Creates a fresh entity instance for composition
*
* @since 2025.05.01
*
* @return EntityMutableInterface Fresh entity object
*/
public function entityFresh(): EntityMutableInterface;
/**
* Transmits an outbound entity
*
* @since 2025.05.01
*
* @param EntityMutableInterface $entity Entity to transmit
*
* @return string Entity identifier assigned by the transport
*
* @throws SendException On delivery failure
*/
public function entitySend(EntityMutableInterface $entity): string;
}

46
shared/lib/Mail/Service/ServiceMutableInterface.php Normal file
View File

@@ -0,0 +1,46 @@
<?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\Object\AddressInterface;
/**
* Mail Service Mutable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ServiceMutableInterface extends ServiceBaseInterface {
/**
* Sets the primary mailing address for this service
*
* @since 2025.05.01
*
* @param AddressInterface $value Primary email address
*
* @return static
*/
public function setPrimaryAddress(AddressInterface $value): static;
/**
* Sets the secondary mailing addresses (aliases) for this service
*
* @since 2025.05.01
*
* @param array<int,AddressInterface> $value Array of secondary addresses
*
* @return static
*/
public function setSecondaryAddresses(array $value): static;
}