tapimo 0.10.2 → 0.12.0

package/src/apps/management/routes/invite-links.ts

@@ -55,217 +55,244 @@ export namespace schema {
     .check(z.describe('Role granted by the link.'), z.meta({ examples: ['member'] }))
 
   /** Management representation, including the recopyable bearer id. */
-  export const InviteLink = Schema.describe(
-    z.object({
-      allowedEmailDomains,
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the link was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      createdBy: z
-        .string()
-        .check(
-          z.describe('User id that created the link.'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      enabled: z
-        .boolean()
-        .check(z.describe('Whether the link is enabled.'), z.meta({ examples: [true] })),
-      expiresAt: nullableExpiry,
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque invite-link resource id (`iln_…`).'),
-          z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      lastUsedAt: z
-        .nullable(z.string())
-        .check(
-          z.describe('When the link last created a membership, or null.'),
-          z.meta({ examples: ['2026-01-02T00:00:00.000Z', null] }),
-        ),
-      maxUses: nullableUses,
-      name: z
-        .string()
-        .check(z.describe('Human-readable link name.'), z.meta({ examples: ['Community'] })),
-      orgId: z
-        .string()
-        .check(
-          z.describe('Organization id (`org_…`) the link joins.'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      role,
-      status: z
-        .enum(['active', 'deleted', 'disabled', 'exhausted', 'expired'])
-        .check(z.describe('Current link availability.'), z.meta({ examples: ['active'] })),
-      token: z
-        .string()
-        .check(
-          z.describe('Opaque bearer token embedded in the recipient URL (`lnk_…`).'),
-          z.meta({ examples: ['lnk_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the link was last changed (ISO 8601).'),
-          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-        ),
-      useCount: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Memberships created through the link.'),
-          z.meta({ examples: [3] }),
-        ),
-    }),
-    'A reusable organization invite link.',
+  export const InviteLink = OpenApi.component(
+    Schema.describe(
+      z.object({
+        allowedEmailDomains,
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the link was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        createdBy: z
+          .string()
+          .check(
+            z.describe('User id that created the link.'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        enabled: z
+          .boolean()
+          .check(z.describe('Whether the link is enabled.'), z.meta({ examples: [true] })),
+        expiresAt: nullableExpiry,
+        id: z
+          .string()
+          .check(
+            z.describe('Opaque invite-link resource id (`iln_…`).'),
+            z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        lastUsedAt: z
+          .nullable(z.iso.datetime())
+          .check(
+            z.describe('When the link last created a membership, or null.'),
+            z.meta({ examples: ['2026-01-02T00:00:00.000Z', null] }),
+          ),
+        maxUses: nullableUses,
+        name: z
+          .string()
+          .check(z.describe('Human-readable link name.'), z.meta({ examples: ['Community'] })),
+        orgId: z
+          .string()
+          .check(
+            z.describe('Organization id (`org_…`) the link joins.'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        role,
+        status: z
+          .enum(['active', 'deleted', 'disabled', 'exhausted', 'expired'])
+          .check(z.describe('Current link availability.'), z.meta({ examples: ['active'] })),
+        token: z
+          .string()
+          .check(
+            z.describe('Opaque bearer token embedded in the recipient URL (`lnk_…`).'),
+            z.meta({ examples: ['lnk_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the link was last changed (ISO 8601).'),
+            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+          ),
+        useCount: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Memberships created through the link.'),
+            z.meta({ examples: [3] }),
+          ),
+      }),
+      'A reusable organization invite link.',
+    ),
+    'InviteLink',
   )
 
   /** Redemption audit representation (never includes a bearer URL). */
-  export const Redemption = Schema.describe(
-    z.object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the membership was created (ISO 8601).'),
-          z.meta({ examples: ['2026-01-02T00:00:00.000Z'] }),
-        ),
-      email: z
-        .string()
-        .check(
-          z.describe('Verified email used for redemption.'),
-          z.meta({ examples: ['dev@example.com'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe('Opaque redemption id (`ilr_…`).'),
-          z.meta({ examples: ['ilr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      inviteLinkId: z
-        .string()
-        .check(
-          z.describe('Invite-link resource id used for redemption.'),
-          z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      inviteLinkName: z
-        .string()
-        .check(z.describe('Link name at redemption time.'), z.meta({ examples: ['Community'] })),
-      orgId: z
-        .string()
-        .check(
-          z.describe('Organization id joined through the link.'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      userId: z
-        .string()
-        .check(
-          z.describe('User id that redeemed the link.'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-    }),
-    'An invite-link redemption audit record.',
-  )
-
-  /** Create body. */
-  export const CreateBody = z
-    .object({
-      allowedEmailDomains: z.optional(allowedEmailDomains),
-      expiresAt: z.optional(nullableExpiry),
-      maxUses: z.optional(nullableUses),
-      name: z.optional(
-        z
+  export const Redemption = OpenApi.component(
+    Schema.describe(
+      z.object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the membership was created (ISO 8601).'),
+            z.meta({ examples: ['2026-01-02T00:00:00.000Z'] }),
+          ),
+        email: z
+          .email()
+          .check(
+            z.describe('Verified email used for redemption.'),
+            z.meta({ examples: ['dev@example.com'] }),
+          ),
+        id: z
           .string()
           .check(
-            z.trim(),
-            z.minLength(1),
-            z.maxLength(100),
-            z.describe('Human-readable link name.'),
-            z.meta({ examples: ['Community'] }),
+            z.describe('Opaque redemption id (`ilr_…`).'),
+            z.meta({ examples: ['ilr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
           ),
-      ),
-      role: z
-        ._default(role, 'member')
-        .check(z.describe('Role granted by the link.'), z.meta({ examples: ['member'] })),
-    })
-    .check(z.describe('Fields for creating an invite link.'))
+        inviteLinkId: z
+          .string()
+          .check(
+            z.describe('Invite-link resource id used for redemption.'),
+            z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        inviteLinkName: z
+          .string()
+          .check(z.describe('Link name at redemption time.'), z.meta({ examples: ['Community'] })),
+        orgId: z
+          .string()
+          .check(
+            z.describe('Organization id joined through the link.'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        userId: z
+          .string()
+          .check(
+            z.describe('User id that redeemed the link.'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      }),
+      'An invite-link redemption audit record.',
+    ),
+    'InviteLinkRedemption',
+  )
+
+  /** Create body. */
+  export const CreateInviteLinkRequest = OpenApi.component(
+    z
+      .object({
+        allowedEmailDomains: z.optional(allowedEmailDomains),
+        expiresAt: z.optional(nullableExpiry),
+        maxUses: z.optional(nullableUses),
+        name: z.optional(
+          z
+            .string()
+            .check(
+              z.trim(),
+              z.minLength(1),
+              z.maxLength(100),
+              z.describe('Human-readable link name.'),
+              z.meta({ examples: ['Community'] }),
+            ),
+        ),
+        role: z
+          ._default(role, 'member')
+          .check(z.describe('Role granted by the link.'), z.meta({ examples: ['member'] })),
+      })
+      .check(z.describe('Fields for creating an invite link.')),
+    'CreateInviteLinkRequest',
+  )
 
   /** Update body. */
-  export const UpdateBody = z
-    .object({
-      enabled: z
-        .boolean()
-        .check(z.describe('Whether the link is enabled.'), z.meta({ examples: [false] })),
-    })
-    .check(z.describe('Fields for updating an invite link.'))
+  export const UpdateInviteLinkRequest = OpenApi.component(
+    z
+      .object({
+        enabled: z
+          .boolean()
+          .check(z.describe('Whether the link is enabled.'), z.meta({ examples: [false] })),
+      })
+      .check(z.describe('Fields for updating an invite link.')),
+    'UpdateInviteLinkRequest',
+  )
 
   /** Bearer-token body for recipient operations. */
-  export const TokenBody = z
-    .object({
-      token: z
-        .string()
-        .check(
-          z.describe('Opaque invite-link bearer token.'),
-          z.meta({ examples: ['lnk_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-    })
-    .check(z.describe('An invite-link bearer token.'))
+  export const InviteLinkTokenRequest = OpenApi.component(
+    z
+      .object({
+        token: z
+          .string()
+          .check(
+            z.describe('Opaque invite-link bearer token.'),
+            z.meta({ examples: ['lnk_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      })
+      .check(z.describe('An invite-link bearer token.')),
+    'InviteLinkTokenRequest',
+  )
 
   /** Public active-link summary. */
-  export const ResolveResponse = Schema.describe(
-    z.object({
-      orgName: z
-        .string()
-        .check(
-          z.describe('Human-readable name of the organization.'),
-          z.meta({ examples: ['Acme, Inc.'] }),
-        ),
-      role,
-    }),
-    'A public summary of an active invite link.',
+  export const ResolveResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        orgName: z
+          .string()
+          .check(
+            z.describe('Human-readable name of the organization.'),
+            z.meta({ examples: ['Acme, Inc.'] }),
+          ),
+        role,
+      }),
+      'A public summary of an active invite link.',
+    ),
+    'ResolveInviteLinkResponse',
   )
 
   /** Successful acceptance. */
-  export const AcceptResponse = Schema.describe(
-    z.object({
-      orgId: z
-        .string()
-        .check(
-          z.describe('Organization id joined through the link.'),
-          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-      role,
-      userId: z
-        .string()
-        .check(
-          z.describe('Member user id.'),
-          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-    }),
-    'The membership granted through an invite link.',
+  export const AcceptResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        orgId: z
+          .string()
+          .check(
+            z.describe('Organization id joined through the link.'),
+            z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+        role,
+        userId: z
+          .string()
+          .check(
+            z.describe('Member user id.'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      }),
+      'The membership granted through an invite link.',
+    ),
+    'AcceptInviteLinkResponse',
   )
 
   /** Link collection response. */
-  export const ListResponse = Schema.describe(
-    z.object({
-      data: z
-        .array(InviteLink)
-        .check(z.describe('Invite links, newest first.'), z.meta({ examples: [[]] })),
-    }),
-    'A non-paginated list of invite links.',
+  export const ListResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        data: z
+          .array(InviteLink)
+          .check(z.describe('Invite links, newest first.'), z.meta({ examples: [[]] })),
+      }),
+      'A non-paginated list of invite links.',
+    ),
+    'InviteLinkList',
   )
 
   /** Redemption collection response. */
-  export const RedemptionsResponse = Schema.describe(
-    z.object({
-      data: z
-        .array(Redemption)
-        .check(z.describe('Redemptions, newest first.'), z.meta({ examples: [[]] })),
-    }),
-    'A non-paginated list of invite-link redemptions.',
+  export const RedemptionsResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        data: z
+          .array(Redemption)
+          .check(z.describe('Redemptions, newest first.'), z.meta({ examples: [[]] })),
+      }),
+      'A non-paginated list of invite-link redemptions.',
+    ),
+    'InviteLinkRedemptionList',
   )
 
   /** Path parameters addressing an organization's invite links. */
@@ -299,19 +326,20 @@ export namespace schema {
     .check(z.describe('Path parameters for one organization invite link.'))
 
   /** Delete confirmation. */
-  export const DeleteResponse = z
-    .object({
-      id: z
-        .string()
-        .check(
-          z.describe('Deleted invite-link resource id.'),
-          z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
-    })
-    .check(z.describe('Confirmation that an invite link was deleted.'))
+  export const DeleteResponse = OpenApi.component(
+    z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Deleted invite-link resource id.'),
+            z.meta({ examples: ['iln_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      })
+      .check(z.describe('Confirmation that an invite link was deleted.')),
+    'DeleteInviteLinkResponse',
+  )
 }
-
-const errors = { 404: 'No accessible invite link was found.' } as const
 const bodyValidation = {
   code: 'body_invalid',
   message: 'Check the request body and try again.',
@@ -329,11 +357,20 @@ export function inviteLinks() {
       Auth.policy({ session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.Params, paramValidation),
-      OpenApi.validate('json', schema.CreateBody, bodyValidation),
+      OpenApi.validate('json', schema.CreateInviteLinkRequest, bodyValidation),
       OpenApi.describeRoute({
         operationId: 'createInviteLink',
         responses: OpenApi.responses({
-          errors,
+          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: 'Created link.', schema: schema.InviteLink },
         }),
         summary: 'Create invite link',
@@ -342,6 +379,8 @@ export function inviteLinks() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
         if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
         const body = c.req.valid('json')
         try {
@@ -371,7 +410,13 @@ export function inviteLinks() {
       OpenApi.describeRoute({
         operationId: 'listInviteLinks',
         responses: OpenApi.responses({
-          errors,
+          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: 'Invite links.', schema: schema.ListResponse },
         }),
         summary: 'List invite links',
@@ -380,6 +425,7 @@ export function inviteLinks() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
         try {
           return c.json(
@@ -398,11 +444,20 @@ export function inviteLinks() {
       Auth.policy({ session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.LinkParams, paramValidation),
-      OpenApi.validate('json', schema.UpdateBody, bodyValidation),
+      OpenApi.validate('json', schema.UpdateInviteLinkRequest, bodyValidation),
       OpenApi.describeRoute({
         operationId: 'updateInviteLink',
         responses: OpenApi.responses({
-          errors,
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Malformed API key, invalid path, or invalid body.',
+            },
+            404: {
+              codes: ['invite_link_not_found', 'organization_not_found'],
+              description: 'No accessible organization or invite link was found.',
+            },
+          },
           success: { description: 'Updated link.', schema: schema.InviteLink },
         }),
         summary: 'Update invite link',
@@ -411,6 +466,8 @@ export function inviteLinks() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
         if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
         const body = c.req.valid('json')
         try {
@@ -435,7 +492,13 @@ export function inviteLinks() {
       OpenApi.describeRoute({
         operationId: 'deleteInviteLink',
         responses: OpenApi.responses({
-          errors,
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['invite_link_not_found', 'organization_not_found'],
+              description: 'No accessible organization or invite link was found.',
+            },
+          },
           success: { description: 'Deleted link.', schema: schema.DeleteResponse },
         }),
         summary: 'Delete invite link',
@@ -444,6 +507,7 @@ export function inviteLinks() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
         try {
           const id = c.req.valid('param').inviteLinkId
@@ -463,7 +527,13 @@ export function inviteLinks() {
       OpenApi.describeRoute({
         operationId: 'listInviteLinkRedemptions',
         responses: OpenApi.responses({
-          errors,
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Malformed API key or invalid path.' },
+            404: {
+              codes: ['invite_link_not_found', 'organization_not_found'],
+              description: 'No accessible organization or invite link was found.',
+            },
+          },
           success: { description: 'Redemptions.', schema: schema.RedemptionsResponse },
         }),
         summary: 'List link redemptions',
@@ -472,6 +542,7 @@ export function inviteLinks() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
         if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
         try {
           const db = Db.get(c.get('db'))
@@ -492,11 +563,17 @@ export function inviteLinks() {
     .post(
       '/v1/invite-links/resolve',
       Auth.policy({ public: true, session: true }),
-      OpenApi.validate('json', schema.TokenBody, bodyValidation),
+      OpenApi.validate('json', schema.InviteLinkTokenRequest, bodyValidation),
       OpenApi.describeRoute({
         operationId: 'resolveInviteLink',
         responses: OpenApi.responses({
-          errors,
+          errors: {
+            400: { codes: ['body_invalid'], description: 'Malformed API key or invalid body.' },
+            404: {
+              codes: ['invite_link_not_found'],
+              description: 'No active invite link was found.',
+            },
+          },
           success: { description: 'Active link summary.', schema: schema.ResolveResponse },
         }),
         summary: 'Resolve invite link',
@@ -523,16 +600,20 @@ export function inviteLinks() {
     .post(
       '/v1/invite-links/accept',
       Auth.policy({ session: true }),
-      OpenApi.validate('json', schema.TokenBody, bodyValidation),
+      OpenApi.validate('json', schema.InviteLinkTokenRequest, bodyValidation),
       OpenApi.describeRoute({
         operationId: 'acceptInviteLink',
         responses: OpenApi.responses({
           errors: {
+            400: { codes: ['body_invalid'], description: 'Malformed API key or invalid body.' },
             403: {
-              codes: ['forbidden', 'invite_link_email_forbidden'],
+              codes: ['invite_link_email_forbidden'],
               description: 'A verified session email from an allowed domain is required.',
             },
-            ...errors,
+            404: {
+              codes: ['invite_link_not_found'],
+              description: 'No active invite link was found.',
+            },
           },
           success: { description: 'Membership.', schema: schema.AcceptResponse },
         }),