tapimo 0.11.0 → 0.12.0

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

@@ -19,28 +19,31 @@ export namespace schema {
   /** Schemas for the getRequestUsage operation. */
   export namespace getRequestUsage {
     /** Usage grouped by API key. */
-    export const KeyBreakdown = z
-      .object({
-        apiKeyId: z
-          .string()
-          .check(
-            z.describe('API key id (`key_…`).'),
-            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-        averageDurationMs: z
-          .number()
-          .check(
-            z.describe('Average request duration in milliseconds.'),
-            z.meta({ examples: [12.3] }),
-          ),
-        errors: z
+    export const KeyBreakdown = OpenApi.component(
+      z
+        .object({
+          apiKeyId: z
+            .string()
+            .check(
+              z.describe('API key id (`key_…`).'),
+              z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+          averageDurationMs: z
+            .number()
+            .check(
+              z.describe('Average request duration in milliseconds.'),
+              z.meta({ examples: [12.3] }),
+            ),
+          errors: z
           .number()
           .check(z.int(), z.describe('Requests whose status was at least 400.'), z.meta({ examples: [3] })), // prettier-ignore
-        requests: z
-          .number()
-          .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [120] })),
-      })
-      .check(z.describe('Usage grouped by API key.'))
+          requests: z
+            .number()
+            .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [120] })),
+        })
+        .check(z.describe('Usage grouped by API key.')),
+      'RequestUsageByKey',
+    )
 
     /** Path parameters addressing one organization's usage. */
     export const Params = z
@@ -86,147 +89,165 @@ export namespace schema {
       .check(z.describe('Query parameters for request usage.'))
 
     /** Usage grouped by route. */
-    export const RouteBreakdown = z
-      .object({
-        averageDurationMs: z
-          .number()
-          .check(
-            z.describe('Average request duration in milliseconds.'),
-            z.meta({ examples: [18.2] }),
-          ),
-        errors: z
+    export const RouteBreakdown = OpenApi.component(
+      z
+        .object({
+          averageDurationMs: z
+            .number()
+            .check(
+              z.describe('Average request duration in milliseconds.'),
+              z.meta({ examples: [18.2] }),
+            ),
+          errors: z
           .number()
           .check(z.int(), z.describe('Requests whose status was at least 400.'), z.meta({ examples: [2] })), // prettier-ignore
-        requests: z
-          .number()
-          .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [80] })),
-        route: z
-          .string()
-          .check(
-            z.describe('Matched route pattern.'),
-            z.meta({ examples: ['/v1/transactions/:hash'] }),
-          ),
-      })
-      .check(z.describe('Usage grouped by route.'))
+          requests: z
+            .number()
+            .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [80] })),
+          route: z
+            .string()
+            .check(
+              z.describe('Matched route pattern.'),
+              z.meta({ examples: ['/v1/transactions/:hash'] }),
+            ),
+        })
+        .check(z.describe('Usage grouped by route.')),
+      'RequestUsageByRoute',
+    )
 
     /** One usage series point. */
-    export const SeriesPoint = z
-      .object({
-        errors: z
+    export const SeriesPoint = OpenApi.component(
+      z
+        .object({
+          errors: z
           .number()
           .check(z.int(), z.describe('Requests whose status was at least 400.'), z.meta({ examples: [1] })), // prettier-ignore
-        requests: z
-          .number()
-          .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [40] })),
-        time: z
-          .string()
-          .check(
-            z.describe('Bucket start timestamp (ISO 8601).'),
-            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-          ),
-      })
-      .check(z.describe('One usage series point.'))
+          requests: z
+            .number()
+            .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [40] })),
+          time: z.iso
+            .datetime()
+            .check(
+              z.describe('Bucket start timestamp (ISO 8601).'),
+              z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+            ),
+        })
+        .check(z.describe('One usage series point.')),
+      'RequestUsageSeriesPoint',
+    )
 
     /** Usage grouped by status code. */
