versa 1.9.0

//! Sender-specific functionality for services that send receipts.
//!
//! This module provides the [`VersaSendingClient`] and [`VersaSender`] trait
//! for services that need to send receipts to customers through the Versa Protocol.
//!
//! ## Workflow
//!
//! 1. Create a [`VersaSendingClient`] with your credentials and schema version
//! 2. Upload any assets (images, PDFs) using [`register_asset`](VersaSender::register_asset)
//! 3. Register the receipt with the Versa registry using [`register_receipt`](VersaSender::register_receipt)
//! 4. Encrypt and send the receipt to each receiver using [`encrypt_and_send`](VersaSender::encrypt_and_send)
//!
//! ## Example
//!
//! ```rust,no_run
//! use versa::client::{VersaClient, ClientError};
//! use versa::client_sender::VersaSender;
//! use versa::protocol::TransactionHandles;
//! use versa::schema::receipt::Receipt;
//!
//! # async fn example() -> Result<(), ClientError> {
//! // Create a sending client
//! let client = VersaClient::new("client_id".to_string(), "secret".to_string())
//!     .sending_client("2.2.0".to_string());
//!
//! // Upload an asset
//! let file_data = vec![0u8; 1024]; // Example file data
//! let asset_response = client.register_asset(file_data, "invoice.pdf".to_string()).await?;
//! let asset_id = asset_response.asset_id;
//!
//! // Register the receipt
//! let handles = TransactionHandles::new()
//!     .with_customer_email("customer@example.com".to_string());
//!     
//! let response = client.register_receipt(handles, None).await?;
//! let (encryption_key, summary, receivers) = response.ready_for_delivery();
//!
//! // Create your receipt (you can use the asset_id in appropriate fields)
//! let receipt = Receipt {
//!     // Use asset_id in fields like logo, receipt_image, etc.
//!     # schema_version: versa::schema::current::SCHEMA_VERSION.parse().unwrap(),
//!     # header: versa::schema::receipt::Header::builder().try_into().unwrap(),
//!     # itemization: versa::schema::receipt::Itemization::builder().try_into().unwrap(),
//!     # payments: None,
//!     # footer: None,
//! };
//!
//! // Send to each receiver
//! for receiver in receivers {
//!     client.encrypt_and_send(receiver, summary.clone().into(), encryption_key.clone(), &receipt).await?;
//! }
//! # Ok(())
//! # }
//! ```

use std::future::Future;

use base64::prelude::*;
use serde::Serialize;
use std::time::SystemTime;

use crate::{
  client::{ClientError, VersaClient, customer_registration::CustomerRegistration},
  protocol::{
    AssetRegistrationResponse, ClientMetadata, EncryptionKey, EventRegistrationRequest,
    EventRegistrationResponse, EventRegistrationSummary, ReceiptRegistrationRequest,
    ReceiptRegistrationResponse, ReceiverFilter, ReceiverInstruction, ReceiverQueryRequest,
    ReceiverQueryResponse, TransactionHandles,
    customer_registration::CustomerRef,
    event::{EventType, InitialEventType, UpdateEventType},
    webhook::WebhookEvent,
  },
};

/// Trait for sending receipts through the Versa Protocol.
///
/// This trait is implemented by [`VersaSendingClient`] and provides the core
/// functionality for registering and sending receipts.
pub trait VersaSender {
  /// Registers an event with the Versa registry.
  ///
  /// Returns encryption keys and a list of receivers that should receive the event.
  ///
  /// # Arguments
  ///
  /// * `event_type` - The type of the event to register
  /// * `handles` - Optional transaction handles for routing the event if no transaction ID provided
  /// * `transaction_id` - Optional transaction ID if updating an existing event
  fn register_event(
    &self,
    event_type: EventType,
    handles: Option<TransactionHandles>,
    transaction_id: Option<String>,
  ) -> impl Future<Output = Result<EventRegistrationResponse, ClientError>> + Send;

  /// Registers a new initial event with the Versa registry.
  ///
  /// Returns encryption keys and a list of receivers that should receive the event.
  ///
  /// # Arguments
  ///
  /// * `event_type` - The type of the initial event to register
  /// * `handles` - required transaction handles for routing the event if no transaction ID provided
  fn register_initial_event(
    &self,
    event_type: InitialEventType,
    handles: TransactionHandles,
  ) -> impl Future<Output = Result<EventRegistrationResponse, ClientError>> + Send;

