1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
//! 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>,
}