payrix 0.3.0

//! Transaction Hold Workflow
//!
//! This module implements a complete workflow for handling transaction holds from
//! the risk department. It follows a typestate pattern for compile-time state safety.
//!
//! # Workflow Overview
//!
//! ```text
//! OnHold ──notify_merchant()──▶ AwaitingResponse
//!                                     │
//!                         receive_decision(Valid/Fraudulent)
//!                                     ▼
//!                             DecisionReceived
//!                                     │
//!                             submit_decision()
//!                                     ▼
//!                                Submitted
//!                                     │
//!                             check_resolution()
//!                                     ▼
//!                                Resolved
//! ```
//!
//! # Example
//!
//! ```rust,no_run
//! use payrix::workflows::hold_handling::{
//!     HoldWorkflowConfig, TypedHold, OnHold, MerchantDecision,
//!     notify_merchant, receive_decision, submit_decision,
//! };
//! use payrix::types::Hold;
//!
//! async fn handle_hold(hold: Hold, config: &HoldWorkflowConfig) -> payrix::Result<()> {
//!     // Wrap raw hold in typestate
//!     let typed_hold = TypedHold::<OnHold>::new(hold);
//!
//!     // Notify merchant and transition to AwaitingResponse
//!     let awaiting = notify_merchant(
//!         typed_hold,
//!         config,
//!         "merchant@example.com",
//!         "Acme Corp"
//!     ).await?;
//!
//!     // Later, when merchant replies...
//!     let with_decision = receive_decision(
//!         awaiting,
//!         MerchantDecision::Valid,
//!         "Transaction verified by customer".to_string(),
//!         vec![],
//!     )?;
//!
//!     // Submit decision to Payrix
//!     // let submitted = submit_decision(with_decision, &client, config).await?;
//!
//!     Ok(())
//! }
//! ```

use std::fmt;
use std::marker::PhantomData;
use std::time::Duration;

use chrono::{DateTime, Utc};

use crate::types::Hold;

// =============================================================================
// Configuration Types
// =============================================================================

/// Configuration for the hold workflow.
#[derive(Debug, Clone)]
pub struct HoldWorkflowConfig {
    /// Email configuration for notifications and reply monitoring.
    pub email: HoldEmailConfig,
    /// Notification template configuration.
    pub notification: HoldNotificationConfig,
    /// Timeout configuration for workflow stages.
    pub timeouts: HoldTimeoutConfig,
}

impl Default for HoldWorkflowConfig {
    fn default() -> Self {
        Self {
            email: HoldEmailConfig::default(),
            notification: HoldNotificationConfig::default(),
            timeouts: HoldTimeoutConfig::default(),
        }
    }
}

/// Email configuration for the hold workflow.
#[derive(Debug, Clone)]
pub struct HoldEmailConfig {
    /// Domain for the reply-to address (e.g., "holds.yourcompany.com").
    pub domain: String,
    /// From address for notification emails.
    pub from_address: String,
    /// Prefix for reply-to address (e.g., "hold+" for "hold+{workflow_id}@domain").
    pub reply_to_prefix: String,
    /// Interval for polling IMAP for replies.
    pub poll_interval: Duration,
    /// IMAP configuration for reading replies.
    pub imap: ImapConfig,
    /// SMTP configuration for sending notifications.
    pub smtp: SmtpConfig,
}

impl Default for HoldEmailConfig {
    fn default() -> Self {
        Self {
            domain: "holds.example.com".to_string(),
            from_address: "noreply@example.com".to_string(),
            reply_to_prefix: "hold+".to_string(),
            poll_interval: Duration::from_secs(30),
            imap: ImapConfig::default(),
            smtp: SmtpConfig::default(),
        }
    }
}

/// IMAP configuration for reading email replies.
#[derive(Debug, Clone)]
pub struct ImapConfig {
    /// IMAP server hostname.
    pub host: String,
    /// IMAP server port.
    pub port: u16,
    /// Use TLS for connection.
    pub use_tls: bool,
    /// Username for authentication.
    pub username: String,
    /// Password for authentication.
    pub password: String,
    /// Mailbox to monitor (default: "INBOX").
    pub mailbox: String,
}

impl Default for ImapConfig {
    fn default() -> Self {
        Self {
            host: "imap.example.com".to_string(),
            port: 993,
            use_tls: true,
            username: String::new(),
            password: String::new(),
            mailbox: "INBOX".to_string(),
        }
    }
}

/// SMTP configuration for sending notification emails.
#[derive(Debug, Clone)]
pub struct SmtpConfig {
    /// SMTP server hostname.
    pub host: String,
    /// SMTP server port.
    pub port: u16,
    /// Use TLS for connection.
    pub use_tls: bool,
    /// Username for authentication.
    pub username: String,
    /// Password for authentication.
    pub password: String,
}

impl Default for SmtpConfig {
    fn default() -> Self {
        Self {
            host: "smtp.example.com".to_string(),
            port: 587,
            use_tls: true,
            username: String::new(),
            password: String::new(),
        }
    }
}

/// Notification template configuration.
#[derive(Debug, Clone)]
pub struct HoldNotificationConfig {
    /// Subject line template. Supports: {hold_id}, {workflow_id}
    pub subject_template: String,
    /// Body template. Supports: {hold_id}, {workflow_id}, {transaction_id},
    /// {amount}, {merchant_name}, {response_instructions}
    pub body_template: String,
    /// Instructions for how merchant should respond.
    pub response_instructions: String,
}

impl Default for HoldNotificationConfig {
    fn default() -> Self {
        Self {
            subject_template: "Action Required: Transaction Hold #{hold_id}".to_string(),
            body_template: r#"Dear {merchant_name},

A transaction has been placed on hold and requires your attention.

Hold ID: {hold_id}
Transaction ID: {transaction_id}
Amount: {amount}

{response_instructions}

Please respond to this email with your decision.

Best regards,
Risk Management Team"#
                .to_string(),
            response_instructions: r#"Please reply to this email with one of the following:
- "VALID" if this transaction is legitimate
- "FRAUDULENT" if this transaction is unauthorized

You may attach any supporting documentation to your reply."#
                .to_string(),
        }
    }
}

/// Timeout configuration for workflow stages.
#[derive(Debug, Clone)]
pub struct HoldTimeoutConfig {
    /// Time after initial notification before sending reminder.
    pub reminder_after: Duration,
    /// Time after initial notification before escalation.
    pub escalation_after: Duration,
    /// Maximum time to wait for merchant response.
    pub max_response_time: Duration,
}

