ic-query-cli 0.25.8

//! Module: icrc::commands::options
//!
//! Responsibility: parse Clap matches into typed ICRC command options.
//! Does not own: command dispatch, report construction, or output.
//! Boundary: validates command arguments before dispatch constructs public requests.

#[cfg(test)]
use super::account::{
    icrc_account_transaction_cache_status_command, icrc_account_transaction_list_command,
    icrc_account_transaction_page_command, icrc_account_transaction_refresh_command,
    icrc_allowance_command, icrc_balance_command,
};
#[cfg(test)]
use super::ledger::{icrc_archives_command, icrc_transactions_command};
use super::{
    FOLLOW_ARCHIVES_ARG, FROM_CANISTER_ID_ARG, INDEX_CANISTER_ID_ARG, LEDGER_CANISTER_ID_ARG,
    LIMIT_ARG, MAX_PAGES_ARG, OWNER_PRINCIPAL_ARG, OWNER_SUBACCOUNT_ARG, PAGE_SIZE_ARG,
    PRINCIPAL_ARG, SORT_ARG, SPENDER_PRINCIPAL_ARG, SPENDER_SUBACCOUNT_ARG, START_ARG,
    SUBACCOUNT_ARG, format_from_matches, source_endpoint_from_matches,
};
use crate::cli::{
    clap::{required_string, required_typed, string_option, typed_option},
    common::OutputFormat,
};
#[cfg(test)]
use crate::{cli::clap::parse_matches_or_usage, icrc::IcrcCommandError};
use clap::ArgMatches;
#[cfg(test)]
use clap::Command as ClapCommand;
use ic_query::icrc::IcrcAccountTransactionSort;
#[cfg(test)]
use std::ffi::OsString;

///
/// IcrcLedgerOptions
///
/// Shared ledger target, output, and endpoint options for simple ICRC queries.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcLedgerOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) format: OutputFormat,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcLedgerOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            format: format_from_matches(matches),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I, command: fn() -> ClapCommand) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(command(), args).map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcBalanceOptions
///
/// Clap-parsed options for generic ICRC account balance queries.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcBalanceOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) account_owner: String,
    pub(in crate::icrc) subaccount_hex: Option<String>,
    pub(in crate::icrc) format: OutputFormat,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcBalanceOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            account_owner: required_string(matches, PRINCIPAL_ARG),
            subaccount_hex: string_option(matches, SUBACCOUNT_ARG),
            format: format_from_matches(matches),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_balance_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcAllowanceOptions
///
/// Clap-parsed options for generic ICRC allowance queries.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAllowanceOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) account_owner: String,
    pub(in crate::icrc) account_subaccount_hex: Option<String>,
    pub(in crate::icrc) spender_owner: String,
    pub(in crate::icrc) spender_subaccount_hex: Option<String>,
    pub(in crate::icrc) format: OutputFormat,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcAllowanceOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            account_owner: required_string(matches, OWNER_PRINCIPAL_ARG),
            account_subaccount_hex: string_option(matches, OWNER_SUBACCOUNT_ARG),
            spender_owner: required_string(matches, SPENDER_PRINCIPAL_ARG),
            spender_subaccount_hex: string_option(matches, SPENDER_SUBACCOUNT_ARG),
            format: format_from_matches(matches),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_allowance_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcAccountTargetOptions
///
/// Shared parsed ledger, account, subaccount, and endpoint identity for account-history commands.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAccountTargetOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) account_owner: String,
    pub(in crate::icrc) subaccount_hex: Option<String>,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcAccountTargetOptions {
    fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            account_owner: required_string(matches, PRINCIPAL_ARG),
            subaccount_hex: string_option(matches, SUBACCOUNT_ARG),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }
}

///
/// IcrcAccountTransactionPageOptions
///
/// Clap-parsed options for one live ICRC index account-history page.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAccountTransactionPageOptions {
    pub(in crate::icrc) target: IcrcAccountTargetOptions,
    pub(in crate::icrc) index_canister_id: Option<String>,
    pub(in crate::icrc) start: Option<String>,
    pub(in crate::icrc) limit: u32,
    pub(in crate::icrc) format: OutputFormat,
}

impl IcrcAccountTransactionPageOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            target: IcrcAccountTargetOptions::from_matches(matches),
            index_canister_id: string_option(matches, INDEX_CANISTER_ID_ARG),
            start: string_option(matches, START_ARG),
            limit: required_typed(matches, LIMIT_ARG),
            format: format_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_account_transaction_page_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcAccountTransactionListOptions
///
/// Clap-parsed options for a cache-only ICRC account transaction list.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAccountTransactionListOptions {
    pub(in crate::icrc) target: IcrcAccountTargetOptions,
    pub(in crate::icrc) limit: u32,
    pub(in crate::icrc) sort: IcrcAccountTransactionSort,
    pub(in crate::icrc) format: OutputFormat,
}

impl IcrcAccountTransactionListOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        let sort = match required_string(matches, SORT_ARG).as_str() {
            "newest" => IcrcAccountTransactionSort::Newest,
            "oldest" => IcrcAccountTransactionSort::Oldest,
            _ => unreachable!("Clap restricts account transaction sort values"),
        };
        Self {
            target: IcrcAccountTargetOptions::from_matches(matches),
            limit: required_typed(matches, LIMIT_ARG),
            sort,
            format: format_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_account_transaction_list_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcAccountTransactionRefreshOptions
///
/// Clap-parsed options for a forced complete ICRC account-history refresh.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAccountTransactionRefreshOptions {
    pub(in crate::icrc) target: IcrcAccountTargetOptions,
    pub(in crate::icrc) index_canister_id: Option<String>,
    pub(in crate::icrc) page_size: u32,
    pub(in crate::icrc) max_pages: Option<u32>,
    pub(in crate::icrc) format: OutputFormat,
}

impl IcrcAccountTransactionRefreshOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            target: IcrcAccountTargetOptions::from_matches(matches),
            index_canister_id: string_option(matches, INDEX_CANISTER_ID_ARG),
            page_size: required_typed(matches, PAGE_SIZE_ARG),
            max_pages: typed_option(matches, MAX_PAGES_ARG),
            format: format_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_account_transaction_refresh_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcAccountTransactionCacheOptions
///
/// Clap-parsed options identifying one local ICRC account-history cache.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcAccountTransactionCacheOptions {
    pub(in crate::icrc) target: IcrcAccountTargetOptions,
    pub(in crate::icrc) format: OutputFormat,
}

impl IcrcAccountTransactionCacheOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            target: IcrcAccountTargetOptions::from_matches(matches),
            format: format_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_account_transaction_cache_status_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcTransactionsOptions
///
/// Clap-parsed options for generic ICRC transaction history queries.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcTransactionsOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) start: u64,
    pub(in crate::icrc) limit: u32,
    pub(in crate::icrc) follow_archives: bool,
    pub(in crate::icrc) format: OutputFormat,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcTransactionsOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            start: required_typed(matches, START_ARG),
            limit: required_typed(matches, LIMIT_ARG),
            follow_archives: matches.get_flag(FOLLOW_ARCHIVES_ARG),
            format: format_from_matches(matches),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_transactions_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}

///
/// IcrcArchivesOptions
///
/// Clap-parsed options for generic ICRC-3 archive range queries.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub(in crate::icrc) struct IcrcArchivesOptions {
    pub(in crate::icrc) ledger_canister_id: String,
    pub(in crate::icrc) from_canister_id: Option<String>,
    pub(in crate::icrc) format: OutputFormat,
    pub(in crate::icrc) source_endpoint: String,
}

impl IcrcArchivesOptions {
    pub(super) fn from_matches(matches: &ArgMatches) -> Self {
        Self {
            ledger_canister_id: required_string(matches, LEDGER_CANISTER_ID_ARG),
            from_canister_id: string_option(matches, FROM_CANISTER_ID_ARG),
            format: format_from_matches(matches),
            source_endpoint: source_endpoint_from_matches(matches),
        }
    }

    #[cfg(test)]
    pub(super) fn parse<I>(args: I) -> Result<Self, IcrcCommandError>
    where
        I: IntoIterator<Item = OsString>,
    {
        let matches = parse_matches_or_usage(icrc_archives_command(), args)
            .map_err(IcrcCommandError::Usage)?;
        Ok(Self::from_matches(&matches))
    }
}