feat: flatten payment_required_header to kwargs; delete PaymentRequiredHeaderInput (#36)

## Summary

Drops the wrapper for `payment_required_header` — the x402
PAYMENT-REQUIRED header builder.

| Before | After |
|---|---|
| `payment_required_header(PaymentRequiredHeaderInput(x402_version=...,
accepts=..., resource=...))` | `payment_required_header(*, x402_version,
accepts, resource=None)` |

Also drops the wrapper-bridge `respond_402` carried since #32 — its
public `x402: dict` kwarg now flows straight to
`payment_required_header(**x402)` without re-wrapping.

## Internal callers updated

- `challenge/respond_402.py`
- `payment/headers.py` (`build_payment_headers` x402 branch)
- `discovery/probe.py` (discovery probe PAYMENT-REQUIRED header)

## Deleted from exports

`PaymentRequiredHeaderInput`.

## Test plan

- [x] `uv run pytest tests/` — 1031 passed / 3 skipped, 95.04% coverage
- [x] `uv run ty check agentscore_commerce/` — clean
- [x] `uv run ruff check . && uv run ruff format .` — clean
- [x] `uv run vulture agentscore_commerce/ --min-confidence 80` — only
the known string-cast / Protocol-param false positives remain (unchanged
from main)

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

Author: vvillait88

agentscore_commerce/challenge/respond_402.py

@@ -30,7 +30,7 @@
 from dataclasses import dataclass
 from typing import Any
 
-from agentscore_commerce.payment.wwwauthenticate import PaymentRequiredHeaderInput, payment_required_header
+from agentscore_commerce.payment.wwwauthenticate import payment_required_header
 
 
 @dataclass
@@ -61,8 +61,5 @@ def respond_402(
     headers = {k.lower(): v for k, v in mppx_challenge_headers.items()}
     headers["content-type"] = "application/json"
     if x402 is not None:
-        # PaymentRequiredHeaderInput still exists pending the wwwauthenticate
-        # flatten in a subsequent PR; respond_402's public API takes a dict now
-        # and we adapt internally so the wrapper deletion is invisible to callers.
-        headers["payment-required"] = payment_required_header(PaymentRequiredHeaderInput(**x402))
+        headers["payment-required"] = payment_required_header(**x402)
     return Respond402Result(body=body, headers=headers, status=402)

agentscore_commerce/discovery/probe.py

@@ -12,10 +12,7 @@
 )
 from agentscore_commerce.payment.networks import networks
 from agentscore_commerce.payment.usdc import USDC
-from agentscore_commerce.payment.wwwauthenticate import (
-    PaymentRequiredHeaderInput,
-    payment_required_header,
-)
+from agentscore_commerce.payment.wwwauthenticate import payment_required_header
 
 # Placeholder payTo for x402 sample accepts in the discovery probe — the probe
 # exists for crawlers to find that we support x402, not for actual payment.
@@ -156,7 +153,7 @@ def build_discovery_probe_response(opts: DiscoveryProbeOptions) -> DiscoveryProb
                 "url": opts.x402_sample.resource_url,
                 "mimeType": "application/json",
             }
-        encoded = payment_required_header(PaymentRequiredHeaderInput(**header_kwargs))
+        encoded = payment_required_header(**header_kwargs)
         headers["payment-required"] = encoded
         # Mirror the aliased accepts in the body so clients that fall back from
         # header → body (e.g. awal's discover) can still extract requirements.

agentscore_commerce/payment/__init__.py

