Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Mail\Application\Contract;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Mail\Domain\Model\ClientMailbox;
12use App\Modules\Mail\Domain\Model\MailMessageDetailDto;
13
14/**
15 * Contract for Email Scanner and Metadata Matcher Service.
16 *
17 * Resolves CRM entities by prefix and email, resolves ownership from headers,
18 * enforces multi-user co-ownership deduplication, and handles record ingestion.
19 *
20 * @package App\Modules\Mail\Application\Contract
21 */
22interface EmailScannerMatcherServiceInterface
23{
24    /**
25     * Resolves CRM entities (ticket, contact, company) from subject, body, and email addresses.
26     *
27     * @param string        $subject   Email subject line.
28     * @param string        $bodyText  Email text body.
29     * @param string        $fromEmail Sender address.
30     * @param array<string> $toEmails  Recipient addresses.
31     * @return array{ticket_id: ?int, contact_id: ?int, company_id: ?int, module_prefix: ?string} Resolved entity IDs.
32     */
33    public function resolveEntities(
34        string $subject,
35        string $bodyText,
36        string $fromEmail,
37        array $toEmails
38    ): array;
39
40    /**
41     * Resolves primary record owner, co-owners, and direction (inbound/outbound) from RFC headers.
42     *
43     * @param string        $fromEmail    Sender email address.
44     * @param array<string> $toEmails     Primary recipient addresses.
45     * @param array<string> $ccEmails     Carbon copy recipient addresses.
46     * @param array<string> $bccEmails    Blind carbon copy recipient addresses.
47     * @param int           $defaultOwner Fallback owner ID (e.g. mailbox owner or admin).
48     * @return array{owner: int, co_owners: array<int>, direction: string, created_by: int} Ownership resolution.
49     */
50    public function resolveOwnership(
51        string $fromEmail,
52        array $toEmails,
53        array $ccEmails,
54        array $bccEmails,
55        int $defaultOwner
56    ): array;
57
58    /**
59     * Ingests a parsed email message with deduplication and workflow event triggering.
60     *
61     * @param ClientMailbox        $mailbox Mailbox entity where message was found.
62     * @param MailMessageDetailDto $detail  Parsed message payload.
63     * @param bool                 $dryRun  Whether to simulate ingestion without database write.
64     * @return array{status: string, email_id: ?int, owner: int, co_owners: array<int>, is_duplicate: bool}
65     */
66    public function processIngestion(
67        ClientMailbox $mailbox,
68        MailMessageDetailDto $detail,
69        bool $dryRun = false
70    ): array;
71}