133 lines
3.9 KiB
PHP
133 lines
3.9 KiB
PHP
<?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 JsonSerializable;
|
|
use KTXF\Mail\Selector\ServiceSelector;
|
|
use KTXF\Mail\Service\IServiceBase;
|
|
|
|
/**
|
|
* Mail Provider Base Interface
|
|
*
|
|
* Core interface for mail providers with context-aware service discovery.
|
|
*
|
|
* @since 2025.05.01
|
|
*/
|
|
interface IProviderBase extends JsonSerializable {
|
|
|
|
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
|
|
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
|
|
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
|
|
public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';
|
|
|
|
public const JSON_TYPE = 'mail.provider';
|
|
public const JSON_PROPERTY_TYPE = '@type';
|
|
public const JSON_PROPERTY_ID = 'id';
|
|
public const JSON_PROPERTY_LABEL = 'label';
|
|
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
|
|
|
|
/**
|
|
* Confirms if a specific capability is supported
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $value Required capability e.g. 'ServiceList'
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function capable(string $value): bool;
|
|
|
|
/**
|
|
* Lists all supported capabilities
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @return array<string,bool>
|
|
*/
|
|
public function capabilities(): array;
|
|
|
|
/**
|
|
* Gets the unique identifier for this provider
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
|
|
*/
|
|
public function id(): string;
|
|
|
|
/**
|
|
* Gets the localized human-friendly name of this provider
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @return string Provider label (e.g., 'SMTP Mail Provider')
|
|
*/
|
|
public function label(): string;
|
|
|
|
/**
|
|
* Lists services for a tenant, optionally filtered by user context
|
|
*
|
|
* When userId is null, returns only System-scoped services.
|
|
* When userId is provided, returns System-scoped services plus
|
|
* User-scoped services owned by that user.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context (null = system only)
|
|
* @param ServiceSelector|null $selector Optional filter criteria
|
|
*
|
|
* @return array<string|int, IServiceBase>
|
|
*/
|
|
public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;
|
|
|
|
/**
|
|
* Checks if specific services exist
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string|int ...$identifiers Service identifiers to check
|
|
*
|
|
* @return array<string|int, bool> Identifier => exists
|
|
*/
|
|
public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;
|
|
|
|
/**
|
|
* Fetches a specific service by identifier
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string|int $identifier Service identifier
|
|
*
|
|
* @return IServiceBase|null
|
|
*/
|
|
public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;
|
|
|
|
/**
|
|
* 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|null $userId User identifier for context
|
|
* @param string $address Email address to find service for
|
|
*
|
|
* @return IServiceBase|null Service handling the address, or null
|
|
*/
|
|
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;
|
|
|
|
}
|