<?php

namespace SugarCalendarBookings\Integrations;

use SugarCalendarBookings\Appointments\AppointmentModel;
use WP_Error;

/**
 * Meeting provider interface.
 *
 * Contract for integrations that create and manage online meetings
 * tied to appointments (e.g., Zoom, Google Meet, Microsoft Teams).
 *
 * Implementations handle all provider-specific API calls. The generic
 * MeetingManager orchestrates appointment lifecycle hooks and delegates
 * to the correct provider based on the appointment's online_location.
 *
 * @since 1.4.0
 */
interface MeetingProviderInterface extends IntegrationCapabilityInterface {

	/**
	 * Create a meeting for an appointment.
	 *
	 * Returns an associative array of meeting metadata to merge into
	 * the appointment's online_location. Must include at minimum
	 * the keys returned by get_meeting_meta_keys().
	 *
	 * @since 1.4.0
	 *
	 * @param AppointmentModel $appointment The appointment model.
	 *
	 * @return array|WP_Error Meeting metadata array on success, WP_Error on failure.
	 */
	public function create_meeting( AppointmentModel $appointment );

	/**
	 * Update an existing meeting for an appointment.
	 *
	 * Called when appointment details change (time, service, invitees).
	 * The implementation decides whether to patch or recreate the meeting.
	 *
	 * @since 1.4.0
	 *
	 * @param AppointmentModel $appointment The appointment model.
	 *
	 * @return array|WP_Error Updated meeting metadata array on success, WP_Error on failure.
	 */
	public function update_meeting( AppointmentModel $appointment );

	/**
	 * Delete a meeting for an appointment.
	 *
	 * @since 1.4.0
	 *
	 * @param AppointmentModel $appointment The appointment model.
	 *
	 * @return true|WP_Error True on success, WP_Error on failure.
	 */
	public function delete_meeting( AppointmentModel $appointment );

	/**
	 * Get the metadata keys this provider stores on an appointment.
	 *
	 * These keys are stored in the appointment's online_location array
	 * alongside the 'provider' key.
	 *
	 * @since 1.4.0
	 *
	 * @return string[] e.g., ['meeting_id', 'join_url'].
	 */
	public function get_meeting_meta_keys(): array;

	/**
	 * Filter a list of WP user IDs to those that can deliver this meeting provider.
	 *
	 * Typically that's users backed by either a global (admin) connection — in
	 * which case everyone can deliver via fallback — or their own active
	 * connection.
	 *
	 * @since 1.4.0
	 *
	 * @param int[] $user_ids Candidate WP user IDs.
	 *
	 * @return int[] Subset of $user_ids that can deliver this provider.
	 */
	public function get_deliverable_user_ids( array $user_ids ): array;
}
