chore(deps): update dependency phpunit/phpunit to v12.5.35

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

composer.lock

@@ -9,20 +9,20 @@
     "packages-dev": [
         {
             "name": "myclabs/deep-copy",
-            "version": "1.13.4",
+            "version": "1.14.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/myclabs/DeepCopy.git",
-                "reference": "07d290f0c47959fd5eed98c95ee5602db07e0b6a"
+                "reference": "8680aa248f8e07bc8fb43f56f0f5fc77a0c96aae"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/07d290f0c47959fd5eed98c95ee5602db07e0b6a",
-                "reference": "07d290f0c47959fd5eed98c95ee5602db07e0b6a",
+                "url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/8680aa248f8e07bc8fb43f56f0f5fc77a0c96aae",
+                "reference": "8680aa248f8e07bc8fb43f56f0f5fc77a0c96aae",
                 "shasum": ""
             },
             "require": {
-                "php": "^7.1 || ^8.0"
+                "php": "^8.0"
             },
             "conflict": {
                 "doctrine/collections": "<1.6.8",
@@ -57,15 +57,15 @@
             ],
             "support": {
                 "issues": "https://github.com/myclabs/DeepCopy/issues",
-                "source": "https://github.com/myclabs/DeepCopy/tree/1.13.4"
+                "source": "https://github.com/myclabs/DeepCopy/tree/1.14.0"
             },
             "funding": [
                 {
-                    "url": "https://tidelift.com/funding/github/packagist/myclabs/deep-copy",
-                    "type": "tidelift"
+                    "url": "https://github.com/mnapoli",
+                    "type": "github"
                 }
             ],
-            "time": "2025-08-01T08:46:24+00:00"
+            "time": "2026-08-11T10:17:44+00:00"
         },
         {
             "name": "nikic/php-parser",
@@ -332,23 +332,23 @@
         },
         {
             "name": "phpunit/php-file-iterator",
-            "version": "6.0.1",
+            "version": "6.0.2",
             "source": {
                 "type": "git",
                 "url": "https://github.com/sebastianbergmann/php-file-iterator.git",
-                "reference": "3d1cd096ef6bea4bf2762ba586e35dbd317cbfd5"
+                "reference": "a248d1640ab059b075f53a2ef0f9856e864e06b5"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/3d1cd096ef6bea4bf2762ba586e35dbd317cbfd5",
-                "reference": "3d1cd096ef6bea4bf2762ba586e35dbd317cbfd5",
+                "url": "https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/a248d1640ab059b075f53a2ef0f9856e864e06b5",
+                "reference": "a248d1640ab059b075f53a2ef0f9856e864e06b5",
                 "shasum": ""
             },
             "require": {
                 "php": ">=8.3"
             },
             "require-dev": {
-                "phpunit/phpunit": "^12.0"
+                "phpunit/phpunit": "^12.5.33"
             },
             "type": "library",
             "extra": {
@@ -381,7 +381,7 @@
             "support": {
                 "issues": "https://github.com/sebastianbergmann/php-file-iterator/issues",
                 "security": "https://github.com/sebastianbergmann/php-file-iterator/security/policy",
-                "source": "https://github.com/sebastianbergmann/php-file-iterator/tree/6.0.1"
+                "source": "https://github.com/sebastianbergmann/php-file-iterator/tree/6.0.2"
             },
             "funding": [
                 {
@@ -401,7 +401,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-02-02T14:04:18+00:00"
+            "time": "2026-08-25T14:40:53+00:00"
         },
         {
             "name": "phpunit/php-invoker",
@@ -589,16 +589,16 @@
         },
         {
             "name": "phpunit/phpunit",
-            "version": "12.5.32",
+            "version": "12.5.35",
             "source": {
                 "type": "git",
                 "url": "https://github.com/sebastianbergmann/phpunit.git",
-                "reference": "c02591dd7840ed124a98d7770753329ad28e9f8f"
+                "reference": "345ac22e42cb14cdc7aa8428655d8bb8c82a4aab"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/c02591dd7840ed124a98d7770753329ad28e9f8f",
-                "reference": "c02591dd7840ed124a98d7770753329ad28e9f8f",
+                "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/345ac22e42cb14cdc7aa8428655d8bb8c82a4aab",
+                "reference": "345ac22e42cb14cdc7aa8428655d8bb8c82a4aab",
                 "shasum": ""
             },
             "require": {
@@ -608,18 +608,18 @@
                 "ext-libxml": "*",
                 "ext-mbstring": "*",
                 "ext-xmlwriter": "*",
-                "myclabs/deep-copy": "^1.13.4",
+                "myclabs/deep-copy": "^1.14.0",
                 "phar-io/manifest": "^2.0.4",
                 "phar-io/version": "^3.2.1",
                 "php": ">=8.3",
                 "phpunit/php-code-coverage": "^12.5.7",
-                "phpunit/php-file-iterator": "^6.0.1",
+                "phpunit/php-file-iterator": "^6.0.2",
                 "phpunit/php-invoker": "^6.0.0",
                 "phpunit/php-text-template": "^5.0.0",
                 "phpunit/php-timer": "^8.0.0",
                 "sebastian/cli-parser": "^4.2.1",
                 "sebastian/comparator": "^7.1.8",
-                "sebastian/diff": "^7.0.0",
+                "sebastian/diff": "^7.0.1",
                 "sebastian/environment": "^8.1.2",
                 "sebastian/exporter": "^7.0.3",
                 "sebastian/global-state": "^8.0.3",
@@ -667,7 +667,7 @@
             "support": {
                 "issues": "https://github.com/sebastianbergmann/phpunit/issues",
                 "security": "https://github.com/sebastianbergmann/phpunit/security/policy",
-                "source": "https://github.com/sebastianbergmann/phpunit/tree/12.5.32"
+                "source": "https://github.com/sebastianbergmann/phpunit/tree/12.5.35"
             },
             "funding": [
                 {
@@ -675,7 +675,7 @@
                     "type": "other"
                 }
             ],
-            "time": "2026-07-25T06:54:13+00:00"
+            "time": "2026-09-09T04:48:50+00:00"
         },
         {
             "name": "sebastian/cli-parser",
@@ -898,24 +898,24 @@
         },
         {
             "name": "sebastian/diff",
-            "version": "7.0.0",
+            "version": "7.0.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/sebastianbergmann/diff.git",
-                "reference": "7ab1ea946c012266ca32390913653d844ecd085f"
+                "reference": "cd4cabe39f8a4e8ee6818ba99f10a05561ea4ad6"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/sebastianbergmann/diff/zipball/7ab1ea946c012266ca32390913653d844ecd085f",
-                "reference": "7ab1ea946c012266ca32390913653d844ecd085f",
+                "url": "https://api.github.com/repos/sebastianbergmann/diff/zipball/cd4cabe39f8a4e8ee6818ba99f10a05561ea4ad6",
+                "reference": "cd4cabe39f8a4e8ee6818ba99f10a05561ea4ad6",
                 "shasum": ""
             },
             "require": {
                 "php": ">=8.3"
             },
             "require-dev": {
-                "phpunit/phpunit": "^12.0",
-                "symfony/process": "^7.2"
+                "phpunit/phpunit": "^12.5.33",
+                "symfony/process": "^7.4.17"
             },
             "type": "library",
             "extra": {
@@ -953,15 +953,27 @@
             "support": {
                 "issues": "https://github.com/sebastianbergmann/diff/issues",
                 "security": "https://github.com/sebastianbergmann/diff/security/policy",
-                "source": "https://github.com/sebastianbergmann/diff/tree/7.0.0"
+                "source": "https://github.com/sebastianbergmann/diff/tree/7.0.1"
             },
             "funding": [
                 {
                     "url": "https://github.com/sebastianbergmann",
                     "type": "github"
+                },
+                {
+                    "url": "https://liberapay.com/sebastianbergmann",
+                    "type": "liberapay"
+                },
+                {
+                    "url": "https://thanks.dev/u/gh/sebastianbergmann",
+                    "type": "thanks_dev"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/sebastian/diff",
+                    "type": "tidelift"
                 }
             ],
-            "time": "2025-02-07T04:55:46+00:00"
+            "time": "2026-08-25T15:35:54+00:00"
         },
         {
             "name": "sebastian/environment",

lib/Controllers/DefaultController.php

@@ -23,8 +23,8 @@ use KTXF\Resource\Identifier\EntityIdentifier;
 use KTXF\Resource\Identifier\ResourceIdentifier;
 use KTXF\Resource\Identifier\ResourceIdentifiers;
 use KTXF\Resource\Identifier\ServiceIdentifier;
-use KTXF\Mail\Provider\ProviderBaseInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
+use KTXF\Resource\SystemIdentity;
 use KTXF\Routing\Attributes\AuthenticatedRoute;
 use KTXM\MailManager\Manager;
 use Psr\Log\LoggerInterface;
@@ -86,7 +86,7 @@ class DefaultController extends ControllerAbstract {
         // acting-user override: only the reserved system context is permitted,
         // gated on the system mail management permission
         if ($user !== null && $user !== $userId) {
-            if ($user !== ProviderBaseInterface::USER_SYSTEM || !$this->identityContext->hasPermission('mail_manager.system')) {
+            if ($user !== SystemIdentity::USER || !$this->identityContext->hasPermission('mail_manager.system')) {
                 return new JsonResponse([
                     'version' => $version,
                     'transaction' => $transaction,
@@ -172,14 +172,15 @@ class DefaultController extends ControllerAbstract {
             'entity.fetch' => $this->entityFetch($tenantId, $userId, $data),
             'entity.extant' => $this->entityExtant($tenantId, $userId, $data),
             'entity.delta' => $this->entityDelta($tenantId, $userId, $data),
-            'entity.create' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
-            'entity.update' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
+            'entity.create' => $this->entityCreate($tenantId, $userId, $data),
+            'entity.update' => $this->entityUpdate($tenantId, $userId, $data),
             'entity.delete' => $this->entityDelete($tenantId, $userId, $data),
             'entity.patch' => $this->entityPatch($tenantId, $userId, $data),
             'entity.move' => $this->entityMove($tenantId, $userId, $data),
             'entity.copy' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
             'entity.submit' => $this->entitySubmit($tenantId, $userId, $data),
             'entity.download' => $this->entityDownload($tenantId, $userId, $data),
+            'entity.preview' => $this->entityPreview($tenantId, $userId, $data),
             'entity.blobs' => $this->entityBlobs($tenantId, $userId, $data),
             
             default => throw new InvalidArgumentException(self::ERR_INVALID_OPERATION . $operation)
@@ -751,6 +752,55 @@ class DefaultController extends ControllerAbstract {
         return $this->manager->entityDelta($tenantId, $userId, $targets);
     }
 
+    private function entityCreate(string $tenantId, string $userId, array $data = []): mixed {
+        if (!isset($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
+        }
+        if (!is_string($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_TARGET);
+        }
+        if (!isset($data['properties'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
+        }
+        if (!is_array($data['properties'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
+        }
+
+        $target = ResourceIdentifier::fromString($data['target']);
+        if (!$target instanceof CollectionIdentifier) {
+            throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection');
+        }
+
+        $options = $data['options'] ?? [];
+        if (!is_array($options)) {
+            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
+        }
+
+        return $this->manager->entityCreate($tenantId, $userId, $target, $data['properties'], $options);
+    }
+
+    private function entityUpdate(string $tenantId, string $userId, array $data = []): mixed {
+        if (!isset($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
+        }
+        if (!is_string($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_TARGET);
+        }
+        if (!isset($data['properties'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
+        }
+        if (!is_array($data['properties'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
+        }
+
+        $target = ResourceIdentifier::fromString($data['target']);
+        if (!$target instanceof EntityIdentifier) {
+            throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection:entity');
+        }
+
+        return $this->manager->entityModify($tenantId, $userId, $target, $data['properties']);
+    }
+
     private function entityPatch(string $tenantId, string $userId, array $data): mixed {
         if (!isset($data['targets'])) {
             throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
@@ -919,4 +969,36 @@ class DefaultController extends ControllerAbstract {
         return $results;
     }
 
+    private function entityPreview(string $tenantId, string $userId, array $data): Response {
+        if (!isset($data['target']) || !is_string($data['target'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
+        }
+        if (!isset($data['part']) || !is_array($data['part'])) {
+            throw new InvalidArgumentException('Attachment preview requires a part');
+        }
+
+        $target = ResourceIdentifier::fromString($data['target']);
+        if (!$target instanceof EntityIdentifier) {
+            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
+        }
+        $preview = $this->manager->entityPreview(
+            $tenantId,
+            $userId,
+            $target,
+            $data['part'],
+            isset($data['variant']) && is_string($data['variant']) ? $data['variant'] : 'inline',
+        );
+        if ($preview === null) {
+            return new Response('', Response::HTTP_NO_CONTENT);
+        }
+
+        return new StreamedResponse($preview->resource->stream(), Response::HTTP_OK, [
+            'Content-Type' => $preview->resource->mimeType(),
+            'Content-Length' => (string) $preview->size,
+            'ETag' => '"' . trim($preview->etag, '"') . '"',
+            'Cache-Control' => 'private, max-age=3600',
+            'X-Content-Type-Options' => 'nosniff',
+        ]);
+    }
+
 }

lib/Daemon/MailDaemon.php

@@ -1,237 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXM\MailManager\Daemon;
-
-use KTXM\MailManager\Manager;
-use Psr\Log\LoggerInterface;
-
-/**
- * Mail Queue Daemon
- * 
- * Long-running worker process for processing queued mail messages.
- * Supports graceful shutdown via signals and configurable batch processing.
- * 
- * @since 2025.05.01
- */
-class MailDaemon {
-
-    private bool $running = false;
-    private bool $shutdown = false;
-    private bool $reload = false;
-
-    /**
-     * @param Manager $manager Mail manager
-     * @param LoggerInterface $logger Logger
-     * @param int $pollInterval Seconds between queue polls when idle
-     * @param int $batchSize Messages to process per batch
-     * @param int|null $maxMemory Maximum memory usage in bytes before restart
-     * @param array<string>|null $tenants Specific tenants to process (null = all)
-     */
-    public function __construct(
-        private Manager $manager,
-        private LoggerInterface $logger,
-        private int $pollInterval = 5,
-        private int $batchSize = 50,
-        private ?int $maxMemory = null,
-        private ?array $tenants = null,
-    ) {
-        // Set default max memory to 128MB
-        $this->maxMemory = $this->maxMemory ?? (128 * 1024 * 1024);
-    }
-
-    /**
-     * Run the daemon main loop
-     * 
-     * @since 2025.05.01
-     */
-    public function run(): void {
-        $this->running = true;
-        $this->shutdown = false;
-        
-        $this->setupSignalHandlers();
-        
-        $this->logger->info('Mail daemon starting', [
-            'pollInterval' => $this->pollInterval,
-            'batchSize' => $this->batchSize,
-            'maxMemory' => $this->formatBytes($this->maxMemory),
-            'tenants' => $this->tenants ?? 'all',
-        ]);
-        
-        $consecutiveEmpty = 0;
-        
-        while (!$this->shutdown) {
-            // Handle reload signal
-            if ($this->reload) {
-                $this->handleReload();
-                $this->reload = false;
-            }
-            
-            // Check memory usage
-            if ($this->isMemoryExceeded()) {
-                $this->logger->warning('Memory limit exceeded, shutting down for restart', [
-                    'current' => $this->formatBytes(memory_get_usage(true)),
-                    'limit' => $this->formatBytes($this->maxMemory),
-                ]);
-                break;
-            }
-            
-            // Process queues
-            $processed = $this->processTenants();
-            
-            if ($processed === 0) {
-                $consecutiveEmpty++;
-                // Exponential backoff up to poll interval
-                $sleepTime = min($consecutiveEmpty, $this->pollInterval);
-                $this->sleep($sleepTime);
-            } else {
-                $consecutiveEmpty = 0;
-            }
-            
-            // Dispatch pending signals
-            pcntl_signal_dispatch();
-        }
-        
-        $this->logger->info('Mail daemon stopped');
-        $this->running = false;
-    }
-
-    /**
-     * Request graceful shutdown
-     * 
-     * @since 2025.05.01
-     */
-    public function stop(): void {
-        $this->shutdown = true;
-    }
-
-    /**
-     * Check if daemon is running
-     * 
-     * @since 2025.05.01
-     * 
-     * @return bool
-     */
-    public function isRunning(): bool {
-        return $this->running;
-    }
-
-    /**
-     * Process all tenants and return total messages processed
-     */
-    private function processTenants(): int {
-        $totalProcessed = 0;
-        $tenants = $this->tenants ?? $this->discoverTenants();
-        
-        foreach ($tenants as $tenantId) {
-            if ($this->shutdown) {
-                break;
-            }
-            
-            $result = $this->manager->queueProcess($tenantId, $this->batchSize);
-            $totalProcessed += $result['processed'] + $result['failed'];
-            
-            if ($result['processed'] > 0 || $result['failed'] > 0) {
-                $this->logger->debug('Processed tenant queue', [
-                    'tenant' => $tenantId,
-                    'processed' => $result['processed'],
-                    'failed' => $result['failed'],
-                ]);
-            }
-        }
-        
-        return $totalProcessed;
-    }
-
-    /**
-     * Discover all tenants with mail queues
-     * 
-     * @return array<string>
-     */
-    private function discoverTenants(): array {
-        // This would need to be implemented based on your tenant discovery mechanism
-        // For now, return empty array - specific tenants should be configured
-        return [];
-    }
-
-    /**
-     * Setup signal handlers for graceful shutdown
-     */
-    private function setupSignalHandlers(): void {
-        if (!function_exists('pcntl_signal')) {
-            $this->logger->warning('PCNTL extension not available, signal handling disabled');
-            return;
-        }
-        
-        pcntl_signal(SIGTERM, function() {
-            $this->logger->info('Received SIGTERM, initiating graceful shutdown');
-            $this->shutdown = true;
-        });
-        
-        pcntl_signal(SIGINT, function() {
-            $this->logger->info('Received SIGINT, initiating graceful shutdown');
-            $this->shutdown = true;
-        });
-        
-        pcntl_signal(SIGHUP, function() {
-            $this->logger->info('Received SIGHUP, will reload configuration');
-            $this->reload = true;
-        });
-    }
-
-    /**
-     * Handle configuration reload
-     */
-    private function handleReload(): void {
-        $this->logger->info('Reloading configuration');
-        // Configuration reload logic would go here
-    }
-
-    /**
-     * Check if memory limit has been exceeded
-     */
-    private function isMemoryExceeded(): bool {
-        if ($this->maxMemory === null) {
-            return false;
-        }
-        
-        return memory_get_usage(true) > $this->maxMemory;
-    }
-
-    /**
-     * Sleep with signal dispatch
-     */
-    private function sleep(int $seconds): void {
-        for ($i = 0; $i < $seconds; $i++) {
-            if ($this->shutdown) {
-                return;
-            }
-            sleep(1);
-            pcntl_signal_dispatch();
-        }
-    }
-
-    /**
-     * Format bytes to human readable string
-     */
-    private function formatBytes(?int $bytes): string {
-        if ($bytes === null) {
-            return 'unlimited';
-        }
-        
-        $units = ['B', 'KB', 'MB', 'GB'];
-        $i = 0;
-        while ($bytes >= 1024 && $i < count($units) - 1) {
-            $bytes /= 1024;
-            $i++;
-        }
-        return round($bytes, 2) . ' ' . $units[$i];
-    }
-
-}

lib/Daemon/MailQueueCli.php

@@ -1,246 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXM\MailManager\Daemon;
-
-use KTXM\MailManager\Queue\JobStatus;
-use KTXM\MailManager\Queue\MailQueue;
-use Psr\Log\LoggerInterface;
-
-/**
- * Mail Queue CLI
- * 
- * Command-line interface for mail queue management operations.
- * 
- * Usage:
- *   php mail-queue.php list <tenant> [--status=pending]
- *   php mail-queue.php retry <jobId>
- *   php mail-queue.php retry-all <tenant> --status=failed
- *   php mail-queue.php purge <tenant> --status=complete --older-than=7d
- *   php mail-queue.php stats <tenant>
- * 
- * @since 2025.05.01
- */
-class MailQueueCli {
-
-    public function __construct(
-        private MailQueue $queue,
-        private LoggerInterface $logger,
-    ) {}
-
-    /**
-     * Run CLI command
-     * 
-     * @param array<string> $args Command line arguments
-     * 
-     * @return int Exit code
-     */
-    public function run(array $args): int {
-        $command = $args[1] ?? 'help';
-        
-        return match($command) {
-            'list' => $this->commandList($args),
-            'retry' => $this->commandRetry($args),
-            'retry-all' => $this->commandRetryAll($args),
-            'purge' => $this->commandPurge($args),
-            'stats' => $this->commandStats($args),
-            'help', '--help', '-h' => $this->commandHelp(),
-            default => $this->commandHelp(),
-        };
-    }
-
-    /**
-     * List jobs in queue
-     */
-    private function commandList(array $args): int {
-        $tenantId = $args[2] ?? null;
-        if ($tenantId === null) {
-            echo "Error: tenant ID required\n";
-            return 1;
-        }
-        
-        $status = $this->parseOption($args, 'status');
-        $statusEnum = $status !== null ? JobStatus::tryFrom($status) : null;
-        $limit = (int)($this->parseOption($args, 'limit') ?? 100);
-        
-        $jobs = $this->queue->listJobs($tenantId, $statusEnum, $limit);
-        
-        if (empty($jobs)) {
-            echo "No jobs found\n";
-            return 0;
-        }
-        
-        echo sprintf("%-36s %-12s %-8s %-20s %s\n", 
-            'JOB ID', 'STATUS', 'ATTEMPTS', 'CREATED', 'SUBJECT');
-        echo str_repeat('-', 100) . "\n";
-        
-        foreach ($jobs as $job) {
-            $subject = substr($job->message->getSubject(), 0, 30);
-            echo sprintf("%-36s %-12s %-8d %-20s %s\n",
-                $job->id,
-                $job->status->value,
-                $job->attempts,
-                $job->created?->format('Y-m-d H:i:s') ?? '-',
-                $subject
-            );
-        }
-        
-        return 0;
-    }
-
-    /**
-     * Retry a specific job
-     */
-    private function commandRetry(array $args): int {
-        $jobId = $args[2] ?? null;
-        if ($jobId === null) {
-            echo "Error: job ID required\n";
-            return 1;
-        }
-        
-        if ($this->queue->retry($jobId)) {
-            echo "Job $jobId queued for retry\n";
-            return 0;
-        }
-        
-        echo "Failed to retry job $jobId (not found or not failed)\n";
-        return 1;
-    }
-
-    /**
-     * Retry all failed jobs for a tenant
-     */
-    private function commandRetryAll(array $args): int {
-        $tenantId = $args[2] ?? null;
-        if ($tenantId === null) {
-            echo "Error: tenant ID required\n";
-            return 1;
-        }
-        
-        $jobs = $this->queue->listJobs($tenantId, JobStatus::Failed);
-        $retried = 0;
-        
-        foreach ($jobs as $job) {
-            if ($this->queue->retry($job->id)) {
-                $retried++;
-            }
-        }
-        
-        echo "Retried $retried jobs\n";
-        return 0;
-    }
-
-    /**
-     * Purge old jobs
-     */
-    private function commandPurge(array $args): int {
-        $tenantId = $args[2] ?? null;
-        if ($tenantId === null) {
-            echo "Error: tenant ID required\n";
-            return 1;
-        }
-        
-        $status = $this->parseOption($args, 'status') ?? 'complete';
-        $statusEnum = JobStatus::tryFrom($status);
-        if ($statusEnum === null) {
-            echo "Error: invalid status '$status'\n";
-            return 1;
-        }
-        
-        $olderThan = $this->parseOption($args, 'older-than') ?? '7d';
-        $seconds = $this->parseDuration($olderThan);
-        
-        $purged = $this->queue->purge($tenantId, $statusEnum, $seconds);
-        echo "Purged $purged jobs\n";
-        
-        return 0;
-    }
-
-    /**
-     * Show queue statistics
-     */
-    private function commandStats(array $args): int {
-        $tenantId = $args[2] ?? null;
-        if ($tenantId === null) {
-            echo "Error: tenant ID required\n";
-            return 1;
-        }
-        
-        $stats = $this->queue->stats($tenantId);
-        
-        echo "Queue Statistics for $tenantId:\n";
-        echo "  Pending:    {$stats['pending']}\n";
-        echo "  Processing: {$stats['processing']}\n";
-        echo "  Complete:   {$stats['complete']}\n";
-        echo "  Failed:     {$stats['failed']}\n";
-        
-        return 0;
-    }
-
-    /**
-     * Show help message
-     */
-    private function commandHelp(): int {
-        echo <<<HELP
-Mail Queue CLI
-
-Usage:
-  mail-queue <command> [options]
-
-Commands:
-  list <tenant>              List jobs in queue
-    --status=<status>        Filter by status (pending, processing, complete, failed)
-    --limit=<n>              Maximum jobs to show (default: 100)
-
-  retry <jobId>              Retry a specific failed job
-
-  retry-all <tenant>         Retry all failed jobs for a tenant
-
-  purge <tenant>             Purge old jobs
-    --status=<status>        Status to purge (default: complete)
-    --older-than=<duration>  Age threshold (default: 7d, e.g., 1h, 30d)
-
-  stats <tenant>             Show queue statistics
-
-  help                       Show this help message
-
-HELP;
-        return 0;
-    }
-
-    /**
-     * Parse a command line option
-     */
-    private function parseOption(array $args, string $name): ?string {
-        foreach ($args as $arg) {
-            if (str_starts_with($arg, "--$name=")) {
-                return substr($arg, strlen("--$name="));
-            }
-        }
-        return null;
-    }
-
-    /**
-     * Parse a duration string to seconds
-     */
-    private function parseDuration(string $duration): int {
-        preg_match('/^(\d+)([smhd])?$/', $duration, $matches);
-        $value = (int)($matches[1] ?? 0);
-        $unit = $matches[2] ?? 's';
-        
-        return match($unit) {
-            's' => $value,
-            'm' => $value * 60,
-            'h' => $value * 3600,
-            'd' => $value * 86400,
-            default => $value,
-        };
-    }
-
-}

lib/Manager.php

@@ -5,10 +5,14 @@ declare(strict_types=1);
 namespace KTXM\MailManager;
 
 use InvalidArgumentException;
+use KTXC\Preview\Preview;
+use KTXC\Preview\PreviewManager;
 use KTXC\Resource\ProviderManager;
+use KTXF\Preview\PreviewSource;
 use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Collection\CollectionPropertiesMutableInterface;
 use KTXF\Mail\Collection\ICollectionBase;
+use KTXF\Mail\Entity\EntityBaseInterface;
 use KTXF\Mail\Entity\IMessageBase;
 use KTXF\Mail\Object\Address;
 use KTXF\Mail\Object\AddressInterface;
@@ -46,6 +50,7 @@ class Manager {
     public function __construct(
         private LoggerInterface $logger,
         private ProviderManager $providerManager,
+        private PreviewManager $previewManager,
     ) { }
 
     /**
@@ -933,13 +938,6 @@ class Manager {
         }
     }
 
-    public function entityDownload(string $tenantId, string $userId, EntityIdentifier $targetEntity, array|null $targetPart): BinaryResource {
-        // retrieve service
-        $service = $this->serviceFetch($tenantId, $userId, $targetEntity->provider(), $targetEntity->service());
-        // download entity
-        return $service->entityDownload($targetEntity, $targetPart);
-    }
-
     /**
      * Check if messages exist
      *
@@ -1129,6 +1127,63 @@ class Manager {
         return $operationOutcome;
     }
 
+    /**
+     * Create a new entity in a collection.
+     *
+     * @param MessagePropertiesMutableInterface|array $properties Entity properties
+     *
+     * @throws InvalidArgumentException
+     */
+    public function entityCreate(string $tenantId, string $userId, CollectionIdentifier $target, MessagePropertiesMutableInterface|array $properties, array $options = []): EntityBaseInterface
+    {
+        $service = $this->serviceFetch($tenantId, $userId, $target->provider(), $target->service());
+
+        if ($service->getEnabled() === false) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' not found or is disabled");
+        }
+        if ($service instanceof ServiceEntityMutableInterface === false) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' does not support entity mutations");
+        }
+        if (!$service->capable(ServiceEntityMutableInterface::CAPABILITY_ENTITY_CREATE)) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' is not capable of creating entities");
+        }
+        if ($properties instanceof MessagePropertiesMutableInterface === false) {
+            $properties = $service->entityFresh()->getProperties()->jsonDeserialize($properties);
+        }
+
+        return $service->entityCreate($target, $properties, $options);
+    }
+
+    /**
+     * Modify an existing entity.
+     *
+     * The returned entity identifier is authoritative and may differ from the
+     * target identifier for providers that use replacement semantics.
+     *
+     * @param MessagePropertiesMutableInterface|array $properties Entity properties
+     *
+     * @throws InvalidArgumentException
+     */
+    public function entityModify(string $tenantId, string $userId, EntityIdentifier $target, MessagePropertiesMutableInterface|array $properties): EntityBaseInterface
+    {
+        $service = $this->serviceFetch($tenantId, $userId, $target->provider(), $target->service());
+
+        if ($service->getEnabled() === false) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' not found or is disabled");
+        }
+        if ($service instanceof ServiceEntityMutableInterface === false) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' does not support entity mutations");
+        }
+        if (!$service->capable(ServiceEntityMutableInterface::CAPABILITY_ENTITY_MODIFY)) {
+            throw new InvalidArgumentException("Service '{$service->identifier()}' is not capable of modifying entities");
+        }
+        if ($properties instanceof MessagePropertiesMutableInterface === false) {
+            $properties = $service->entityFresh()->getProperties()->jsonDeserialize($properties);
+        }
+
+        return $service->entityModify($target, $properties);
+    }
+
     /**
      * Deletes entities
      *
@@ -1294,4 +1349,50 @@ class Manager {
         return $service->entitySubmit($sender, $source, $message);
     }
 
+    public function entityDownload(string $tenantId, string $userId, EntityIdentifier $targetEntity, array|null $targetPart): BinaryResource {
+        // retrieve service
+        $service = $this->serviceFetch($tenantId, $userId, $targetEntity->provider(), $targetEntity->service());
+        // download entity
+        return $service->entityDownload($targetEntity, $targetPart);
+    }
+
+    /**
+     * Resolve an authorized attachment and lazily generate or retrieve its preview.
+     */
+    public function entityPreview(string $tenantId, string $userId, EntityIdentifier $targetEntity, array $part, string $variant = 'inline'): ?Preview {
+        $mimeType = $part['type'] ?? null;
+        $size = $part['size'] ?? null;
+        if (!is_string($mimeType) || ($size !== null && !is_int($size))) {
+            throw new InvalidArgumentException('Attachment preview requires a MIME type and optional integer size');
+        }
+
+        $selector = array_filter([
+            'blobId' => $part['blobId'] ?? null,
+            'partId' => $part['partId'] ?? null,
+            'cid' => $part['cid'] ?? null,
+        ], static fn(mixed $value): bool => is_string($value) && $value !== '');
+        if ($selector === []) {
+            throw new InvalidArgumentException('Attachment preview requires a blob, part, or content identifier');
+        }
+
+        $attachmentIdentity = hash('sha256', json_encode($selector, JSON_THROW_ON_ERROR));
+
+        return $this->previewManager->fetch($tenantId, new PreviewSource(
+            sourceType: 'mail-attachment',
+            identity: (string) $targetEntity . ':' . $attachmentIdentity,
+            // Attachments are immutable once delivered, so there is no revision to track;
+            // existence and access are enforced by entityDownload() (via serviceFetch) below,
+            // which only runs on a cache miss.
+            signature: 'immutable',
+            mimeType: $mimeType,
+            size: $size,
+            resourceFactory: fn(): BinaryResource => $this->entityDownload(
+                $tenantId,
+                $userId,
+                $targetEntity,
+                $selector,
+            ),
+        ), $variant);
+    }
+
 }

lib/Module.php

@@ -2,7 +2,8 @@
 
 namespace KTXM\MailManager;
 
-use KTXF\Module\ModuleBrowserInterface;
+use KTXF\Module\Configuration\BrowserModuleContextInterface;
+use KTXF\Module\Configuration\ModuleContextInterface;
 use KTXF\Module\ModuleInstanceAbstract;
 
 /**
@@ -11,7 +12,7 @@ use KTXF\Module\ModuleInstanceAbstract;
  * Provides unified mail sending and management across multiple providers
  * with context-aware service discovery and queued delivery.
  */
-class Module extends ModuleInstanceAbstract implements ModuleBrowserInterface
+class Module extends ModuleInstanceAbstract
 {
 
     public function __construct()
@@ -58,15 +59,10 @@ class Module extends ModuleInstanceAbstract implements ModuleBrowserInterface
         ];
     }
     
-    public function registerBI(): array {
-        return [
-            'handle' => $this->handle(),
-            'namespace' => 'MailManager',
-            'version' => $this->version(),
-            'label' => $this->label(),
-            'author' => $this->author(),
-            'description' => $this->description(),
-            'boot' => 'static/module.mjs',
-        ];
+    public function configure(ModuleContextInterface $context): void
+    {
+        if ($context instanceof BrowserModuleContextInterface) {
+            $context->registerModule($this, 'MailManager', 'static/module.mjs');
+        }
     }
 }

lib/Queue/JobStatus.php

@@ -1,32 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXM\MailManager\Queue;
-
-use JsonSerializable;
-
-/**
- * Mail Job Status
- * 
- * Status states for queued mail jobs.
- * 
- * @since 2025.05.01
- */
-enum JobStatus: string implements JsonSerializable {
-
-    case Pending = 'pending';
-    case Processing = 'processing';
-    case Complete = 'complete';
-    case Failed = 'failed';
-
-    public function jsonSerialize(): string {
-        return $this->value;
-    }
-
-}

lib/Queue/MailJob.php

@@ -1,115 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXM\MailManager\Queue;
-
-use DateTimeImmutable;
-use KTXF\Mail\Entity\IMessageMutable;
-use KTXF\Mail\Queue\SendOptions;
-
-/**
- * Mail Job
- * 
- * Represents a queued mail job with metadata and message content.
- * 
- * @since 2025.05.01
- */
-class MailJob {
-
-    public function __construct(
-        public readonly string $id,
-        public readonly string $tenantId,
-        public readonly string $providerId,
-        public readonly string|int $serviceId,
-        public readonly IMessageMutable $message,
-        public readonly SendOptions $options,
-        public JobStatus $status = JobStatus::Pending,
-        public int $attempts = 0,
-        public ?string $lastError = null,
-        public ?string $messageId = null,
-        public ?DateTimeImmutable $created = null,
-        public ?DateTimeImmutable $scheduled = null,
-        public ?DateTimeImmutable $lastAttempt = null,
-        public ?DateTimeImmutable $completed = null,
-    ) {
-        $this->created = $this->created ?? new DateTimeImmutable();
-        $this->scheduled = $this->scheduled ?? $this->calculateScheduledTime();
-    }
-
-    /**
-     * Calculate when this job should be processed
-     * 
-     * @return DateTimeImmutable
-     */
-    private function calculateScheduledTime(): DateTimeImmutable {
-        $scheduled = $this->created ?? new DateTimeImmutable();
-        
-        if ($this->options->delaySeconds !== null && $this->options->delaySeconds > 0) {
-            $scheduled = $scheduled->modify("+{$this->options->delaySeconds} seconds");
-        }
-        
-        return $scheduled;
-    }
-
-    /**
-     * Check if the job is ready to be processed
-     * 
-     * @return bool
-     */
-    public function isReady(): bool {
-        if ($this->status !== JobStatus::Pending) {
-            return false;
-        }
-        
-        return $this->scheduled === null || $this->scheduled <= new DateTimeImmutable();
-    }
-
-    /**
-     * Check if the job can be retried
-     * 
-     * @return bool
-     */
-    public function canRetry(): bool {
-        return $this->attempts < $this->options->retryCount;
-    }
-
-    /**
-     * Get retry delay in seconds based on attempt count (exponential backoff)
-     * 
-     * @return int
-     */
-    public function getRetryDelay(): int {
-        // Exponential backoff: 30s, 60s, 120s, 240s, ...
-        return min(30 * (2 ** $this->attempts), 3600);
-    }
-
-    /**
-     * Serialize job metadata for storage
-     * 
-     * @return array
-     */
-    public function toMetaArray(): array {
-        return [
-            'id' => $this->id,
-            'tenantId' => $this->tenantId,
-            'providerId' => $this->providerId,
-            'serviceId' => $this->serviceId,
-            'options' => $this->options->jsonSerialize(),
-            'status' => $this->status->value,
-            'attempts' => $this->attempts,
-            'lastError' => $this->lastError,
-            'messageId' => $this->messageId,
-            'created' => $this->created?->format('c'),
-            'scheduled' => $this->scheduled?->format('c'),
-            'lastAttempt' => $this->lastAttempt?->format('c'),
-            'completed' => $this->completed?->format('c'),
-        ];
-    }
-
-}

lib/Queue/MailQueueFile.php

@@ -1,492 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXM\MailManager\Queue;
-
-use DateTimeImmutable;
-use DI\Attribute\Inject;
-use Psr\Log\LoggerInterface;
-use KTXF\Mail\Entity\IMessageMutable;
-use KTXF\Mail\Entity\Message;
-use KTXF\Mail\Queue\SendOptions;
-use RuntimeException;
-
-/**
- * File-Based Mail Queue
- * 
- * Stores mail queue jobs on disk with atomic operations using file locks.
- * 
- * Structure:
- *   storage/{tenantId}/mail/queue/
- *     pending/{jobId}/
- *       meta.json
- *       message.json
- *     processing/{jobId}/...
- *     complete/{jobId}/...
- *     failed/{jobId}/...
- * 
- * @since 2025.05.01
- */
-class MailQueueFile {
-
-    private const DIR_PENDING = 'pending';
-    private const DIR_PROCESSING = 'processing';
-    private const DIR_COMPLETE = 'complete';
-    private const DIR_FAILED = 'failed';
-    private string $storagePath;
-
-    public function __construct(
-        private LoggerInterface $logger,
-        #[Inject('rootDir')] private readonly string $rootDir,
-    ) {
-        $this->storagePath = $this->rootDir . '/var/cache/mail_manager/queue';
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function enqueue(
-        string $tenantId,
-        string $providerId,
-        string|int $serviceId,
-        IMessageMutable $message,
-        SendOptions $options
-    ): string {
-        $jobId = $this->generateJobId();
-        
-        $job = new MailJob(
-            id: $jobId,
-            tenantId: $tenantId,
-            providerId: $providerId,
-            serviceId: $serviceId,
-            message: $message,
-            options: $options,
-        );
-        
-        $this->writeJob($job, self::DIR_PENDING);
-        
-        return $jobId;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function dequeue(string $tenantId, int $limit = 50): array {
-        $pendingDir = $this->getQueueDir($tenantId, self::DIR_PENDING);
-        
-        if (!is_dir($pendingDir)) {
-            return [];
-        }
-        
-        $jobs = [];
-        $entries = scandir($pendingDir);
-        
-        // Sort by priority (read meta files)
-        $jobsWithPriority = [];
-        foreach ($entries as $entry) {
-            if ($entry === '.' || $entry === '..') {
-                continue;
-            }
-            
-            $jobDir = $pendingDir . '/' . $entry;
-            if (!is_dir($jobDir)) {
-                continue;
-            }
-            
-            $metaFile = $jobDir . '/meta.json';
-            if (!file_exists($metaFile)) {
-                continue;
-            }
-            
-            $meta = json_decode(file_get_contents($metaFile), true);
-            if ($meta === null) {
-                continue;
-            }
-            
-            $scheduled = isset($meta['scheduled']) ? new DateTimeImmutable($meta['scheduled']) : null;
-            if ($scheduled !== null && $scheduled > new DateTimeImmutable()) {
-                continue; // Not ready yet
-            }
-            
-            $jobsWithPriority[] = [
-                'id' => $entry,
-                'priority' => $meta['options']['priority'] ?? 0,
-                'created' => $meta['created'] ?? '',
-            ];
-        }
-        
-        // Sort by priority (desc) then by created (asc)
-        usort($jobsWithPriority, function($a, $b) {
-            if ($a['priority'] !== $b['priority']) {
-                return $b['priority'] <=> $a['priority'];
-            }
-            return $a['created'] <=> $b['created'];
-        });
-        
-        // Take up to limit and move to processing
-        $jobsWithPriority = array_slice($jobsWithPriority, 0, $limit);
-        
-        foreach ($jobsWithPriority as $jobInfo) {
-            $job = $this->loadJob($tenantId, $jobInfo['id'], self::DIR_PENDING);
-            if ($job === null) {
-                continue;
-            }
-            
-            // Move to processing
-            $this->moveJob($tenantId, $jobInfo['id'], self::DIR_PENDING, self::DIR_PROCESSING);
-            $job->status = JobStatus::Processing;
-            $job->lastAttempt = new DateTimeImmutable();
-            $job->attempts++;
-            $this->updateJobMeta($tenantId, $jobInfo['id'], $job, self::DIR_PROCESSING);
-            
-            $jobs[] = $job;
-        }
-        
-        return $jobs;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function acknowledge(string $jobId, string $messageId): void {
-        $job = $this->findJobById($jobId);
-        if ($job === null) {
-            return;
-        }
-        
-        $job->status = JobStatus::Complete;
-        $job->messageId = $messageId;
-        $job->completed = new DateTimeImmutable();
-        
-        $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_COMPLETE);
-        $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_COMPLETE);
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function reject(string $jobId, string $error, bool $retry = true): void {
-        $job = $this->findJobById($jobId);
-        if ($job === null) {
-            return;
-        }
-        
-        $job->lastError = $error;
-        
-        if ($retry && $job->canRetry()) {
-            // Move back to pending with delay
-            $job->status = JobStatus::Pending;
-            $job->scheduled = (new DateTimeImmutable())->modify('+' . $job->getRetryDelay() . ' seconds');
-            
-            $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_PENDING);
-            $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_PENDING);
-        } else {
-            // Move to failed
-            $job->status = JobStatus::Failed;
-            $job->completed = new DateTimeImmutable();
-            
-            $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_FAILED);
-            $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_FAILED);
-        }
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function getJob(string $jobId): ?MailJob {
-        return $this->findJobById($jobId);
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function listJobs(string $tenantId, ?JobStatus $status = null, int $limit = 100, int $offset = 0): array {
-        $dirs = $status !== null 
-            ? [$this->statusToDir($status)]
-            : [self::DIR_PENDING, self::DIR_PROCESSING, self::DIR_COMPLETE, self::DIR_FAILED];
-        
-        $jobs = [];
-        
-        foreach ($dirs as $dir) {
-            $queueDir = $this->getQueueDir($tenantId, $dir);
-            if (!is_dir($queueDir)) {
-                continue;
-            }
-            
-            foreach (scandir($queueDir) as $entry) {
-                if ($entry === '.' || $entry === '..') {
-                    continue;
-                }
-                
-                $job = $this->loadJob($tenantId, $entry, $dir);
-                if ($job !== null) {
-                    $jobs[] = $job;
-                }
-            }
-        }
-        
-        // Sort by created desc
-        usort($jobs, fn($a, $b) => ($b->created?->getTimestamp() ?? 0) <=> ($a->created?->getTimestamp() ?? 0));
-        
-        return array_slice($jobs, $offset, $limit);
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function retry(string $jobId): bool {
-        $job = $this->findJobById($jobId);
-        if ($job === null || $job->status !== JobStatus::Failed) {
-            return false;
-        }
-        
-        $job->status = JobStatus::Pending;
-        $job->attempts = 0;
-        $job->lastError = null;
-        $job->scheduled = new DateTimeImmutable();
-        
-        $this->moveJob($job->tenantId, $jobId, self::DIR_FAILED, self::DIR_PENDING);
-        $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_PENDING);
-        
-        return true;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function purge(string $tenantId, JobStatus $status, int $olderThanSeconds): int {
-        $dir = $this->statusToDir($status);
-        $queueDir = $this->getQueueDir($tenantId, $dir);
-        
-        if (!is_dir($queueDir)) {
-            return 0;
-        }
-        
-        $threshold = new DateTimeImmutable("-{$olderThanSeconds} seconds");
-        $purged = 0;
-        
-        foreach (scandir($queueDir) as $entry) {
-            if ($entry === '.' || $entry === '..') {
-                continue;
-            }
-            
-            $jobDir = $queueDir . '/' . $entry;
-            $metaFile = $jobDir . '/meta.json';
-            
-            if (!file_exists($metaFile)) {
-                continue;
-            }
-            
-            $meta = json_decode(file_get_contents($metaFile), true);
-            $completed = isset($meta['completed']) ? new DateTimeImmutable($meta['completed']) : null;
-            
-            if ($completed !== null && $completed < $threshold) {
-                $this->deleteJobDir($jobDir);
-                $purged++;
-            }
-        }
-        
-        return $purged;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function stats(string $tenantId): array {
-        $stats = [
-            'pending' => 0,
-            'processing' => 0,
-            'complete' => 0,
-            'failed' => 0,
-        ];
-        
-        foreach ($stats as $status => $_) {
-            $dir = $this->getQueueDir($tenantId, $status);
-            if (is_dir($dir)) {
-                $stats[$status] = count(array_filter(
-                    scandir($dir),
-                    fn($e) => $e !== '.' && $e !== '..'
-                ));
-            }
-        }
-        
-        return $stats;
-    }
-
-    /**
-     * Generate a unique job ID
-     */
-    private function generateJobId(): string {
-        return sprintf(
-            '%08x-%04x-%04x-%04x-%012x',
-            time(),
-            mt_rand(0, 0xffff),
-            mt_rand(0, 0x0fff) | 0x4000,
-            mt_rand(0, 0x3fff) | 0x8000,
-            mt_rand(0, 0xffffffffffff)
-        );
-    }
-
-    /**
-     * Get the queue directory path for a tenant and status
-     */
-    private function getQueueDir(string $tenantId, string $status): string {
-        return $this->storagePath . '/' . $tenantId . '/mail/queue/' . $status;
-    }
-
-    /**
-     * Write a job to disk
-     */
-    private function writeJob(MailJob $job, string $status): void {
-        $jobDir = $this->getQueueDir($job->tenantId, $status) . '/' . $job->id;
-        
-        if (!is_dir($jobDir)) {
-            mkdir($jobDir, 0755, true);
-        }
-        
-        // Write meta
-        $metaFile = $jobDir . '/meta.json';
-        file_put_contents($metaFile, json_encode($job->toMetaArray(), JSON_PRETTY_PRINT));
-        
-        // Write message
-        $messageFile = $jobDir . '/message.json';
-        file_put_contents($messageFile, json_encode($job->message, JSON_PRETTY_PRINT));
-    }
-
-    /**
-     * Load a job from disk
-     */
-    private function loadJob(string $tenantId, string $jobId, string $status): ?MailJob {
-        $jobDir = $this->getQueueDir($tenantId, $status) . '/' . $jobId;
-        $metaFile = $jobDir . '/meta.json';
-        $messageFile = $jobDir . '/message.json';
-        
-        if (!file_exists($metaFile) || !file_exists($messageFile)) {
-            return null;
-        }
-        
-        $meta = json_decode(file_get_contents($metaFile), true);
-        $messageData = json_decode(file_get_contents($messageFile), true);
-        
-        if ($meta === null || $messageData === null) {
-            return null;
-        }
-        
-        $message = Message::fromArray($messageData);
-        
-        return new MailJob(
-            id: $meta['id'],
-            tenantId: $meta['tenantId'],
-            providerId: $meta['providerId'],
-            serviceId: $meta['serviceId'],
-            message: $message,
-            options: new SendOptions(
-                immediate: $meta['options']['immediate'] ?? false,
-                priority: $meta['options']['priority'] ?? 0,
-                retryCount: $meta['options']['retryCount'] ?? 3,
-                delaySeconds: $meta['options']['delaySeconds'] ?? null,
-            ),
-            status: JobStatus::from($meta['status']),
-            attempts: $meta['attempts'] ?? 0,
-            lastError: $meta['lastError'] ?? null,
-            messageId: $meta['messageId'] ?? null,
-            created: isset($meta['created']) ? new DateTimeImmutable($meta['created']) : null,
-            scheduled: isset($meta['scheduled']) ? new DateTimeImmutable($meta['scheduled']) : null,
-            lastAttempt: isset($meta['lastAttempt']) ? new DateTimeImmutable($meta['lastAttempt']) : null,
-            completed: isset($meta['completed']) ? new DateTimeImmutable($meta['completed']) : null,
-        );
-    }
-
-    /**
-     * Move a job between status directories
-     */
-    private function moveJob(string $tenantId, string $jobId, string $fromStatus, string $toStatus): void {
-        $fromDir = $this->getQueueDir($tenantId, $fromStatus) . '/' . $jobId;
-        $toDir = $this->getQueueDir($tenantId, $toStatus) . '/' . $jobId;
-        
-        if (!is_dir($fromDir)) {
-            throw new RuntimeException("Job directory not found: $fromDir");
-        }
-        
-        $toParent = dirname($toDir);
-        if (!is_dir($toParent)) {
-            mkdir($toParent, 0755, true);
-        }
-        
-        rename($fromDir, $toDir);
-    }
-
-    /**
-     * Update job metadata
-     */
-    private function updateJobMeta(string $tenantId, string $jobId, MailJob $job, string $status): void {
-        $metaFile = $this->getQueueDir($tenantId, $status) . '/' . $jobId . '/meta.json';
-        file_put_contents($metaFile, json_encode($job->toMetaArray(), JSON_PRETTY_PRINT));
-    }
-
-    /**
-     * Find a job by ID across all status directories
-     */
-    private function findJobById(string $jobId): ?MailJob {
-        // We need to search across all tenants and statuses
-        // This is inefficient - in production, consider caching or indexing
-        $tenantsDir = $this->storagePath;
-        
-        if (!is_dir($tenantsDir)) {
-            return null;
-        }
-        
-        foreach (scandir($tenantsDir) as $tenantId) {
-            if ($tenantId === '.' || $tenantId === '..') {
-                continue;
-            }
-            
-            foreach ([self::DIR_PENDING, self::DIR_PROCESSING, self::DIR_COMPLETE, self::DIR_FAILED] as $status) {
-                $job = $this->loadJob($tenantId, $jobId, $status);
-                if ($job !== null) {
-                    return $job;
-                }
-            }
-        }
-        
-        return null;
-    }
-
-    /**
-     * Delete a job directory recursively
-     */
-    private function deleteJobDir(string $dir): void {
-        if (!is_dir($dir)) {
-            return;
-        }
-        
-        foreach (scandir($dir) as $file) {
-            if ($file === '.' || $file === '..') {
-                continue;
-            }
-            $path = $dir . '/' . $file;
-            is_dir($path) ? $this->deleteJobDir($path) : unlink($path);
-        }
-        
-        rmdir($dir);
-    }
-
-    /**
-     * Convert JobStatus to directory name
-     */
-    private function statusToDir(JobStatus $status): string {
-        return match($status) {
-            JobStatus::Pending => self::DIR_PENDING,
-            JobStatus::Processing => self::DIR_PROCESSING,
-            JobStatus::Complete => self::DIR_COMPLETE,
-            JobStatus::Failed => self::DIR_FAILED,
-        };
-    }
-
-}

src/services/entityService.ts

@@ -2,7 +2,7 @@
  * Entity management service
  */
 
-import { transceivePost, transceiveStream, transceiveDownload } from './transceive';
+import { transceivePost, transceiveStream, transceiveDownload, transceiveBlob } from './transceive';
 import type {
   EntityFetchRequest,
   EntityFetchResponse,
@@ -28,6 +28,7 @@ import type {
   EntityPatchResponse,
   EntityPatchRequest,
   EntityDownloadRequest,
+  EntityPreviewRequest,
   EntityBlobsRequest,
   EntityBlobsResponse,
   EntityBlobsWireResponse,
@@ -231,6 +232,10 @@ export const entityService = {
     return transceiveDownload<EntityDownloadRequest>('entity.download', request);
   },
 
+  async preview(request: EntityPreviewRequest): Promise<Blob> {
+    return await transceiveBlob<EntityPreviewRequest>('entity.preview', request);
+  },
+
   /**
    * Fetch one or more message parts (attachments) inline for rendering.
    *

src/services/index.ts

@@ -8,9 +8,8 @@ export { serviceService } from './serviceService';
 export { collectionService } from './collectionService';
 export { entityService } from './entityService';
 
-// Type exports
-export type * from '../types/common';
-export type * from '../types/provider';
-export type * from '../types/service';
-export type * from '../types/collection';
-export type * from '../types/entity';
+export * from '../types/common';
+export * from '../types/provider';
+export * from '../types/service';
+export * from '../types/collection';
+export * from '../types/entity';

src/services/transceive.ts

@@ -188,6 +188,28 @@ export function transceiveDownload<TRequest>(
   return { transaction: request.transaction };
 }
 
+export async function transceiveBlob<TRequest>(operation: string, data: TRequest): Promise<Blob> {
+  const request: ApiRequest<TRequest> = {
+    version: API_VERSION,
+    transaction: generateTransactionId(),
+    operation,
+    data,
+  };
+  let blob: Blob | null = null;
+  await fetchWrapper.post(API_URL, request, {
+    headers: { 'Accept': '*/*' },
+    onStream: async (response: Response) => {
+      if (response.status === 204) {
+        throw new Error(`[${operation}] Preview unavailable`);
+      }
+      blob = await response.blob();
+    },
+  });
+  if (blob === null) throw new Error(`[${operation}] Empty preview response`);
+  return blob;
+}
+
+
 function appendHiddenField(form: HTMLFormElement, name: string, value: string): void {
   const input = document.createElement('input');
   input.type = 'hidden';

src/stores/entitiesStore.ts

@@ -10,6 +10,7 @@ import type {
   EntityBlobSelector,
   EntityBlobsResponse,
   EntityDownloadRequest,
+  EntityPreviewRequest,
   EntityTransmitRequest,
   EntityTransmitResponse,
 } from '../types/entity'
@@ -518,6 +519,10 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
     }
   }
 
+  async function preview(request: EntityPreviewRequest): Promise<Blob> {
+    return await entityService.preview(request)
+  }
+
   // Return public API
   return {
     // State (readonly)
@@ -540,6 +545,7 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
     move,
     transmit,
     download,
+    preview,
     blobs,
   }
 })

src/types/entity.ts

@@ -227,6 +227,12 @@ export interface EntityDownloadRequest {
   filename?: string | null;
 }
 
+export interface EntityPreviewRequest {
+  target: EntityIdentifier;
+  part: EntityBlobSelector & { type: string; size?: number | null };
+  variant?: string;
+}
+
 export interface EntityBlobsRequest {
   target: EntityIdentifier;
   parts: EntityBlobSelector[];
@@ -246,4 +252,4 @@ export interface EntityBlobsResult extends Omit<EntityBlobsWireResult, 'bytes'>
   blob: Blob;
 }
 
-export interface EntityBlobsResponse extends Array<EntityBlobsResult> {}
+export interface EntityBlobsResponse extends Array<EntityBlobsResult> {}