dashboard: consume /billing/usage + /team/summary (§10.20) (#33)

Retires the client-side Usage-panel aggregation (resources → useMemo) in
favour of the new server-side cached aggregates. The dashboard no longer
pulls the full resource list just to compute six numbers; the agent API
caches the rollup per team in Redis (30s for billing/usage, 5min for
team/summary) and shares it across surfaces.

Per the §13 freshness rule, the eventual-consistency tradeoff is now
visible to users — the Usage panel renders an "as of Ns ago · cached
30s" footnote so they can tell whether a freshly-provisioned resource
should already appear in the figures.

api/index.ts — adds fetchBillingUsage() + fetchTeamSummary() typed
wrappers, including BillingUsage / TeamSummary / UsageMetric /
TeamSummaryCounts types.

BillingPage.tsx — replaces the resources useMemo aggregate with the
server payload. The Usage panel still renders the same six rows; values
now come from `billingUsage.usage.<service>.bytes` (or `.count`) and
the seats row finally reads a real member count (closes the §10.7 gap
for the Usage panel). Adds formatAsOf() helper + data-testid
`billing-usage-as-of` for the eventual-consistency footnote.

AppShell.tsx — extends SidebarUpgradeCard to fetch /team/summary once
per session-load (5m Redis cache + browser Cache-Control makes this
cheap) and render a "N resources · M members" line on paid-tier cards.
Skipped for anonymous/free where the card is the upgrade CTA only.

Tests: 164 pass, 3 skipped (matches main). New §10.20 coverage in
BillingPage.test.tsx asserts:
  - listResources() is NOT called for usage data (regression guard)
  - fetchBillingUsage() is called exactly once
  - the `as_of` footnote renders when the cached payload arrives
  - zero-usage server response renders zeroes in every row
  - server bytes → MB conversion (100 MB Postgres → "100 / 1 GB")

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

src/api/index.ts

@@ -668,3 +668,77 @@ export type ClaimResp = {
 export async function claim(body: { jwt: string; email: string }): Promise<ClaimResp> {
   return call('/claim', { method: 'POST', body: JSON.stringify(body) })
 }
+
+// ─── §10.20 cached aggregates (LIVE) ────────────────────────────────────
+//
+// Two server-side cached endpoints replace what the dashboard previously
+// computed client-side:
+//
+//   fetchBillingUsage() → GET /api/v1/billing/usage   (Redis-cached 30s)
+//   fetchTeamSummary()  → GET /api/v1/team/summary    (Redis-cached 5m)
+//
+// Both responses carry `as_of` (ISO timestamp) + `freshness_seconds` so the
+// UI can render an "as of Ns ago" footnote that makes the eventual-
+// consistency tradeoff visible to the user (per §13).
+//
+// These are pure GETs — safe to call on render. The agent API sets
+// Cache-Control: private, max-age=N so the browser also caches the
+// response within the same window (no double-fetch on remount).
+
+/** Per-metric shape inside `usage` — bytes/limit_bytes for storage services,
+ *  count/limit for everything else. -1 means unlimited. */
+export type UsageMetric = {
+  bytes?: number
+  limit_bytes?: number
+  count?: number
+  limit?: number
+}
+
+export type BillingUsage = {
+  ok: true
+  freshness_seconds: number
+  /** ISO-8601 UTC timestamp of when the server computed this snapshot. */
+  as_of: string
+  usage: {
+    postgres: UsageMetric
+    redis: UsageMetric
+    mongodb: UsageMetric
+    deployments: UsageMetric
+    webhooks: UsageMetric
+    vault: UsageMetric
+    members: UsageMetric
+  }
+}
+
+export async function fetchBillingUsage(): Promise<BillingUsage> {
+  return call<BillingUsage>('/api/v1/billing/usage')
+}
+
+export type TeamSummaryCounts = {
+  resources: {
+    total: number
+    postgres: number
+    redis: number
+    mongodb: number
+    webhook: number
+    queue: number
+    storage: number
+    other: number
+  }
+  deployments: number
+  members: number
+  vault_keys: number
+}
+
+export type TeamSummary = {
+  ok: true
+  freshness_seconds: number
+  /** ISO-8601 UTC timestamp of when the server computed this snapshot. */
+  as_of: string
+  tier: string
+  counts: TeamSummaryCounts
+}
+
+export async function fetchTeamSummary(): Promise<TeamSummary> {
+  return call<TeamSummary>('/api/v1/team/summary')
+}

src/layout/AppShell.tsx

@@ -1,7 +1,9 @@
 import { Link, NavLink, Outlet, useLocation } from 'react-router-dom'
 import { Brand, ExpiryWarningBanner, ScopePill, useExpiryTick } from '../components/Common'
-import { useState, type ReactNode } from 'react'
+import { useEffect, useState, type ReactNode } from 'react'
 import { addEnv, setEnv, useDashboardCtx, type DashboardCtx } from '../hooks/useDashboardCtx'
+import * as api from '../api'
+import type { TeamSummary } from '../api'
 
 type Scope = 'read' | 'write' | 'agent'
 
@@ -266,6 +268,26 @@ function SidebarUpgradeCard({ ctx, now }: { ctx: DashboardCtx; now: number }) {
   const billing = ctx.billing
   const loading = ctx.billingLoading
 
+  // §10.20: cached team summary feeds the resource/member counts that
+  // previously didn't render (the dashboard ctx's `counts` field had no
+  // live source for `team` — see useDashboardCtx.refreshCounts which
+  // hardcodes `team: 1`). One fetch per session-load amortises against
+  // every authenticated page render thanks to the server-side 5-min
+  // Redis cache + browser Cache-Control: max-age=300.
+  const [summary, setSummary] = useState<TeamSummary | null>(null)
+  useEffect(() => {
+    // Skip the fetch on anon/free where the card never renders counts
+    // (the upgrade CTA below is the only render path). Also skip when
+    // there's no team_id yet — the request would 401 anyway.
+    if (!ctx.me?.team?.id) return
+    if (tier === 'anonymous' || tier === 'free') return
+    let alive = true
+    api.fetchTeamSummary()
+      .then((s) => { if (alive) setSummary(s) })
+      .catch(() => { /* sidebar count rendering is non-critical */ })
+    return () => { alive = false }
+  }, [ctx.me?.team?.id, tier])
+
   // Loading state — render a quiet skeleton instead of stale fixture text.
   if (loading && !billing) {
     return (
@@ -304,6 +326,14 @@ function SidebarUpgradeCard({ ctx, now }: { ctx: DashboardCtx; now: number }) {
       ? `${billing.payment_network.toLowerCase()} · ****${billing.payment_last4}`
       : null
 
+  // §10.20: live resource + member counts from the cached team summary.
+  // Hidden until the fetch resolves so we never render "0 resources · 0
+  // members" misleadingly during load.
+  const counts = summary?.counts
+  const countsLine = counts
+    ? `${counts.resources.total} resource${counts.resources.total === 1 ? '' : 's'} · ${counts.members} member${counts.members === 1 ? '' : 's'}`
+    : null
+
   return (
     <div className="upgrade-card" data-testid="sidebar-upgrade-card-paid">
       <div className="label">{tier ? `→ ${tier} · live` : ''}</div>
@@ -315,6 +345,18 @@ function SidebarUpgradeCard({ ctx, now }: { ctx: DashboardCtx; now: number }) {
           </>
         ) : null}
         {paymentHint ? <span className="dim">{paymentHint}</span> : null}
+        {countsLine ? (
+          <>
+            <br />
+            <span
+              className="dim"
+              data-testid="sidebar-team-counts"
+              style={{ fontSize: 10.5, opacity: 0.75 }}
+            >
+              {countsLine}
+            </span>
+          </>
+        ) : null}
       </div>
       <Link to="/app/billing" className="cta" data-testid="sidebar-manage-plan">
         Manage plan →

src/pages/BillingPage.test.tsx

@@ -68,6 +68,12 @@ vi.mock('../api', async () => {
     fetchBilling: vi.fn(),
     listInvoices: vi.fn(),
     listResources: vi.fn(),
+    // §10.20: BillingPage's Usage panel now reads fetchBillingUsage() (a
+    // server-side cached aggregate) instead of listResources(). The
+    // listResources mock above stays in the module-level mock for the
+    // pre-§10.20 tests that still reference it; new tests should drive
+    // fetchBillingUsage.
+    fetchBillingUsage: vi.fn(),
     createCheckout: vi.fn(),
     cancelSubscription: vi.fn(),
   }
@@ -104,13 +110,45 @@ function mockHappyBilling() {
     ok: true,
     invoices: FIXTURE_INVOICES,
   })
-  // Default: no resources → Usage panel renders zeroes. Tests that care
-  // about specific usage figures override this themselves.
+  // Pre-§10.20 tests still mock listResources; new code path doesn't
+  // call it, so this resolves to an unused empty list.
   ;(api.listResources as any).mockResolvedValue({
     ok: true,
     items: [],
     total: 0,
   })
+  // §10.20: default zero-usage server response. Tests that pin specific
+  // usage figures override this with a payload carrying real bytes/counts.
+  ;(api.fetchBillingUsage as any).mockResolvedValue(makeUsageResp({}))
+}
+
+/** §10.20 test helper — build a BillingUsage response with optional overrides
+ *  per metric. Unspecified metrics default to {bytes:0, limit_bytes:-1} or
+ *  {count:0, limit:-1} matching the server's "no row" shape. */
+function makeUsageResp(over: Partial<{
+  postgres_bytes: number
+  redis_bytes: number
+  mongodb_bytes: number
+  deployments: number
+  webhooks: number
+  vault: number
+  members: number
+}>) {
+  return {
+    ok: true,
+    freshness_seconds: 30,
+    // Pin as_of so the "as of Ns ago" footnote renders deterministically.
+    as_of: new Date(Date.now() - 5000).toISOString(),
+    usage: {
+      postgres: { bytes: over.postgres_bytes ?? 0, limit_bytes: 1024 * 1024 * 1024 },
+      redis: { bytes: over.redis_bytes ?? 0, limit_bytes: 50 * 1024 * 1024 },
+      mongodb: { bytes: over.mongodb_bytes ?? 0, limit_bytes: 100 * 1024 * 1024 },
+      deployments: { count: over.deployments ?? 0, limit: 1 },
+      webhooks: { count: over.webhooks ?? 0, limit: 1000 },
+      vault: { count: over.vault ?? 0, limit: 20 },
+      members: { count: over.members ?? 1, limit: 1 },
+    },
+  }
 }
 
 /** Wait for the page to finish its initial load (skeleton → real content). */
@@ -180,7 +218,7 @@ describe('BillingPage — backend-down error state (§10.21)', () => {
   it('renders the billing-error banner when fetchBilling rejects (no fixture fallback)', async () => {
     ;(api.fetchBilling as any).mockRejectedValue(Object.assign(new Error('Razorpay is not configured'), { status: 503 }))
     ;(api.listInvoices as any).mockResolvedValue({ ok: true, invoices: [] })
-    ;(api.listResources as any).mockResolvedValue({ ok: true, items: [], total: 0 })
+    ;(api.fetchBillingUsage as any).mockResolvedValue(makeUsageResp({}))
     render(<BillingPage />)
     await waitFor(() => {
       expect(screen.getByTestId('billing-error')).toBeTruthy()
@@ -193,7 +231,7 @@ describe('BillingPage — backend-down error state (§10.21)', () => {
   it('surfaces the error message on the billing-error banner', async () => {
     ;(api.fetchBilling as any).mockRejectedValue(new Error('Razorpay is not configured'))
     ;(api.listInvoices as any).mockResolvedValue({ ok: true, invoices: [] })
-    ;(api.listResources as any).mockResolvedValue({ ok: true, items: [], total: 0 })
+    ;(api.fetchBillingUsage as any).mockResolvedValue(makeUsageResp({}))
     const { container } = render(<BillingPage />)
     await waitFor(() => {
       expect(screen.getByTestId('billing-error')).toBeTruthy()
@@ -208,6 +246,9 @@ describe('BillingPage — initial render', () => {
     ;(api.fetchBilling as any).mockReturnValue(new Promise(() => {}))   // never resolves
     ;(api.listInvoices as any).mockReturnValue(new Promise(() => {}))
     ;(api.listResources as any).mockReturnValue(new Promise(() => {}))
+    // §10.20: BillingPage calls fetchBillingUsage now; it must return a
+    // pending promise (never resolves) so the skeleton state holds.
+    ;(api.fetchBillingUsage as any).mockReturnValue(new Promise(() => {}))
     const { container } = render(<BillingPage />)
     expect(container.querySelector('.skel')).toBeTruthy()
   })
@@ -453,61 +494,38 @@ describe('BillingPage — userEvent integration', () => {
   })
 })
 
-// ─── Usage panel — real data from listResources() (§10.1) ───────────────
-// The old Usage panel hardcoded "47 / 500", "163 / 256", "1.64 / 2 GB", etc.
-// We now aggregate ctx.resources by type. These tests pin the contract:
-//   (a) values move when listResources moves,
-//   (b) the old fixture numbers no longer appear in the DOM.
-describe('BillingPage — Usage panel reflects listResources()', () => {
-  // Minimal Resource fixture factory — keeps the test contained.
-  function makePgResource(id: string, mb: number) {
-    return {
-      id,
-      token: id,
-      resource_type: 'postgres',
-      tier: 'hobby',
-      status: 'active',
-      name: id,
-      env: 'production',
-      storage_bytes: mb * 1024 * 1024,
-      storage_limit_bytes: 1024 * 1024 * 1024,
-      storage_exceeded: false,
-      expires_at: null,
-      created_at: new Date().toISOString(),
-    }
-  }
-
-  it('aggregates two postgres resources totalling 100 MB into one UsageRow', async () => {
+// ─── Usage panel — server-side cached aggregate (§10.20) ────────────────
+// The Usage panel reads /api/v1/billing/usage (cached 30s in Redis with
+// singleflight on the server). These tests pin the contract:
+//   (a) values reflect the server response, not a client-side aggregate,
+//   (b) BillingPage does NOT call listResources() for usage data,
+//   (c) the `as_of` footnote renders so the eventual-consistency tradeoff
+//       is visible to users.
+describe('BillingPage — Usage panel reflects fetchBillingUsage() (§10.20)', () => {
+  it('renders postgres bytes (100 MB / 1 GB) from the server response', async () => {
     mockTier = 'hobby'
     mockHappyBilling()
-    ;(api.listResources as any).mockResolvedValue({
-      ok: true,
-      items: [makePgResource('p_a', 40), makePgResource('p_b', 60)],
-      total: 2,
-    })
+    ;(api.fetchBillingUsage as any).mockResolvedValue(makeUsageResp({
+      postgres_bytes: 100 * 1024 * 1024,
+    }))
     const { container } = render(<BillingPage />)
     await waitForLoaded()
-    // hobby postgres limit is 1024 MB → renders as "1 GB".
     await waitFor(() => {
       const text = container.textContent ?? ''
       expect(text).toContain('100')
       expect(text).toContain('1 GB')
     })
   })
 
-  it('renders 0 for the resource-driven UsageRows when the resource list is empty', async () => {
+  it('renders zeroes when the server reports no usage', async () => {
     mockTier = 'hobby'
     mockHappyBilling()
-    ;(api.listResources as any).mockResolvedValue({ ok: true, items: [], total: 0 })
     const { container } = render(<BillingPage />)
     await waitForLoaded()
     await waitFor(() => {
       const rows = container.querySelectorAll('.usage-row')
       // 6 usage rows: postgres, redis, mongo, deployments, webhooks, team seats.
       expect(rows.length).toBe(6)
-      // Resource-aggregated rows (postgres / redis / mongo / deployments /
-      // webhooks) must read "0 / …" when the list is empty. Team seats is a
-      // separate constant for now (no member-list endpoint) and is exempt.
       const resourceRowKeys = ['postgres', 'redis', 'mongo', 'deployments', 'webhooks']
       resourceRowKeys.forEach((key) => {
         const row = Array.from(rows).find((r) => r.querySelector('.k')?.textContent === key)
@@ -525,6 +543,35 @@ describe('BillingPage — Usage panel reflects listResources()', () => {
     await waitForLoaded()
     expect(container.textContent).not.toMatch(/\b47\b/)
   })
+
+  // §10.20 / §14: critical contract — the page must NOT round-trip to
+  // /resources for usage data anymore. Catches accidental reintroductions
+  // of the client-side aggregate.
+  it('does not call listResources() for usage data', async () => {
+    mockTier = 'hobby'
+    mockHappyBilling()
+    render(<BillingPage />)
+    await waitForLoaded()
+    // Wait a tick to make sure any in-flight effect has a chance to fire.
+    await new Promise((r) => setTimeout(r, 50))
+    expect((api.listResources as any).mock?.calls?.length ?? 0).toBe(0)
+    // The new cached aggregate, on the other hand, must be called exactly once.
+    expect((api.fetchBillingUsage as any).mock?.calls?.length ?? 0).toBe(1)
+  })
+
+  // §10.20 / §13: the eventual-consistency footnote must render so users
+  // can see when the snapshot was computed.
+  it('renders the "as of Ns ago" footnote when the cached payload arrives', async () => {
+    mockTier = 'hobby'
+    mockHappyBilling()
+    const { getByTestId } = render(<BillingPage />)
+    await waitForLoaded()
+    await waitFor(() => {
+      const footnote = getByTestId('billing-usage-as-of')
+      expect(footnote.textContent).toMatch(/as of/)
+      expect(footnote.textContent).toMatch(/cached 30s/)
+    })
+  })
 })
 
 // ─── §10.8 cleanups: card expiry leak, invoice status, update mailto ────