use std::fmt;
use std::sync::Arc;
use serde::Serialize;
use serde_json::Value;
use crate::core::encoding::{encode_segment, to_json_vec};
use crate::core::error::Result;
use crate::core::models::checkout_recovery::{
CandidatePreviewResponse, CheckoutReactivation, CheckoutReactivationPreview,
CheckoutRecoveryStatus, CheckoutReminder, CheckoutReminderList, ManualEmailPreview,
TestEmailResponse,
};
use crate::http::client::Inner;
use crate::http::transport::HttpMethod;
#[derive(Debug, Clone)]
pub struct CheckoutRecovery {
inner: Arc<Inner>,
}
impl CheckoutRecovery {
pub(crate) fn new(inner: Arc<Inner>) -> Self {
Self { inner }
}
pub async fn retrieve(&self, payment_id: &str) -> Result<CheckoutRecoveryStatus> {
self.inner
.request(HttpMethod::Get, &payment_path(payment_id), None, &[], None)
.await
}
pub async fn stop(&self, payment_id: &str) -> Result<CheckoutRecoveryStatus> {
let path = format!("{}/stop", payment_path(payment_id));
self.inner
.request_body_keyed_with_query(HttpMethod::Post, &path, None, &[], None)
.await
}
pub async fn resume(&self, payment_id: &str) -> Result<CheckoutRecoveryStatus> {
let path = format!("{}/resume", payment_path(payment_id));
self.inner
.request_body_keyed_with_query(HttpMethod::Post, &path, None, &[], None)
.await
}
pub async fn preview_reactivation(
&self,
payment_id: &str,
) -> Result<CheckoutReactivationPreview> {
let path = format!("{}/reactivation", payment_path(payment_id));
self.inner
.request(HttpMethod::Get, &path, None, &[], None)
.await
}
pub async fn reactivate(
&self,
payment_id: &str,
params: &ReactivateCheckoutRequest,
) -> Result<CheckoutReactivation> {
let path = format!("{}/reactivate", payment_path(payment_id));
let body = to_json_vec(params)?;
self.inner
.request_body_keyed_with_query(HttpMethod::Post, &path, Some(&body), &[], None)
.await
}
pub async fn preview_email(
&self,
payment_id: &str,
params: &ManualEmailRequest,
) -> Result<ManualEmailPreview> {
let path = format!("{}/email/preview", payment_path(payment_id));
let body = to_json_vec(params)?;
self.inner
.request_body_keyed_with_query(HttpMethod::Post, &path, Some(&body), &[], None)
.await
}
pub async fn send_email(
&self,
payment_id: &str,
params: &ManualEmailRequest,
) -> Result<CheckoutReminder> {
let path = format!("{}/email", payment_path(payment_id));
let body = to_json_vec(params)?;
self.inner
.request_body_keyed(
HttpMethod::Post,
&path,
Some(&body),
params.idempotency_key.as_deref(),
)
.await
}
pub async fn list_reminders(
&self,
params: Option<&CheckoutReminderListParams>,
) -> Result<CheckoutReminderList> {
let mut query = Vec::new();
if let Some(params) = params {
if let Some(profile_id) = ¶ms.profile_id {
query.push(("profile_id", profile_id.clone()));
}
if let Some(limit) = params.limit {
query.push(("limit", limit.to_string()));
}
if let Some(offset) = params.offset {
query.push(("offset", offset.to_string()));
}
}
self.inner
.request(
HttpMethod::Get,
"/checkout-recovery/reminders",
None,
&query,
None,
)
.await
}
pub async fn preview_candidates(
&self,
params: &CandidatePreviewRequest,
) -> Result<CandidatePreviewResponse> {
let body = to_json_vec(params)?;
self.inner
.request_body_keyed_with_query(
HttpMethod::Post,
"/checkout-recovery/candidates",
Some(&body),
&[],
None,
)
.await
}
pub async fn send_test_email(&self, params: &TestEmailRequest) -> Result<TestEmailResponse> {
let body = to_json_vec(params)?;
self.inner
.request_body_keyed_with_query(
HttpMethod::Post,
"/checkout-recovery/test-email",
Some(&body),
&[],
None,
)
.await
}
}
fn payment_path(payment_id: &str) -> String {
format!("/checkout-recovery/payments/{}", encode_segment(payment_id))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ReminderScenario {
UnfinishedCheckout,
PaymentFailed,
MethodRestored,
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct ReactivateCheckoutRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub validity_seconds: Option<u32>,
}
impl ReactivateCheckoutRequest {
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn validity_seconds(mut self, validity_seconds: u32) -> Self {
self.validity_seconds = Some(validity_seconds);
self
}
}
#[derive(Clone, Serialize)]
pub struct ManualEmailRequest {
pub scenario: ReminderScenario,
#[serde(skip_serializing_if = "Option::is_none")]
pub recipient: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub language: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub subject: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub body: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub idempotency_key: Option<String>,
}
impl fmt::Debug for ManualEmailRequest {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("ManualEmailRequest")
.field("scenario", &self.scenario)
.field("recipient", &self.recipient.as_ref().map(|_| "<redacted>"))
.field("language", &self.language)
.field("subject", &self.subject)
.field("body", &self.body)
.field("idempotency_key", &self.idempotency_key)
.finish()
}
}
impl ManualEmailRequest {
pub fn new(scenario: ReminderScenario) -> Self {
Self {
scenario,
recipient: None,
language: None,
subject: None,
body: None,
idempotency_key: None,
}
}
#[must_use]
pub fn recipient(mut self, recipient: impl Into<String>) -> Self {
self.recipient = Some(recipient.into());
self
}
#[must_use]
pub fn language(mut self, language: impl Into<String>) -> Self {
self.language = Some(language.into());
self
}
#[must_use]
pub fn text(mut self, subject: impl Into<String>, body: impl Into<String>) -> Self {
self.subject = Some(subject.into());
self.body = Some(body.into());
self
}
#[must_use]
pub fn idempotency_key(mut self, idempotency_key: impl Into<String>) -> Self {
self.idempotency_key = Some(idempotency_key.into());
self
}
}
#[derive(Debug, Clone, Default)]
pub struct CheckoutReminderListParams {
pub profile_id: Option<String>,
pub limit: Option<u32>,
pub offset: Option<u32>,
}
impl CheckoutReminderListParams {
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn profile_id(mut self, profile_id: impl Into<String>) -> Self {
self.profile_id = Some(profile_id.into());
self
}
#[must_use]
pub fn limit(mut self, limit: u32) -> Self {
self.limit = Some(limit);
self
}
#[must_use]
pub fn offset(mut self, offset: u32) -> Self {
self.offset = Some(offset);
self
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct CandidatePreviewRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub profile_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub rule: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub limit: Option<u32>,
}
impl CandidatePreviewRequest {
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn profile_id(mut self, profile_id: impl Into<String>) -> Self {
self.profile_id = Some(profile_id.into());
self
}
#[must_use]
pub fn rule(mut self, rule: Value) -> Self {
self.rule = Some(rule);
self
}
#[must_use]
pub fn limit(mut self, limit: u32) -> Self {
self.limit = Some(limit);
self
}
}
#[derive(Debug, Clone, Serialize)]
pub struct TestEmailRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub profile_id: Option<String>,
pub scenario: ReminderScenario,
#[serde(skip_serializing_if = "Option::is_none")]
pub language: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub subject: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub body: Option<String>,
}
impl TestEmailRequest {
pub fn new(scenario: ReminderScenario) -> Self {
Self {
profile_id: None,
scenario,
language: None,
subject: None,
body: None,
}
}
#[must_use]
pub fn profile_id(mut self, profile_id: impl Into<String>) -> Self {
self.profile_id = Some(profile_id.into());
self
}
#[must_use]
pub fn language(mut self, language: impl Into<String>) -> Self {
self.language = Some(language.into());
self
}
#[must_use]
pub fn text(mut self, subject: impl Into<String>, body: impl Into<String>) -> Self {
self.subject = Some(subject.into());
self.body = Some(body.into());
self
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::http::mock::{Step, client_with, client_with_retries};
use serde_json::json;
const REMINDER_JSON: &str = r#"{
"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": "2026-01-01T00:00:00Z",
"modified_at": "2026-01-01T00:00:01Z",
"sent_at": "2026-01-01T00:00:01Z",
"surprise_field": "r"
}"#;
fn status_json() -> String {
format!(
r#"{{
"payment_id": "pay_1",
"current_payment_id": "pay_2",
"profile_id": "pro_1",
"rule_enabled": true,
"automatic": "excluded",
"reasons": ["stopped"],
"reminders_sent": 1,
"max_reminders": 3,
"stopped": true,
"stopped_by": "usr_1",
"recipient_unsubscribed": false,
"destination": "new_checkout",
"reminders": [{REMINDER_JSON}],
"surprise_field": 1
}}"#
)
}
#[tokio::test]
async fn retrieve_gets_the_payment_path_encoded() {
let (client, mock) = client_with(vec![Step::ok(&status_json())]);
let out = client.checkout_recovery().retrieve("pay/1").await.unwrap();
assert_eq!(out.current_payment_id, "pay_2");
assert_eq!(out.reasons, ["stopped"]);
assert_eq!(out.max_reminders, 3);
assert_eq!(out.reminders[0].id, "rem_1");
assert_eq!(out.reminders[0].extra["surprise_field"], "r");
assert_eq!(out.extra["surprise_field"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay%2F1"
);
}
#[tokio::test]
async fn stop_posts_without_a_body() {
let (client, mock) = client_with(vec![Step::ok(&status_json())]);
let out = client.checkout_recovery().stop("pay_1").await.unwrap();
assert!(out.stopped);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay_1/stop"
);
assert!(seen[0].body.is_none());
}
#[tokio::test]
async fn resume_posts_without_a_body() {
let (client, mock) = client_with(vec![Step::ok(&status_json())]);
client.checkout_recovery().resume("pay_1").await.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay_1/resume"
);
assert!(seen[0].body.is_none());
}
#[tokio::test]
async fn preview_reactivation_gets_the_reactivation_path() {
let (client, mock) = client_with(vec![Step::ok(
r#"{"payment_id":"pay_1","current_payment_id":"pay_1","profile_id":"pro_1",
"status":"requires_payment_method","available":false,"blocked":"checkout_still_open",
"amount":1999,"currency":"EUR","checkout_expired":false,
"default_validity_seconds":900,"min_validity_seconds":300,"max_validity_seconds":86400,
"reactivations":[{"payment_id":"pay_0","previous_payment_id":"pay_00",
"reactivated_by":"usr_1","reactivated_at":"2026-01-01T00:00:00Z"}],
"surprise_field":true}"#,
)]);
let out = client
.checkout_recovery()
.preview_reactivation("pay_1")
.await
.unwrap();
assert!(!out.available);
assert_eq!(out.blocked.as_deref(), Some("checkout_still_open"));
assert_eq!(out.max_validity_seconds, 86400);
assert_eq!(out.reactivations[0].reactivated_by, "usr_1");
assert_eq!(out.extra["surprise_field"], true);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay_1/reactivation"
);
}
const REACTIVATION_JSON: &str = r#"{"payment_id":"pay_1","previous_payment_id":"pay_1",
"current_payment_id":"pay_2","checkout_url":"https://checkout.test/x",
"already_active":false,"surprise_field":3}"#;
#[tokio::test]
async fn reactivate_posts_the_validity() {
let (client, mock) = client_with(vec![Step::ok(REACTIVATION_JSON)]);
let out = client
.checkout_recovery()
.reactivate(
"pay_1",
&ReactivateCheckoutRequest::new().validity_seconds(3600),
)
.await
.unwrap();
assert_eq!(out.current_payment_id, "pay_2");
assert!(!out.already_active);
assert_eq!(out.extra["surprise_field"], 3);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay_1/reactivate"
);
assert_eq!(seen[0].body_json(), json!({"validity_seconds": 3600}));
}
#[tokio::test]
async fn reactivate_with_defaults_sends_an_empty_object() {
let (client, mock) = client_with(vec![Step::ok(REACTIVATION_JSON)]);
client
.checkout_recovery()
.reactivate("pay_1", &ReactivateCheckoutRequest::new())
.await
.unwrap();
assert_eq!(mock.seen.lock().unwrap()[0].body_json(), json!({}));
}
#[tokio::test]
async fn preview_email_posts_the_message_without_a_key_header() {
let (client, mock) = client_with(vec![Step::ok(
r#"{"scenario":"payment_failed","recipient":"ada@buyer.example","from_name":"Shop",
"language":"de","subject":"S","text_body":"T","html_body":"<p>T</p>",
"link":"https://checkout.test/x","destination":"open_checkout","surprise_field":1}"#,
)]);
let params = ManualEmailRequest::new(ReminderScenario::PaymentFailed)
.language("de")
.text("S", "T");
let out = client
.checkout_recovery()
.preview_email("pay_1", ¶ms)
.await
.unwrap();
assert_eq!(out.language, "de");
assert_eq!(out.destination, "open_checkout");
assert_eq!(out.extra["surprise_field"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay_1/email/preview"
);
assert_eq!(
seen[0].body_json(),
json!({"scenario": "payment_failed", "language": "de", "subject": "S", "body": "T"})
);
assert!(!seen[0].had_idempotency_key());
}
#[tokio::test]
async fn send_email_carries_the_body_key_as_the_idempotency_header() {
let (client, mock) = client_with(vec![Step::ok(REMINDER_JSON)]);
let params = ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout)
.idempotency_key("send-0001");
let out = client
.checkout_recovery()
.send_email("pay/1", ¶ms)
.await
.unwrap();
assert_eq!(out.status, "sent");
assert_eq!(out.extra["surprise_field"], "r");
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/payments/pay%2F1/email"
);
assert_eq!(
seen[0].body_json(),
json!({"scenario": "unfinished_checkout", "idempotency_key": "send-0001"})
);
assert_eq!(seen[0].header("idempotency-key"), Some("send-0001"));
}
#[tokio::test]
async fn send_email_is_retried_after_a_5xx_under_the_same_key() {
let (client, mock) = client_with_retries(
vec![
Step::status(500, r#"{"error":{"message":"boom"}}"#),
Step::ok(REMINDER_JSON),
],
2,
);
let params = ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout)
.idempotency_key("send-0001");
client
.checkout_recovery()
.send_email("pay_1", ¶ms)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen.len(), 2);
assert_eq!(seen[1].header("idempotency-key"), Some("send-0001"));
}
#[tokio::test]
async fn send_email_without_a_key_is_not_retried_after_a_5xx() {
let (client, mock) = client_with_retries(
vec![
Step::status(500, r#"{"error":{"message":"boom"}}"#),
Step::ok(REMINDER_JSON),
],
2,
);
let out = client
.checkout_recovery()
.send_email(
"pay_1",
&ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout),
)
.await;
assert!(out.is_err());
let seen = mock.seen.lock().unwrap();
assert_eq!(seen.len(), 1);
assert!(!seen[0].had_idempotency_key());
}
#[tokio::test]
async fn list_reminders_sends_the_page_query() {
let (client, mock) = client_with(vec![Step::ok(&format!(
r#"{{"data":[{REMINDER_JSON}],"surprise_field":"l"}}"#
))]);
let params = CheckoutReminderListParams::new()
.profile_id("pro_1")
.limit(10)
.offset(20);
let out = client
.checkout_recovery()
.list_reminders(Some(¶ms))
.await
.unwrap();
assert_eq!(out.data[0].scenario, "unfinished_checkout");
assert_eq!(out.extra["surprise_field"], "l");
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/checkout-recovery/reminders?profile_id=pro_1&limit=10&offset=20"
);
}
#[tokio::test]
async fn list_reminders_without_params_sends_no_query() {
let (client, mock) = client_with(vec![Step::ok(r#"{"data":[]}"#)]);
client
.checkout_recovery()
.list_reminders(None)
.await
.unwrap();
assert_eq!(
mock.seen.lock().unwrap()[0].url,
"https://api.test/checkout-recovery/reminders"
);
}
#[tokio::test]
async fn preview_candidates_posts_the_rule() {
let (client, mock) = client_with(vec![Step::ok(
r#"{"evaluated":2,"eligible":1,"purchase_history_complete":true,
"candidates":[{"payment_id":"pay_1","current_payment_id":"pay_1",
"created_at":"2026-01-01T00:00:00Z","amount":100,"test_mode":false,
"automatic":"due","reasons":[]}],"surprise_field":1}"#,
)]);
let params = CandidatePreviewRequest::new()
.profile_id("pro_1")
.rule(json!({"enabled": true}))
.limit(5);
let out = client
.checkout_recovery()
.preview_candidates(¶ms)
.await
.unwrap();
assert_eq!(out.evaluated, 2);
assert_eq!(out.candidates[0].automatic, "due");
assert_eq!(out.extra["surprise_field"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/checkout-recovery/candidates");
assert_eq!(
seen[0].body_json(),
json!({"profile_id": "pro_1", "rule": {"enabled": true}, "limit": 5})
);
}
#[tokio::test]
async fn send_test_email_posts_the_scenario() {
let (client, mock) = client_with(vec![Step::ok(
r#"{"recipient":"me@team.example","sent":true,"surprise_field":1}"#,
)]);
let params = TestEmailRequest::new(ReminderScenario::MethodRestored).profile_id("pro_1");
let out = client
.checkout_recovery()
.send_test_email(¶ms)
.await
.unwrap();
assert!(out.sent);
assert_eq!(out.extra["surprise_field"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/checkout-recovery/test-email");
assert_eq!(
seen[0].body_json(),
json!({"profile_id": "pro_1", "scenario": "method_restored"})
);
}
#[test]
fn manual_email_request_debug_redacts_the_recipient() {
let req = ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout)
.recipient("ada@buyer.example");
let printed = format!("{req:?}");
assert!(!printed.contains("buyer.example"), "{printed}");
assert!(printed.contains("<redacted>"));
}
fn keyed_client_over_503s() -> (
crate::Delopay,
std::sync::Arc<crate::http::mock::MockTransport>,
) {
let (client, mock) = crate::http::mock::client_with_retries(
vec![Step::status(503, "{}"), Step::status(503, "{}")],
2,
);
(client.with_idempotency_key("client-wide-key"), mock)
}
fn assert_sent_once_unkeyed(mock: &crate::http::mock::MockTransport) {
assert_eq!(mock.call_count(), 1, "a 503 was replayed");
assert!(
!mock.seen.lock().unwrap()[0].had_idempotency_key(),
"the client-wide key was inherited"
);
}
#[tokio::test]
async fn new_writes_do_not_inherit_the_client_key() {
let (client, mock) = keyed_client_over_503s();
assert!(client.checkout_recovery().stop("pay_1").await.is_err());
assert_sent_once_unkeyed(&mock);
let (client, mock) = keyed_client_over_503s();
let params = TestEmailRequest::new(ReminderScenario::UnfinishedCheckout);
assert!(
client
.checkout_recovery()
.send_test_email(¶ms)
.await
.is_err()
);
assert_sent_once_unkeyed(&mock);
}
#[tokio::test]
async fn send_email_without_a_body_key_ignores_the_client_key() {
let (client, mock) = keyed_client_over_503s();
let params = ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout);
assert!(
client
.checkout_recovery()
.send_email("pay_1", ¶ms)
.await
.is_err()
);
assert_sent_once_unkeyed(&mock);
}
#[tokio::test]
async fn send_email_with_a_body_key_sends_it_over_the_client_key_and_retries() {
let (client, mock) = crate::http::mock::client_with_retries(
vec![
Step::status(503, "{}"),
Step::status(503, "{}"),
Step::ok(REMINDER_JSON),
],
2,
);
let client = client.with_idempotency_key("client-wide-key");
let params = ManualEmailRequest::new(ReminderScenario::UnfinishedCheckout)
.idempotency_key("send-0002");
let out = client
.checkout_recovery()
.send_email("pay_1", ¶ms)
.await;
assert!(out.is_ok(), "{out:?}");
let seen = mock.seen.lock().unwrap();
assert_eq!(seen.len(), 3);
for attempt in seen.iter() {
assert_eq!(attempt.header("idempotency-key"), Some("send-0002"));
}
}
}