pvoutput-client 0.0.3

//! API response types.

use jiff::{
	Span, Timestamp,
	civil::{Date, Time},
};
use reqwest::header::HeaderMap;
use serde::{
	Deserialize, Deserializer,
	de::{DeserializeOwned, Error},
};

use crate::types::{Conditions, error::RateLimitError, regions::Region};

/// An API response along with current rate limit information.
#[derive(Debug, Clone)]
pub struct Response<T> {
	/// Data returned by the API.
	pub data: T,

	/// Rate limit information.
	pub rate_limit: RateLimit,
}

impl<T> Response<T> {
	pub(crate) const fn new(data: T, rate_limit: RateLimit) -> Self { Self { data, rate_limit } }
}

/// Rate limit information: the number of requests that can be made per hour, the remaining request count, and the time
/// at which the limit will be reset.
///
/// [PVOutput docs](https://pvoutput.org/help/api_specification.html#http-headers)
#[derive(Debug, Clone)]
pub struct RateLimit {
	/// The total request limit for the hour.
	pub limit: u16,

	/// The remaining requests for the hour.
	pub remaining: u16,

	/// The time at which the rate limit will be reset.
	pub reset: Timestamp,
}

impl RateLimit {
	/// The number of requests that have been used in this hourly block.
	///
	/// # Example
	/// ```rust
	/// use pvoutput_client::types::response::RateLimit;
	/// use jiff::Timestamp;
	/// let rate_limit = RateLimit { limit: 300, remaining: 100, reset: Timestamp::now() };
	/// assert_eq!(rate_limit.used(), 200);
	/// ```
	#[must_use]
	pub const fn used(&self) -> u16 {
		debug_assert!(self.remaining <= self.limit);
		self.limit - self.remaining
	}
}

impl TryFrom<&HeaderMap> for RateLimit {
	type Error = RateLimitError;

	fn try_from(value: &HeaderMap) -> Result<Self, Self::Error> {
		if let (Some(limit), Some(remaining), Some(reset)) = (
			value.get("X-Rate-Limit-Limit"),
			value.get("X-Rate-Limit-Remaining"),
			value.get("X-Rate-Limit-Reset"),
		) {
			let limit = limit.to_str()?.parse()?;
			let remaining = remaining.to_str()?.parse()?;
			let reset = Timestamp::from_second(reset.to_str()?.parse()?)?;

			debug_assert!(remaining <= limit);

			Ok(Self {
				limit,
				remaining,
				reset,
			})
		} else {
			Err(RateLimitError::MissingValues)
		}
	}
}

/// Information returned by the [`get_status`](crate::Client::get_status) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Status {
	/// The date of the status.
	pub date: Date,

	/// The time of the status.
	pub time: Time,

	/// Energy generation in watt-hours.
	pub energy_generation: f32,

	/// Power generation in watts.
	pub power_generation: f32,

	/// Energy consumption in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub energy_consumption: Option<f32>,

	/// Power consumption in watts.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub power_consumption: Option<f32>,

	/// Normalised output in kilowatts per kilowatt.
	// TODO: what does that even mean?
	pub normalised_output: f32,

	/// Temperature in degrees Celsius.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub temperature: Option<f32>,

	/// Voltage in volts.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub voltage: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 1.
	#[serde(default)]
	pub extended_value_1: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 2.
	#[serde(default)]
	pub extended_value_2: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 3.
	#[serde(default)]
	pub extended_value_3: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 4.
	#[serde(default)]
	pub extended_value_4: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 5.
	#[serde(default)]
	pub extended_value_5: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 6.
	#[serde(default)]
	pub extended_value_6: Option<f32>,
}

