tapimo 0.6.0 → 0.7.1

package/src/apps/management/routes/billing.test.ts

@@ -5,11 +5,10 @@ import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import * as ApiKeys from '../../../ApiKeys.js'
 import * as TestApp from '../../../../test/App.js'
 import * as TestStripe from '../../../../test/Stripe.js'
-import * as EarlyAccess from '../../../db/tables/earlyAccess.js'
+import * as EnabledBillingSources from '../../../db/tables/enabledBillingSources.js'
 import * as Memberships from '../../../db/tables/memberships.js'
 import * as SponsoredTransactions from '../../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../../db/tables/stripeCustomers.js'
-import * as Users from '../../../db/tables/users.js'
 import * as Viem from '../../../internal/Viem.js'
 import * as core_Billing from '../Billing.js'
 import type * as App from '../../../App.js'
@@ -66,7 +65,6 @@ function createApp(
     billing?: App.Billing | undefined
     db?: TestApp.create.Options['db']
     kv?: { store: ReturnType<typeof TestApp.kvStore> }
-    tmp_earlyAccess?: boolean
   } = {},
 ) {
   // prettier-ignore
@@ -76,7 +74,6 @@ function createApp(
     db: options.db ?? TestApp.database(),
     ...(options.kv ? { kv: options.kv } : {}),
     session: { wallet: { origin } },
-    ...(options.tmp_earlyAccess === undefined ? {} : { tmp_earlyAccess: options.tmp_earlyAccess }),
   })
 }
 
@@ -108,6 +105,20 @@ async function seeded(app: ReturnType<typeof createApp>) {
   return { cookie, orgId: id }
 }
 
