tango-python 0.2.0__tar.gz → 0.3.0__tar.gz

{tango_python-0.2.0 → tango_python-0.3.0}/.github/workflows/publish.yml

@@ -3,6 +3,7 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   build-and-publish:
@@ -24,5 +25,5 @@ jobs:
     
     - name: Publish to PyPI
       env:
-        UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        UV_PUBLISH_TOKEN: ${{ secrets.TANGO_PYPI_TOKEN }}
       run: uv publish

{tango_python-0.2.0 → tango_python-0.3.0}/.gitignore

@@ -145,4 +145,6 @@ dmypy.json
 .DS_Store
 Thumbs.db
 
-.cursor/*
+# Other
+yoni/
+.cursor/*

tango_python-0.3.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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]
+
+### Added
+
+### Changed
+
+## [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.2.0 → tango_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 0.2.0
+Version: 0.3.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
@@ -61,7 +61,7 @@ A modern Python SDK for the [Tango API](https://tango.makegov.com) by MakeGov, f
 
 - **Dynamic Response Shaping** - Request only the fields you need, reducing payload sizes by 60-80%
 - **Full Type Safety** - Runtime-generated TypedDict types with accurate type hints for IDE autocomplete
-- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices, grants) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
+- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices, grants, webhooks) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
 - **Flexible Data Access** - Dictionary-based response objects with validation
 - **Modern Python** - Built for Python 3.12+ using modern async-ready patterns
 - **Production-Ready** - Comprehensive test suite with VCR.py-based integration tests

{tango_python-0.2.0 → tango_python-0.3.0}/README.md

@@ -6,7 +6,7 @@ A modern Python SDK for the [Tango API](https://tango.makegov.com) by MakeGov, f
 
 - **Dynamic Response Shaping** - Request only the fields you need, reducing payload sizes by 60-80%
 - **Full Type Safety** - Runtime-generated TypedDict types with accurate type hints for IDE autocomplete
-- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices, grants) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
+- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices, grants, webhooks) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
 - **Flexible Data Access** - Dictionary-based response objects with validation
 - **Modern Python** - Built for Python 3.12+ using modern async-ready patterns
 - **Production-Ready** - Comprehensive test suite with VCR.py-based integration tests

{tango_python-0.2.0 → tango_python-0.3.0}/docs/API_REFERENCE.md

@@ -7,12 +7,15 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Client Initialization](#client-initialization)
 - [Agencies](#agencies)
 - [Contracts](#contracts)
+- [IDVs](#idvs)
+- [Vehicles](#vehicles)
 - [Entities](#entities)
 - [Forecasts](#forecasts)
 - [Opportunities](#opportunities)
 - [Notices](#notices)
 - [Grants](#grants)
 - [Business Types](#business-types)
+- [Webhooks](#webhooks)
 - [Response Objects](#response-objects)
 - [Error Handling](#error-handling)
 
@@ -271,6 +274,119 @@ contracts = client.list_contracts(
 
 ---
 
+## Vehicles
+
+Vehicles provide a solicitation-centric way to discover groups of related IDVs and (optionally) expand into the underlying awards via shaping.
+
+### list_vehicles()
+
+List vehicles with optional vehicle-level full-text search.
+
+```python
+vehicles = client.list_vehicles(
+    page=1,
+    limit=25,
+    search="GSA schedule",
+    shape=ShapeConfig.VEHICLES_MINIMAL,
+    flat=False,
+    flat_lists=False,
+)
+```
+
+**Parameters:**
+- `page` (int): Page number (default: 1)
+- `limit` (int): Results per page (default: 25, max: 100)
+- `search` (str, optional): Vehicle-level search term
+- `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
+- `joiner` (str): Joiner used when `flat=True` (default: `"."`)
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with vehicle dictionaries
+
+### get_vehicle()
+
+Get a single vehicle by UUID.
+
+```python
+vehicle = client.get_vehicle(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLES_COMPREHENSIVE,
+)
+```
+
+**Notes:**
+- On the vehicle detail endpoint, `search` filters **expanded awardees** when your `shape` includes `awardees(...)` (it does not filter the vehicle itself).
+
+### list_vehicle_awardees()
+
+List the IDV awardees for a vehicle.
+
+```python
+awardees = client.list_vehicle_awardees(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLE_AWARDEES_MINIMAL,
+)
+```
+
+---
+
+## IDVs
+
+IDVs (indefinite delivery vehicles) are the parent “vehicle award” records that can have child awards/orders under them.
+
+### list_idvs()
+
+```python
+idvs = client.list_idvs(
+    limit=25,
+    cursor=None,
+    shape=ShapeConfig.IDVS_MINIMAL,
+    awarding_agency="4700",
+)
+```
+
+Notes:
+
+- This endpoint uses **keyset pagination** (`cursor` + `limit`) rather than page numbers.
+
+### get_idv()
+
+```python
+idv = client.get_idv("SOME_IDV_KEY", shape=ShapeConfig.IDVS_COMPREHENSIVE)
+```
+
+### list_idv_awards()
+
+Lists child awards (contracts) under an IDV.
+
+```python
+awards = client.list_idv_awards("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_child_idvs()
+
+Lists child IDVs under an IDV.
+
+```python
+children = client.list_idv_child_idvs("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_transactions()
+
+```python
+tx = client.list_idv_transactions("SOME_IDV_KEY", limit=100)
+```
+
+### get_idv_summary() / list_idv_summary_awards()
+
+```python
+summary = client.get_idv_summary("SOLICITATION_IDENTIFIER")
+awards = client.list_idv_summary_awards("SOLICITATION_IDENTIFIER", limit=25)
+```
+
+---
+
 ## Entities
 
 Vendors, recipients, and organizations doing business with the government.
@@ -606,6 +722,135 @@ for biz_type in business_types.results:
 
 ---
 
+## Webhooks
+
+Webhook APIs let **Large / Enterprise** users manage subscription filters for outbound Tango webhooks.
+
+### list_webhook_event_types()
+
+Discover supported `event_type` values and subject types.
+
+```python
+info = client.list_webhook_event_types()
+print(info.event_types[0].event_type)
+```
+
+### list_webhook_subscriptions()
+
+```python
+subs = client.list_webhook_subscriptions(page=1, page_size=25)
+```
+
+Notes:
+
+- This endpoint uses `page` + `page_size` (tier-capped) rather than `limit`.
+
+### create_webhook_subscription()
+
+```python
+sub = client.create_webhook_subscription(
+    "Track specific vendors",
+    {
+        "records": [
+            {"event_type": "awards.new_award", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
+            {"event_type": "awards.new_transaction", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
+        ]
+    },
+)
+```
+
+Notes:
+
+- Prefer v2 fields: `subject_type` + `subject_ids`.
+- Legacy compatibility: `resource_ids` is accepted as an alias for `subject_ids` (don’t send both).
+- Catch-all: `subject_ids: []` means “all subjects” for that record and is **Enterprise-only**. Large tier users must list specific IDs.
+
+### update_webhook_subscription()
+
+```python
+sub = client.update_webhook_subscription("SUBSCRIPTION_UUID", subscription_name="Updated name")
+```
+
+### delete_webhook_subscription()
+
+```python
+client.delete_webhook_subscription("SUBSCRIPTION_UUID")
+```
+
+### list_webhook_endpoints()
+
+List your webhook endpoint(s).
+
+```python
+endpoints = client.list_webhook_endpoints(page=1, limit=25)
+```
+
+### get_webhook_endpoint()
+
+```python
+endpoint = client.get_webhook_endpoint("ENDPOINT_UUID")
+```
+
+### create_webhook_endpoint() / update_webhook_endpoint() / delete_webhook_endpoint()
+
+In production, MakeGov provisions the initial endpoint for you. These are most useful for dev/self-service.
+
+```python
+endpoint = client.create_webhook_endpoint("https://example.com/tango/webhooks")
+endpoint = client.update_webhook_endpoint(endpoint.id, is_active=False)
+client.delete_webhook_endpoint(endpoint.id)
+```
+
+### test_webhook_delivery()
+
+Send an immediate test webhook to your configured endpoint.
+
+```python
+result = client.test_webhook_delivery()
+print(result.success, result.status_code)
+```
+
+### get_webhook_sample_payload()
+
+Fetch Tango-shaped sample deliveries (and sample subscription request bodies).
+
+```python
+sample = client.get_webhook_sample_payload(event_type="awards.new_award")
+print(sample["event_type"])
+```
+
+### Deliveries / redelivery
+
+The API does not currently expose a public `/api/webhooks/deliveries/` or redelivery endpoint. Use:
+
+- `test_webhook_delivery()` for connectivity checks
+- `get_webhook_sample_payload()` for building handlers + subscription payloads
+
+### Receiving webhooks (signature verification)
+
+Every delivery includes an HMAC signature header:
+
+- `X-Tango-Signature: sha256=<hex digest>`
+
+Compute the digest over the **raw request body bytes** using your shared secret.
+
+```python
+import hashlib
+import hmac
+
+
+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)
+```
+
+---
+
 ## Response Objects
 
 ### PaginatedResponse

{tango_python-0.2.0 → tango_python-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -97,6 +97,7 @@ markers = [
     "live: Tests that always use live API (skip cassettes)",
     "cached: Tests that only run with cached responses",
     "slow: Tests that are slow to execute",
+    "production: Production API smoke tests that run against live API",
 ]
 
 [tool.coverage.run]

tango_python-0.3.0/scripts/README.md

@@ -0,0 +1,76 @@
+# Development Scripts
+
+This directory contains utility scripts used during development and maintenance of the tango-python library.
+
+## Scripts
+
+### Schema and API Tools
+
+- **`fetch_api_schema.py`** - Fetches the OpenAPI schema from the Tango API and saves it locally
+- **`generate_schemas_from_api.py`** - Generates schema definitions from the API reference (outputs to stdout)
+
+### Testing and Validation
+
+- **`test_production.py`** - Runs production API smoke tests against the live API
+- **`pr_review.py`** - Runs configurable validation checks for PR review (linting, type checking, tests)
+
+## Usage
+
+These scripts are primarily for maintainers and are not part of the public API.
+
+### Production API Testing
+
+Run smoke tests against the production API:
+
+```bash
+# Requires TANGO_API_KEY environment variable
+uv run python scripts/test_production.py
+```
+
+This runs fast smoke tests (~30-60 seconds) that validate core SDK functionality against the live production API.
+
+### PR Review Validation
+
+Run validation checks for PR review. **Automatically detects PR context** from GitHub Actions, GitHub CLI, or git branch.
+
+```bash
+# Auto-detect PR and run validation (default: production mode)
+uv run python scripts/pr_review.py
+
+# Review a specific PR number
+uv run python scripts/pr_review.py --pr-number 123
+
+# Smoke tests only
+uv run python scripts/pr_review.py --mode smoke
+
+# Quick validation (linting + type checking, no tests)
+uv run python scripts/pr_review.py --mode quick
+
+# Full validation (all checks including all tests)
+uv run python scripts/pr_review.py --mode full
+
+# Check only changed files (auto-enabled when PR is detected)
+uv run python scripts/pr_review.py --mode production --changed-files-only
+```
+
+**Validation Modes:**
+- `smoke` - Production API smoke tests only
+- `quick` - Linting + type checking (no tests)
+- `full` - All checks (linting + type checking + all tests)
+- `production` - Production API smoke tests + linting + type checking (default)
+
+**PR Detection:**
+The script automatically detects PR information from:
+- GitHub Actions environment variables (`GITHUB_EVENT_PATH`, `GITHUB_PR_NUMBER`)
+- GitHub CLI (`gh pr view` - requires `gh auth login`)
+- Current git branch
+
+When a PR is detected, the script displays PR information and automatically:
+- Detects the base branch from the PR
+- Checks only changed files
+- Shows PR URL in summary
+
+## Requirements
+
+- `TANGO_API_KEY` environment variable (required for production API tests)
+- All dependencies installed: `uv sync --all-extras`