@voltro/cli 0.28.0 → 0.29.0

package/templates/apps/frontend-portal/src/globals.css

@@ -0,0 +1,93 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --accent: #4f46e5;
+  --danger: #dc2626;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --accent: #818cf8;
+  --danger: #f87171;
+  --border: #1f2937;
+  --panel: #111827;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.55;
+}
+a { color: inherit; }
+.muted { color: var(--muted); }
+.spacer { flex: 1; }
+
+/* Buttons + inputs */
+.btn {
+  display: inline-block; cursor: pointer; border: 0; border-radius: 8px;
+  background: var(--accent); color: #fff; padding: 0.55rem 1rem;
+  font: inherit; font-weight: 600; text-decoration: none;
+}
+.btn:disabled { opacity: 0.6; cursor: default; }
+.btn.ghost { background: transparent; color: var(--accent); border: 1px solid var(--border); }
+.link { background: none; border: 0; color: var(--accent); cursor: pointer; font: inherit; padding: 0; }
+input {
+  font: inherit; padding: 0.5rem 0.65rem; border: 1px solid var(--border);
+  border-radius: 8px; background: var(--bg); color: var(--fg); min-width: 0;
+}
+.error-text { color: var(--danger); }
+
+/* Marketing */
+.marketing header {
+  display: flex; align-items: center; gap: 1rem;
+  padding: 1rem 1.5rem; border-bottom: 1px solid var(--border);
+}
+.marketing .brand { font-weight: 700; text-decoration: none; }
+.hero { max-width: 40rem; margin: 0 auto; padding: 3rem 1.5rem; }
+.hero h1 { margin: 0 0 0.75rem; }
+.auth-form { display: flex; flex-direction: column; gap: 0.85rem; max-width: 22rem; margin-top: 1.25rem; }
+.auth-form label { display: flex; flex-direction: column; gap: 0.25rem; font-size: 0.9rem; }
+
+/* Dashboard shell */
+.dash { display: grid; grid-template-columns: 15rem 1fr; min-height: 100vh; }
+.dash aside { border-right: 1px solid var(--border); padding: 1.25rem; background: var(--panel); }
+.dash aside .brand { font-weight: 700; margin-bottom: 1rem; }
+.dash nav { display: flex; flex-direction: column; gap: 0.5rem; }
+.dash nav a { text-decoration: none; color: var(--muted); padding: 0.35rem 0; }
+.dash nav a[aria-current="page"] { color: var(--fg); font-weight: 600; }
+.dash main { padding: 1.5rem 2rem; }
+.topbar { display: flex; align-items: center; margin-bottom: 1rem; }
+@media (max-width: 40rem) { .dash { grid-template-columns: 1fr; } .dash aside { border-right: 0; border-bottom: 1px solid var(--border); } }
+
+/* Bits */
+.row { display: flex; gap: 0.6rem; align-items: center; flex-wrap: wrap; margin-top: 0.5rem; }
+.empty { color: var(--muted); margin-top: 1.5rem; }
+.cards { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); gap: 0.75rem; }
+.card { border: 1px solid var(--border); border-radius: 10px; padding: 0.9rem 1rem; background: var(--panel); }
+.card .value { font-weight: 600; }
+.card .label { color: var(--muted); font-size: 0.85rem; margin-top: 0.2rem; }
+.paywall { border: 1px solid var(--accent); border-radius: 12px; padding: 1rem 1.25rem; margin-top: 1.25rem; background: color-mix(in oklab, var(--accent) 8%, transparent); }
+.paywall p { margin: 0.35rem 0 0.75rem; }
+.facts { display: grid; grid-template-columns: max-content 1fr; gap: 0.4rem 1.5rem; margin-top: 1rem; }
+.facts dt { color: var(--muted); }
+.facts dd { margin: 0; font-weight: 600; }
+.rows { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0.4rem; }
+.rows li { display: flex; justify-content: space-between; align-items: center; border: 1px solid var(--border); border-radius: 8px; padding: 0.6rem 0.9rem; background: var(--panel); }
+.tag { font-size: 0.8rem; color: var(--muted); border: 1px solid var(--border); border-radius: 999px; padding: 0.05rem 0.55rem; }
+code { background: color-mix(in oklab, var(--fg) 8%, transparent); padding: 0.1em 0.35em; border-radius: 4px; }
+
+/* Portal extras */
+.rows .grow { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.rows li { gap: 0.6rem; }
+.notice { border: 1px solid var(--accent); border-radius: 10px; padding: 0.85rem 1rem; background: color-mix(in oklab, var(--accent) 8%, transparent); }
+.ok { color: var(--accent); }
+.token { display: block; margin-top: 0.5rem; padding: 0.6rem 0.75rem; background: var(--bg); border: 1px solid var(--border); border-radius: 8px; word-break: break-all; font-size: 0.85rem; }
+.cards .card a { font-weight: 600; text-decoration: none; color: var(--accent); }

package/templates/apps/frontend-portal/src/globals.d.ts

@@ -0,0 +1,6 @@
+// Ambient declarations.
+//
+// `declare module '*.css'`: TypeScript with `moduleResolution: Bundler` rejects
+// a bare `import './globals.css'` unless the asset module is declared. Vite
+// resolves it at build time; the declaration is type-only.
+declare module '*.css'

package/templates/apps/frontend-portal/src/lib/api.ts

@@ -0,0 +1,62 @@
+// The shapes this portal reads off the api-saas-starter backend, kept LOCAL so
+// the pages are self-contained. They mirror the api's descriptor outputs
+// (`session.me`, `billing.subscription`, `billing.invoices`) and the framework's
+// `/v1/api-keys` REST surface.
+
+// The caller's resolved identity, from `session.me`. The SSR gate reads it.
+export interface Identity {
+  readonly type: string
+  readonly id: string | null
+  readonly tenantId: string | null
+}
+
+// `billing.subscription` streams `{ subscription: … | null }` — null before the
+// tenant has any subscription row (they're on the implicit free plan).
+export interface SubscriptionState {
+  readonly subscription: {
+    readonly plan: string
+    readonly status: string
+    readonly quantity: number
+    readonly currentPeriodEnd: string | null
+    readonly cancelAt: string | null
+  } | null
+}
+
+// One row of `billing.invoices`. `hostedUrl` / `pdfUrl` are the PROVIDER's own
+// pages — the portal links out, it never renders an invoice.
+export interface Invoice {
+  readonly providerInvoiceId: string
+  readonly amountMinor: number
+  readonly currency: string
+  readonly status: string
+  readonly createdAt: string | null
+  readonly hostedUrl: string | null
+  readonly pdfUrl: string | null
+}
+
+// `billing.previewChange` — the provider's prorated settlement for a change.
+export interface ChangePreview {
+  readonly plan: string
+  readonly quantity: number
+  readonly prorationMinor: number
+  readonly currency: string
+}
+
+// One key from `GET /v1/api-keys` (the framework's built-in management surface).
+export interface ApiKey {
+  readonly id: string
+  readonly name: string
+  readonly keyPrefix: string
+  readonly createdAt: number
+  readonly lastUsedAt: number | null
+  readonly revokedAt: number | null
+}
+
+// Minor units (cents) → a display string. Intl handles the currency + locale.
+export const formatMoney = (minor: number, currency: string, locale: string): string => {
+  try {
+    return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(minor / 100)
+  } catch {
+    return `${(minor / 100).toFixed(2)} ${currency.toUpperCase()}`
+  }
+}

package/templates/apps/frontend-portal/src/locales/de.ts

@@ -0,0 +1,86 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build if a key is missing. Translate the prose only; keep ICU
+// placeholders (`{amount}`) identical to en.ts.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.login.title':    'Anmelden',
+  'meta.overview.title': 'Konto',
+  'meta.billing.title':  'Abrechnung',
+  'meta.invoices.title': 'Rechnungen',
+  'meta.apiKeys.title':  'API-Schlüssel',
+  'meta.profile.title':  'Profil',
+
+  'lang.label': 'Sprache',
+
+  'auth.signIn.heading':  'Anmelden',
+  'auth.signUp.heading':  'Konto erstellen',
+  'auth.email':           'E-Mail',
+  'auth.password':        'Passwort',
+  'auth.signIn.submit':   'Anmelden',
+  'auth.signUp.submit':   'Konto erstellen',
+  'auth.toggle.toSignUp': 'Kein Konto? Erstelle eins',
+  'auth.toggle.toSignIn': 'Konto vorhanden? Anmelden',
+  'auth.pending':         'Bitte warten…',
+  'auth.error':           'Das hat nicht geklappt. Prüfe deine Angaben und versuche es erneut.',
+
+  'nav.overview': 'Übersicht',
+  'nav.billing':  'Abrechnung',
+  'nav.invoices': 'Rechnungen',
+  'nav.apiKeys':  'API-Schlüssel',
+  'nav.profile':  'Profil',
+
+  'overview.heading':        'Kontoübersicht',
+  'overview.renews':         'Verlängert am',
+  'overview.link.billing':   'Plan & Zahlungsmethode',
+  'overview.link.invoices':  'Rechnungsverlauf',
+  'overview.link.apiKeys':   'API-Schlüssel verwalten',
+
+  'billing.heading':        'Abrechnung',
+  'billing.plan.label':     'Aktueller Plan',
+  'billing.plan.free':      'Kostenlos',
+  'billing.status.label':   'Status',
+  'billing.seats.label':    'Sitze',
+  'billing.card.manage':    'Zahlungsmethode verwalten →',
+  'billing.change.title':   'Plan ändern',
+  'billing.change.body':    'Upgrade auf Pro. Wir nennen den genauen anteiligen Betrag vor der Abbuchung.',
+  'billing.change.preview': 'Upgrade ansehen',
+  'billing.change.quote':   'Diese Änderung kostet heute etwa {amount}.',
+  'billing.change.confirm': 'Upgrade bestätigen',
+  'billing.change.done':    'Dein Plan wurde aktualisiert.',
+  'billing.pending':        'Wird ausgeführt…',
+
+  'invoices.heading': 'Rechnungen',
+  'invoices.empty':   'Noch keine Rechnungen.',
+  'invoices.view':    'Ansehen',
+  'invoices.pdf':     'PDF',
+
+  'apiKeys.heading':      'API-Schlüssel',
+  'apiKeys.loading':      'Wird geladen…',
+  'apiKeys.notEnabled':   'API-Schlüssel sind für diese API nicht aktiviert. Setze `apiKeys: true` in der app.config.ts der API, um die eingebaute Schlüsselverwaltung zu aktivieren.',
+  'apiKeys.noAccess':     'Dein Konto darf keine API-Schlüssel verwalten. Dafür ist ein Admin-Scope nötig.',
+  'apiKeys.error':        'API-Schlüssel konnten nicht geladen werden. Bitte erneut versuchen.',
+  'apiKeys.name.placeholder': 'Schlüsselname (z. B. CI-Deploy)',
+  'apiKeys.issue':        'Schlüssel erstellen',
+  'apiKeys.minted.title': 'Kopiere deinen Schlüssel jetzt',
+  'apiKeys.minted.body':  'Der vollständige Schlüssel wird nur dieses eine Mal angezeigt. Bewahre ihn sicher auf.',
+  'apiKeys.empty':        'Noch keine Schlüssel — erstelle oben deinen ersten.',
+  'apiKeys.revoke':       'Widerrufen',
+  'apiKeys.revoked':      'widerrufen',
+
+  'profile.heading':      'Profil',
+  'profile.id':           'Benutzer-ID',
+  'profile.tenant':       'Organisation',
+  'profile.cp.heading':   'Passwort ändern',
+  'profile.cp.email':     'E-Mail deines Kontos',
+  'profile.cp.submit':    'Reset-Link senden',
+  'profile.cp.sent':      'Falls zu dieser E-Mail ein Konto existiert, ist ein Reset-Link unterwegs.',
+  'profile.signOut':      'Abmelden',
+
+  'error.heading':    'Etwas ist schiefgelaufen',
+  'error.retry':      'Erneut versuchen',
+  'notFound.heading': 'Nicht gefunden',
+  'notFound.body':    'Diese Seite existiert nicht.',
+  'notFound.back':    '← Zurück zur Übersicht',
+})

