Feature capability validation: require/supports API

[bokelley]

Context

The AdCP protocol already has a robust feature flag system in get_adcp_capabilities — sellers declare boolean features like audience_targeting, conversion_tracking, inline_creative_management, etc. via media_buy.features, and the schema allows arbitrary additional boolean features via additionalProperties.

However, buyer agents currently have to manually inspect the capabilities response and implement their own checks before calling feature-dependent tasks. This is error-prone and leads to mid-flow failures when a buyer assumes a seller supports something it doesn't.

The client library should make capability checking a first-class concern.

Proposed API

1. seller.supports(feature) — check a single feature

seller = await AdCPClient.connect(seller_url)

if seller.supports("audience_targeting"):
    await seller.sync_audiences(...)

if seller.supports("conversion_tracking"):
    await seller.sync_event_sources(...)

Returns True if the seller's capabilities response declares the feature as True. Returns False if the feature is absent or False.

Should work for:

• media_buy.features.* (e.g., audience_targeting, conversion_tracking, catalog_management)
• signals.features.* (e.g., catalog_signals)
• Top-level protocol support (e.g., supports("media_buy") checks supported_protocols)
• Extension support (e.g., supports("ext:scope3") checks extensions_supported)
• Targeting capabilities (e.g., supports("targeting.geo_countries"))

2. seller.require(*features) — fail fast if features are missing

seller = await AdCPClient.connect(seller_url)

# Raises AdCPFeatureUnsupported before any task calls
seller.require("audience_targeting", "conversion_tracking")

# Safe to use these features now
await seller.sync_audiences(...)
await seller.sync_event_sources(...)

The error should be actionable:

AdCPFeatureUnsupported: Seller at https://example.com does not support: audience_targeting
  Declared features: inline_creative_management, conversion_tracking, property_list_filtering
  Protocol version: 3

3. Automatic validation on task calls (optional, opt-in)

seller = await AdCPClient.connect(seller_url, validate_features=True)

# Automatically checks that seller supports audience_targeting
# before sending the request — raises AdCPFeatureUnsupported
await seller.sync_audiences(...)

This requires a mapping from task names to required features:

• sync_audiences → audience_targeting
• sync_event_sources, log_event → conversion_tracking
• sync_catalogs → catalog_management

4. Capabilities caching

The capabilities response includes last_updated. The client should:

• Cache capabilities after the first fetch
• Expose seller.refresh_capabilities() for manual refresh
• Respect reasonable TTL (e.g., 1 hour default, configurable)

Design principles

• Absent = unsupported. If a feature isn't in the response, treat it as False. No inference, no guessing.
• Fail fast, fail clearly. The error message should tell the buyer what the seller does support so the buyer agent can adapt.
• Additive features only. Within v3, new features are purely additive. If a seller doesn't know about a feature, it just doesn't declare it. Nothing breaks.
• No silent degradation. The client library should never silently drop fields or fall back. If the buyer asks for something the seller doesn't support, raise. It's the buyer agent's job to decide whether to skip the seller or simplify the request.

Non-goals

• v2 backward compatibility (v2 is being deprecated)
• Automatic feature negotiation or degradation (that's the buyer agent's domain logic)