Add an endpoint to return returned letter stats

Currently the dashboard in the admin app pull the entire returned letter
summary for a service to calculate how many letters have been returned
in the last seven days.

Adding a separate endpoint for this purpose is better because:
- it’s a more efficient query
- it’s less data to send down the pipe
- it gives us a place to return the complete datetime, so the dashboard
  can be more precise about when the most recent report was

app/dao/returned_letters_dao.py

@@ -13,6 +13,7 @@ from app.models import (
     Template,
     User,
 )
+from app.utils import midnight_n_days_ago
 
 
 def _get_notification_ids_for_references(references):
@@ -50,6 +51,25 @@ def insert_or_update_returned_letters(references):
         db.session.connection().execute(stmt)
 
 
+def fetch_returned_letter_count(service_id):
+    return db.session.query(
+        func.count(ReturnedLetter.notification_id).label('returned_letter_count'),
+    ).filter(
+        ReturnedLetter.service_id == service_id,
+        ReturnedLetter.reported_at > midnight_n_days_ago(7),
+    ).one()
+
+
+def fetch_most_recent_returned_letter(service_id):
+    return db.session.query(
+        ReturnedLetter.reported_at,
+    ).filter(
+        ReturnedLetter.service_id == service_id,
+    ).order_by(
+        desc(ReturnedLetter.reported_at)
+    ).first()
+
+
 def fetch_returned_letter_summary(service_id):
     return db.session.query(
         func.count(ReturnedLetter.notification_id).label('returned_letter_count'),

app/service/rest.py

@@ -31,8 +31,10 @@ from app.dao.fact_notification_status_dao import (
 from app.dao.inbound_numbers_dao import dao_allocate_number_for_service
 from app.dao.organisation_dao import dao_get_organisation_by_service_id
 from app.dao.returned_letters_dao import (
+    fetch_most_recent_returned_letter,
+    fetch_returned_letter_count,
     fetch_returned_letter_summary,
-    fetch_returned_letters
+    fetch_returned_letters,
 )
 from app.dao.service_data_retention_dao import (
     fetch_service_data_retention,
@@ -946,6 +948,25 @@ def check_if_reply_to_address_already_in_use(service_id, email_address):
         )
 
 
+@service_blueprint.route('/<uuid:service_id>/returned-letter-statistics', methods=['GET'])
+def returned_letter_statistics(service_id):
+
+    most_recent = fetch_most_recent_returned_letter(service_id)
+
+    if not most_recent:
+        return jsonify({
+            'returned_letter_count': 0,
+            'most_recent_report': None,
+        })
+
+    count = fetch_returned_letter_count(service_id)
+
+    return jsonify({
+        'returned_letter_count': count.returned_letter_count,
+        'most_recent_report': most_recent.reported_at.strftime(DATETIME_FORMAT_NO_TIMEZONE),
+    })
+
+
 @service_blueprint.route('/<uuid:service_id>/returned-letter-summary', methods=['GET'])
 def returned_letter_summary(service_id):
     results = fetch_returned_letter_summary(service_id)