package/templates/apps/frontend-portal/src/locales/en.ts

@@ -0,0 +1,93 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts`; `defineLocale<typeof en>()` enforces that parity.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Browser tab titles.
+  'meta.login.title':    'Sign in',
+  'meta.overview.title': 'Account',
+  'meta.billing.title':  'Billing',
+  'meta.invoices.title': 'Invoices',
+  'meta.apiKeys.title':  'API keys',
+  'meta.profile.title':  'Profile',
+
+  'lang.label': 'Language',
+
+  // ---- Auth form (/login) ----
+  'auth.signIn.heading':  'Sign in',
+  'auth.signUp.heading':  'Create your account',
+  'auth.email':           'Email',
+  'auth.password':        'Password',
+  'auth.signIn.submit':   'Sign in',
+  'auth.signUp.submit':   'Create account',
+  'auth.toggle.toSignUp': 'No account? Create one',
+  'auth.toggle.toSignIn': 'Have an account? Sign in',
+  'auth.pending':         'Please wait…',
+  'auth.error':           'That didn’t work. Check your details and try again.',
+
+  // ---- Sidebar nav ----
+  'nav.overview': 'Overview',
+  'nav.billing':  'Billing',
+  'nav.invoices': 'Invoices',
+  'nav.apiKeys':  'API keys',
+  'nav.profile':  'Profile',
+
+  // ---- Overview ----
+  'overview.heading':        'Account overview',
+  'overview.renews':         'Renews',
+  'overview.link.billing':   'Plan & payment method',
+  'overview.link.invoices':  'Invoice history',
+  'overview.link.apiKeys':   'Manage API keys',
+
+  // ---- Billing ----
+  'billing.heading':        'Billing',
+  'billing.plan.label':     'Current plan',
+  'billing.plan.free':      'Free',
+  'billing.status.label':   'Status',
+  'billing.seats.label':    'Seats',
+  'billing.card.manage':    'Manage payment method →',
+  'billing.change.title':   'Change plan',
+  'billing.change.body':    'Upgrade to Pro. We’ll quote the exact prorated amount before charging.',
+  'billing.change.preview': 'Preview upgrade',
+  'billing.change.quote':   'This change settles at about {amount} today.',
+  'billing.change.confirm': 'Confirm upgrade',
+  'billing.change.done':    'Your plan has been updated.',
+  'billing.pending':        'Working…',
+
+  // ---- Invoices ----
+  'invoices.heading': 'Invoices',
+  'invoices.empty':   'No invoices yet.',
+  'invoices.view':    'View',
+  'invoices.pdf':     'PDF',
+
+  // ---- API keys ----
+  'apiKeys.heading':      'API keys',
+  'apiKeys.loading':      'Loading…',
+  'apiKeys.notEnabled':   'API keys aren’t enabled on this API. Set `apiKeys: true` in the API’s app.config.ts to turn on the built-in key management surface.',
+  'apiKeys.noAccess':     'Your account doesn’t have permission to manage API keys. An admin scope is required.',
+  'apiKeys.error':        'Couldn’t load API keys. Please try again.',
+  'apiKeys.name.placeholder': 'Key name (e.g. CI deploy)',
+  'apiKeys.issue':        'Create key',
+  'apiKeys.minted.title': 'Copy your key now',
+  'apiKeys.minted.body':  'This is the only time the full key is shown. Store it somewhere safe.',
+  'apiKeys.empty':        'No keys yet — create your first above.',
+  'apiKeys.revoke':       'Revoke',
+  'apiKeys.revoked':      'revoked',
+
+  // ---- Profile ----
+  'profile.heading':      'Profile',
+  'profile.id':           'User ID',
+  'profile.tenant':       'Organization',
+  'profile.cp.heading':   'Change password',
+  'profile.cp.email':     'Your account email',
+  'profile.cp.submit':    'Email me a reset link',
+  'profile.cp.sent':      'If that email has an account, a reset link is on its way.',
+  'profile.signOut':      'Sign out',
+
+  // ---- Scoped fallbacks ----
+  'error.heading':    'Something went wrong',
+  'error.retry':      'Try again',
+  'notFound.heading': 'Not found',
+  'notFound.body':    'That page doesn’t exist.',
+  'notFound.back':    '← Back to overview',
+} as const)

package/templates/apps/frontend-portal/src/locales/index.ts

@@ -0,0 +1,14 @@
+// Catalog lookup OUTSIDE React — for a page's `meta({ locale })` locale-aware
+// <title>. This app is cookie-i18n (no `/<locale>` URL prefix), so @voltro/web
+// hands `meta` the active locale from the `voltro:lang` cookie. Inside React use
+// `<T>` / `useT()` via the framework's auto-wired <I18nProvider> instead.
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — which is what `PageMeta.title` requires
+// under exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages

package/templates/apps/frontend-portal/src/pages/(portal)/api-keys/page.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+//
+// The API-keys page. We stub `fetch` to the framework's `/v1/api-keys` surface
+// and assert the two paths that matter for a template shipped against an api
+// that does NOT enable keys by default: a 404 shows the "enable apiKeys" notice
+// (degrade, don't break), and a 200 renders the key list + issue form.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../../locales/en'
+
+const { default: ApiKeys } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+const stubFetch = (status: number, body: unknown): void => {
+  ;(globalThis as { fetch: unknown }).fetch = vi.fn(async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  })) as unknown as typeof fetch
+}
+
+const flush = async (): Promise<void> => {
+  await act(async () => { await Promise.resolve(); await Promise.resolve() })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+beforeEach(() => { vi.restoreAllMocks() })
+
+describe('api-keys — graceful states', () => {
+  test('a 404 (apiKeys not enabled) shows the enable notice, not a broken table', async () => {
+    stubFetch(404, { error: 'not_found' })
+    render(createElement(ApiKeys))
+    await flush()
+    expect(container.querySelector('.notice')).not.toBeNull()
+    expect(container.textContent).toContain('aren’t enabled')
+    // No issue form when the surface is unavailable.
+    expect(container.querySelector('form')).toBeNull()
+  })
+
+  test('a 200 renders the key list and the issue form', async () => {
+    stubFetch(200, { keys: [{ id: 'k1', name: 'CI', keyPrefix: 'voltro_ab', createdAt: 0, lastUsedAt: null, revokedAt: null }] })
+    render(createElement(ApiKeys))
+    await flush()
+    expect(container.querySelector('form')).not.toBeNull()
+    expect(container.textContent).toContain('CI')
+    expect(container.textContent).toContain('voltro_ab')
+  })
+})

package/templates/apps/frontend-portal/src/pages/(portal)/api-keys/page.tsx

@@ -0,0 +1,124 @@
+// API keys — URL `/api-keys`. Drives the framework's BUILT-IN key management
+// surface (`GET/POST /v1/api-keys*`), which the api exposes when it sets
+// `apiKeys: true`. Keys are hash-stored; the raw token is shown exactly ONCE at
+// mint time and is unrecoverable after.
+//
+// This surface is admin-scoped and off by default, so the page DEGRADES: a 404
+// means the api hasn't enabled `apiKeys`, a 401/403 means the signed-in user
+// lacks the scope. It tells the operator exactly what to turn on rather than
+// showing a broken table. (api-saas-starter does not enable it out of the box —
+// see the README.)
+import type { ReactNode } from 'react'
+import { useEffect, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../../locales/index'
+import type { ApiKey } from '../../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.apiKeys.title'],
+})
+
+type State = 'loading' | 'ready' | 'notEnabled' | 'noAccess' | 'error'
+
+const BASE = '/v1/api-keys'
+
+export default function ApiKeys(): ReactNode {
+  const [state, setState] = useState<State>('loading')
+  const [keys, setKeys] = useState<ReadonlyArray<ApiKey>>([])
+  const [name, setName] = useState('')
+  const [minted, setMinted] = useState<string | null>(null)
+  const [pending, setPending] = useState(false)
+  const nameLabel = useT('apiKeys.name.placeholder')
+
+  const load = (): void => {
+    void fetch(BASE, { headers: { accept: 'application/json' } })
+      .then(async (res) => {
+        if (res.ok) {
+          const body = (await res.json()) as { keys: ReadonlyArray<ApiKey> }
+          setKeys(body.keys ?? [])
+          setState('ready')
+        } else if (res.status === 404) setState('notEnabled')
+        else if (res.status === 401 || res.status === 403) setState('noAccess')
+        else setState('error')
+      })
+      .catch(() => setState('error'))
+  }
+
+  useEffect(load, [])
+
+  const onIssue = (e: FormEvent): void => {
+    e.preventDefault()
+    const trimmed = name.trim()
+    if (trimmed === '') return
+    setPending(true)
+    setMinted(null)
+    void fetch(`${BASE}/issue`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: trimmed }),
+    })
+      .then(async (res) => {
+        if (res.ok) {
+          const body = (await res.json()) as { token: string }
+          setMinted(body.token)
+          setName('')
+          load()
+        }
+      })
+      .finally(() => setPending(false))
+  }
+
+  const onRevoke = (id: string): void => {
+    void fetch(`${BASE}/revoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id }),
+    }).then(() => load())
+  }
+
+  return (
+    <section>
+      <h1><T id="apiKeys.heading" /></h1>
+
+      {state === 'loading' ? <p className="empty"><T id="apiKeys.loading" /></p> : null}
+      {state === 'notEnabled' ? <p className="notice" role="status"><T id="apiKeys.notEnabled" /></p> : null}
+      {state === 'noAccess' ? <p className="notice" role="status"><T id="apiKeys.noAccess" /></p> : null}
+      {state === 'error' ? <p className="error-text" role="alert"><T id="apiKeys.error" /></p> : null}
+
+      {state === 'ready' ? (
+        <>
+          <form className="row" onSubmit={onIssue} style={{ marginTop: '0.5rem' }}>
+            <input aria-label={nameLabel} placeholder={nameLabel} value={name} onChange={(e) => setName(e.target.value)} />
+            <button type="submit" className="btn" disabled={pending}><T id="apiKeys.issue" /></button>
+          </form>
+
+          {minted ? (
+            <div className="paywall" role="alert" style={{ marginTop: '1rem' }}>
+              <strong><T id="apiKeys.minted.title" /></strong>
+              <p className="muted"><T id="apiKeys.minted.body" /></p>
+              <code className="token">{minted}</code>
+            </div>
+          ) : null}
+
+          {keys.length === 0 ? (
+            <p className="empty"><T id="apiKeys.empty" /></p>
+          ) : (
+            <ul className="rows" style={{ marginTop: '1.25rem' }}>
+              {keys.map((k) => (
+                <li key={k.id}>
+                  <span className="grow">{k.name} <code>{k.keyPrefix}…</code></span>
+                  {k.revokedAt
+                    ? <span className="tag"><T id="apiKeys.revoked" /></span>
+                    : <button type="button" className="link" onClick={() => onRevoke(k.id)}><T id="apiKeys.revoke" /></button>}
+                </li>
+              ))}
+            </ul>
+          )}
+        </>
+      ) : null}
+    </section>
+  )
+}

