//! Public site provider trait definitions.

use anyhow::Result;
use async_trait::async_trait;

use super::capabilities::SiteCapabilities;
use super::query::MediaResourceQuery;
use super::types::{ResolvedSiteDownload, ResourceCandidate};
use crate::types::Provider;

/// Public provider interface for site-based media resource discovery.
#[async_trait]
pub trait SiteProvider: Provider {
    /// Search primary resources on the target site.
    async fn search_resources(&self, query: &MediaResourceQuery) -> Result<Vec<ResourceCandidate>>;

    /// Fetch the latest resources exposed by the target site.
    async fn latest_resources(&self) -> Result<Vec<ResourceCandidate>>;

    /// Resolve a candidate into a torrent handoff target.
    ///
    /// # Errors
    ///
    /// Returns an error when the candidate can no longer be resolved or the
    /// provider cannot produce a usable torrent URL or torrent payload.
    async fn resolve(&self, candidate: &ResourceCandidate) -> Result<ResolvedSiteDownload>;

    /// Declare provider capabilities.
    fn capabilities(&self) -> SiteCapabilities;
}
