delopay 0.7.0

Official Rust SDK for the DeloPay payments API
Documentation
//! Analytics drill-through models.
//!
//! The aggregate dashboards answer with open shapes (see
//! [`crate::Analytics`]); the drill lists do not, because their rows carry two
//! distinctions a caller can only lose once — which of a row's two timestamps
//! is the payment's own age, and whether a USD figure is complete.

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

/// One row behind a clicked chart element.
///
/// The fields below `connector` are always sent by the current backend, and
/// nullable rather than omitted: a payment that never reached an attempt has
/// no processor, which is not the same as the endpoint declining to say.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DrillPayment {
    /// The payment this row is (or, on the subscription drill, the invoice id
    /// when the cycle never reached a payment — see
    /// [`invoice_id`](Self::invoice_id)).
    pub payment_id: String,
    /// Owning merchant — meaningful on a cross-merchant scope.
    pub merchant_id: String,
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Shop name for the profile, when known to the scope.
    #[serde(default)]
    pub shop_name: Option<String>,
    /// Raw intent status.
    pub status: String,
    #[serde(default)]
    pub amount_minor: Option<i64>,
    #[serde(default)]
    pub currency: Option<String>,
    /// When the buyer was **observed** — the timestamp of the canonical
    /// client-context row, not of the payment. This is the value the window
    /// filters on, so it always falls inside the requested range.
    ///
    /// Read [`payment_created_at`](Self::payment_created_at) for the payment's
    /// own age: the two can be days apart on a long-lived payment link, and
    /// reading this one as the creation time is what makes a drill list look
    /// like it is ignoring its own window. RFC 3339 UTC.
    pub created_at: String,
    /// When the **payment** was created, RFC 3339 UTC. Unlike
    /// [`created_at`](Self::created_at) this need not fall inside the
    /// requested window: a payment created weeks ago can be observed today.
    pub payment_created_at: String,
    /// IP-claimed country of the canonical observation.
    #[serde(default)]
    pub country: Option<String>,
    /// IP-resolved city, when GeoLite2 had one.
    #[serde(default)]
    pub city: Option<String>,
    /// Processor of the active attempt (`"Direct"` when the attempt carried
    /// none); `None` when the intent never reached an attempt.
    #[serde(default)]
    pub connector: Option<String>,
    /// High-level payment method of the active attempt (`card`, `wallet`, …).
    #[serde(default)]
    pub payment_method: Option<String>,
    /// Narrower method type of the active attempt (`credit`, `apple_pay`, …).
    #[serde(default)]
    pub payment_method_type: Option<String>,
    /// Checkout channel token; `None` on rows that are not payments.
    #[serde(default)]
    pub channel: Option<String>,
    /// Device class of the canonical observation, when one exists.
    #[serde(default)]
    pub device_class: Option<String>,
    /// Browser family of the canonical observation (`chrome`, `safari`, …).
    #[serde(default)]
    pub browser_family: Option<String>,
    /// Platform family of the canonical observation (`ios`, `android`, …).
    #[serde(default)]
    pub platform_family: Option<String>,
    /// Seconds from the first checkout open to the succeeded transition;
    /// `None` when either endpoint is missing.
    #[serde(default)]
    pub time_to_pay_s: Option<f64>,
    /// The amount in USD major units, converted with the same rates the
    /// dashboard sums with — so a drawer's figures agree with the chart that
    /// was clicked. `None` when the currency has no fresh rate, which is a
    /// missing figure and not a zero.
    #[serde(default)]
    pub amount_usd: Option<f64>,
    /// Successfully refunded amount in the payment's own minor units.
    #[serde(default)]
    pub refunded_minor: Option<i64>,
    /// The buyer's customer id, when the payment carried one.
    #[serde(default)]
    pub customer_id: Option<String>,
    /// Subscription this row belongs to. Set only by the subscription drill;
    /// its presence is what tells a client to link the row at the
    /// subscription rather than at the payment.
    #[serde(default)]
    pub subscription_id: Option<String>,
    /// Invoice (billing cycle) this row is. Subscription drill only.
    #[serde(default)]
    pub invoice_id: Option<String>,
    /// The invoice's own status, which is not the payment's: a cycle can have
    /// failed while no payment row exists at all. Subscription drill only.
    #[serde(default)]
    pub invoice_status: Option<String>,
    /// Plan the subscription is on. Subscription drill only.
    #[serde(default)]
    pub plan: Option<String>,
    /// Billing processor that raised the cycle. Subscription drill only.
    #[serde(default)]
    pub billing_processor: Option<String>,
    /// The subscription's own status. Subscription drill only.
    #[serde(default)]
    pub subscription_status: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Figures over the **whole** match of a drill — not the returned page — so a
/// drawer header can summarise what was clicked while the list is paged.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DrillSummary {
    /// Rows matched (equals the response's `total`). On the subscription
    /// drill a row is a billing cycle, so this is the invoice count.
    pub count: i64,
    /// Rows whose outcome is success (settled cycles on the subscription
    /// drill).
    pub successful_count: i64,
    /// USD major units. Rows with no fresh rate contribute their count but
    /// not their volume — see [`unconverted_count`](Self::unconverted_count).
    pub successful_volume_usd: f64,
    /// Successfully refunded volume behind the matched rows, USD major units.
    pub refund_volume_usd: f64,
    /// `successful_count / count`, `0` when nothing matched.
    pub success_rate: f64,
    /// Median successful amount, USD major units; `None` when none converted.
    #[serde(default)]
    pub median_amount_usd: Option<f64>,
    /// Median time-to-pay over the matched paid, timed sessions (device and
    /// geo drills); `None` elsewhere.
    #[serde(default)]
    pub median_time_to_pay_s: Option<f64>,
    /// Distinct subscriptions behind the matched cycles (subscription drill);
    /// `None` elsewhere.
    #[serde(default)]
    pub subscriptions: Option<i64>,
    /// Rows whose currency had no fresh USD rate. Non-zero makes every USD
    /// figure above a **lower bound** rather than a total.
    pub unconverted_count: i64,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl DrillSummary {
    /// Whether the USD figures cover every matched row.
    ///
    /// `false` means [`successful_volume_usd`](Self::successful_volume_usd)
    /// and [`refund_volume_usd`](Self::refund_volume_usd) are lower bounds:
    /// some row's currency had no fresh rate, so its money is missing from
    /// them while its row is still counted.
    pub fn usd_is_complete(&self) -> bool {
        self.unconverted_count == 0
    }
}

/// A drill-through list: the rows behind one clicked chart element.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DrillResponse {
    /// `false` when the client-context switch that feeds these lists is off.
    /// The response is then a 200 carrying no rows and a caveat naming the
    /// switch, rather than an error.
    pub enabled: bool,
    /// Codes, not sentences — ways the figures are not the whole truth.
    #[serde(default)]
    pub caveats: Vec<String>,
    /// One page, sorted per the request's sort key (newest first by default).
    #[serde(default)]
    pub payments: Vec<DrillPayment>,
    /// Full match count, which may exceed `payments.len()`.
    pub total: i64,
    /// Figures over the whole match. `None` against a backend that predates
    /// the summary — which is "no summary", not zeros.
    #[serde(default)]
    pub summary: Option<DrillSummary>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}