This pull request refactors the /prospects API endpoint to provide a more useful and production-ready response. Instead of returning static endpoint information, the endpoint now returns a paginated, filtered, and ordered list of prospects, prioritizing flagged entries and sorting alphabetically by first name.

app/api/prospects/prospects.py

@@ -8,23 +8,14 @@
 router = APIRouter()
 base_url = os.getenv("BASE_URL", "http://localhost:8000")
 
-@router.get("/prospects")
-def root() -> dict:
-    """GET /prospects endpoint."""
-    meta = make_meta("success", "Prospects endpoint")
-    data = [
-        {"init": f"{base_url}/prospects/init"},
-        {"search": f"{base_url}/prospects/search/?query=karen"},
-    ]
-    return {"meta": meta, "data": data}
 
-# endpoint: /prospects/read
-@router.get("/prospects/read")
-def prospects_read(
+# Refactored GET /prospects endpoint to return paginated, filtered, and ordered results
+@router.get("/prospects")
+def get_prospects(
     page: int = Query(1, ge=1, description="Page number (1-based)"),
     limit: int = Query(50, ge=1, le=500, description="Records per page (default 50, max 500)")
 ) -> dict:
-    """Read and return paginated rows from the prospects table, excluding hidden."""
+    """Return paginated, filtered, and ordered prospects (flagged first, then alphabetical by first_name)."""
     meta = make_meta("success", "Read paginated prospects")
     conn_gen = get_db_connection()
     conn = next(conn_gen)
@@ -34,7 +25,13 @@ def prospects_read(
         cur.execute('SELECT COUNT(*) FROM prospects WHERE hide IS NOT TRUE;')
         count_row = cur.fetchone() if cur.description is not None else None
         total = count_row[0] if count_row is not None else 0
-        cur.execute(f'SELECT * FROM prospects WHERE hide IS NOT TRUE OFFSET %s LIMIT %s;', (offset, limit))
+        # Order: flagged first (flag DESC NULLS LAST), then first_name ASC
+        cur.execute('''
+            SELECT * FROM prospects
+            WHERE hide IS NOT TRUE
+            ORDER BY COALESCE(flag, FALSE) DESC, first_name ASC
+            OFFSET %s LIMIT %s;
+        ''', (offset, limit))
         if cur.description is not None:
             columns = [desc[0] for desc in cur.description]
             rows = cur.fetchall()
@@ -61,6 +58,7 @@ def prospects_read(
 
 
 
+
 # Schema for update
 from pydantic import BaseModel
 from typing import Optional