tapimo 0.10.2 → 0.12.0

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

@@ -25,41 +25,44 @@ export namespace schema {
     )
 
   /** One project: an app or integration within an organization. */
-  export const Project = Schema.describe(
-    z.object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the project was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      environments: z.array(z.enum(environments)).check(
-        z.describe('Environments available to this project: sandbox (testnet) and production (mainnet).'), // prettier-ignore
-        z.meta({ examples: [[...environments]] }),
-      ),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque project id (`prj_…`).'),
-          z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
-      orgId: z
-        .string()
-        .check(
-          z.describe('Owning organization id (`org_…`).'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the project was last updated (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+  export const Project = OpenApi.component(
+    Schema.describe(
+      z.object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the project was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        environments: z.array(z.enum(environments)).check(
+          z.describe('Environments available to this project: sandbox (testnet) and production (mainnet).'), // prettier-ignore
+          z.meta({ examples: [[...environments]] }),
         ),
-    }),
-    'A project: an app or integration within an organization.',
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque project id (`prj_…`).'),
+            z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        name: z
+          .string()
+          .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
+        orgId: z
+          .string()
+          .check(
+            z.describe('Owning organization id (`org_…`).'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the project was last updated (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+      }),
+      'A project: an app or integration within an organization.',
+    ),
+    'Project',
   )
 
   /** Path parameters addressing an organization's project collection. */
@@ -92,34 +95,47 @@ export namespace schema {
     })
     .check(z.describe('Path parameters for one project.'))
 
-  /** Request body creating or renaming a project. */
-  export const ProjectBody = z
-    .object({ name })
-    .check(z.describe('Fields for creating or renaming a project.'))
+  /** Request body creating a project. */
+  export const CreateProjectRequest = OpenApi.component(
+    z.object({ name }).check(z.describe('Fields for creating a project.')),
+    'CreateProjectRequest',
+  )
+
+  /** Request body updating a project. */
+  export const UpdateProjectRequest = OpenApi.component(
+    z.object({ name }).check(z.describe('Fields for updating a project.')),
+    'UpdateProjectRequest',
+  )
 
   /** Schemas for the deleteProject operation. */
   export namespace deleteProject {
     /** Confirmation that the project was deleted. */
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the project that was deleted.'),
-            z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the project was deleted.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the project that was deleted.'),
+              z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the project was deleted.')),
+      'DeleteProjectResponse',
+    )
   }
 
   /** Schemas for the listProjects operation. */
   export namespace listProjects {
     /** Non-paginated list of an organization's projects. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Project).check(z.describe('The projects, newest first.')),
-      }),
-      "A non-paginated list of an organization's projects.",
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z.array(Project).check(z.describe('The projects, newest first.')),
+        }),
+        "A non-paginated list of an organization's projects.",
+      ),
+      'ProjectList',
     )
   }
 }
@@ -140,7 +156,16 @@ export function projects() {
       OpenApi.describeRoute({
         operationId: 'listProjects',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible organization was found for this id.' },
+          errors: {
+            400: {
+              codes: ['param_invalid'],
+              description: 'Malformed API key or invalid path parameters.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+          },
           success: {
             description: "The organization's projects, newest first.",
             schema: schema.listProjects.Response,
@@ -180,14 +205,23 @@ export function projects() {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.ProjectBody, {
+      OpenApi.validate('json', schema.CreateProjectRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
       OpenApi.describeRoute({
         operationId: 'createProject',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible organization was found for this id.' },
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path parameters, or invalid request body.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+          },
           success: { description: 'The created project.', schema: schema.Project },
         }),
         summary: 'Create project',
@@ -196,6 +230,7 @@ export function projects() {
       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',
@@ -229,7 +264,16 @@ export function projects() {
       OpenApi.describeRoute({
         operationId: 'getProject',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible project was found for this id.' },
+          errors: {
+            400: {
+              codes: ['param_invalid'],
+              description: 'Malformed API key or invalid path parameters.',
+            },
+            404: {
+              codes: ['organization_not_found', 'project_not_found'],
+              description: 'No accessible project was found for this id.',
+            },
+          },
           success: { description: 'One project.', schema: schema.Project },
         }),
         summary: 'Get project',
@@ -256,14 +300,23 @@ export function projects() {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.ProjectBody, {
+      OpenApi.validate('json', schema.UpdateProjectRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
       OpenApi.describeRoute({
         operationId: 'updateProject',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible project was found for this id.' },
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path parameters, or invalid request body.',
+            },
+            404: {
+              codes: ['organization_not_found', 'project_not_found'],
+              description: 'No accessible project was found for this id.',
+            },
+          },
           success: { description: 'The updated project.', schema: schema.Project },
         }),
         summary: 'Update project',
@@ -282,6 +335,7 @@ export function projects() {
             message: 'Check the request body and try again.',
           })
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
 
         const body = c.req.valid('json')
         const db = Db.get(c.get('db'))
@@ -306,7 +360,16 @@ export function projects() {
       OpenApi.describeRoute({
         operationId: 'deleteProject',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible project was found for this id.' },
+          errors: {
+            400: {
+              codes: ['param_invalid'],
+              description: 'Malformed API key or invalid path parameters.',
+            },
+            404: {
+              codes: ['organization_not_found', 'project_not_found'],
+              description: 'No accessible project was found for this id.',
+            },
+          },
           success: {
             description: 'Confirmation that the project was deleted.',
             schema: schema.deleteProject.Response,
@@ -318,6 +381,7 @@ export function projects() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',

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

@@ -2,7 +2,51 @@ import * as Scope from '../../../Scope.js'
 import * as TestApp from '../../../../test/App.js'
 import * as Scopes from './scopes.js'
 
+test('publishes a generator-ready OpenAPI contract', async () => {
+  const spec = await (await TestApp.create().request('/openapi.json')).json()
+  const operation = spec.paths['/v1/scopes'].get
+
+  expect(spec.components.schemas.ScopeList.properties.data.examples).toEqual([[]])
+
+  expect({
+    components: ['Scope', 'ScopeList'].filter((name) => spec.components.schemas[name]),
+    errors: {
+      400: operation.responses[400].content['application/json'].schema,
+      403: operation.responses[403].content['application/json'].schema,
+    },
+    operationId: operation.operationId,
+    response: operation.responses[200].content['application/json'].schema,
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "Scope",
+        "ScopeList",
+      ],
+      "errors": {
+        "400": {
+          "$ref": "#/components/schemas/ApiKeyMalformedError",
+        },
+        "403": {
+          "$ref": "#/components/schemas/ForbiddenError",
+        },
+      },
+      "operationId": "getScopes",
+      "response": {
+        "$ref": "#/components/schemas/ScopeList",
+      },
+    }
+  `)
+})
+
 describe('scopes', () => {
+  test('rejects malformed API key credentials', async () => {
+    const response = await TestApp.create().request('/v1/scopes', {
+      headers: { authorization: 'Basic wrong' },
+    })
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'api_key_malformed' } })
+  })
+
   test('lists the scope catalog without authentication (public catalog)', async () => {
     const app = TestApp.create()
     const response = await app.request('/v1/scopes')

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

@@ -12,37 +12,45 @@ export namespace schema {
   /** Schemas for the getScopes operation. */
   export namespace getScopes {
     /** A single issuable API-key scope. */
-    export const Entry = z
-      .object({
-        description: z
-          .string()
-          .check(
-            z.describe('Human-readable explanation of what the scope grants.'),
-            z.meta({ examples: ['Read webhook subscriptions.'] }),
-          ),
-        scope: z
-          .string()
-          .check(
-            z.describe(
-              'Scope identifier used in API-key grants and route policies. Zone templates carry a concrete chain id and access level in grants.',
+    export const Entry = OpenApi.component(
+      z
+        .object({
+          description: z
+            .string()
+            .check(
+              z.describe('Human-readable explanation of what the scope grants.'),
+              z.meta({ examples: ['Read webhook subscriptions.'] }),
             ),
-            z.meta({ examples: ['data:read'] }),
-          ),
-        selfServe: z
-          .boolean()
-          .check(
-            z.describe('Whether an eligible session may self-mint this scope.'),
-            z.meta({ examples: [true] }),
-          ),
-      })
-      .check(z.describe('A single issuable API-key scope.'))
+          scope: z
+            .string()
+            .check(
+              z.describe(
+                'Scope identifier used in API-key grants and route policies. Zone templates carry a concrete chain id and access level in grants.',
+              ),
+              z.meta({ examples: ['data:read'] }),
+            ),
+          selfServe: z
+            .boolean()
+            .check(
+              z.describe('Whether an eligible session may self-mint this scope.'),
+              z.meta({ examples: [true] }),
+            ),
+        })
+        .check(z.describe('A single issuable API-key scope.')),
+      'Scope',
+    )
 
     /** Response body for the scope catalog. */
-    export const Response = z
-      .object({
-        data: z.array(Entry).check(z.describe('Issuable API-key scopes.')),
-      })
-      .check(z.describe('Response body for the scope catalog.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Entry)
+            .check(z.describe('Issuable API-key scopes.'), z.meta({ examples: [[]] })),
+        })
+        .check(z.describe('Response body for the scope catalog.')),
+      'ScopeList',
+    )
   }
 }
 
@@ -59,6 +67,7 @@ export function scopes() {
       description: 'See which scopes can be granted to API keys.',
       operationId: 'getScopes',
       responses: OpenApi.responses({
+        errors: { 400: { codes: [], description: 'Malformed API key.' } },
         success: { description: 'Issuable scope catalog.', schema: schema.getScopes.Response },
       }),
       summary: 'List scopes',

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

@@ -124,6 +124,98 @@ const emptyUsage = {
 
 afterEach(() => vi.useRealTimers())
 
+test('publishes generator-ready OpenAPI contracts', async () => {
+  const spec = await (await createApp().request('/openapi.json')).json()
+  const requests = spec.paths['/v1/orgs/{orgId}/usage/requests'].get
+  const sponsorships = spec.paths['/v1/orgs/{orgId}/usage/sponsorships'].get
+
+  expect({
+    components: [
+      'RequestUsage',
+      'RequestUsageByKey',
+      'RequestUsageByRoute',
+      'RequestUsageByStatus',
+      'RequestUsageSeriesPoint',
+      'RequestUsageTotals',
+      'SponsorshipUsage',
+      'SponsorshipUsageBucket',
+    ].filter((name) => spec.components.schemas[name]),
+    requests: {
+      errors: {
+        400: requests.responses[400].content['application/json'].schema,
+        404: requests.responses[404].content['application/json'].schema,
+        501: requests.responses[501].content['application/json'].schema,
+      },
+      operationId: requests.operationId,
+      response: requests.responses[200].content['application/json'].schema,
+    },
+    sponsorships: {
+      errors: {
+        400: sponsorships.responses[400].content['application/json'].schema,
+        404: sponsorships.responses[404].content['application/json'].schema,
+      },
+      operationId: sponsorships.operationId,
+      response: sponsorships.responses[200].content['application/json'].schema,
+    },
+    timestamps: {
+      requestFrom: spec.components.schemas.RequestUsage.properties.from.format,
+      requestPoint: spec.components.schemas.RequestUsageSeriesPoint.properties.time.format,
+      requestTo: spec.components.schemas.RequestUsage.properties.to.format,
+      sponsorship: spec.components.schemas.SponsorshipUsageBucket.properties.timestamp.format,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "RequestUsage",
+        "RequestUsageByKey",
+        "RequestUsageByRoute",
+        "RequestUsageByStatus",
+        "RequestUsageSeriesPoint",
+        "RequestUsageTotals",
+        "SponsorshipUsage",
+        "SponsorshipUsageBucket",
+      ],
+      "requests": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidOrQueryInvalidError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+          "501": {
+            "$ref": "#/components/schemas/AnalyticsUnconfiguredError",
+          },
+        },
+        "operationId": "getRequestUsage",
+        "response": {
+          "$ref": "#/components/schemas/RequestUsage",
+        },
+      },
+      "sponsorships": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidOrQueryInvalidError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+        },
+        "operationId": "getSponsorshipUsage",
+        "response": {
+          "$ref": "#/components/schemas/SponsorshipUsage",
+        },
+      },
+      "timestamps": {
+        "requestFrom": "date-time",
+        "requestPoint": "date-time",
+        "requestTo": "date-time",
+        "sponsorship": "date-time",
+      },
+    }
+  `)
+})
+
 describe('GET /orgs/:orgId/usage/requests', () => {
   test('scopes to one project with environment-filtered attribution and legacy key ids', async () => {
     vi.useFakeTimers({ now: new Date('2026-02-01T00:00:00.000Z') })