  /// Registers an update event with the Versa registry.
  ///
  /// Returns encryption keys and a list of receivers that should receive the event.
  ///
  /// # Arguments
  ///
  /// * `event_type` - The type of the update event to register
  /// * `handles` - required transaction handles for routing the event if no transaction ID provided
  fn register_update_event(
    &self,
    event_type: UpdateEventType,
    transaction_id: String,
  ) -> impl Future<Output = Result<EventRegistrationResponse, ClientError>> + Send;

  /// Registers a receipt with the Versa registry.
  ///
  /// Returns encryption keys and a list of receivers that should receive the receipt.
  ///
  /// # Arguments
  ///
  /// * `handles` - Transaction handles for routing the receipt
  /// * `transaction_id` - Optional transaction ID if updating an existing receipt
  #[deprecated(since = "1.6.0", note = "please use `register_event()` instead")]
  fn register_receipt(
    &self,
    handles: TransactionHandles,
    transaction_id: Option<String>,
  ) -> impl Future<Output = Result<ReceiptRegistrationResponse, ClientError>> + Send;

  /// Encrypts and sends data to a receiver.
  ///
  /// This method encrypts the provided data using the encryption key from the
  /// registry and sends it to the specified receiver's webhook endpoint.
  ///
  /// # Arguments
  ///
  /// * `receiver` - Receiver instruction from the registry response
  /// * `summary` - Registration summary from the registry response
  /// * `encryption_key` - Encryption key from the registry response
  /// * `data` - The receipt or itinerary data to send
  fn encrypt_and_send<T>(
    &self,
    receiver: ReceiverInstruction,
    summary: EventRegistrationSummary,
    encryption_key: EncryptionKey,
    data: T,
  ) -> impl Future<Output = Result<(), ClientError>>
  where
    T: Serialize;
  /// Registers an asset (image or PDF) with the Versa registry.
  ///
  /// Uploads a file to the Versa registry and returns an asset ID that can be
  /// used to reference the file in receipts and other Versa data structures.
  ///
  /// # Arguments
  ///
  /// * `file_data` - The raw bytes of the file to upload
  /// * `filename` - The original filename (used for content type detection)
  ///
  /// # Supported File Types
  ///
  /// * PDF files
  /// * PNG images
  /// * JPEG images
  /// * WEBP images
  ///
  /// Files must be under 50MB in size.
  fn register_asset(
    &self,
    file_data: Vec<u8>,
    filename: String,
  ) -> impl Future<Output = Result<AssetRegistrationResponse, ClientError>> + Send;

  /// Queries available receivers based on optional filters and transaction handles.
  ///
  /// Returns a list of receivers that match the specified criteria. If transaction
  /// handles are provided, the response will include handling information indicating
  /// whether the sender is registered with each receiver.
  ///
  /// # Arguments
  ///
  /// * `filters` - Optional filters to narrow the receiver list (e.g., by category or region)
  /// * `handles` - Optional transaction handles to check registration status
  ///
  /// # Example
  ///
  /// ```rust,no_run
  /// # use versa::client::{VersaClient, ClientError};
  /// # use versa::client_sender::VersaSender;
  /// # use versa::protocol::{ReceiverFilter, ReceiverCategory, TransactionHandles};
  /// # async fn example() -> Result<(), ClientError> {
  /// # let client = VersaClient::new("id".to_string(), "secret".to_string())
  /// #     .sending_client("2.2.0".to_string());
  /// // Query all expense receivers
  /// let filters = vec![ReceiverFilter::Category(vec![ReceiverCategory::Expense])];
  /// let response = client.query_receivers(Some(filters), None).await?;
  ///
  /// // Query receivers with handling info for a specific customer
  /// let handles = TransactionHandles::new()
  ///     .with_customer_email("customer@example.com".to_string());
  /// let response = client.query_receivers(None, Some(handles)).await?;
  /// # Ok(())
  /// # }
  /// ```
  fn query_receivers(
    &self,
    filters: Option<Vec<ReceiverFilter>>,
    handles: Option<TransactionHandles>,
  ) -> impl Future<Output = Result<ReceiverQueryResponse, ClientError>> + Send;
}

/// Client for sending receipts through the Versa Protocol.
///
/// Created by calling [`sending_client`](VersaClient::sending_client) on a [`VersaClient`].
pub struct VersaSendingClient {
  base_client: VersaClient,
  /// The schema version to use for receipts (e.g., "2.2.0")
  pub schema_version: String,
}

