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

tango_python-1.0.0/.github/workflows/docs-dispatch.yml

@@ -0,0 +1,58 @@
+name: Docs dispatch
+
+# Fires on push to main when content that affects the published docs site
+# changes (docs/, README, or CHANGELOG). Notifies makegov/docs via
+# repository_dispatch so the docs site rebuilds without waiting for someone
+# to push to the composer.
+#
+# tango-python is a `coloc-source` repo: its docs/ folder is the authoritative
+# source for the Python SDK pages on docs.makegov.com (see makegov/docs#15).
+#
+# Required secrets:
+#   DOCS_DISPATCH_TOKEN — GitHub token with contents:write on makegov/docs.
+#
+# Required variables (optional):
+#   DOCS_TARGET_REPO — override the dispatch target (default: makegov/docs).
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "CHANGELOG.md"
+  workflow_dispatch:
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Detect changed paths
+        id: changes
+        run: |
+          set -euo pipefail
+          base=$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)
+          external=$(git diff --name-only "$base" HEAD -- 'docs' 'README.md' 'CHANGELOG.md' | paste -sd, -)
+          {
+            echo "external=$external"
+            echo "has_external=$([ -n "$external" ] && echo true || echo false)"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch to docs composer (makegov/docs)
+        if: steps.changes.outputs.has_external == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          TARGET: ${{ vars.DOCS_TARGET_REPO || 'makegov/docs' }}
+        run: |
+          gh api "repos/$TARGET/dispatches" \
+            -f event_type=external_updated \
+            -f "client_payload[source_repo]=${{ github.repository }}" \
+            -f "client_payload[source_ref]=${{ github.sha }}" \
+            -f "client_payload[changed_paths]=${{ steps.changes.outputs.external }}"

{tango_python-0.5.0 → tango_python-1.0.0}/.gitignore

@@ -149,4 +149,28 @@ Thumbs.db
 yoni/
 .cursor/*
 
-examples/
+examples/
+
+.claude-plugin/
+CLAUDE.md
+# >>> mg-tools >>>
+# --- mg-tools (per-developer; re-run 'mg-tools install' after clone) ---
+.claude-plugin/plugin-pointer.json
+.claude/settings.json
+.claude/settings.local.json
+.claude/mg-tools-integration.md
+.mcp.json
+.mcp.disabled.json
+.mg-tools/
+.claude/worktrees/
+.claude/scheduled_tasks.lock
+.claude.bak.*
+.cursor.bak.*
+.mcp.json.bak.*
+# Local IDE/editor config files
+.vscode/
+*.code-workspace
+.zed/
+.idea/
+# <<< mg-tools <<<
+>>>>>>> Stashed changes

tango_python-1.0.0/CHANGELOG.md

@@ -0,0 +1,177 @@
+# 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).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-13
+
+> First stable release. `tango-python` is now at full API parity with the
+> Tango HTTP surface, the legacy subject-based webhook subscription
+> mechanism has been removed in favor of filter alerts, the shape parser
+> agrees byte-for-byte with the server's expand-alias handling, and the
+> SDK's docs are auto-published to `docs.makegov.com/sdks/python/` via the
+> composer pipeline (makegov/docs#15 / makegov/docs#16). From `1.x` on,
+> we'll only do breaking changes on a major bump.
+>
+> Originally tracked as: API parity (PR #25), subject-based webhook
+> removal (PR #27 / issue #2275), shape-validator alias support (PR #28 /
+> issue #2266), and the docs-only content port (makegov/docs#16).
+
+### Added
+- `ordering` parameter on `list_forecasts`, `list_grants`, `list_subawards`, `list_gsa_elibrary_contracts`, and `list_opportunities`. Prefix with `-` for descending. Closes a parity gap with the API surface (these endpoints all accept `?ordering=` server-side).
+- `create_webhook_endpoint` accepts `name=` (keyword-only) and now **requires** it. The Tango API enforces unique `(user, name)` on endpoints; omitting `name` returns a 400 server-side, so the SDK raises `TangoValidationError` client-side instead of round-tripping. (0.7.0 — never publicly released — emitted a `DeprecationWarning` instead.)
+- `update_webhook_endpoint` accepts `name=` for renaming an endpoint.
+- Webhook alerts (filter subscriptions): `list_webhook_alerts`, `get_webhook_alert`, `create_webhook_alert`, `update_webhook_alert`, `delete_webhook_alert` — the canonical write surface over `/api/webhooks/alerts/`. New `WebhookAlert` dataclass exported from the top-level package.
+- `resolve(name, target_type, ...)` — POST `/api/resolve/` to rank entity / organization candidates from a free-text name. Returns `ResolveResult` with `ResolveCandidate` entries (both exported).
+- `validate(identifier_type, value)` — POST `/api/validate/` to validate the format of a PIID, solicitation number, or UEI. Returns `ValidateResult` (exported).
+- 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 sub-resources: `list_idv_lcats`.
+- Agency sub-resources: `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/`.
+
+### Changed
+- `create_webhook_alert` accepts `endpoint=` (keyword-only). Required for accounts with multiple webhook endpoints; auto-resolves for single-endpoint accounts. Closes the multi-endpoint smoke-test gap (tango#2256).
+- `test_webhook_delivery` now sends the canonical `endpoint` body key instead of the deprecated `endpoint_id` alias (tango#2252). The Python kwarg name stays `endpoint_id=` for backwards compatibility; the wire payload is what changed.
+- **`generate_signature(body, secret)` now returns the full wire form `"sha256=<hex>"`** instead of bare hex. Callers can assign the return value directly to the `X-Tango-Signature` header without wrapping in a format string. This is a breaking change for code that relied on the bare-hex return; pass it through `parse_signature_header()` to recover the previous form. `verify_signature` accepts both prefixed and bare-hex inputs (unchanged), so receivers continue to work either way.
+
+### Removed
+- **Subject-based webhook subscription surface** (tango#2275). Migrate to `create_webhook_alert(...)` and the alerts API.
+  - Methods: `list_webhook_subscriptions`, `get_webhook_subscription`, `create_webhook_subscription`, `update_webhook_subscription`, `delete_webhook_subscription`.
+  - Dataclasses: `WebhookSubscription`, `WebhookSubjectTypeDefinition`. Both are no longer exported from the top-level `tango` package — importing them raises `ImportError`.
+  - Fields: `default_subject_type` removed from `WebhookEventType`; `subject_types` and `subject_type_definitions` removed from `WebhookEventTypesResponse`. The server's `/api/webhooks/event-types/` response no longer carries these.
+  - CLI: the entire `tango webhooks subscriptions` Click subgroup (`list` / `get` / `create` / `delete`). Use the SDK's `client.create_webhook_alert(...)` etc. directly — there is no CLI subgroup for alerts.
+- `ordering` kwarg from `list_notices` and `list_protests`. The notices and protests viewsets reject every `?ordering=` value at runtime (tango#2254); the kwarg silently sent unsupported values. Other five list methods retain `ordering`.
+
+### Fixed
+- `TangoClient._post()` and `_patch()` accept both `json_data=` (positional) and `json=` (keyword) for backward compatibility. Internal callers and docs examples that use `json=` no longer fail with `TypeError`. Passing **both** now raises `TangoValidationError` rather than silently preferring one — that ambiguity would hide caller bugs.
+- `get_psc_metrics` / `get_naics_metrics` / `get_entity_metrics` docstrings — `period_grouping` values are `"month"` / `"quarter"` / `"year"` (the path-segment values the API accepts), not `"monthly"` / `"quarterly"`.
+- `docs/API_REFERENCE.md#get_agency` — example uses `client.get_agency("GSA")` consistently and notes the parameter accepts CGAC / FPDS / short code / abbreviation / canonical name.
+- `README.md` Quick Start — `get_agency()` returns an `Agency` dataclass, so the example uses attribute access (`agency.name`) instead of `agency['name']` which would `TypeError`.
+- `scripts/smoke_api_parity.py` — `list_business_types(limit=1)` is now wrapped in the `run(...)` helper so a failure on that call records FAIL instead of aborting the smoke run.
+- `tango webhooks endpoints create` CLI now accepts and requires `--name` (passed through to `create_webhook_endpoint(name=...)`). Previously the option was absent, meaning the CLI could never set a custom endpoint name and every call would 400 server-side (the server enforces `unique(user, name)`).
+- `WebhookAlert.query_type` and `WebhookAlert.filters` tightened from `Optional` to non-optional (`str` and `dict[str, Any]` respectively). Legacy nullable rows were purged by the tango#2275 migration; the server model and serializer guarantee non-null values for all current data. `WebhookAlert.status` narrowed from `str` to `Literal["active", "paused"]` — the server serializer produces exactly those two values.
+- **Shape validator agrees with server on `naics(...)` / `psc(...)` expansions.** The client-side `ShapeParser.validate()` previously rejected the canonical `shape=naics(code,description)` form (which the server has always accepted) and also rejected the alias `shape=naics_code(code,description)`. The parser now mirrors the server's `_EXPAND_ALIASES` (introduced in Tango PR makegov/tango#2259) and rewrites `naics_code(...)` / `psc_code(...)` to their canonical `naics(...)` / `psc(...)` form at parse time. Bare scalar leaves (`shape=naics_code` / `shape=psc_code`) are left untouched and still return the raw column value, matching the server. Schemas for `Contract`, `Forecast`, `Opportunity`, `Notice`, and `Vehicle` gained explicit `naics` / `psc` expand entries backed by the existing `CodeDescription` nested model. Fixes makegov/tango#2266.
+- **`Subaward` schema matches the server's `SubawardSerializer`.** The previous `SUBAWARD_SCHEMA` declared two fields the server has never exposed (`id`, `amount`) and was missing every real field on the resource — including `piid`, `key`, `awarding_office` / `funding_office` / `place_of_performance` / `subaward_details` / `fsrs_details` / `highly_compensated_officers` / `usaspending_permalink`, and the denormalized `prime_awardee_*` / `recipient_*` lookup columns. Shape strings that referenced any real field (e.g. `shape="piid"`) would fail client-side validation with `unknown_field`, and conversely the SDK happily passed `shape="id"` / `shape="amount"` through to the server, where they were rejected. `SUBAWARD_SCHEMA` is now derived directly from `awards.serializers.subawards.SubawardSerializer` and the resource's runtime `available_fields`. The `Subaward` dataclass in `tango/models.py` was updated to match. New nested schemas `SubawardDetails`, `FsrsDetails`, `SubawardPlaceOfPerformance`, and `HighlyCompensatedOfficer` are registered so the corresponding shape expansions validate end-to-end.
+
+### Documentation
+- New `docs/ERRORS.md` — full exception hierarchy, recovery patterns, and the shape-error classes (`ShapeValidationError`, `ShapeParseError`, `TypeGenerationError`, `ModelInstantiationError`). Ported from `docs.makegov.com/sdks/python/errors.md` ahead of the docs-site auto-pull cutover (makegov/docs#15 / makegov/docs#16).
+- New `docs/PAGINATION.md` — page-based vs cursor-based strategies, iteration patterns, and the `PaginatedResponse` field reference. Ported from `docs.makegov.com/sdks/python/pagination.md`.
+- New `docs/CLIENT.md` — `TangoClient` constructor reference, `rate_limit_info` / `last_response_headers` properties, and retry-semantics note (the SDK has no built-in retry). Ported from `docs.makegov.com/sdks/python/client.md`.
+
+### CI
+- New `.github/workflows/docs-dispatch.yml` — fires on push to `main` when `docs/**`, `README.md`, or `CHANGELOG.md` changes and dispatches `external_updated` at `makegov/docs` so the public docs site rebuilds with the latest SDK content. Required for the makegov/docs#15 auto-pull pipeline.
+
+## [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.5.0 → tango_python-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 0.5.0
+Version: 1.0.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
@@ -94,12 +96,14 @@ print(f"Found {agencies.count} agencies")
 
 # Get specific agency
 agency = client.get_agency("GSA")
-print(f"Agency: {agency['name']}")
+print(f"Agency: {agency.name}")
 
 # Search contracts
 contracts = client.list_contracts(
     limit=10
 )
+```
+
 ## Authentication
 
 Most endpoints require an API key. You can obtain one from the [Tango API portal](https://tango.makegov.com).
@@ -224,9 +228,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)
@@ -254,13 +263,13 @@ opportunities = client.list_opportunities(agency="DOD", active=True, limit=25)
 ### Notices
 
 ```python
-notices = client.list_notices(agency="DOD", notice_type="award", limit=25)
+notices = client.list_notices(agency="DOD", notice_type="Presolicitation", limit=25)
 ```
 
 ### Grants
 
 ```python
-grants = client.list_grants(agency="HHS", status="forecasted", limit=25)
+grants = client.list_grants(agency="HHS", status="F", limit=25)  # F = Forecasted
 ```
 
 ### Protests
@@ -280,12 +289,45 @@ contract = client.get_gsa_elibrary_contract("UUID")
 ### Reference Data
 
 ```python
-# Offices, organizations, NAICS, subawards, business types
+# Offices, organizations, NAICS, PSC, subawards, business types
 offices = client.list_offices(search="acquisitions")
 organizations = client.list_organizations(level=1)
 naics = client.list_naics(search="software")
+get_naics = client.get_naics("541511")
+psc = client.list_psc()
 subawards = client.list_subawards(prime_uei="UEI123")
 business_types = client.list_business_types()
+mas_sins = client.list_mas_sins()
+assistance = client.list_assistance_listings()
+departments = client.list_departments()
+```
+
+### Resolve / Validate
+
+```python
+# Resolve a name to entity/org candidates
+result = client.resolve(name="Lockheed Martin", target_type="entity")
+for c in result.candidates:
+    print(c.identifier, c.display_name)
+
+# Validate an identifier
+result = client.validate(identifier_type="uei", value="ABCDEF123456")
+```
+
+### IT Dashboard
+
+```python
+investments = client.list_itdashboard_investments(search="cloud", limit=25)
+investment = client.get_itdashboard_investment("023-000001234")
+```
+
+### Entity Sub-resources
+
+```python
+contracts = client.list_entity_contracts("ABCDEF123456", limit=25)
+idvs = client.list_entity_idvs("ABCDEF123456")
+otas = client.list_entity_otas("ABCDEF123456")
+metrics = client.get_entity_metrics("ABCDEF123456", months=12, period_grouping="month")
 ```
 
 ## Pagination
@@ -303,9 +345,9 @@ print(f"Previous page URL: {response.previous}")
 for contract in response.results:
     print(contract['description'])
 
-# Get next page
+# Get next page (contracts use keyset/cursor pagination)
 if response.next:
-    next_response = client.list_contracts(page=2, limit=25)
+    next_response = client.list_contracts(cursor=response.cursor, limit=25)
 ```
 
 ## Error Handling
@@ -332,7 +374,7 @@ except TangoNotFoundError:
     print("Resource not found")
 except TangoValidationError as e:
     print(f"Invalid parameters: {e.message}")
-    print(f"Details: {e.details}")
+    print(f"Details: {e.response_data}")
 except TangoRateLimitError:
     print("Rate limit exceeded")
 except TangoAPIError as e:
@@ -364,24 +406,59 @@ contracts = client.list_contracts(
 
 ### Flattened Responses
 
-Enable flattening to get dot-notation field names:
+The `flat=True` parameter is passed to the API, which returns dot-notation keys in the raw response. The SDK still wraps the result in a `ShapedModel` — access nested fields via attribute or dict syntax, not dot-notation string keys:
 
 ```python
 contracts = client.list_contracts(
     shape="key,piid,recipient(display_name,uei)",
     flat=True
 )
-# Returns: {"key": "...", "piid": "...", "recipient.display_name": "...", "recipient.uei": "..."}
+for contract in contracts.results:
+    # Attribute access
+    print(contract.recipient.display_name)
+    # Dict access (nested, not flat string keys)
+    print(contract['recipient']['display_name'])
+```
 
-# Flatten arrays with indexed keys
-contracts = client.list_contracts(
-    shape="key,transactions(*)",
-    flat=True,
-    flat_lists=True
-)
-# 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 delivery endpoints
+tango webhooks endpoints 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 +608,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