-    export const StatusBreakdown = z
-      .object({
-        requests: z
-          .number()
-          .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [100] })),
-        status: z
-          .number()
-          .check(z.int(), z.describe('HTTP status code.'), z.meta({ examples: [200] })),
-      })
-      .check(z.describe('Usage grouped by status code.'))
+    export const StatusBreakdown = OpenApi.component(
+      z
+        .object({
+          requests: z
+            .number()
+            .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [100] })),
+          status: z
+            .number()
+            .check(z.int(), z.describe('HTTP status code.'), z.meta({ examples: [200] })),
+        })
+        .check(z.describe('Usage grouped by status code.')),
+      'RequestUsageByStatus',
+    )
 
     /** Overall usage totals. */
-    export const Totals = z
-      .object({
-        averageDurationMs: z
-          .number()
-          .check(
-            z.describe('Average request duration in milliseconds.'),
-            z.meta({ examples: [15.6] }),
-          ),
-        errors: z
+    export const Totals = OpenApi.component(
+      z
+        .object({
+          averageDurationMs: z
+            .number()
+            .check(
+              z.describe('Average request duration in milliseconds.'),
+              z.meta({ examples: [15.6] }),
+            ),
+          errors: z
           .number()
           .check(z.int(), z.describe('Requests whose status was at least 400.'), z.meta({ examples: [5] })), // prettier-ignore
-        requests: z
-          .number()
-          .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [200] })),
-      })
-      .check(z.describe('Overall usage totals.'))
+          requests: z
+            .number()
+            .check(z.int(), z.describe('Total requests.'), z.meta({ examples: [200] })),
+        })
+        .check(z.describe('Overall usage totals.')),
+      'RequestUsageTotals',
+    )
 
     /** Request usage. */
