// file: crates/ksp-wallet-lib/src/view.rs
// version: 5

/// Authorized VIEW capability handle.
///
/// VIEW exposes protected metadata and retains only the authenticated metadata capability required for self-service password rotation. It never owns the
/// Solana secret, OWNER administration material or metadata-write authority.
pub struct WalletView {
    info: crate::WalletInfo,
    state: crate::ViewState,
}

impl WalletView {
    /// Builds `WalletView` from unlocked.
    pub(crate) fn from_unlocked(info: crate::WalletInfo, state: crate::ViewState) -> Self {
        return Self { info, state };
    }

    /// Returns the native Wallet format version backing this authorized handle.
    #[must_use]
    pub const fn format_version(&self) -> u32 {
        return self.info.format_version();
    }

    /// Returns the authorization capability represented by this handle.
    #[must_use]
    pub const fn capability(&self) -> crate::WalletCapability {
        return crate::WalletCapability::View;
    }

    /// Returns the authorized Solana public key.
    #[must_use]
    pub const fn pubkey(&self) -> &ksp_core_lib::Pubkey {
        return self.info.pubkey();
    }

    /// Returns the protected internal alias, when present.
    #[must_use]
    pub fn alias(&self) -> std::option::Option<&str> {
        return self.info.alias();
    }

    /// Returns the protected notes.
    #[must_use]
    pub fn notes(&self) -> &[crate::WalletNote] {
        return self.info.notes();
    }

    /// Returns the complete safe metadata projection for this VIEW capability.
    #[must_use]
    pub fn info(&self) -> &crate::WalletInfo {
        ksp_logging_lib::trace!(
            target: crate::TRACING_TARGET,
            operation = "wallet_info_projection",
            capability = "view",
            "wallet metadata projection requested"
        );
        return &self.info;
    }

    /// Rotates only this VIEW credential and atomically replaces the existing wallet file.
    ///
    /// The same metadata content key and OWNER-signed VIEW slot identifier are retained. Alias, notes, Pubkey, OWNER material, activation state and the
    /// Solana secret remain unchanged.
    pub async fn rotate_view_password(
        &mut self,
        destination: impl std::convert::AsRef<std::path::Path>,
        new_password: crate::ViewPassword,
    ) -> ksp_core_lib::Result<()> {
        let envelope = match self.state.stage_view_password_rotation(new_password).await {
            std::result::Result::Ok(value) => value,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let persist_result = self.state.persist_staged(destination.as_ref().to_path_buf(), &envelope).await;
        if let std::result::Result::Err(error) = persist_result {
            return std::result::Result::Err(error);
        }
        if let std::result::Result::Err(error) = self.state.apply_envelope(envelope) {
            return std::result::Result::Err(error);
        }
        ksp_logging_lib::debug!(
            target: crate::TRACING_TARGET,
            operation = "wallet_rotate_view_password",
            capability = "view",
            "wallet VIEW password self-rotated"
        );
        return std::result::Result::Ok(());
    }

    /// Serializes the unchanged locked native Wallet in its current V1 or V2 wire format.
    pub fn to_native_bytes(&self) -> ksp_core_lib::Result<std::vec::Vec<u8>> {
        return self.state.native_bytes();
    }

    /// Serializes a V1 handle as its historical JSON document.
    ///
    /// V2 handles return a format error instead of being converted implicitly.
    pub fn to_json_bytes(&self) -> ksp_core_lib::Result<std::vec::Vec<u8>> {
        return self.state.json_bytes_v1();
    }
}

impl std::fmt::Debug for WalletView {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter.debug_struct("WalletView").field("info", &self.info).field("unlocked_state", &"<redacted>").finish();
    }
}