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\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11/**
12 * Contract for email open pixels and click-through tracking service.
13 *
14 * @package App\Modules\Mail\Application\Service
15 */
16interface MailTrackingServiceInterface
17{
18    /**
19     * Creates and registers a new tracking token for an outgoing email.
20     *
21     * @param int|null $mailQueueId    Queue record ID.
22     * @param string   $recipientEmail Recipient email address.
23     * @return string Generated unique tracking token string.
24     */
25    public function registerTrackingToken(?int $mailQueueId, string $recipientEmail): string;
26
27    /**
28     * Records email open event in tracking records.
29     *
30     * @param string      $token     Tracking token.
31     * @param string|null $ipAddress Client IP address.
32     * @param string|null $userAgent Client User-Agent string.
33     */
34    public function recordOpen(string $token, ?string $ipAddress = null, ?string $userAgent = null): void;
35
36    /**
37     * Records link click event and updates click counters.
38     *
39     * @param string      $token     Tracking token.
40     * @param string      $url       Target clicked URL.
41     * @param string|null $ipAddress Client IP address.
42     * @param string|null $userAgent Client User-Agent string.
43     */
44    public function recordClick(
45        string $token,
46        string $url,
47        ?string $ipAddress = null,
48        ?string $userAgent = null
49    ): void;
50
51    /**
52     * Injects tracking pixel and wraps hyperlinks with click-tracking redirects.
53     *
54     * @param string $html    Original email HTML body.
55     * @param string $token   Registered tracking token.
56     * @param string $baseUrl Base application URL.
57     * @return string Enhanced HTML with pixel and tracked hyperlinks.
58     */
59    public function injectTracking(
60        string $html,
61        string $token,
62        string $baseUrl = 'https://app-admin.ammonly.com'
63    ): string;
64}