Sync to Tango API v4.6.9: budget surface, singleton GETs, bug fixes (v1.1.0) (#31)

* feat: sync to Tango API v4.6.9 (budget surface, singleton GETs, bug fixes)

Phase 1 (bug fixes):
- Contract model: drop dead fields (id, award_id, recipient_name, award_amount,
  awarding_agency, funding_agency); add real ContractListSerializer fields. Old
  fields kept Optional/None + deprecation note, to be removed in 2.0.0.
- list_contracts: stop sending page=1 to the cursor-only /api/contracts/.
- add list_otidv_awards (parity with Node).

Phase 2 (additive):
- budget accounts surface: list_budget_accounts, get_budget_account,
  get_budget_account_quarters, get_budget_account_recipients (+ BudgetAccount
  model + shape schema).
- singleton detail GETs: get_contract, get_contract_subawards,
  get_contract_transactions, get_forecast, get_grant, get_notice,
  get_opportunity, get_subaward.
- get_entity_budget_flows(uei).
- grant_id filter on list_grants.

Phase 3 (CI):
- re-enable lint.yml as a PR gate; conformance split into a non-blocking job.

Version bump to 1.1.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: re-record contract integration cassettes for cursor-only pagination

The list_contracts page=1 removal changed the recorded request URI, so 32
contract/edge-case cassettes no longer matched. Re-recorded against live API
(v4.6.9). Two expensive filter queries (awarding_agency, multi-param search)
504 at the gateway on re-record, so those two cassettes retain their prior
valid 200 response with only the stale `&page=1` stripped from the request URI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(shapes): register ContractOrIDVCompetition nested schema alias

CONTRACT_SCHEMA/IDV_SCHEMA reference the competition leaf as
"ContractOrIDVCompetition" but only "Competition" was registered in
EXPLICIT_SCHEMAS, so competition(extent_competed,...) nested selections on
contract/IDV shapes raised ShapeValidationError. Register the name as an alias
of COMPETITION_SCHEMA. Fixes tango-python#29 item 1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(lint): make mypy advisory and conformance skip without token

Re-enabling lint.yml surfaced two pre-existing blockers unrelated to the API
sync: ~28 mypy errors that predate CI enforcement, and a conformance job that
fails because the private makegov/tango checkout needs an unconfigured
TANGO_API_REPO_ACCESS_TOKEN secret.

Keep ruff format + ruff check as hard gates (clean today). Make mypy advisory
(continue-on-error) pending a debt burn-down. Gate the conformance steps on the
token being present so the job skips cleanly (green) instead of failing red, and
becomes a real gate automatically once the secret exists.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(types): align webhook alert parser with WebhookAlert contract

Clears the 4 mypy errors the v1.1.0 branch introduced over main's baseline.
_parse_webhook_alert now emits str/dict/Literal values matching the model's
declared types (sparse payloads hydrate "" / {} instead of None); cli sample
payload cast to dict for assignment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: V. David Zvenyach <dave@zvenyach.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/workflows/lint.yml

@@ -1,43 +1,96 @@
 name: Linting
 
-# Disabled: requires checkout of private makegov/tango repo for filter_shape conformance check.
-# Re-enable when that repo is accessible (e.g. add TANGO_API_REPO_ACCESS_TOKEN secret).
+# Lint gate runs on every PR and push to main.
+#
+# - ruff format + ruff check are HARD gates (block the PR).
+# - mypy is ADVISORY for now (continue-on-error): the package carries ~28
+#   pre-existing type errors that predate CI enforcement. Tracked for burn-down
+#   in makegov/tango-python; flip `continue-on-error` off once that's clear.
+# - The SDK filter/shape conformance check needs the canonical manifest from the
+#   private makegov/tango repo, which requires a TANGO_API_REPO_ACCESS_TOKEN
+#   secret the public CI does not have. The conformance job SKIPS cleanly when
+#   the token is absent (rather than failing red) and becomes a real gate the
+#   moment the secret is configured.
 on:
   workflow_dispatch:
-  # push:
-  #   branches: [ main, develop ]
-  # pull_request:
-  #   branches: [ main, develop ]
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
 jobs:
   lint:
     runs-on: ubuntu-latest
-    
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Check formatting with ruff
+      run: uv run ruff format --check tango/
+
+    - name: Lint with ruff
+      run: uv run ruff check tango/
+
+    - name: Type check with mypy (advisory)
+      continue-on-error: true
+      run: uv run mypy tango/
+
+  conformance:
+    # Requires the canonical filter_shape manifest from the private makegov/tango
+    # repo. When TANGO_API_REPO_ACCESS_TOKEN is not configured, every real step
+    # is skipped and the job passes (rather than failing on an empty token).
+    # Configure the secret to turn this into a hard gate automatically.
+    runs-on: ubuntu-latest
+
     steps:
+    - name: Determine token availability
+      id: gate
+      env:
+        TANGO_API_REPO_ACCESS_TOKEN: ${{ secrets.TANGO_API_REPO_ACCESS_TOKEN }}
+      run: |
+        if [ -n "$TANGO_API_REPO_ACCESS_TOKEN" ]; then
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "ready=false" >> "$GITHUB_OUTPUT"
+          echo "::notice::Skipping SDK conformance check — TANGO_API_REPO_ACCESS_TOKEN not configured."
+        fi
+
     - uses: actions/checkout@v4
+      if: steps.gate.outputs.ready == 'true'
 
     - name: Checkout tango API repo (manifest source)
+      if: steps.gate.outputs.ready == 'true'
       uses: actions/checkout@v4
       with:
         repository: makegov/tango
         path: tango-api
-    
+        token: ${{ secrets.TANGO_API_REPO_ACCESS_TOKEN }}
+
     - name: Install uv
+      if: steps.gate.outputs.ready == 'true'
       uses: astral-sh/setup-uv@v4
       with:
         version: "latest"
-    
+
     - name: Set up Python
+      if: steps.gate.outputs.ready == 'true'
       run: uv python install 3.12
-    
+
     - name: Install dependencies
+      if: steps.gate.outputs.ready == 'true'
       run: uv sync --all-extras
-    
-    - name: Check formatting with ruff
-      run: uv run ruff format --check tango/
-    
-    - name: Lint with ruff
-      run: uv run ruff check tango/
 
     - name: Check SDK filter/shape conformance
+      if: steps.gate.outputs.ready == 'true'
       run: uv run python scripts/check_filter_shape_conformance.py --manifest tango-api/contracts/filter_shape_contract.json

CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- `_parse_webhook_alert`: aligned the parser output with the `WebhookAlert`
+  type contract. Sparse server payloads now hydrate `query_type` and `filters`
+  as `""` / `{}` (matching their declared non-null types) rather than `None`,
+  and `status` is typed as the `Literal["active", "paused"]` the model promises.
+  Clears the four type-check errors this introduced; no change for full payloads.
+- `Contract` model: removed dead fields (`id`, `award_id`, `recipient_name`,
+  `award_amount`, `awarding_agency`, `funding_agency`) and added the real API
+  fields (`key`, `piid`, `obligated`, `total_contract_value`,
+  `base_and_exercised_options_value`, `awarding_office`, `funding_office`,
+  `naics_code`, `psc_code`, `set_aside`, `solicitation_identifier`,
+  `parent_award`, `legislative_mandates`, `subawards_summary`,
+  `place_of_performance`). The deprecated fields remain declared with `None`
+  defaults for one minor cycle (they never returned data) and will be removed
+  in `2.0.0`. New `OrganizationOfficePayload` dataclass for the office fields.
+  (`Contract` is a documentation-only dataclass — not instantiated or exported
+  — so there is no runtime impact.)
+- `list_contracts`: no longer sends `page=1` to the cursor-only `/api/contracts/`
+  endpoint. When no cursor is supplied, neither `page` nor `cursor` is sent and
+  the API returns the first page by default.
+- Shape validation: registered the `ContractOrIDVCompetition` nested schema
+  (alias of `Competition`) so nested selections like
+  `competition(extent_competed,number_of_offers_received)` on contract / IDV
+  shapes validate instead of raising `ShapeValidationError`.
+
+### Added
+- Budget accounts surface (tango v4.6.8): `list_budget_accounts`,
+  `get_budget_account`, `get_budget_account_quarters`,
+  `get_budget_account_recipients`. New `BudgetAccount` dataclass exported from
+  the top-level package, plus `ShapeConfig.BUDGET_ACCOUNTS_MINIMAL`.
+- Singleton detail GETs: `get_contract`, `get_contract_subawards`,
+  `get_contract_transactions`, `get_forecast`, `get_grant`, `get_notice`,
+  `get_opportunity`, `get_subaward`.
+- `get_entity_budget_flows(uei)` for `/api/entities/{uei}/budget-flows/`.
+- `list_otidv_awards(key)` for `/api/otidvs/{key}/awards/` (parity with Node).
+- `grant_id` filter kwarg on `list_grants` (supports multi-value OR via `|`).
+
+### CI
+- Re-enabled `lint.yml` as a PR + push-to-main gate. `ruff format` and
+  `ruff check` are hard gates; `mypy` runs advisory (continue-on-error) pending
+  burn-down of ~28 pre-existing type errors. The filter/shape conformance check
+  is a separate job that skips cleanly until a `TANGO_API_REPO_ACCESS_TOKEN`
+  secret for the private manifest repo is configured, at which point it becomes
+  a hard gate.
+
 ## [1.0.0] - 2026-05-13
 
 > First stable release. `tango-python` is now at full API parity with the

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "1.0.0"
+version = "1.1.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"

scripts/check_filter_shape_conformance.py

@@ -51,6 +51,7 @@
     "naics": "list_naics",
     "gsa_elibrary_contracts": "list_gsa_elibrary_contracts",
     "itdashboard": "list_itdashboard_investments",
+    "budget_accounts": "list_budget_accounts",
     # Resources not yet implemented in SDK
     "offices": None,
 }
