Dev Updates

Production smoke and frontend smoke now cover all external v0 API endpoints with optional keyed checks. The Node smoke runner (scripts/smoke/run_smoke.mjs) runs keyed checks for GET /api/v0/health, /api/v0/coverage, and /api/v0/price when TEST_API_KEY or --api-key is set; V0_PRICE uses the first TCG/set from the coverage response. The prod-smoke CI workflow passes TEST_API_KEY from repository secrets so keyed v0 checks run in CI when configured. The frontend smoke suite (npm run test:smoke) includes v0 health and v0 API integration tests (coverage and price) when INTEGRATION_API_BASE and TEST_API_KEY are set; they are skipped otherwise so Jest reports skipped instead of a false pass. Shared helpers (v0IntegrationHelpers) centralize backend root and auth headers for v0 tests. Docs (contract README, docs/ci/smoke.md) describe the full test stack: unkeyed and keyed checks, frontend smoke patterns, and safe addition of new checks.

Documentation and tooling for using a dedicated v0 API key when testing or running smoke checks against production. Contract README now explains TEST_API_KEY: store the raw key from a production-created key (e.g. label test or ci) in .env or CI secrets and use it for manual or scripted calls to production v0. New docs/RAILWAY_V0_API.md describes the single Railway variable required for v0 (PARTNER_API_KEY_HMAC_SECRET), how to create production keys with the same secret, and that no other vars are needed to enable the API. A frontend integration test hits GET /api/v0/health with TEST_API_KEY when INTEGRATION_API_BASE or NEXT_PUBLIC_API_BASE is set; it skips when the key is missing. .env.example documents the optional TEST_API_KEY variable.

The /readyz endpoint no longer runs the DB check in a thread pool, which could cause "unknown" readiness when the session was used from another thread. Readiness now runs in the request thread with a 2s statement_timeout so the check is reliable and does not hang. The /status page hydration error (server rendering "Offline" while the client showed "Checking readiness…") is fixed by deferring use of navigator.onLine until after mount, so server and client render the same initial state.

We shipped TCG-first SEO and copy across the JK Index frontend. Root layout default title and description now name all three TCGs (Pokémon TCG, One Piece TCG, Riftbound TCG) and include intent phrases: sold listings, market price, and graded (PSA) price history. Homepage H1 and hero subline, About section, and footer tagline use the same language. Card, set, and TCG landing pages have updated metadata templates with TCG and price-index wording. The how-prices page and navbar tagline now say TCG explicitly. Dev-updates route has its own layout with title and description. No routing or JSON-LD changes.

We added a full frontend and SEO audit document (docs/audit-jk-index-seo-perf-quality.md) covering TCG-first discoverability, Core Web Vitals, and code quality. The audit recommends explicit TCG language in titles and meta (e.g. Pokémon TCG price index, One Piece TCG card prices, sold listings, graded PSA price history), a technical SEO checklist with file-level fixes, top 10 performance issues with concrete fixes (LCP, CLS, INP, bundle, images, preconnect, fonts), and a ranked backlog with four PR-sized slices. No React Native in this repo; audit is web-only.

The /status page is now easy to find from the API surface: Platform API landing and docs include a Status button and a "Status / Health" link in the docs TOC with copy about live readiness checks and request IDs. The docs auth section has a callout: "Having trouble? Check /status and include X-Request-Id in support DMs." The status page itself was upgraded for RN-style clients: clear state labels (Healthy, Not Ready, Down, Offline), user-friendly messages for each error (e.g. timeout, network_error, 503 reasons), response time and copyable Request ID, a collapsed Details section with raw /readyz JSON, and "What to do next" guidance. The backend uses a shared executor for /readyz to avoid thread leakage; tests cover stability and documented reason codes.

A production-grade API health surface is now available for load balancers, status pages, and high-scale clients (e.g. React Native). Backend exposes GET /healthz (liveness), GET /readyz (readiness with DB and schema checks, bounded timeout), and GET /api/v0/health (keyed, detailed checks: db, fx_table, fx_rate_usd_cad). The web status page at /status loads fast, uses a single bounded request to /readyz with timeout and optional retries, shows last-checked time and request ID for debugging, and does not poll. Production smoke now requires 200 on /healthz, /readyz, and /status. Docs in docs/dev/api_health.md cover recommended RN usage, retry policy, and ETag/304.

Phase 2.4d completes the v0 pricing milestone: builders with API keys can use GET /api/v0/price for real USD and CAD snapshots. All money fields (latest, median) are decimal strings at 2 decimals (ROUND_HALF_UP). CAD responses include fx_rate as a 6-decimal string, fx_as_of (ISO8601), and fx_source. When FX is missing, the response remains matched with snapshot=null and reason_code=fx_unavailable (no silent fallback). Centralized helpers: money.py (quantize_money, money_str, fx_rate_str) and snapshot_currency.py (convert_snapshot_usd_to_cad). Contract and observability tests cover USD/CAD snapshot-present, fx_unavailable, and no_pricing_for_segment.

Phase 2.4c wires real USD pricing snapshots into GET /api/v0/price for supported segments. When sales data exists for the requested card and segment (raw_nm/lp/mp or psa_7–psa_10), the response now includes pricing.snapshot with latest, median, count, and currency=USD, plus pricing.as_of (ISO8601). When no data exists, outcome remains matched with snapshot=null and reason_code=no_pricing_for_segment. CAD requests are unchanged (Phase 2.4d will add conversion). Contract and observability tests cover snapshot-present and null paths.

Phase 2.4b adds the DB query layer that returns sale rows for a single card and segment with no cross-segment contamination. Raw segments (raw_nm, raw_lp, raw_mp) filter on ungraded sales and stored raw_condition; PSA segments (psa_7 through psa_10) filter on graded PSA sales by grade tier. Results are ordered by newest sale_date first with a stable tie-breaker. Unknown canonical_id returns an empty list. No route, auth, or contract changes in this step.

Phase 2.4a adds the pure snapshot computation layer for the Pricing API v0: deterministic latest, median, count, and as_of from an in-memory list of sale rows. All price math uses Decimal for precision; latest is defined by newest sale date (not highest price), and even-N median is the arithmetic mean of the two middle values. This core is isolated from routes and the database so it can be tested and relied on before wiring to real data. No API or contract changes in this step.

Phase 2.3 makes the Pricing API v0 observable before adding real pricing snapshots. Every request to /api/v0/price or /api/v0/coverage now produces one machine-readable log event with request ID, API key ID, path, outcome, and reason code so support and operations can trace and analyze usage. Prometheus metrics were added for request counts by outcome and path, latency histograms, rate-limit hits, and cache hit/miss when clients use conditional requests. No API contract or response bodies changed; this is instrumentation only.