feat: 2.1.1 — typed errors, bootstrap session helper, stripe $0.50 auto-drop

[vvillait88]

Summary

Python parity for the node-commerce 2.1.1 release (agentscore/node-commerce#55).

1. Typed errors in stripe-multichain + dispatch helpers

• pay_to_address.py: malformed Authorization: Payment, cache-miss recipient, missing recipient field → CheckoutValidationError(401, invalid_credential, action=retry_without_credential). Fallback when none of preferred/base/tempo recipients land → 503 payment_provider_unavailable.
• payment_intent.py: Stripe returns an empty deposit_addresses map → 503 payment_provider_unavailable.
• payment/dispatch.py: unregistered EVM/Solana handler or unrecognized network family → 503 payment_provider_unavailable.

Previously these all surfaced as bare ValueError / RuntimeError → 500 to the agent.

2. CheckoutValidationError extraction to its own module

agentscore_commerce/errors.py is the new canonical home. checkout.py, checkout_compute_first.py, identity/policy.py, stripe_multichain/{pay_to_address,payment_intent}.py, payment/dispatch.py import directly. Top-level __init__.py re-exports for the public surface.

This breaks the identity.policy → checkout cycle that previously required lazy/local imports.

3. build_verification_required_body(reason, message=?, agent_instructions=?, extra=?) helper

Collapses the per-merchant identity_verification_required body mapping into one call. Same shape as the node helper.

4. (Already existing — preserved) Checkout auto-defaults create_session_on_missing

From gate.api_key + gate.base_url + gate.context + gate.merchant_name when not supplied.

5. Stripe $0.50 USD auto-drop (compose + discovery)

Stripe's fixed ~$0.30 fee makes sub-50-cent card charges unprofitable (a $0.11 PI nets -$0.19 after fees); many accounts also reject PI creation under the floor with amount_too_small. The SDK now drops the stripe/charge rail from BOTH layers when amount_usd < 0.50:

• build_mppx_compose_rails in agentscore_commerce/payment/compose_rails.py — drops the stripe/charge intent at mppx compose time with a one-time logging.warning. Warn-once state lives on a _WarnedFlags class (module-level class attribute, lint-clean).
• Checkout._emit_402 in agentscore_commerce/checkout.py AND compute_first_checkout._emit_402 in agentscore_commerce/checkout_compute_first.py — strip the stripe slot from the rails dict before build_accepted_methods / build_how_to_pay run, so the 402 body's accepted_methods + agent_instructions.how_to_pay stay consistent with what pympp will actually accept.

Pass include_stripe=False to suppress the warning when the merchant knows their pricing tier is permanently sub-50-cent. Shared constant: agentscore_commerce/payment/constants.py:STRIPE_MIN_CHARGE_USD.

6. In-range deps bumps

lefthook 2.1.6 → 2.1.8. uv sync --upgrade --all-extras --all-groups; no major bumps.

Version

• 2.1.0 → 2.1.1

Test plan

• uv run ruff check .
• uv run ty check agentscore_commerce/
• uv run pytest tests/ — 1385 pass + 4 skipped, 95.05% coverage (clears 95% bar)
• Cross-language parity verified against node-commerce 2.1.1 (same auto-drop behavior at $0.50 boundary, same envelope shape)

🤖 Generated with Claude Code