RequestDto & ResponseDto

Every backend API body and response must use RequestDto<T> and ResponseDto<T> from @quan-erp/shared-backend-core. Never return raw payloads or accept unwrapped request bodies.

Overview

Wrappers give every endpoint the same shape: payload plus status, message, and a referenceId for tracing. Controllers read body.payload and return ResponseDto.ok / okWithEmpty / error.

Import from @quan-erp/shared-backend-core on the backend
Frontend uses the simplified types from @quan-erp/shared-frontend-core
Never return raw entities or accept bare DTOs on @Body()

1. ResponseDto<T>

Successful and error responses share one envelope.

ResponseDto.ok(data, options?) — success with payload
ResponseDto.okWithEmpty() — success with null payload (delete / no-content updates)
ResponseDto.error(message, code?, referenceId?, payload?) — error envelope

Field	Type	Notes
timestamp	string	ISO time
status	"success" \| "error"	Outcome flag
message	string?	User-facing message (localize when possible)
code	HttpStatus?	Optional HTTP status for errors
referenceId	string	UUID for log / support tracing
payload	T	Actual data (or null for empty success)

TSXcontroller responses

import {
  Delete,
  Get,
  HttpStatus,
  Post,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

@Get("/profile")
async getProfile() {
  const profile = await this.service.getProfile();
  return ResponseDto.ok(profile);
}

@Delete("/history/:id")
async deleteHistory() {
  await this.service.delete(/* … */);
  return ResponseDto.okWithEmpty();
}

@Post("/update")
async update() {
  try {
    return ResponseDto.ok(
      { success: true },
      { message: "Profile updated successfully" },
    );
  } catch {
    return ResponseDto.error(
      "Failed to update profile",
      HttpStatus.INTERNAL_SERVER_ERROR,
    );
  }
}

2. RequestDto<T>

@Body() expects RequestDto<T>. Client JSON wraps the real DTO; read it from body.payload.

TSXrequest body

import { Body, Post, RequestDto } from "@quan-erp/shared-backend-core";

@Post("/calculate")
async calculate(@Body() body: RequestDto<LoanCalculationDto>) {
  const data = body.payload;
  return ResponseDto.ok(await this.service.calculate(data));
}

3. Frontend pairing

On the client, wrap POST/PUT with new RequestDto(dto), cast response.data as ResponseDto<T>, check status, then return payload. Prefer shared-frontend-core helpers and Admin Axios & Query patterns.

new RequestDto(dto) before post/put
if (data.status === "error") throw …
GET fetchFn should return payload, not the full ResponseDto
See Frontend → Platform APIs → RequestDto & ResponseDto