impl Default for HoldTimeoutConfig {
    fn default() -> Self {
        Self {
            reminder_after: Duration::from_secs(24 * 60 * 60),      // 24 hours
            escalation_after: Duration::from_secs(72 * 60 * 60),   // 72 hours
            max_response_time: Duration::from_secs(168 * 60 * 60), // 7 days
        }
    }
}

/// Builder for HoldWorkflowConfig.
#[derive(Debug, Default)]
pub struct HoldWorkflowConfigBuilder {
    config: HoldWorkflowConfig,
}

impl HoldWorkflowConfigBuilder {
    /// Create a new builder with default configuration.
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the email domain.
    pub fn domain(mut self, domain: impl Into<String>) -> Self {
        self.config.email.domain = domain.into();
        self
    }

    /// Set the from address.
    pub fn from_address(mut self, address: impl Into<String>) -> Self {
        self.config.email.from_address = address.into();
        self
    }

    /// Set IMAP configuration.
    pub fn imap(mut self, config: ImapConfig) -> Self {
        self.config.email.imap = config;
        self
    }

    /// Set SMTP configuration.
    pub fn smtp(mut self, config: SmtpConfig) -> Self {
        self.config.email.smtp = config;
        self
    }

    /// Set reminder timeout.
    pub fn reminder_after(mut self, duration: Duration) -> Self {
        self.config.timeouts.reminder_after = duration;
        self
    }

    /// Set escalation timeout.
    pub fn escalation_after(mut self, duration: Duration) -> Self {
        self.config.timeouts.escalation_after = duration;
        self
    }

    /// Build the configuration.
    pub fn build(self) -> HoldWorkflowConfig {
        self.config
    }
}

// =============================================================================
// Error Types
// =============================================================================

/// Errors that can occur during hold workflow processing.
#[derive(Debug)]
pub enum HoldError {
    /// Hold not found.
    NotFound(String),
    /// Hold is in an invalid state for the requested operation.
    InvalidState {
        /// The hold ID.
        hold_id: String,
        /// The current state of the hold.
        current_state: String,
        /// The expected state for this operation.
        expected_state: String,
    },
    /// Hold has already been released.
    AlreadyReleased(String),
    /// Invalid decision provided.
    InvalidDecision(String),
    /// Document upload failed.
    DocumentUpload(String),
    /// Email notification failed.
    EmailNotification(String),
    /// Email parsing failed.
    EmailParsing(String),
    /// Configuration error.
    Configuration(String),
    /// Payrix API error.
    Api(crate::error::Error),
    /// Generic workflow error.
    Workflow(String),
}

impl fmt::Display for HoldError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::NotFound(id) => write!(f, "Hold not found: {}", id),
            Self::InvalidState {
                hold_id,
                current_state,
                expected_state,
            } => write!(
                f,
                "Hold {} is in state '{}', expected '{}'",
                hold_id, current_state, expected_state
            ),
            Self::AlreadyReleased(id) => write!(f, "Hold {} has already been released", id),
            Self::InvalidDecision(msg) => write!(f, "Invalid decision: {}", msg),
            Self::DocumentUpload(msg) => write!(f, "Document upload failed: {}", msg),
            Self::EmailNotification(msg) => write!(f, "Email notification failed: {}", msg),
            Self::EmailParsing(msg) => write!(f, "Email parsing failed: {}", msg),
            Self::Configuration(msg) => write!(f, "Configuration error: {}", msg),
            Self::Api(e) => write!(f, "Payrix API error: {}", e),
            Self::Workflow(msg) => write!(f, "Workflow error: {}", msg),
        }
    }
}

impl std::error::Error for HoldError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Api(e) => Some(e),
            _ => None,
        }
    }
}

impl From<crate::error::Error> for HoldError {
    fn from(err: crate::error::Error) -> Self {
        Self::Api(err)
    }
}

impl From<HoldError> for crate::error::Error {
    fn from(err: HoldError) -> Self {
        match err {
            HoldError::Api(e) => e,
            other => crate::error::Error::Workflow(other.to_string()),
        }
    }
}

/// Result type alias for hold workflow operations.
pub type HoldResult<T> = Result<T, HoldError>;

// =============================================================================
// State Machine Types
// =============================================================================

/// Sealed trait to prevent external implementations of HoldState.
mod private {
    pub trait Sealed {}
}

/// Marker trait for hold workflow states.
///
/// This trait is sealed and cannot be implemented outside this crate.
pub trait HoldState: private::Sealed {
    /// Name of this state for display/logging.
    fn state_name() -> &'static str;
}

/// Initial state: Hold has been detected but merchant not yet notified.
#[derive(Debug, Clone, Default)]
pub struct OnHold;

impl private::Sealed for OnHold {}
impl HoldState for OnHold {
    fn state_name() -> &'static str {
        "OnHold"
    }
}

/// Merchant has been notified, awaiting their response.
#[derive(Debug, Clone, Default)]
pub struct AwaitingResponse;

impl private::Sealed for AwaitingResponse {}
impl HoldState for AwaitingResponse {
    fn state_name() -> &'static str {
        "AwaitingResponse"
    }
}

/// Merchant has responded with a decision (Valid or Fraudulent).
#[derive(Debug, Clone, Default)]
pub struct DecisionReceived;

impl private::Sealed for DecisionReceived {}
impl HoldState for DecisionReceived {
    fn state_name() -> &'static str {
        "DecisionReceived"
    }
}

/// Decision has been submitted to Payrix.
#[derive(Debug, Clone, Default)]
pub struct Submitted;

impl private::Sealed for Submitted {}
impl HoldState for Submitted {
    fn state_name() -> &'static str {
        "Submitted"
    }
}

/// Workflow is complete - hold has been resolved.
#[derive(Debug, Clone, Default)]
pub struct Resolved;

impl private::Sealed for Resolved {}
impl HoldState for Resolved {
    fn state_name() -> &'static str {
        "Resolved"
    }
}

// =============================================================================
// TypedHold - State Machine Wrapper
// =============================================================================

/// A hold wrapped with typestate for compile-time workflow enforcement.
///
/// This struct wraps a [`Hold`] and tracks workflow state at the type level,
/// ensuring that operations can only be performed in the correct order.
#[derive(Debug, Clone)]
pub struct TypedHold<S: HoldState> {
    /// The underlying hold data.
    inner: Hold,
    /// Unique workflow instance ID for tracking.
    workflow_id: String,
    /// Timestamp when the hold entered the current state.
    state_entered_at: DateTime<Utc>,
    /// Timestamp when merchant was notified (if applicable).
    pub notified_at: Option<DateTime<Utc>>,
    /// The merchant's decision (if received).
    pub decision: Option<MerchantDecision>,
    /// Note from the merchant explaining their decision.
    pub merchant_note: Option<String>,
    /// Documents attached by the merchant.
    pub documents: Vec<HoldDocument>,
    /// Phantom data for state type.
    _state: PhantomData<S>,
}

