tapimo 0.10.2 → 0.12.0

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

@@ -25,40 +25,55 @@ export namespace schema {
     )
 
   /** One organization: the top-level tenant that owns API keys. */
-  export const Organization = Schema.describe(
-    z.object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the organization was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque organization id (`org_…`).'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      name: z
-        .string()
-        .check(
-          z.describe('Human-readable organization name.'),
-          z.meta({ examples: ['Acme, Inc.'] }),
-        ),
-      role: z
-        .optional(z.enum(Memberships.roles))
-        .check(
-          z.describe("The caller's role; absent for API keys and the super admin."),
-          z.meta({ examples: ['owner'] }),
-        ),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the organization was last updated (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-    }),
-    'An organization: the top-level tenant that owns API keys.',
+  export const Organization = OpenApi.component(
+    Schema.describe(
+      z.object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the organization was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque organization id (`org_…`).'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        name: z
+          .string()
+          .check(
+            z.describe('Human-readable organization name.'),
+            z.meta({ examples: ['Acme, Inc.'] }),
+          ),
+        role: z
+          .optional(z.enum(Memberships.roles))
+          .check(
+            z.describe("The caller's role; absent for API keys and the super admin."),
+            z.meta({ examples: ['owner'] }),
+          ),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the organization was last updated (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+      }),
+      'An organization: the top-level tenant that owns API keys.',
+    ),
+    'Organization',
+  )
+
+  /** Request body creating an organization. */
+  export const CreateOrganizationRequest = OpenApi.component(
+    z.object({ name }).check(z.describe('Fields for creating an organization.')),
+    'CreateOrganizationRequest',
+  )
+
+  /** Request body updating an organization. */
+  export const UpdateOrganizationRequest = OpenApi.component(
+    z.object({ name }).check(z.describe('Fields for updating an organization.')),
+    'UpdateOrganizationRequest',
   )
 
   /** Path parameters addressing one organization. */
@@ -73,34 +88,35 @@ export namespace schema {
     })
     .check(z.describe('Path parameters for one organization.'))
 