+/** Seeds an owned organization with Stripe setup enabled. */
+async function seededWithStripe(
+  app: ReturnType<typeof createApp>,
+  db: ReturnType<typeof TestApp.database>,
+) {
+  const result = await seeded(app)
+  await EnabledBillingSources.add(db, {
+    createdBy: 'test',
+    orgId: result.orgId,
+    source: 'stripe',
+  })
+  return result
+}
+
 describe('GET /orgs/:orgId/billing', () => {
   test('behavior: synthesizes none for orgs without a billing source', async () => {
     const app = createApp()
@@ -116,6 +127,7 @@ describe('GET /orgs/:orgId/billing', () => {
     expect(response.status).toBe(200)
     expect(await response.json()).toMatchInlineSnapshot(`
       {
+        "enabledSources": [],
         "spend": {
           "amount": "0",
           "currency": "usd",
@@ -139,6 +151,28 @@ describe('GET /orgs/:orgId/billing', () => {
     expect(body.updatedAt).toBeDefined()
   })
 
+  test('behavior: lists organization-wide sources in canonical order', async () => {
+    const db = TestApp.database()
+    const app = createApp({ billing: billingWithSandbox(), db })
+    const { cookie, orgId } = await seeded(app)
+    await EnabledBillingSources.add(db, { createdBy: 'test', orgId, source: 'tempo' })
+    await EnabledBillingSources.add(db, { createdBy: 'test', orgId, source: 'stripe' })
+
+    const production = await app.request(`/v1/orgs/${orgId}/billing`, { headers: { cookie } })
+    const sandbox = await app.request(`/v1/orgs/${orgId}/billing?environment=sandbox`, {
+      headers: { cookie },
+    })
+
+    expect(await production.json()).toMatchObject({
+      enabledSources: ['stripe', 'tempo'],
+      status: 'none',
+    })
+    expect(await sandbox.json()).toMatchObject({
+      enabledSources: ['stripe', 'tempo'],
+      status: 'none',
+    })
+  })
+
   test('behavior: the super admin reads any org', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
@@ -165,7 +199,7 @@ describe('GET /orgs/:orgId/billing', () => {
     expect(response.status).toBe(401)
   })
 
-  test('behavior: 501 when billing is unconfigured', async () => {
+  test('behavior: reads database-backed state when Stripe is unconfigured', async () => {
     const app = TestApp.create({
       auth: { superAdmin: { secret } },
       db: TestApp.database(),
@@ -173,9 +207,18 @@ describe('GET /orgs/:orgId/billing', () => {
     })
     const { cookie, orgId } = await seeded(app)
     const response = await app.request(`/v1/orgs/${orgId}/billing`, { headers: { cookie } })
-    expect(response.status).toBe(501)
-    const body = (await response.json()) as { error: { code: string } }
-    expect(body.error.code).toMatchInlineSnapshot(`"billing_unconfigured"`)
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "enabledSources": [],
+        "spend": {
+          "amount": "0",
+          "currency": "usd",
+          "period": "month",
+        },
+        "status": "none",
+      }
+    `)
   })
 })
 
@@ -202,6 +245,7 @@ describe('PATCH /orgs/:orgId/billing', () => {
     expect(response.status).toBe(200)
     expect(await response.json()).toMatchInlineSnapshot(`
       {
+        "enabledSources": [],
         "spend": {
           "amount": "0",
           "currency": "usd",
@@ -294,7 +338,7 @@ describe('PATCH /orgs/:orgId/billing', () => {
     expect(response.status).toBe(404)
   })
 
-  test('behavior: 501 when billing is unconfigured', async () => {
+  test('behavior: updates database-backed state when Stripe is unconfigured', async () => {
     const app = TestApp.create({
       auth: { superAdmin: { secret } },
       db: TestApp.database(),
@@ -303,9 +347,12 @@ describe('PATCH /orgs/:orgId/billing', () => {
     const { cookie, orgId } = await seeded(app)
     const response = await app.request(
       `/v1/orgs/${orgId}/billing`,
-      patch(cookie, { spendLimit: null }),
+      patch(cookie, { spendLimit: { amount: '250' } }),
     )
-    expect(response.status).toBe(501)
+    expect(response.status).toBe(200)
+    expect(
+      ((await response.json()) as { spendLimit?: { amount: string } }).spendLimit?.amount,
+    ).toBe('250')
   })
 })
 
@@ -355,8 +402,9 @@ describe('POST /orgs/:orgId/billing/stripe/checkout', () => {
   })
 
   test('behavior: an unreachable Stripe maps to the upstream error envelope', async () => {
-    const app = createApp()
-    const { cookie, orgId } = await seeded(app)
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const { cookie, orgId } = await seededWithStripe(app, db)
     // First Stripe call the route makes is the customer create; the connection
     // is refused for real (no transport fake).
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
@@ -366,9 +414,13 @@ describe('POST /orgs/:orgId/billing/stripe/checkout', () => {
   })
 })
 
-describe('early access', () => {
-  test('behavior: checkout requires early access', async () => {
-    const app = createApp({ tmp_earlyAccess: true })
+describe('billing source access', () => {
+  test('behavior: checkout requires Stripe to be enabled', async () => {
+    const app = TestApp.create({
+      auth: { superAdmin: { secret } },
+      db: TestApp.database(),
+      session: { wallet: { origin } },
+    })
     const { cookie, orgId } = await seeded(app)
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     expect(response.status).toBe(403)
@@ -377,75 +429,29 @@ describe('early access', () => {
     expect(body).toMatchInlineSnapshot(`
       {
         "error": {
-          "code": "early_access_required",
-          "message": "Requires early access. Ask a teammate with access to invite you by email, or contact Tempo.",
+          "code": "billing_source_disabled",
+          "message": "Stripe billing is not enabled for this organization",
         },
       }
     `)
   })
 
-  test('behavior: the gate precedes membership resolution', async () => {
-    // The gate depends only on the caller, so it leaks nothing about the org;
-    // early-access strangers still get the membership 404.
+  test('behavior: the source gate replaces temporary billing early access', async () => {
     const db = TestApp.database()
-    const app = createApp({ db, tmp_earlyAccess: true })
-    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
-    const { orgId } = await seeded(app)
-
-    const other = await session(app)
-    const gated = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(other))
-    expect(gated.status).toBe(403)
-    expect(((await gated.json()) as { error: { code: string } }).error.code).toBe('early_access_required') // prettier-ignore
-
-    const granted = await session(app)
-    const me = await app.request('/v1/me', { headers: { cookie: granted } })
-    const { id: userId } = (await me.json()) as { id: string }
-    await Users.setEmail(db, userId, 'stranger@example.org')
-    expect(
-      (await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(granted))).status,
-    ).toBe(404)
-  })
-
-  test('behavior: the gate precedes the owner-role check', async () => {
-    const db = TestApp.database()
-    const app = createApp({ db, tmp_earlyAccess: true })
-    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
-    const { orgId } = await seeded(app)
-    const member = await session(app)
-    const me = await app.request('/v1/me', { headers: { cookie: member } })
-    const { id: userId } = (await me.json()) as { id: string }
-    await Memberships.create(db, { orgId, role: 'member', userId })
-
-    const gated = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(member))
-    expect(gated.status).toBe(403)
-    expect(((await gated.json()) as { error: { code: string } }).error.code).toBe('early_access_required') // prettier-ignore
-
-    // Early-access members still fail the owner-role check.
-    await Users.setEmail(db, userId, 'member@example.org')
-    const write = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(member))
-    expect(write.status).toBe(403)
-    expect(((await write.json()) as { error: { code: string } }).error.code).toBe('forbidden')
-  })
-
-  test('behavior: early-access owners pass the gate', async () => {
-    const db = TestApp.database()
-    const app = createApp({ db, tmp_earlyAccess: true })
-    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
-    const { cookie, orgId } = await seeded(app)
-    const me = await app.request('/v1/me', { headers: { cookie } })
-    const { id: userId } = (await me.json()) as { id: string }
-    await Users.setEmail(db, userId, 'dev@example.org')
+    const app = createApp({ db })
+    const { cookie, orgId } = await seededWithStripe(app, db)
 
-    // The unreachable Stripe upstream (502) proves the request passed the gate.
+    // The unreachable Stripe upstream proves source access, not user early access, is the gate.
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     expect(response.status).toBe(502)
     expect(((await response.json()) as { error: { code: string } }).error.code).toBe('upstream_error') // prettier-ignore
   })
 
-  test('behavior: management keys pass the gate', async () => {
+  test('behavior: an enabled management key reaches Stripe', async () => {
+    const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
-    const app = createApp({ tmp_earlyAccess: true, kv: { store } })
-    const { orgId } = await seeded(app)
+    const app = createApp({ db, kv: { store } })
+    const { orgId } = await seededWithStripe(app, db)
     const { token } = await ApiKeys.mint(store, { orgId, scopes: ['management:write'] })
 
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, {
@@ -455,9 +461,10 @@ describe('early access', () => {
     expect(response.status).toBe(502)
   })
 
-  test('behavior: the super admin passes the gate', async () => {
-    const app = createApp({ tmp_earlyAccess: true })
-    const { orgId } = await seeded(app)
+  test('behavior: an enabled super admin reaches Stripe', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const { orgId } = await seededWithStripe(app, db)
 
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, {
       ...as(secret),
@@ -551,6 +558,7 @@ describe('DELETE /orgs/:orgId', () => {
     const db = TestApp.database()
     const app = createApp({ db })
     const { cookie, orgId } = await seeded(app)
+    await EnabledBillingSources.add(db, { createdBy: 'test', orgId, source: 'stripe' })
     await StripeCustomers.create(db, { orgId, stripeCustomerId: 'cus_cascade' })
 
     const response = await app.request(`/v1/orgs/${orgId}`, {
@@ -558,19 +566,30 @@ describe('DELETE /orgs/:orgId', () => {
       method: 'DELETE',
     })
     expect(response.status).toBe(200)
+    expect(await EnabledBillingSources.listByOrg(db, orgId)).toEqual([])
     expect(await StripeCustomers.get(db, orgId)).toBeUndefined()
   })
 })
 
 describe('environment scoping', () => {
-  test('behavior: sandbox is 501 when no sandbox source is configured', async () => {
+  test('behavior: sandbox billing state remains readable without a Stripe source', async () => {
     const app = createApp()
     const { cookie, orgId } = await seeded(app)
     const response = await app.request(`/v1/orgs/${orgId}/billing?environment=sandbox`, {
       headers: { cookie },
     })
-    expect(response.status).toBe(501)
-    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('billing_unconfigured') // prettier-ignore
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "enabledSources": [],
+        "spend": {
+          "amount": "0",
+          "currency": "usd",
+          "period": "month",
+        },
+        "status": "none",
+      }
+    `)
   })
 
   test('behavior: rejects an unknown environment', async () => {
@@ -756,7 +775,7 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
   test('checkout provisions distinct customers per environment', { timeout: 30_000 }, async () => {
     const db = TestApp.database()
     const app = createApp({ billing: sandboxBillingBoth(), db })
-    const { cookie, orgId } = await seeded(app)
+    const { cookie, orgId } = await seededWithStripe(app, db)
 
     const prod = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     const sbx = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout?environment=sandbox`, post(cookie)) // prettier-ignore
@@ -783,7 +802,7 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
   test('checkout provisions a real customer and setup session', { timeout: 30_000 }, async () => {
     const db = TestApp.database()
     const app = createApp({ billing: sandboxBilling(), db })
-    const { cookie, orgId } = await seeded(app)
+    const { cookie, orgId } = await seededWithStripe(app, db)
 
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     // Track for teardown before asserting: a failed assertion must not leak
@@ -831,7 +850,7 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
       // prettier-ignore
       const db = TestApp.database()
       const app = createApp({ billing: sandboxBilling(), db })
-      const { cookie, orgId } = await seeded(app)
+      const { cookie, orgId } = await seededWithStripe(app, db)
       const checkout = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
       const customerId = (await StripeCustomers.get(db, orgId))?.stripeCustomerId
       if (customerId) TestStripe.track(customerId)
@@ -844,8 +863,9 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
         invoice_settings: { default_payment_method: attached.paymentMethod },
       })
       await StripeCustomers.setStatus(db, orgId, 'active')
+      await EnabledBillingSources.remove(db, { orgId, source: 'stripe' })
 
-      // The list reads live Stripe state: card details plus the default marker.
+      // Disabling setup does not block management of the existing Stripe source.
       const list = await app.request(`/v1/orgs/${orgId}/billing/payment-methods`, {
         headers: { cookie },
       })
@@ -900,7 +920,7 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
       // prettier-ignore
       const db = TestApp.database()
       const app = createApp({ billing: sandboxBilling(), db })
-      const { cookie, orgId } = await seeded(app)
+      const { cookie, orgId } = await seededWithStripe(app, db)
       const checkout = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
       const customerId = (await StripeCustomers.get(db, orgId))?.stripeCustomerId
       if (customerId) TestStripe.track(customerId)
@@ -930,11 +950,12 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (direct)', () => {
 
     const db = TestApp.database()
     const app = createApp({ billing: sandboxBilling(), db })
-    const { cookie, orgId } = await seeded(app)
+    const { cookie, orgId } = await seededWithStripe(app, db)
     const checkout = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     const customerId = (await StripeCustomers.get(db, orgId))?.stripeCustomerId
     if (customerId) TestStripe.track(customerId)
     expect(checkout.status).toBe(200)
+    await EnabledBillingSources.remove(db, { orgId, source: 'stripe' })
 
     const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/manage`, post(cookie))
     expect(response.status).toBe(200)
@@ -963,7 +984,7 @@ describe.runIf(TestStripe.secretKey)('stripe sandbox (live delivery)', () => {
   })
 
   test('attach → active, detach → none, delete → canceled', { timeout: 300_000 }, async () => {
-    const { cookie, orgId } = await seeded(app)
+    const { cookie, orgId } = await seededWithStripe(app, db)
     const checkout = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
     const customerId = (await StripeCustomers.get(db, orgId))?.stripeCustomerId
     if (customerId) TestStripe.track(customerId)

package/src/apps/management/routes/billing.ts

@@ -6,6 +6,7 @@ import * as ApiKeys from '../../../ApiKeys.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as BillingSettings from '../../../db/tables/billingSettings.js'
 import * as Db from '../../../db/Db.js'
+import * as EnabledBillingSources from '../../../db/tables/enabledBillingSources.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -113,6 +114,12 @@ export namespace schema {
   /** An organization's billing state. */
   export const Billing = Schema.describe(
     z.object({
+      enabledSources: z
+        .array(z.enum(EnabledBillingSources.sources))
+        .check(
+          z.describe('Billing sources this organization may set up.'),
+          z.meta({ examples: [['stripe']] }),
+        ),
       spend: z
         .optional(
           z.object({
@@ -234,7 +241,7 @@ export namespace schema {
 }
 
 /**
- * Mounts billing routes. Reads require membership or scoped API key access; organizations without Stripe state return `none`.
+ * Mounts billing routes. Reads require membership or scoped API key access; organizations without provider state return `none`.
  */
 export function billing() {
   return new Hono<Environment>()
@@ -255,7 +262,6 @@ export function billing() {
         responses: OpenApi.responses({
           errors: {
             404: 'No accessible organization was found for this id.',
-            501: 'Billing is not configured on this deployment.',
           },
           success: { description: "The organization's billing state.", schema: schema.Billing },
         }),
@@ -276,10 +282,7 @@ export function billing() {
             message: 'Check the query parameters and try again.',
           })
 
-        const billing = c.get('billing')
-        if (!billing) return billingUnconfigured(c)
         const environment = c.req.valid('query').environment
-        if (!stripeFor(billing, environment)) return billingUnconfigured(c)
 
         try {
           return c.json(
@@ -313,7 +316,6 @@ export function billing() {
           errors: {
             403: 'Requires the owner role.',
             404: 'No accessible organization was found for this id.',
-            501: 'Billing is not configured on this deployment.',
           },
           success: {
             description: "The organization's updated billing state.",
@@ -342,10 +344,7 @@ export function billing() {
             message: 'Check the request body and try again.',
           })
 
-        const billing = c.get('billing')
-        if (!billing) return billingUnconfigured(c)
         const environment = c.req.valid('query').environment
-        if (!stripeFor(billing, environment)) return billingUnconfigured(c)
 
         const body = c.req.valid('json')
         const org = Auth.org(c)
@@ -380,7 +379,7 @@ export function billing() {
     )
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/checkout',
-      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true, tmp_earlyAccess: true }), // prettier-ignore
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -395,8 +394,8 @@ export function billing() {
         responses: OpenApi.responses({
           errors: {
             403: {
-              codes: ['api_key_forbidden', 'early_access_required', 'forbidden'],
-              description: 'Requires the owner role and early access.',
+              codes: ['api_key_forbidden', 'billing_source_disabled', 'forbidden'],
+              description: 'Requires the owner role and Stripe billing enabled.',
             },
             404: 'No accessible organization was found for this id.',
             501: 'Billing is not configured on this deployment.',
@@ -413,7 +412,6 @@ export function billing() {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
-        if (Auth.tmp_narrowEarlyAccess) return Auth.tmp_ensureEarlyAccessError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -425,16 +423,19 @@ export function billing() {
             message: 'Check the query parameters and try again.',
           })
 
-        const billing = c.get('billing')
-        if (!billing) return billingUnconfigured(c)
-        const environment = c.req.valid('query').environment
-        const source = stripeFor(billing, environment)
-        if (!source) return billingUnconfigured(c)
-
-        const { client } = source
         const org = Auth.org(c)
         const db = Db.get(c.get('db'))
         try {
+          if (!(await EnabledBillingSources.isEnabled(db, { orgId: org.id, source: 'stripe' })))
+            return billingSourceDisabled(c)
+
+          const billing = c.get('billing')
+          if (!billing) return billingUnconfigured(c)
+          const environment = c.req.valid('query').environment
+          const source = stripeFor(billing, environment)
+          if (!source) return billingUnconfigured(c)
+
+          const { client } = source
           const existing = await StripeCustomers.get(db, org.id, environment)
           const customerId = existing
             ? existing.stripeCustomerId
@@ -885,7 +886,8 @@ async function billingBody(
   environment: ResourceEnvironment,
 ) {
   const db = Db.get(c.get('db'))
-  const [record, settings] = await Promise.all([
+  const [enabledSources, record, settings] = await Promise.all([
+    EnabledBillingSources.listByOrg(db, orgId),
     StripeCustomers.get(db, orgId, environment),
     BillingSettings.get(db, orgId, environment),
   ])
@@ -900,6 +902,7 @@ async function billingBody(
     since: core_Billing.periodStart(period),
   })
   return {
+    enabledSources: enabledSources.map((record) => record.source),
     spend: { amount: core_Billing.fromBaseUnits(spend), currency, period },
     ...(settings?.spendLimit != null
       ? { spendLimit: { amount: settings.spendLimit, currency, period } }
@@ -959,6 +962,14 @@ function billingNotFound(c: Context<Environment>) {
   })
 }
 
+function billingSourceDisabled(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'billing_source_disabled',
+    message: 'Stripe billing is not enabled for this organization',
+    status: 403,
+  })
+}
+
 function billingUnconfigured(c: Context<Environment>) {
   return Response.error(c, {
     code: 'billing_unconfigured',

package/src/apps/management/routes/faucet.test.ts

@@ -43,9 +43,17 @@ describe('faucet', () => {
     expect(funded.status).toBe(200)
     const result = await TestApp.json(funded, Faucet.schema.FundResponse)
     expect(result.tokens.length).toBeGreaterThan(0)
-    expect(result.tokens.every((token) => token.symbol.length > 0)).toBe(true)
-    expect(result.tokens.every((token) => BigInt(token.amount) > 0n)).toBe(true)
-    expect(result.transactionHashes).toEqual(result.tokens.map((token) => token.transactionHash))
+    expect(
+      result.tokens.every(
+        (entry) =>
+          entry.token.symbol.length > 0 &&
+          BigInt(entry.amount.baseUnits) > 0n &&
+          entry.amount.currency === entry.token.currency &&
+          entry.amount.decimals === entry.token.decimals &&
+          /^\d+(\.\d+)?$/.test(entry.amount.formatted),
+      ),
+    ).toBe(true)
+    expect(result.transactionHashes).toEqual(result.tokens.map((entry) => entry.transactionHash))
 
     const repeated = await app.request(`/v1/orgs/${org.id}/faucet`, {
       body: JSON.stringify({ address: recipient }),

package/src/apps/management/routes/faucet.ts

@@ -6,6 +6,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as RateLimit from '../../../internal/RateLimit.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
+import * as Value from '../../../internal/Value.js'
 import * as Viem from '../../../internal/Viem.js'
 import type { Environment } from '../App.js'
 
@@ -14,6 +15,37 @@ const userRateLimit = { perMinute: 3 } satisfies RateLimit.Limit
 
 /** OpenAPI schemas owned by the sandbox faucet. */
 export namespace schema {
+  const Token = Schema.describe(
+    z.object({
+      address: Schema.TokenAddress.check(z.describe('The test token contract that minted funds.')),
+      currency: z
+        .string()
+        .check(z.describe('The token’s currency label.'), z.meta({ examples: ['USD'] })),
+      decimals: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('The decimal places used by the token.'),
+          z.meta({ examples: [6] }),
+        ),
+      name: z
+        .string()
+        .check(z.describe('The token’s human-readable name.'), z.meta({ examples: ['Test USD'] })),
+      symbol: z.string().check(z.describe('The token’s symbol.'), z.meta({ examples: ['TUSD'] })),
+    }),
+    'A test token minted by the faucet.',
+  )
+
+  const FundedToken = Schema.describe(
+    z.object({
+      amount: Schema.TokenAmount.check(z.describe('Amount minted by the faucet.')),
+      token: Token,
+      transactionHash: Schema.Hash.check(z.describe('The transaction that minted this token.')),
+    }),
+    'One token amount minted by the faucet.',
+  )
+
   /** Faucet request body. */
   export const FundBody = Schema.describe(
     z.object({ address: Schema.Address }),
@@ -24,29 +56,7 @@ export namespace schema {
   export const FundResponse = Schema.describe(
     z.object({
       tokens: z
-        .array(
-          z.object({
-            address: Schema.TokenAddress.check(
-              z.describe('The test token contract that minted funds.'),
-            ),
-            amount: Schema.DecimalString.check(
-              z.describe('The minted amount in the token’s smallest units.'),
-            ),
-            currency: z.string().check(z.describe('The token’s currency label.')),
-            decimals: z
-              .number()
-              .check(
-                z.int(),
-                z.nonnegative(),
-                z.describe('The number of decimal places the token uses.'),
-              ),
-            name: z.string().check(z.describe('The token’s human-readable name.')),
-            symbol: z.string().check(z.describe('The token’s symbol.')),
-            transactionHash: Schema.Hash.check(
-              z.describe('The transaction that minted this token.'),
-            ),
-          }),
-        )
+        .array(FundedToken)
         .check(z.describe('The configured test tokens minted to the account.')),
       transactionHashes: z
         .array(Schema.Hash)
@@ -124,17 +134,23 @@ export function faucet() {
             const event = client.token.mint.extractEvent(receipt.logs)
             const metadata = await client.token.getMetadata({ token: event.address })
             return {
-              address: event.address,
-              amount: event.args.amount.toString(),
-              currency: metadata.currency,
-              decimals: metadata.decimals,
-              name: metadata.name,
-              symbol: metadata.symbol,
+              amount: Value.tokenAmount({
+                baseUnits: event.args.amount,
+                currency: metadata.currency,
+                decimals: metadata.decimals,
+              }),
+              token: {
+                address: event.address,
+                currency: metadata.currency,
+                decimals: metadata.decimals,
+                name: metadata.name,
+                symbol: metadata.symbol,
+              },
               transactionHash: receipt.transactionHash,
             }
           }),
         )
-        const transactionHashes = tokens.map((token) => token.transactionHash)
+        const transactionHashes = tokens.map((entry) => entry.transactionHash)
         return c.json(Response.validated(schema.FundResponse, { tokens, transactionHashes }), 200)
       } catch (cause) {
         return Response.upstream(c, cause)