Read-through-API: move client reads onto edge-cached v2 endpoints

[rferrari]

Why

The webapp (skatehive3.0) and mobile app read most display data directly from Hive RPC (feeds, profiles, posts, notifications, HP/vote math). That means multi-second round-trips, public-node flakiness with failover, and N+1 call patterns (a comment thread = many sequential get_content calls). Meanwhile the v2 API now edge-caches all reads (CDN-Cache-Control, commit 3bb3c8d).

This is the tracking issue for closing the remaining read gaps so clients can consume edge-cached v2 endpoints instead of hitting the chain directly. It's driven by an architectural audit of skatehive3.0 (AUDIT_READ_THROUGH_API.md).

Principles / decisions

• Reads decouple from the chain; writes do not. Aioha + dhive stay the exclusive signing/broadcast path. Userbase (email/lite users) and Farcaster are untouched.
• Extend v2, no v3. All additions are non-breaking new endpoints. Each client adapts response shape via its own adapter — versioning is not the tool for shape differences.
• HAFSQL-first, dhive as fallback. Reads prefer our own Postgres (offloads public nodes, edge-cacheable, collapses N RPC calls into one join); dhive is the resilience layer and the source for data HAFSQL doesn't expose.
• Some reads stay on-chain deliberately — they're part of write flows (follow-toggle read, waitForPost cross-post gating, key validation, pre-transfer balance) and need live state.

Endpoints (this repo)

• feat(api): add v2 /post/[author]/[permlink] read endpoint #35 — GET /api/v2/post/[author]/[permlink] (also introduces the vitest runner + cacheHeaders helper) — base of the stack
• feat(api): add v2 /notifications/[username] endpoint #36 — GET /api/v2/notifications/[username]
• feat(api): add v2 /chain/globals endpoint #37 — GET /api/v2/chain/globals (HP + vote-value constants)

Merge order: #35 first, then #36 and #37 (independent siblings).

/account was evaluated and not needed — /profile + /balance already cover existence/metadata/balances; the only extra a raw account gives is keys/authorities, which are write-coupled and stay on-chain.

Follow-up (separate repos)

• Webapp: add a centralized lib/api/skatehiveClient.ts (modeled on mobile lib/api.ts) + React Query, migrate read hooks (profile, comments, post pages, notifications, HP) with a dhive fallback.
• Mobile: switch notification reads to the new endpoint — Migrate notifications to skatehive-api /api/v2/notifications endpoint mobileapp#17.

Testing

Unit tests via vitest (pnpm test, tests/unit/*.test.ts) introduced in #35; each endpoint ships unit + smoke coverage.

🤖 Generated with Claude Code