impl<S: HoldState> TypedHold<S> {
    /// Get the hold ID.
    pub fn id(&self) -> &crate::types::PayrixId {
        &self.inner.id
    }

    /// Get the workflow instance ID.
    pub fn workflow_id(&self) -> &str {
        &self.workflow_id
    }

    /// Get the transaction ID associated with this hold.
    pub fn transaction_id(&self) -> Option<&crate::types::PayrixId> {
        self.inner.txn.as_ref()
    }

    /// Get the entity ID associated with this hold.
    pub fn entity_id(&self) -> Option<&crate::types::PayrixId> {
        self.inner.entity.as_ref()
    }

    /// Get the current state name.
    pub fn state_name(&self) -> &'static str {
        S::state_name()
    }

    /// Get when this state was entered.
    pub fn state_entered_at(&self) -> DateTime<Utc> {
        self.state_entered_at
    }

    /// Get a reference to the inner Hold.
    pub fn inner(&self) -> &Hold {
        &self.inner
    }

    /// Check if the hold has been released.
    pub fn is_released(&self) -> bool {
        self.inner.released.is_some()
    }

    /// Transition to a new state (internal use only).
    pub(crate) fn transition<T: HoldState + Default>(self) -> TypedHold<T> {
        TypedHold {
            inner: self.inner,
            workflow_id: self.workflow_id,
            state_entered_at: Utc::now(),
            notified_at: self.notified_at,
            decision: self.decision,
            merchant_note: self.merchant_note,
            documents: self.documents,
            _state: PhantomData,
        }
    }
}

impl TypedHold<OnHold> {
    /// Create a new TypedHold from a raw Hold.
    ///
    /// Generates a unique workflow ID for tracking this workflow instance.
    pub fn new(hold: Hold) -> Self {
        Self {
            inner: hold,
            workflow_id: generate_workflow_id(),
            state_entered_at: Utc::now(),
            notified_at: None,
            decision: None,
            merchant_note: None,
            documents: Vec::new(),
            _state: PhantomData,
        }
    }

    /// Create a TypedHold with a specific workflow ID.
    ///
    /// Useful for resuming a workflow from persistence.
    pub fn with_workflow_id(hold: Hold, workflow_id: String) -> Self {
        Self {
            inner: hold,
            workflow_id,
            state_entered_at: Utc::now(),
            notified_at: None,
            decision: None,
            merchant_note: None,
            documents: Vec::new(),
            _state: PhantomData,
        }
    }
}

impl TypedHold<AwaitingResponse> {
    /// Check if the response deadline has passed.
    pub fn is_expired(&self, config: &HoldWorkflowConfig) -> bool {
        if let Some(notified) = self.notified_at {
            let elapsed = Utc::now().signed_duration_since(notified);
            elapsed > chrono::Duration::from_std(config.timeouts.max_response_time).unwrap()
        } else {
            false
        }
    }

    /// Check if a reminder should be sent.
    pub fn should_send_reminder(&self, config: &HoldWorkflowConfig) -> bool {
        if let Some(notified) = self.notified_at {
            let elapsed = Utc::now().signed_duration_since(notified);
            elapsed > chrono::Duration::from_std(config.timeouts.reminder_after).unwrap()
        } else {
            false
        }
    }
}

/// A document attached by the merchant.
#[derive(Debug, Clone)]
pub struct HoldDocument {
    /// Original filename.
    pub filename: String,
    /// MIME type of the document.
    pub content_type: String,
    /// Document content.
    pub data: Vec<u8>,
}

/// The merchant's decision about a held transaction.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MerchantDecision {
    /// Transaction is valid/legitimate - request release.
    Valid,
    /// Transaction is fraudulent - acknowledge fraud.
    Fraudulent,
}

impl fmt::Display for MerchantDecision {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Valid => write!(f, "Valid"),
            Self::Fraudulent => write!(f, "Fraudulent"),
        }
    }
}

/// Generate a unique workflow ID.
fn generate_workflow_id() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_millis();
    format!("wf_{}", timestamp)
}

// =============================================================================
// HoldWorkflow Enum - Public API
// =============================================================================

/// Represents a hold at any stage of the workflow.
///
/// This enum provides a way to work with holds without knowing the exact
/// state at compile time. Useful for serialization and dynamic dispatch.
#[derive(Debug, Clone)]
pub enum HoldWorkflow {
    /// Hold detected, merchant not yet notified.
    OnHold(TypedHold<OnHold>),
    /// Notification sent, awaiting merchant response.
    AwaitingResponse(TypedHold<AwaitingResponse>),
    /// Merchant responded with decision.
    DecisionReceived(TypedHold<DecisionReceived>),
    /// Decision submitted to Payrix.
    Submitted(TypedHold<Submitted>),
    /// Workflow complete.
    Resolved(TypedHold<Resolved>),
}

impl HoldWorkflow {
    /// Create a new workflow from a raw Hold.
    pub fn new(hold: Hold) -> Self {
        Self::OnHold(TypedHold::new(hold))
    }

    /// Get the hold ID.
    pub fn id(&self) -> &crate::types::PayrixId {
        match self {
            Self::OnHold(h) => h.id(),
            Self::AwaitingResponse(h) => h.id(),
            Self::DecisionReceived(h) => h.id(),
            Self::Submitted(h) => h.id(),
            Self::Resolved(h) => h.id(),
        }
    }

    /// Get the workflow ID.
    pub fn workflow_id(&self) -> &str {
        match self {
            Self::OnHold(h) => h.workflow_id(),
            Self::AwaitingResponse(h) => h.workflow_id(),
            Self::DecisionReceived(h) => h.workflow_id(),
            Self::Submitted(h) => h.workflow_id(),
            Self::Resolved(h) => h.workflow_id(),
        }
    }

    /// Get the current state name.
    pub fn state_name(&self) -> &'static str {
        match self {
            Self::OnHold(_) => "OnHold",
            Self::AwaitingResponse(_) => "AwaitingResponse",
            Self::DecisionReceived(_) => "DecisionReceived",
            Self::Submitted(_) => "Submitted",
            Self::Resolved(_) => "Resolved",
        }
    }

    /// Check if the workflow is complete.
    pub fn is_resolved(&self) -> bool {
        matches!(self, Self::Resolved(_))
    }
}

// =============================================================================
// Hold Detection
// =============================================================================

