Added protests endpoint

Author: vdavez

tango/client.py

@@ -31,6 +31,7 @@
     Opportunity,
     Organization,
     PaginatedResponse,
+    Protest,
     SearchFilters,
     ShapeConfig,
     Subaward,
@@ -1859,6 +1860,129 @@ def list_notices(
             results=results,
         )
 
+    # Protest endpoints
+    # See https://tango.makegov.com/docs/api-reference/protests.md
+    # Note: Protests API does not support ordering (returns 400 if provided).
+    # Use shape=...,dockets(...) to request nested dockets.
+    def list_protests(
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+        source_system: str | None = None,
+        outcome: str | None = None,
+        case_type: str | None = None,
+        agency: str | None = None,
+        case_number: str | None = None,
+        solicitation_number: str | None = None,
+        protester: str | None = None,
+        filed_date_after: str | None = None,
+        filed_date_before: str | None = None,
+        decision_date_after: str | None = None,
+        decision_date_before: str | None = None,
+        search: str | None = None,
+    ) -> PaginatedResponse:
+        """
+        List bid protests.
+
+        Returns case-level protest records. Use shape=...,dockets(...) to include
+        nested dockets. API reference: https://tango.makegov.com/docs/api-reference/protests.md
+
+        Args:
+            page: Page number
+            limit: Results per page (max 100)
+            shape: Response shape string (defaults to minimal shape)
+            flat: If True, flatten nested objects in shaped response
+            flat_lists: If True, flatten arrays using indexed keys
+            source_system: Filter by source system (e.g. gao)
+            outcome: Filter by outcome (e.g. Denied, Dismissed, Withdrawn, Sustained)
+            case_type: Filter by case type
+            agency: Filter by protested agency text
+            case_number: Filter by case number (e.g. b-423274)
+            solicitation_number: Filter by exact solicitation number
+            protester: Filter by protester name text
+            filed_date_after: Filed date on or after
+            filed_date_before: Filed date on or before
+            decision_date_after: Decision date on or after
+            decision_date_before: Decision date on or before
+            search: Full-text search over protest searchable fields
+        """
+        params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+
+        if shape is None:
+            shape = ShapeConfig.PROTESTS_MINIMAL
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+
+        for key, val in (
+            ("source_system", source_system),
+            ("outcome", outcome),
+            ("case_type", case_type),
+            ("agency", agency),
+            ("case_number", case_number),
+            ("solicitation_number", solicitation_number),
+            ("protester", protester),
+            ("filed_date_after", filed_date_after),
+            ("filed_date_before", filed_date_before),
+            ("decision_date_after", decision_date_after),
+            ("decision_date_before", decision_date_before),
+            ("search", search),
+        ):
+            if val is not None:
+                params[key] = val
+
+        data = self._get("/api/protests/", params)
+
+        results = [
+            self._parse_response_with_shape(item, shape, Protest, flat, flat_lists)
+            for item in data["results"]
+        ]
+
+        return PaginatedResponse(
+            count=data["count"],
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=results,
+        )
+
+    def get_protest(
+        self,
+        case_id: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> Any:
+        """
+        Get a single protest by case_id (RFC 4122 UUID).
+
+        Use shape=...,dockets(...) to include nested dockets.
+        API reference: https://tango.makegov.com/docs/api-reference/protests.md
+
+        Args:
+            case_id: Deterministic case UUID (from source_system + base_case_number)
+            shape: Response shape string (defaults to minimal shape)
+            flat: If True, flatten nested objects in shaped response
+            flat_lists: If True, flatten arrays using indexed keys
+        """
+        params: dict[str, Any] = {}
+        if shape is None:
+            shape = ShapeConfig.PROTESTS_MINIMAL
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+
+        data = self._get(f"/api/protests/{case_id}/", params)
+        return self._parse_response_with_shape(data, shape, Protest, flat, flat_lists)
+
     # Grant endpoints
     def list_grants(
         self,

tango/models.py

@@ -433,6 +433,33 @@ class Notice:
     naics_code: str | None = None
 
 
+@dataclass
+class Protest:
+    """Schema definition for Protest (not used for instances)
+
+    Bid protest records at /api/protests/. Case-level object identified by case_id (UUID).
+    See https://tango.makegov.com/docs/api-reference/protests.md.
+    """
+
+    case_id: str
+    case_number: str | None = None
+    title: str | None = None
+    source_system: str | None = None
+    outcome: str | None = None
+    agency: str | None = None
+    protester: str | None = None
+    solicitation_number: str | None = None
+    case_type: str | None = None
+    filed_date: datetime | None = None
+    posted_date: datetime | None = None
+    decision_date: datetime | None = None
+    due_date: datetime | None = None
+    docket_url: str | None = None
+    decision_url: str | None = None
+    digest: str | None = None
+    dockets: list[dict[str, Any]] | None = None
+
+
 @dataclass
 class AssistanceListing:
     """Schema definition for Assistance Listing (not used for instances)"""
@@ -589,6 +616,9 @@ class ShapeConfig:
     # Default for list_notices()
     NOTICES_MINIMAL: Final = "notice_id,title,solicitation_number,posted_date"
 
+    # Default for list_protests()
+    PROTESTS_MINIMAL: Final = "case_id,case_number,title,source_system,outcome,filed_date"
+
     # Default for list_grants()
     GRANTS_MINIMAL: Final = "grant_id,opportunity_number,title,status(*),agency_code"
 

tango/shapes/explicit_schemas.py

@@ -637,6 +637,57 @@
 }
 
 
+# Docket-level fields for Protest dockets expansion: dockets(docket_number, filed_date, ...)
+PROTEST_DOCKET_SCHEMA: dict[str, FieldSchema] = {
+    "source_system": FieldSchema(name="source_system", type=str, is_optional=True, is_list=False),
+    "case_number": FieldSchema(name="case_number", type=str, is_optional=True, is_list=False),
+    "docket_number": FieldSchema(name="docket_number", type=str, is_optional=True, is_list=False),
+    "title": FieldSchema(name="title", type=str, is_optional=True, is_list=False),
+    "protester": FieldSchema(name="protester", type=str, is_optional=True, is_list=False),
+    "agency": FieldSchema(name="agency", type=str, is_optional=True, is_list=False),
+    "solicitation_number": FieldSchema(
+        name="solicitation_number", type=str, is_optional=True, is_list=False
+    ),
+    "case_type": FieldSchema(name="case_type", type=str, is_optional=True, is_list=False),
+    "outcome": FieldSchema(name="outcome", type=str, is_optional=True, is_list=False),
+    "filed_date": FieldSchema(name="filed_date", type=datetime, is_optional=True, is_list=False),
+    "posted_date": FieldSchema(name="posted_date", type=datetime, is_optional=True, is_list=False),
+    "decision_date": FieldSchema(
+        name="decision_date", type=datetime, is_optional=True, is_list=False
+    ),
+    "due_date": FieldSchema(name="due_date", type=datetime, is_optional=True, is_list=False),
+    "docket_url": FieldSchema(name="docket_url", type=str, is_optional=True, is_list=False),
+    "decision_url": FieldSchema(name="decision_url", type=str, is_optional=True, is_list=False),
+    "digest": FieldSchema(name="digest", type=str, is_optional=True, is_list=False),
+}
+
+PROTEST_SCHEMA: dict[str, FieldSchema] = {
+    "case_id": FieldSchema(name="case_id", type=str, is_optional=False, is_list=False),
+    "case_number": FieldSchema(name="case_number", type=str, is_optional=True, is_list=False),
+    "title": FieldSchema(name="title", type=str, is_optional=True, is_list=False),
+    "source_system": FieldSchema(name="source_system", type=str, is_optional=True, is_list=False),
+    "outcome": FieldSchema(name="outcome", type=str, is_optional=True, is_list=False),
+    "agency": FieldSchema(name="agency", type=str, is_optional=True, is_list=False),
+    "protester": FieldSchema(name="protester", type=str, is_optional=True, is_list=False),
+    "solicitation_number": FieldSchema(
+        name="solicitation_number", type=str, is_optional=True, is_list=False
+    ),
+    "case_type": FieldSchema(name="case_type", type=str, is_optional=True, is_list=False),
+    "filed_date": FieldSchema(name="filed_date", type=datetime, is_optional=True, is_list=False),
+    "posted_date": FieldSchema(name="posted_date", type=datetime, is_optional=True, is_list=False),
+    "decision_date": FieldSchema(
+        name="decision_date", type=datetime, is_optional=True, is_list=False
+    ),
+    "due_date": FieldSchema(name="due_date", type=datetime, is_optional=True, is_list=False),
+    "docket_url": FieldSchema(name="docket_url", type=str, is_optional=True, is_list=False),
+    "decision_url": FieldSchema(name="decision_url", type=str, is_optional=True, is_list=False),
+    "digest": FieldSchema(name="digest", type=str, is_optional=True, is_list=False),
+    "dockets": FieldSchema(
+        name="dockets", type=dict, is_optional=True, is_list=True, nested_model="ProtestDocket"
+    ),
+}
+
+
 AGENCY_SCHEMA: dict[str, FieldSchema] = {
     "abbreviation": FieldSchema(name="abbreviation", type=str, is_optional=True, is_list=False),
     "code": FieldSchema(name="code", type=str, is_optional=False, is_list=False),
@@ -1105,6 +1156,8 @@
     "Forecast": FORECAST_SCHEMA,
     "Opportunity": OPPORTUNITY_SCHEMA,
     "Notice": NOTICE_SCHEMA,
+    "Protest": PROTEST_SCHEMA,
+    "ProtestDocket": PROTEST_DOCKET_SCHEMA,
     "Agency": AGENCY_SCHEMA,
     "Grant": GRANT_SCHEMA,
     # Vehicles (Awards)