feat(server): createUpstreamHttpClient + createTranslationMap (translator pattern helpers)

[bokelley]

Parent: #452

JS source

.changeset/adapter-translation-helpers.md (6.7).

What Python adopters write today

200+ lines of httpx.AsyncClient boilerplate per upstream — auth header injection, 404→None translation, retry/timeout policy, JSON decode. See examples/v3_reference_seller/src/upstream.py for the canonical hand-rolled version.

Plus per-adapter bidirectional code↔code translation maps (status enums, channel enums, etc.) hand-written as two parallel dicts that drift.

Proposed API

from adcp.decisioning import create_upstream_http_client, create_translation_map

client = create_upstream_http_client(
    base_url="https://api.vendor.com",
    auth={"type": "static_bearer", "token": "..."},      # or dynamic_bearer | api_key | none
    network_code="abc123",
    default_headers={...},
    timeout_s=30.0,
)
# Typed get/post/put/delete returning parsed JSON or None on 404.
account = await client.get("/accounts/{id}", params={...})

status_map = create_translation_map[AdcpStatus, UpstreamStatus]({
    "active": "ACTIVE",
    "paused": "PAUSED",
    ...
})
status_map.to_upstream("active")     # "ACTIVE"
status_map.to_adcp("ACTIVE")         # "active"
status_map.has_adcp("active")        # True
status_map.has_upstream("ACTIVE")    # True

Auth modes: static_bearer / dynamic_bearer (callable returning fresh token, used by OAuth passthrough in #6) / api_key / none.

Acceptance criteria

• Both helpers exported from adcp.decisioning.
• Tests cover: each auth mode, 404→None, retry on 5xx, JSON decode errors.
• Translation map: round-trip identity, missing-key raises, generic typing.
• examples/v3_reference_seller/src/upstream.py could be refactored to use them (defer that to a follow-up v3-ref-seller-uses-helpers PR).

[bokelley]

Triage

Classification: Feature request
Bucket(s): client (no client label exists in this repo — gap noted)
Status: clarify

What the experts said:

• code-reviewer: Three blockers before implementation: (1) create_translation_map[T1, T2](...) isn't valid Python 3.10/3.11 — function subscript requires __class_getitem__ on the callable; (2) auth as a plain dict breaks strict mypy and is inconsistent with the ApiKeyCredential/OAuthCredential dataclass pattern in adcp.decisioning.registry; (3) network_code at constructor-level conflicts with the multi-tenant pooling pattern in the existing reference seller (where it's per-call from ctx.account.metadata).
• dx-expert: Agrees on all three blockers. Also flags that KeyError with a descriptive message (listing known keys) is more ergonomic than None for missing-key lookups, and recommends a class (UpstreamClient) over a factory function for lifecycle clarity.

My take: Both experts converge on the same three spec-level questions; the acceptance criteria are otherwise well-scoped and respx is already in dev deps. Resolving these will unlock an Execute.

1. Generic syntax: Should TranslationMap be a generic class (TranslationMap[AdcpStatus, UpstreamStatus]({"active": "ACTIVE"})) rather than a subscriptable factory function? Subscripting a plain function at runtime isn't supported on Python 3.10/3.11.
2. Auth config: Should auth use typed dataclass variants (StaticBearerAuth(token=...), DynamicBearerAuth(token_fn=...), ApiKeyAuth(...), NoAuth()) instead of a plain dict, mirroring the ApiKeyCredential/OAuthCredential pattern already in adcp.decisioning.registry?
3. network_code placement: Should network_code be a per-call kwarg (as in the existing MockUpstreamClient) rather than a constructor param? Baking it into construction breaks multi-tenant adopters who serve multiple networks from a single pooled client.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01NHKqCc2S2Jkdi2Lxf2bDE5

---

Generated by Claude Code

[bokelley]

Resolving the three triage questions:

1. Generic syntax: Generic class. TranslationMap[AdcpStatus, UpstreamStatus]({"active": "ACTIVE"}) — mirrors dict[K, V].
2. Auth config: Typed dataclasses (StaticBearerAuth, DynamicBearerAuth, ApiKeyAuth, NoAuth). Matches the ApiKeyCredential / OAuthCredential pattern already in adcp.decisioning.registry.
3. network_code placement: Per-call kwarg. Constructor-level breaks the existing MockUpstreamClient pattern and multi-tenant pooling.

Ready to Execute.

[bokelley]

Triage

Classification: Feature request
Bucket(s): client, handlers
Status: drafting-pr
Milestone: omitted

What the experts said:

• code-reviewer: approved — narrowed except Exception → except ValueError; __cause__ assertion added; all other acceptance criteria already met
• dx-expert: approved — SERVICE_UNAVAILABLE + recovery="transient" is the correct projection for a CDN/proxy interception returning non-JSON on a 2xx

My take: Both create_upstream_http_client and create_translation_map were already fully implemented and exported from adcp.decisioning before this re-triage — the only remaining gap against the acceptance criteria was "Tests cover: … JSON decode errors." PR #767 closes that gap: wraps response.json() in except ValueError and raises a typed AdcpError(SERVICE_UNAVAILABLE) rather than propagating a raw JSONDecodeError.

Drafting PR: #767 — fix(decisioning): project malformed-JSON 2xx responses to AdcpError

---

Triaged by Claude Code. Session: https://claude.ai/code/session_0172h7dGLvfEeo1DLKzAH4TZ

---

Generated by Claude Code

[bokelley]

Closing — the typed dataclass auth variants (StaticBearer / DynamicBearer / ApiKey / NoAuth), the generic TranslationMap[A, U] class, and per-call auth_context (instead of a constructor-level network_code) all shipped in #464 and match the triage resolutions above.

The one remaining dx-expert nit — KeyError listing the known keys when to_upstream / to_adcp miss — is in #768.