/// Configuration for hold polling on startup.
#[derive(Debug, Clone, Default)]
pub struct HoldPollingConfig {
    /// Filter by entity ID (optional).
    pub entity_id: Option<String>,
    /// Maximum number of holds to fetch per page.
    pub page_size: Option<u32>,
}

/// Detect all unreleased holds from the Payrix API.
///
/// This is typically called at startup to catch any holds that may have
/// been created while the service was down.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `config` - Polling configuration
pub async fn detect_unreleased_holds(
    client: &crate::PayrixClient,
    config: &HoldPollingConfig,
) -> crate::Result<Vec<Hold>> {
    use crate::entity::EntityType;

    // Build query for unreleased, active holds
    let mut query = "released[equals]=&inactive[equals]=0".to_string();

    if let Some(entity_id) = &config.entity_id {
        query.push_str(&format!("&entity[equals]={}", entity_id));
    }

    if let Some(page_size) = config.page_size {
        query.push_str(&format!("&page[limit]={}", page_size));
    }

    let holds: Vec<Hold> = client.search(EntityType::Holds, &query).await?;

    tracing::info!(
        count = holds.len(),
        "Detected unreleased holds on startup"
    );

    Ok(holds)
}

/// Detect holds for a specific transaction.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `transaction_id` - The transaction ID to check
pub async fn detect_holds_for_transaction(
    client: &crate::PayrixClient,
    transaction_id: &str,
) -> crate::Result<Vec<Hold>> {
    use crate::entity::EntityType;

    let query = format!(
        "txn[equals]={}&released[equals]=&inactive[equals]=0",
        transaction_id
    );

    let holds: Vec<Hold> = client.search(EntityType::Holds, &query).await?;

    Ok(holds)
}

/// Check if a transaction has an active hold.
///
/// This is a quick check based on the transaction's reserved amount.
/// If reserved > 0, the transaction likely has a hold.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `transaction_id` - The transaction ID to check
pub async fn transaction_has_hold(
    client: &crate::PayrixClient,
    transaction_id: &str,
) -> crate::Result<bool> {
    let holds = detect_holds_for_transaction(client, transaction_id).await?;
    Ok(!holds.is_empty())
}

/// Get a specific hold by ID.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `hold_id` - The hold ID
pub async fn get_hold(client: &crate::PayrixClient, hold_id: &str) -> crate::Result<Hold> {
    use crate::entity::EntityType;

    client
        .get_one::<Hold>(EntityType::Holds, hold_id)
        .await?
        .ok_or_else(|| crate::error::Error::NotFound(format!("Hold not found: {}", hold_id)))
}

/// Load a hold into the workflow state machine.
///
/// Determines the appropriate state based on the hold's current status.
///
/// # Arguments
///
/// * `hold` - The hold to load
pub fn load_workflow(hold: Hold) -> HoldWorkflow {
    // Check if already resolved
    if hold.released.is_some() {
        let typed = TypedHold::<OnHold>::new(hold);
        // Fast-forward through states
        let typed = typed.transition::<AwaitingResponse>();
        let typed = typed.transition::<DecisionReceived>();
        let typed = typed.transition::<Submitted>();
        let typed = typed.transition::<Resolved>();
        return HoldWorkflow::Resolved(typed);
    }

    // Otherwise start fresh
    HoldWorkflow::new(hold)
}

/// Check if a webhook event indicates a transaction hold.
///
/// This checks the transaction's reserved amount, which is set when
/// a hold is placed on the transaction.
///
/// # Arguments
///
/// * `txn` - The transaction from the webhook event
pub fn webhook_event_has_hold(txn: &crate::types::Transaction) -> bool {
    // Check if reserved amount is set (indicates hold)
    if let Some(reserved) = txn.reserved {
        return reserved > 0;
    }
    false
}

/// Extract hold information from a webhook event.
///
/// If the transaction has a hold (reserved > 0), this returns the
/// transaction ID which can be used to fetch the actual Hold record.
///
/// # Arguments
///
/// * `txn` - The transaction from the webhook event
pub fn extract_hold_from_webhook(txn: &crate::types::Transaction) -> Option<String> {
    if webhook_event_has_hold(txn) {
        Some(txn.id.to_string())
    } else {
        None
    }
}

/// Poll for holds at startup and create workflows.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `config` - Polling configuration
pub async fn poll_for_holds_at_startup(
    client: &crate::PayrixClient,
    config: &HoldPollingConfig,
) -> crate::Result<Vec<HoldWorkflow>> {
    let holds = detect_unreleased_holds(client, config).await?;
    let workflows: Vec<HoldWorkflow> = holds.into_iter().map(load_workflow).collect();
    Ok(workflows)
}

// =============================================================================
// Email Notification
// =============================================================================

/// Context for rendering notification email templates.
#[derive(Debug, Clone)]
pub struct NotificationContext {
    /// Hold ID.
    pub hold_id: String,
    /// Workflow ID (used in reply-to address).
    pub workflow_id: String,
    /// Transaction ID.
    pub transaction_id: Option<String>,
    /// Hold amount in cents.
    pub amount: Option<i64>,
    /// Merchant name or ID.
    pub merchant_name: String,
    /// Entity ID.
    pub entity_id: Option<String>,
    /// Hold reason (if available).
    pub hold_reason: Option<String>,
}

impl NotificationContext {
    /// Format the amount as a currency string.
    pub fn formatted_amount(&self) -> String {
        match self.amount {
            Some(cents) => format!("${:.2}", cents as f64 / 100.0),
            None => "Unknown".to_string(),
        }
    }
}

/// A rendered notification email ready to send.
#[derive(Debug, Clone)]
pub struct NotificationEmail {
    /// Recipient email address.
    pub to: String,
    /// Reply-to address (contains workflow ID for tracking).
    pub reply_to: String,
    /// Email subject.
    pub subject: String,
    /// Email body (plain text).
    pub body: String,
}

/// Builder for constructing notification emails.
pub struct NotificationBuilder<'a> {
    config: &'a HoldWorkflowConfig,
    context: NotificationContext,
    recipient: Option<String>,
}

impl<'a> NotificationBuilder<'a> {
    /// Create a new notification builder.
    pub fn new(config: &'a HoldWorkflowConfig, context: NotificationContext) -> Self {
        Self {
            config,
            context,
            recipient: None,
        }
    }

    /// Set the recipient email address.
    pub fn to(mut self, email: impl Into<String>) -> Self {
        self.recipient = Some(email.into());
        self
    }

