<?php

namespace SugarCalendarBookings\Integrations\CalendarEvents;

use SugarCalendarBookings\Appointments\AppointmentModel;
use SugarCalendarBookings\Integrations\OAuthRelay\OAuthConnectionModel;
use WP_Error;

/**
 * Cancellable calendar event provider interface.
 *
 * Optional capability for integrations that support a first-class
 * cancellation action (e.g. Microsoft Graph POST /events/{id}/cancel).
 * Providers that implement this interface can send attendee notifications
 * and mark the event cancelled in remote calendars without deleting it.
 *
 * Providers that do NOT implement this interface receive no action on
 * appointment cancellation — the event simply remains in the calendar
 * until the appointment is hard-deleted.
 *
 * @since 1.5.0
 */
interface CancellableCalendarEventProviderInterface {

	/**
	 * Cancel a calendar event and notify attendees.
	 *
	 * The remote event MUST NOT be deleted by this method. It is expected to
	 * remain in the organiser's calendar in a cancelled state. Deletion is
	 * handled separately by delete_event() when the appointment is hard-deleted.
	 *
	 * @since 1.5.0
	 *
	 * @param AppointmentModel     $appointment   Appointment being cancelled.
	 * @param OAuthConnectionModel $connection    Target OAuth connection.
	 * @param string               $event_id      Provider event ID to cancel.
	 * @param array                $existing_link Previously-stored event link entry.
	 *
	 * @return true|WP_Error True on success or error.
	 */
	public function cancel_event( AppointmentModel $appointment, OAuthConnectionModel $connection, string $event_id, array $existing_link );
}