-    export const Response = Schema.describe(
-      z.object({
-        byKey: z.array(KeyBreakdown).check(z.describe('Usage grouped by API key.')),
-        byRoute: z.array(RouteBreakdown).check(z.describe('Usage grouped by route.')),
-        byStatus: z.array(StatusBreakdown).check(z.describe('Usage grouped by status code.')),
-        from: z
-          .string()
-          .check(
-            z.describe('Inclusive lower timestamp bound used for the read (ISO 8601).'),
-            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-          ),
-        interval: z
-          .enum(['day', 'hour'])
-          .check(
-            z.describe('Bucket size used for the time series.'),
-            z.meta({ examples: ['day'] }),
-          ),
-        series: z.array(SeriesPoint).check(z.describe('Usage grouped into time buckets.')),
-        to: z
-          .string()
-          .check(
-            z.describe('Inclusive upper timestamp bound used for the read (ISO 8601).'),
-            z.meta({ examples: ['2026-01-31T23:59:59.000Z'] }),
-          ),
-        totals: Totals,
-      }),
-      'Request usage.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          byKey: z.array(KeyBreakdown).check(z.describe('Usage grouped by API key.'), z.meta({ examples: [[]] })), // prettier-ignore
+          byRoute: z.array(RouteBreakdown).check(z.describe('Usage grouped by route.'), z.meta({ examples: [[]] })), // prettier-ignore
+          byStatus: z.array(StatusBreakdown).check(z.describe('Usage grouped by status code.'), z.meta({ examples: [[]] })), // prettier-ignore
+          from: z.iso
+            .datetime()
+            .check(
+              z.describe('Inclusive lower timestamp bound used for the read (ISO 8601).'),
+              z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+            ),
+          interval: z
+            .enum(['day', 'hour'])
+            .check(
+              z.describe('Bucket size used for the time series.'),
+              z.meta({ examples: ['day'] }),
+            ),
+          series: z.array(SeriesPoint).check(z.describe('Usage grouped into time buckets.'), z.meta({ examples: [[]] })), // prettier-ignore
+          to: z.iso
+            .datetime()
+            .check(
+              z.describe('Inclusive upper timestamp bound used for the read (ISO 8601).'),
+              z.meta({ examples: ['2026-01-31T23:59:59.000Z'] }),
+            ),
+          totals: Totals,
+        }),
+        'Request usage.',
+      ),
+      'RequestUsage',
     )
   }
 
   /** Schemas for the getSponsorshipUsage operation. */
   export namespace getSponsorshipUsage {
     /** One time bucket of sponsorship usage. */
-    export const Bucket = Schema.describe(
-      z.object({
-        count: z
-          .number()
-          .check(
-            z.describe('Sponsored transactions recorded in the bucket, any status.'),
-            z.meta({ examples: [42] }),
-          ),
-        failed: z
-          .number()
-          .check(
-            z.describe('Sponsored transactions in the bucket whose status is `failed`.'),
-            z.meta({ examples: [3] }),
-          ),
-        feeTotal: z
-          .object({
-            amount: z.string().check(
-              z.describe('Committed fees as a decimal string: finalized fees plus in-flight fee caps; failed rows contribute zero.'), // prettier-ignore
-              z.meta({ examples: ['12.34'] }),
+    export const Bucket = OpenApi.component(
+      Schema.describe(
+        z.object({
+          count: z
+            .number()
+            .check(
+              z.describe('Sponsored transactions recorded in the bucket, any status.'),
+              z.meta({ examples: [42] }),
             ),
-            currency: z
-              .enum(BillingSettings.currencies)
-              .check(z.describe('Currency of the fee figure.'), z.meta({ examples: ['usd'] })),
-          })
-          .check(
-            z.describe('Committed fees for the bucket.'),
-            z.meta({ examples: [{ amount: '12.34', currency: 'usd' }] }),
-          ),
-        timestamp: z
-          .string()
-          .check(
-            z.describe('Bucket start (ISO 8601), aligned to UTC calendar boundaries.'),
-            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-          ),
-      }),
-      'One time bucket of sponsorship usage.',
+          failed: z
+            .number()
+            .check(
+              z.describe('Sponsored transactions in the bucket whose status is `failed`.'),
+              z.meta({ examples: [3] }),
+            ),
+          feeTotal: z
+            .object({
+              amount: z.string().check(
+                z.describe('Committed fees as a decimal string: finalized fees plus in-flight fee caps; failed rows contribute zero.'), // prettier-ignore
+                z.meta({ examples: ['12.34'] }),
+              ),
+              currency: z
+                .enum(BillingSettings.currencies)
+                .check(z.describe('Currency of the fee figure.'), z.meta({ examples: ['usd'] })),
+            })
+            .check(
+              z.describe('Committed fees for the bucket.'),
+              z.meta({ examples: [{ amount: '12.34', currency: 'usd' }] }),
+            ),
+          timestamp: z.iso
+            .datetime()
+            .check(
+              z.describe('Bucket start (ISO 8601), aligned to UTC calendar boundaries.'),
+              z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+            ),
+        }),
+        'One time bucket of sponsorship usage.',
+      ),
+      'SponsorshipUsageBucket',
     )
 
     /** Path parameters addressing one organization's usage. */
@@ -278,15 +299,19 @@ export namespace schema {
       .check(z.describe('Query parameters scoping the sponsorship usage series.'))
 
     /** Sponsorship usage bucketed over time. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z
-          .array(Bucket)
-          .check(
-            z.describe('Time-ordered usage buckets; buckets with no sponsorships are omitted.'),
-          ),
-      }),
-      'Sponsorship usage bucketed over time.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z
+            .array(Bucket)
+            .check(
+              z.describe('Time-ordered usage buckets; buckets with no sponsorships are omitted.'),
+              z.meta({ examples: [[]] }),
+            ),
+        }),
+        'Sponsorship usage bucketed over time.',
+      ),
+      'SponsorshipUsage',
     )
   }
 }
@@ -310,7 +335,10 @@ export function usage() {
         operationId: 'getRequestUsage',
         responses: OpenApi.responses({
           errors: {
-            400: { codes: ['query_invalid'], description: 'Invalid query parameters.' },
+            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.',
@@ -414,7 +442,14 @@ export function usage() {
         operationId: 'getSponsorshipUsage',
         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 sponsorship usage series.",

package/src/apps/management/routes/verified-token-requests.test.ts

@@ -52,6 +52,120 @@ const token = {
   symbol: 'tUSD',
 } satisfies Partial<z.input<typeof schema.CreateBody>>
 
+test('publishes generator-ready OpenAPI contracts', async () => {
+  const { app } = createApp()
+  const spec = await (await app.request('/openapi.json')).json()
+  const collection = spec.paths['/v1/orgs/{orgId}/verified-token-requests']
+  const detail = spec.paths['/v1/orgs/{orgId}/verified-token-requests/{requestId}'].delete
+
+  expect({
+    components: [
+      'CancelVerifiedTokenRequestResponse',
+      'CreateVerifiedTokenRequestInput',
+      'VerifiedTokenRequest',
+      'VerifiedTokenRequestList',
+    ].filter((name) => spec.components.schemas[name]),
+    create: {
+      errors: {
+        400: collection.post.responses[400].content['application/json'].schema,
+        404: collection.post.responses[404].content['application/json'].schema,
+        409: collection.post.responses[409].content['application/json'].schema,
+      },
+      operationId: collection.post.operationId,
+      request: collection.post.requestBody.content['application/json'].schema,
+      response: collection.post.responses[200].content['application/json'].schema,
+    },
+    delete: {
+      errors: {
+        400: detail.responses[400].content['application/json'].schema,
+        404: detail.responses[404].content['application/json'].schema,
+        409: detail.responses[409].content['application/json'].schema,
+      },
+      operationId: detail.operationId,
+      response: detail.responses[200].content['application/json'].schema,
+    },
+    list: {
+      errors: {
+        400: collection.get.responses[400].content['application/json'].schema,
+        404: collection.get.responses[404].content['application/json'].schema,
+      },
+      operationId: collection.get.operationId,
+      response: collection.get.responses[200].content['application/json'].schema,
+    },
+    timestamps: {
+      createdAt: spec.components.schemas.VerifiedTokenRequest.properties.createdAt.format,
+      reviewedAt:
+        spec.components.schemas.VerifiedTokenRequest.properties.reviewedAt.anyOf[0].format,
+      updatedAt: spec.components.schemas.VerifiedTokenRequest.properties.updatedAt.format,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "CancelVerifiedTokenRequestResponse",
+        "CreateVerifiedTokenRequestInput",
+        "VerifiedTokenRequest",
+        "VerifiedTokenRequestList",
+      ],
+      "create": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+          "409": {
+            "$ref": "#/components/schemas/RequestLimitReachedOrRequestPendingExistsOrVerifiedSymbolExistsOrVerifiedTokenExistsError",
+          },
+        },
+        "operationId": "createVerifiedTokenRequest",
+        "request": {
+          "$ref": "#/components/schemas/CreateVerifiedTokenRequestInput",
+        },
+        "response": {
+          "$ref": "#/components/schemas/VerifiedTokenRequest",
+        },
+      },
+      "delete": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundOrVerifiedTokenRequestNotFoundError",
+          },
+          "409": {
+            "$ref": "#/components/schemas/RequestNotPendingError",
+          },
+        },
+        "operationId": "cancelVerifiedTokenRequest",
+        "response": {
+          "$ref": "#/components/schemas/CancelVerifiedTokenRequestResponse",
+        },
+      },
+      "list": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+        },
+        "operationId": "listVerifiedTokenRequests",
+        "response": {
+          "$ref": "#/components/schemas/VerifiedTokenRequestList",
+        },
+      },
+      "timestamps": {
+        "createdAt": "date-time",
+        "reviewedAt": "date-time",
+        "updatedAt": "date-time",
+      },
+    }
+  `)
+})
+
 describe('POST /v1/orgs/:orgId/verified-token-requests', () => {
   test('members submit requests', async () => {
     const db = TestApp.database()