feat: more response docs

packages/server/src/modules/Accounts/Accounts.controller.ts

@@ -13,6 +13,7 @@ import { CreateAccountDTO } from './CreateAccount.dto';
 import { EditAccountDTO } from './EditAccount.dto';
 import { IAccountsFilter, IAccountsTransactionsFilter } from './Accounts.types';
 import {
+  ApiExtraModels,
   ApiOperation,
   ApiParam,
   ApiResponse,
@@ -20,9 +21,12 @@ import {
   getSchemaPath,
 } from '@nestjs/swagger';
 import { AccountResponseDto } from './dtos/AccountResponse.dto';
+import { AccountTypeResponseDto } from './dtos/AccountTypeResponse.dto';
 
 @Controller('accounts')
 @ApiTags('Accounts')
+@ApiExtraModels(AccountResponseDto)
+@ApiExtraModels(AccountTypeResponseDto)
 export class AccountsController {
   constructor(private readonly accountsApplication: AccountsApplication) {}
 
@@ -112,6 +116,9 @@ export class AccountsController {
   @ApiResponse({
     status: 200,
     description: 'The account types have been successfully retrieved.',
+    schema: {
+      $ref: getSchemaPath(AccountTypeResponseDto),
+    },
   })
   async getAccountTypes() {
     return this.accountsApplication.getAccountTypes();

packages/server/src/modules/Accounts/dtos/AccountTypeResponse.dto.ts

@@ -0,0 +1,51 @@
+import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
+
+export class AccountTypeResponseDto {
+  @ApiProperty({
+    description: 'The display label for the account type',
+    example: 'Cash',
+  })
+  label: string;
+
+  @ApiProperty({
+    description: 'The unique key for the account type',
+    example: 'cash',
+  })
+  key: string;
+
+  @ApiProperty({
+    description: 'The normal balance type for the account',
+    example: 'debit',
+  })
+  normal: string;
+
+  @ApiProperty({
+    description: 'The parent type of the account',
+    example: 'current-asset',
+  })
+  parentType: string;
+
+  @ApiProperty({
+    description: 'The root type of the account',
+    example: 'asset',
+  })
+  rootType: string;
+
+  @ApiProperty({
+    description: 'Whether the account type supports multiple currencies',
+    example: true,
+  })
+  multiCurrency: boolean;
+
+  @ApiProperty({
+    description: 'Whether the account type appears on the balance sheet',
+    example: true,
+  })
+  balanceSheet: boolean;
+
+  @ApiProperty({
+    description: 'Whether the account type appears on the income sheet',
+    example: false,
+  })
+  incomeSheet: boolean;
+}

packages/server/src/modules/InventoryAdjutments/InventoryAdjustments.controller.ts

@@ -62,6 +62,10 @@ export class InventoryAdjustmentsController {
   @ApiResponse({
     status: 200,
     description: 'The inventory adjustments have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(InventoryAdjustmentResponseDto) },
+    },
   })
   public async getInventoryAdjustments(
     @Query() filterDTO: IInventoryAdjustmentsFilter,

packages/server/src/modules/Items/Item.controller.ts

@@ -27,12 +27,21 @@ import { CreateItemDto, EditItemDto } from './dtos/Item.dto';
 import { GetItemsQueryDto } from './dtos/GetItemsQuery.dto';
 import { ItemResponseDto } from './dtos/itemResponse.dto';
 import { PaginatedResponseDto } from '@/common/dtos/PaginatedResults.dto';
+import { ItemInvoiceResponseDto } from './dtos/itemInvoiceResponse.dto';
+import { ItemEstimatesResponseDto } from './dtos/ItemEstimatesResponse.dto';
+import { ItemBillsResponseDto } from './dtos/itemBillsResponse.dto';
+import { ItemReceiptsResponseDto } from './dtos/ItemReceiptsResponse.dto';
 
 @Controller('/items')
 @ApiTags('Items')
 @UseGuards(SubscriptionGuard)
 @ApiExtraModels(ItemResponseDto)
 @ApiExtraModels(PaginatedResponseDto)
+@ApiExtraModels(ItemInvoiceResponseDto)
+@ApiExtraModels(ItemEstimatesResponseDto)
+@ApiExtraModels(ItemBillsResponseDto)
+@ApiExtraModels(ItemEstimatesResponseDto)
+@ApiExtraModels(ItemReceiptsResponseDto)
 export class ItemsController extends TenantController {
   constructor(private readonly itemsApplication: ItemsApplicationService) {
     super();
@@ -150,11 +159,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.editItem(itemId, editItemDto);
   }
 
-  /**
-   * Create item.
-   * @param createItemDto - The item DTO.
-   * @returns The created item id.
-   */
   @Post()
   @ApiOperation({ summary: 'Create a new item (product or service).' })
   @ApiResponse({
@@ -166,10 +170,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.createItem(createItemDto);
   }
 
-  /**
-   * Delete item.
-   * @param id - The item id.
-   */
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given item (product or service).' })
   @ApiResponse({
@@ -188,10 +188,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.deleteItem(itemId);
   }
 
-  /**
-   * Inactivate item.
-   * @param id - The item id.
-   */
   @Patch(':id/inactivate')
   @ApiOperation({ summary: 'Inactivate the given item (product or service).' })
   @ApiResponse({
@@ -210,10 +206,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.inactivateItem(itemId);
   }
 
-  /**
-   * Activate item.
-   * @param id - The item id.
-   */
   @Patch(':id/activate')
   @ApiOperation({ summary: 'Activate the given item (product or service).' })
   @ApiResponse({
@@ -232,10 +224,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.activateItem(itemId);
   }
 
-  /**
-   * Get item.
-   * @param id - The item id.
-   */
   @Get(':id')
   @ApiOperation({ summary: 'Get the given item (product or service).' })
   @ApiResponse({
@@ -257,11 +245,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.getItem(itemId);
   }
 
-  /**
-   * Retrieves the item associated invoices transactions.
-   * @param {string} id
-   * @returns {Promise<any>}
-   */
   @Get(':id/invoices')
   @ApiOperation({
     summary: 'Retrieves the item associated invoices transactions.',
@@ -270,6 +253,10 @@ export class ItemsController extends TenantController {
     status: 200,
     description:
       'The item associated invoices transactions have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(ItemInvoiceResponseDto) },
+    },
   })
   @ApiResponse({ status: 404, description: 'The item not found.' })
   @ApiParam({
@@ -283,11 +270,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.getItemInvoicesTransactions(itemId);
   }
 
-  /**
-   * Retrieves the item associated bills transactions.
-   * @param {string} id
-   * @returns {Promise<any>}
-   */
   @Get(':id/bills')
   @ApiOperation({
     summary: 'Retrieves the item associated bills transactions.',
@@ -296,6 +278,10 @@ export class ItemsController extends TenantController {
     status: 200,
     description:
       'The item associated bills transactions have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(ItemBillsResponseDto) },
+    },
   })
   @ApiResponse({ status: 404, description: 'The item not found.' })
   @ApiParam({
@@ -309,11 +295,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.getItemBillTransactions(itemId);
   }
 
-  /**
-   * Retrieves the item associated estimates transactions.
-   * @param {string} id
-   * @returns {Promise<any>}
-   */
   @Get(':id/estimates')
   @ApiOperation({
     summary: 'Retrieves the item associated estimates transactions.',
@@ -322,6 +303,10 @@ export class ItemsController extends TenantController {
     status: 200,
     description:
       'The item associated estimate transactions have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(ItemEstimatesResponseDto) },
+    },
   })
   @ApiResponse({ status: 404, description: 'The item not found.' })
   @ApiParam({
@@ -335,11 +320,6 @@ export class ItemsController extends TenantController {
     return this.itemsApplication.getItemEstimatesTransactions(itemId);
   }
 
-  /**
-   * Retrieves the item associated receipts transactions.
-   * @param {string} id
-   * @returns {Promise<any>}
-   */
   @Get(':id/receipts')
   @ApiOperation({
     summary: 'Retrieves the item associated receipts transactions.',
@@ -348,6 +328,9 @@ export class ItemsController extends TenantController {
     status: 200,
     description:
       'The item associated receipts transactions have been successfully retrieved.',
+    schema: {
+      $ref: getSchemaPath(ItemReceiptsResponseDto),
+    },
   })
   @ApiResponse({ status: 404, description: 'The item not found.' })
   @ApiParam({

packages/server/src/modules/Items/dtos/ItemBillsResponse.dto.ts

@@ -0,0 +1,94 @@
+import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
+
+@ApiExtraModels()
+export class ItemBillsResponseDto {
+  @ApiProperty({
+    example: 123,
+    description: 'The unique identifier of the bill.',
+  })
+  billId: number;
+
+  @ApiProperty({
+    example: 'BILL-2024-001',
+    description: 'The bill number.',
+  })
+  billNumber: string;
+
+  @ApiProperty({
+    example: 'REF-2024-001',
+    description: 'The reference number of the bill.',
+  })
+  referenceNumber: string;
+
+  @ApiProperty({
+    example: '2024-06-01',
+    description: 'The date of the bill.',
+  })
+  billDate: string;
+
+  @ApiProperty({
+    example: '01/06/2024',
+    description: 'The formatted date of the bill.',
+  })
+  formattedBillDate: string;
+
+  @ApiProperty({
+    example: '2024-06-15',
+    description: 'The due date of the bill.',
+  })
+  billDueDate: string;
+
+  @ApiProperty({
+    example: '15/06/2024',
+    description: 'The formatted due date of the bill.',
+  })
+  formattedBillDueDate: string;
+
+  @ApiProperty({
+    example: 1000,
+    description: 'The amount of the bill item.',
+  })
+  amount: number;
+
+  @ApiProperty({
+    example: '$1,000.00',
+    description: 'The formatted amount of the bill item.',
+  })
+  formattedAmount: string;
+
+  @ApiProperty({
+    example: 5,
+    description: 'The quantity of the item in the bill.',
+  })
+  quantity: number;
+
+  @ApiProperty({
+    example: '5',
+    description: 'The formatted quantity of the item in the bill.',
+  })
+  formattedQuantity: string;
+
+  @ApiProperty({
+    example: 200,
+    description: 'The rate of the item in the bill.',
+  })
+  rate: number;
+
+  @ApiProperty({
+    example: '$200.00',
+    description: 'The formatted rate of the item in the bill.',
+  })
+  formattedRate: string;
+
+  @ApiProperty({
+    example: 'Acme Vendor',
+    description: 'The display name of the vendor.',
+  })
+  vendorDisplayName: string;
+
+  @ApiProperty({
+    example: 'USD',
+    description: 'The currency code of the vendor.',
+  })
+  vendorCurrencyCode: string;
+}

packages/server/src/modules/Items/dtos/ItemEstimatesResponse.dto.ts

@@ -0,0 +1,71 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ApiExtraModels } from '@nestjs/swagger';
+
+@ApiExtraModels()
+export class ItemEstimatesResponseDto {
+  @ApiProperty({
+    example: 123,
+    description: 'The unique identifier of the estimate.',
+  })
+  estimateId: number;
+
+  @ApiProperty({ example: 'EST-2024-001', description: 'The estimate number.' })
+  estimateNumber: string;
+
+  @ApiProperty({
+    example: 'REF-2024-001',
+    description: 'The reference number for the estimate.',
+  })
+  referenceNumber: string;
+
+  @ApiProperty({
+    example: '2024-06-01',
+    description: 'The date of the estimate.',
+  })
+  estimateDate: string;
+
+  @ApiProperty({
+    example: '01/06/2024',
+    description: 'The formatted estimate date.',
+  })
+  formattedEstimateDate: string;
+
+  @ApiProperty({ example: 1000, description: 'The amount of the estimate.' })
+  amount: number;
+
+  @ApiProperty({
+    example: '$1,000.00',
+    description: 'The formatted amount of the estimate.',
+  })
+  formattedAmount: string;
+
+  @ApiProperty({ example: 5, description: 'The quantity in the estimate.' })
+  quantity: number;
+
+  @ApiProperty({
+    example: '5',
+    description: 'The formatted quantity in the estimate.',
+  })
+  formattedQuantity: string;
+
+  @ApiProperty({ example: 200, description: 'The rate in the estimate.' })
+  rate: number;
+
+  @ApiProperty({
+    example: '$200.00',
+    description: 'The formatted rate in the estimate.',
+  })
+  formattedRate: string;
+
+  @ApiProperty({
+    example: 'Acme Corp',
+    description: 'The display name of the customer.',
+  })
+  customerDisplayName: string;
+
+  @ApiProperty({
+    example: 'USD',
+    description: 'The currency code of the customer.',
+  })
+  customerCurrencyCode: string;
+}

packages/server/src/modules/Items/dtos/ItemInvoiceResponse.dto.ts

@@ -0,0 +1,78 @@
+import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
+
+export class ItemInvoiceResponseDto {
+  @ApiProperty({
+    example: 123,
+    description: 'The unique identifier of the invoice.',
+  })
+  invoiceId: number;
+
+  @ApiProperty({ example: 'INV-2024-001', description: 'The invoice number.' })
+  invoiceNumber: string;
+
+  @ApiProperty({
+    example: 'REF-2024-001',
+    description: 'The reference number of the invoice.',
+  })
+  referenceNumber: string;
+
+  @ApiProperty({
+    example: '2024-06-01',
+    description: 'The date of the invoice.',
+  })
+  invoiceDate: string;
+
+  @ApiProperty({
+    example: '01/06/2024',
+    description: 'The formatted date of the invoice.',
+  })
+  formattedInvoiceDate: string;
+
+  @ApiProperty({
+    example: 1000,
+    description: 'The amount of the invoice item.',
+  })
+  amount: number;
+
+  @ApiProperty({
+    example: '$1,000.00',
+    description: 'The formatted amount of the invoice item.',
+  })
+  formattedAmount: string;
+
+  @ApiProperty({
+    example: 5,
+    description: 'The quantity of the item in the invoice.',
+  })
+  quantity: number;
+
+  @ApiProperty({
+    example: '5',
+    description: 'The formatted quantity of the item in the invoice.',
+  })
+  formattedQuantity: string;
+
+  @ApiProperty({
+    example: 200,
+    description: 'The rate of the item in the invoice.',
+  })
+  rate: number;
+
+  @ApiProperty({
+    example: '$200.00',
+    description: 'The formatted rate of the item in the invoice.',
+  })
+  formattedRate: string;
+
+  @ApiProperty({
+    example: 'Acme Corp',
+    description: 'The display name of the customer.',
+  })
+  customerDisplayName: string;
+
+  @ApiProperty({
+    example: 'USD',
+    description: 'The currency code of the customer.',
+  })
+  customerCurrencyCode: string;
+}

packages/server/src/modules/Items/dtos/ItemReceiptsResponse.dto.ts

@@ -0,0 +1,76 @@
+import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
+
+@ApiExtraModels()
+export class ItemReceiptsResponseDto {
+  @ApiProperty({
+    example: 123,
+    description: 'The unique identifier of the receipt.',
+  })
+  receiptId: number;
+
+  @ApiProperty({ example: 'RCPT-2024-001', description: 'The receipt number.' })
+  receipNumber: string;
+
+  @ApiProperty({
+    example: 'REF-2024-001',
+    description: 'The reference number for the receipt.',
+  })
+  referenceNumber: string;
+
+  @ApiProperty({
+    example: '2024-06-01',
+    description: 'The date of the receipt.',
+  })
+  receiptDate: string;
+
+  @ApiProperty({
+    example: '01/06/2024',
+    description: 'The formatted date of the receipt.',
+  })
+  formattedReceiptDate: string;
+
+  @ApiProperty({ example: 1000, description: 'The amount for the receipt.' })
+  amount: number;
+
+  @ApiProperty({
+    example: '$1,000.00',
+    description: 'The formatted amount for the receipt.',
+  })
+  formattedAmount: string;
+
+  @ApiProperty({
+    example: 10,
+    description: 'The quantity of items in the receipt.',
+  })
+  quantity: number;
+
+  @ApiProperty({
+    example: '10',
+    description: 'The formatted quantity of items in the receipt.',
+  })
+  formattedQuantity: string;
+
+  @ApiProperty({
+    example: 100,
+    description: 'The rate per item in the receipt.',
+  })
+  rate: number;
+
+  @ApiProperty({
+    example: '$100.00',
+    description: 'The formatted rate per item in the receipt.',
+  })
+  formattedRate: string;
+
+  @ApiProperty({
+    example: 'John Doe',
+    description: 'The display name of the customer.',
+  })
+  customerDisplayName: string;
+
+  @ApiProperty({
+    example: 'USD',
+    description: 'The currency code of the customer.',
+  })
+  customerCurrencyCode: string;
+}