CLI: clarify simulate output; add fetch-sample and list-event-types

The simulate output's `sent_bytes` (length only) and `response_body`
(the receiver's pong) were both confusing for devs who really want to
see the canonical Tango shape they're driving their handler with:

- `sent_bytes` (int) → `sent_payload` (the parsed JSON dict)
- `response_body` → `receiver_response` (clarifies whose body it is)

Two new subcommands close the discovery loop for devs building against
the Tango API:

- `tango webhooks fetch-sample [--event-type X]` — print the canonical
  sample payload Tango emits (read-only, no POST). Wraps the SDK's
  `get_webhook_sample_payload`.
- `tango webhooks list-event-types` — list every event type Tango
  supports with descriptions. Wraps `list_webhook_event_types`.

Together: `list-event-types` → pick one → `fetch-sample` to see the
shape → `simulate --event-type X` to drive the handler with that shape,
all without leaving the shell.

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

Author: vdavez

CHANGELOG.md

@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `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 with `webhooks listen|trigger|simulate` subcommands. Stripe-CLI-style developer ergonomics for testing webhook integrations.
+- New `tango[webhooks]` extra (adds `click`) ships a `tango` console script with `webhooks listen|trigger|simulate|fetch-sample|list-event-types` subcommands. Stripe-CLI-style developer ergonomics for testing webhook integrations: `fetch-sample` and `list-event-types` let devs discover canonical payload shapes without dropping into Python.
 
 ### Notes
 - Console script name `tango` may be revisited before the next release if it conflicts with sibling tooling (`tango-scripts` reuses the bare name).

tango/webhooks/cli.py

@@ -202,16 +202,69 @@ def simulate_cmd(
             {
                 "status_code": result.status_code,
                 "signature": f"sha256={result.signature}",
-                "sent_bytes": len(result.sent_bytes),
-                "response_body": result.response_body[:500],
+                "sent_payload": payload,
+                "receiver_response": result.response_body[:500],
             },
             indent=2,
+            sort_keys=True,
         )
     )
     if result.status_code >= 400:
         raise SystemExit(1)
 
 
+@webhooks.command("fetch-sample")
+@click.option(
+    "--event-type",
+    default=None,
+    help="If set, fetch the canonical sample for that event type. "
+    "Otherwise return the full samples mapping for every event type.",
+)
+@click.option(
+    "--api-key",
+    envvar="TANGO_API_KEY",
+    help="Tango API key (or TANGO_API_KEY).",
+)
+@click.option(
+    "--base-url",
+    envvar="TANGO_BASE_URL",
+    default="https://tango.makegov.com",
+    show_default=True,
+    help="Tango base URL (or TANGO_BASE_URL).",
+)
+def fetch_sample_cmd(event_type: str | None, api_key: str | None, base_url: str) -> None:
+    """Print the canonical sample payload Tango emits for a given event type."""
+    from tango import TangoClient
+
+    client = TangoClient(api_key=api_key, base_url=base_url)
+    payload = client.get_webhook_sample_payload(event_type=event_type)
+    click.echo(json.dumps(payload, indent=2, sort_keys=True))
+
+
+@webhooks.command("list-event-types")
+@click.option(
+    "--api-key",
+    envvar="TANGO_API_KEY",
+    help="Tango API key (or TANGO_API_KEY).",
+)
+@click.option(
+    "--base-url",
+    envvar="TANGO_BASE_URL",
+    default="https://tango.makegov.com",
+    show_default=True,
+    help="Tango base URL (or TANGO_BASE_URL).",
+)
+def list_event_types_cmd(api_key: str | None, base_url: str) -> None:
+    """List webhook event types Tango supports, with descriptions."""
+    from tango import TangoClient
+
+    client = TangoClient(api_key=api_key, base_url=base_url)
+    response = client.list_webhook_event_types()
+    width = max((len(et.event_type) for et in response.event_types), default=0)
+    for et in response.event_types:
+        click.echo(f"{et.event_type:<{width}}  {et.description}")
+
+
 def _print_delivery(delivery: Delivery) -> None:
     """Default ``listen`` callback: write a one-line summary plus body."""
     summary = _summarize(delivery.body_json)

tests/test_webhooks_cli.py

@@ -17,6 +17,8 @@ def test_cli_help() -> None:
     assert "listen" in result.output
     assert "trigger" in result.output
     assert "simulate" in result.output
+    assert "fetch-sample" in result.output
+    assert "list-event-types" in result.output
 
 
 def test_cli_simulate_signs_and_posts(tmp_path: object) -> None:
@@ -43,6 +45,11 @@ def test_cli_simulate_signs_and_posts(tmp_path: object) -> None:
         body = json.loads(result.output)
         assert body["status_code"] == 200
         assert body["signature"].startswith("sha256=")
+        # Output now includes the actual payload that was sent (the dev's
+        # main artifact of interest), not just its byte length.
+        assert isinstance(body["sent_payload"], dict)
+        assert "events" in body["sent_payload"]
+        assert body["receiver_response"] == '{"ok": true}'
 
 
 def test_cli_simulate_with_payload_file(tmp_path: object) -> None:
@@ -72,6 +79,70 @@ def test_cli_simulate_with_payload_file(tmp_path: object) -> None:
         assert rx.deliveries[0].body_json == payload
 
 
+def test_cli_fetch_sample_prints_payload() -> None:
+    """fetch-sample hits the SDK's get_webhook_sample_payload and pretty-prints."""
+    from unittest.mock import Mock, patch
+
+    sample = {"events": [{"event_type": "entities.updated", "uei": "ABC"}]}
+    mock_response = Mock()
+    mock_response.status_code = 200
+    mock_response.headers = {}
+    mock_response.json.return_value = sample
+    mock_response.raise_for_status = Mock()
+
+    runner = CliRunner()
+    with patch("tango.client.httpx.Client.request", return_value=mock_response):
+        result = runner.invoke(
+            main,
+            [
+                "webhooks",
+                "fetch-sample",
+                "--event-type",
+                "entities.updated",
+                "--api-key",
+                "k",
+            ],
+        )
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.output) == sample
+
+
+def test_cli_list_event_types_prints_table() -> None:
+    from unittest.mock import Mock, patch
+
+    api_response = {
+        "event_types": [
+            {
+                "event_type": "entities.updated",
+                "default_subject_type": "entity",
+                "description": "Entity updated",
+                "schema_version": 1,
+            },
+            {
+                "event_type": "awards.created",
+                "default_subject_type": "award",
+                "description": "New award",
+                "schema_version": 1,
+            },
+        ],
+        "subject_types": [],
+        "subject_type_definitions": [],
+    }
+    mock_response = Mock()
+    mock_response.status_code = 200
+    mock_response.headers = {}
+    mock_response.json.return_value = api_response
+    mock_response.raise_for_status = Mock()
+
+    runner = CliRunner()
+    with patch("tango.client.httpx.Client.request", return_value=mock_response):
+        result = runner.invoke(main, ["webhooks", "list-event-types", "--api-key", "k"])
+    assert result.exit_code == 0, result.output
+    assert "entities.updated" in result.output
+    assert "Entity updated" in result.output
+    assert "awards.created" in result.output
+
+
 def test_cli_simulate_rejects_both_modes() -> None:
     runner = CliRunner()
     result = runner.invoke(