/// Historic status.
///
/// Returned by the [`get_status_history`](crate::Client::get_status_history) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct History {
	/// The date of the status.
	pub date: Date,

	/// The time of the status.
	pub time: Time,

	/// Energy generation in watt-hours.
	pub energy_generation: f32,

	/// Energy efficiency in kilowatt-hours per kilowatt-hour.
	pub energy_efficiency: f32,

	/// Instantaneous power generation in watts.
	pub instantaneous_power: f32,

	/// Average power generation in watts.
	pub average_power: f32,

	/// Normalised output in kilowatts per kilowatt.
	// TODO: what does that even mean?
	pub normalised_output: f32,

	/// Energy consumption in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub energy_consumption: Option<f32>,

	/// Power consumption in watts.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub power_consumption: Option<f32>,

	/// Temperature in degrees Celsius.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub temperature: Option<f32>,

	/// Voltage in volts.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub voltage: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 1.
	#[serde(default)]
	pub extended_value_1: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 2.
	#[serde(default)]
	pub extended_value_2: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 3.
	#[serde(default)]
	pub extended_value_3: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 4.
	#[serde(default)]
	pub extended_value_4: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 5.
	#[serde(default)]
	pub extended_value_5: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 6.
	#[serde(default)]
	pub extended_value_6: Option<f32>,
}

/// Daily status summary.
///
/// Returned by the [`get_status_daily`](crate::Client::get_status_daily) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct DailyStatus {
	/// Energy generation in watt-hours.
	pub energy_generation: f32,

	/// Power generation in watts.
	pub power_generation: f32,

	/// Peak power generation in watts.
	pub peak_power_generation: f32,

	/// Time at which the peak power generation occurred.
	pub peak_time: Time,

	/// Energy consumption data.
	#[serde(skip)]
	pub consumption: Option<DailyConsumption>,

	/// Temperature data.
	#[serde(skip)]
	pub temperatures: Option<DailyTemperatures>,
}

/// Daily power and energy consumption data.
///
/// Part of a [`DailyStatus`] response.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct DailyConsumption {
	/// Energy consumption in watt-hours.
	pub energy_consumption: Option<f32>,

	/// Power consumption in watts.
	pub power_consumption: Option<f32>,

	/// Standby power consumption(?)
	pub standby_power_consumption: Option<f32>,

	/// Standby power time(?)
	pub standby_power_time: Option<Time>,
}

/// Daily temperature data.
///
/// Part of a [`DailyStatus`] response.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct DailyTemperatures {
	/// Lowest recorded temperature in degrees Celsius.
	pub lowest_temperature: Option<f32>,

	/// Highest recorded temperature in degrees Celsius.
	pub highest_temperature: Option<f32>,

	/// Average temperature in degrees Celsius.
	pub average_temperature: Option<f32>,
}

/// System statistics.
///
/// Returned by the [`get_statistics`](crate::Client::get_statistics) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Statistics {
	/// Energy generated in watt-hours.
	pub energy_generated: u64,

	/// Energy exported in watt-hours.
	pub energy_exported: u64,

	/// Average energy generation in watt-hours.
	pub average_energy_generation: u32,

	/// Minimum energy generation in watt-hours.
	pub minimum_energy_generation: u32,

	/// Maximum energy generation in watt-hours.
	pub maximum_energy_generation: u32,

	/// Average efficiency in kilowatt-hours per kilowatt-hour.
	pub average_efficiency: f32,

	/// Number of outputs recorded.
	pub outputs: u32,

	/// Date from which these data were measured.
	pub date_from: Date,

	/// Date to which these data were measured.
	pub date_to: Date,

	/// The best daily energy efficiency in kilowatt-hours per kilowatt-hour.
	pub record_efficiency: f32,

	/// The date of the best daily energy efficiency.
	pub record_date: Date,

	/// Energy consumption data.
	#[serde(skip)]
	pub consumption: Option<ConsumptionStatistics>,

	/// Credit amount.
	#[serde(skip)]
	pub credit: Option<f32>,

	/// Debit amount.
	#[serde(skip)]
	pub debit: Option<f32>,
}

/// Consumption statistics.
/// All figures are in watt-hours.
///
/// Part of a [`Statistics`] response.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
pub struct ConsumptionStatistics {
	/// Energy consumed.
	pub energy_consumed: u64,

	/// Peak energy import.
	pub peak_energy_import: u32,

	/// Off-peak energy import.
	pub off_peak_energy_import: u32,

	/// Shoulder energy import.
	pub shoulder_energy_import: u32,

	/// High-shoulder energy import.
	pub high_shoulder_energy_import: u32,

	/// Average consumption.
	pub average_consumption: u32,

	/// Minimum consumption.
	pub minimum_consumption: u32,

	/// Maximum consumption.
	pub maximum_consumption: u32,
}

