tango-python 0.5.0__tar.gz → 0.6.0__tar.gz

tango_python-0.6.0/.claude-plugin/plugin-pointer.json

@@ -0,0 +1,5 @@
+{
+  "source": "/Users/vdavez/Sync/makegov/mg-tools",
+  "installed_by": "mg-tools/install.py",
+  "note": "Load via: claude --plugin-dir $source (or add to your shell's claude wrapper)."
+}

tango_python-0.6.0/.mg-tools/DIARY.md

@@ -0,0 +1,5 @@
+# Diary
+
+Append-only log of notable sessions. Newest at bottom. See mg-tools' `diary` skill
+for the invocation protocol.
+

tango_python-0.6.0/.mg-tools/config.json

@@ -0,0 +1,8 @@
+{
+  "profile": "sdk",
+  "toolchain": "both",
+  "baseBranch": "main",
+  "changelogPath": "CHANGELOG.md",
+  "appsRoot": null,
+  "ruleMap": {}
+}

tango_python-0.6.0/.mg-tools/version

@@ -0,0 +1 @@
+1.0.3 2026-04-29T12:42:30Z /Users/vdavez/Sync/makegov/mg-tools

tango_python-0.6.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2026-05-07
+
+### Added
+- Vehicles: new top-level fields `program_acronym`, `idv_count`, `total_obligated`, `is_synthetic_solicitation`, `latest_award_date`, `description`, `opportunity_id`.
+- Vehicles: new `metrics(*)` shape expansion bundling 12 computed metrics: `avg_offers_received`, `award_concentration_hhi`, `order_concentration_hhi`, `competed_rate`, `using_agency_count`, `avg_order_value`, `max_order_value`, `top_recipient_share`, `recent_obligations_24mo`, `recent_orders_24mo`, `days_since_last_order`, `obligation_to_ceiling_ratio`. Backed by a new `VehicleMetrics` schema.
+- `list_vehicle_orders(uuid, ...)` for the new `/api/vehicles/{uuid}/orders/` endpoint, returning task orders under the vehicle's IDVs with two-phase pagination.
+- `list_vehicles` gained 21 explicit filter parameters per API 4.3.0: `vehicle_type`, `type_of_idc`, `contract_type`, `set_aside` (multi-value via `|`), `who_can_use`, `naics_code`, `psc_code`, `program_acronym`, `agency`, `organization_id`, `total_obligated_min`/`max`, `idv_count_min`/`max`, `order_count_min`/`max`, `fiscal_year`, `award_date_after`/`before`, `last_date_to_order_after`/`before`.
+- `list_vehicle_awardees` gained a `search` parameter for entity-aware full-text search across IDV fields and recipient entity details (API 4.3.0).
+- `ordering` parameter on `list_vehicles` (whitelist: `vehicle_obligations`, `latest_award_date`, `total_obligated`, `award_date`, `last_date_to_order`, `fiscal_year`, `idv_count`, `order_count`) and on `list_vehicle_orders` (whitelist: `award_date`, `obligated`, `total_contract_value`). Prefix with `-` for descending.
+- `ShapeConfig.VEHICLE_ORDERS_MINIMAL` default for the new orders endpoint.
+- Shaping: New `organization(*)` expand on `Vehicle`, `Forecast`, `Grant`, `ITDashboardInvestment`, and `Protest` schemas — returns the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Selectable as the bare leaf (`shape=...,organization`) or as a sub-selectable expansion (`shape=...,organization(office_code,...)`).
+- Shaping: New `vehicle(*)` expand on `Contract` — request the parent vehicle inline from `/api/contracts/` (API 4.2.0).
+- `Vehicle` and `VehicleMetrics` are now exported from the top-level `tango` package.
+- `tango.webhooks` subpackage with HMAC-SHA256 signing helpers (`verify_signature`, `generate_signature`, `parse_signature_header`) that mirror the canonical Tango server scheme byte-for-byte. Importable from a default `pip install tango-python` (pure stdlib).
+- `WebhookReceiver`: a stdlib-based local HTTP listener for development and integration tests. Verifies signatures, optionally forwards each delivery to a downstream URL, and records deliveries in memory for inspection. Usable as a context manager (`with WebhookReceiver(secret=...).run() as rx: ...`).
+- `tango.webhooks.simulate.deliver(...)`: locally sign and POST a payload to any URL — no Tango involvement. Useful for offline iteration on receiver code.
+- New `tango[webhooks]` extra (adds `click`) ships a `tango` console script covering the full webhook lifecycle for developer integrations:
+  - `listen` — local receiver
+  - `simulate` — sign a payload locally; with `--to`, also POST it
+  - `trigger` — ask Tango to send a real test delivery
+  - `fetch-sample` — print the canonical payload Tango emits for an event type
+  - `list-event-types` — discover what's subscribable
+  - `endpoints list|get|create|delete` — manage delivery endpoints
+  - `subscriptions list|get|create|delete` — manage what events you receive
+  Together these let a developer go from zero to receiving real Tango webhooks without leaving the shell or dropping into Python.
+
+### Changed
+- `ShapeConfig.VEHICLES_MINIMAL` and `VEHICLES_COMPREHENSIVE` now include the new top-level fields and the `organization` expansion. `VEHICLES_COMPREHENSIVE` defaults to `metrics(*)` and no longer pulls the deprecated `competition_details(*)` blob.
+
+### Deprecated
+- Vehicles shape fields `agency_details`, `competition_details`, and the `opportunity` expansion. The upstream API now sends a `Deprecation: true` header for these and recomputes them at request time. Explicit use in `shape=...` emits a Python `DeprecationWarning`. Sunset timeline TBD upstream.
+
+### Notes
+- Console script name `tango` may be revisited in a future release if it conflicts with sibling tooling (`tango-scripts` reuses the bare name).
+
+### Documentation
+- New `docs/WEBHOOKS.md` — comprehensive guide covering install, concepts, a zero-to-receiving quickstart, full CLI reference, and programmatic patterns for `WebhookReceiver` / `simulate.sign` / `simulate.deliver` in pytest fixtures.
+- `docs/API_REFERENCE.md`: filled in `get_webhook_subscription`, replaced the hand-rolled signature-verification snippet with a pointer to `tango.webhooks.verify_signature`, and added a new "Webhook tooling (`tango.webhooks`)" section that documents every importable from the new subpackage.
+- `README.md`: new "Webhook Tooling" section under Advanced Features, plus the new guide is linked from the Documentation index.
+
+## [0.5.0] - 2026-04-08
+
+### Added
+- IT Dashboard investments: `list_itdashboard_investments`, `get_itdashboard_investment` (`/api/itdashboard/`) with shaping and filter params (`search`, `agency_code`, `agency_name`, `type_of_investment`, `updated_time_after`, `updated_time_before`, `cio_rating`, `cio_rating_max`, `performance_risk`). Tier-gated by the API: free tier gets `search`, pro adds structured filters, business+ adds CIO/performance analytics. New `ITDashboardInvestment` model and `ShapeConfig.ITDASHBOARD_INVESTMENTS_MINIMAL` / `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` defaults.
+
+## [0.4.4] - 2026-03-25
+
+### Added
+- `parent_piid` filter parameter on `list_contracts` for filtering orders under a specific parent IDV PIID.
+- `user_agent` and `extra_headers` parameters on `TangoClient` for custom request headers.
+- `TangoClient.last_response_headers` property for accessing full HTTP headers from the most recent API response.
+
+## [0.4.3] - 2026-03-21
+
+### Added
+- `TangoRateLimitError` now exposes `wait_in_seconds`, `detail`, and `limit_type` properties parsed from the API's 429 response body.
+- `RateLimitInfo` dataclass for structured access to rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and per-window daily/burst variants).
+- `TangoClient.rate_limit_info` property returns rate limit info from the most recent API response.
+
+### Changed
+- `_request` now passes the full 429 response body to `TangoRateLimitError` (previously discarded), enabling callers to access `wait_in_seconds` and the specific limit type that was exceeded.
+
+## [0.4.2] - 2026-03-04
+
+### Added
+- Protests endpoints: `list_protests`, `get_protest` with shaping and filter params (`source_system`, `outcome`, `case_type`, `agency`, `case_number`, `solicitation_number`, `protester`, `filed_date_after`, `filed_date_before`, `decision_date_after`, `decision_date_before`, `search`).
+
+### Changed
+- Lint CI workflow disabled for push/PR (runs only on manual trigger) until the private `makegov/tango` repo is accessible to the workflow.
+- Updated documents to reflect changes since v0.4.0
+- Entities: `ENTITIES_COMPREHENSIVE` now uses `federal_obligations(*)` expansion; the API treats federal obligations as an expansion rather than a plain shape field.
+- Docs: `SHAPES.md` documents `federal_obligations(*)` as an expansion for entity shaping.
+- Integration tests: `test_parsing_nested_objects_with_missing_data` accepts award office fields (`office_code`, `agency_code`, `department_code`) and empty nested objects when the API returns partial data.
+
+### Removed
+- Assistance: `list_assistance` endpoint and all related tests, docs, and references.
+- IDV summaries: `get_idv_summary` and `list_idv_summary_awards` endpoints and related integration tests, cassettes, and API reference section.
+
+## [0.4.1] - 2026-03-03
+
+### Added
+- GSA eLibrary contracts: `list_gsa_elibrary_contracts`, `get_gsa_elibrary_contract` with shaping and filter params (`contract_number`, `key`, `piid`, `schedule`, `search`, `sin`, `uei`).
+
+### Changed
+- Conformance: replaced `**kwargs`/`**filters` with explicit filter parameters on `list_contracts`, `list_idvs`, `list_entities`, `list_forecasts`, `list_grants`, `list_notices`, `list_opportunities` for full filter/shape conformance. Backward compatibility preserved for `list_contracts(filters=SearchFilters(...))`.
+
+## [0.4.0] - 2026-02-24
+
+### Added
+- Offices, Organizations, OTAs, OTIDVs, Subawards, NAICS, and Assistance endpoints.
+- Filter/shape conformance tooling and documentation.
+
+### Changed
+- CI lint workflow runs filter/shape conformance when the manifest is available.
+
+## [0.3.0] - 2026-02-09
+
+### Added
+- Vehicles endpoints: `list_vehicles`, `get_vehicle`, and `list_vehicle_awardees` (supports shaping + flattening). (refs `makegov/tango#1328`)
+- IDV endpoints: `list_idvs`, `get_idv`, `list_idv_awards`, `list_idv_child_idvs`, `list_idv_transactions`, `get_idv_summary`, `list_idv_summary_awards`. (refs `makegov/tango#1328`)
+- Webhooks v2 client support: event type discovery, subscription CRUD, endpoint management, test delivery, and sample payload helpers. (refs `makegov/tango#1274`)
+
+### Changed
+- Expanded explicit schemas to support common IDV shaping expansions (award offices, officers, period of performance, etc.).
+- HTTP client now supports PATCH/DELETE helpers for webhook management endpoints.
+
+## [0.2.0] - 2025-11-16
+
+- Entirely refactored SDK

