@ftisindia/create-app 0.1.0

package/template/src/modules/invitations/dto/accept-invitation.dto.ts

@@ -0,0 +1,24 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+import { InvitationTokenDto } from "./invitation-token.dto";
+
+export class AcceptInvitationDto extends InvitationTokenDto {
+  @ApiPropertyOptional({
+    description:
+      "Required only when the invitation target is an email with no existing user.",
+    example: "dev-password-123",
+    minLength: 8,
+    maxLength: 128,
+  })
+  @IsOptional()
+  @IsString()
+  @MinLength(8)
+  @MaxLength(128)
+  password?: string;
+
+  @ApiPropertyOptional({ example: "New Member", maxLength: 120 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(120)
+  displayName?: string;
+}

package/template/src/modules/invitations/dto/create-invitation.dto.ts

@@ -0,0 +1,100 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { InvitationTargetType } from "@prisma/client";
+import { Type } from "class-transformer";
+import {
+  isEmail,
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
+  Validate,
+  ValidationArguments,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from "class-validator";
+
+const mobileTargetPattern = /^\+?[1-9]\d{6,14}$/;
+
+type InvitationTargetValueObject = {
+  targetType?: InvitationTargetType;
+};
+
+@ValidatorConstraint({ name: "InvitationTargetValue", async: false })
+class InvitationTargetValueConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown, args: ValidationArguments) {
+    if (typeof value !== "string") {
+      return false;
+    }
+
+    const targetType = (args.object as InvitationTargetValueObject).targetType;
+    if (targetType === InvitationTargetType.EMAIL) {
+      return isEmail(value.trim());
+    }
+
+    if (targetType === InvitationTargetType.MOBILE) {
+      return mobileTargetPattern.test(value.trim());
+    }
+
+    return false;
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    const targetType = (args.object as InvitationTargetValueObject).targetType;
+    if (targetType === InvitationTargetType.EMAIL) {
+      return "targetValue must be a valid email address when targetType is EMAIL";
+    }
+
+    if (targetType === InvitationTargetType.MOBILE) {
+      return "targetValue must be an E.164-style mobile number when targetType is MOBILE";
+    }
+
+    return "targetValue must match targetType";
+  }
+}
+
+export class CreateInvitationDto {
+  @ApiProperty({
+    enum: InvitationTargetType,
+    example: InvitationTargetType.EMAIL,
+  })
+  @IsEnum(InvitationTargetType)
+  targetType!: InvitationTargetType;
+
+  @ApiProperty({
+    description:
+      "Email address or E.164-style mobile number matching targetType.",
+    example: "new.member@example.com",
+    minLength: 3,
+    maxLength: 320,
+  })
+  @IsString()
+  @MinLength(3)
+  @MaxLength(320)
+  @Validate(InvitationTargetValueConstraint)
+  targetValue!: string;
+
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  @IsUUID()
+  roleId!: string;
+
+  @ApiPropertyOptional({
+    description: "Invitation lifetime in days.",
+    example: 7,
+    minimum: 1,
+    maximum: 30,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(30)
+  expiresInDays?: number;
+}

package/template/src/modules/invitations/dto/invitation-response.dto.ts

@@ -0,0 +1,108 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { InvitationStatus, InvitationTargetType } from "@prisma/client";
+import { MembershipResponseDto } from "../../../common/dto/membership-response.dto";
+import { RoleSummaryDto } from "../../../common/dto/role-summary.dto";
+import {
+  ActiveUserSummaryDto,
+  UserSummaryDto,
+} from "../../../common/dto/user-summary.dto";
+
+export class InvitationResponseDto {
+  @ApiProperty({
+    example: "17a21ad7-bd1b-42d8-b809-0a3892bb60c3",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    enum: InvitationTargetType,
+    example: InvitationTargetType.EMAIL,
+  })
+  targetType!: InvitationTargetType;
+
+  @ApiProperty({ example: "new.member@example.com" })
+  targetValue!: string;
+
+  @ApiProperty({ example: "new.member@example.com" })
+  normalizedTargetValue!: string;
+
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  roleId!: string;
+
+  @ApiProperty({ enum: InvitationStatus, example: InvitationStatus.PENDING })
+  status!: InvitationStatus;
+
+  @ApiProperty({ example: "2026-06-08T10:30:00.000Z", format: "date-time" })
+  expiresAt!: string;
+
+  @ApiProperty({
+    example: "4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456",
+    format: "uuid",
+  })
+  invitedByUserId!: string;
+
+  @ApiPropertyOptional({
+    example: "7efd9a26-fbec-4511-ae37-7fb1c35e5215",
+    format: "uuid",
+    nullable: true,
+  })
+  acceptedByUserId?: string | null;
+
+  @ApiProperty({ type: RoleSummaryDto })
+  role!: RoleSummaryDto;
+
+  @ApiProperty({ type: UserSummaryDto })
+  invitedByUser!: UserSummaryDto;
+
+  @ApiPropertyOptional({ type: UserSummaryDto, nullable: true })
+  acceptedByUser?: UserSummaryDto | null;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+
+  @ApiPropertyOptional({
+    example: "2026-06-01T10:35:00.000Z",
+    format: "date-time",
+    nullable: true,
+  })
+  acceptedAt?: string | null;
+
+  @ApiPropertyOptional({
+    example: "2026-06-01T10:40:00.000Z",
+    format: "date-time",
+    nullable: true,
+  })
+  revokedAt?: string | null;
+}
+
+export class InvitationWithTokenResponseDto {
+  @ApiProperty({ type: InvitationResponseDto })
+  invitation!: InvitationResponseDto;
+
+  @ApiProperty({
+    description:
+      "One-time invitation token. This is returned only at create/resend time.",
+    example: "k0Y7QJr7pC1r7GJrFXdN2vzmw1lYkT5YhJdORQb4Pp4",
+  })
+  inviteToken!: string;
+}
+
+export class AcceptInvitationResponseDto {
+  @ApiProperty({ type: InvitationResponseDto })
+  invitation!: InvitationResponseDto;
+
+  @ApiProperty({ type: MembershipResponseDto })
+  membership!: MembershipResponseDto;
+
+  @ApiProperty({ type: ActiveUserSummaryDto })
+  user!: ActiveUserSummaryDto;
+}

package/template/src/modules/invitations/dto/invitation-token.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MaxLength, MinLength } from "class-validator";
+
+export class InvitationTokenDto {
+  @ApiProperty({
+    description: "One-time invitation token from create/resend invitation.",
+    example: "k0Y7QJr7pC1r7GJrFXdN2vzmw1lYkT5YhJdORQb4Pp4",
+    minLength: 20,
+    maxLength: 256,
+  })
+  @IsString()
+  @MinLength(20)
+  @MaxLength(256)
+  token!: string;
+}

package/template/src/modules/invitations/invitations.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { MembershipsModule } from "../memberships/memberships.module";
+import { InvitationsService } from "./application/services/invitations.service";
+import { InvitationsController } from "./presentation/invitations.controller";
+
+@Module({
+  imports: [AuthModule, MembershipsModule],
+  controllers: [InvitationsController],
+  providers: [InvitationsService],
+})
+export class InvitationsModule {}

package/template/src/modules/invitations/presentation/invitations.controller.ts

@@ -0,0 +1,149 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  Post,
+  UseGuards,
+} from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from "@nestjs/swagger";
+import { ApiErrorResponses } from "../../../common/swagger/api-error-responses";
+import { PermissionGuard } from "../../access-control/application/services/permission.guard";
+import { RequirePermissions } from "../../access-control/presentation/permissions.decorator";
+import { JwtAuthGuard } from "../../auth/infrastructure/passport/jwt-auth.guard";
+import { CurrentUser } from "../../auth/presentation/current-user.decorator";
+import { AuthenticatedUser } from "../../auth/types/authenticated-user";
+import { OrgScopeGuard } from "../../request-context/presentation/org-scope.guard";
+import { InvitationsService } from "../application/services/invitations.service";
+import { AcceptInvitationDto } from "../dto/accept-invitation.dto";
+import { CreateInvitationDto } from "../dto/create-invitation.dto";
+import { InvitationTokenDto } from "../dto/invitation-token.dto";
+import {
+  AcceptInvitationResponseDto,
+  InvitationResponseDto,
+  InvitationWithTokenResponseDto,
+} from "../dto/invitation-response.dto";
+
+@ApiTags("Invitations")
+@Controller()
+export class InvitationsController {
+  constructor(private readonly invitationsService: InvitationsService) {}
+
+  @Post("organisations/:orgId/invitations")
+  @UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+  @RequirePermissions("memberships.invite")
+  @ApiBearerAuth()
+  @ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+  @ApiOperation({
+    summary: "Create an invitation for an email or mobile target.",
+  })
+  @ApiCreatedResponse({
+    description: "Invitation created. The inviteToken is shown once.",
+    type: InvitationWithTokenResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 403, 404, 409)
+  create(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Body() dto: CreateInvitationDto,
+  ) {
+    return this.invitationsService.createInvitation(user, orgId, dto);
+  }
+
+  @Get("organisations/:orgId/invitations")
+  @UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+  @RequirePermissions("memberships.read")
+  @ApiBearerAuth()
+  @ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+  @ApiOperation({ summary: "List invitations for an organisation." })
+  @ApiOkResponse({
+    description: "Organisation invitations.",
+    type: [InvitationResponseDto],
+  })
+  @ApiErrorResponses(400, 401, 403)
+  list(@CurrentUser() user: AuthenticatedUser, @Param("orgId") orgId: string) {
+    return this.invitationsService.listInvitations(user, orgId);
+  }
+
+  @Post("organisations/:orgId/invitations/:invitationId/revoke")
+  @HttpCode(200)
+  @UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+  @RequirePermissions("memberships.revoke")
+  @ApiBearerAuth()
+  @ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+  @ApiParam({
+    name: "invitationId",
+    description: "Invitation ID.",
+    format: "uuid",
+  })
+  @ApiOperation({ summary: "Revoke a pending invitation." })
+  @ApiOkResponse({
+    description: "Revoked invitation.",
+    type: InvitationResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 403, 404, 409, 410)
+  revoke(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("invitationId") invitationId: string,
+  ) {
+    return this.invitationsService.revokeInvitation(user, orgId, invitationId);
+  }
+
+  @Post("organisations/:orgId/invitations/:invitationId/resend")
+  @HttpCode(200)
+  @UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+  @RequirePermissions("memberships.invite")
+  @ApiBearerAuth()
+  @ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+  @ApiParam({
+    name: "invitationId",
+    description: "Invitation ID.",
+    format: "uuid",
+  })
+  @ApiOperation({ summary: "Resend a pending or expired invitation." })
+  @ApiOkResponse({
+    description: "Invitation resent. The new inviteToken is shown once.",
+    type: InvitationWithTokenResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 403, 404, 409)
+  resend(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("invitationId") invitationId: string,
+  ) {
+    return this.invitationsService.resendInvitation(user, orgId, invitationId);
+  }
+
+  @Post("invitations/accept")
+  @HttpCode(200)
+  @ApiOperation({ summary: "Accept an invitation token." })
+  @ApiOkResponse({
+    description: "Invitation accepted and membership created.",
+    type: AcceptInvitationResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 409, 410)
+  accept(@Body() dto: AcceptInvitationDto) {
+    return this.invitationsService.acceptInvitation(dto);
+  }
+
+  @Post("invitations/decline")
+  @HttpCode(200)
+  @ApiOperation({ summary: "Decline an invitation token." })
+  @ApiOkResponse({
+    description: "Declined invitation.",
+    type: InvitationResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 409, 410)
+  decline(@Body() dto: InvitationTokenDto) {
+    return this.invitationsService.declineInvitation(dto);
+  }
+}