tapimo 0.10.2 → 0.12.0

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

@@ -23,44 +23,50 @@ export namespace schema {
     .check(z.describe('Role granted when the invitation is accepted.'), z.meta({ examples: ['member'] })) // prettier-ignore
 
   /** One pending invitation. */
-  export const Invitation = Schema.describe(
-    z.object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the invitation was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      email: z
-        .string()
-        .check(z.describe('Invitee email (lowercase).'), z.meta({ examples: ['dev@example.com'] })),
-      expiresAt: z
-        .string()
-        .check(
-          z.describe('When the invitation expires (ISO 8601).'),
-          z.meta({ examples: ['2026-01-08T00:00:00.000Z'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque invitation id (`inv_…`).'),
-          z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      invitedBy: z
-        .string()
-        .check(
-          z.describe('User or API key id that created the invitation.'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      orgId: z
-        .string()
-        .check(
-          z.describe('Organization id (`org_…`) the invitation joins.'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      role,
-    }),
-    'One pending invitation.',
+  export const Invitation = OpenApi.component(
+    Schema.describe(
+      z.object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the invitation was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        email: z
+          .email()
+          .check(
+            z.describe('Invitee email (lowercase).'),
+            z.meta({ examples: ['dev@example.com'] }),
+          ),
+        expiresAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the invitation expires (ISO 8601).'),
+            z.meta({ examples: ['2026-01-08T00:00:00.000Z'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque invitation id (`inv_…`).'),
+            z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        invitedBy: z
+          .string()
+          .check(
+            z.describe('User or API key id that created the invitation.'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        orgId: z
+          .string()
+          .check(
+            z.describe('Organization id (`org_…`) the invitation joins.'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        role,
+      }),
+      'One pending invitation.',
+    ),
+    'Invitation',
   )
 
   /** Path parameters addressing an organization's invitation collection. */
@@ -106,100 +112,128 @@ export namespace schema {
     .check(z.describe("Path parameters for one of the caller's invitations."))
 
   /** Request body creating an invitation. */
-  export const InvitationBody = z
-    .object({
-      email: z
-        .email()
-        .check(z.describe('Invitee email.'), z.meta({ examples: ['dev@example.com'] })),
-      role,
-    })
-    .check(z.describe('Fields for creating an invitation.'))
+  export const CreateInvitationRequest = OpenApi.component(
+    z
+      .object({
+        email: z
+          .email()
+          .check(z.describe('Invitee email.'), z.meta({ examples: ['dev@example.com'] })),
+        role,
+      })
+      .check(z.describe('Fields for creating an invitation.')),
+    'CreateInvitationRequest',
+  )
 
   /** Schemas for the listInvitations / listMyInvitations operations. */
   export namespace listInvitations {
     /** Non-paginated list of pending invitations. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Invitation).check(z.describe('Pending invitations, newest first.')),
-      }),
-      'A non-paginated list of pending invitations.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z
+            .array(Invitation)
+            .check(z.describe('Pending invitations, newest first.'), z.meta({ examples: [[]] })),
+        }),
+        'A non-paginated list of pending invitations.',
+      ),
+      'InvitationList',
     )
   }
 
   /** Schemas for the listMyInvitations operation. */
   export namespace listMyInvitations {
     /** A pending invitation addressed to the caller, with the inviting org's name. */
-    export const Item = z.extend(Invitation, {
-      orgName: z
-        .string()
-        .check(
-          z.describe('Human-readable name of the inviting organization.'),
-          z.meta({ examples: ['Acme, Inc.'] }),
-        ),
-    })
+    export const Item = OpenApi.component(
+      Schema.describe(
+        z.extend(Invitation, {
+          orgName: z
+            .string()
+            .check(
+              z.describe('Human-readable name of the inviting organization.'),
+              z.meta({ examples: ['Acme, Inc.'] }),
+            ),
+        }),
+        "One pending invitation addressed to the caller, with the inviting organization's name.",
+      ),
+      'MyInvitation',
+    )
 
     /** Non-paginated list of the caller's pending invitations. */
-    export const Response = Schema.describe(
-      z.object({
-        data: z.array(Item).check(z.describe('Pending invitations, newest first.')),
-      }),
-      "A non-paginated list of the caller's pending invitations.",
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          data: z
+            .array(Item)
+            .check(z.describe('Pending invitations, newest first.'), z.meta({ examples: [[]] })),
+        }),
+        "A non-paginated list of the caller's pending invitations.",
+      ),
+      'MyInvitationList',
     )
   }
 
   /** Schemas for the acceptInvitation operation. */
   export namespace acceptInvitation {
     /** The membership granted by accepting. */
-    export const Response = Schema.describe(
-      z.object({
-        orgId: z
-          .string()
-          .check(
-            z.describe('Organization id (`org_…`) joined.'),
-            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-        role: z
-          .enum(Memberships.roles)
-          .check(z.describe('Granted role.'), z.meta({ examples: ['member'] })),
-        userId: z
-          .string()
-          .check(
-            z.describe('Member user id (`usr_…`).'),
-            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      }),
-      'The membership granted by accepting.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.object({
+          orgId: z
+            .string()
+            .check(
+              z.describe('Organization id (`org_…`) joined.'),
+              z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+          role: z
+            .enum(Memberships.roles)
+            .check(z.describe('Granted role.'), z.meta({ examples: ['member'] })),
+          userId: z
+            .string()
+            .check(
+              z.describe('Member user id (`usr_…`).'),
+              z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        }),
+        'The membership granted by accepting.',
+      ),
+      'AcceptInvitationResponse',
     )
   }
 
   /** Schemas for the declineInvitation operation. */
   export namespace declineInvitation {
     /** Confirmation that the invitation was declined. */
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the invitation that was declined.'),
-            z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the invitation was declined.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the invitation that was declined.'),
+              z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the invitation was declined.')),
+      'DeclineInvitationResponse',
+    )
   }
 
   /** Schemas for the revokeInvitation operation. */
   export namespace revokeInvitation {
     /** Confirmation that the invitation was revoked. */
-    export const Response = z
-      .object({
-        id: z
-          .string()
-          .check(
-            z.describe('ID of the invitation that was revoked.'),
-            z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-          ),
-      })
-      .check(z.describe('Confirmation that the invitation was revoked.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          id: z
+            .string()
+            .check(
+              z.describe('ID of the invitation that was revoked.'),
+              z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+            ),
+        })
+        .check(z.describe('Confirmation that the invitation was revoked.')),
+      'RevokeInvitationResponse',
+    )
   }
 }
 
@@ -218,7 +252,7 @@ export function invitations() {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
-      OpenApi.validate('json', schema.InvitationBody, {
+      OpenApi.validate('json', schema.CreateInvitationRequest, {
         code: 'body_invalid',
         message: 'Check the request body and try again.',
       }),
@@ -226,7 +260,16 @@ export function invitations() {
         description: 'Invite an email to the organization with a role. The invitee accepts after signing in with that verified email.', // prettier-ignore
         operationId: 'createInvitation',
         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 created invitation.', schema: schema.Invitation },
         }),
         summary: 'Create invitation',
@@ -235,6 +278,7 @@ export function invitations() {
       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',
@@ -290,7 +334,13 @@ export function invitations() {
       OpenApi.describeRoute({
         operationId: 'listInvitations',
         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: 'Pending invitations, newest first.',
             schema: schema.listInvitations.Response,
@@ -302,6 +352,7 @@ export function invitations() {
       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',
@@ -333,7 +384,13 @@ export function invitations() {
       OpenApi.describeRoute({
         operationId: 'revokeInvitation',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible pending invitation was found for this id.' },
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['invitation_not_found', 'organization_not_found'],
+              description: 'No accessible organization or pending invitation was found.',
+            },
+          },
           success: {
             description: 'Confirmation that the invitation was revoked.',
             schema: schema.revokeInvitation.Response,
@@ -345,6 +402,7 @@ export function invitations() {
       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',
@@ -375,6 +433,7 @@ export function invitations() {
         description: "Pending invitations addressed to the session's verified email.",
         operationId: 'listMyInvitations',
         responses: OpenApi.responses({
+          errors: { 400: { codes: [], description: 'Malformed API key.' } },
           success: {
             description: 'Pending invitations, newest first.',
             schema: schema.listMyInvitations.Response,
@@ -420,7 +479,16 @@ export function invitations() {
         description: "Accept an invitation addressed to the session's verified email, joining the organization with the invited role.", // prettier-ignore
         operationId: 'acceptInvitation',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible pending invitation was found for this id.' },
+          errors: {
+            400: {
+              codes: ['param_invalid'],
+              description: 'Malformed API key or invalid path.',
+            },
+            404: {
+              codes: ['invitation_not_found'],
+              description: 'No accessible pending invitation was found for this id.',
+            },
+          },
           success: {
             description: 'The membership granted by accepting.',
             schema: schema.acceptInvitation.Response,
@@ -475,7 +543,16 @@ export function invitations() {
         description: "Decline an invitation addressed to the session's verified email. Declining settles the invitation; it can no longer be accepted.", // prettier-ignore
         operationId: 'declineInvitation',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible pending invitation was found for this id.' },
+          errors: {
+            400: {
+              codes: ['param_invalid'],
+              description: 'Malformed API key or invalid path.',
+            },
+            404: {
+              codes: ['invitation_not_found'],
+              description: 'No accessible pending invitation was found for this id.',
+            },
+          },
           success: {
             description: 'Confirmation that the invitation was declined.',
             schema: schema.declineInvitation.Response,