tapimo 0.11.0 → 0.12.0

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

@@ -21,6 +21,55 @@ function createApp() {
   })
 }
 
+test('publishes a generator-ready OpenAPI contract', async () => {
+  const spec = await (await createApp().request('/openapi.json')).json()
+  const operation = spec.paths['/v1/me'].get
+
+  expect(spec.components.schemas.User.properties.email.examples).toEqual(['dev@example.com'])
+
+  expect({
+    component: spec.components.schemas.User ? 'User' : undefined,
+    errors: {
+      400: operation.responses[400].content['application/json'].schema,
+      403: operation.responses[403].content['application/json'].schema,
+      404: operation.responses[404].content['application/json'].schema,
+    },
+    formats: {
+      address: spec.components.schemas.User.properties.address.pattern,
+      createdAt: spec.components.schemas.User.properties.createdAt.format,
+      email: spec.components.schemas.User.properties.email.format,
+      updatedAt: spec.components.schemas.User.properties.updatedAt.format,
+    },
+    operationId: operation.operationId,
+    response: operation.responses[200].content['application/json'].schema,
+  }).toMatchInlineSnapshot(`
+    {
+      "component": "User",
+      "errors": {
+        "400": {
+          "$ref": "#/components/schemas/ApiKeyMalformedError",
+        },
+        "403": {
+          "$ref": "#/components/schemas/ForbiddenError",
+        },
+        "404": {
+          "$ref": "#/components/schemas/UserNotFoundError",
+        },
+      },
+      "formats": {
+        "address": "^0x[0-9a-fA-F]{40}$",
+        "createdAt": "date-time",
+        "email": "email",
+        "updatedAt": "date-time",
+      },
+      "operationId": "getMe",
+      "response": {
+        "$ref": "#/components/schemas/User",
+      },
+    }
+  `)
+})
+
 describe('SIWE verification', () => {
   test('surfaces configured RPC failures as dependency errors', async () => {
     const account = Account.fromHeadlessWebAuthn(P256.randomPrivateKey(), {

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

@@ -12,37 +12,43 @@ import * as Users from '../../../db/tables/users.js'
 /** Zod schemas owned by the current-user resource. */
 export namespace schema {
   /** The signed-in developer. */
-  export const User = Schema.describe(
-    z.object({
-      address: z
-        .optional(z.string())
-        .check(
-          z.describe('Wallet address bound to this user, when wallet sign-in established it.'),
-          z.meta({ examples: ['0x0000000000000000000000000000000000000001'] }),
-        ),
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the user was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      email: z
-        .optional(z.string())
-        .check(z.describe('Verified email from the wallet identity token, when present.')),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque user id (`usr_…`).'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the user was last updated (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-    }),
-    'The signed-in developer.',
+  export const User = OpenApi.component(
+    Schema.describe(
+      z.object({
+        address: z
+          .optional(z.templateLiteral(['0x', z.string().check(z.regex(/^[0-9a-fA-F]{40}$/))]))
+          .check(
+            z.describe('Wallet address bound to this user, when wallet sign-in established it.'),
+            z.meta({ examples: ['0x0000000000000000000000000000000000000001'] }),
+          ),
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the user was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        email: z
+          .optional(z.email())
+          .check(
+            z.describe('Verified email from the wallet identity token, when present.'),
+            z.meta({ examples: ['dev@example.com'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque user id (`usr_…`).'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the user was last updated (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+      }),
+      'The signed-in developer.',
+    ),
+    'User',
   )
 }
 
@@ -58,8 +64,12 @@ export function me() {
       operationId: 'getMe',
       responses: OpenApi.responses({
         errors: {
+          400: { codes: [], description: 'Malformed API key.' },
           403: 'The caller is not a signed-in user.',
-          404: 'No user exists for this session.',
+          404: {
+            codes: ['user_not_found'],
+            description: 'No user exists for this session.',
+          },
         },
         success: { description: 'The authenticated user.', schema: schema.User },
       }),

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

@@ -44,6 +44,129 @@ async function team(
   return { member, org, owner }
 }
 
+test('publishes generator-ready OpenAPI contracts', async () => {
+  const spec = await (await createApp().request('/openapi.json')).json()
+  const collection = spec.paths['/v1/orgs/{orgId}/members']
+  const detail = spec.paths['/v1/orgs/{orgId}/members/{userId}']
+
+  expect(spec.components.schemas.MemberList.properties.data.examples).toEqual([[]])
+
+  expect({
+    components: ['Member', 'MemberList', 'RemoveMemberResponse', 'UpdateMemberRequest'].filter(
+      (name) => spec.components.schemas[name],
+    ),
+    list: {
+      errors: {
+        400: collection.get.responses[400].content['application/json'].schema,
+        403: collection.get.responses[403].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,
+    },
+    memberFormats: {
+      address: spec.components.schemas.Member.properties.address.pattern,
+      createdAt: spec.components.schemas.Member.properties.createdAt.format,
+      email: spec.components.schemas.Member.properties.email.format,
+    },
+    remove: {
+      errors: {
+        400: detail.delete.responses[400].content['application/json'].schema,
+        403: detail.delete.responses[403].content['application/json'].schema,
+        404: detail.delete.responses[404].content['application/json'].schema,
+        409: detail.delete.responses[409].content['application/json'].schema,
+      },
+      operationId: detail.delete.operationId,
+      response: detail.delete.responses[200].content['application/json'].schema,
+    },
+    update: {
+      errors: {
+        400: detail.patch.responses[400].content['application/json'].schema,
+        403: detail.patch.responses[403].content['application/json'].schema,
+        404: detail.patch.responses[404].content['application/json'].schema,
+        409: detail.patch.responses[409].content['application/json'].schema,
+      },
+      operationId: detail.patch.operationId,
+      request: detail.patch.requestBody.content['application/json'].schema,
+      response: detail.patch.responses[200].content['application/json'].schema,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "Member",
+        "MemberList",
+        "RemoveMemberResponse",
+        "UpdateMemberRequest",
+      ],
+      "list": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+        },
+        "operationId": "listMembers",
+        "response": {
+          "$ref": "#/components/schemas/MemberList",
+        },
+      },
+      "memberFormats": {
+        "address": "^0x[0-9a-fA-F]{40}$",
+        "createdAt": "date-time",
+        "email": "email",
+      },
+      "remove": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/MemberNotFoundOrOrganizationNotFoundError",
+          },
+          "409": {
+            "$ref": "#/components/schemas/LastOwnerError",
+          },
+        },
+        "operationId": "removeMember",
+        "response": {
+          "$ref": "#/components/schemas/RemoveMemberResponse",
+        },
+      },
+      "update": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/MemberNotFoundOrOrganizationNotFoundError",
+          },
+          "409": {
+            "$ref": "#/components/schemas/LastOwnerError",
+          },
+        },
+        "operationId": "updateMember",
+        "request": {
+          "$ref": "#/components/schemas/UpdateMemberRequest",
+        },
+        "response": {
+          "$ref": "#/components/schemas/Member",
+        },
+      },
+    }
+  `)
+})
+
 describe('members', () => {
   test('lists the team with roles and identity', async () => {
     const db = TestApp.database()
@@ -140,7 +263,7 @@ describe('members', () => {
       app.request(`/v1/orgs/${org.id}/members/${owner.userId}`, json('PATCH', second.cookie, { role: 'member' })), // prettier-ignore
       app.request(`/v1/orgs/${org.id}/members/${second.userId}`, json('PATCH', owner.cookie, { role: 'member' })), // prettier-ignore
     ])
-    expect([a.status, b.status].sort()).toEqual([200, 409])
+    expect([a.status, b.status].sort((left, right) => left - right)).toEqual([200, 409])
     const owners = (await Memberships.listByOrg(db, org.id)).filter(({ role }) => role === 'owner')
     expect(owners).toHaveLength(1)
   })

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

@@ -18,35 +18,38 @@ export namespace schema {
     .check(z.describe('Membership role.'), z.meta({ examples: ['admin'] }))
 
   /** One organization member: the membership plus the member's identity. */
-  export const Member = Schema.describe(
-    z.object({
-      address: z
-        .optional(z.string())
-        .check(
-          z.describe("The member's wallet address, when wallet sign-in established it."),
-          z.meta({ examples: ['0x20f414b3cbcf1fd8e8f5e1c1c2e3d4a5b6c7d8e9'] }),
-        ),
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the member joined (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      email: z
-        .optional(z.string())
-        .check(
-          z.describe("The member's verified email, when known."),
-          z.meta({ examples: ['dev@example.com'] }),
-        ),
-      role: Role,
-      userId: z
-        .string()
-        .check(
-          z.describe('Member user id (`usr_…`).'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-    }),
-    "One organization member: the membership plus the member's identity.",
+  export const Member = OpenApi.component(
+    Schema.describe(
+      z.object({
+        address: z
+          .optional(z.templateLiteral(['0x', z.string().check(z.regex(/^[0-9a-fA-F]{40}$/))]))
+          .check(
+            z.describe("The member's wallet address, when wallet sign-in established it."),
+            z.meta({ examples: ['0x20f414b3cbcf1fd8e8f5e1c1c2e3d4a5b6c7d8e9'] }),
+          ),
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the member joined (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        email: z
+          .optional(z.email())
+          .check(
+            z.describe("The member's verified email, when known."),
+            z.meta({ examples: ['dev@example.com'] }),
+          ),
+        role: Role,
+        userId: z
+          .string()
+          .check(
+            z.describe('Member user id (`usr_…`).'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      }),
+      "One organization member: the membership plus the member's identity.",
+    ),
+    'Member',
   )
 
   /** Path parameters addressing an organization's member collection. */
@@ -80,34 +83,43 @@ export namespace schema {
     .check(z.describe('Path parameters for one member.'))
 
   /** Request body changing a member's role. */
-  export const MemberBody = z
-    .object({ role: Role })
-    .check(z.describe("Fields for changing a member's role."))
+  export const UpdateMemberRequest = OpenApi.component(
+    z.object({ role: Role }).check(z.describe("Fields for changing a member's role.")),
+    'UpdateMemberRequest',
+  )
 
   /** Schemas for the listMembers operation. */
   export namespace listMembers {
     /** Non-paginated list of an organization's members. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Member).check(z.describe('The members, oldest first.')),
-      }),
-      "A non-paginated list of an organization's members.",
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z
+            .array(Member)
+            .check(z.describe('The members, oldest first.'), z.meta({ examples: [[]] })),
+        }),
+        "A non-paginated list of an organization's members.",
+      ),
+      'MemberList',
     )
   }
 
   /** Schemas for the removeMember operation. */
   export namespace removeMember {
     /** Confirmation that the member was removed. */
-    export const Response = z
-      .object({
-        userId: z
-          .string()
-          .check(
-            z.describe('User id (`usr_…`) of the removed member.'),
-            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the member was removed.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          userId: z
+            .string()
+            .check(
+              z.describe('User id (`usr_…`) of the removed member.'),
+              z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the member was removed.')),
+      'RemoveMemberResponse',
+    )
   }
 }
 
@@ -129,7 +141,13 @@ export function members() {
       OpenApi.describeRoute({
         operationId: 'listMembers',
         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: 'The members, oldest first.',
             schema: schema.listMembers.Response,
@@ -169,7 +187,7 @@ export function members() {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.MemberBody, {
+      OpenApi.validate('json', schema.UpdateMemberRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
@@ -178,7 +196,14 @@ export function members() {
         operationId: 'updateMember',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible member was found for this id.',
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path, or invalid body.',
+            },
+            404: {
+              codes: ['member_not_found', 'organization_not_found'],
+              description: 'No accessible organization or member was found for this id.',
+            },
             409: {
               codes: ['last_owner'],
               description: 'The organization would be left without an owner.',
@@ -192,6 +217,7 @@ export function members() {
       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',
@@ -237,7 +263,11 @@ export function members() {
         operationId: 'removeMember',
         responses: OpenApi.responses({
           errors: {
-            404: 'No accessible member was found for this id.',
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['member_not_found', 'organization_not_found'],
+              description: 'No accessible organization or member was found for this id.',
+            },
             409: {
               codes: ['last_owner'],
               description: 'The organization would be left without an owner.',

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

@@ -79,7 +79,183 @@ async function session(app: TestApp.signIn.App) {
   return cookie!
 }
 
+test('publishes generator-ready OpenAPI contracts', async () => {
+  const spec = await (await createApp().request('/openapi.json')).json()
+  const collection = spec.paths['/v1/orgs']
+  const detail = spec.paths['/v1/orgs/{orgId}']
+
+  expect({
+    components: [
+      'CreateOrganizationRequest',
+      'DeleteOrganizationResponse',
+      'Organization',
+      'OrganizationList',
+      'UpdateOrganizationRequest',
+    ].filter((name) => spec.components.schemas[name]),
+    create: {
+      errors: {
+        400: collection.post.responses[400].content['application/json'].schema,
+        403: collection.post.responses[403].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.delete.responses[400].content['application/json'].schema,
+        403: detail.delete.responses[403].content['application/json'].schema,
+        404: detail.delete.responses[404].content['application/json'].schema,
+        409: detail.delete.responses[409].content['application/json'].schema,
+      },
+      operationId: detail.delete.operationId,
+      response: detail.delete.responses[200].content['application/json'].schema,
+    },
+    get: {
+      errors: {
+        400: detail.get.responses[400].content['application/json'].schema,
+        403: detail.get.responses[403].content['application/json'].schema,
+        404: detail.get.responses[404].content['application/json'].schema,
+      },
+      operationId: detail.get.operationId,
+      response: detail.get.responses[200].content['application/json'].schema,
+    },
+    list: {
+      errors: {
+        400: collection.get.responses[400].content['application/json'].schema,
+        403: collection.get.responses[403].content['application/json'].schema,
+      },
+      operationId: collection.get.operationId,
+      response: collection.get.responses[200].content['application/json'].schema,
+    },
+    timestamps: {
+      createdAt: spec.components.schemas.Organization.properties.createdAt.format,
+      updatedAt: spec.components.schemas.Organization.properties.updatedAt.format,
+    },
+    update: {
+      errors: {
+        400: detail.patch.responses[400].content['application/json'].schema,
+        403: detail.patch.responses[403].content['application/json'].schema,
+        404: detail.patch.responses[404].content['application/json'].schema,
+      },
+      operationId: detail.patch.operationId,
+      request: detail.patch.requestBody.content['application/json'].schema,
+      response: detail.patch.responses[200].content['application/json'].schema,
+    },
+  }).toMatchInlineSnapshot(`
+    {
+      "components": [
+        "CreateOrganizationRequest",
+        "DeleteOrganizationResponse",
+        "Organization",
+        "OrganizationList",
+        "UpdateOrganizationRequest",
+      ],
+      "create": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+        },
+        "operationId": "createOrganization",
+        "request": {
+          "$ref": "#/components/schemas/CreateOrganizationRequest",
+        },
+        "response": {
+          "$ref": "#/components/schemas/Organization",
+        },
+      },
+      "delete": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+          "409": {
+            "$ref": "#/components/schemas/SponsorshipsUnreportedError",
+          },
+        },
+        "operationId": "deleteOrganization",
+        "response": {
+          "$ref": "#/components/schemas/DeleteOrganizationResponse",
+        },
+      },
+      "get": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+        },
+        "operationId": "getOrganization",
+        "response": {
+          "$ref": "#/components/schemas/Organization",
+        },
+      },
+      "list": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+        },
+        "operationId": "listOrganizations",
+        "response": {
+          "$ref": "#/components/schemas/OrganizationList",
+        },
+      },
+      "timestamps": {
+        "createdAt": "date-time",
+        "updatedAt": "date-time",
+      },
+      "update": {
+        "errors": {
+          "400": {
+            "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
+          },
+          "403": {
+            "$ref": "#/components/schemas/ForbiddenError",
+          },
+          "404": {
+            "$ref": "#/components/schemas/OrganizationNotFoundError",
+          },
+        },
+        "operationId": "updateOrganization",
+        "request": {
+          "$ref": "#/components/schemas/UpdateOrganizationRequest",
+        },
+        "response": {
+          "$ref": "#/components/schemas/Organization",
+        },
+      },
+    }
+  `)
+})
+
 describe('GET /orgs', () => {
+  test('rejects malformed API key credentials', async () => {
+    const response = await createApp().request('/v1/orgs', {
+      headers: { authorization: 'Basic wrong' },
+    })
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'api_key_malformed' } })
+  })
+
   test('lists all organizations for the super admin', async () => {
     const response = await (await seeded()).request('/v1/orgs', as(secret))
     expect(response.status).toBe(200)