delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
//! Checkout-recovery models: the emails that bring the buyer of an unfinished
//! checkout back to a payable checkout, and checkout reactivation.
//!
//! Buyer addresses and composed message bodies are redacted from `Debug`.

use std::fmt;

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

/// A checkout's recovery: whether and when the shop's rule reminds it, every
/// reason it does not, every message about it, and where its link goes.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutRecoveryStatus {
    /// The checkout's first payment.
    pub payment_id: String,
    /// The payment the checkout is on now: the first, or the newest the
    /// recovery link made.
    pub current_payment_id: String,
    /// The shop (business profile).
    pub profile_id: String,
    /// Whether the shop's reminder rule is switched on.
    pub rule_enabled: bool,
    /// `due`, `scheduled` or `excluded`.
    pub automatic: String,
    /// Why no reminder is due now, when none is.
    #[serde(default)]
    pub reasons: Vec<String>,
    /// ISO 8601 time of the next automatic reminder.
    #[serde(default)]
    pub next_reminder_at: Option<String>,
    /// What the next automatic reminder would say, e.g. `unfinished_checkout`.
    #[serde(default)]
    pub next_scenario: Option<String>,
    /// Automatic reminders sent so far.
    pub reminders_sent: u32,
    /// The most automatic reminders the rule sends.
    pub max_reminders: u32,
    /// The merchant stopped this checkout's reminders.
    pub stopped: bool,
    /// ISO 8601 time the reminders were stopped.
    #[serde(default)]
    pub stopped_at: Option<String>,
    /// Who stopped them.
    #[serde(default)]
    pub stopped_by: Option<String>,
    /// The buyer's address, masked. Redacted from `Debug`.
    #[serde(default)]
    pub recipient: Option<String>,
    /// The buyer asked not to be sent these reminders.
    pub recipient_unsubscribed: bool,
    /// Where the checkout's link takes the buyer now, e.g. `open_checkout`,
    /// `new_checkout`.
    pub destination: String,
    /// Why a message by hand would be refused now, if it would.
    #[serde(default)]
    pub manual_blocked: Option<String>,
    /// Every message about this checkout, newest first.
    #[serde(default)]
    pub reminders: Vec<CheckoutReminder>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl fmt::Debug for CheckoutRecoveryStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CheckoutRecoveryStatus")
            .field("payment_id", &self.payment_id)
            .field("current_payment_id", &self.current_payment_id)
            .field("profile_id", &self.profile_id)
            .field("rule_enabled", &self.rule_enabled)
            .field("automatic", &self.automatic)
            .field("reasons", &self.reasons)
            .field("next_reminder_at", &self.next_reminder_at)
            .field("next_scenario", &self.next_scenario)
            .field("reminders_sent", &self.reminders_sent)
            .field("max_reminders", &self.max_reminders)
            .field("stopped", &self.stopped)
            .field("recipient", &self.recipient.as_ref().map(|_| "<redacted>"))
            .field("recipient_unsubscribed", &self.recipient_unsubscribed)
            .field("destination", &self.destination)
            .field("manual_blocked", &self.manual_blocked)
            .field("reminders", &self.reminders)
            .finish_non_exhaustive()
    }
}