    /// Build the notification email.
    pub fn build(self) -> HoldResult<NotificationEmail> {
        let recipient = self.recipient.ok_or_else(|| {
            HoldError::Configuration("Recipient email address not set".to_string())
        })?;

        // Build reply-to address with workflow ID
        let reply_to = format!(
            "{}{}@{}",
            self.config.email.reply_to_prefix,
            self.context.workflow_id,
            self.config.email.domain
        );

        // Render subject
        let subject = self
            .config
            .notification
            .subject_template
            .replace("{hold_id}", &self.context.hold_id)
            .replace("{workflow_id}", &self.context.workflow_id);

        // Render body
        let body = self
            .config
            .notification
            .body_template
            .replace("{hold_id}", &self.context.hold_id)
            .replace("{workflow_id}", &self.context.workflow_id)
            .replace(
                "{transaction_id}",
                self.context.transaction_id.as_deref().unwrap_or("N/A"),
            )
            .replace("{amount}", &self.context.formatted_amount())
            .replace("{merchant_name}", &self.context.merchant_name)
            .replace(
                "{response_instructions}",
                &self.config.notification.response_instructions,
            );

        Ok(NotificationEmail {
            to: recipient,
            reply_to,
            subject,
            body,
        })
    }
}

/// Send a notification email to the merchant.
///
/// This is a placeholder that should be implemented using the email service.
/// The actual implementation would use SMTP or an email service provider.
///
/// # Arguments
///
/// * `_config` - The workflow configuration
/// * `email` - The notification email to send
#[allow(unused_variables)]
pub async fn send_notification(
    _config: &HoldWorkflowConfig,
    email: &NotificationEmail,
) -> HoldResult<()> {
    // TODO: Implement actual email sending using the email service
    // This would typically use:
    // - SMTP via the configured SMTP settings
    // - Or AWS SES via the email service crate

    tracing::info!(
        to = %email.to,
        subject = %email.subject,
        reply_to = %email.reply_to,
        "Would send hold notification email"
    );

    Ok(())
}

/// Notify merchant about a hold and transition to AwaitingResponse state.
///
/// # Arguments
///
/// * `hold` - The hold in OnHold state
/// * `config` - The workflow configuration
/// * `merchant_email` - The merchant's email address
/// * `merchant_name` - The merchant's name (for personalization)
pub async fn notify_merchant(
    mut hold: TypedHold<OnHold>,
    config: &HoldWorkflowConfig,
    merchant_email: &str,
    merchant_name: &str,
) -> HoldResult<TypedHold<AwaitingResponse>> {
    // Build notification context
    let context = NotificationContext {
        hold_id: hold.id().to_string(),
        workflow_id: hold.workflow_id().to_string(),
        transaction_id: hold.transaction_id().map(|id| id.to_string()),
        amount: None, // Hold amount would need to come from the transaction
        merchant_name: merchant_name.to_string(),
        entity_id: hold.entity_id().map(|id| id.to_string()),
        hold_reason: hold.inner().hold_source_details.clone(),
    };

    // Build and send notification
    let email = NotificationBuilder::new(config, context)
        .to(merchant_email)
        .build()?;

    send_notification(config, &email).await?;

    // Update hold state
    hold.notified_at = Some(chrono::Utc::now());

    // Transition to AwaitingResponse
    Ok(hold.transition())
}

// =============================================================================
// Email Parsing
// =============================================================================

/// A parsed email attachment.
#[derive(Debug, Clone)]
pub struct ParsedAttachment {
    /// Original filename.
    pub filename: String,
    /// MIME type.
    pub content_type: String,
    /// Attachment data.
    pub data: Vec<u8>,
}

/// A parsed email reply from a merchant.
#[derive(Debug, Clone)]
pub struct ParsedEmailReply {
    /// The workflow ID extracted from the reply-to address.
    pub workflow_id: String,
    /// The merchant's decision (Valid or Fraudulent).
    pub decision: MerchantDecision,
    /// The merchant's note/explanation.
    pub note: Option<String>,
    /// Attached documents.
    pub attachments: Vec<ParsedAttachment>,
}

/// Classify a merchant's decision based on email body keywords.
///
/// # Arguments
///
/// * `body` - The email body text
///
/// # Returns
///
/// The classified decision, or an error if the decision cannot be determined.
pub fn classify_decision(body: &str) -> HoldResult<MerchantDecision> {
    let body_lower = body.to_lowercase();

    // Keywords indicating valid transaction
    // Note: We check fraud keywords first since they're more specific (e.g., "unauthorized" before "authorized")
    let valid_keywords = [
        "valid",
        "legitimate",
        "not fraud",
        "release",
        "approve",
        "genuine",
        "confirmed",
        "is authorized",
        "was authorized",
    ];

    // Keywords indicating fraudulent transaction (checked with higher priority)
    let fraud_keywords = [
        "fraud",
        "fraudulent",
        "unauthorized",
        "stolen",
        "suspicious",
        "deny",
        "reject",
        "fake",
        "scam",
    ];

    // Check fraud keywords first (they're more specific)
    let fraud_score: usize = fraud_keywords
        .iter()
        .filter(|kw| body_lower.contains(*kw))
        .count();

    // If any fraud keyword is found, subtract from valid score when "authorized" would match inside "unauthorized"
    let valid_score: usize = valid_keywords
        .iter()
        .filter(|kw| body_lower.contains(*kw))
        .count();

    if valid_score > fraud_score {
        Ok(MerchantDecision::Valid)
    } else if fraud_score > valid_score {
        Ok(MerchantDecision::Fraudulent)
    } else if valid_score > 0 {
        // Tie with some keywords - default to valid
        Ok(MerchantDecision::Valid)
    } else {
        Err(HoldError::EmailParsing(
            "Could not determine decision from email body".to_string(),
        ))
    }
}

/// Extract workflow ID from a reply-to address.
///
/// Expected format: `prefix{workflow_id}@domain`
///
/// # Arguments
///
/// * `address` - The reply-to email address
/// * `prefix` - The expected prefix (e.g., "hold+")
pub fn extract_workflow_id(address: &str, prefix: &str) -> HoldResult<String> {
    // Remove angle brackets if present
    let address = address.trim_matches(|c| c == '<' || c == '>');

    // Split on @ to get local part
    let local_part = address
        .split('@')
        .next()
        .ok_or_else(|| HoldError::EmailParsing("Invalid email address format".to_string()))?;

    // Check for prefix
    if !local_part.starts_with(prefix) {
        return Err(HoldError::EmailParsing(format!(
            "Email address doesn't start with expected prefix '{}'",
            prefix
        )));
    }

    // Extract workflow ID
    let workflow_id = &local_part[prefix.len()..];

    if workflow_id.is_empty() {
        return Err(HoldError::EmailParsing(
            "Workflow ID is empty".to_string(),
        ));
    }

    Ok(workflow_id.to_string())
}