/// Common system information.
///
/// Returned by the [`get_system`](crate::Client::get_system) and
/// [`get_favourites`](crate::Client::get_favourites) endpoints.
#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default)]
pub struct System {
	/// System name.
	pub name: String,

	/// System size in watts.
	pub size: u64,

	/// Postcode or Zipcode.
	pub postcode: Option<String>,

	/// Number of panels in the primary array.
	pub panels: Option<u32>,

	/// Power of each panel in the primary array in watts.
	pub panel_power: Option<u32>,

	/// Panel brand.
	pub brand: Option<String>,

	/// Number of inverters.
	pub inverters: Option<u32>,

	/// Inverter power in watts.
	pub inverter_power: Option<u64>,

	/// Inverter brand.
	pub inverter_brand: Option<String>,

	/// Orientation of the primary solar array.
	pub orientation: Option<Orientation>,

	/// Tilt of the primary solar array.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub tilt: Option<f32>,

	/// System shade level.
	#[serde(deserialize_with = "nullable")]
	pub shade: Option<Shade>,

	/// System installation date.
	pub install_date: Option<Date>,

	/// System location latitude.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub latitude: Option<f32>,

	/// System location longitude.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub longitude: Option<f32>,
}

/// Full system information.
///
/// Returned by the [`get_system`](crate::Client::get_system) endpoint.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct FullSystem {
	/// Base system information.
	#[serde(skip)]
	pub system: System,

	/// Status update frequency in minutes.
	pub status_interval: Option<u32>,

	/// Number of panels in the secondary array.
	#[serde(default)]
	pub secondary_panels: Option<u32>,

	/// Power of each panel in the secondary array in watts.
	#[serde(default)]
	pub secondary_panel_power: Option<u32>,

	/// Orientation of the secondary solar array.
	#[serde(deserialize_with = "nullable", default)]
	pub secondary_orientation: Option<Orientation>,

	/// Tilt of the secondary solar array.
	#[serde(deserialize_with = "opt_nan_f32", default)]
	pub secondary_tilt: Option<f32>,

	/// Tariff information.
	#[serde(skip)]
	pub tariffs: Tariffs,

	/// Participating teams.
	#[serde(skip)]
	pub teams: Vec<u32>,

	/// Number of donations.
	#[serde(skip)]
	pub donations: u32,

	/// Extended data.
	#[serde(skip)]
	pub extended_data: Vec<Option<f32>>,

	/// Monthly estimates.
	#[serde(skip)]
	pub monthly_estimates: Vec<f32>,
}

impl From<System> for FullSystem {
	fn from(value: System) -> Self {
		Self {
			system: value,
			..Default::default()
		}
	}
}

/// System [tariff](https://www.energy.gov.au/solar/financial-benefits-solar/electricity-pricing-plans-and-tariffs)
/// information.
///
/// Part of a [`FullSystem`] response.
#[derive(Debug, Clone, Copy, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Tariffs {
	/// Export tariff in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub export: Option<f32>,

	/// Import peak tariff in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub import_peak: Option<f32>,

	/// Import off-peak tariff in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub import_off_peak: Option<f32>,

	/// Import shoulder tariff in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub import_shoulder: Option<f32>,

	/// Import high shoulder tariff in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub import_high_shoulder: Option<f32>,

	/// Daily import charge in cents.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub daily: Option<f32>,
}

/// Solar array panel orientation.
#[derive(Debug, Clone, Copy, Deserialize, Eq, PartialEq, Hash)]
pub enum Orientation {
	#[serde(rename = "N")]
	North,

	#[serde(rename = "NE")]
	NorthEast,

	#[serde(rename = "NW")]
	NorthWest,

	#[serde(rename = "W")]
	West,

	#[serde(rename = "E")]
	East,

	#[serde(rename = "EW")]
	EastWest,

	#[serde(rename = "S")]
	South,

	#[serde(rename = "SE")]
	SouthEast,

	#[serde(rename = "SW")]
	SouthWest,
}

/// Solar array shade level.
#[derive(Debug, Clone, Copy, Deserialize, Eq, PartialEq, Hash, PartialOrd, Ord)]
pub enum Shade {
	/// No shade.
	No,

	/// Low shade.
	Low,

