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\Calendar\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11/**
12 * Contract for dispatching calendar invitations and updating RSVP response statuses.
13 *
14 * @package App\Modules\Calendar\Application\Service
15 */
16interface CalendarInvitationServiceInterface
17{
18    /**
19     * Sends calendar invitation or cancellation emails to all attendees of an event.
20     *
21     * @param array<string, mixed> $record Calendar record data.
22     * @param string               $action 'create', 'update', or 'cancel'.
23     * @return int Number of invitations enqueued.
24     */
25    public function sendEventInvitations(array $record, string $action = 'create'): int;
26
27    /**
28     * Sends an iTIP METHOD:REPLY notification email to the organizer when an attendee RSVPs.
29     *
30     * @param array<string, mixed> $record        Calendar event record.
31     * @param string               $attendeeEmail Responding attendee email.
32     * @param string               $response      'accepted', 'declined', or 'tentative'.
33     * @return bool True if enqueued.
34     */
35    public function sendOrganizerRsvpNotification(array $record, string $attendeeEmail, string $response): bool;
36
37    /**
38     * Updates an attendee's RSVP status in the database JSON column.
39     *
40     * @param int    $calendarId    Event ID.
41     * @param string $attendeeEmail Attendee email.
42     * @param string $newStatus     'accepted', 'declined', or 'tentative'.
43     * @return bool True if updated successfully.
44     */
45    public function updateAttendeeStatus(int $calendarId, string $attendeeEmail, string $newStatus): bool;
46
47    /**
48     * Resolves organizer details from event record owner or fallback.
49     *
50     * @param array<string, mixed> $record Event data.
51     * @return array{name: string, email: string}
52     */
53    public function resolveOrganizer(array $record): array;
54
55    /**
56     * Resolves event record by ID.
57     *
58     * @param int $calendarId Event ID.
59     * @return array<string, mixed>|null Event row or null.
60     */
61    public function findCalendarRecord(int $calendarId): ?array;
62
63    /**
64     * Normalizes attendees data into a clean array.
65     *
66     * @param mixed $raw Raw attendees data from DB.
67     * @return list<array{name: string, email: string, status: string}>
68     */
69    public function extractAttendees(mixed $raw): array;
70
71    /**
72     * Formats start and end dates into localized human-readable string.
73     *
74     * @param string $startDate ISO datetime string.
75     * @param string $endDate   ISO datetime string.
76     * @param bool   $isAllDay  Whether event is all-day.
77     * @param string $lang      Language code ('pl' or 'en').
78     * @return string Human-readable formatted range.
79     */
80    public function formatEventDate(
81        string $startDate,
82        string $endDate,
83        bool $isAllDay,
84        string $lang = 'pl'
85    ): string;
86}