Standardize dto suffix (#443)

# Problem

The data transfer objects were not consistently named in the docs.

# Solution

- Standardize on the `Dto` suffix (too many conflicts to remove it)
- Fix issue with swagger to Markdown generation to fix accidental
classing instead of title
- Fix issue with dev controller data type (file instead of Buffer)
- Have prettier ignore generated files

.prettierignore

@@ -5,3 +5,7 @@
 **/*.yml
 # Ignore rust build files
 services/account/rust-webhook-server/target
+# Ignore generated content
+services/*/apps/api/src/metadata.ts
+**/swagger.json
+services/*/docs/index.html

docs/preprocessor.mjs

@@ -51,7 +51,14 @@ function swaggerEmbed(chapter) {
   if (match) {
     const swaggerFile = match[1];
     const output = runNpxCommand('openapi-to-md', [swaggerFile]);
-    const replaceWith = output.split('\n').slice(5).join('\n');
+    const replaceWith = output
+      .split('\n')
+      // Remove the default header
+      .slice(5)
+      // This hack fixes the markdown issue that mdBook headers support classes which breaks
+      // with some params lines: https://rust-lang.github.io/mdBook/format/markdown.html#heading-attributes
+      .map((line) => (line.startsWith('#') ? line + '{}' : line))
+      .join('\n');
     chapter.content = chapter.content.replace(match[0], replaceWith);
   }
   if (chapter.sub_items) {

services/account/apps/api/src/controllers/v1/accounts-v1.controller.ts

@@ -1,8 +1,8 @@
 import { AccountsService } from '#api/services/accounts.service';
-import { AccountResponse } from '#lib/types/dtos/accounts.response.dto';
+import { AccountResponseDto } from '#lib/types/dtos/accounts.response.dto';
 import { WalletLoginRequestDto } from '#lib/types/dtos/wallet.login.request.dto';
-import { WalletLoginConfigResponse } from '#lib/types/dtos/wallet.login.config.response.dto';
-import { WalletLoginResponse } from '#lib/types/dtos/wallet.login.response.dto';
+import { WalletLoginConfigResponseDto } from '#lib/types/dtos/wallet.login.config.response.dto';
+import { WalletLoginResponseDto } from '#lib/types/dtos/wallet.login.response.dto';
 import { Body, Controller, Get, Post, HttpCode, HttpStatus, Logger, Param, HttpException } from '@nestjs/common';
 import { ApiBody, ApiOkResponse, ApiCreatedResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
 
@@ -18,8 +18,8 @@ export class AccountsControllerV1 {
   @Get('siwf')
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Get the Sign In With Frequency configuration' })
-  @ApiOkResponse({ description: 'Returned SIWF Configuration data', type: WalletLoginConfigResponse })
-  async getSIWFConfig(): Promise<WalletLoginConfigResponse> {
+  @ApiOkResponse({ description: 'Returned SIWF Configuration data', type: WalletLoginConfigResponseDto })
+  async getSIWFConfig(): Promise<WalletLoginConfigResponseDto> {
     try {
       this.logger.debug('Received request for Sign In With Frequency Configuration');
       return this.accountsService.getSIWFConfig();
@@ -33,14 +33,14 @@ export class AccountsControllerV1 {
   @Get(':msaId')
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Fetch an account given an MSA Id' })
-  @ApiOkResponse({ description: 'Found account', type: AccountResponse })
+  @ApiOkResponse({ description: 'Found account', type: AccountResponseDto })
   /**
    * Gets an account.
    * @param queryParams - The query parameters for creating the account.
    * @returns A promise that resolves to an Account object => {msaId, handle}.
    * @throws An error if the account cannot be found.
    */
-  async getAccountForMsa(@Param('msaId') msaId: string): Promise<AccountResponse> {
+  async getAccountForMsa(@Param('msaId') msaId: string): Promise<AccountResponseDto> {
     try {
       this.logger.debug(`Received request to get account with msaId: ${msaId}`);
       const account = await this.accountsService.getAccount(msaId);
@@ -56,14 +56,14 @@ export class AccountsControllerV1 {
   @Get('account/:publicKey')
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Fetch an account given a public key' })
-  @ApiOkResponse({ description: 'Found account', type: AccountResponse })
+  @ApiOkResponse({ description: 'Found account', type: AccountResponseDto })
   /**
    * Gets an account.
    * @param queryParams - The query parameters for creating the account.
    * @returns A promise that resolves to an Account object => {msaId, handle}.
    * @throws An error if the msaId or account cannot be found.
    */
-  async getAccountForPublicKey(@Param('publicKey') publicKey: string): Promise<AccountResponse> {
+  async getAccountForPublicKey(@Param('publicKey') publicKey: string): Promise<AccountResponseDto> {
     try {
       this.logger.debug(`Received request to get account with publicKey: ${publicKey}`);
       const response = await this.accountsService.getMsaIdForPublicKey(publicKey);
@@ -82,9 +82,9 @@ export class AccountsControllerV1 {
   @Post('siwf')
   @HttpCode(HttpStatus.CREATED)
   @ApiOperation({ summary: 'Request to Sign In With Frequency' })
-  @ApiCreatedResponse({ description: 'Signed in successfully', type: WalletLoginResponse })
+  @ApiCreatedResponse({ description: 'Signed in successfully', type: WalletLoginResponseDto })
   @ApiBody({ type: WalletLoginRequestDto })
-  async postSignInWithFrequency(@Body() walletLoginRequest: WalletLoginRequestDto): Promise<WalletLoginResponse> {
+  async postSignInWithFrequency(@Body() walletLoginRequest: WalletLoginRequestDto): Promise<WalletLoginResponseDto> {
     try {
       this.logger.debug(`Received Sign In With Frequency request: ${JSON.stringify(walletLoginRequest)}`);
       return this.accountsService.signInWithFrequency(walletLoginRequest);

services/account/apps/api/src/controllers/v1/handles-v1.controller.ts

@@ -3,9 +3,9 @@ import { ApiBody, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { TransactionType } from '#lib/types/enums';
 import { HandlesService } from '#api/services/handles.service';
 import { EnqueueService } from '#lib/services/enqueue-request.service';
-import { ChangeHandleRequest, CreateHandleRequest, HandleRequest } from '#lib/types/dtos/handles.request.dto';
+import { ChangeHandleRequest, CreateHandleRequest, HandleRequestDto } from '#lib/types/dtos/handles.request.dto';
 import { TransactionResponse } from '#lib/types/dtos/transaction.response.dto';
-import { HandleResponseDTO } from '#lib/types/dtos/accounts.response.dto';
+import { HandleResponseDto } from '#lib/types/dtos/accounts.response.dto';
 
 @Controller('v1/handles')
 @ApiTags('v1/handles')
@@ -23,14 +23,14 @@ export class HandlesControllerV1 {
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Request to create a new handle for an account' })
   @ApiOkResponse({ description: 'Handle creation request enqueued' })
-  @ApiBody({ type: HandleRequest })
+  @ApiBody({ type: HandleRequestDto })
   /**
    * Creates a handle using the provided query parameters.
    * @param queryParams - The query parameters for creating the account.
    * @returns A message that the handle creation is in progress.
    * @throws An error if the handle creation fails.
    */
-  async createHandle(@Body() createHandleRequest: HandleRequest): Promise<TransactionResponse> {
+  async createHandle(@Body() createHandleRequest: HandleRequestDto): Promise<TransactionResponse> {
     try {
       const response = await this.enqueueService.enqueueRequest<CreateHandleRequest>({
         ...createHandleRequest,
@@ -48,14 +48,14 @@ export class HandlesControllerV1 {
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Request to change a handle' })
   @ApiOkResponse({ description: 'Handle change request enqueued' })
-  @ApiBody({ type: HandleRequest })
+  @ApiBody({ type: HandleRequestDto })
   /**
    * Using the provided query parameters, removes the old handle and creates a new one.
    * @param queryParams - The query parameters for changing the handle.
    * @returns A message that the handle change is in progress.
    * @throws An error if the handle creation fails.
    */
-  async changeHandle(@Body() changeHandleRequest: HandleRequest): Promise<TransactionResponse> {
+  async changeHandle(@Body() changeHandleRequest: HandleRequestDto): Promise<TransactionResponse> {
     try {
       const response = await this.enqueueService.enqueueRequest<ChangeHandleRequest>({
         ...changeHandleRequest,
@@ -79,7 +79,7 @@ export class HandlesControllerV1 {
    * @returns A promise that resolves to a Handle object, representing the found handle.
    * @throws An error if the handle cannot be found.
    */
-  async getHandle(@Param('msaId') msaId: string): Promise<HandleResponseDTO> {
+  async getHandle(@Param('msaId') msaId: string): Promise<HandleResponseDto> {
     try {
       const handle = await this.handlesService.getHandle(msaId);
       if (!handle) {

services/account/apps/api/src/controllers/v1/keys-v1.controller.ts

@@ -3,7 +3,7 @@ import { EnqueueService } from '#lib/services/enqueue-request.service';
 import { TransactionType } from '#lib/types/enums';
 import { Controller, Get, HttpCode, HttpStatus, Logger, Param, HttpException, Body, Post } from '@nestjs/common';
 import { ApiBody, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
-import { KeysRequest, AddKeyRequest } from '#lib/types/dtos/keys.request.dto';
+import { KeysRequestDto, AddKeyRequestDto } from '#lib/types/dtos/keys.request.dto';
 import { TransactionResponse } from '#lib/types/dtos/transaction.response.dto';
 import { KeysResponse } from '#lib/types/dtos/keys.response.dto';
 
@@ -23,16 +23,16 @@ export class KeysControllerV1 {
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'Add new control keys for an MSA Id' })
   @ApiOkResponse({ description: 'Found public keys' })
-  @ApiBody({ type: KeysRequest })
+  @ApiBody({ type: KeysRequestDto })
   /**
    * Add new control keys for an MSA Id.
    * @param queryParams - The query parameters for adding the public keys.
    * @returns A promise that resolves to an array of public keys associated with the given msaId.
    * @throws An error if no public keys can be found.
    */
-  async addKey(@Body() addKeysRequest: KeysRequest): Promise<TransactionResponse> {
+  async addKey(@Body() addKeysRequest: KeysRequestDto): Promise<TransactionResponse> {
     try {
-      const response = await this.enqueueService.enqueueRequest<AddKeyRequest>({
+      const response = await this.enqueueService.enqueueRequest<AddKeyRequestDto>({
         ...addKeysRequest,
         type: TransactionType.ADD_KEY,
       });