BFF Stream — Learnings

Proxy/adaptor framing is a contract, not a coding style

The original plan said “return the v1 DTO”. Review tightened that to: “this route is a proxy/adaptor — it preserves Amazon’s null/present signal verbatim, distinguishing ‘Amazon did not provide this field’ from a real empty value.” The implementation consequences:

• Every core DTO field is nullable.
• The mapper never substitutes ?? "" or ?? 0.
• HTTP 206 is the right status for partial upstream responses (a half-populated DTO is correct content, not an error).

Lesson for similar BFF routes: spell out the proxy/adaptor framing in the plan, name the null-pass-through invariant explicitly, and define partial-response status semantics before implementation. It’s cheaper than retro-fitting nullable types and a new HTTP status across the route + tests + mocks.

SDK client lifetime is a perf invariant, not a detail

The amazon-creators-api SDK caches OAuth2 tokens on the ApiClient instance. Constructing a fresh ApiClient per request silently bypasses that cache — every BFF call paid for a new auth/o2/token round trip instead of one per ~9-minute token lifetime. The fix (module-scope lazy init) is one line. The lesson is to look for stateful per-instance caches in any vendor SDK and treat instance lifetime as a perf invariant.

Error envelopes deserve a single shape

The JWT-failure path originally returned { ok: false, error } (no code), while every other error path returned { ok: false, code, message }. Consumers keying off code would have broken silently on auth failures. Lesson: when you have an { ok, code, message } contract, all failure paths emit it, including framework-imposed ones like JWT verification. Add an explicit AUTHENTICATION_REQUIRED code rather than letting the framework’s envelope leak through.

Pin SDK versions exactly when integrating a critical vendor

amazon-creators-api@1.2.2 is pinned without a caret. The SDK has Amazon-internal behaviour (token caching, retry, resource defaults) that a minor bump could change without us noticing until prod. The cost of pinning is occasional manual updates; the cost of not pinning is a class of regression that doesn’t show up until production traffic. For a credential-bearing integration with a single upstream vendor, exact pinning is the right default.