rustledger 0.16.0

//! Price fetching module for rustledger.
//!
//! This module provides a pluggable price source system that supports:
//! - Built-in sources (Yahoo Finance, Coinbase, ECB, etc.)
//! - External command sources for custom integrations
//! - Configurable commodity-to-source mappings
//! - Fallback chains for reliability

pub mod cache;
pub mod discovery;
pub mod external;
pub mod sources;

use crate::config::{CommodityMapping, PriceConfig, PriceSourceConfig, SourceRef};
use anyhow::{Context, Result};
use rust_decimal::Decimal;
use rustledger_core::NaiveDate;
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

pub use sources::PriceSource;

/// A request to fetch a price.
#[derive(Debug, Clone)]
pub struct PriceRequest {
    /// The ticker symbol to fetch.
    pub ticker: String,
    /// The target currency for the price.
    pub currency: String,
    /// Optional specific date (None = current price).
    pub date: Option<NaiveDate>,
}

impl PriceRequest {
    /// Create a new price request.
    pub fn new(ticker: impl Into<String>, currency: impl Into<String>) -> Self {
        Self {
            ticker: ticker.into(),
            currency: currency.into(),
            date: None,
        }
    }

    /// Set the date for the request.
    #[must_use]
    pub const fn with_date(mut self, date: NaiveDate) -> Self {
        self.date = Some(date);
        self
    }
}

/// A response from a price source.
#[derive(Debug, Clone)]
pub struct PriceResponse {
    /// The fetched price.
    pub price: Decimal,
    /// The currency of the price.
    pub currency: String,
    /// The date of the price.
    pub date: NaiveDate,
    /// The source that provided the price.
    pub source: String,
}

/// Registry of available price sources.
pub struct PriceSourceRegistry {
    sources: HashMap<String, Arc<dyn PriceSource>>,
    default_source: String,
    timeout: Duration,
    /// When false, a commodity with no explicit source declaration
    /// errors instead of silently using `default_source`. See #966 and
    /// `PriceConfig::use_default_source`.
    use_default_source: bool,
}

impl PriceSourceRegistry {
    /// Create a new registry with built-in sources.
    pub fn new(config: &PriceConfig) -> Self {
        let mut sources: HashMap<String, Arc<dyn PriceSource>> = HashMap::new();
        let timeout = Duration::from_secs(config.effective_timeout());

        // Register built-in sources
        sources.insert(
            "yahoo".to_string(),
            Arc::new(sources::YahooFinanceSource::new(timeout)),
        );
        sources.insert(
            "coinbase".to_string(),
            Arc::new(sources::CoinbaseSource::new(timeout)),
        );
        sources.insert(
            "coincap".to_string(),
            Arc::new(sources::CoinCapSource::new(timeout)),
        );
        sources.insert(
            "ecb".to_string(),
            Arc::new(sources::EcbSource::new(timeout)),
        );
        sources.insert(
            "ratesapi".to_string(),
            Arc::new(sources::RatesApiSource::new(timeout)),
        );
        sources.insert(
            "tsp".to_string(),
            Arc::new(sources::TspSource::new(timeout)),
        );
        sources.insert(
            "eastmoneyfund".to_string(),
            Arc::new(sources::EastMoneyFundSource::new(timeout)),
        );

        // Register API key sources (always registered; they return clear errors if key is missing)
        sources.insert(
            "oanda".to_string(),
            Arc::new(sources::OandaSource::new(timeout)),
        );
        sources.insert(
            "alphavantage".to_string(),
            Arc::new(sources::AlphaVantageSource::new(timeout)),
        );
        sources.insert(
            "coinmarketcap".to_string(),
            Arc::new(sources::CoinMarketCapSource::new(timeout)),
        );
        sources.insert(
            "quandl".to_string(),
            Arc::new(sources::QuandlSource::new(timeout)),
        );

        // Register custom command sources from config
        for (name, source_config) in &config.sources {
            if let PriceSourceConfig::Command {
                command,
                timeout: cmd_timeout,
                env,
            } = source_config
            {
                let cmd_timeout =
                    Duration::from_secs(cmd_timeout.unwrap_or(config.effective_timeout()));
                sources.insert(
                    name.clone(),
                    Arc::new(external::ExternalCommandSource::with_name(
                        command.clone(),
                        cmd_timeout,
                        env.clone(),
                        name.clone(),
                    )),
                );
            }
        }

        Self {
            sources,
            default_source: config.effective_default_source().to_string(),
            timeout,
            use_default_source: config.effective_use_default_source(),
        }
    }

    /// Get a source by name.
    pub fn get(&self, name: &str) -> Option<Arc<dyn PriceSource>> {
        self.sources.get(name).cloned()
    }