@@ -62,6 +63,7 @@ def get_shape_config_entries() -> list[tuple[str, str, type[Any]]]:
         IDV,
         OTA,
         OTIDV,
+        BudgetAccount,
         Contract,
         Entity,
         Forecast,
@@ -110,6 +112,7 @@ def get_shape_config_entries() -> list[tuple[str, str, type[Any]]]:
             ShapeConfig.ITDASHBOARD_INVESTMENTS_COMPREHENSIVE,
             ITDashboardInvestment,
         ),
+        ("BUDGET_ACCOUNTS_MINIMAL", ShapeConfig.BUDGET_ACCOUNTS_MINIMAL, BudgetAccount),
     ]
     for name, shape_str, model_cls in configs:
         entries.append((name, shape_str, model_cls))

tango/__init__.py

@@ -9,6 +9,7 @@
     TangoValidationError,
 )
 from .models import (
+    BudgetAccount,
     GsaElibraryContract,
     ITDashboardInvestment,
     PaginatedResponse,
@@ -43,7 +44,7 @@
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __all__ = [
     "TangoClient",
     "TangoAPIError",
@@ -54,6 +55,7 @@
     "RateLimitInfo",
     "ResolveCandidate",
     "ResolveResult",
+    "BudgetAccount",
     "GsaElibraryContract",
     "ITDashboardInvestment",
     "PaginatedResponse",