@@ -36,7 +36,6 @@
 )
 from agentscore_commerce.payment.usdc import USDC
 from agentscore_commerce.payment.wwwauthenticate import (
-    PaymentRequiredHeaderInput,
     alias_amount_fields,
     payment_required_header,
     www_authenticate_header,
@@ -87,7 +86,6 @@
     "NetworkFamily",
     "PaymentHeadersRail",
     "PaymentHeadersResult",
-    "PaymentRequiredHeaderInput",
     "PaymentSigner",
     "ProcessX402SettleFailure",
     "ProcessX402SettleResult",

agentscore_commerce/payment/headers.py

@@ -16,7 +16,6 @@
 
 from agentscore_commerce.payment.directive import build_payment_directive
 from agentscore_commerce.payment.wwwauthenticate import (
-    PaymentRequiredHeaderInput,
     payment_required_header,
     www_authenticate_header,
 )
@@ -138,11 +137,9 @@ def build_payment_headers(
 
     if x402 is not None:
         result["payment_required"] = payment_required_header(
-            PaymentRequiredHeaderInput(
-                x402_version=x402.version,
-                accepts=x402.accepts,
-                resource=x402.resource,
-            ),
+            x402_version=x402.version,
+            accepts=x402.accepts,
+            resource=x402.resource,
         )
 
     return result

agentscore_commerce/payment/wwwauthenticate.py

@@ -2,7 +2,6 @@
 
 import base64
 import json
-from dataclasses import dataclass
 from typing import Any, Literal
 
 
@@ -39,21 +38,19 @@ def alias_amount_fields(accepts: list[Any]) -> list[Any]:
     return out
 
 
-@dataclass
-class PaymentRequiredHeaderInput:
-    x402_version: Literal[1, 2]
-    accepts: list[Any]
-    resource: dict[str, str] | None = None
-
-
-def payment_required_header(input: PaymentRequiredHeaderInput) -> str:
+def payment_required_header(
+    *,
+    x402_version: Literal[1, 2],
+    accepts: list[Any],
+    resource: dict[str, str] | None = None,
+) -> str:
     """Encode the standard x402 PAYMENT-REQUIRED header (base64-encoded JSON).
 
     Each accepts entry is post-processed via :func:`alias_amount_fields` so v1-only
     clients (e.g. awal) and v2-strict clients can both read it.
     """
-    body: dict[str, Any] = {"x402Version": input.x402_version, "accepts": alias_amount_fields(input.accepts)}
-    if input.resource is not None:
-        body["resource"] = input.resource
+    body: dict[str, Any] = {"x402Version": x402_version, "accepts": alias_amount_fields(accepts)}
+    if resource is not None:
+        body["resource"] = resource
     raw = json.dumps(body, separators=(",", ":")).encode()
     return base64.b64encode(raw).decode()

tests/test_payment_misc.py

@@ -4,7 +4,6 @@
 from agentscore_commerce.payment import (
     SETTLEMENT_OVERRIDES_HEADER,
     USDC,
-    PaymentRequiredHeaderInput,
     lookup_rail,
     network_family,
     networks,
@@ -58,9 +57,7 @@ def test_www_authenticate_header_joins_directives():
 
 
 def test_payment_required_header_base64_encodes_json():
-    h = payment_required_header(
-        PaymentRequiredHeaderInput(x402_version=2, accepts=[{"scheme": "exact"}], resource={"url": "https://x"})
-    )
+    h = payment_required_header(x402_version=2, accepts=[{"scheme": "exact"}], resource={"url": "https://x"})
     decoded = json.loads(base64.b64decode(h))
     assert decoded["x402Version"] == 2
     assert decoded["accepts"] == [{"scheme": "exact"}]
@@ -75,10 +72,8 @@ def test_payment_required_header_emits_v1_alias_for_v2_clients():
     from agentscore_commerce.payment import alias_amount_fields
 
     h = payment_required_header(
-        PaymentRequiredHeaderInput(
-            x402_version=2,
-            accepts=[{"scheme": "exact", "network": "eip155:84532", "amount": "110000"}],
-        )
+        x402_version=2,
+        accepts=[{"scheme": "exact", "network": "eip155:84532", "amount": "110000"}],
     )
     decoded = json.loads(base64.b64decode(h))
     assert decoded["accepts"][0]["amount"] == "110000"