#[cfg(feature = "client_sender")]
impl VersaClient {
  /// Access sending APIs by configuring a Versa sending client with a schema version
  pub fn sending_client(self, schema_version: String) -> VersaSendingClient {
    VersaSendingClient {
      base_client: self,
      schema_version,
    }
  }
}

impl VersaSendingClient {
  pub fn client_id(&self) -> String {
    self.base_client.client_id()
  }
}

#[cfg(feature = "client_sender")]
impl VersaSender for VersaSendingClient {
  async fn register_event(
    &self,
    event_type: EventType,
    handles: Option<TransactionHandles>,
    transaction_id: Option<String>,
  ) -> Result<EventRegistrationResponse, ClientError> {
    let credential = self.base_client.authorization_header_val();
    let schema_version = self.schema_version.clone();

    let payload = EventRegistrationRequest {
      event_type: Some(event_type),
      schema_version,
      handles,
      transaction_id,
      client_metadata: Some(ClientMetadata {
        client_string: self.base_client.client_string(),
      }),
      transaction_event_filter: None,
    };

    let payload_json = serde_json::to_string(&payload).unwrap();

    let url = format!("{}/register", self.base_client.registry_url);
    let client = reqwest::Client::new();
    let response_result = client
      .post(url)
      .header("Accept", "application/json")
      .header("Authorization", credential)
      .header("Content-Type", "application/json")
      .body(payload_json)
      .send()
      .await;

    let res = match response_result {
      Ok(res) => res,
      Err(e) => {
        return Err(ClientError::NetworkError(e));
      }
    };

    if res.status().is_success() {
      let data: EventRegistrationResponse = match res.json().await {
        Ok(val) => val,
        Err(e) => {
          return Err(ClientError::DeserializationError(e));
        }
      };
      return Ok(data);
    } else {
      return Err(ClientError::RegistryError(
        res.status(),
        res.text().await.unwrap_or_default(),
      ));
    }
  }

  async fn register_initial_event(
    &self,
    event_type: InitialEventType,
    handles: TransactionHandles,
  ) -> Result<EventRegistrationResponse, ClientError> {
    self
      .register_event(event_type.into(), Some(handles), None)
      .await
  }

  async fn register_update_event(
    &self,
    event_type: UpdateEventType,
    transaction_id: String,
  ) -> Result<EventRegistrationResponse, ClientError> {
    self
      .register_event(event_type.into(), None, Some(transaction_id))
      .await
  }

  async fn register_receipt(
    &self,
    handles: TransactionHandles,
    transaction_id: Option<String>,
  ) -> Result<ReceiptRegistrationResponse, ClientError> {
    let credential = self.base_client.authorization_header_val();
    let schema_version = self.schema_version.clone();

    let payload = ReceiptRegistrationRequest {
      event_type: None,
      schema_version,
      handles: Some(handles),
      transaction_id,
      client_metadata: Some(ClientMetadata {
        client_string: self.base_client.client_string(),
      }),
      transaction_event_filter: None,
    };

    let payload_json = serde_json::to_string(&payload).unwrap();

    let url = format!("{}/register", self.base_client.registry_url);
    let client = reqwest::Client::new();
    let response_result = client
      .post(url)
      .header("Accept", "application/json")
      .header("Authorization", credential)
      .header("Content-Type", "application/json")
      .body(payload_json)
      .send()
      .await;

    let res = match response_result {
      Ok(res) => res,
      Err(e) => {
        return Err(ClientError::NetworkError(e));
      }
    };

    if res.status().is_success() {
      let data: ReceiptRegistrationResponse = match res.json().await {
        Ok(val) => val,
        Err(e) => {
          return Err(ClientError::DeserializationError(e));
        }
      };
      return Ok(data);
    } else {
      return Err(ClientError::RegistryError(
        res.status(),
        res.text().await.unwrap_or_default(),
      ));
    }
  }