-  /** Request body creating or renaming an organization. */
-  export const OrganizationBody = z
-    .object({ name })
-    .check(z.describe('Fields for creating or renaming an organization.'))
-
   /** Schemas for the deleteOrganization operation. */
   export namespace deleteOrganization {
     /** Confirmation that the organization was deleted. */
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the organization that was deleted.'),
-            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the organization was deleted.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the organization that was deleted.'),
+              z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the organization was deleted.')),
+      'DeleteOrganizationResponse',
+    )
   }
 
   /** Schemas for the listOrganizations operation. */
   export namespace listOrganizations {
     /** Non-paginated list of organizations. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Organization).check(z.describe('The organizations, newest first.')),
-      }),
-      'A non-paginated list of organizations.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z.array(Organization).check(z.describe('The organizations, newest first.')),
+        }),
+        'A non-paginated list of organizations.',
+      ),
+      'OrganizationList',
     )
   }
 }
@@ -116,6 +132,7 @@ export function orgs() {
       OpenApi.describeRoute({
         operationId: 'listOrganizations',
         responses: OpenApi.responses({
+          errors: { 400: { codes: [], description: 'Malformed API key.' } },
           success: {
             description: 'The organizations, newest first.',
             schema: schema.listOrganizations.Response,
@@ -154,13 +171,16 @@ export function orgs() {
     .post(
       '/v1/orgs',
       Auth.policy({ session: true }),
-      OpenApi.validate('json', schema.OrganizationBody, {
+      OpenApi.validate('json', schema.CreateOrganizationRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
       OpenApi.describeRoute({
         operationId: 'createOrganization',
         responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid'], description: 'Malformed API key or invalid body.' },
+          },
           success: {
             description: 'The created organization.',
             schema: schema.Organization,
@@ -218,7 +238,13 @@ export function orgs() {
       OpenApi.describeRoute({
         operationId: 'getOrganization',
         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.' },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+          },
           success: { description: 'One organization.', schema: schema.Organization },
         }),
         summary: 'Get organization',
@@ -250,14 +276,23 @@ export function orgs() {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.OrganizationBody, {
+      OpenApi.validate('json', schema.UpdateOrganizationRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
       OpenApi.describeRoute({
         operationId: 'updateOrganization',
         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, or invalid body.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
+          },
           success: { description: 'The updated organization.', schema: schema.Organization },
         }),
         summary: 'Update organization',
@@ -265,6 +300,8 @@ export function orgs() {
       }),
       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',
@@ -306,7 +343,11 @@ export function orgs() {
         operationId: 'deleteOrganization',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible organization was found for this id.',
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found for this id.',
+            },
             409: {
               codes: ['sponsorships_unreported'],
               description: 'Billable sponsorships are still awaiting settlement.',
@@ -323,6 +364,7 @@ export function orgs() {
       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/projects.test.ts

@@ -20,6 +20,189 @@ function createApp() {
   return TestApp.create({ session: { wallet: { origin } } })
 }
 
+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}/projects']
+  const detail = spec.paths['/v1/orgs/{orgId}/projects/{projectId}']
+
+  expect({
+    components: [
+      'CreateProjectRequest',
+      'DeleteProjectResponse',
+      'Project',
+      'ProjectList',
+      'UpdateProjectRequest',
+    ].filter((name) => spec.components.schemas[name]),
+    create: {
+      errors: {
+        400: collection.post.responses[400].content['application/json'].schema,
+        401: collection.post.responses[401].content['application/json'].schema,
+        403: collection.post.responses[403].content['application/json'].schema,
+        404: collection.post.responses[404].content['application/json'].schema,
+        502: collection.post.responses[502].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: {
+      operationId: detail.delete.operationId,
+      response: detail.delete.responses[200].content['application/json'].schema,
+    },
+    errorComponents: {
+      detail: {
+        reference:
+          spec.components.schemas.ApiKeyMalformedOrParamInvalidError.properties.error.properties
+            .details.items,
+        required: spec.components.schemas.ErrorDetail.required,
+      },
+      invalidBodyOrParameters:
+        spec.components.schemas.ApiKeyMalformedOrBodyInvalidOrParamInvalidError.properties.error
+          .properties.code.enum,
+      invalidParameters:
+        spec.components.schemas.ApiKeyMalformedOrParamInvalidError.properties.error.properties.code
+          .enum,
+      forbidden: spec.components.schemas.ForbiddenError.properties.error.properties.code.enum,
+      organizationNotFound:
+        spec.components.schemas.OrganizationNotFoundError.properties.error.properties.code.enum,
+      organizationOrProjectNotFound:
+        spec.components.schemas.OrganizationNotFoundOrProjectNotFoundError.properties.error
+          .properties.code.enum,
+    },
+    list: {
+      operationId: collection.get.operationId,
+      response: collection.get.responses[200].content['application/json'].schema,
+    },
+    sharedResponses: {
+      internal: spec.components.responses.InternalError.content['application/json'].schema,
+      rateLimit: spec.components.responses.RateLimited.content['application/json'].schema,
+    },
+    timestamps: {
+      createdAt: spec.components.schemas.Project.properties.createdAt.format,
+      updatedAt: spec.components.schemas.Project.properties.updatedAt.format,
+    },
+    update: {
+      operationId: detail.patch.operationId,
+      request: detail.patch.requestBody.content['application/json'].schema,
+      response: detail.patch.responses[200].content['application/json'].schema,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "CreateProjectRequest",
+        "DeleteProjectResponse",
+        "Project",
+        "ProjectList",
+        "UpdateProjectRequest",
+      ],
+      "create": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
+          },
+          "401": {
+            "$ref": "#/components/schemas/AuthenticationError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+          "502": {
+            "$ref": "#/components/schemas/UpstreamError",
+          },
+        },
+        "operationId": "createProject",
+        "request": {
+          "$ref": "#/components/schemas/CreateProjectRequest",
+        },
+        "response": {
+          "$ref": "#/components/schemas/Project",
+        },
+      },
+      "delete": {
+        "operationId": "deleteProject",
+        "response": {
+          "$ref": "#/components/schemas/DeleteProjectResponse",
+        },
+      },
+      "errorComponents": {
+        "detail": {
+          "reference": {
+            "$ref": "#/components/schemas/ErrorDetail",
+          },
+          "required": [
+            "message",
+          ],
+        },
+        "forbidden": [
+          "api_key_forbidden",
+          "api_key_ip_forbidden",
+          "forbidden",
+        ],
+        "invalidBodyOrParameters": [
+          "api_key_malformed",
+          "body_invalid",
+          "param_invalid",
+        ],
+        "invalidParameters": [
+          "api_key_malformed",
+          "param_invalid",
+        ],
+        "organizationNotFound": [
+          "organization_not_found",
+        ],
+        "organizationOrProjectNotFound": [
+          "organization_not_found",
+          "project_not_found",
+        ],
+      },
+      "list": {
+        "operationId": "listProjects",
+        "response": {
+          "$ref": "#/components/schemas/ProjectList",
+        },
+      },
+      "sharedResponses": {
+        "internal": {
+          "$ref": "#/components/schemas/InternalError",
+        },
+        "rateLimit": {
+          "$ref": "#/components/schemas/RateLimitError",
+        },
+      },
+      "timestamps": {
+        "createdAt": "date-time",
+        "updatedAt": "date-time",
+      },
+      "update": {
+        "operationId": "updateProject",
+        "request": {
+          "$ref": "#/components/schemas/UpdateProjectRequest",
+        },
+        "response": {
+          "$ref": "#/components/schemas/Project",
+        },
+      },
+    }
+  `)
+
+  expect(detail.patch.responses[400].content['application/json'].schema).toEqual(
+    collection.post.responses[400].content['application/json'].schema,
+  )
+  expect(collection.get.responses[404].content['application/json'].schema).toEqual(
+    collection.post.responses[404].content['application/json'].schema,
+  )
+  expect(detail.patch.responses[404].content['application/json'].schema).toEqual(
+    detail.get.responses[404].content['application/json'].schema,
+  )
+  expect(detail.delete.responses[404].content['application/json'].schema).toEqual(
+    detail.get.responses[404].content['application/json'].schema,
+  )
+})
+
 /** Signs in a fresh scripted account; returns its session cookie. */
 async function session(app: TestApp.signIn.App) {
   const account = privateKeyToAccount(generatePrivateKey())