feat(sdk-ts): add authentication fetch utils

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

@@ -14,12 +14,19 @@ import {
   ApiOperation,
   ApiBody,
   ApiParam,
-  ApiExcludeController,
+  ApiResponse,
+  ApiExtraModels,
+  getSchemaPath,
 } from '@nestjs/swagger';
 import { PublicRoute } from './guards/jwt.guard';
 import { AuthenticationApplication } from './AuthApplication.sevice';
 import { AuthSignupDto } from './dtos/AuthSignup.dto';
 import { AuthSigninDto } from './dtos/AuthSignin.dto';
+import { AuthSignupVerifyDto } from './dtos/AuthSignupVerify.dto';
+import { AuthSendResetPasswordDto } from './dtos/AuthSendResetPassword.dto';
+import { AuthResetPasswordDto } from './dtos/AuthResetPassword.dto';
+import { AuthSigninResponseDto } from './dtos/AuthSigninResponse.dto';
+import { AuthMetaResponseDto } from './dtos/AuthMetaResponse.dto';
 import { LocalAuthGuard } from './guards/Local.guard';
 import { AuthSigninService } from './commands/AuthSignin.service';
 import { TenantModel } from '../System/models/TenantModel';
@@ -27,7 +34,7 @@ import { SystemUser } from '../System/models/SystemUser';
 
 @Controller('/auth')
 @ApiTags('Auth')
-@ApiExcludeController()
+@ApiExtraModels(AuthSigninResponseDto, AuthMetaResponseDto)
 @PublicRoute()
 @Throttle({ auth: {} })
 export class AuthController {
@@ -43,10 +50,15 @@ export class AuthController {
   @UseGuards(LocalAuthGuard)
   @ApiOperation({ summary: 'Sign in a user' })
   @ApiBody({ type: AuthSigninDto })
+  @ApiResponse({
+    status: 200,
+    description: 'Sign-in successful. Returns access token and tenant/organization IDs.',
+    schema: { $ref: getSchemaPath(AuthSigninResponseDto) },
+  })
   async signin(
     @Request() req: Request & { user: SystemUser },
     @Body() signinDto: AuthSigninDto,
-  ) {
+  ): Promise<AuthSigninResponseDto> {
     const { user } = req;
     const tenant = await this.tenantModel.query().findById(user.tenantId);
 
@@ -61,59 +73,47 @@ export class AuthController {
   @Post('/signup')
   @ApiOperation({ summary: 'Sign up a new user' })
   @ApiBody({ type: AuthSignupDto })
+  @ApiResponse({ status: 201, description: 'Sign-up initiated. Check email for confirmation.' })
   signup(@Request() req: Request, @Body() signupDto: AuthSignupDto) {
     return this.authApp.signUp(signupDto);
   }
 
   @Post('/signup/verify')
   @ApiOperation({ summary: 'Confirm user signup' })
-  @ApiBody({
-    schema: {
-      type: 'object',
-      properties: {
-        email: { type: 'string', example: 'user@example.com' },
-        token: { type: 'string', example: 'confirmation-token' },
-      },
-    },
-  })
-  signupConfirm(@Body('email') email: string, @Body('token') token: string) {
-    return this.authApp.signUpConfirm(email, token);
+  @ApiBody({ type: AuthSignupVerifyDto })
+  @ApiResponse({ status: 200, description: 'Signup confirmed successfully.' })
+  signupConfirm(@Body() body: AuthSignupVerifyDto) {
+    return this.authApp.signUpConfirm(body.email, body.token);
   }
 
   @Post('/send_reset_password')
   @ApiOperation({ summary: 'Send reset password email' })
-  @ApiBody({
-    schema: {
-      type: 'object',
-      properties: {
-        email: { type: 'string', example: 'user@example.com' },
-      },
-    },
-  })
-  sendResetPassword(@Body('email') email: string) {
-    return this.authApp.sendResetPassword(email);
+  @ApiBody({ type: AuthSendResetPasswordDto })
+  @ApiResponse({ status: 200, description: 'Reset password email sent if the account exists.' })
+  sendResetPassword(@Body() body: AuthSendResetPasswordDto) {
+    return this.authApp.sendResetPassword(body.email);
   }
 
   @Post('/reset_password/:token')
   @ApiOperation({ summary: 'Reset password using token' })
-  @ApiParam({ name: 'token', description: 'Reset password token' })
-  @ApiBody({
-    schema: {
-      type: 'object',
-      properties: {
-        password: { type: 'string', example: 'new-password' },
-      },
-    },
-  })
+  @ApiParam({ name: 'token', description: 'Reset password token from email link' })
+  @ApiBody({ type: AuthResetPasswordDto })
+  @ApiResponse({ status: 200, description: 'Password reset successfully.' })
   resetPassword(
     @Param('token') token: string,
-    @Body('password') password: string,
+    @Body() body: AuthResetPasswordDto,
   ) {
-    return this.authApp.resetPassword(token, password);
+    return this.authApp.resetPassword(token, body.password);
   }
 
   @Get('/meta')
-  meta() {
+  @ApiOperation({ summary: 'Get auth metadata (e.g. signup disabled)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Auth metadata for the login/signup page.',
+    schema: { $ref: getSchemaPath(AuthMetaResponseDto) },
+  })
+  meta(): Promise<AuthMetaResponseDto> {
     return this.authApp.getAuthMeta();
   }
 }

packages/server/src/modules/Auth/dtos/AuthMetaResponse.dto.ts

@@ -0,0 +1,6 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AuthMetaResponseDto {
+  @ApiProperty({ description: 'Whether signup is disabled' })
+  signupDisabled: boolean;
+}

packages/server/src/modules/Auth/dtos/AuthResetPassword.dto.ts

@@ -0,0 +1,12 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AuthResetPasswordDto {
+  @ApiProperty({
+    example: 'new-password',
+    description: 'New password',
+  })
+  @IsNotEmpty()
+  @IsString()
+  password: string;
+}

packages/server/src/modules/Auth/dtos/AuthSendResetPassword.dto.ts

@@ -0,0 +1,12 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AuthSendResetPasswordDto {
+  @ApiProperty({
+    example: 'user@example.com',
+    description: 'User email address to send reset link to',
+  })
+  @IsNotEmpty()
+  @IsString()
+  email: string;
+}

packages/server/src/modules/Auth/dtos/AuthSigninResponse.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AuthSigninResponseDto {
+  @ApiProperty({ description: 'JWT access token' })
+  accessToken: string;
+
+  @ApiProperty({ description: 'Organization ID' })
+  organizationId: string;
+
+  @ApiProperty({ description: 'Tenant ID' })
+  tenantId: number;
+
+  @ApiProperty({ description: 'User ID' })
+  userId: number;
+}

packages/server/src/modules/Auth/dtos/AuthSignupVerify.dto.ts

@@ -0,0 +1,20 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AuthSignupVerifyDto {
+  @ApiProperty({
+    example: 'user@example.com',
+    description: 'User email address',
+  })
+  @IsNotEmpty()
+  @IsString()
+  email: string;
+
+  @ApiProperty({
+    example: 'confirmation-token',
+    description: 'Signup confirmation token from email',
+  })
+  @IsNotEmpty()
+  @IsString()
+  token: string;
+}