tapimo 0.10.2 → 0.12.0

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

@@ -49,194 +49,217 @@ export namespace schema {
     .check(z.describe('Path parameters addressing one payment method.'))
 
   /** A per-period spend limit. */
-  export const SpendLimit = Schema.describe(
-    z.object({
-      amount: z.string().check(
-        // The lookahead rejects zero: a zero limit would refuse all
-        // sponsorship, which `null` (clear) already expresses.
-        z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
-        z.describe('Limit as a positive decimal string in `currency` units.'),
-        z.meta({ examples: ['250'] }),
-      ),
-      currency: z
-        ._default(z.enum(BillingSettings.currencies), 'usd')
-        .check(
-          z.describe('Currency the limit is denominated in; `usd` only today.'),
-          z.meta({ examples: ['usd'] }),
-        ),
-      period: z
-        ._default(z.enum(BillingSettings.periods), 'month')
-        .check(
-          z.describe('Window the limit applies over; `month` (UTC calendar) only today.'),
-          z.meta({ examples: ['month'] }),
+  export const SpendLimit = OpenApi.component(
+    Schema.describe(
+      z.object({
+        amount: z.string().check(
+          // The lookahead rejects zero: a zero limit would refuse all
+          // sponsorship, which `null` (clear) already expresses.
+          z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
+          z.describe('Limit as a positive decimal string in `currency` units.'),
+          z.meta({ examples: ['250'] }),
         ),
-    }),
-    'A per-period spend limit.',
+        currency: z
+          ._default(z.enum(BillingSettings.currencies), 'usd')
+          .check(
+            z.describe('Currency the limit is denominated in; `usd` only today.'),
+            z.meta({ examples: ['usd'] }),
+          ),
+        period: z
+          ._default(z.enum(BillingSettings.periods), 'month')
+          .check(
+            z.describe('Window the limit applies over; `month` (UTC calendar) only today.'),
+            z.meta({ examples: ['month'] }),
+          ),
+      }),
+      'A per-period spend limit.',
+    ),
+    'BillingSpendLimit',
   )
 
   /** A per-transaction fee cap. */
-  export const TxFeeLimit = Schema.describe(
-    z.object({
-      amount: z.string().check(
-        // The lookahead rejects zero: a zero cap would refuse every
-        // transaction, which is not a supported configuration.
-        z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
-        z.describe('Cap as a positive decimal string in `currency` units.'),
-        z.meta({ examples: ['0.50'] }),
-      ),
-      currency: z
-        ._default(z.enum(BillingSettings.currencies), 'usd')
-        .check(
-          z.describe('Currency the cap is denominated in; `usd` only today.'),
-          z.meta({ examples: ['usd'] }),
+  export const TxFeeLimit = OpenApi.component(
+    Schema.describe(
+      z.object({
+        amount: z.string().check(
+          // The lookahead rejects zero: a zero cap would refuse every
+          // transaction, which is not a supported configuration.
+          z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
+          z.describe('Cap as a positive decimal string in `currency` units.'),
+          z.meta({ examples: ['0.50'] }),
         ),
-    }),
-    'A per-transaction fee cap.',
+        currency: z
+          ._default(z.enum(BillingSettings.currencies), 'usd')
+          .check(
+            z.describe('Currency the cap is denominated in; `usd` only today.'),
+            z.meta({ examples: ['usd'] }),
+          ),
+      }),
+      'A per-transaction fee cap.',
+    ),
+    'BillingTransactionFeeLimit',
   )
 
   /** PATCH body; absent fields stay unchanged, null clears a limit. */
-  export const Patch = Schema.describe(
-    z.object({
-      spendLimit: z
-        .optional(z.nullable(SpendLimit))
-        .check(
-          z.describe('Spend limit per period; absent leaves it unchanged, null removes it.'),
-          z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
+  export const Patch = OpenApi.component(
+    Schema.describe(
+      z.object({
+        spendLimit: z
+          .optional(z.nullable(SpendLimit))
+          .check(
+            z.describe('Spend limit per period; absent leaves it unchanged, null removes it.'),
+            z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
+          ),
+        txFeeLimit: z.optional(z.nullable(TxFeeLimit)).check(
+          z.describe('Per-transaction fee cap; absent leaves it unchanged, null restores the platform default.'), // prettier-ignore
+          z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
         ),
-      txFeeLimit: z.optional(z.nullable(TxFeeLimit)).check(
-        z.describe('Per-transaction fee cap; absent leaves it unchanged, null restores the platform default.'), // prettier-ignore
-        z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
-      ),
-    }),
-    'Billing settings to apply.',
+      }),
+      'Billing settings to apply.',
+    ),
+    'UpdateBillingRequest',
   )
 
   /** 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']] }),
+  export const Billing = OpenApi.component(
+    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({
+              amount: z.string().check(
+                z.describe('Committed spend as a decimal string: finalized fees plus in-flight fee caps.'), // prettier-ignore
+                z.meta({ examples: ['12.34'] }),
+              ),
+              currency: z
+                .enum(BillingSettings.currencies)
+                .check(z.describe('Currency of the spend figure.'), z.meta({ examples: ['usd'] })),
+              period: z
+                .enum(BillingSettings.periods)
+                .check(z.describe('Window the figure covers.'), z.meta({ examples: ['month'] })),
+            }),
+          )
+          .check(
+            z.describe('Billable production spend committed in the current window.'),
+            z.meta({ examples: [{ amount: '12.34', currency: 'usd', period: 'month' }] }),
+          ),
+        spendLimit: z
+          .optional(SpendLimit)
+          .check(
+            z.describe('Configured spend limit; absent when the organization has none.'),
+            z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
+          ),
+        status: z.enum(StripeCustomers.statuses).check(
+          z.describe("Billing status derived from the organization's billing source; `active` opens production fee sponsorship."), // prettier-ignore
+          z.meta({ examples: ['active'] }),
         ),
-      spend: z
-        .optional(
-          z.object({
-            amount: z.string().check(
-              z.describe('Committed spend as a decimal string: finalized fees plus in-flight fee caps.'), // prettier-ignore
-              z.meta({ examples: ['12.34'] }),
+        txFeeLimit: z
+          .optional(TxFeeLimit)
+          .check(
+            z.describe(
+              'Configured per-transaction fee cap; absent when the platform default applies.',
             ),
-            currency: z
-              .enum(BillingSettings.currencies)
-              .check(z.describe('Currency of the spend figure.'), z.meta({ examples: ['usd'] })),
-            period: z
-              .enum(BillingSettings.periods)
-              .check(z.describe('Window the figure covers.'), z.meta({ examples: ['month'] })),
-          }),
-        )
-        .check(
-          z.describe('Billable production spend committed in the current window.'),
-          z.meta({ examples: [{ amount: '12.34', currency: 'usd', period: 'month' }] }),
-        ),
-      spendLimit: z
-        .optional(SpendLimit)
-        .check(
-          z.describe('Configured spend limit; absent when the organization has none.'),
-          z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
-        ),
-      status: z.enum(StripeCustomers.statuses).check(
-        z.describe("Billing status derived from the organization's billing source; `active` opens production fee sponsorship."), // prettier-ignore
-        z.meta({ examples: ['active'] }),
-      ),
-      txFeeLimit: z
-        .optional(TxFeeLimit)
-        .check(
-          z.describe(
-            'Configured per-transaction fee cap; absent when the platform default applies.',
+            z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
           ),
-          z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
+        updatedAt: z.optional(z.iso.datetime()).check(
+          z.describe('When the billing status last changed (ISO 8601); absent before first checkout.'), // prettier-ignore
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
         ),
-      updatedAt: z.optional(z.string()).check(
-        z.describe('When the billing status last changed (ISO 8601); absent before first checkout.'), // prettier-ignore
-        z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-      ),
-    }),
-    "An organization's billing state.",
+      }),
+      "An organization's billing state.",
+    ),
+    'Billing',
   )
 
   /** A hosted Stripe session link. */
-  export const Session = Schema.describe(
-    z.object({
-      url: z
-        .url()
-        .check(
-          z.describe('Hosted Stripe session URL; navigate the browser here.'),
-          z.meta({ examples: ['https://checkout.stripe.com/c/pay/cs_test_a1b2c3'] }),
-        ),
-    }),
-    'A hosted Stripe session link.',
+  export const Session = OpenApi.component(
+    Schema.describe(
+      z.object({
+        url: z
+          .url()
+          .check(
+            z.describe('Hosted Stripe session URL; navigate the browser here.'),
+            z.meta({ examples: ['https://checkout.stripe.com/c/pay/cs_test_a1b2c3'] }),
+          ),
+      }),
+      'A hosted Stripe session link.',
+    ),
+    'BillingSession',
   )
 
   /** A payment method on file. */
-  export const PaymentMethod = Schema.describe(
-    z.object({
-      card: z
-        .optional(
-          z.object({
-            brand: z
-              .string()
-              .check(z.describe('Card brand (e.g. `visa`).'), z.meta({ examples: ['visa'] })),
-            expMonth: z
-              .number()
-              .check(z.describe('Expiry month (1-12).'), z.meta({ examples: [12] })),
-            expYear: z.number().check(z.describe('Expiry year.'), z.meta({ examples: [2030] })),
-            last4: z
-              .string()
-              .check(z.describe('Last four digits.'), z.meta({ examples: ['4242'] })),
-          }),
-        )
-        .check(
-          z.describe('Card details; present when `type` is `card`.'),
-          z.meta({ examples: [{ brand: 'visa', expMonth: 12, expYear: 2030, last4: '4242' }] }),
-        ),
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the method was attached (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      default: z
-        .boolean()
-        .check(z.describe('Whether invoices charge this method.'), z.meta({ examples: [true] })),
-      id: z
-        .string()
-        .check(
-          z.describe('The payment method id (`pm_…`).'),
-          z.meta({ examples: ['pm_1NVChw2eZvKYlo2CHxiM5E2N'] }),
-        ),
-      provider: z
-        .literal('stripe')
-        .check(
-          z.describe('Payment provider; `stripe` only today.'),
-          z.meta({ examples: ['stripe'] }),
-        ),
-      type: z
-        .string()
-        .check(
-          z.describe('Method type (e.g. `card`, `us_bank_account`).'),
-          z.meta({ examples: ['card'] }),
-        ),
-    }),
-    'A payment method on file.',
+  export const PaymentMethod = OpenApi.component(
+    Schema.describe(
+      z.object({
+        card: z
+          .optional(
+            z.object({
+              brand: z
+                .string()
+                .check(z.describe('Card brand (e.g. `visa`).'), z.meta({ examples: ['visa'] })),
+              expMonth: z
+                .number()
+                .check(z.describe('Expiry month (1-12).'), z.meta({ examples: [12] })),
+              expYear: z.number().check(z.describe('Expiry year.'), z.meta({ examples: [2030] })),
+              last4: z
+                .string()
+                .check(z.describe('Last four digits.'), z.meta({ examples: ['4242'] })),
+            }),
+          )
+          .check(
+            z.describe('Card details; present when `type` is `card`.'),
+            z.meta({ examples: [{ brand: 'visa', expMonth: 12, expYear: 2030, last4: '4242' }] }),
+          ),
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the method was attached (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        default: z
+          .boolean()
+          .check(z.describe('Whether invoices charge this method.'), z.meta({ examples: [true] })),
+        id: z
+          .string()
+          .check(
+            z.describe('The payment method id (`pm_…`).'),
+            z.meta({ examples: ['pm_1NVChw2eZvKYlo2CHxiM5E2N'] }),
+          ),
+        provider: z
+          .literal('stripe')
+          .check(
+            z.describe('Payment provider; `stripe` only today.'),
+            z.meta({ examples: ['stripe'] }),
+          ),
+        type: z
+          .string()
+          .check(
+            z.describe('Method type (e.g. `card`, `us_bank_account`).'),
+            z.meta({ examples: ['card'] }),
+          ),
+      }),
+      'A payment method on file.',
+    ),
+    'BillingPaymentMethod',
   )
 
   /** An organization's payment methods. */
-  export const PaymentMethods = Schema.describe(
-    z.object({
-      data: z.array(PaymentMethod).check(z.describe('Payment methods on file, newest first.')),
-    }),
-    "An organization's payment methods.",
+  export const PaymentMethods = OpenApi.component(
+    Schema.describe(
+      z.object({
+        data: z
+          .array(PaymentMethod)
+          .check(z.describe('Payment methods on file, newest first.'), z.meta({ examples: [[]] })),
+      }),
+      "An organization's payment methods.",
+    ),
+    'BillingPaymentMethodList',
   )
 }
 
@@ -261,7 +284,14 @@ export function billing() {
         operationId: 'getBilling',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible organization was found for this id.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
           },
           success: { description: "The organization's billing state.", schema: schema.Billing },
         }),
@@ -314,8 +344,14 @@ export function billing() {
         operationId: 'updateBilling',
         responses: OpenApi.responses({
           errors: {
-            403: 'Requires the owner role.',
-            404: 'No accessible organization was found for this id.',
+            400: {
+              codes: ['body_invalid', 'param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, invalid query, or invalid body.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
           },
           success: {
             description: "The organization's updated billing state.",
@@ -328,6 +364,7 @@ export function billing() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -393,12 +430,22 @@ export function billing() {
         operationId: 'createStripeCheckout',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
             403: {
-              codes: ['api_key_forbidden', 'billing_source_disabled', 'forbidden'],
+              codes: ['billing_source_disabled'],
               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.',
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+            501: {
+              codes: ['billing_unconfigured'],
+              description: 'Billing is not configured on this deployment.',
+            },
           },
           success: {
             description: 'A Stripe Checkout (setup mode) session for attaching a payment method.',
@@ -485,9 +532,18 @@ export function billing() {
         operationId: 'createStripeManage',
         responses: OpenApi.responses({
           errors: {
-            403: 'Requires the owner role.',
-            404: 'No accessible organization, or no billing to manage yet.',
-            501: 'Billing is not configured on this deployment.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['billing_not_found', 'organization_not_found'],
+              description: 'No accessible organization or billing account was found.',
+            },
+            501: {
+              codes: ['billing_unconfigured'],
+              description: 'Billing is not configured on this deployment.',
+            },
           },
           success: {
             description: 'A Stripe billing-portal session for managing payment methods and invoices.', // prettier-ignore
@@ -500,6 +556,7 @@ export function billing() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -548,8 +605,18 @@ export function billing() {
         operationId: 'getBillingPaymentMethods',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible organization was found for this id.',
-            501: 'Billing is not configured on this deployment.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+            501: {
+              codes: ['billing_unconfigured'],
+              description: 'Billing is not configured on this deployment.',
+            },
           },
           success: {
             description: "The organization's payment methods.",
@@ -634,9 +701,18 @@ export function billing() {
         operationId: 'deleteBillingPaymentMethod',
         responses: OpenApi.responses({
           errors: {
-            403: 'Requires the owner role.',
-            404: 'No accessible organization, billing, or payment method for this id.',
-            501: 'Billing is not configured on this deployment.',
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Malformed API key, invalid path, or invalid query.',
+            },
+            404: {
+              codes: ['billing_not_found', 'organization_not_found', 'payment_method_not_found'],
+              description: 'No accessible organization, billing account, or payment method was found.', // prettier-ignore
+            },
+            501: {
+              codes: ['billing_unconfigured'],
+              description: 'Billing is not configured on this deployment.',
+            },
           },
           success: {
             description: "The organization's updated billing state.",
@@ -649,6 +725,7 @@ export function billing() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',

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

@@ -28,6 +28,45 @@ async function organization(app: ReturnType<typeof createApp>, cookie: string) {
   return TestApp.json(response, Orgs.schema.Organization)
 }
 
+test('publishes a generator-ready OpenAPI contract', async () => {
+  const spec = await (await createApp().request('/openapi.json')).json()
+  const operation = spec.paths['/v1/orgs/{orgId}/faucet'].post
+
+  expect({
+    amountExamples: spec.components.schemas.FaucetFundedToken.properties.amount.examples,
+    components: [
+      'FaucetFundedToken',
+      'FaucetToken',
+      'FundTestnetAccountRequest',
+      'FundTestnetAccountResponse',
+    ].filter((name) => spec.components.schemas[name]),
+    errors: {
+      400: operation.responses[400].content['application/json'].schema,
+      404: operation.responses[404].content['application/json'].schema,
+      429: operation.responses[429].content['application/json'].schema,
+    },
+    operationId: operation.operationId,
+    request: operation.requestBody.content['application/json'].schema,
+    response: operation.responses[200].content['application/json'].schema,
+  }).toEqual({
+    amountExamples: [{ baseUnits: '1000000000', currency: 'USD', decimals: 6, formatted: '1000' }],
+    components: [
+      'FaucetFundedToken',
+      'FaucetToken',
+      'FundTestnetAccountRequest',
+      'FundTestnetAccountResponse',
+    ],
+    errors: {
+      400: { $ref: '#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError' },
+      404: { $ref: '#/components/schemas/OrganizationNotFoundError' },
+      429: { $ref: '#/components/schemas/RateLimitExceededError' },
+    },
+    operationId: 'fundTestnetAccount',
+    request: { $ref: '#/components/schemas/FundTestnetAccountRequest' },
+    response: { $ref: '#/components/schemas/FundTestnetAccountResponse' },
+  })
+})
+
 describe('faucet', () => {
   test('funds a member account and rate limits repeated funding', async () => {
     const app = createApp()