feat: Add API endpoints for retrieving minimum ROAS of products and average minimum ROAS for clients, including detailed documentation

api.php

@@ -71,6 +71,37 @@ function api_get_product_by_offer_and_client( $mdb, $offer_id, $client_id )
   ) -> fetch( \PDO::FETCH_ASSOC );
 }
 
+function api_get_product_by_id_or_offer_id( $mdb, $product_id, $offer_id )
+{
+  if ( $product_id > 0 )
+  {
+    return $mdb -> query(
+      'SELECT p.id, p.offer_id, p.min_roas
+       FROM products p
+       WHERE p.id = :product_id
+       LIMIT 1',
+      [
+        ':product_id' => (int) $product_id
+      ]
+    ) -> fetch( \PDO::FETCH_ASSOC );
+  }
+
+  if ( $offer_id !== '' )
+  {
+    return $mdb -> query(
+      'SELECT p.id, p.offer_id, p.min_roas
+       FROM products p
+       WHERE p.offer_id = :offer_id
+       LIMIT 1',
+      [
+        ':offer_id' => (string) $offer_id
+      ]
+    ) -> fetch( \PDO::FETCH_ASSOC );
+  }
+
+  return null;
+}
+
 function api_normalize_product_text( $value )
 {
   $value = trim( (string) $value );
@@ -340,6 +371,117 @@ if ( \S::get( 'action' ) == 'product_google_category_get' )
   ] );
 }
 
+// Odczyt minimalnego ROAS produktu przez API
+if ( \S::get( 'action' ) == 'product_min_roas_get' )
+{
+  api_validate_api_key( $mdb );
+
+  $product_id = (int) \S::get( 'product_id' );
+  $google_ads_product_id = trim( (string) \S::get( 'google_ads_product_id' ) );
+
+  if ( $product_id <= 0 && $google_ads_product_id === '' )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Missing required param: product_id or google_ads_product_id' ], 422 );
+  }
+
+  if ( $product_id > 0 && $google_ads_product_id !== '' )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Provide only one identifier: product_id or google_ads_product_id' ], 422 );
+  }
+
+  $product = api_get_product_by_id_or_offer_id( $mdb, $product_id, $google_ads_product_id );
+
+  if ( !$product )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Product not found' ], 404 );
+  }
+
+  $min_roas_raw = $product['min_roas'] ?? null;
+  $min_roas = $min_roas_raw !== null && $min_roas_raw !== '' ? (float) $min_roas_raw : null;
+
+  api_json_response( [
+    'result' => 'ok',
+    'product_id' => (int) $product['id'],
+    'offer_id' => (string) ( $product['offer_id'] ?? '' ),
+    'min_roas' => $min_roas
+  ] );
+}
+
+// Odczyt sredniego minimalnego ROAS dla klienta
+if ( \S::get( 'action' ) == 'client_avg_min_roas_get' )
+{
+  api_validate_api_key( $mdb );
+
+  $client_id = (int) \S::get( 'client_id' );
+  $google_ads_id = trim( (string) \S::get( 'google_ads_id' ) );
+
+  if ( $client_id <= 0 && $google_ads_id === '' )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Missing required param: client_id or google_ads_id' ], 422 );
+  }
+
+  if ( $client_id > 0 && $google_ads_id !== '' )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Provide only one identifier: client_id or google_ads_id' ], 422 );
+  }
+
+  $resolved_client = null;
+
+  if ( $client_id > 0 )
+  {
+    $resolved_client = $mdb -> query(
+      'SELECT id, google_ads_customer_id
+       FROM clients
+       WHERE id = :client_id
+       LIMIT 1',
+      [
+        ':client_id' => $client_id
+      ]
+    ) -> fetch( \PDO::FETCH_ASSOC );
+  }
+  else
+  {
+    $google_ads_id_clean = str_replace( '-', '', $google_ads_id );
+    $resolved_client = $mdb -> query(
+      'SELECT id, google_ads_customer_id
+       FROM clients
+       WHERE REPLACE( google_ads_customer_id, \'-\', \'\' ) = :google_ads_id
+       LIMIT 1',
+      [
+        ':google_ads_id' => $google_ads_id_clean
+      ]
+    ) -> fetch( \PDO::FETCH_ASSOC );
+  }
+
+  if ( !$resolved_client )
+  {
+    api_json_response( [ 'result' => 'error', 'message' => 'Client not found' ], 404 );
+  }
+
+  $avg_row = $mdb -> query(
+    'SELECT AVG( p.min_roas ) AS avg_min_roas,
+            COUNT( p.id ) AS products_with_min_roas
+     FROM products p
+     WHERE p.client_id = :client_id
+       AND p.min_roas IS NOT NULL',
+    [
+      ':client_id' => (int) $resolved_client['id']
+    ]
+  ) -> fetch( \PDO::FETCH_ASSOC );
+
+  $avg_min_roas_raw = $avg_row['avg_min_roas'] ?? null;
+  $avg_min_roas = $avg_min_roas_raw !== null && $avg_min_roas_raw !== '' ? round( (float) $avg_min_roas_raw, 6 ) : null;
+  $products_with_min_roas = (int) ( $avg_row['products_with_min_roas'] ?? 0 );
+
+  api_json_response( [
+    'result' => 'ok',
+    'client_id' => (int) $resolved_client['id'],
+    'google_ads_id' => (string) ( $resolved_client['google_ads_customer_id'] ?? '' ),
+    'products_with_min_roas' => $products_with_min_roas,
+    'avg_min_roas' => $avg_min_roas
+  ] );
+}
+
 // Pobranie 10 produktow do optymalizacji (wg klikniec, bez nowego tytulu lub kategorii Google)
 if ( \S::get( 'action' ) == 'products_to_optimize' )
 {