  async fn encrypt_and_send<T>(
    &self,
    receiver: ReceiverInstruction,
    summary: EventRegistrationSummary,
    encryption_key: EncryptionKey,
    data: T,
  ) -> Result<(), ClientError>
  where
    T: Serialize,
  {
    let envelope = crate::encryption::encrypt_envelope(
      &data,
      &BASE64_STANDARD.decode(encryption_key.0).unwrap(),
    );

    let EventRegistrationSummary {
      mode: _,
      event_id: _,
      receipt_id,
      transaction_id: _,
    } = summary;

    let data = crate::protocol::ReceiverPayload {
      sender_client_id: self.base_client.client_id(),
      receipt_id,
      envelope,
    };

    let timestamp = std::time::SystemTime::now()
      .duration_since(SystemTime::UNIX_EPOCH)
      .unwrap()
      .as_secs() as i64;

    let payload = WebhookEvent {
      data,
      event_id: Some(receiver.event_id),
      event_at: Some(timestamp),
      delivery_id: None, // TODO generate and return this
      delivery_at: Some(timestamp),
      event: receiver.event_type.into(),
    };

    let payload_json = serde_json::to_string(&payload).unwrap();
    let byte_body = bytes::Bytes::from(payload_json.clone());
    let token = crate::hmac_util::generate_token(byte_body, receiver.secret);
    let client = reqwest::Client::new();
    let response_result = client
      .post(&receiver.address)
      .header("Content-Type", "application/json")
      .header("X-Request-Signature", token)
      .body(payload_json)
      .send()
      .await;

    let res = match response_result {
      Ok(res) => res,
      Err(e) => {
        return Err(ClientError::NetworkError(e));
      }
    };

    if res.status().is_success() {
      // info!("Successfully sent data to receiver: {}", receiver.address);
      // TODO: process response from each receiver
      return Ok(());
    } else {
      return Err(ClientError::RemoteClientError(
        res.status(),
        res.text().await.unwrap_or_default(),
      ));
    }
  }

  async fn register_asset(
    &self,
    file_data: Vec<u8>,
    filename: String,
  ) -> Result<AssetRegistrationResponse, ClientError> {
    let credential = self.base_client.authorization_header_val();
    let url = format!("{}/asset", self.base_client.registry_url);

    let client = reqwest::Client::new();
    let form = reqwest::multipart::Form::new().part(
      "file",
      reqwest::multipart::Part::bytes(file_data).file_name(filename),
    );

    let response_result = client
      .post(url)
      .header("Authorization", credential)
      .multipart(form)
      .send()
      .await;

    let res = match response_result {
      Ok(res) => res,
      Err(e) => {
        return Err(ClientError::NetworkError(e));
      }
    };

    if res.status().is_success() {
      let data: AssetRegistrationResponse = match res.json().await {
        Ok(val) => val,
        Err(e) => {
          return Err(ClientError::DeserializationError(e));
        }
      };
      return Ok(data);
    } else {
      return Err(ClientError::RegistryError(
        res.status(),
        res.text().await.unwrap_or_default(),
      ));
    }
  }

  async fn query_receivers(
    &self,
    filters: Option<Vec<ReceiverFilter>>,
    handles: Option<TransactionHandles>,
  ) -> Result<ReceiverQueryResponse, ClientError> {
    let credential = self.base_client.authorization_header_val();

    let payload = ReceiverQueryRequest { filters, handles };
    let payload_json = serde_json::to_string(&payload).unwrap();

    let url = format!("{}/receiver/query", self.base_client.registry_url);
    let client = reqwest::Client::new();
    let response_result = client
      .post(url)
      .header("Accept", "application/json")
      .header("Authorization", credential)
      .header("Content-Type", "application/json")
      .body(payload_json)
      .send()
      .await;

    let res = match response_result {
      Ok(res) => res,
      Err(e) => {
        return Err(ClientError::NetworkError(e));
      }
    };

    if res.status().is_success() {
      let data: ReceiverQueryResponse = match res.json().await {
        Ok(val) => val,
        Err(e) => {
          return Err(ClientError::DeserializationError(e));
        }
      };
      return Ok(data);
    } else {
      return Err(ClientError::RegistryError(
        res.status(),
        res.text().await.unwrap_or_default(),
      ));
    }
  }
}

// TODO: could use the typestate pattern with a generic type to constrain the customer reference
impl CustomerRegistration for VersaSendingClient {
  async fn register_customer_reference(
    &self,
    customer_reference: CustomerRef,
  ) -> Result<(), ClientError> {
    self
      .base_client
      .register_customer_reference(customer_reference)
      .await
  }

  async fn deregister_customer_reference(
    &self,
    customer_reference: CustomerRef,
  ) -> Result<(), ClientError> {
    self
      .base_client
      .register_customer_reference(customer_reference)
      .await
  }
}