	/// Medium shade.
	Medium,

	/// High shade.
	High,
}

/// Ladder ranking information.
///
/// Returned by the [`get_ladder`](crate::Client::get_ladder) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Ladder {
	/// Ranking date.
	pub date: Date,

	/// Generation rank.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub generation_rank: Option<u32>,

	/// Efficiency rank.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub efficiency_rank: Option<u32>,

	/// Average efficiency in kilowatt-hours per kilowatt-hour.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub efficiency: Option<f32>,

	/// Total number of outputs in days.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub total_outputs: Option<u32>,

	/// Date of the latest output considered by the ranking.
	pub last_output: Option<Date>,

	/// Total generation in watt-hours.
	#[serde(deserialize_with = "opt_nan_u64")]
	pub total_generation: Option<u64>,

	/// Total consumption in watt-hours.
	#[serde(deserialize_with = "opt_nan_u64")]
	pub total_consumption: Option<u64>,

	/// Maximum generation in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub max_generation: Option<u32>,

	/// Maximum consumption in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub max_consumption: Option<u32>,

	/// Age of this system in days.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub system_age: Option<u32>,
}

impl Ladder {
	/// Returns a URL for this system's generation rank on PVOutput.org's `ladder.jsp` page.
	#[must_use]
	pub fn generation_rank_url(&self) -> Option<String> {
		self
			.generation_rank
			.map(|rank| format!("https://pvoutput.org/ladder.jsp?rank={rank}&o=e&d=desc&filter=0&p={}", rank / 30))
	}
}

/// A daily output.
///
/// Returned by the [`get_outputs`](crate::Client::get_outputs) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Output {
	pub date: Date,

	/// Energy generated in watt-hours.
	pub energy_generation: u32,

	/// Energy efficiency in kilowatt-hours per kilowatt-hour.
	pub energy_efficiency: f32,

	/// Energy exported in watt-hours.
	pub energy_exported: u32,

	/// Energy used in watt-hours.
	pub energy_used: u32,

	/// Peak power generation in watts.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub peak_power: Option<u32>,

	/// Peak power generation time.
	#[serde(deserialize_with = "opt_nan_time")]
	pub peak_time: Option<Time>,

	/// Weather conditions.
	pub conditions: Conditions,

	/// Minimum temperature in degrees Celsius.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub min_temperature: Option<u32>,

	/// Maximum temperature in degrees Celsius.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub max_temperature: Option<u32>,

	/// Peak energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub peak_energy_import: Option<u32>,

	/// Off-peak energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub off_peak_energy_import: Option<u32>,

	/// Shoulder energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub shoulder_energy_import: Option<u32>,

	/// High-shoulder energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub high_shoulder_energy_import: Option<u32>,

	#[serde(skip)]
	/// Export data.
	pub export: Option<OutputExport>,

	/// Insolation in watt-hours.
	#[serde(skip)]
	pub insolation: Option<u32>,
}

/// Energy export information for an [`Output`].
#[derive(Clone, Debug, Deserialize, Default)]
pub struct OutputExport {
	/// Peak energy export in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub peak_energy_export: Option<u32>,

	/// Off-peak energy export in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub off_peak_energy_export: Option<u32>,

	/// Shoulder energy export in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub shoulder_energy_export: Option<u32>,

	/// High-shoulder energy export in watt-hours.
	#[serde(deserialize_with = "opt_nan_u32")]
	pub high_shoulder_energy_export: Option<u32>,
}

/// Aggregated output data.
///
/// Returned by the [`get_aggregate_outputs`](crate::Client::get_aggregate_outputs) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct AggregatedOutput {
	/// The month or year of the aggregated output.
	pub date: AggregateDate,

	/// Number of outputs.
	pub outputs: u32,

	/// Energy generated in watt-hours.
	pub energy_generation: u64,

	/// Energy efficiency in kilowatt-hours per kilowatt-hour.
	pub energy_efficiency: f32,

	/// Energy exported in watt-hours.
	pub energy_exported: u64,

	/// Energy used in watt-hours.
	pub energy_used: u64,

	/// Peak energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub peak_energy_import: Option<f32>,

	/// Off-peak energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub off_peak_energy_import: Option<f32>,

	/// Shoulder energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub shoulder_energy_import: Option<f32>,

	/// High-shoulder energy import in watt-hours.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub high_shoulder_energy_import: Option<f32>,

	#[serde(skip)]
	/// Export data.
	pub export: Option<OutputExport>,
}