package/templates/apps/frontend-portal/src/pages/(portal)/billing/page.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+//
+// The billing page. We mock `@voltro/client` (the live subscription + the three
+// billing actions) and assert: the current plan renders, and the plan-change
+// flow quotes the provider's proration BEFORE it can be confirmed (preview →
+// confirm), not a locally-estimated figure.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../../locales/en'
+
+const subData = vi.fn<() => { data: unknown }>()
+const previewRun = vi.fn<(input: unknown) => Promise<unknown>>()
+
+vi.mock('@voltro/client', () => ({
+  useSubscription: () => subData(),
+  useAction: (_api: string, tag: string) => ({
+    run: tag === 'billing.previewChange' ? previewRun : vi.fn().mockResolvedValue({ url: 'https://provider/portal' }),
+    pending: false,
+  }),
+}))
+
+const { default: Billing, meta, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+beforeEach(() => {
+  subData.mockReset()
+  subData.mockReturnValue({ data: { subscription: { plan: 'free', status: 'active', quantity: 1, currentPeriodEnd: null, cancelAt: null } } })
+  previewRun.mockReset()
+  previewRun.mockResolvedValue({ plan: 'pro', quantity: 1, prorationMinor: 900, currency: 'usd' })
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('billing — config', () => {
+  test('is an SSR page titled Billing (so the parent gate runs per request)', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Billing')
+  })
+})
+
+describe('billing — render + change flow', () => {
+  test('shows the current plan', () => {
+    render(createElement(Billing))
+    expect(container.textContent).toContain('free')
+    expect(container.textContent).toContain('Current plan')
+  })
+
+  test('previewing the upgrade quotes the provider proration before confirm appears', async () => {
+    render(createElement(Billing))
+    // Before preview: the button is "Preview upgrade", not "Confirm".
+    expect(container.textContent).toContain('Preview upgrade')
+    expect(container.textContent).not.toContain('Confirm upgrade')
+
+    const previewBtn = Array.from(container.querySelectorAll('button')).find((b) => b.textContent === 'Preview upgrade')!
+    await act(async () => {
+      previewBtn.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+      await Promise.resolve(); await Promise.resolve()
+    })
+    expect(previewRun).toHaveBeenCalledWith({ plan: 'pro' })
+    // The quote is shown and now the confirm button is available.
+    expect(container.textContent).toContain('settles at about')
+    expect(container.textContent).toContain('Confirm upgrade')
+  })
+})