import type {
	MetadataSearchQuery,
	MetadataSearchResult,
	ResolvedSeriesMetadataResult,
	ResolvedTitleCreditsResult,
	SeriesCreditsQuery,
	SeriesEpisodeCreditsQuery,
	SeriesInfo,
} from "@/models";
import type { IProviderLifecycle } from "./lifecycle";

/**
 * Series search query interface
 * Extends base metadata search query for TV series-specific searches
 */
export type SeriesSearchQuery = MetadataSearchQuery;

/**
 * Series search result interface
 * Uses base metadata search result structure
 */
export type SeriesSearchResult = MetadataSearchResult;

/**
 * Base interface for TV series metadata providers
 * Providers implementing this interface can supply series metadata and optionally credits
 * Extends IProviderLifecycle for mount/dispose capabilities
 */
export interface BaseSeriesProvider extends IProviderLifecycle {
	/**
	 * Search for TV series by title and optional year
	 * @param query - Search query containing title and optional year
	 * @returns Promise resolving to search results with series matches
	 */
	search(query: SeriesSearchQuery): Promise<SeriesSearchResult>;

	/**
	 * Resolve detailed TV series metadata from file information
	 * @param info - Series information extracted from file including season and episode
	 * @returns Promise resolving to complete series metadata or null if not found
	 */
	resolve(info: SeriesInfo): Promise<ResolvedSeriesMetadataResult>;

	/**
	 * Resolve credits for Series. This function executed after `resolve()` function. Binded into schema `series`
	 * @param query - SeriesCreditsQuery object
	 */
	resolveCredits(
		query: SeriesCreditsQuery,
	): Promise<ResolvedTitleCreditsResult>;

	/**
	 * Resolve credits (cast & crew) for a TV series episode
	 * Optional method - not all providers may support credits
	 * @param query - Object containing seriesId, seasonNumber, and episodeNumber
	 * @returns Promise resolving to credits data or null if not found
	 */
	resolveCreditsForEpisode?(
		query: SeriesEpisodeCreditsQuery,
	): Promise<ResolvedTitleCreditsResult>;
}