/// A date range for an [`AggregatedOutput`].
///
/// Represents either a year or a year and month.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum AggregateDate {
	/// A year.
	Year(u16),

	/// A year and month.
	YearAndMonth(u16, u8),
}

impl<'de> Deserialize<'de> for AggregateDate {
	fn deserialize<D>(d: D) -> Result<Self, D::Error>
	where
		D: Deserializer<'de>,
	{
		let s = String::deserialize(d)?;
		Ok(if s.len() == 4 {
			Self::Year(s.parse().map_err(Error::custom)?)
		} else {
			let (year, month) = s.split_at_checked(4).ok_or_else(|| Error::custom(format!("invalid date: {s}")))?;
			Self::YearAndMonth(year.parse().map_err(Error::custom)?, month.parse().map_err(Error::custom)?)
		})
	}
}

impl AggregateDate {
	/// Converts the [`AggregateDate`] to an arbitrary jiff [`Date`].
	/// - A `Year` will be converted to a `Date` on the first day of the first month of that year.
	/// - A `YearAndMonth` will be converted to a `Date` on the first day of that month of that year.
	///
	/// # Errors
	/// Will return an error if the [`AggregateDate`] is not a valid, jiff-expressible year or year and month.
	/// For example, `Year(10_000)` will return an error, as years in jiff must be below 9999.
	///
	/// # Example
	/// ```rust
	/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
	/// use pvoutput_client::types::response::AggregateDate;
	/// use jiff::civil::Date;
	///
	/// assert_eq!(AggregateDate::Year(2025).as_arbitrary_date()?, Date::constant(2025, 1, 1));
	/// assert_eq!(AggregateDate::YearAndMonth(2025, 9).as_arbitrary_date()?, Date::constant(2025, 9, 1));
	/// # Ok(())
	/// # }
	/// ```
	pub fn as_arbitrary_date(&self) -> Result<Date, jiff::Error> {
		#[allow(clippy::cast_possible_wrap)]
		match self {
			Self::Year(year) => Date::new(*year as i16, 1, 1),
			Self::YearAndMonth(year, month) => Date::new(*year as i16, *month as i8, 1),
		}
	}

	/// Returns this [`AggregateDate`]'s year.
	///
	/// # Example
	/// ```rust
	/// use pvoutput_client::types::response::AggregateDate;
	/// assert_eq!(AggregateDate::Year(2025).year(), 2025);
	/// assert_eq!(AggregateDate::YearAndMonth(2025, 9).year(), 2025);
	/// ```
	#[allow(clippy::must_use_candidate)]
	pub const fn year(&self) -> u16 {
		match self {
			Self::Year(year) | Self::YearAndMonth(year, _) => *year,
		}
	}
}

/// Daily team output data.
///
/// Returned by the [`get_team_outputs`](crate::Client::get_team_outputs) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct TeamOutput {
	/// The date this output corresponds to.
	pub date: Date,

	/// Number of outputs.
	pub outputs: u32,

	/// Energy efficiency in kilowatt-hours per kilowatt-hour.
	pub energy_efficiency: f32,

	/// Total energy generated in watt-hours.
	pub energy_generation: u32,

	/// Average energy generation in watt-hours.
	pub average_energy_generation: u32,

	/// Total energy exported in watt-hours.
	pub energy_exported: u32,

	/// Total energy consumed in watt-hours.
	pub energy_consumed: u32,

	/// Average energy consumption in watt-hours.
	pub average_energy_consumption: u32,

	/// Total energy imported in watt-hours.
	pub energy_imported: u32,
}

/// One day of user-defined [extended data](https://pvoutput.org/help/extended_data.html).
///
/// Returned by the [`get_extended`](crate::Client::get_extended) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct ExtendedData {
	/// The date for these data.
	pub date: Date,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 1.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_1: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 2.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_2: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 3.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_3: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 4.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_4: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 5.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_5: Option<f32>,

	/// User-defined [extended data](https://pvoutput.org/help/extended_data.html) parameter 6.
	#[serde(default, deserialize_with = "opt_nan_f32")]
	pub extended_value_6: Option<f32>,
}

