Enhance fraud protection reporting with event source tracking

This update modifies the `wc_fraud_protection_report` function and the `fraud_protection_report` method in the `OrderEventsTracker` class to include a new parameter for the event source, utilizing constants from the `ApiClient`. Additionally, the implementation now validates the source against predefined constants, logging warnings for invalid sources. Unit tests have been updated to reflect these changes, ensuring robust coverage for the new functionality.

Author: leonardola

src/ApiClient.php

@@ -95,6 +95,32 @@ class ApiClient {
 		self::REPORT_STATUS_BAD,
 	);
 
+	/**
+	 * Report source: chargeback event.
+	 */
+	public const REPORT_SOURCE_CHARGEBACK = 'chargeback';
+
+	/**
+	 * Report source: manual review outcome.
+	 */
+	public const REPORT_SOURCE_MANUAL_REVIEW = 'manual_review';
+
+	/**
+	 * Report source: API-driven event.
+	 */
+	public const REPORT_SOURCE_API = 'api';
+
+	/**
+	 * Valid report source values.
+	 *
+	 * @var array<string>
+	 */
+	public const VALID_REPORT_SOURCES = array(
+		self::REPORT_SOURCE_CHARGEBACK,
+		self::REPORT_SOURCE_MANUAL_REVIEW,
+		self::REPORT_SOURCE_API,
+	);
+
 	/**
 	 * Verify a session with the Blackbox API and get a fraud decision.
 	 *

src/OrderEventsTracker.php

@@ -53,11 +53,20 @@ public function register(): void {}
 	 *
 	 * @internal
 	 * @param \WC_Order $order  The order to report on.
+	 * @param string    $source The source of the event. Use ApiClient::REPORT_SOURCE_* constants.
 	 * @param string    $status The status of the event. Use ApiClient::REPORT_STATUS_GOOD or ApiClient::REPORT_STATUS_BAD.
 	 * @param string    $notes  The notes of the event.
 	 */
-	public function fraud_protection_report( \WC_Order $order, string $status, string $notes ): void {
+	public function fraud_protection_report( \WC_Order $order, string $source, string $status, string $notes ): void {
 		try {
+			if ( ! in_array( $source, ApiClient::VALID_REPORT_SOURCES, true ) ) {
+				FraudProtectionController::log(
+					'warning',
+					sprintf( 'Invalid report source "%s", skipping report.', $source )
+				);
+				return;
+			}
+
 			if ( ! in_array( $status, ApiClient::VALID_REPORT_STATUSES, true ) ) {
 				FraudProtectionController::log(
 					'warning',
@@ -79,7 +88,7 @@ public function fraud_protection_report( \WC_Order $order, string $status, strin
 				$session_id,
 				array(
 					'label'  => $status,
-					'source' => 'payment_gateway_event',
+					'source' => $source,
 					'notes'  => sanitize_text_field( $notes ),
 				)
 			);

tests/php/src/OrderEventsTrackerTest.php

@@ -69,12 +69,12 @@ public function test_fraud_protection_report_reports_when_session_id_exists(): v
 				'bb-session-123',
 				array(
 					'label'  => 'bad',
-					'source' => 'payment_gateway_event',
+					'source' => ApiClient::REPORT_SOURCE_API,
 					'notes'  => 'Payment failed via Stripe.',
 				)
 			);
 
-		$this->sut->fraud_protection_report( $order, 'bad', 'Payment failed via Stripe.' );
+		$this->sut->fraud_protection_report( $order, ApiClient::REPORT_SOURCE_API, 'bad', 'Payment failed via Stripe.' );
 	}
 
 	/**
@@ -92,12 +92,12 @@ public function test_fraud_protection_report_reports_good_status(): void {
 				'bb-session-456',
 				array(
 					'label'  => 'good',
-					'source' => 'payment_gateway_event',
+					'source' => ApiClient::REPORT_SOURCE_API,
 					'notes'  => 'Payment completed successfully.',
 				)
 			);
 
-		$this->sut->fraud_protection_report( $order, 'good', 'Payment completed successfully.' );
+		$this->sut->fraud_protection_report( $order, ApiClient::REPORT_SOURCE_API, 'good', 'Payment completed successfully.' );
 	}
 
 	/**
@@ -110,7 +110,7 @@ public function test_fraud_protection_report_skips_when_no_session_id(): void {
 			->expects( $this->never() )
 			->method( 'report' );
 
-		$this->sut->fraud_protection_report( $order, 'bad', 'Some notes.' );
+		$this->sut->fraud_protection_report( $order, ApiClient::REPORT_SOURCE_API, 'bad', 'Some notes.' );
 	}
 
 	/**
@@ -125,11 +125,28 @@ public function test_fraud_protection_report_skips_when_invalid_status(): void {
 			->expects( $this->never() )
 			->method( 'report' );
 
-		$this->sut->fraud_protection_report( $order, 'invalid_status', 'Some notes.' );
+		$this->sut->fraud_protection_report( $order, ApiClient::REPORT_SOURCE_API, 'invalid_status', 'Some notes.' );
 
 		$this->assertLogged( 'warning', 'Invalid report status "invalid_status", skipping report.' );
 	}
 
+	/**
+	 * @testdox fraud_protection_report() skips reporting and logs warning when source is invalid.
+	 */
+	public function test_fraud_protection_report_skips_when_invalid_source(): void {
+		$order = \WC_Helper_Order::create_order();
+		$order->update_meta_data( SessionVerifier::ORDER_BLACKBOX_SESSION_ID_KEY, 'bb-session-123' );
+		$order->save_meta_data();
+
+		$this->api_client
+			->expects( $this->never() )
+			->method( 'report' );
+
+		$this->sut->fraud_protection_report( $order, 'invalid_source', 'bad', 'Some notes.' );
+
+		$this->assertLogged( 'warning', 'Invalid report source "invalid_source", skipping report.' );
+	}
+
 	/**
 	 * @testdox fraud_protection_report() catches exceptions and logs error.
 	 */
@@ -142,7 +159,7 @@ public function test_fraud_protection_report_catches_exceptions(): void {
 			->method( 'report' )
 			->willThrowException( new \RuntimeException( 'API connection failed' ) );
 
-		$this->sut->fraud_protection_report( $order, 'bad', 'Payment failed.' );
+		$this->sut->fraud_protection_report( $order, ApiClient::REPORT_SOURCE_API, 'bad', 'Payment failed.' );
 
 		$this->assertLogged( 'error', 'Failed to report 3rd party event to Blackbox API: API connection failed' );
 	}

woocommerce-fraud-protection.php

@@ -142,13 +142,14 @@ function () {
  * (i.e. after `woocommerce_store_api_checkout_order_processed`).
  *
  * @param \WC_Order $order  The order to report on.
+ * @param string    $source The source of the event. Use ApiClient::REPORT_SOURCE_* constants.
  * @param string    $status The status of the event. Use ApiClient::REPORT_STATUS_GOOD or ApiClient::REPORT_STATUS_BAD.
  * @param string    $notes  Free-form notes describing the event.
  */
-function wc_fraud_protection_report( \WC_Order $order, string $status, string $notes ): void {
+function wc_fraud_protection_report( \WC_Order $order, string $source, string $status, string $notes ): void {
 	$api_client = new \Automattic\WooCommerce\FraudProtection\ApiClient();
 
 	$order_events_tracker = new \Automattic\WooCommerce\FraudProtection\OrderEventsTracker();
 	$order_events_tracker->init( $api_client );
-	$order_events_tracker->fraud_protection_report( $order, $status, $notes );
+	$order_events_tracker->fraud_protection_report( $order, $source, $status, $notes );
 }