/// One message to a buyer about a checkout: an automatic reminder or one
/// sent by hand.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutReminder {
    /// The message's ID.
    pub id: String,
    /// The checkout's first payment.
    pub payment_id: String,
    /// The shop (business profile).
    pub profile_id: String,
    /// Automatic or by hand.
    pub origin: String,
    /// What it says, e.g. `unfinished_checkout`, `payment_failed`.
    pub scenario: String,
    /// 1, 2, ... for automatic reminders; absent for a message sent by hand.
    #[serde(default)]
    pub sequence: Option<i32>,
    /// Where the message is, e.g. sent, failed or skipped.
    pub status: String,
    /// The buyer's address, masked. Redacted from `Debug`.
    #[serde(default)]
    pub recipient: Option<String>,
    /// The language it was written in.
    #[serde(default)]
    pub locale: Option<String>,
    /// The subject it was sent with, placeholders as written.
    #[serde(default)]
    pub subject: Option<String>,
    /// The body it was sent with, placeholders as written.
    #[serde(default)]
    pub body: Option<String>,
    /// A message about a test payment; its subject is marked `[TEST]`.
    pub test_mode: bool,
    /// Delivery attempts so far.
    pub attempts: i32,
    /// Why it failed or was skipped.
    #[serde(default)]
    pub error_code: Option<String>,
    /// Why it failed or was skipped, in words.
    #[serde(default)]
    pub error_message: Option<String>,
    /// Who sent it by hand.
    #[serde(default)]
    pub requested_by: Option<String>,
    /// ISO 8601 creation time.
    pub created_at: String,
    /// ISO 8601 last-modification time.
    pub modified_at: String,
    /// ISO 8601 time it was sent.
    #[serde(default)]
    pub sent_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl fmt::Debug for CheckoutReminder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CheckoutReminder")
            .field("id", &self.id)
            .field("payment_id", &self.payment_id)
            .field("profile_id", &self.profile_id)
            .field("origin", &self.origin)
            .field("scenario", &self.scenario)
            .field("sequence", &self.sequence)
            .field("status", &self.status)
            .field("recipient", &self.recipient.as_ref().map(|_| "<redacted>"))
            .field("locale", &self.locale)
            .field("test_mode", &self.test_mode)
            .field("attempts", &self.attempts)
            .field("error_code", &self.error_code)
            .field("created_at", &self.created_at)
            .field("sent_at", &self.sent_at)
            .finish_non_exhaustive()
    }
}