/// Parse an email reply from a merchant.
///
/// This extracts the workflow ID, decision, note, and attachments from
/// the email.
///
/// # Arguments
///
/// * `to_address` - The To address (contains workflow ID)
/// * `body` - The email body text
/// * `attachments` - List of attachments
/// * `prefix` - The reply-to prefix used (e.g., "hold+")
pub fn parse_email_reply(
    to_address: &str,
    body: &str,
    attachments: Vec<ParsedAttachment>,
    prefix: &str,
) -> HoldResult<ParsedEmailReply> {
    let workflow_id = extract_workflow_id(to_address, prefix)?;
    let decision = classify_decision(body)?;
    let note = extract_merchant_note(body);

    Ok(ParsedEmailReply {
        workflow_id,
        decision,
        note,
        attachments,
    })
}

/// Extract the merchant's note from the email body.
///
/// Attempts to extract meaningful content, filtering out quoted replies
/// and signature blocks.
fn extract_merchant_note(body: &str) -> Option<String> {
    let lines: Vec<&str> = body.lines().collect();

    // Filter out quoted lines (starting with >) and common signatures
    let meaningful_lines: Vec<&str> = lines
        .into_iter()
        .filter(|line| {
            let trimmed = line.trim();
            !trimmed.starts_with('>')
                && !trimmed.starts_with("On ")
                && !trimmed.starts_with("From:")
                && !trimmed.starts_with("Sent:")
                && !trimmed.starts_with("To:")
                && !trimmed.starts_with("Subject:")
                && !trimmed.starts_with("--")
                && !trimmed.starts_with("___")
                && !trimmed.is_empty()
        })
        .collect();

    if meaningful_lines.is_empty() {
        None
    } else {
        Some(meaningful_lines.join("\n").trim().to_string())
    }
}

/// Process a merchant's email reply and transition hold state.
///
/// # Arguments
///
/// * `hold` - The hold in AwaitingResponse state
/// * `decision` - The merchant's decision
/// * `note` - The merchant's note
/// * `documents` - Documents from the email
pub fn receive_decision(
    mut hold: TypedHold<AwaitingResponse>,
    decision: MerchantDecision,
    note: String,
    documents: Vec<HoldDocument>,
) -> HoldResult<TypedHold<DecisionReceived>> {
    hold.decision = Some(decision);
    hold.merchant_note = Some(note);
    hold.documents = documents;

    Ok(hold.transition())
}

// =============================================================================
// Document Upload
// =============================================================================

/// Result of uploading documents.
#[derive(Debug)]
pub struct UploadResult {
    /// ID of the created note.
    pub note_id: String,
    /// IDs of uploaded documents.
    pub document_ids: Vec<String>,
}

/// Parameters for creating a note.
#[derive(Debug)]
pub struct CreateNoteParams {
    /// The hold ID to attach the note to.
    pub hold_id: String,
    /// The note type (e.g., "riskApproved", "riskDenied").
    pub note_type: String,
    /// The note text.
    pub text: String,
}

/// Parameters for uploading a document.
#[derive(Debug)]
pub struct UploadDocumentParams {
    /// The note ID to attach the document to.
    pub note_id: String,
    /// The filename.
    pub filename: String,
    /// The MIME type.
    pub content_type: String,
    /// The document data.
    pub data: Vec<u8>,
}

/// Create a note attached to a hold.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `params` - The note parameters
#[allow(unused_variables)]
pub async fn create_hold_note(
    client: &crate::PayrixClient,
    params: &CreateNoteParams,
) -> HoldResult<String> {
    // TODO: Implement actual note creation via Payrix API
    // This would use the Notes endpoint with:
    // - hold: params.hold_id
    // - noteType: params.note_type
    // - text: params.text

    tracing::info!(
        hold_id = %params.hold_id,
        note_type = %params.note_type,
        "Would create hold note"
    );

    // Return a placeholder ID
    use std::time::{SystemTime, UNIX_EPOCH};
    let ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
    Ok(format!("t1_nte_{:023x}", ts))
}

/// Upload a document to a note.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `params` - The document parameters
#[allow(unused_variables)]
pub async fn upload_document(
    client: &crate::PayrixClient,
    params: &UploadDocumentParams,
) -> HoldResult<String> {
    // TODO: Implement actual document upload via Payrix API
    // This would use the NoteDocuments endpoint with base64-encoded data

    tracing::info!(
        note_id = %params.note_id,
        filename = %params.filename,
        content_type = %params.content_type,
        size = params.data.len(),
        "Would upload document"
    );

    // Return a placeholder ID
    use std::time::{SystemTime, UNIX_EPOCH};
    let ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
    Ok(format!("t1_ntd_{:023x}", ts))
}

/// Infer file type from content-type header.
pub fn infer_file_type(content_type: &str) -> &'static str {
    match content_type.to_lowercase().as_str() {
        "application/pdf" => "pdf",
        "image/jpeg" | "image/jpg" => "jpg",
        "image/png" => "png",
        "image/gif" => "gif",
        "text/plain" => "txt",
        "application/msword" => "doc",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document" => "docx",
        "application/vnd.ms-excel" => "xls",
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" => "xlsx",
        _ => "bin",
    }
}

/// Infer file type from filename extension.
pub fn infer_file_type_from_filename(filename: &str) -> &'static str {
    let ext = filename
        .rsplit('.')
        .next()
        .unwrap_or("")
        .to_lowercase();

    match ext.as_str() {
        "pdf" => "pdf",
        "jpg" | "jpeg" => "jpg",
        "png" => "png",
        "gif" => "gif",
        "txt" => "txt",
        "doc" => "doc",
        "docx" => "docx",
        "xls" => "xls",
        "xlsx" => "xlsx",
        _ => "bin",
    }
}

