<?php

namespace SugarCalendarBookings\Migration;

use WP_Error;

/**
 * Source Adapter Interface.
 *
 * @since 1.3.0
 */
interface SourceAdapterInterface {

	/**
	 * Fetch raw data from source with pagination.
	 *
	 * IMPORTANT: Must support limit/offset for batch processing!
	 *
	 * @since 1.3.0
	 *
	 * @param string               $entity_type Entity type (service, customer, appointment, location).
	 * @param array<string, mixed> $options     Options: - limit: int (default 100); offset: int (default 0).
	 *
	 * @return array<object>|WP_Error Array of raw data or error.
	 */
	public function fetch( string $entity_type, array $options = [] );

	/**
	 * Get total count of entities in source.
	 *
	 * Required for progress tracking on large migrations.
	 *
	 * @since 1.3.0
	 *
	 * @param string $entity_type Entity type.
	 *
	 * @return int|WP_Error Total count or error.
	 */
	public function count( string $entity_type );

	/**
	 * Map raw data to SCB format.
	 *
	 * @since 1.3.0
	 *
	 * @param string               $entity_type Entity type.
	 * @param object               $raw_data    Raw data.
	 * @param array<string, mixed> $context     Context (author_id, etc.).
	 *
	 * @return array<string, mixed>|null Mapped data or null.
	 */
	public function map( string $entity_type, object $raw_data, array $context = [] );

	/**
	 * Validate source availability.
	 *
	 * @since 1.3.0
	 *
	 * @return true|WP_Error
	 */
	public function validate();

	/**
	 * Get source ID.
	 *
	 * @since 1.3.0
	 *
	 * @return string
	 */
	public function get_id(): string;

	/**
	 * Get source name.
	 *
	 * @since 1.3.0
	 *
	 * @return string
	 */
	public function get_name(): string;
}
