use std::sync::Arc;
use serde::Serialize;
use serde_json::Value;
use crate::core::encoding::{encode_segment, to_json_vec};
use crate::core::error::{DelopayError, Result};
use crate::core::models::buyer_evidence::{BuyerEvidenceQueue, BuyerEvidenceReviewDetail};
use crate::http::client::Inner;
use crate::http::transport::HttpMethod;
use crate::resources::ValidateRequest;
#[derive(Debug, Clone)]
pub struct BuyerEvidenceReviews {
inner: Arc<Inner>,
}
impl BuyerEvidenceReviews {
pub(crate) fn new(inner: Arc<Inner>) -> Self {
Self { inner }
}
pub async fn list(
&self,
params: Option<&BuyerEvidenceQueueParams>,
) -> Result<BuyerEvidenceQueue> {
let query = params
.map(BuyerEvidenceQueueParams::to_query)
.unwrap_or_default();
self.inner
.request(HttpMethod::Get, "/buyer-evidence", None, &query, None)
.await
}
pub async fn retrieve(&self, evidence_id: &str) -> Result<BuyerEvidenceReviewDetail> {
self.inner
.request(
HttpMethod::Get,
&evidence_path(evidence_id),
None,
&[],
None,
)
.await
}
pub async fn download_file(&self, evidence_id: &str, file_id: &str) -> Result<Vec<u8>> {
let path = format!(
"{}/files/{}",
evidence_path(evidence_id),
encode_segment(file_id)
);
self.inner
.request_bytes(HttpMethod::Get, &path, &[], "*/*")
.await
}
pub async fn request_information(
&self,
evidence_id: &str,
params: &BuyerEvidenceInformationRequest,
) -> Result<BuyerEvidenceReviewDetail> {
params.validate()?;
self.post(evidence_id, "information-requests", &to_json_vec(params)?)
.await
}
pub async fn reply(
&self,
evidence_id: &str,
params: &BuyerEvidenceReply,
) -> Result<BuyerEvidenceReviewDetail> {
self.post(evidence_id, "replies", &to_json_vec(params)?)
.await
}
pub async fn review(
&self,
evidence_id: &str,
params: &BuyerEvidenceReviewCreate,
) -> Result<BuyerEvidenceReviewDetail> {
params.validate()?;
self.post(evidence_id, "reviews", &to_json_vec(params)?)
.await
}
pub async fn note(
&self,
evidence_id: &str,
params: &BuyerEvidenceNote,
) -> Result<BuyerEvidenceReviewDetail> {
self.post(evidence_id, "notes", &to_json_vec(params)?).await
}
async fn post(
&self,
evidence_id: &str,
step: &str,
body: &[u8],
) -> Result<BuyerEvidenceReviewDetail> {
let path = format!("{}/{step}", evidence_path(evidence_id));
self.inner
.request_body_keyed(HttpMethod::Post, &path, Some(body), None)
.await
}
}
fn evidence_path(evidence_id: &str) -> String {
format!("/buyer-evidence/{}", encode_segment(evidence_id))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum BuyerEvidenceState {
AwaitingBuyer,
AwaitingReview,
InformationRequested,
Reviewed,
}
impl BuyerEvidenceState {
pub fn as_str(self) -> &'static str {
match self {
Self::AwaitingBuyer => "awaiting_buyer",
Self::AwaitingReview => "awaiting_review",
Self::InformationRequested => "information_requested",
Self::Reviewed => "reviewed",
}
}
}
#[derive(Debug, Clone, Default)]
pub struct BuyerEvidenceQueueParams {
pub state: Option<BuyerEvidenceState>,
pub overdue: Option<bool>,
pub extension_requested: Option<bool>,
pub test_mode: Option<bool>,
pub limit: Option<u32>,
pub offset: Option<u32>,
}
impl BuyerEvidenceQueueParams {
fn to_query(&self) -> Vec<(&'static str, String)> {
let mut q = Vec::new();
if let Some(v) = self.state {
q.push(("state", v.as_str().to_string()));
}
if let Some(v) = self.overdue {
q.push(("overdue", v.to_string()));
}
if let Some(v) = self.extension_requested {
q.push(("extension_requested", v.to_string()));
}
if let Some(v) = self.test_mode {
q.push(("test_mode", v.to_string()));
}
if let Some(v) = self.limit {
q.push(("limit", v.to_string()));
}
if let Some(v) = self.offset {
q.push(("offset", v.to_string()));
}
q
}
}
fn reject_extra_collisions(
extra: &serde_json::Map<String, Value>,
named: &[&str],
type_name: &str,
) -> Result<()> {
for key in extra.keys() {
if named.contains(&key.as_str()) {
return Err(DelopayError::InvalidRequest(format!(
"`extra` key `{key}` collides with a named field on {type_name}"
)));
}
}
Ok(())
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct BuyerEvidenceInformationRequest {
pub question: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub due_at: Option<String>,
#[serde(flatten, skip_serializing_if = "serde_json::Map::is_empty")]
pub extra: serde_json::Map<String, Value>,
}
impl BuyerEvidenceInformationRequest {
pub fn new(question: impl Into<String>) -> Self {
Self {
question: question.into(),
..Default::default()
}
}
#[must_use]
pub fn due_at(mut self, due_at: impl Into<String>) -> Self {
self.due_at = Some(due_at.into());
self
}
}
const BUYER_EVIDENCE_INFORMATION_REQUEST_NAMED: &[&str] = &["question", "due_at"];
impl ValidateRequest for BuyerEvidenceInformationRequest {
fn validate(&self) -> Result<()> {
reject_extra_collisions(
&self.extra,
BUYER_EVIDENCE_INFORMATION_REQUEST_NAMED,
"BuyerEvidenceInformationRequest",
)
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct BuyerEvidenceReply {
pub body: String,
}
impl BuyerEvidenceReply {
pub fn new(body: impl Into<String>) -> Self {
Self { body: body.into() }
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct BuyerEvidenceNote {
pub body: String,
}
impl BuyerEvidenceNote {
pub fn new(body: impl Into<String>) -> Self {
Self { body: body.into() }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum BuyerEvidenceOutcome {
SupportsBuyer,
DoesNotSupportBuyer,
Inconclusive,
}
#[derive(Debug, Clone, Serialize)]
pub struct BuyerEvidenceReviewCreate {
pub outcome: BuyerEvidenceOutcome,
pub response: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub note: Option<String>,
#[serde(flatten, skip_serializing_if = "serde_json::Map::is_empty")]
pub extra: serde_json::Map<String, Value>,
}
impl BuyerEvidenceReviewCreate {
pub fn new(outcome: BuyerEvidenceOutcome, response: impl Into<String>) -> Self {
Self {
outcome,
response: response.into(),
note: None,
extra: serde_json::Map::new(),
}
}
#[must_use]
pub fn note(mut self, note: impl Into<String>) -> Self {
self.note = Some(note.into());
self
}
}
const BUYER_EVIDENCE_REVIEW_CREATE_NAMED: &[&str] = &["outcome", "response", "note"];
impl ValidateRequest for BuyerEvidenceReviewCreate {
fn validate(&self) -> Result<()> {
reject_extra_collisions(
&self.extra,
BUYER_EVIDENCE_REVIEW_CREATE_NAMED,
"BuyerEvidenceReviewCreate",
)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::http::mock::{Step, client_with};
use serde_json::json;
const SUMMARY_FIELDS: &str = r#"
"id": "bev_1", "merchant_id": "mer_1", "profile_id": "pro_1",
"customer_id": "cus_1", "case_kind": "dispute", "case_category": "bank_chargeback",
"case_opened_at": "2026-01-01T00:00:00Z", "test_mode": false,
"state": "awaiting_review", "next_actor": "reviewer", "overdue": false,
"policy_source": "merchant", "created_at": "2026-01-01T00:00:00Z",
"modified_at": "2026-01-02T00:00:00Z""#;
fn detail_json() -> String {
format!(
r#"{{{SUMMARY_FIELDS},
"case": {{"id": "case_1", "kind": "dispute", "category": "bank_chargeback",
"origin": "bank_card_issuer", "state": "open", "next_actor": "merchant",
"outcome": "pending", "shop_name": "Main", "amount": 1500,
"currency": "EUR", "created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-02T00:00:00Z",
"events": [{{"at": "2026-01-01T00:00:00Z", "kind": "opened", "actor": "provider"}}],
"history_complete": true}},
"policy": {{"case_categories": ["dispute"], "max_files": 5,
"max_file_megabytes": 10, "file_types": ["pdf", "png"],
"explanation_required": true, "initial_hours": 72,
"supplement_hours": 48, "review_target_hours": 24,
"merchant_access": "review"}},
"history": [{{"id": "h_1", "kind": "submitted", "actor": "buyer",
"at": "2026-01-01T00:00:00Z", "body": "see receipt",
"files": [{{"id": "f_1", "file_name": "receipt.pdf", "file_type": "pdf",
"size_bytes": 2048, "uploaded_at": "2026-01-01T00:00:00Z",
"submitted": true}}],
"public": true}}],
"files": [{{"id": "f_1", "file_name": "receipt.pdf", "file_type": "pdf",
"size_bytes": 2048, "uploaded_at": "2026-01-01T00:00:00Z",
"submitted": true, "sha256": "ab12"}}],
"detail_surprise": 1}}"#
)
}
#[tokio::test]
async fn list_sends_the_filters() {
let (client, mock) = client_with(vec![Step::ok(&format!(
r#"{{"data":[{{{SUMMARY_FIELDS}, "row_surprise": 1}}],"total":1}}"#
))]);
let params = BuyerEvidenceQueueParams {
state: Some(BuyerEvidenceState::AwaitingReview),
overdue: Some(true),
test_mode: Some(false),
limit: Some(10),
..Default::default()
};
let queue = client
.buyer_evidence_reviews()
.list(Some(¶ms))
.await
.unwrap();
assert_eq!(queue.total, 1);
assert_eq!(queue.data[0].state, "awaiting_review");
assert_eq!(queue.data[0].extra["row_surprise"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/buyer-evidence?state=awaiting_review&overdue=true\
&test_mode=false&limit=10"
);
}
#[tokio::test]
async fn retrieve_encodes_the_evidence_id() {
let (client, mock) = client_with(vec![Step::ok(&detail_json())]);
let detail = client
.buyer_evidence_reviews()
.retrieve("bev/1")
.await
.unwrap();
assert_eq!(detail.policy.max_files, 5);
assert_eq!(detail.history[0].files[0].size_bytes, 2048);
assert_eq!(detail.files[0].sha256, "ab12");
assert_eq!(detail.case.as_ref().unwrap()["id"], "case_1");
assert_eq!(detail.extra["detail_surprise"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(seen[0].url, "https://api.test/buyer-evidence/bev%2F1");
}
#[tokio::test]
async fn download_file_returns_the_bytes_of_the_encoded_file() {
let (client, mock) = client_with(vec![Step::ok("%PDF-1.4")]);
let bytes = client
.buyer_evidence_reviews()
.download_file("bev_1", "f/1")
.await
.unwrap();
assert_eq!(bytes, b"%PDF-1.4");
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(
seen[0].url,
"https://api.test/buyer-evidence/bev_1/files/f%2F1"
);
assert_eq!(seen[0].header("accept"), Some("*/*"));
}
#[tokio::test]
async fn request_information_posts_the_question() {
let (client, mock) = client_with(vec![Step::ok(&detail_json())]);
let req = BuyerEvidenceInformationRequest::new("Can you send the tracking number?")
.due_at("2026-01-05T00:00:00Z");
client
.buyer_evidence_reviews()
.request_information("bev_1", &req)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(
seen[0].url,
"https://api.test/buyer-evidence/bev_1/information-requests"
);
assert_eq!(
seen[0].body_json(),
json!({"question": "Can you send the tracking number?", "due_at": "2026-01-05T00:00:00Z"})
);
}
#[tokio::test]
async fn reply_posts_to_the_replies_path() {
let (client, mock) = client_with(vec![Step::ok(&detail_json())]);
client
.buyer_evidence_reviews()
.reply("bev_1", &BuyerEvidenceReply::new("Thanks, reviewing"))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/buyer-evidence/bev_1/replies");
assert_eq!(seen[0].body_json(), json!({"body": "Thanks, reviewing"}));
}
#[tokio::test]
async fn review_posts_the_outcome() {
let (client, mock) = client_with(vec![Step::ok(&detail_json())]);
let req = BuyerEvidenceReviewCreate::new(
BuyerEvidenceOutcome::DoesNotSupportBuyer,
"The parcel was delivered",
)
.note("carrier proof attached");
client
.buyer_evidence_reviews()
.review("bev_1", &req)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/buyer-evidence/bev_1/reviews");
assert_eq!(
seen[0].body_json(),
json!({
"outcome": "does_not_support_buyer",
"response": "The parcel was delivered",
"note": "carrier proof attached"
})
);
}
#[tokio::test]
async fn note_posts_to_the_notes_path() {
let (client, mock) = client_with(vec![Step::ok(&detail_json())]);
client
.buyer_evidence_reviews()
.note("bev_1", &BuyerEvidenceNote::new("internal"))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/buyer-evidence/bev_1/notes");
assert_eq!(seen[0].body_json(), json!({"body": "internal"}));
}
fn assert_named_complete<T: Serialize>(req: &T, named: &[&str]) {
let value = serde_json::to_value(req).unwrap();
for key in value.as_object().expect("serializes to an object").keys() {
assert!(
named.contains(&key.as_str()),
"NAMED is missing wire key `{key}`"
);
}
}
#[test]
fn buyer_evidence_information_request_named_fields_are_complete() {
let req = BuyerEvidenceInformationRequest::new("q").due_at("2026-01-05T00:00:00Z");
assert_named_complete(&req, BUYER_EVIDENCE_INFORMATION_REQUEST_NAMED);
}
#[test]
fn buyer_evidence_review_create_named_fields_are_complete() {
let req = BuyerEvidenceReviewCreate::new(BuyerEvidenceOutcome::Inconclusive, "r").note("n");
assert_named_complete(&req, BUYER_EVIDENCE_REVIEW_CREATE_NAMED);
}
#[test]
fn review_validate_rejects_colliding_extra_key() {
let mut req = BuyerEvidenceReviewCreate::new(BuyerEvidenceOutcome::SupportsBuyer, "r");
req.extra
.insert("outcome".to_string(), json!("inconclusive"));
match req.validate().unwrap_err() {
DelopayError::InvalidRequest(msg) => assert!(msg.contains("outcome")),
other => panic!("expected InvalidRequest, got {other:?}"),
}
}
#[tokio::test]
async fn writes_ignore_the_client_wide_idempotency_key() {
let steps = (0..4)
.map(|_| Step::status(503, r#"{"error":{"message":"down"}}"#))
.collect();
let (client, mock) = crate::http::mock::client_with_retries(steps, 2);
let client = client.with_idempotency_key("client-key");
client
.buyer_evidence_reviews()
.request_information("bev_1", &BuyerEvidenceInformationRequest::new("q"))
.await
.unwrap_err();
client
.buyer_evidence_reviews()
.reply("bev_1", &BuyerEvidenceReply::new("r"))
.await
.unwrap_err();
client
.buyer_evidence_reviews()
.review(
"bev_1",
&BuyerEvidenceReviewCreate::new(BuyerEvidenceOutcome::Inconclusive, "r"),
)
.await
.unwrap_err();
client
.buyer_evidence_reviews()
.note("bev_1", &BuyerEvidenceNote::new("n"))
.await
.unwrap_err();
assert_eq!(mock.call_count(), 4);
for seen in mock.seen.lock().unwrap().iter() {
assert!(
!seen.had_idempotency_key(),
"{} sent the client key",
seen.url
);
}
}
}