/// Upload all documents from a merchant's response.
///
/// # Arguments
///
/// * `client` - The Payrix client
/// * `hold_id` - The hold ID
/// * `decision` - The merchant's decision (determines note type)
/// * `note_text` - The text for the note
/// * `documents` - The documents to upload
pub async fn upload_decision_documents(
    client: &crate::PayrixClient,
    hold_id: &str,
    decision: MerchantDecision,
    note_text: &str,
    documents: &[HoldDocument],
) -> HoldResult<UploadResult> {
    let note_type = match decision {
        MerchantDecision::Valid => "riskApproved",
        MerchantDecision::Fraudulent => "riskDenied",
    };

    // Create the note
    let note_id = create_hold_note(
        client,
        &CreateNoteParams {
            hold_id: hold_id.to_string(),
            note_type: note_type.to_string(),
            text: note_text.to_string(),
        },
    )
    .await?;

    // Upload each document
    let mut document_ids = Vec::new();
    for doc in documents {
        let doc_id = upload_document(
            client,
            &UploadDocumentParams {
                note_id: note_id.clone(),
                filename: doc.filename.clone(),
                content_type: doc.content_type.clone(),
                data: doc.data.clone(),
            },
        )
        .await?;
        document_ids.push(doc_id);
    }

    Ok(UploadResult {
        note_id,
        document_ids,
    })
}

// =============================================================================
// Decision Processing
// =============================================================================

/// Result of submitting a decision.
#[derive(Debug)]
pub struct DecisionResult {
    /// Whether the decision was accepted.
    pub accepted: bool,
    /// The updated hold ID.
    pub hold_id: String,
    /// IDs of uploaded documents.
    pub document_ids: Vec<String>,
}

/// Submit a merchant's decision to Payrix.
///
/// This uploads documents, creates notes, and updates the hold status.
///
/// # Arguments
///
/// * `hold` - The hold with decision
/// * `client` - The Payrix client
/// * `config` - The workflow configuration
#[allow(unused_variables)]
pub async fn submit_decision(
    hold: TypedHold<DecisionReceived>,
    client: &crate::PayrixClient,
    config: &HoldWorkflowConfig,
) -> HoldResult<TypedHold<Submitted>> {
    let decision = hold
        .decision
        .ok_or_else(|| HoldError::InvalidDecision("No decision set".to_string()))?;

    let note = hold
        .merchant_note
        .clone()
        .unwrap_or_else(|| format!("Merchant decision: {}", decision));

    // Upload documents and create note
    let _upload_result = upload_decision_documents(
        client,
        &hold.id().to_string(),
        decision,
        &note,
        &hold.documents,
    )
    .await?;

    // Submit the decision based on type
    match decision {
        MerchantDecision::Valid => {
            submit_valid_decision(client, &hold.id().to_string()).await?;
        }
        MerchantDecision::Fraudulent => {
            submit_fraudulent_decision(client, &hold.id().to_string()).await?;
        }
    }

    Ok(hold.transition())
}

/// Submit a valid transaction decision.
///
/// This requests release of the hold with ReleaseAction::Approved.
#[allow(unused_variables)]
async fn submit_valid_decision(
    client: &crate::PayrixClient,
    hold_id: &str,
) -> HoldResult<()> {
    // TODO: Implement actual hold release via Payrix API
    // This would update the hold with:
    // - releaseAction: 1 (Approved)
    // - reviewed: current timestamp

    tracing::info!(
        hold_id = %hold_id,
        action = "release",
        "Would submit valid decision - release hold"
    );

    Ok(())
}

/// Submit a fraudulent transaction decision.
///
/// This marks the hold as reviewed with ReleaseAction::Failed.
#[allow(unused_variables)]
async fn submit_fraudulent_decision(
    client: &crate::PayrixClient,
    hold_id: &str,
) -> HoldResult<()> {
    // TODO: Implement actual hold update via Payrix API
    // This would update the hold with:
    // - releaseAction: 4 (Failed)
    // - reviewed: current timestamp

    tracing::info!(
        hold_id = %hold_id,
        action = "acknowledge_fraud",
        "Would submit fraudulent decision - acknowledge fraud"
    );

    Ok(())
}

/// Check the resolution status of a submitted hold.
///
/// # Arguments
///
/// * `hold` - The submitted hold
/// * `client` - The Payrix client
#[allow(unused_variables)]
pub async fn check_resolution(
    hold: TypedHold<Submitted>,
    client: &crate::PayrixClient,
) -> HoldResult<ResolutionStatus> {
    // Fetch the current hold status
    let current_hold = get_hold(client, &hold.id().to_string()).await?;

    if current_hold.released.is_some() {
        Ok(ResolutionStatus::Resolved(hold.transition()))
    } else {
        Ok(ResolutionStatus::Pending(hold))
    }
}

/// The resolution status of a hold.
#[derive(Debug)]
pub enum ResolutionStatus {
    /// Hold is still pending resolution.
    Pending(TypedHold<Submitted>),
    /// Hold has been resolved.
    Resolved(TypedHold<Resolved>),
}