    /// Get the default source.
    pub fn default_source(&self) -> Option<Arc<dyn PriceSource>> {
        self.get(&self.default_source)
    }

    /// Get the default source name.
    pub fn default_source_name(&self) -> &str {
        &self.default_source
    }

    /// List all registered source names.
    pub fn list_sources(&self) -> Vec<&str> {
        let mut names: Vec<&str> = self.sources.keys().map(String::as_str).collect();
        names.sort_unstable();
        names
    }

    /// Check if a source is registered.
    pub fn has_source(&self, name: &str) -> bool {
        self.sources.contains_key(name)
    }

    /// Get the configured timeout.
    pub const fn timeout(&self) -> Duration {
        self.timeout
    }

    /// Fetch a price using the configured mapping.
    ///
    /// This method resolves the commodity to the appropriate source and
    /// ticker based on the configuration, then fetches the price. When a
    /// fallback chain is in play, each entry's per-source ticker is used
    /// (issue #963).
    ///
    /// # Errors
    ///
    /// Returns an error if the commodity has no explicit source
    /// declaration (no CLI `--source`, no `[price.mapping.X]` in config,
    /// no `price:` metadata) and `[price] use_default_source = false`
    /// (the default). See issue #966.
    pub fn fetch_price(
        &self,
        commodity: &str,
        currency: &str,
        date: Option<NaiveDate>,
        mapping: &HashMap<String, CommodityMapping>,
    ) -> Result<PriceResponse> {
        let attempts = self.resolve_mapping(commodity, mapping)?;

        let mut last_error = None;
        let mut unknown_sources = Vec::new();

        for (source_name, ticker) in &attempts {
            if let Some(source) = self.get(source_name) {
                let request = PriceRequest {
                    ticker: ticker.clone(),
                    currency: currency.to_string(),
                    date,
                };

                match source.fetch_price(&request) {
                    Ok(response) => return Ok(response),
                    Err(e) => {
                        last_error = Some(e);
                        // Try next source in fallback chain
                    }
                }
            } else {
                // Track unknown sources for error reporting
                unknown_sources.push(source_name.clone());
            }
        }

        // Build an informative error message
        let err_msg = if let Some(e) = last_error {
            if unknown_sources.is_empty() {
                e
            } else {
                anyhow::anyhow!(
                    "{}; note: unknown sources skipped: {}",
                    e,
                    unknown_sources.join(", ")
                )
            }
        } else if !unknown_sources.is_empty() {
            anyhow::anyhow!(
                "No price source available for commodity {commodity}: unknown sources: {}",
                unknown_sources.join(", ")
            )
        } else {
            anyhow::anyhow!("No price source available for commodity {commodity}")
        };

        Err(err_msg)
    }

    /// Resolve a commodity to a list of `(source, ticker)` attempts to
    /// try in order. Each fallback entry can carry its own ticker so a
    /// chain like `EUR:ecbrates/GBP-EUR,EUR:ecb/GBP` queries each source
    /// with the ticker shape it expects (issue #963).
    ///
    /// # Errors
    ///
    /// Returns an error if `mapping` has no entry for `commodity` and
    /// `use_default_source` is false. The error message lists the
    /// remediation paths so users can pick whichever fits their workflow.
    fn resolve_mapping(
        &self,
        commodity: &str,
        mapping: &HashMap<String, CommodityMapping>,
    ) -> Result<Vec<(String, String)>> {
        if let Some(commodity_mapping) = mapping.get(commodity) {
            let attempts = match commodity_mapping {
                CommodityMapping::Simple(ticker) => {
                    vec![(self.default_source.clone(), ticker.clone())]
                }
                CommodityMapping::Detailed(d) => {
                    let parent_ticker = d.ticker.clone().unwrap_or_else(|| commodity.to_string());
                    match &d.source {
                        SourceRef::Single(s) => vec![(s.clone(), parent_ticker)],
                        SourceRef::Fallback(entries) => entries
                            .iter()
                            .map(|e| {
                                // Per-entry ticker wins; otherwise fall back to the
                                // parent ticker. This mirrors the metadata semantics
                                // the discovery layer encodes for chained `price:`.
                                let t = e
                                    .ticker()
                                    .map_or_else(|| parent_ticker.clone(), str::to_string);
                                (e.source_name().to_string(), t)
                            })
                            .collect(),
                    }
                }
            };
            return Ok(attempts);
        }

        // No mapping. Issue #966: silently dispatching to `default_source`
        // is the failure mode where currency codes like `BAM` get sent to
        // Yahoo and return a stock price for an unrelated ticker. Refuse
        // unless the user has opted in via `[price] use_default_source = true`.
        if self.use_default_source {
            return Ok(vec![(self.default_source.clone(), commodity.to_string())]);
        }
        Err(anyhow::anyhow!(
            "no price source configured for {commodity}. Pick one:\n  \
             - pass `--source <name>` (e.g. `--source ecb`),\n  \
             - pass `--mapping {commodity}:<TICKER>`,\n  \
             - add `[price.mapping.{commodity}]` to your rledger config,\n  \
             - annotate the commodity in your beancount file with \
             `price: \"<quote>:<source>/<ticker>\"` or `quote_currency: \"<currency>\"` \
             and load the file with `-f`,\n  \
             - or set `[price] use_default_source = true` in your config to fall back \
             to the default source ({default}) for unmapped symbols.",
            default = self.default_source,
        ))
    }
}

