feat(client): API parity — 30+ methods, ordering kwargs, webhook write fixes

[makegov-hal]

Summary

Brings tango-python to full API parity with Tango: 30+ new methods, signature fixes for write paths, ordering kwargs on list endpoints that were silently missing them, and four new typed response models. 278 unit tests pass, 45/45 smoke checks pass against a running Tango instance, 80% line coverage across the package.

Branch: 5 commits on feat/api-parity off main.

What's new

Resolve / Validate utilities (typed wrappers)

Two new top-level methods replace the prior client._post("/api/resolve/", ...) workaround:

• resolve(name, target_type, ...) — POST /api/resolve/. Returns a typed ResolveResult with ResolveCandidate entries (identifier, display_name, match_tier on Pro+). Optional context: state, city, context string. Backed by new dataclasses exported from the package root.
• validate(identifier_type, value) — POST /api/validate/. Returns ValidateResult.

Webhook alerts CRUD parity

The convenience layer over /api/webhooks/alerts/ (filter subscriptions) was previously create-only. Full CRUD now:

• list_webhook_alerts(...)
• get_webhook_alert(id)
• create_webhook_alert(name=, query_type=, filters=, frequency=, cron_expression=)
• update_webhook_alert(id, ...)
• delete_webhook_alert(id)

WebhookAlert dataclass exported from tango.

Webhook write-method signatures, completed

The SDK's write methods were missing fields that the Tango API has required since multi-endpoint support landed. Catching up:

• create_webhook_endpoint now accepts name= (keyword-only). Required by the server; omitting it emits a DeprecationWarning and will become an error in a future major version.
• create_webhook_subscription accepts endpoint=, subscription_type=, query_type=, filter_definition=, frequency=, cron_expression=, is_active= — covers both subject and filter subscription patterns through the canonical /api/webhooks/subscriptions/ API.
• update_webhook_subscription accepts frequency=, cron_expression=, is_active=.
• update_webhook_endpoint accepts name= for renames.

Reference data

list_departments, get_department, list_psc, get_psc, get_psc_metrics, get_naics, get_naics_metrics, get_business_type, list_assistance_listings, get_assistance_listing, list_mas_sins, get_mas_sin.

Entity sub-resources

list_entity_contracts, list_entity_idvs, list_entity_otas, list_entity_otidvs, list_entity_subawards, list_entity_lcats, get_entity_metrics. All shape-aware where the underlying endpoint supports shaping.

IDV + agency sub-resources

• list_idv_lcats
• list_agency_awarding_contracts, list_agency_funding_contracts

Misc

• search_opportunity_attachments(q, top_k, include_extracted_text) for /api/opportunities/attachment-search/
• get_version() for /api/version/
• list_api_keys() for /api/api-keys/

ordering parameter where the API supports it

Seven list methods now accept ordering= and pass it through:

list_forecasts, list_grants, list_subawards, list_gsa_elibrary_contracts, list_opportunities, list_notices, list_protests. Prefix with - for descending. This closes parity gaps where the API documented ?ordering= but the SDK silently rejected the kwarg.

Fixed

• TangoClient._post() and _patch() now accept both json_data= (positional, original) and json= (kwarg). Internal callers and docs examples that use json= no longer fail with TypeError.

Testing

• pytest: 412 passed, 31 skipped — was 238 before this branch; +40 new tests in tests/test_api_parity.py.
• 80% line coverage across tango/ (pytest --cov).
• mypy clean on changed code; ruff clean.
• Smoke (scripts/smoke_api_parity.py against http://localhost:8000): 45/45 pass. Three blocks SKIPped for environmental reasons (/attachment-search/ 404 locally, /funding-contracts/ 504 on the test agency, create_webhook_alert skipped when the test account has multiple endpoints — see makegov/tango#2256).
• All smoke-test webhook resources cleaned up — zero leftover endpoints/subs/alerts.

Decisions worth flagging

• Kept uuid= on vehicle methods (list_vehicle_awardees, list_vehicle_orders). Matches the existing get_vehicle(uuid) path-param convention. SDK convention: IDVs use key=, vehicles use uuid=.

Known issues uncovered during parity work (tracked separately on tango)

• makegov/tango#2252 — Webhooks v2 inconsistency: /subscriptions/ POST uses field endpoint; /endpoints/test-delivery/ uses endpoint_id.
• makegov/tango#2254 — OpenAPI advertises ordering on /notices/, /protests/, /subawards/ but viewsets reject most values.
• makegov/tango#2256 — Multi-endpoint accounts can't use /api/webhooks/alerts/; backend needs to accept an explicit endpoint field on the alert create serializer before the SDKs can paper over the limitation.

Risks

• No breaking changes to existing public methods. New kwargs are keyword-only with safe defaults; backward-compatible across the board.
• DeprecationWarning on create_webhook_endpoint without name= may surface in user logs — intentional, since the API will eventually reject name-less requests outright.

Sibling work

Companion PR in tango-node covers the same parity work for the Node SDK. Docs are updated to reflect both SDKs' new surfaces in makegov/docs#9.

– Hal 🤖

[Copilot]

Pull request overview

This PR expands tango-python toward full Tango API parity by adding many missing client methods and typed models, plus fixing webhook write signatures and request-body kwarg compatibility to match documented usage.

Changes:

• Added Resolve/Validate POST helpers with typed response models (ResolveResult, ValidateResult) and exported them at the package root.
• Implemented webhook alerts CRUD plus webhook endpoint/subscription write-signature parity (including name= on endpoint creation and additional subscription fields).
• Added ordering= passthrough on several list endpoints and introduced a comprehensive unit-test suite + smoke script for the parity surface.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_client.py	Updates webhook endpoint CRUD test to include name= and assert it is sent in the request body.
tests/test_api_parity.py	Adds extensive mock-driven tests covering new parity methods, ordering passthrough, and _post/_patch json kwarg aliasing.
tango/models.py	Introduces new dataclasses (WebhookAlert, ResolveCandidate/Result, ValidateResult) and minor shape string formatting change.
tango/client.py	Adds _post/_patch json= alias support, ordering= kwargs, webhook write fixes, webhook alerts CRUD, resolve/validate endpoints, and multiple reference/sub-resource list/get methods.
tango/init.py	Exports new parity models from the package root.
scripts/smoke_api_parity.py	Adds an end-to-end smoke script to exercise parity methods against a running Tango instance with cleanup.
CHANGELOG.md	Documents newly added methods/kwargs and the _post/_patch compatibility fix.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.