tango_python-0.6.0/CLAUDE.md

@@ -0,0 +1,130 @@
+# tango-python
+
+<!--
+This file is the AI-assistant context for this Python SDK. It's
+**gitignored** — each developer regenerates it locally by running
+`mg-tools install`, and may edit it freely without affecting the repo.
+External contributors don't see it; they read README.md and any
+committed CONTRIBUTING.md / docs/ for contribution guidance.
+
+MakeGov team members: per-developer mg-tools plugin paths + rules table
+live in `.claude/mg-tools-integration.md` (also gitignored).
+-->
+
+## Non-Negotiables
+
+- **Python version is pinned.** Check `pyproject.toml` for `requires-python`; don't use features below that. CI matrix is the contract.
+- **Public SDK — surface is contract.** Method names, parameter names, and return shapes are promises. Deprecate, don't break. If you rename a method, leave an alias + deprecation warning for at least one minor version.
+- **Always update `CHANGELOG.md`** under `## [Unreleased]` when source files change. Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) + [SemVer](https://semver.org/).
+- **Type hints are required on public API.** Strict `mypy` catches drift; new code must type-check cleanly.
+- **No `**kwargs` for filter / query parameters.** Every accepted filter must be an explicit named parameter. Opaque `**kwargs` is banned from the public surface because it can't be type-checked, documented, or validated against the API's filter contract.
+- **Never `git commit` / `push` / `merge` without the user's explicit permission.**
+- Use the `gh` CLI for GitHub operations.
+
+## Project conventions
+
+### Toolchain
+
+- **Dependency / env manager:** `uv`. Always run tooling via `uv run ...` — never bare `pytest`/`ruff`/`mypy`.
+- **Formatter + linter:** `ruff` — config in `pyproject.toml::[tool.ruff]`. Don't hand-format; let ruff do it.
+- **Type checker:** `mypy` in strict mode. New code must type-check.
+- **Base branch:** `main`. Release PRs target it directly.
+
+### Commands
+
+```bash
+# install
+uv sync --all-extras
+
+# format / lint / types
+uv run ruff format .
+uv run ruff check .
+uv run mypy <package>/
+
+# tests
+uv run pytest                                   # all
+uv run pytest tests/ -m "not integration"       # unit only
+uv run pytest tests/integration/                # integration
+
+# if this SDK uses cassette-based integration tests
+# (VCR.py or similar), refresh via an env var when endpoints change
+# — see repo-specific docs for the exact knob.
+```
+
+### Tests
+
+- **Unit:** fast, no network. Should run in under ~10s total.
+- **Integration:** gated behind a marker (`@pytest.mark.integration`); replayed via cassettes in CI.
+- **Live / production smoke:** live-API-gated via env var (e.g. `<SDK>_API_KEY`) + a separate marker. Never run in regular CI.
+- Pytest markers should be registered in `pyproject.toml::[tool.pytest.ini_options].markers`.
+- When a cassette-driven test is affected by an API change, refresh cassettes and commit them in the same PR.
+
+### Release flow
+
+1. Bump `version` in `pyproject.toml` AND `__version__` in the package's `__init__.py` (keep them in sync — ruff lint should catch drift).
+2. Promote `## [Unreleased]` → a dated version section in `CHANGELOG.md`.
+3. Open a PR to `main`, titled as the version number (e.g. `v0.5.1`) — no `WIP:` prefix for release PRs.
+4. A CI workflow handles PyPI publish on tag (check `.github/workflows/` for the exact trigger).
+
+### Style
+
+- **Double quotes** for Python strings (ruff-enforced via `quote-style = "double"`).
+- American English everywhere.
+
+## Where things live in this repo
+
+<!--
+Fill this in. Agents read `CLAUDE.md` first; the pointers below tell them where
+this repo keeps its truth. If a concern isn't listed, an agent will fall back to
+conventional paths — but it'll miss anything stashed in non-obvious locations.
+
+Run `/mg-tools:mg-setup` to (re)populate this section with a guided first pass and
+follow-up questions.
+-->
+
+| What | Where |
+| ---- | ----- |
+| Architecture / design notes | `<docs/ARCHITECTURE.md>` |
+| Local rules (per-topic agent guidance) | `.claude/rules/*.md` |
+| Local agents | `.claude/agents/*.md` |
+| Local skills | `.claude/skills/*/SKILL.md` |
+| User-facing docs | `docs/` |
+| README | `README.md` |
+| Contributing guide | `CONTRIBUTING.md` |
+| SDK source | `<package>/` |
+| Tests | `tests/` |
+| Cassettes (if VCR-based integration tests) | `<tests/cassettes/>` |
+| Other repo-specific sources of truth | *(add below)* |
+
+## MakeGov sibling repos (read as local files via `../<name>/`)
+
+Team machines check out MakeGov repos as siblings under a single root (default `~/Sites/`). Read sibling content as ordinary local paths — no `gh api`, no `WebFetch`.
+
+- `../docs/` — public / editorial-split docs
+- `../tango/` — primary API / backend this SDK targets
+- `../mg-tools/` — shared AI tooling
+- Other siblings: `../infra/`, `../scraper-service/`, `../crm/`, `../makegov.com/`, `../marcomms/`
+
+Full list + conventions: `${CLAUDE_PLUGIN_ROOT}/rules/sibling-repos.md`.
+
+## Context precedence (read order)
+
+Local wins. Before any non-trivial task:
+
+1. This `CLAUDE.md` (root + any scoped `**/CLAUDE.md`) — **start here**, then follow the pointers in "Where things live"
+2. Files named in "Where things live" above
+3. Sibling repos (above) when the task spans MakeGov surfaces (e.g. an SDK method wrapping a tango endpoint → read tango's view/serializer)
+4. Shipped mg-tools rules under `${CLAUDE_PLUGIN_ROOT}/rules/`
+5. Community / language defaults (last resort)
+
+Don't fall back to shipped defaults while local pointers remain unread.
+
+## Referenced docs
+
+- `README.md` — public install + quickstart (user-facing).
+- `docs/` — any user-facing guides (shape/filter DSLs, advanced usage, etc.).
+- `CONTRIBUTING.md` (if present) — contribution flow for external contributors.
+
+## Contributing
+
+External contributors: see `CONTRIBUTING.md` and/or the repo's open issues. Tests and linters should pass locally before opening a PR.

{tango_python-0.5.0 → tango_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python SDK for the Tango API
 Project-URL: Homepage, https://github.com/makegov/tango-python
 Project-URL: Documentation, https://docs.makegov.com/tango-python
@@ -51,6 +51,8 @@ Requires-Dist: ruff>=0.3.0; extra == 'dev'
 Provides-Extra: notebooks
 Requires-Dist: ipykernel>=6.25.0; extra == 'notebooks'
 Requires-Dist: jupyter>=1.0.0; extra == 'notebooks'
+Provides-Extra: webhooks
+Requires-Dist: click>=8.1; extra == 'webhooks'
 Description-Content-Type: text/markdown
 
 # Tango Python SDK
@@ -224,9 +226,14 @@ otidvs = client.list_otidvs(limit=25)
 ### Vehicles
 
 ```python
-vehicles = client.list_vehicles(search="GSA schedule", shape=ShapeConfig.VEHICLES_MINIMAL)
+vehicles = client.list_vehicles(
+    search="GSA schedule",
+    ordering="-vehicle_obligations",
+    shape=ShapeConfig.VEHICLES_MINIMAL,
+)
 vehicle = client.get_vehicle("UUID", shape=ShapeConfig.VEHICLES_COMPREHENSIVE)
 awardees = client.list_vehicle_awardees("UUID")
+orders = client.list_vehicle_orders("UUID", ordering="-obligated")
 ```
 
 ### Entities (Vendors/Recipients)
@@ -382,6 +389,46 @@ contracts = client.list_contracts(
 # Returns: {"key": "...", "transactions.0.action_date": "...", "transactions.0.obligated": "..."}
 ```
 
+### Webhook Tooling
+
+The SDK ships first-class tooling for **building and testing webhook integrations against the Tango API** — including signing helpers, a local receiver, and a command-line tool covering the full lifecycle:
+
+```bash
+pip install 'tango-python[webhooks]'
+```
+
+This adds a `tango` console script with subcommands for the full webhook lifecycle:
+
+```bash
+# Discover what's available
+tango webhooks list-event-types
+tango webhooks fetch-sample --event-type entities.updated
+
+# Local development
+tango webhooks listen --port 8011 --secret $SECRET    # receiver
+tango webhooks simulate --secret $SECRET --event-type entities.updated  # sign + print
+tango webhooks simulate --secret $SECRET --event-type entities.updated \
+    --to http://127.0.0.1:8011/tango/webhooks         # also POST
+
+# Manage real subscriptions and endpoints
+tango webhooks endpoints     create|list|get|delete
+tango webhooks subscriptions create|list|get|delete
+
+# Force a real test delivery from Tango
+tango webhooks trigger
+```
+
+The signing helpers (`verify_signature`, `generate_signature`) are pure stdlib and importable from the default install — your receiver code doesn't need the extra:
+
+```python
+from tango.webhooks import verify_signature
+
+if not verify_signature(raw_body, secret, request.headers.get("X-Tango-Signature")):
+    return 401, "invalid signature"
+```
+
+For the full guide — workflow, CLI reference, and programmatic patterns for pytest fixtures — see [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md).
+
 ### Type Hints with IDE Support
 
 Import TypedDict types for IDE autocomplete:
@@ -531,6 +578,7 @@ tango-python/
 - [Shape System Guide](docs/SHAPES.md) - Comprehensive guide to response shaping
 - [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
 - [Developer Guide](docs/DEVELOPERS.md) - Technical documentation for developers
+- [Webhooks Guide](docs/WEBHOOKS.md) - Workflow, CLI reference, and programmatic patterns for webhook integrations
 - [Quick Start Notebook](docs/quick_start.ipynb) - Interactive Jupyter notebook with examples
 
 ## Requirements

{tango_python-0.5.0 → tango_python-0.6.0}/README.md

@@ -169,9 +169,14 @@ otidvs = client.list_otidvs(limit=25)
 ### Vehicles
 
 ```python
-vehicles = client.list_vehicles(search="GSA schedule", shape=ShapeConfig.VEHICLES_MINIMAL)
+vehicles = client.list_vehicles(
+    search="GSA schedule",
+    ordering="-vehicle_obligations",
+    shape=ShapeConfig.VEHICLES_MINIMAL,
+)
 vehicle = client.get_vehicle("UUID", shape=ShapeConfig.VEHICLES_COMPREHENSIVE)
 awardees = client.list_vehicle_awardees("UUID")
+orders = client.list_vehicle_orders("UUID", ordering="-obligated")
 ```
 
 ### Entities (Vendors/Recipients)
@@ -327,6 +332,46 @@ contracts = client.list_contracts(
 # Returns: {"key": "...", "transactions.0.action_date": "...", "transactions.0.obligated": "..."}
 ```
 
+### Webhook Tooling
+
+The SDK ships first-class tooling for **building and testing webhook integrations against the Tango API** — including signing helpers, a local receiver, and a command-line tool covering the full lifecycle:
+
+```bash
+pip install 'tango-python[webhooks]'
+```
+
+This adds a `tango` console script with subcommands for the full webhook lifecycle:
+
+```bash
+# Discover what's available
+tango webhooks list-event-types
+tango webhooks fetch-sample --event-type entities.updated
+
+# Local development
+tango webhooks listen --port 8011 --secret $SECRET    # receiver
+tango webhooks simulate --secret $SECRET --event-type entities.updated  # sign + print
+tango webhooks simulate --secret $SECRET --event-type entities.updated \
+    --to http://127.0.0.1:8011/tango/webhooks         # also POST
+
+# Manage real subscriptions and endpoints
+tango webhooks endpoints     create|list|get|delete
+tango webhooks subscriptions create|list|get|delete
+
+# Force a real test delivery from Tango
+tango webhooks trigger
+```
+
+The signing helpers (`verify_signature`, `generate_signature`) are pure stdlib and importable from the default install — your receiver code doesn't need the extra:
+
+```python
+from tango.webhooks import verify_signature
+
+if not verify_signature(raw_body, secret, request.headers.get("X-Tango-Signature")):
+    return 401, "invalid signature"
+```
+
+For the full guide — workflow, CLI reference, and programmatic patterns for pytest fixtures — see [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md).
+
 ### Type Hints with IDE Support
 
 Import TypedDict types for IDE autocomplete:
@@ -476,6 +521,7 @@ tango-python/
 - [Shape System Guide](docs/SHAPES.md) - Comprehensive guide to response shaping
 - [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
 - [Developer Guide](docs/DEVELOPERS.md) - Technical documentation for developers
+- [Webhooks Guide](docs/WEBHOOKS.md) - Workflow, CLI reference, and programmatic patterns for webhook integrations
 - [Quick Start Notebook](docs/quick_start.ipynb) - Interactive Jupyter notebook with examples
 
 ## Requirements

{tango_python-0.5.0 → tango_python-0.6.0}/docs/API_REFERENCE.md

@@ -503,13 +503,14 @@ Vehicles provide a solicitation-centric way to discover groups of related IDVs a
 
 ### list_vehicles()
 
-List vehicles with optional vehicle-level full-text search.
+List vehicles with optional vehicle-level full-text search and ordering.
 
 ```python
 vehicles = client.list_vehicles(
     page=1,
     limit=25,
     search="GSA schedule",
+    ordering="-vehicle_obligations",
     shape=ShapeConfig.VEHICLES_MINIMAL,
     flat=False,
     flat_lists=False,
@@ -520,6 +521,7 @@ vehicles = client.list_vehicles(
 - `page` (int): Page number (default: 1)
 - `limit` (int): Results per page (default: 25, max: 100)
 - `search` (str, optional): Vehicle-level search term
+- `ordering` (str, optional): Server-side sort. Allowed: `vehicle_obligations`, `latest_award_date`. Prefix with `-` for descending.
 - `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLES_MINIMAL`)
 - `flat` (bool): Flatten nested objects in shaped response
 - `flat_lists` (bool): Flatten arrays using indexed keys
@@ -552,6 +554,67 @@ awardees = client.list_vehicle_awardees(
 )
 ```
 
+### list_vehicle_orders()
+
+List task orders under a vehicle's IDVs (`/api/vehicles/{uuid}/orders/`). Optimized for fast pagination over large vehicles.
+
+```python
+orders = client.list_vehicle_orders(
+    uuid="00000000-0000-0000-0000-000000000001",
+    limit=25,
+    ordering="-obligated",
+    shape=ShapeConfig.VEHICLE_ORDERS_MINIMAL,
+)
+```
+
+**Parameters:**
+- `uuid` (str): Vehicle UUID
+- `page` (int): Page number (default: 1)
+- `limit` (int): Results per page (default: 25, max: 100)
+- `ordering` (str, optional): Server-side sort. Allowed: `award_date` (default), `obligated`, `total_contract_value`. Prefix with `-` for descending.
+- `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLE_ORDERS_MINIMAL`)
+- `flat`, `flat_lists`, `joiner`: as on other vehicles methods
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with order (Contract) dictionaries
+
+### Vehicle response fields
+
+The post-cutover (May 2026) vehicle response includes these top-level fields, all addressable via the `shape` parameter:
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `uuid` | str | Stable identifier. |
+| `solicitation_identifier` | str | Solicitation shared by underlying IDVs. |
+| `is_synthetic_solicitation` | bool | `True` for GWAC orphans recovered via `ACRO:` prefix. |
+| `agency_id` | str | From IDV award-key suffix. |
+| `program_acronym` | str \| None | New post-cutover field. |
+| `organization_id` | str \| None | Awarding organization. |
+| `organization` | dict \| None | Live awarding-org snapshot `{organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name}`. Selected as a leaf field (`shape=...,organization`); not currently sub-selectable. |
+| `vehicle_type`, `who_can_use`, `type_of_idc`, `contract_type` | dict \| None | Returned as `{code, description}`. |
+| `description` | str \| None | Common text across IDV descriptions. |
+| `descriptions` | list[str] \| None | Distinct IDV descriptions. |
+| `idv_count`, `awardee_count`, `order_count` | int \| None | Denormalized rollups. |
+| `total_obligated`, `vehicle_obligations`, `vehicle_contracts_value` | Decimal \| None | Denormalized rollups. |
+| `award_date`, `latest_award_date`, `last_date_to_order` | date \| None | |
+| `solicitation_title`, `solicitation_description`, `solicitation_date`, `opportunity_id` | str / date / None | From SAM.gov via the linked Opportunity. |
+| `naics_code`, `psc_code`, `set_aside`, `fiscal_year` | int / str / None | |
+
+### Vehicle shape expansions
+
+- `awardees(...)` — underlying IDV awards. Supports nested `orders(...)`.
+- `metrics(*)` — bundled computed metrics: `avg_offers_received`, `award_concentration_hhi`, `order_concentration_hhi`, `competed_rate`, `using_agency_count`, `avg_order_value`, `max_order_value`, `top_recipient_share`, `recent_obligations_24mo`, `recent_orders_24mo`, `days_since_last_order`, `obligation_to_ceiling_ratio`. Defaults included in `ShapeConfig.VEHICLES_COMPREHENSIVE`.
+- `organization` — live awarding-org snapshot (selected as a leaf field; not sub-selectable).
+
+### Deprecated shape fields
+
+The following fields and expansions are still served by the API (recomputed at request time from the underlying IDVs) but the API now returns a `Deprecation: true` response header for them. They will be removed in a future tango API release.
+
+- `agency_details` (top-level field and `agency_details(*)` expansion)
+- `competition_details` (top-level field and `competition_details(*)` expansion)
+- `opportunity(*)` expansion (use the new top-level `solicitation_*` and `opportunity_id` fields instead)
+
+If you pass any of these in `shape=...`, the SDK will emit a Python `DeprecationWarning`. The default shapes (`VEHICLES_MINIMAL`, `VEHICLES_COMPREHENSIVE`) no longer include them.
+
 ---
 
 ## IDVs
@@ -1227,6 +1290,8 @@ for code in naics.results:
 
 Webhook APIs let **Large / Enterprise** users manage subscription filters for outbound Tango webhooks.
 
+> **For testing, signing, and a CLI tool**, see [`docs/WEBHOOKS.md`](WEBHOOKS.md). This section covers SDK method signatures only.
+
 ### list_webhook_event_types()
 
 Discover supported `event_type` values and subject types.
@@ -1246,6 +1311,12 @@ Notes:
 
 - This endpoint uses `page` + `page_size` (tier-capped) rather than `limit`.
 
+### get_webhook_subscription()
+
+```python
+sub = client.get_webhook_subscription("SUBSCRIPTION_UUID")
+```
+
 ### create_webhook_subscription()
 
 ```python
@@ -1335,21 +1406,89 @@ Every delivery includes an HMAC signature header:
 
 Compute the digest over the **raw request body bytes** using your shared secret.
 
+The SDK ships a stdlib-only verifier that mirrors the Tango server's signing scheme byte-for-byte. Use it instead of hand-rolling — it's importable from a default install (no extras needed):
+
 ```python
-import hashlib
-import hmac
+from tango.webhooks import verify_signature
 
+if not verify_signature(raw_body, secret, request.headers.get("X-Tango-Signature")):
+    return 401
+```
+
+`verify_signature` returns `False` for missing/empty/malformed headers — it never raises. Comparison is constant-time.
+
+---
+
+## Webhook tooling (`tango.webhooks`)
+
+The `tango.webhooks` subpackage adds testing and developer-tooling primitives on top of the API methods above. Signing helpers ship with the default install; the receiver and CLI ship with `pip install 'tango-python[webhooks]'`. See [`docs/WEBHOOKS.md`](WEBHOOKS.md) for usage guides; this section is the import-level reference.
+
+### Signing (default install)
 
-def verify_tango_webhook_signature(secret: str, raw_body: bytes, signature_header: str | None) -> bool:
-    if not signature_header:
-        return False
-    sig = signature_header.strip()
-    if sig.startswith("sha256="):
-        sig = sig[len("sha256=") :]
-    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
-    return hmac.compare_digest(expected, sig)
+```python
+from tango.webhooks import (
+    verify_signature,        # (body: bytes, secret: str, header: str | None) -> bool
+    generate_signature,      # (body: bytes, secret: str) -> str (lowercase hex)
+    parse_signature_header,  # (header: str | None) -> str | None  (strips "sha256=")
+    SIGNATURE_HEADER,        # "X-Tango-Signature"
+    SIGNATURE_PREFIX,        # "sha256="
+)
 ```
 
+### `WebhookReceiver` (with `[webhooks]` extra)
+
+A stdlib-based local HTTP receiver, useful in tests and during local development.
+
+```python
+from tango.webhooks import WebhookReceiver, Delivery
+
+with WebhookReceiver(secret="dev").run() as rx:
+    # ... cause something to POST to rx.url ...
+    deliveries: list[Delivery] = rx.deliveries
+```
+
+Constructor (all keyword arguments):
+
+| Arg | Default | Meaning |
+|---|---|---|
+| `secret` | `""` | Shared secret. Empty means signatures are not verified. |
+| `path` | `/tango/webhooks` | URL path to accept POSTs on. |
+| `host` | `127.0.0.1` | Bind address. |
+| `port` | `0` | TCP port. `0` = OS picks a free port. |
+| `forward_to` | `None` | Optional URL to mirror each delivery to. |
+| `max_history` | `256` | Cap on the in-memory `deliveries` deque. |
+| `on_delivery` | `None` | Callback fired for every delivery (verified or not). |
+| `require_signature` | `None` | Override default (require iff `secret` is set). |
+
+Each `Delivery` is a dataclass: `received_at`, `path`, `signature_header`, `body_bytes`, `body_json`, `verified`, `remote_addr`, `forward_status`, `forward_error`.
+
+### `simulate.sign` and `simulate.deliver`
+
+```python
+from tango.webhooks import sign, SignedRequest
+from tango.webhooks import simulate
+
+# Offline — produce the signed wire form without POSTing:
+signed: SignedRequest = sign({"events": [{"event_type": "..."}]}, secret="s")
+signed.body         # bytes you would put on the wire
+signed.signature    # bare lowercase hex
+signed.headers      # {"Content-Type": ..., "X-Tango-Signature": "sha256=..."}
+
+# With delivery — sign and POST to a target URL:
+result = simulate.deliver(target_url="http://localhost:8011/tango/webhooks",
+                          payload={...}, secret="s")
+result.status_code   # status from the receiver
+result.signature     # bare hex
+result.sent_bytes    # exact bytes that were POSTed
+result.response_body # body the receiver returned
+```
+
+`simulate.deliver` and `simulate.sign` accept payloads as `dict`, `list`, `str`, or raw `bytes`. Dicts/lists are serialized via `json.dumps(..., sort_keys=True, separators=(",", ":"))` so signatures are reproducible across runs.
+
+### CLI entry point
+
+The `tango[webhooks]` extra also installs a `tango` console script. See [`docs/WEBHOOKS.md` § CLI reference](WEBHOOKS.md#cli-reference) for the full command list.
+
 ---
 
 ## Response Objects

{tango_python-0.5.0 → tango_python-0.6.0}/docs/SHAPES.md

@@ -57,7 +57,9 @@ idvs = client.list_idvs(shape=ShapeConfig.IDVS_MINIMAL)
 grants = client.list_grants(shape=ShapeConfig.GRANTS_MINIMAL)
 ```
 
-**Available constants:** Contracts (`CONTRACTS_MINIMAL`), Entities (`ENTITIES_MINIMAL`, `ENTITIES_COMPREHENSIVE`), Forecasts, Opportunities, Notices, Grants, IDVs, Vehicles, Organizations, OTAs, OTIDVs, Subawards. See [API Reference – ShapeConfig](API_REFERENCE.md#shapeconfig-predefined-shapes) for the full table and which method uses which constant.
+**Available constants:** Contracts (`CONTRACTS_MINIMAL`), Entities (`ENTITIES_MINIMAL`, `ENTITIES_COMPREHENSIVE`), Forecasts, Opportunities, Notices, Grants, IDVs, Vehicles (`VEHICLES_MINIMAL`, `VEHICLES_COMPREHENSIVE`, `VEHICLE_AWARDEES_MINIMAL`, `VEHICLE_ORDERS_MINIMAL`), Organizations, OTAs, OTIDVs, Subawards. See [API Reference – ShapeConfig](API_REFERENCE.md#shapeconfig-predefined-shapes) for the full table and which method uses which constant.
+
+> **Vehicles `metrics(*)` expansion:** The vehicles surface bundles 12 computed metrics under a single `metrics(*)` expansion (e.g. `award_concentration_hhi`, `competed_rate`, `top_recipient_share`). It is included in `VEHICLES_COMPREHENSIVE` by default. The `agency_details`, `competition_details`, and `opportunity` shape entries are deprecated and emit `DeprecationWarning` if requested explicitly.
 
 ## Basic Shaping