switchkit 0.1.0

use serde_json::Value;

use crate::error::Result;
use crate::model::{DeviceSnapshot, PowerAction, Relay};
use crate::target::{DeviceTarget, Vendor};

/// A vendor client. ONE implementation IS one vendor and serves MANY devices - methods take
/// a `&DeviceTarget`, so it is a shared, stateless client, NOT a per-device object. Blocking
/// I/O (cores use `ureq`); a consumer on an async runtime wraps calls in `spawn_blocking`.
pub trait SmartDevice: Send + Sync {
    fn vendor(&self) -> Vendor;

    /// Probe a target for THIS vendor's signature. `Ok(Some(snapshot))` = reachable and
    /// CONFIRMED this vendor; `Ok(None)` = reachable but not this vendor's signature; `Err` =
    /// no-answer / needs-auth / could-not-confirm. ONLY `Ok(Some)` classifies a host - for
    /// discovery, `Ok(None)` and `Err` are BOTH "not this vendor, try the next client", so a
    /// core impl that cannot perfectly distinguish reachable-non-match from no-answer (some
    /// vendor APIs conflate an HTTP 4xx with a transport failure) never causes a wrong guess:
    /// a host is only classified when SOME client returns `Ok(Some)`, else it is unrecognized.
    fn probe(&self, target: &DeviceTarget) -> Result<Option<DeviceSnapshot>>;

    /// One refresh. `Ok` = reachable reading; `Err` = unreadable (the consumer renders offline).
    fn status(&self, target: &DeviceTarget) -> Result<DeviceSnapshot>;

    /// Switch a relay. `channel` = None targets the sole/first relay. Returns the CONFIRMED
    /// relay state read back from the device (never optimistic).
    fn set_power(
        &self,
        target: &DeviceTarget,
        channel: Option<u8>,
        action: PowerAction,
    ) -> Result<Relay>;

    fn firmware_version(&self, target: &DeviceTarget) -> Result<Option<String>>;
    fn firmware_update(&self, target: &DeviceTarget, ota_url: Option<&str>) -> Result<()>;
    fn config_get(&self, target: &DeviceTarget, setting: &str) -> Result<Value>;
    fn config_set(&self, target: &DeviceTarget, setting: &str, value: &str) -> Result<Value>;
    fn backup(&self, target: &DeviceTarget) -> Result<Vec<u8>>;
    /// A raw vendor command / RPC (Tasmota console, Shelly RPC method). The CALLER classifies
    /// it via `guardrail::classify` first; the core just executes and returns the raw JSON.
    fn console(&self, target: &DeviceTarget, command: &str) -> Result<Value>;
}

/// A device found during discovery, already classified to a vendor.
#[derive(Debug, Clone)]
pub struct Discovered {
    pub host: String,
    pub vendor: Vendor,
    pub snapshot: DeviceSnapshot,
}