/// A page of messages to buyers, newest first.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutReminderList {
    /// The messages.
    #[serde(default)]
    pub data: Vec<CheckoutReminder>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Whether a checkout can be reactivated now, and what it would continue.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutReactivationPreview {
    /// The checkout's first payment.
    pub payment_id: String,
    /// The payment the checkout is on now.
    pub current_payment_id: String,
    /// The shop (business profile).
    pub profile_id: String,
    /// The current payment's status.
    pub status: String,
    /// Whether the checkout can be reactivated now.
    pub available: bool,
    /// Why it cannot, when it cannot, e.g. `paid`, `checkout_still_open`.
    #[serde(default)]
    pub blocked: Option<String>,
    /// The merchant's order reference.
    #[serde(default)]
    pub merchant_order_reference_id: Option<String>,
    /// The payment's description.
    #[serde(default)]
    pub description: Option<String>,
    /// The amount, in minor units of `currency`.
    pub amount: i64,
    /// ISO 4217 currency code.
    #[serde(default)]
    pub currency: Option<String>,
    /// The current checkout page.
    #[serde(default)]
    pub checkout_url: Option<String>,
    /// ISO 8601 time the current checkout page expires.
    #[serde(default)]
    pub checkout_expires_at: Option<String>,
    /// Whether the current checkout page has expired.
    pub checkout_expired: bool,
    /// The validity a reactivation gives when none is asked for, in seconds.
    pub default_validity_seconds: u32,
    /// The shortest validity that may be asked for, in seconds.
    pub min_validity_seconds: u32,
    /// The longest validity that may be asked for, in seconds.
    pub max_validity_seconds: u32,
    /// Earlier reactivations of this checkout.
    #[serde(default)]
    pub reactivations: Vec<CheckoutReactivationRecord>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One earlier reactivation of a checkout.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutReactivationRecord {
    /// The payment the reactivation made.
    pub payment_id: String,
    /// The payment it replaced.
    pub previous_payment_id: String,
    /// Who reactivated it.
    pub reactivated_by: String,
    /// ISO 8601 time of the reactivation.
    pub reactivated_at: String,
    /// ISO 8601 time the replaced checkout expired.
    #[serde(default)]
    pub previous_expires_at: Option<String>,
    /// ISO 8601 time the reactivated checkout expires.
    #[serde(default)]
    pub expires_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// The checkout a reactivation continues on.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutReactivation {
    /// The checkout's first payment.
    pub payment_id: String,
    /// The payment it replaced.
    pub previous_payment_id: String,
    /// The payment the checkout is on now.
    pub current_payment_id: String,
    /// The reactivated checkout page.
    pub checkout_url: String,
    /// ISO 8601 time the reactivated checkout expires.
    #[serde(default)]
    pub expires_at: Option<String>,
    /// ISO 8601 time the replaced checkout expired.
    #[serde(default)]
    pub previous_expires_at: Option<String>,
    /// `true` when a repeated request answers with the checkout an earlier
    /// one made.
    pub already_active: bool,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A message by hand as it would be sent now. Nothing was sent.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct ManualEmailPreview {
    /// What it says, e.g. `unfinished_checkout`.
    pub scenario: String,
    /// The address it goes to, in full. Redacted from `Debug`.
    #[serde(default)]
    pub recipient: Option<String>,
    /// The sender name.
    pub from_name: String,
    /// The sender address.
    #[serde(default)]
    pub from_address: Option<String>,
    /// The reply-to address.
    #[serde(default)]
    pub reply_to: Option<String>,
    /// The language it is written in.
    pub language: String,
    /// The composed subject.
    pub subject: String,
    /// The composed plain-text body. Redacted from `Debug`.
    pub text_body: String,
    /// The composed HTML body. Redacted from `Debug`.
    pub html_body: String,
    /// The link in the message. Redacted from `Debug`.
    pub link: String,
    /// Where the link takes the buyer now.
    pub destination: String,
    /// Why it would be refused, if it would.
    #[serde(default)]
    pub blocked: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl fmt::Debug for ManualEmailPreview {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ManualEmailPreview")
            .field("scenario", &self.scenario)
            .field("recipient", &self.recipient.as_ref().map(|_| "<redacted>"))
            .field("from_name", &self.from_name)
            .field("language", &self.language)
            .field("subject", &self.subject)
            .field("text_body", &"<redacted>")
            .field("html_body", &"<redacted>")
            .field("link", &"<redacted>")
            .field("destination", &self.destination)
            .field("blocked", &self.blocked)
            .finish_non_exhaustive()
    }
}

/// The shop's recent checkouts judged under a reminder rule. Nothing was
/// sent.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CandidatePreviewResponse {
    /// Checkouts judged.
    pub evaluated: u32,
    /// Checkouts the rule would remind.
    pub eligible: u32,
    /// Whether every checkout's purchase history could be read.
    pub purchase_history_complete: bool,
    /// Every checkout judged, with its reasons.
    #[serde(default)]
    pub candidates: Vec<CandidatePreview>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One checkout judged under a reminder rule.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct CandidatePreview {
    /// The checkout's first payment.
    pub payment_id: String,
    /// The payment the checkout is on now.
    pub current_payment_id: String,
    /// ISO 8601 creation time.
    pub created_at: String,
    /// The amount, in minor units of `currency`.
    pub amount: i64,
    /// ISO 4217 currency code.
    #[serde(default)]
    pub currency: Option<String>,
    /// The buyer's address. Redacted from `Debug`.
    #[serde(default)]
    pub recipient: Option<String>,
    /// A test payment.
    pub test_mode: bool,
    /// `due`, `scheduled` or `excluded`.
    pub automatic: String,
    /// Why no reminder is due, when none is.
    #[serde(default)]
    pub reasons: Vec<String>,
    /// ISO 8601 time of the next reminder.
    #[serde(default)]
    pub next_reminder_at: Option<String>,
    /// What the next reminder would say.
    #[serde(default)]
    pub next_scenario: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl fmt::Debug for CandidatePreview {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CandidatePreview")
            .field("payment_id", &self.payment_id)
            .field("current_payment_id", &self.current_payment_id)
            .field("created_at", &self.created_at)
            .field("amount", &self.amount)
            .field("currency", &self.currency)
            .field("recipient", &self.recipient.as_ref().map(|_| "<redacted>"))
            .field("test_mode", &self.test_mode)
            .field("automatic", &self.automatic)
            .field("reasons", &self.reasons)
            .field("next_reminder_at", &self.next_reminder_at)
            .field("next_scenario", &self.next_scenario)
            .finish_non_exhaustive()
    }
}

/// The outcome of a test reminder sent to the signed-in user's own address.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct TestEmailResponse {
    /// The address it went to. Redacted from `Debug`.
    pub recipient: String,
    /// Whether it was sent.
    pub sent: bool,
    /// Why it was not sent.
    #[serde(default)]
    pub error_code: Option<String>,
    /// Why it was not sent, in words.
    #[serde(default)]
    pub error_message: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

impl fmt::Debug for TestEmailResponse {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("TestEmailResponse")
            .field("recipient", &"<redacted>")
            .field("sent", &self.sent)
            .field("error_code", &self.error_code)
            .field("error_message", &self.error_message)
            .finish_non_exhaustive()
    }
}

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

    #[test]
    fn recovery_status_debug_redacts_the_recipient() {
        let status: CheckoutRecoveryStatus = serde_json::from_str(
            r#"{"payment_id":"pay_1","current_payment_id":"pay_1","profile_id":"pro_1",
                "rule_enabled":true,"automatic":"scheduled","reasons":[],"reminders_sent":0,
                "max_reminders":2,"stopped":false,"recipient":"j***@buyer.example",
                "recipient_unsubscribed":false,"destination":"open_checkout",
                "reminders":[{"id":"rem_1","payment_id":"pay_1","profile_id":"pro_1",
                "origin":"manual","scenario":"unfinished_checkout","status":"sent",
                "recipient":"j***@buyer.example","test_mode":false,"attempts":1,
                "created_at":"t","modified_at":"t"}]}"#,
        )
        .unwrap();
        let printed = format!("{status:?}");
        assert!(!printed.contains("buyer.example"), "{printed}");
        assert!(printed.contains("<redacted>"));
        assert!(printed.contains("pay_1"));
    }

    #[test]
    fn manual_email_preview_debug_redacts_recipient_bodies_and_link() {
        let preview: ManualEmailPreview = serde_json::from_str(
            r#"{"scenario":"unfinished_checkout","recipient":"ada@buyer.example",
                "from_name":"Shop","language":"en","subject":"Your order",
                "text_body":"Hi Ada Lovelace","html_body":"<p>Hi Ada Lovelace</p>",
                "link":"https://pay.example/secret-token","destination":"open_checkout"}"#,
        )
        .unwrap();
        let printed = format!("{preview:?}");
        for leaked in ["buyer.example", "Ada Lovelace", "secret-token"] {
            assert!(!printed.contains(leaked), "{leaked} leaked: {printed}");
        }
        assert!(printed.contains("Your order"));
    }

    #[test]
    fn candidate_and_test_email_debug_redact_the_recipient() {
        let candidate: CandidatePreview = serde_json::from_str(
            r#"{"payment_id":"pay_1","current_payment_id":"pay_1","created_at":"t",
                "amount":100,"recipient":"ada@buyer.example","test_mode":false,
                "automatic":"due","reasons":[]}"#,
        )
        .unwrap();
        assert!(!format!("{candidate:?}").contains("buyer.example"));
        let test: TestEmailResponse =
            serde_json::from_str(r#"{"recipient":"me@team.example","sent":true}"#).unwrap();
        assert!(!format!("{test:?}").contains("team.example"));
    }
}