feat(server): add response DTOs for Payment Links, Stripe, Credit Notes and Inventory Cost

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

@@ -14,6 +14,7 @@ import {
   ApiExtraModels,
   ApiOperation,
   ApiParam,
+  ApiQuery,
   ApiResponse,
   ApiTags,
   getSchemaPath,
@@ -92,7 +93,7 @@ export class BillPaymentsController {
     summary:
       'Retrieves the payable entries of the new page once vendor be selected.',
   })
-  @ApiParam({
+  @ApiQuery({
     name: 'vendorId',
     required: true,
     type: Number,

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

@@ -24,6 +24,7 @@ import { CreditNoteApplication } from './CreditNoteApplication.service';
 import { ICreditNotesQueryDTO } from './types/CreditNotes.types';
 import { CreateCreditNoteDto, EditCreditNoteDto } from './dtos/CreditNote.dto';
 import { CreditNoteResponseDto } from './dtos/CreditNoteResponse.dto';
+import { CreditNoteStateResponseDto } from './dtos/CreditNoteStateResponse.dto';
 import { PaginatedResponseDto } from '@/common/dtos/PaginatedResults.dto';
 import { ApiCommonHeaders } from '@/common/decorators/ApiCommonHeaders';
 import {
@@ -62,7 +63,11 @@ export class CreditNotesController {
   @Get('state')
   @RequirePermission(CreditNoteAction.View, AbilitySubject.CreditNote)
   @ApiOperation({ summary: 'Get credit note state' })
-  @ApiResponse({ status: 200, description: 'Returns the credit note state' })
+  @ApiResponse({
+    status: 200,
+    description: 'Returns the credit note state',
+    type: CreditNoteStateResponseDto,
+  })
   getCreditNoteState() {
     return this.creditNoteApplication.getCreditNoteState();
   }

packages/server/src/modules/CreditNotes/dtos/CreditNoteStateResponse.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreditNoteStateResponseDto {
+  @ApiProperty({
+    description: 'Default PDF template ID for credit notes',
+    example: 1,
+  })
+  defaultTemplateId: number;
+}

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

@@ -1,7 +1,8 @@
 import { Controller, Get, Query } from '@nestjs/common';
 import { GetItemsInventoryValuationListService } from './queries/GetItemsInventoryValuationList.service';
 import { GetInventoyItemsCostQueryDto } from './dtos/GetInventoryItemsCostQuery.dto';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { GetInventoryItemsCostResponseDto } from './dtos/GetInventoryItemsCostResponse.dto';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { ApiCommonHeaders } from '@/common/decorators/ApiCommonHeaders';
 
 @Controller('inventory-cost')
@@ -14,9 +15,14 @@ export class InventoryCostController {
 
   @Get('items')
   @ApiOperation({ summary: 'Get items inventory valuation list' })
+  @ApiResponse({
+    status: 200,
+    description: 'Items inventory cost list',
+    type: GetInventoryItemsCostResponseDto,
+  })
   async getItemsCost(
     @Query() itemsCostsQueryDto: GetInventoyItemsCostQueryDto,
-  ) {
+  ): Promise<GetInventoryItemsCostResponseDto> {
     const costs = await this.inventoryItemCost.getItemsInventoryValuationList(
       itemsCostsQueryDto.itemsIds,
       itemsCostsQueryDto.date,

packages/server/src/modules/InventoryCost/dtos/GetInventoryItemsCostResponse.dto.ts

@@ -0,0 +1,23 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class InventoryItemCostDto {
+  @ApiProperty({ description: 'Item ID' })
+  itemId: number;
+
+  @ApiProperty({ description: 'Valuation' })
+  valuation: number;
+
+  @ApiProperty({ description: 'Quantity' })
+  quantity: number;
+
+  @ApiProperty({ description: 'Average cost' })
+  average: number;
+}
+
+export class GetInventoryItemsCostResponseDto {
+  @ApiProperty({
+    type: [InventoryItemCostDto],
+    description: 'List of item costs',
+  })
+  costs: InventoryItemCostDto[];
+}

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

@@ -3,6 +3,10 @@ import { Controller, Get, Param, Post, Res } from '@nestjs/common';
 import { PaymentLinksApplication } from './PaymentLinksApplication';
 import { ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { ApiCommonHeaders } from '@/common/decorators/ApiCommonHeaders';
+import {
+  GetInvoicePaymentLinkResponseWrapperDto,
+} from './dtos/GetInvoicePaymentLinkResponse.dto';
+import { CreateStripeCheckoutSessionResponseDto } from './dtos/CreateStripeCheckoutSessionResponse.dto';
 
 @Controller('payment-links')
 @ApiTags('Payment Links')
@@ -24,12 +28,7 @@ export class PaymentLinksController {
   @ApiResponse({
     status: 200,
     description: 'Successfully retrieved payment link metadata',
-    schema: {
+    type: GetInvoicePaymentLinkResponseWrapperDto,
-      type: 'object',
-      properties: {
-        data: { type: 'object', description: 'Payment link metadata' },
-      },
-    },
   })
   @ApiResponse({ status: 404, description: 'Payment link not found' })
   public async getPaymentLinkPublicMeta(
@@ -55,19 +54,7 @@ export class PaymentLinksController {
   @ApiResponse({
     status: 200,
     description: 'Successfully created Stripe checkout session',
-    schema: {
+    type: CreateStripeCheckoutSessionResponseDto,
-      type: 'object',
-      properties: {
-        id: {
-          type: 'string',
-          description: 'Stripe checkout session ID',
-        },
-        url: {
-          type: 'string',
-          description: 'Stripe checkout session URL',
-        },
-      },
-    },
   })
   @ApiResponse({ status: 404, description: 'Payment link not found' })
   public async createInvoicePaymentLinkCheckoutSession(

packages/server/src/modules/PaymentLinks/dtos/CreateStripeCheckoutSessionResponse.dto.ts

@@ -0,0 +1,21 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateStripeCheckoutSessionResponseDto {
+  @ApiProperty({
+    description: 'Stripe checkout session ID',
+    example: 'cs_test_xxx',
+  })
+  sessionId: string;
+
+  @ApiProperty({
+    description: 'Stripe publishable key for the client',
+    example: 'pk_test_xxx',
+  })
+  publishableKey: string;
+
+  @ApiProperty({
+    description: 'URL to redirect the customer to complete checkout',
+    example: 'https://checkout.stripe.com/c/pay/cs_test_xxx',
+  })
+  redirectTo: string;
+}

packages/server/src/modules/PaymentLinks/dtos/GetInvoicePaymentLinkResponse.dto.ts

@@ -0,0 +1,171 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class PaymentLinkAddressDto {
+  @ApiProperty({ description: 'Address line 1' })
+  address_1: string;
+
+  @ApiProperty({ description: 'Address line 2' })
+  address_2: string;
+
+  @ApiProperty({ description: 'Postal code' })
+  postal_code: string;
+
+  @ApiProperty({ description: 'City' })
+  city: string;
+
+  @ApiProperty({ description: 'State or province' })
+  state_province: string;
+
+  @ApiProperty({ description: 'Phone number' })
+  phone: string;
+}
+
+export class PaymentLinkOrganizationDto {
+  @ApiProperty({ type: 'object', description: 'Organization address' })
+  address: Record<string, PaymentLinkAddressDto>;
+
+  @ApiProperty({ description: 'Organization name' })
+  name: string;
+
+  @ApiProperty({ description: 'Primary brand color' })
+  primaryColor: string;
+
+  @ApiProperty({ description: 'Logo URI' })
+  logoUri: string;
+
+  @ApiProperty({ description: 'Formatted address text' })
+  addressTextFormatted: string;
+}
+
+export class PaymentLinkEntryDto {
+  @ApiProperty({ description: 'Line item description' })
+  description: string;
+
+  @ApiProperty({ description: 'Item name' })
+  itemName: string;
+
+  @ApiProperty({ description: 'Quantity' })
+  quantity: number;
+
+  @ApiProperty({ description: 'Formatted quantity' })
+  quantityFormatted: string;
+
+  @ApiProperty({ description: 'Unit rate' })
+  rate: number;
+
+  @ApiProperty({ description: 'Formatted rate' })
+  rateFormatted: string;
+
+  @ApiProperty({ description: 'Line total' })
+  total: number;
+
+  @ApiProperty({ description: 'Formatted total' })
+  totalFormatted: string;
+}
+
+export class PaymentLinkTaxEntryDto {
+  @ApiProperty({ description: 'Tax name' })
+  name: string;
+
+  @ApiProperty({ description: 'Tax rate amount' })
+  taxRateAmount: number;
+
+  @ApiProperty({ description: 'Formatted tax rate amount' })
+  taxRateAmountFormatted: string;
+
+  @ApiProperty({ description: 'Tax rate code' })
+  taxRateCode: string;
+}
+
+export class PaymentLinkBrandingTemplateDto {
+  @ApiProperty({ description: 'Company logo URI' })
+  companyLogoUri: string;
+
+  @ApiProperty({ description: 'Primary color' })
+  primaryColor: string;
+
+  @ApiProperty({ description: 'Secondary color', required: false })
+  secondaryColor?: string;
+}
+
+export class GetInvoicePaymentLinkResponseDto {
+  @ApiProperty({ description: 'Amount due' })
+  dueAmount: number;
+
+  @ApiProperty({ description: 'Formatted amount due' })
+  dueAmountFormatted: string;
+
+  @ApiProperty({ description: 'Due date' })
+  dueDate: string;
+
+  @ApiProperty({ description: 'Formatted due date' })
+  dueDateFormatted: string;
+
+  @ApiProperty({ description: 'Formatted invoice date' })
+  invoiceDateFormatted: string;
+
+  @ApiProperty({ description: 'Invoice number' })
+  invoiceNo: string;
+
+  @ApiProperty({ description: 'Payment amount' })
+  paymentAmount: number;
+
+  @ApiProperty({ description: 'Formatted payment amount' })
+  paymentAmountFormatted: string;
+
+  @ApiProperty({ description: 'Subtotal' })
+  subtotal: number;
+
+  @ApiProperty({ description: 'Formatted subtotal' })
+  subtotalFormatted: string;
+
+  @ApiProperty({ description: 'Formatted subtotal in local currency' })
+  subtotalLocalFormatted: string;
+
+  @ApiProperty({ description: 'Total amount' })
+  total: number;
+
+  @ApiProperty({ description: 'Formatted total' })
+  totalFormatted: string;
+
+  @ApiProperty({ description: 'Formatted total in local currency' })
+  totalLocalFormatted: string;
+
+  @ApiProperty({ description: 'Customer name' })
+  customerName: string;
+
+  @ApiProperty({ description: 'Invoice message' })
+  invoiceMessage: string;
+
+  @ApiProperty({ description: 'Terms and conditions' })
+  termsConditions: string;
+
+  @ApiProperty({ type: [PaymentLinkEntryDto], description: 'Invoice line entries' })
+  entries: PaymentLinkEntryDto[];
+
+  @ApiProperty({ type: [PaymentLinkTaxEntryDto], description: 'Tax entries' })
+  taxes: PaymentLinkTaxEntryDto[];
+
+  @ApiProperty({ type: PaymentLinkBrandingTemplateDto, description: 'Branding template' })
+  brandingTemplate: PaymentLinkBrandingTemplateDto;
+
+  @ApiProperty({ type: PaymentLinkOrganizationDto, description: 'Organization metadata' })
+  organization: PaymentLinkOrganizationDto;
+
+  @ApiProperty({ description: 'Whether Stripe is available as payment method' })
+  hasStripePaymentMethod: boolean;
+
+  @ApiProperty({ description: 'Whether invoice has receivable balance' })
+  isReceivable: boolean;
+
+  @ApiProperty({ description: 'Formatted customer address' })
+  formattedCustomerAddress: string;
+}
+
+export class GetInvoicePaymentLinkResponseWrapperDto {
+  @ApiProperty({
+    type: GetInvoicePaymentLinkResponseDto,
+    description: 'Payment link invoice metadata',
+  })
+  data: GetInvoicePaymentLinkResponseDto;
+}

packages/server/src/modules/StripePayment/CreateStripeAccountLink.ts

@@ -12,4 +12,12 @@ export class CreateStripeAccountLinkService {
   public createAccountLink(stripeAccountId: string) {
     return this.stripePaymentService.createAccountLink(stripeAccountId);
   }
+
+  /**
+   * Creates a Stripe account session for the Connect embedded component.
+   * @param {string} accountId - Stripe Connect account ID.
+   */
+  public createAccountSession(accountId: string) {
+    return this.stripePaymentService.createAccountSession(accountId);
+  }
 }

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

@@ -1,6 +1,13 @@
 import { Body, Controller, Get, Injectable, Post } from '@nestjs/common';
 import { StripePaymentApplication } from './StripePaymentApplication';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiBody, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { GetStripeConnectLinkResponseDto } from './dtos/GetStripeConnectLinkResponse.dto';
+import { ExchangeStripeOAuthBodyDto } from './dtos/ExchangeStripeOAuthBody.dto';
+import { CreateStripeAccountLinkBodyDto } from './dtos/CreateStripeAccountLinkBody.dto';
+import { CreateStripeAccountLinkResponseDto } from './dtos/CreateStripeAccountLinkResponse.dto';
+import { CreateStripeAccountResponseDto } from './dtos/CreateStripeAccountResponse.dto';
+import { CreateStripeAccountSessionBodyDto } from './dtos/CreateStripeAccountSessionBody.dto';
+import { CreateStripeAccountSessionResponseDto } from './dtos/CreateStripeAccountSessionResponse.dto';
 
 @Controller('/stripe')
 @ApiTags('stripe')
@@ -9,9 +16,17 @@ export class StripeIntegrationController {
 
   /**
    * Retrieves Stripe OAuth2 connect link.
-   * @returns {Promise<Response|void>}
    */
   @Get('/link')
+  @ApiOperation({
+    summary: 'Get Stripe Connect link',
+    description: 'Retrieves the Stripe OAuth2 Connect authorization URL',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Successfully retrieved Stripe Connect link',
+    type: GetStripeConnectLinkResponseDto,
+  })
   public async getStripeConnectLink() {
     const authorizationUri = this.stripePaymentApp.getStripeConnectLink();
 
@@ -20,37 +35,85 @@ export class StripeIntegrationController {
 
   /**
    * Exchanges the given Stripe authorization code to Stripe user id and access token.
-   * @returns {Promise<void>}
    */
   @Post('/callback')
-  public async exchangeOAuth(@Body('code') code: string) {
+  @ApiOperation({
-    await this.stripePaymentApp.exchangeStripeOAuthToken(code);
+    summary: 'Exchange Stripe OAuth code',
+    description:
+      'Exchanges the Stripe authorization code for user id and access token',
+  })
+  @ApiBody({ type: ExchangeStripeOAuthBodyDto })
+  @ApiResponse({
+    status: 201,
+    description: 'Successfully exchanged OAuth code',
+  })
+  public async exchangeOAuth(@Body() body: ExchangeStripeOAuthBodyDto) {
+    await this.stripePaymentApp.exchangeStripeOAuthToken(body.code);
 
     return {};
   }
 
   /**
    * Creates a new Stripe account.
-   * @returns {Promise<void>}
    */
+  @Post('/account')
+  @ApiOperation({
+    summary: 'Create Stripe account',
+    description: 'Creates a new Stripe Connect account',
+  })
+  @ApiResponse({
+    status: 201,
+    description: 'Successfully created Stripe account',
+    type: CreateStripeAccountResponseDto,
+  })
   public async createAccount() {
     const accountId = await this.stripePaymentApp.createStripeAccount();
-    return {
+    return { account_id: accountId };
-      accountId,
-      message: 'The Stripe account has been created successfully.',
-    };
   }
 
   /**
-   * Creates a new Stripe account session.
+   * Creates a Stripe account session for the Connect embedded component.
-   * @returns {Promise<void>}
+   */
+  @Post('/account_session')
+  @ApiOperation({
+    summary: 'Create Stripe account session',
+    description:
+      'Creates an account session for the Stripe Connect embedded component',
+  })
+  @ApiBody({ type: CreateStripeAccountSessionBodyDto })
+  @ApiResponse({
+    status: 201,
+    description: 'Successfully created account session',
+    type: CreateStripeAccountSessionResponseDto,
+  })
+  public async createAccountSession(
+    @Body() body: CreateStripeAccountSessionBodyDto,
+  ) {
+    const clientSecret = await this.stripePaymentApp.createAccountSession(
+      body.account ?? '',
+    );
+    return { client_secret: clientSecret };
+  }
+
+  /**
+   * Creates a new Stripe account link for onboarding.
    */
   @Post('/account_link')
+  @ApiOperation({
+    summary: 'Create Stripe account link',
+    description: 'Creates a Stripe Connect account link for onboarding',
+  })
+  @ApiBody({ type: CreateStripeAccountLinkBodyDto })
+  @ApiResponse({
+    status: 201,
+    description: 'Successfully created account link',
+    type: CreateStripeAccountLinkResponseDto,
+  })
   public async createAccountLink(
-    @Body('stripeAccountId') stripeAccountId: string,
+    @Body() body: CreateStripeAccountLinkBodyDto,
   ) {
     const clientSecret =
-      await this.stripePaymentApp.createAccountLink(stripeAccountId);
+      await this.stripePaymentApp.createAccountLink(body.stripeAccountId);
 
     return { clientSecret };
   }

packages/server/src/modules/StripePayment/StripePaymentApplication.ts

@@ -37,6 +37,14 @@ export class StripePaymentApplication {
     );
   }
 
+  /**
+   * Creates a Stripe account session for the Connect embedded component.
+   * @param {string} accountId - Stripe Connect account ID.
+   */
+  public createAccountSession(accountId: string) {
+    return this.createStripeAccountLinkService.createAccountSession(accountId);
+  }
+
   /**
    * Retrieves Stripe OAuth2 connect link.
    * @returns {string}

packages/server/src/modules/StripePayment/dtos/CreateStripeAccountLinkBody.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString } from 'class-validator';
+
+export class CreateStripeAccountLinkBodyDto {
+  @ApiProperty({
+    description: 'Stripe Connect account ID',
+    example: 'acct_xxx',
+  })
+  @IsString()
+  stripeAccountId: string;
+}

packages/server/src/modules/StripePayment/dtos/CreateStripeAccountLinkResponse.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { StripeAccountLinkResponseDto } from './StripeAccountLinkResponse.dto';
+
+export class CreateStripeAccountLinkResponseDto {
+  @ApiProperty({
+    type: StripeAccountLinkResponseDto,
+    description: 'Stripe AccountLink object for onboarding',
+  })
+  clientSecret: StripeAccountLinkResponseDto;
+}

packages/server/src/modules/StripePayment/dtos/CreateStripeAccountResponse.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateStripeAccountResponseDto {
+  @ApiProperty({
+    description: 'The Stripe Connect account ID',
+    example: 'acct_1234567890',
+  })
+  account_id: string;
+}

packages/server/src/modules/StripePayment/dtos/CreateStripeAccountSessionBody.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateStripeAccountSessionBodyDto {
+  @ApiProperty({
+    description: 'Stripe Connect account ID to create a session for',
+    example: 'acct_1234567890',
+    required: false,
+  })
+  account?: string;
+}

packages/server/src/modules/StripePayment/dtos/CreateStripeAccountSessionResponse.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateStripeAccountSessionResponseDto {
+  @ApiProperty({
+    description: 'Stripe Account Session client secret for the Connect embedded component',
+    example: 'acs_xxx_secret_xxx',
+  })
+  client_secret: string;
+}

packages/server/src/modules/StripePayment/dtos/ExchangeStripeOAuthBody.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString } from 'class-validator';
+
+export class ExchangeStripeOAuthBodyDto {
+  @ApiProperty({
+    description: 'Authorization code returned by Stripe OAuth',
+    example: 'ac_xxx',
+  })
+  @IsString()
+  code: string;
+}

packages/server/src/modules/StripePayment/dtos/GetStripeConnectLinkResponse.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class GetStripeConnectLinkResponseDto {
+  @ApiProperty({
+    description: 'Stripe OAuth2 Connect authorization URL',
+    example: 'https://connect.stripe.com/oauth/authorize?response_type=code&client_id=...',
+  })
+  url: string;
+}

packages/server/src/modules/StripePayment/dtos/StripeAccountLinkResponse.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class StripeAccountLinkResponseDto {
+  @ApiProperty({
+    description: 'URL for the account onboarding flow',
+    example: 'https://connect.stripe.com/setup/xxx',
+  })
+  url: string;
+
+  @ApiProperty({
+    description: 'Unix timestamp when the link was created',
+    example: 1234567890,
+  })
+  created: number;
+
+  @ApiProperty({
+    description: 'Unix timestamp when the link expires',
+    example: 1234567890,
+  })
+  expires_at: number;
+
+  @ApiProperty({
+    description: 'Stripe object type',
+    example: 'account_link',
+  })
+  object: string;
+}