/// A favourite system.
///
/// Returned by the [`get_favourites`](crate::Client::get_favourites) endpoint.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct FavouriteSystem {
	/// System information.
	#[serde(skip)]
	pub system: System,

	/// System ID.
	pub id: u32,

	/// Status interval in minutes.
	pub status_interval: u32,
}

impl FavouriteSystem {
	#[must_use]
	pub(crate) const fn new(system: System, system_id: u32, status_interval: u32) -> Self {
		Self {
			system,
			id: system_id,
			status_interval,
		}
	}
}

/// Insolation data.
///
/// Returned by the [`get_insolation`](crate::Client::get_insolation) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Insolation {
	/// Time for the calculated insolation data.
	pub time: Time,

	/// Power in watts.
	pub power: u32,

	/// Energy in watt-hours.
	pub energy: u32,
}

/// A search result.
///
/// Returned by the [`search`](crate::Client::search) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct SearchResult {
	/// Name.
	pub name: String,

	/// Size in watts.
	pub size: u64,

	/// Postcode.
	pub postcode: String,

	/// Orientation.
	pub orientation: Orientation,

	/// Number of outputs.
	pub outputs: u32,

	/// How long ago the last output was recorded, or `None` if the system has no outputs.
	#[serde(deserialize_with = "search_span")]
	pub last_output: Option<Span>,

	/// System ID.
	pub system_id: u32,

	/// Panel brand.
	pub panel: Option<String>,

	/// Inverter brand.
	pub inverter: Option<String>,

	/// Distance in kilometres from the location provided in the search query.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub distance: Option<f32>,

	/// Latitude.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub latitude: Option<f32>,

	/// Longitude.
	#[serde(deserialize_with = "opt_nan_f32")]
	pub longitude: Option<f32>,
}

/// A [team](https://pvoutput.org/help/teams.html).
///
/// Returned by the [`get_team`](crate::Client::get_team) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Team {
	/// Team name.
	pub name: String,

	/// Team system size in watts.
	pub size: u64,

	/// Average system size in watts.
	pub average_size: u32,

	/// Number of systems in this team.
	pub systems: u32,

	/// Total energy generated in watt-hours.
	pub energy_generation: u64,

	/// Number of outputs recorded.
	pub outputs: u32,

	/// Average energy generation in watt-hours.
	pub average_energy_generation: u32,

	/// Type of team.
	pub team_type: TeamType,

	/// Team description.
	pub description: String,

	/// Team creation date.
	pub created: Date,
}

/// A category for a [`Team`].
#[derive(Debug, Clone, Deserialize)]
pub enum TeamType {
	/// A team for a particular panel brand.
	Panel,

	/// A team for a particular inverter brand.
	Inverter,

	/// A team for a geographic region or location.
	Geographic,

	/// A team for a particular installer.
	Installer,

	/// A team for a specific piece of software.
	Software,

	/// A general team.
	General,
}

/// Supply and demand information for a particular region.
///
/// Returned by the [`get_supply`](crate::Client::get_supply) endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct Supply {
	/// Timestamp for the aggregated data.
	pub timestamp: Timestamp,

	/// The region these data are for.
	pub region: Region,

	/// Utilisation as a percentage.
	pub utilisation: f32,

	/// Total power output in watts.
	pub power_output: u64,

	/// Total power input in watts.
	pub power_input: u64,

	/// Average power output in watts.
	pub average_power_output: u32,

	/// Average power input in watts.
	pub average_power_input: u32,

	/// Average net power in watts.
	pub average_net_power: i32,

	/// Systems outputting power(?).
	pub systems_out: u32,

	/// Systems consuming power(?).
	pub systems_in: u32,

	/// Total size of this region's systems in watts.
	pub total_size: u64,

	/// Average size of this region's systems in watts.
	#[serde(deserialize_with = "opt_negative_u32")]
	pub average_size: Option<u32>,
}

/// Status information for a status uploaded to a batch status endpoint.
///
/// Returned by the [`crate::Client::add_batch_status`] and [`crate::Client::add_batch_status_net`] endpoints.
#[derive(Clone, Debug, Deserialize)]
pub struct BatchStatusReport {
	/// The date for this status.
	pub date: Date,