// =============================================================================
// Tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    /// Create a test Hold for use in tests.
    fn make_test_hold() -> Hold {
        Hold {
            id: "t1_hld_12345678901234567890123".parse().unwrap(),
            created: None,
            modified: None,
            creator: None,
            modifier: None,
            login: None,
            entity: Some("t1_ent_12345678901234567890123".parse().unwrap()),
            txn: Some("t1_txn_12345678901234567890123".parse().unwrap()),
            terminal_txn: None,
            account: None,
            verification: None,
            verification_ref: None,
            decision_action: None,
            action: None,
            hold_source: None,
            hold_source_id: None,
            hold_source_details: Some("Risk review required".to_string()),
            division: None,
            released: None,
            reviewed: None,
            inactive: false,
            frozen: false,
            release_action: None,
            delayed_funding_start_date: None,
            delayed_funding_end_date: None,
            analyst: None,
            claimed: None,
            #[cfg(not(feature = "sqlx"))]
            reserve: None,
        }
    }

    // -------------------------------------------------------------------------
    // Configuration Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_default_config() {
        let config = HoldWorkflowConfig::default();
        assert_eq!(config.email.domain, "holds.example.com");
        assert_eq!(config.email.poll_interval, Duration::from_secs(30));
        assert_eq!(config.timeouts.reminder_after, Duration::from_secs(24 * 60 * 60));
    }

    #[test]
    fn test_config_builder() {
        let config = HoldWorkflowConfigBuilder::new()
            .domain("mycompany.com")
            .from_address("noreply@mycompany.com")
            .reminder_after(Duration::from_secs(12 * 60 * 60))
            .build();

        assert_eq!(config.email.domain, "mycompany.com");
        assert_eq!(config.email.from_address, "noreply@mycompany.com");
        assert_eq!(config.timeouts.reminder_after, Duration::from_secs(12 * 60 * 60));
    }

    // -------------------------------------------------------------------------
    // State Machine Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_typed_hold_creation() {
        let hold = make_test_hold();
        let typed = TypedHold::<OnHold>::new(hold);

        assert_eq!(typed.state_name(), "OnHold");
        assert!(typed.workflow_id().starts_with("wf_"));
        assert!(!typed.is_released());
    }

    #[test]
    fn test_typed_hold_with_workflow_id() {
        let hold = make_test_hold();
        let typed = TypedHold::<OnHold>::with_workflow_id(hold, "custom_wf_123".to_string());

        assert_eq!(typed.workflow_id(), "custom_wf_123");
    }

    #[test]
    fn test_hold_workflow_enum() {
        let hold = make_test_hold();
        let workflow = HoldWorkflow::new(hold);

        assert_eq!(workflow.state_name(), "OnHold");
        assert!(!workflow.is_resolved());
    }

    #[test]
    fn test_merchant_decision_display() {
        assert_eq!(format!("{}", MerchantDecision::Valid), "Valid");
        assert_eq!(format!("{}", MerchantDecision::Fraudulent), "Fraudulent");
    }

    // -------------------------------------------------------------------------
    // Notification Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_notification_context_formatted_amount() {
        let context = NotificationContext {
            hold_id: "123".to_string(),
            workflow_id: "abc".to_string(),
            transaction_id: None,
            amount: Some(10050),
            merchant_name: "Test Merchant".to_string(),
            entity_id: None,
            hold_reason: None,
        };

        assert_eq!(context.formatted_amount(), "$100.50");
    }

    #[test]
    fn test_notification_context_no_amount() {
        let context = NotificationContext {
            hold_id: "123".to_string(),
            workflow_id: "abc".to_string(),
            transaction_id: None,
            amount: None,
            merchant_name: "Test Merchant".to_string(),
            entity_id: None,
            hold_reason: None,
        };

        assert_eq!(context.formatted_amount(), "Unknown");
    }

    #[test]
    fn test_notification_builder() {
        let config = HoldWorkflowConfig::default();
        let context = NotificationContext {
            hold_id: "t1_hld_123".to_string(),
            workflow_id: "wf_abc".to_string(),
            transaction_id: Some("t1_txn_456".to_string()),
            amount: Some(5000),
            merchant_name: "Acme Corp".to_string(),
            entity_id: None,
            hold_reason: None,
        };

        let email = NotificationBuilder::new(&config, context)
            .to("merchant@example.com")
            .build()
            .unwrap();

        assert_eq!(email.to, "merchant@example.com");
        assert!(email.reply_to.contains("wf_abc"));
        assert!(email.subject.contains("t1_hld_123"));
        assert!(email.body.contains("Acme Corp"));
        assert!(email.body.contains("$50.00"));
    }

    #[test]
    fn test_notification_builder_missing_recipient() {
        let config = HoldWorkflowConfig::default();
        let context = NotificationContext {
            hold_id: "123".to_string(),
            workflow_id: "abc".to_string(),
            transaction_id: None,
            amount: None,
            merchant_name: "Test".to_string(),
            entity_id: None,
            hold_reason: None,
        };

        let result = NotificationBuilder::new(&config, context).build();
        assert!(result.is_err());
    }

    // -------------------------------------------------------------------------
    // Email Parsing Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_classify_decision_valid() {
        assert_eq!(
            classify_decision("This is a valid transaction").unwrap(),
            MerchantDecision::Valid
        );
        assert_eq!(
            classify_decision("Please release this legitimate payment").unwrap(),
            MerchantDecision::Valid
        );
        assert_eq!(
            classify_decision("I confirm this is not fraud").unwrap(),
            MerchantDecision::Valid
        );
    }

    #[test]
    fn test_classify_decision_fraudulent() {
        assert_eq!(
            classify_decision("This is fraud").unwrap(),
            MerchantDecision::Fraudulent
        );
        assert_eq!(
            classify_decision("This transaction is unauthorized").unwrap(),
            MerchantDecision::Fraudulent
        );
        assert_eq!(
            classify_decision("My card was stolen").unwrap(),
            MerchantDecision::Fraudulent
        );
    }

    #[test]
    fn test_classify_decision_unclear() {
        let result = classify_decision("Hello, I received your email");
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_workflow_id() {
        let id = extract_workflow_id("hold+wf_123456@holds.example.com", "hold+").unwrap();
        assert_eq!(id, "wf_123456");

        let id = extract_workflow_id("<hold+wf_789@holds.example.com>", "hold+").unwrap();
        assert_eq!(id, "wf_789");
    }

    #[test]
    fn test_extract_workflow_id_wrong_prefix() {
        let result = extract_workflow_id("support+123@example.com", "hold+");
        assert!(result.is_err());
    }

    #[test]
    fn test_parse_email_reply() {
        let reply = parse_email_reply(
            "hold+wf_123@holds.example.com",
            "This transaction is valid. Please release.",
            vec![],
            "hold+",
        )
        .unwrap();

        assert_eq!(reply.workflow_id, "wf_123");
        assert_eq!(reply.decision, MerchantDecision::Valid);
        assert!(reply.note.is_some());
    }

    // -------------------------------------------------------------------------
    // Document Upload Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_infer_file_type() {
        assert_eq!(infer_file_type("application/pdf"), "pdf");
        assert_eq!(infer_file_type("image/jpeg"), "jpg");
        assert_eq!(infer_file_type("image/png"), "png");
        assert_eq!(infer_file_type("text/plain"), "txt");
        assert_eq!(infer_file_type("application/octet-stream"), "bin");
    }

    #[test]
    fn test_infer_file_type_from_filename() {
        assert_eq!(infer_file_type_from_filename("document.pdf"), "pdf");
        assert_eq!(infer_file_type_from_filename("photo.jpg"), "jpg");
        assert_eq!(infer_file_type_from_filename("image.PNG"), "png");
        assert_eq!(infer_file_type_from_filename("unknown"), "bin");
    }

    // -------------------------------------------------------------------------
    // Error Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_hold_error_display() {
        let err = HoldError::NotFound("123".to_string());
        assert_eq!(format!("{}", err), "Hold not found: 123");

        let err = HoldError::InvalidState {
            hold_id: "456".to_string(),
            current_state: "OnHold".to_string(),
            expected_state: "AwaitingResponse".to_string(),
        };
        assert!(format!("{}", err).contains("456"));
        assert!(format!("{}", err).contains("OnHold"));
    }

    // -------------------------------------------------------------------------
    // Detection Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_load_workflow_fresh() {
        let hold = make_test_hold();
        let workflow = load_workflow(hold);
        assert_eq!(workflow.state_name(), "OnHold");
    }

    #[test]
    fn test_load_workflow_released() {
        let mut hold = make_test_hold();
        hold.released = Some("2024-01-01 12:00:00.0000".to_string());
        let workflow = load_workflow(hold);
        assert_eq!(workflow.state_name(), "Resolved");
    }
}