use std::sync::Arc;
use serde::Serialize;
use crate::core::encoding::{encode_segment, to_json_vec};
use crate::core::error::{DelopayError, Result};
use crate::core::models::risk::{
MerchantRiskResponse, RiskAdjustments, RiskTuningPreviewResponse, RiskTuningResponse,
ShopRiskResponse,
};
use crate::http::client::Inner;
use crate::http::transport::HttpMethod;
use crate::resources::ValidateRequest;
#[derive(Debug, Clone)]
pub struct Risk {
inner: Arc<Inner>,
}
impl Risk {
pub(crate) fn new(inner: Arc<Inner>) -> Self {
Self { inner }
}
pub async fn retrieve(&self) -> Result<MerchantRiskResponse> {
self.inner
.request(HttpMethod::Get, "/risk", None, &[], None)
.await
}
pub async fn retrieve_shop(&self, profile_id: &str) -> Result<ShopRiskResponse> {
let path = format!("/risk/shops/{}", encode_segment(profile_id));
self.inner
.request(HttpMethod::Get, &path, None, &[], None)
.await
}
pub async fn retrieve_tuning(&self, target: &RiskTuningTarget) -> Result<RiskTuningResponse> {
self.inner
.request(HttpMethod::Get, &target.path(), None, &[], None)
.await
}
pub async fn update_tuning(
&self,
target: &RiskTuningTarget,
params: &RiskTuningUpdateRequest,
) -> Result<RiskTuningResponse> {
params.adjustments.validate()?;
let body = to_json_vec(params)?;
self.inner
.request_body_keyed(HttpMethod::Put, &target.path(), Some(&body), None)
.await
}
pub async fn reset_tuning(
&self,
target: &RiskTuningTarget,
expected_revision: i64,
) -> Result<RiskTuningResponse> {
self.inner
.request_body_keyed_with_query(
HttpMethod::Delete,
&target.path(),
None,
&[("expected_revision", expected_revision.to_string())],
None,
)
.await
}
pub async fn preview_tuning(
&self,
target: &RiskTuningTarget,
adjustments: &RiskAdjustments,
) -> Result<RiskTuningPreviewResponse> {
adjustments.validate()?;
let path = format!("{}/preview", target.path());
let body = to_json_vec(&PreviewBody { adjustments })?;
self.inner
.request_body_keyed(HttpMethod::Post, &path, Some(&body), None)
.await
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum RiskTuningTarget {
Merchant,
Project(String),
Shop(String),
}
impl RiskTuningTarget {
fn path(&self) -> String {
match self {
Self::Merchant => "/risk/tuning".to_string(),
Self::Project(id) => format!("/risk/tuning/projects/{}", encode_segment(id)),
Self::Shop(id) => format!("/risk/tuning/shops/{}", encode_segment(id)),
}
}
}
#[derive(Debug, Clone, Default, Serialize)]
pub struct RiskTuningUpdateRequest {
pub adjustments: RiskAdjustments,
pub expected_revision: i64,
}
impl RiskTuningUpdateRequest {
pub fn new(adjustments: RiskAdjustments, expected_revision: i64) -> Self {
Self {
adjustments,
expected_revision,
}
}
}
#[derive(Serialize)]
struct PreviewBody<'a> {
adjustments: &'a RiskAdjustments,
}
const RISK_ADJUSTMENTS_NAMED: &[&str] = &["deciding_window", "bands", "min_volume", "components"];
impl ValidateRequest for RiskAdjustments {
fn validate(&self) -> Result<()> {
for key in self.extra.keys() {
if RISK_ADJUSTMENTS_NAMED.contains(&key.as_str()) {
return Err(DelopayError::InvalidRequest(format!(
"`extra` key `{key}` collides with a named field on RiskAdjustments"
)));
}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::core::models::risk::{RiskBands, RiskComponentAdjustment, RiskWindowBandOverrides};
use crate::http::mock::{Step, client_with, client_with_retries};
use serde_json::json;
const SHOP_JSON: &str = r#"{
"shop_id": "pro_1", "computed_at": "2026-01-01T00:00:00Z",
"connectors": [{
"connector": "stripe", "band": "watch", "index": 42, "trend": "up",
"model_version": 3, "computed_at": "2026-01-01T00:00:00Z",
"components": [{"name": "dispute_rate", "weight": 0.4}],
"assessment": "reference",
"adjusted_unavailable": {"reason": "window_unavailable", "adjustment_revision": 0},
"card_testing_incidents": [{
"started_at": "2026-01-01T00:00:00Z", "ended_at": "2026-01-01T00:10:00Z",
"window_minutes": 10, "attempts": 120, "refusals": 100,
"distinct_cards": 90, "thresholds": {"min_refusals": 10, "min_refusal_share": 0.5},
"model_version": 3, "first_detected_at": "2026-01-01T00:05:00Z",
"last_detected_at": "2026-01-01T00:10:00Z"
}],
"connector_surprise": 1
}],
"shop_surprise": 2
}"#;
#[tokio::test]
async fn retrieve_gets_the_merchant_roll_up() {
let (client, mock) = client_with(vec![Step::ok(&format!(
r#"{{"merchant_id":"mer_1","worst_band":"watch","shops":[{SHOP_JSON}],"x":1}}"#
))]);
let risk = client.risk().retrieve().await.unwrap();
assert_eq!(risk.merchant_id, "mer_1");
assert_eq!(risk.worst_band.as_deref(), Some("watch"));
assert_eq!(risk.shops[0].connectors[0].index, Some(42));
assert_eq!(risk.extra["x"], 1);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(seen[0].url, "https://api.test/risk");
}
#[tokio::test]
async fn retrieve_shop_encodes_the_profile_id() {
let (client, mock) = client_with(vec![Step::ok(SHOP_JSON)]);
let shop = client.risk().retrieve_shop("pro/1").await.unwrap();
let connector = &shop.connectors[0];
assert_eq!(connector.band, "watch");
assert_eq!(connector.model_version, 3);
assert_eq!(connector.components[0]["name"], "dispute_rate");
assert_eq!(
connector.adjusted_unavailable.as_ref().unwrap().reason,
"window_unavailable"
);
assert_eq!(connector.card_testing_incidents[0].refusals, 100);
assert_eq!(connector.extra["connector_surprise"], 1);
assert_eq!(shop.extra["shop_surprise"], 2);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(seen[0].url, "https://api.test/risk/shops/pro%2F1");
}
const TUNING_JSON: &str = r#"{
"scope": "shop", "scope_id": "pro_1",
"adjustments": {"deciding_window": "worst_of", "min_volume": 50,
"components": {"dispute_rate": {"threshold": 0.0075}},
"future_knob": 3},
"revision": 7, "updated_at": "2026-01-01T00:00:00Z",
"updated_by": {"id": "user_1", "name": "owner@example.com"},
"reference": {"model_version": 3, "settings": {"deciding_window": "worst_of",
"bands": {"30d": {"watch": 40, "at_risk": 65, "critical": 85},
"60d": {"watch": 40, "at_risk": 65, "critical": 85},
"90d": {"watch": 40, "at_risk": 65, "critical": 85}},
"min_volume": 20},
"components": {"dispute_rate": {"default": {"threshold": 0.0075, "weight": 0.4}}}},
"effective": {"settings": {"deciding_window": "worst_of",
"bands": {"30d": {"watch": 40, "at_risk": 65, "critical": 85},
"60d": {"watch": 40, "at_risk": 65, "critical": 85},
"90d": {"watch": 40, "at_risk": 65, "critical": 85}},
"min_volume": 50},
"sources": {"deciding_window": "shop",
"bands": {"30d": "reference", "60d": "reference", "90d": "reference"},
"min_volume": "shop"}},
"recompute_pending": true, "tuning_surprise": 1
}"#;
fn adjustments() -> RiskAdjustments {
RiskAdjustments::new()
.deciding_window("30d")
.bands(RiskWindowBandOverrides {
d30: Some(RiskBands::new(40, 65, 85)),
..Default::default()
})
.min_volume(25)
.component(
"refund_rate",
RiskComponentAdjustment {
weight: Some(0.0),
..Default::default()
},
)
}
#[tokio::test]
async fn retrieve_tuning_gets_each_scopes_path() {
let (client, mock) = client_with(vec![
Step::ok(TUNING_JSON),
Step::ok(TUNING_JSON),
Step::ok(TUNING_JSON),
]);
let tuning = client
.risk()
.retrieve_tuning(&RiskTuningTarget::Merchant)
.await
.unwrap();
assert_eq!(tuning.revision, 7);
assert!(tuning.recompute_pending);
assert_eq!(tuning.adjustments.min_volume, Some(50));
assert_eq!(
tuning.adjustments.components["dispute_rate"].threshold,
Some(0.0075)
);
assert_eq!(tuning.adjustments.extra["future_knob"], 3);
assert_eq!(tuning.extra["tuning_surprise"], 1);
assert!(!format!("{tuning:?}").contains("owner@example.com"));
client
.risk()
.retrieve_tuning(&RiskTuningTarget::Project("prj/1".to_string()))
.await
.unwrap();
client
.risk()
.retrieve_tuning(&RiskTuningTarget::Shop("pro_1".to_string()))
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "GET");
assert_eq!(seen[0].url, "https://api.test/risk/tuning");
assert_eq!(seen[1].url, "https://api.test/risk/tuning/projects/prj%2F1");
assert_eq!(seen[2].url, "https://api.test/risk/tuning/shops/pro_1");
}
#[tokio::test]
async fn update_tuning_puts_the_adjustments_and_expected_revision() {
let (client, mock) = client_with(vec![Step::ok(TUNING_JSON)]);
let req = RiskTuningUpdateRequest::new(adjustments(), 7);
client
.risk()
.update_tuning(&RiskTuningTarget::Shop("pro_1".to_string()), &req)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "PUT");
assert_eq!(seen[0].url, "https://api.test/risk/tuning/shops/pro_1");
assert_eq!(
seen[0].body_json(),
json!({
"adjustments": {
"deciding_window": "30d",
"bands": {"30d": {"watch": 40, "at_risk": 65, "critical": 85}},
"min_volume": 25,
"components": {"refund_rate": {"weight": 0.0}}
},
"expected_revision": 7
})
);
}
#[tokio::test]
async fn update_tuning_saves_back_fields_it_read_but_does_not_model() {
let (client, mock) = client_with(vec![Step::ok(TUNING_JSON), Step::ok(TUNING_JSON)]);
let target = RiskTuningTarget::Merchant;
let read = client.risk().retrieve_tuning(&target).await.unwrap();
let req = RiskTuningUpdateRequest::new(read.adjustments.min_volume(60), read.revision);
client.risk().update_tuning(&target, &req).await.unwrap();
let seen = mock.seen.lock().unwrap();
let body = seen[1].body_json();
assert_eq!(body["adjustments"]["future_knob"], 3);
assert_eq!(body["adjustments"]["min_volume"], 60);
assert_eq!(body["expected_revision"], 7);
}
#[tokio::test]
async fn update_tuning_surfaces_a_stale_revision_as_ir_16_without_retrying() {
let (client, mock) = client_with_retries(
vec![Step::status(
400,
r#"{"error":{"code":"IR_16","type":"invalid_request","message":"The revision moved"}}"#,
)],
2,
);
let req = RiskTuningUpdateRequest::new(RiskAdjustments::new(), 6);
let err = client
.risk()
.update_tuning(&RiskTuningTarget::Merchant, &req)
.await
.unwrap_err();
match err {
DelopayError::Api(api) => {
assert_eq!(api.status, 400);
assert_eq!(api.code, "IR_16");
}
other => panic!("expected Api, got {other:?}"),
}
assert_eq!(mock.call_count(), 1);
}
#[tokio::test]
async fn update_tuning_is_not_retried_on_5xx() {
let (client, mock) = client_with_retries(
vec![Step::status(500, r#"{"error":{"message":"boom"}}"#)],
2,
);
let req = RiskTuningUpdateRequest::new(RiskAdjustments::new(), 1);
client
.risk()
.update_tuning(&RiskTuningTarget::Merchant, &req)
.await
.unwrap_err();
assert_eq!(mock.call_count(), 1);
}
#[tokio::test]
async fn reset_tuning_deletes_with_the_expected_revision() {
let (client, mock) = client_with(vec![Step::ok(TUNING_JSON), Step::ok(TUNING_JSON)]);
client
.risk()
.reset_tuning(&RiskTuningTarget::Merchant, 7)
.await
.unwrap();
client
.risk()
.reset_tuning(&RiskTuningTarget::Project("prj_1".to_string()), 2)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "DELETE");
assert_eq!(
seen[0].url,
"https://api.test/risk/tuning?expected_revision=7"
);
assert!(seen[0].body.is_none());
assert_eq!(
seen[1].url,
"https://api.test/risk/tuning/projects/prj_1?expected_revision=2"
);
}
#[tokio::test]
async fn preview_tuning_posts_the_adjustments_under_the_preview_path() {
let (client, mock) = client_with(vec![
Step::ok(
r#"{"scope":"merchant","scope_id":"mer_1","shops":[{"shop_id":"pro_1",
"connectors":[{"connector":"stripe","reference":{"band":"watch","risk_index":45},
"current":{"band":"watch","risk_index":45},
"proposed":{"band":"healthy","risk_index":30},"x":1}]}],
"evidence_until":"2026-10-27","model_version":3,"y":2}"#,
),
Step::ok(
r#"{"scope":"shop","scope_id":"pro_1","shops":[{"shop_id":"pro_1",
"connectors":[{"connector":"paypal","unavailable":"no_evidence"}]}],
"evidence_until":"2026-10-27","model_version":3}"#,
),
]);
let out = client
.risk()
.preview_tuning(&RiskTuningTarget::Merchant, &adjustments())
.await
.unwrap();
let connector = &out.shops[0].connectors[0];
assert_eq!(connector.proposed.as_ref().unwrap().band, "healthy");
assert_eq!(connector.reference.as_ref().unwrap().risk_index, Some(45));
assert_eq!(connector.extra["x"], 1);
assert_eq!(out.extra["y"], 2);
let shop = client
.risk()
.preview_tuning(
&RiskTuningTarget::Shop("pro/1".to_string()),
&RiskAdjustments::new(),
)
.await
.unwrap();
assert_eq!(
shop.shops[0].connectors[0].unavailable.as_deref(),
Some("no_evidence")
);
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].method, "POST");
assert_eq!(seen[0].url, "https://api.test/risk/tuning/preview");
assert_eq!(seen[0].body_json()["adjustments"]["min_volume"], 25);
assert_eq!(
seen[1].url,
"https://api.test/risk/tuning/shops/pro%2F1/preview"
);
assert_eq!(seen[1].body_json(), json!({"adjustments": {}}));
}
#[test]
fn risk_adjustments_named_fields_are_complete() {
let value = serde_json::to_value(adjustments()).unwrap();
for key in value.as_object().expect("serializes to an object").keys() {
assert!(
RISK_ADJUSTMENTS_NAMED.contains(&key.as_str()),
"RISK_ADJUSTMENTS_NAMED is missing wire key `{key}`"
);
}
}
#[test]
fn adjustments_validate_rejects_colliding_extra_key() {
let mut adj = RiskAdjustments::new();
adj.extra.insert("min_volume".to_string(), json!(5));
match adj.validate().unwrap_err() {
DelopayError::InvalidRequest(msg) => assert!(msg.contains("min_volume")),
other => panic!("expected InvalidRequest, got {other:?}"),
}
}
#[tokio::test]
async fn writes_ignore_the_client_wide_idempotency_key() {
let steps = (0..3)
.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
.risk()
.update_tuning(
&RiskTuningTarget::Merchant,
&RiskTuningUpdateRequest::new(RiskAdjustments::new(), 1),
)
.await
.unwrap_err();
client
.risk()
.reset_tuning(&RiskTuningTarget::Shop("pro_1".to_string()), 1)
.await
.unwrap_err();
client
.risk()
.preview_tuning(&RiskTuningTarget::Merchant, &RiskAdjustments::new())
.await
.unwrap_err();
assert_eq!(mock.call_count(), 3);
for seen in mock.seen.lock().unwrap().iter() {
assert!(
!seen.had_idempotency_key(),
"{} sent the client key",
seen.url
);
}
}
#[tokio::test]
async fn writes_are_not_retried_after_a_network_error_with_a_client_key() {
let steps = (0..3)
.map(|_| Step::Fail(crate::http::transport::TransportErrorKind::Connect))
.collect();
let (client, mock) = crate::http::mock::client_with_retries(steps, 2);
let client = client.with_idempotency_key("client-key");
client
.risk()
.update_tuning(
&RiskTuningTarget::Merchant,
&RiskTuningUpdateRequest::new(RiskAdjustments::new(), 4),
)
.await
.unwrap_err();
client
.risk()
.reset_tuning(&RiskTuningTarget::Shop("pro_1".to_string()), 4)
.await
.unwrap_err();
client
.risk()
.preview_tuning(&RiskTuningTarget::Merchant, &RiskAdjustments::new())
.await
.unwrap_err();
assert_eq!(mock.call_count(), 3);
let seen = mock.seen.lock().unwrap();
for request in seen.iter() {
assert!(
!request.had_idempotency_key(),
"{} sent the client key",
request.url
);
}
assert_eq!(
(seen[0].method, seen[0].url.as_str()),
("PUT", "https://api.test/risk/tuning")
);
assert_eq!(
(seen[1].method, seen[1].url.as_str()),
(
"DELETE",
"https://api.test/risk/tuning/shops/pro_1?expected_revision=4"
)
);
assert_eq!(
(seen[2].method, seen[2].url.as_str()),
("POST", "https://api.test/risk/tuning/preview")
);
}
}