impl Default for PriceSourceRegistry {
    fn default() -> Self {
        Self::new(&PriceConfig::default())
    }
}

/// Convenience function to fetch a single price with default configuration.
pub fn fetch_price(
    ticker: &str,
    currency: &str,
    source_name: Option<&str>,
) -> Result<PriceResponse> {
    let config = PriceConfig::default();
    let registry = PriceSourceRegistry::new(&config);

    let source_name = source_name.unwrap_or(registry.default_source_name());
    let source = registry
        .get(source_name)
        .with_context(|| format!("Unknown price source: {source_name}"))?;

    let request = PriceRequest::new(ticker, currency);
    source.fetch_price(&request)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{FallbackDetail, FallbackEntry};

    #[test]
    fn test_price_request_builder() {
        let request = PriceRequest::new("AAPL", "USD");
        assert_eq!(request.ticker, "AAPL");
        assert_eq!(request.currency, "USD");
        assert!(request.date.is_none());

        let date = rustledger_core::naive_date(2024, 1, 15).unwrap();
        let request_with_date = PriceRequest::new("AAPL", "USD").with_date(date);
        assert_eq!(request_with_date.date, Some(date));
    }

    #[test]
    fn test_registry_default_sources() {
        let registry = PriceSourceRegistry::default();

        // Built-in sources should be registered (no API key required)
        assert!(registry.has_source("yahoo"));
        assert!(registry.has_source("coinbase"));
        assert!(registry.has_source("coincap"));
        assert!(registry.has_source("ecb"));
        assert!(registry.has_source("ratesapi"));
        assert!(registry.has_source("tsp"));
        assert!(registry.has_source("eastmoneyfund"));

        // API key sources should also be registered (will error if key not set)
        assert!(registry.has_source("oanda"));
        assert!(registry.has_source("alphavantage"));
        assert!(registry.has_source("coinmarketcap"));
        assert!(registry.has_source("quandl"));

        // Default source should be yahoo
        assert_eq!(registry.default_source_name(), "yahoo");
    }

    #[test]
    fn test_registry_list_sources() {
        let registry = PriceSourceRegistry::default();
        let sources = registry.list_sources();

        assert!(sources.contains(&"yahoo"));
        assert!(sources.contains(&"coinbase"));

        // List should be sorted
        let mut sorted = sources.clone();
        sorted.sort_unstable();
        assert_eq!(sources, sorted);
    }

    #[test]
    fn test_resolve_mapping_simple() {
        let registry = PriceSourceRegistry::default();
        let mut mapping = HashMap::new();
        mapping.insert(
            "BTC".to_string(),
            CommodityMapping::Simple("BTC-USD".to_string()),
        );

        let attempts = registry.resolve_mapping("BTC", &mapping).unwrap();
        assert_eq!(attempts, vec![("yahoo".to_string(), "BTC-USD".to_string())]);
    }

    #[test]
    fn test_resolve_mapping_detailed() {
        let registry = PriceSourceRegistry::default();
        let mut mapping = HashMap::new();
        mapping.insert(
            "EUR".to_string(),
            CommodityMapping::Detailed(crate::config::DetailedMapping {
                source: SourceRef::Fallback(vec![
                    FallbackEntry::Name("ecb".to_string()),
                    FallbackEntry::Name("ratesapi".to_string()),
                ]),
                ticker: None,
                quote_currency: None,
            }),
        );

        let attempts = registry.resolve_mapping("EUR", &mapping).unwrap();
        assert_eq!(
            attempts,
            vec![
                ("ecb".to_string(), "EUR".to_string()),
                ("ratesapi".to_string(), "EUR".to_string()),
            ]
        );
    }

    /// Issue #966: by default, resolving a commodity that has no
    /// mapping (and no `--source` was provided at the call site) is an
    /// error rather than a silent dispatch to `default_source`. The
    /// error message points the user at every remediation path so they
    /// don't have to guess which one applies to their workflow.
    #[test]
    fn test_resolve_mapping_no_mapping_errors_by_default() {
        let registry = PriceSourceRegistry::default();
        let mapping = HashMap::new();

        let result = registry.resolve_mapping("AAPL", &mapping);
        let err = result.expect_err("default behavior must refuse unmapped symbols");
        let msg = err.to_string();
        assert!(
            msg.contains("AAPL"),
            "error must name the offending symbol: {msg}"
        );
        // Every remediation path must be discoverable from the error so
        // the user can pick whichever one fits their workflow.
        for needle in [
            "--source",
            "--mapping",
            "[price.mapping.AAPL]",
            "price:",
            "quote_currency:",
            "-f",
            "use_default_source",
        ] {
            assert!(msg.contains(needle), "error must mention `{needle}`: {msg}");
        }
    }

    /// `[price] use_default_source = true` restores the previous
    /// behavior — unmapped symbols dispatch to `default_source`.
    #[test]
    fn test_resolve_mapping_no_mapping_uses_default_when_opted_in() {
        let config = PriceConfig {
            use_default_source: Some(true),
            ..PriceConfig::default()
        };
        let registry = PriceSourceRegistry::new(&config);
        let mapping = HashMap::new();

        let attempts = registry
            .resolve_mapping("AAPL", &mapping)
            .expect("opt-in must allow default-source dispatch");
        assert_eq!(attempts, vec![("yahoo".to_string(), "AAPL".to_string())]);
    }

    /// Issue #963: a fallback chain whose entries carry per-source
    /// tickers must query each source with that source's own ticker.
    /// Previously all sources reused the first spec's ticker.
    #[test]
    fn test_resolve_mapping_fallback_uses_per_source_tickers() {
        let registry = PriceSourceRegistry::default();
        let mut mapping = HashMap::new();
        mapping.insert(
            "GBP".to_string(),
            CommodityMapping::Detailed(crate::config::DetailedMapping {
                source: SourceRef::Fallback(vec![
                    FallbackEntry::Detailed(FallbackDetail {
                        source: "ecbrates".to_string(),
                        ticker: Some("GBP-EUR".to_string()),
                    }),
                    FallbackEntry::Detailed(FallbackDetail {
                        source: "ecb".to_string(),
                        ticker: Some("GBP".to_string()),
                    }),
                ]),
                ticker: Some("GBP-EUR".to_string()),
                quote_currency: Some("EUR".to_string()),
            }),
        );

        let attempts = registry.resolve_mapping("GBP", &mapping).unwrap();
        assert_eq!(
            attempts,
            vec![
                ("ecbrates".to_string(), "GBP-EUR".to_string()),
                ("ecb".to_string(), "GBP".to_string()),
            ],
            "each fallback source must use its own ticker (issue #963)"
        );
    }

    /// Mixed-shape fallback: a bare-string entry inherits the parent
    /// ticker, while an object entry uses its own. Verifies the
    /// `FallbackEntry::Name(_)` arm of `resolve_mapping` falls through
    /// to `parent_ticker` correctly.
    #[test]
    fn test_resolve_mapping_fallback_mixed_entries_inherit_parent_ticker() {
        let registry = PriceSourceRegistry::default();
        let mut mapping = HashMap::new();
        mapping.insert(
            "BTC".to_string(),
            CommodityMapping::Detailed(crate::config::DetailedMapping {
                source: SourceRef::Fallback(vec![
                    FallbackEntry::Name("yahoo".to_string()),
                    FallbackEntry::Detailed(FallbackDetail {
                        source: "coingecko".to_string(),
                        ticker: Some("bitcoin".to_string()),
                    }),
                ]),
                ticker: Some("BTC-USD".to_string()),
                quote_currency: None,
            }),
        );

        let attempts = registry.resolve_mapping("BTC", &mapping).unwrap();
        assert_eq!(
            attempts,
            vec![
                // Bare-string entry inherits parent ticker.
                ("yahoo".to_string(), "BTC-USD".to_string()),
                // Detailed entry uses its own ticker.
                ("coingecko".to_string(), "bitcoin".to_string()),
            ]
        );
    }

    #[test]
    fn test_custom_config() {
        let config = PriceConfig {
            default_source: Some("coinbase".to_string()),
            timeout: Some(60),
            ..Default::default()
        };

        let registry = PriceSourceRegistry::new(&config);
        assert_eq!(registry.default_source_name(), "coinbase");
        assert_eq!(registry.timeout(), Duration::from_mins(1));
    }
}