@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/frontend-portal/README.md

@@ -0,0 +1,71 @@
+# {{capProjectName}} {{capAppName}} — billing & account portal
+
+The lean "manage your account" surface customers visit outside the product:
+plan, payment method, invoices, API keys, profile. Consumes the
+**api-saas-starter** backend; billing is plugin-orchestrated, so the template
+never renders an invoice or holds a card. Bilingual (en/de).
+
+```bash
+voltro init my-saas --api=api-saas-starter --web=frontend-portal
+```
+
+## Pages
+
+| URL | Reads / drives | Notes |
+|---|---|---|
+| `/` | `billing.subscription` | overview: plan, status, renewal + quick links |
+| `/billing` | `billing.subscription`, `billing.portalUrl`, `billing.previewChange`, `billing.changePlan` | plan card; card management redirects to the provider portal; a plan change QUOTES the provider's proration before applying |
+| `/invoices` | `billing.invoices` | list; "View" / "PDF" link out to the provider's hosted pages |
+| `/api-keys` | `GET/POST /v1/api-keys*` | the framework's built-in key management (see below) |
+| `/profile` | `session.me`, `/auth/password-reset`, `/auth/sign-out` | identity, self-serve password reset, sign out |
+| `/login` | `POST /auth/*` | sign-in / sign-up |
+
+`(portal)/layout.tsx` is the SSR auth gate — it asks `session.me` server-side and
+RedirectErrors an anonymous visitor to `/login`.
+
+## API keys — one config step on the API
+
+The API-keys page drives the framework's **built-in** management surface
+(`/v1/api-keys`), which the API exposes only when it sets `apiKeys: true` in its
+`app.config.ts`. **api-saas-starter does not enable it by default**, so out of the
+box this page shows a clear "enable it" notice rather than a broken table. To make
+it live:
+
+1. On the API: `export default { …, apiKeys: true }`.
+2. Grant the signed-in user an issuing scope (`apikey:issue:self`) or `admin` —
+   the management routes are admin-scoped by design (keys are org credentials).
+
+The raw key is shown exactly **once** at mint time (hash-stored, unrecoverable).
+The page degrades on `404` (not enabled), `401/403` (no scope), and errors.
+
+## What's intentionally NOT here
+
+Per the lean brief: **no** support-ticket system and **no** team/member
+management — those belong in the product's own dashboard or a dedicated tool.
+Seat changes stay with the dashboard (`billing.changeSeats`); this portal is plan,
+payment, invoices, keys, profile.
+
+## Files
+
+```
+app.config.ts                       web app; apis.app → @{{projectName}}/api (api-saas-starter)
+src/lib/api.ts                      wire shapes (subscription/invoice/apiKey) + formatMoney
+src/pages/
+  login/page.tsx(.test)             sign-in / sign-up (POST /auth/*)
+  (portal)/layout.tsx(.test)        shell + SSR auth gate (session.me)
+  (portal)/page.tsx                 overview
+  (portal)/billing/page.tsx(.test)  plan + payment method + quoted plan change
+  (portal)/invoices/page.tsx        invoice history (links out)
+  (portal)/api-keys/page.tsx(.test) framework key management (graceful)
+  (portal)/profile/page.tsx         identity + password reset + sign out
+  (portal)/error.tsx · not-found.tsx
+src/locales/{en,de}.ts              bilingual catalogs (parity-enforced)
+```
+
+## Going to production
+
+- **Real Stripe** — configure `billingPlugin({ provider: 'stripe', … })` on the
+  API; `billing.portalUrl` then opens Stripe's real hosted portal and
+  `billing.invoices` returns real `hostedUrl`/`pdfUrl` links.
+- **Email** — wire `sendEmail` on the API so the profile password-reset actually
+  delivers.

package/templates/apps/frontend-portal/app.config.ts

@@ -0,0 +1,37 @@
+// Web app for the {{projectName}} project — the customer BILLING + ACCOUNT
+// portal over the sibling `api-saas-starter` api. Slim by design: the screens a
+// customer visits to manage their account OUTSIDE the product — plan, payment
+// method, invoices, API keys, profile.
+//
+//   - `/login` — static sign-in that POSTs to the api's `/auth/*`.
+//   - The authed portal in the SILENT route group `src/pages/(portal)/`. Its
+//     `layout.tsx` loader is the auth gate (asks the api's `session.me`,
+//     RedirectErrors an anonymous visitor to /login). Its pages are
+//     `renderMode: 'ssr'` so the gate runs per request.
+//
+// Billing is plugin-orchestrated: `billing.subscription` / `billing.invoices`
+// are live reads, and card management / plan changes go through the provider via
+// `billing.portalUrl` / `billing.changePlan` — the template never renders an
+// invoice or holds a card itself.
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api this portal consumes. Pair with api-saas-starter:
+  // `voltro init my-saas --api=api-saas-starter --web=frontend-portal`.
+  // The hooks pass 'app' as the lookup key; codegen pulls its typed rpc surface
+  // (session.me + the billing plugin's `billing.*`).
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

package/templates/apps/frontend-portal/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@{{projectName}}/api": "0.30.0",
+    "@voltro/cli": "0.30.0",
+    "@voltro/client": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/i18n": "0.30.0",
+    "@voltro/ui-shadcn": "0.30.0",
+    "@voltro/web": "0.30.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@voltro/devtools": "0.30.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/frontend-portal/src/config.ts

@@ -0,0 +1,8 @@
+// The brand name shown in the marketing header + dashboard sidebar.
+//
+// A plain constant — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. `VOLTRO_PUBLIC_APP_NAME` is still
+// declared in app.config.ts (validated + in the env manifest); to read it typed
+// instead, after one `voltro dev` swap this for
+// `publicEnv.VOLTRO_PUBLIC_APP_NAME` from '@voltro/env/public'.
+export const APP_NAME = '{{capProjectName}}'

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:locale` 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')
+  })
+})