	/// The time for this status.
	pub time: Time,

	/// Whether this status was successful.
	#[serde(deserialize_with = "bool_int")]
	pub success: bool,
}

// custom deserialiser functions

/// Deserialises an `f32`, treating `NaN` as `None`.
pub(crate) fn opt_nan_f32<'de, D>(d: D) -> Result<Option<f32>, D::Error>
where
	D: Deserializer<'de>,
{
	Option::<f32>::deserialize(d).map(|r| r.filter(|f| !f.is_nan()))
}

/// Deserialises a `u32`, treating `NaN` as `None`.
pub(crate) fn opt_nan_u32<'de, D>(d: D) -> Result<Option<u32>, D::Error>
where
	D: Deserializer<'de>,
{
	#[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
	Option::<f32>::deserialize(d).map(|r| r.filter(|f| !f.is_nan()).map(|f| f as u32))
}

/// Deserialises a `u64`, treating `NaN` as `None`.
pub(crate) fn opt_nan_u64<'de, D>(d: D) -> Result<Option<u64>, D::Error>
where
	D: Deserializer<'de>,
{
	#[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
	Option::<f64>::deserialize(d).map(|r| r.filter(|f| !f.is_nan()).map(|f| f as u64))
}

/// Deserialises a `Time`, treating `NaN` as `None`.
pub(crate) fn opt_nan_time<'de, D>(d: D) -> Result<Option<Time>, D::Error>
where
	D: Deserializer<'de>,
{
	match String::deserialize(d)?.as_str() {
		"NaN" => Ok(None),
		s => Ok(Some(s.parse().map_err(Error::custom)?)),
	}
}

/// Deserialises a `u32`, treating `-1` as `None`.
pub(crate) fn opt_negative_u32<'de, D>(d: D) -> Result<Option<u32>, D::Error>
where
	D: Deserializer<'de>,
{
	#[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
	match i64::deserialize(d)? {
		-1 => Ok(None),
		n => Ok(Some(u32::try_from(n).map_err(Error::custom)?)),
	}
}

/// Deserialises a nullable value, treating `null` as `None`.
fn nullable<'de, D, T>(d: D) -> Result<Option<T>, D::Error>
where
	D: Deserializer<'de>,
	T: DeserializeOwned,
{
	// h/t https://stackoverflow.com/a/56384732
	#[derive(Deserialize)]
	#[serde(untagged)]
	enum Maybe<T> {
		Some(Option<T>),
		OtherString(String),
	}

	match Deserialize::deserialize(d)? {
		Maybe::Some(s) => Ok(s),
		Maybe::OtherString(s) if s == "null" => Ok(None),
		Maybe::OtherString(s) => Err(Error::custom(format!("invalid value: {s}"))),
	}
}

/// Parses the following:
/// - No Output -> `None`
/// - Today -> `Span::new()`
/// - Yesterday -> `Span::new().days(1)`
/// - n days ago -> `Span::new().days(n)`
/// - n weeks ago -> `Span::new().weeks(n)`
fn search_span<'de, D>(d: D) -> Result<Option<Span>, D::Error>
where
	D: Deserializer<'de>,
{
	Ok(match String::deserialize(d)?.as_str() {
		"No Outputs" => None,
		"Today" => Some(Span::new()),
		"Yesterday" => Some(Span::new().days(1)),
		days if days.ends_with("days ago") => {
			Some(Span::new().days(days.split(' ').next().unwrap().parse::<i64>().map_err(Error::custom)?))
		}
		weeks if weeks.ends_with("weeks ago") || weeks.ends_with("week ago") => {
			Some(Span::new().weeks(weeks.split(' ').next().unwrap().parse::<i64>().map_err(Error::custom)?))
		}
		other => return Err(Error::custom(format!("Couldn't parse {other} as Span!"))),
	})
}

/// Deserialises a boolean from an integer.
fn bool_int<'de, D>(d: D) -> Result<bool, D::Error>
where
	D: Deserializer<'de>,
{
	Ok(match u8::deserialize(d)? {
		0 => false,
		1 => true,
		_ => return Err(Error::custom("invalid value")),
	})
}