<?php

namespace SugarCalendarBookings\Integrations;

use SugarCalendarBookings\Integrations\OAuthRelay\OAuthConnectionModel;

/**
 * Calendar conflict provider interface.
 *
 * Contract for integrations that can provide busy time data
 * from external calendars for conflict checking.
 *
 * @since 1.4.0
 */
interface CalendarConflictProviderInterface extends IntegrationCapabilityInterface {

	/**
	 * Fetch busy times from the provider for a given connection.
	 *
	 * Called on initial OAuth connect. Returns array of busy time entries,
	 * each with keys: provider_event_id, title, start_at, end_at, is_all_day.
	 *
	 * @since 1.4.0
	 *
	 * @param OAuthConnectionModel $connection OAuth connection.
	 * @param string               $from       Start datetime (Y-m-d H:i:s).
	 * @param string               $to         End datetime (Y-m-d H:i:s).
	 *
	 * @return array Array of event arrays.
	 */
	public function fetch_busy_times( OAuthConnectionModel $connection, string $from, string $to ): array;

	/**
	 * Get the calendar ID for this provider's connection.
	 *
	 * For MVP, returns the primary/default calendar identifier.
	 *
	 * @since 1.4.0
	 *
	 * @param OAuthConnectionModel $connection OAuth connection.
	 *
	 * @return string Calendar identifier.
	 */
	public function get_calendar_id( OAuthConnectionModel $connection ): string;
}
