<?php
if ( ! defined( 'ABSPATH' ) ) exit;

/**
 * Data source interface and factory for Scholar Sync.
 *
 * @package ScholarSync
 * @subpackage ScholarSync/includes
 */

/**
 * Contract that every data source must satisfy.
 */
interface ScholarSync_Data_Source {

	/**
	 * Search Google Scholar for author profiles matching $query.
	 *
	 * @param string $query Author name (min 4 chars).
	 * @return array|WP_Error
	 *   Success: array with key 'profiles' ⇒ list of
	 *     [ 'author_id', 'name', 'thumbnail', 'affiliations' ].
	 *   Failure: WP_Error with a human-readable message.
	 */
	public function search_authors( string $query );

	/**
	 * Fetch full author + articles data for a single scholar.
	 *
	 * The returned array must have the same shape that
	 * ScholarSync_Author_Sync::insert_author() and insert_articles() expect:
	 *   author     → id, name, affiliations, website, interests, thumbnail
	 *   cited_by   → table (citations/h_index/i10_index rows), graph
	 *   articles      → citation_id, title, link, authors, publication, cited_by, year
	 *   pagination    → next, count
	 *   transaction_id → present when more pages remain; absent when sync is complete
	 *
	 * @param string $scholar_id      Google Scholar user ID.
	 * @param string $transaction_id  GUID from previous response, or '' to start fresh.
	 * @return array|WP_Error
	 */
	public function get_author( string $scholar_id, string $transaction_id = '' );

	/**
	 * Return sync status for an already-tracked author.
	 *
	 * @param string $scholar_id Google Scholar user ID.
	 * @return array|WP_Error
	 *   Success: [ 'last_update' => datetime string, 'next_update' => datetime string ]
	 *   Failure: WP_Error.
	 */
	public function get_sync_status( string $scholar_id );
}

/**
 * Return the active data source instance.
 *
 * Always returns the remote cloud source (scholar-sync.org).
 *
 * @return ScholarSync_Data_Source
 */
function scholar_sync_get_data_source(): ScholarSync_Data_Source {
	require_once SCHOLAR_SYNC_PLUGIN_DIR . '/includes/class-scholar-sync-remote-source.php';
	return new ScholarSync_Remote_Source();
}
