delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The customer model.

use serde::Deserialize;
use serde_json::Value;

/// A customer as returned by the API.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CustomerResponse {
    /// Unique customer ID.
    pub customer_id: String,
    /// ISO 8601 creation timestamp.
    #[serde(default)]
    pub created_at: Option<String>,
    /// Full name.
    #[serde(default)]
    pub name: Option<String>,
    /// Email address.
    #[serde(default)]
    pub email: Option<String>,
    /// Phone number.
    #[serde(default)]
    pub phone: Option<String>,
    /// Phone country code.
    #[serde(default)]
    pub phone_country_code: Option<String>,
    /// Internal notes.
    #[serde(default)]
    pub description: Option<String>,
    /// ID of the default saved payment method, if any.
    #[serde(default)]
    pub default_payment_method_id: Option<String>,
    /// Arbitrary metadata.
    #[serde(default)]
    pub metadata: Option<Value>,
    /// Shops (business profiles) this customer has transacted in, derived from
    /// their payments — the same rule the `profile_ids` list filter applies. A
    /// customer created but never charged belongs to no shop.
    ///
    /// Returned by [`Customers::retrieve`](crate::resources::customers::Customers::retrieve)
    /// only: deriving it costs a query per customer, so the list endpoints omit
    /// it. **`None` means "not computed", not "no shops"** — `Some(vec![])` is
    /// a real answer and stays distinguishable from a field nobody filled in.
    ///
    /// A shop-scoped caller only sees their own shop here; the server narrows
    /// the list to the caller's scope.
    #[serde(default)]
    pub profile_ids: Option<Vec<String>>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// What placing a customer in a shop did.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum CustomerShopPlacementOutcome {
    /// The customer now belongs to the shop; their other shops are unchanged.
    Placed,
    /// The customer already belonged to the shop; nothing changed.
    AlreadyInShop,
    /// No customer with this id. Only a bulk placement answers it; a single
    /// placement answers `CustomerNotFound` instead.
    NotFound,
    /// An outcome this SDK version does not know yet.
    #[serde(other)]
    Unknown,
}

/// One customer's placement in a shop.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CustomerShopPlacementResponse {
    /// The customer.
    pub customer_id: String,
    /// The shop.
    pub profile_id: String,
    /// What the placement did.
    pub outcome: CustomerShopPlacementOutcome,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Every distinct customer of a bulk placement, in the order of the request.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CustomerShopBulkPlacementResponse {
    /// The shop.
    pub profile_id: String,
    /// One entry per distinct customer id of the request.
    #[serde(default)]
    pub placements: Vec<CustomerShopPlacementResponse>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}
#[cfg(test)]
mod tests {
    use super::*;

    /// "This customer has paid no shop" and "the list endpoint did not compute
    /// this" are different answers. Mutation: `#[serde(default)]` on a
    /// `Vec<String>` instead of an `Option` collapses them into one.
    #[test]
    fn customer_distinguishes_empty_shops_from_uncomputed_shops() {
        let charged: CustomerResponse =
            serde_json::from_str(r#"{"customer_id":"cus_1","profile_ids":["pro_1"]}"#).unwrap();
        let never_charged: CustomerResponse =
            serde_json::from_str(r#"{"customer_id":"cus_2","profile_ids":[]}"#).unwrap();
        let from_a_list: CustomerResponse =
            serde_json::from_str(r#"{"customer_id":"cus_3"}"#).unwrap();

        assert_eq!(
            charged.profile_ids.as_deref(),
            Some(&["pro_1".to_string()][..])
        );
        assert_eq!(never_charged.profile_ids.as_deref(), Some(&[][..]));
        assert_eq!(from_a_list.profile_ids, None);
    }
}