@koalarx/nest 3.1.50 → 4.0.1

package/koala-nest/src/host/app.module.ts

@@ -0,0 +1,27 @@
+import { validateEnvConfig } from '@/core/env';
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { InactivePersonHandler } from '@/application/person/jobs/events/person/inactive-person/inactive-person.handler';
+import { CreatePersonJob } from '@/application/person/jobs/cron/create-person.job';
+import { DeleteInactiveJob } from '@/application/person/jobs/cron/delete-inactive.job';
+import { AuthModule } from './controllers/auth/auth.module';
+import { JobsModule } from './jobs/jobs.module';
+import { PersonModule } from './controllers/person/person.module';
+import { SecurityModule } from './security/security.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      validate: (config) => validateEnvConfig(config),
+    }),
+    SecurityModule,
+    AuthModule,
+    JobsModule.register({
+      imports: [PersonModule],
+      eventHandlers: [InactivePersonHandler],
+      cronJobs: [CreatePersonJob, DeleteInactiveJob],
+    }),
+  ],
+})
+export class AppModule {}

package/koala-nest/src/host/controllers/auth/auth.module.ts

@@ -0,0 +1,38 @@
+import { LoginHandler } from '@/application/auth/login/login.handler';
+import { RefreshTokenHandler } from '@/application/auth/refresh-token/refresh-token.handler';
+import { UserInfoHandler } from '@/application/auth/user-info/user-info.handler';
+import { OAuthAuthLinkHandler } from '@/application/auth/oauth2/auth-link/auth-link.handler';
+import { OAuthExchangeCodeHandler } from '@/application/auth/oauth2/exchange-code/exchange-code.handler';
+import { ScalarOAuthTokenHandler } from '@/application/auth/oauth2/scalar-token/scalar-oauth-token.handler';
+import { Module } from '@nestjs/common';
+import { ControllerModule } from '../common/controller.module';
+import { SecurityModule } from '@/host/security/security.module';
+import { LoginController } from './login.controller';
+import { UserInfoController } from './user-info.controller';
+import { RefreshTokenController } from './refresh-token.controller';
+import { OAuthAuthLinkController } from '../oauth2/auth-link.controller';
+import { OAuthExchangeCodeController } from '../oauth2/exchange-code.controller';
+import { OAuthCallbackController } from '../oauth2/oauth-callback.controller';
+import { ScalarOAuthTokenController } from '../oauth2/scalar-token.controller';
+
+@Module({
+  imports: [ControllerModule, SecurityModule],
+  controllers: [
+    LoginController,
+    UserInfoController,
+    RefreshTokenController,
+    OAuthAuthLinkController,
+    OAuthExchangeCodeController,
+    OAuthCallbackController,
+    ScalarOAuthTokenController,
+  ],
+  providers: [
+    LoginHandler,
+    UserInfoHandler,
+    RefreshTokenHandler,
+    OAuthAuthLinkHandler,
+    OAuthExchangeCodeHandler,
+    ScalarOAuthTokenHandler,
+  ],
+})
+export class AuthModule {}

package/koala-nest/src/host/controllers/auth/login.controller.ts

@@ -0,0 +1,41 @@
+import { LoginHandler } from '@/application/auth/login/login.handler';
+import { LoginRequest } from '@/application/auth/login/login.request';
+import { LoginResponse } from '@/application/auth/login/login.response';
+import { AuthHttp } from '@/core/auth/auth.constants';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { Body, HttpCode, HttpStatus, Post, Res } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import type { Response } from 'express';
+import { IController } from '../common/controller.base';
+import { AUTH_ROUTER_CONFIG } from './router.config';
+
+@Controller(AUTH_ROUTER_CONFIG)
+export class LoginController implements IController<
+  LoginRequest,
+  LoginResponse
+> {
+  constructor(private readonly handler: LoginHandler) {}
+
+  @Post('login')
+  @IsPublic()
+  @ApiExcludeEndpointDiffDevelop()
+  @HttpCode(HttpStatus.OK)
+  @ApiOkResponse({ type: LoginResponse })
+  async handle(
+    @Body() request: LoginRequest,
+    @Res({ passthrough: true }) response: Response,
+  ): Promise<LoginResponse> {
+    const tokens = await this.handler.handle(request);
+
+    response.cookie(AuthHttp.REFRESH_TOKEN_COOKIE, tokens.refreshToken, {
+      path: '/',
+      secure: true,
+      sameSite: 'strict',
+      httpOnly: true,
+    });
+
+    return tokens;
+  }
+}

package/koala-nest/src/host/controllers/auth/refresh-token.controller.ts

@@ -0,0 +1,24 @@
+import { RefreshTokenHandler } from '@/application/auth/refresh-token/refresh-token.handler';
+import { AuthTokenResponse } from '@/application/auth/common/auth-token.response';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { AUTH_ROUTER_CONFIG } from './router.config';
+
+@Controller(AUTH_ROUTER_CONFIG)
+export class RefreshTokenController implements IController<
+  void,
+  AuthTokenResponse
+> {
+  constructor(private readonly handler: RefreshTokenHandler) {}
+
+  @Post('refresh')
+  @ApiExcludeEndpointDiffDevelop()
+  @HttpCode(HttpStatus.OK)
+  @ApiOkResponse({ type: AuthTokenResponse })
+  handle(): Promise<AuthTokenResponse> {
+    return this.handler.handle();
+  }
+}

package/koala-nest/src/host/controllers/auth/router.config.ts

@@ -0,0 +1,9 @@
+import { RouterConfigBase } from '../common/router-config.base';
+
+class AuthRouterConfig extends RouterConfigBase {
+  constructor() {
+    super('Auth', '/auth');
+  }
+}
+
+export const AUTH_ROUTER_CONFIG = new AuthRouterConfig();

package/koala-nest/src/host/controllers/auth/user-info.controller.ts

@@ -0,0 +1,19 @@
+import { UserInfoHandler } from '@/application/auth/user-info/user-info.handler';
+import { UserInfoResponse } from '@/application/auth/user-info/user-info.response';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { Get, HttpCode, HttpStatus } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { AUTH_ROUTER_CONFIG } from './router.config';
+
+@Controller(AUTH_ROUTER_CONFIG)
+export class UserInfoController implements IController<void, UserInfoResponse> {
+  constructor(private readonly handler: UserInfoHandler) {}
+
+  @Get('user-info')
+  @HttpCode(HttpStatus.OK)
+  @ApiOkResponse({ type: UserInfoResponse })
+  handle(): Promise<UserInfoResponse> {
+    return this.handler.handle();
+  }
+}

package/koala-nest/src/host/controllers/common/controller.base.ts

@@ -0,0 +1,9 @@
+import { Response as HttpResponse } from 'express';
+
+export abstract class IController<Request, Response, Params = any> {
+  abstract handle(
+    request: Request,
+    params?: Params,
+    response?: HttpResponse,
+  ): Promise<Response>;
+}

package/koala-nest/src/host/controllers/common/controller.module.ts

@@ -0,0 +1,10 @@
+import { MappingProvider } from '@/application/mapping/mapping.provider';
+import { InfraModule } from '@/infra/infra.module';
+import { Module } from '@nestjs/common';
+
+@Module({
+  imports: [InfraModule],
+  providers: [MappingProvider],
+  exports: [InfraModule],
+})
+export class ControllerModule {}

package/koala-nest/src/host/controllers/common/router-config.base.ts

@@ -0,0 +1,14 @@
+export abstract class RouterConfigBase {
+  protected constructor(
+    private readonly _tag: string,
+    private readonly _group: string,
+  ) {}
+
+  get group() {
+    return this._group;
+  }
+
+  get tag() {
+    return this._tag;
+  }
+}

package/koala-nest/src/host/controllers/health-check/health-check.controller.ts

@@ -0,0 +1,29 @@
+import { DatabaseIndicator } from '@/infra/services/database.indicator.service';
+import { RedisIndicator } from '@/infra/services/redis.indicator.service';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { Controller, Get } from '@nestjs/common';
+import { ApiExcludeEndpoint } from '@nestjs/swagger';
+import { HealthCheck, HealthCheckService } from '@nestjs/terminus';
+
+@Controller('health')
+export class HealthCheckController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly db: DatabaseIndicator,
+    private readonly redis: RedisIndicator,
+  ) {}
+
+  @ApiExcludeEndpoint()
+  @Get()
+  @IsPublic()
+  @HealthCheck()
+  healthCheck() {
+    const checks = [() => this.db.isHealthy()];
+
+    if (this.redis.isConfigured()) {
+      checks.push(() => this.redis.isHealthy());
+    }
+
+    return this.health.check(checks);
+  }
+}

package/koala-nest/src/host/controllers/health-check/health-check.module.ts

@@ -0,0 +1,22 @@
+import { DatabaseIndicator } from '@/infra/services/database.indicator.service';
+import { RedisIndicator } from '@/infra/services/redis.indicator.service';
+import { DatabaseModule } from '@/infra/database/database.module';
+import { HttpModule } from '@nestjs/axios';
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { ControllerModule } from '../common/controller.module';
+import { HealthCheckController } from './health-check.controller';
+
+@Module({
+  imports: [
+    ControllerModule,
+    DatabaseModule,
+    HttpModule,
+    TerminusModule.forRoot({
+      errorLogStyle: 'pretty',
+    }),
+  ],
+  providers: [DatabaseIndicator, RedisIndicator],
+  controllers: [HealthCheckController],
+})
+export class HealthCheckModule {}

package/koala-nest/src/host/controllers/oauth2/auth-link.controller.ts

@@ -0,0 +1,29 @@
+import { OAuthAuthLinkHandler } from '@/application/auth/oauth2/auth-link/auth-link.handler';
+import { OAuthAuthLinkRequest } from '@/application/auth/oauth2/auth-link/auth-link.request';
+import { OAuthAuthLinkResponse } from '@/application/auth/oauth2/auth-link/auth-link.response';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { Body, HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { OAUTH_ROUTER_CONFIG } from './router.config';
+
+@Controller(OAUTH_ROUTER_CONFIG)
+export class OAuthAuthLinkController implements IController<
+  OAuthAuthLinkRequest,
+  OAuthAuthLinkResponse
+> {
+  constructor(private readonly handler: OAuthAuthLinkHandler) {}
+
+  @Post('auth-link')
+  @IsPublic()
+  @ApiExcludeEndpointDiffDevelop()
+  @HttpCode(HttpStatus.OK)
+  @ApiOkResponse({ type: OAuthAuthLinkResponse })
+  handle(
+    @Body() request: OAuthAuthLinkRequest,
+  ): Promise<OAuthAuthLinkResponse> {
+    return this.handler.handle(request);
+  }
+}

package/koala-nest/src/host/controllers/oauth2/exchange-code.controller.ts

@@ -0,0 +1,29 @@
+import { OAuthExchangeCodeHandler } from '@/application/auth/oauth2/exchange-code/exchange-code.handler';
+import { AuthTokenResponse } from '@/application/auth/common/auth-token.response';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { Body, HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { OAUTH_ROUTER_CONFIG } from './router.config';
+import { OAuthExchangeCodeRequest } from '@/application/auth/oauth2/exchange-code/exchange-code.request';
+
+@Controller(OAUTH_ROUTER_CONFIG)
+export class OAuthExchangeCodeController implements IController<
+  OAuthExchangeCodeRequest,
+  AuthTokenResponse
+> {
+  constructor(private readonly handler: OAuthExchangeCodeHandler) {}
+
+  @Post('token')
+  @IsPublic()
+  @ApiExcludeEndpointDiffDevelop()
+  @HttpCode(HttpStatus.OK)
+  @ApiOkResponse({ type: AuthTokenResponse })
+  handle(
+    @Body() request: OAuthExchangeCodeRequest,
+  ): Promise<AuthTokenResponse> {
+    return this.handler.handle(request);
+  }
+}

package/koala-nest/src/host/controllers/oauth2/oauth-callback.controller.ts

@@ -0,0 +1,28 @@
+import { OAuthCallbackResponse } from '@/application/auth/oauth2/callback/oauth-callback.response';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { Controller, Get, HttpCode, HttpStatus, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiOkResponse, ApiTags } from '@nestjs/swagger';
+
+@Controller()
+@ApiTags('OAuth2')
+export class OAuthCallbackController {
+  @Get('sso/callback')
+  @IsPublic()
+  @HttpCode(HttpStatus.OK)
+  @ApiExcludeEndpointDiffDevelop()
+  @ApiOkResponse({ type: OAuthCallbackResponse })
+  handle(@Query() query: OAuthCallbackResponse): OAuthCallbackResponse {
+    return query;
+  }
+
+  /** Alias legado — não documentado (Scalar usa `/sso/callback`). */
+  @Get('oauth2/callback')
+  @IsPublic()
+  @HttpCode(HttpStatus.OK)
+  @ApiExcludeEndpoint()
+  @ApiOkResponse({ type: OAuthCallbackResponse })
+  handleLegacy(@Query() query: OAuthCallbackResponse): OAuthCallbackResponse {
+    return query;
+  }
+}

package/koala-nest/src/host/controllers/oauth2/router.config.ts

@@ -0,0 +1,9 @@
+import { RouterConfigBase } from '../common/router-config.base';
+
+class OAuthRouterConfig extends RouterConfigBase {
+  constructor() {
+    super('OAuth2', '/oauth2');
+  }
+}
+
+export const OAUTH_ROUTER_CONFIG = new OAuthRouterConfig();

package/koala-nest/src/host/controllers/oauth2/scalar-token.controller.ts

@@ -0,0 +1,16 @@
+import { ScalarOAuthTokenHandler } from '@/application/auth/oauth2/scalar-token/scalar-oauth-token.handler';
+import { AuthTokenResponse } from '@/application/auth/common/auth-token.response';
+import { ScalarTokenEndpoint } from '@/host/decorators/scalar-token-endpoint.decorator';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { Body } from '@nestjs/common';
+import { OAUTH_ROUTER_CONFIG } from './router.config';
+
+@Controller(OAUTH_ROUTER_CONFIG)
+export class ScalarOAuthTokenController {
+  constructor(private readonly handler: ScalarOAuthTokenHandler) {}
+
+  @ScalarTokenEndpoint()
+  handle(@Body() body: Record<string, string>): Promise<AuthTokenResponse> {
+    return this.handler.handle(body);
+  }
+}

package/koala-nest/src/host/controllers/person/create-person.controller.ts

@@ -0,0 +1,23 @@
+import { Body, HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiCreatedResponse } from '@nestjs/swagger';
+import { PERSON_ROUTER_CONFIG } from './router.config';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { IController } from '../common/controller.base';
+import { CreatePersonRequest } from '@/application/person/create/create-person.request';
+import { CreatePersonResponse } from '@/application/person/create/create-person.response';
+import { CreatePersonHandler } from '@/application/person/create/create-person.handler';
+
+@Controller(PERSON_ROUTER_CONFIG)
+export class CreatePersonController implements IController<
+  CreatePersonRequest,
+  CreatePersonResponse
+> {
+  constructor(private readonly handler: CreatePersonHandler) {}
+
+  @Post()
+  @ApiCreatedResponse({ type: CreatePersonResponse })
+  @HttpCode(HttpStatus.CREATED)
+  handle(@Body() request: CreatePersonRequest): Promise<CreatePersonResponse> {
+    return this.handler.handle(request);
+  }
+}

package/koala-nest/src/host/controllers/person/delete-person.controller.ts

@@ -0,0 +1,23 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { DeletePersonHandler } from '@/application/person/delete/delete-person.handler';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { ApiExcludeEndpointDiffDevelop } from '@/host/decorators/api-exclude-endpoint-diff-develop.decorator';
+import { RestrictionByProfile } from '@/host/decorators/restriction-by-profile.decorator';
+import { Delete, HttpCode, HttpStatus, Param } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { PERSON_ROUTER_CONFIG } from './router.config';
+
+@Controller(PERSON_ROUTER_CONFIG)
+export class DeletePersonController implements IController<string, void> {
+  constructor(private readonly handler: DeletePersonHandler) {}
+
+  @Delete(':id')
+  @RestrictionByProfile([AuthProfile.admin])
+  @ApiExcludeEndpointDiffDevelop()
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOkResponse()
+  handle(@Param('id') id: string): Promise<void> {
+    return this.handler.handle(+id);
+  }
+}

package/koala-nest/src/host/controllers/person/person.module.ts

@@ -0,0 +1,39 @@
+import { CreatePersonHandler } from '@/application/person/create/create-person.handler';
+import { DeletePersonHandler } from '@/application/person/delete/delete-person.handler';
+import { ReadManyPersonHandler } from '@/application/person/read-many/read-many-person.handler';
+import { ReadPersonHandler } from '@/application/person/read/read-person.handler';
+import { UpdatePersonHandler } from '@/application/person/update/update-person.handler';
+import { Module } from '@nestjs/common';
+import { ControllerModule } from '../common/controller.module';
+import { CreatePersonController } from './create-person.controller';
+import { DeletePersonController } from './delete-person.controller';
+import { ReadManyPersonController } from './read-many-person.controller';
+import { ReadPersonController } from './read-person.controller';
+import { UpdatePersonController } from './update-person.controller';
+
+@Module({
+  imports: [ControllerModule],
+  controllers: [
+    CreatePersonController,
+    ReadPersonController,
+    ReadManyPersonController,
+    UpdatePersonController,
+    DeletePersonController,
+  ],
+  providers: [
+    CreatePersonHandler,
+    ReadPersonHandler,
+    ReadManyPersonHandler,
+    UpdatePersonHandler,
+    DeletePersonHandler,
+  ],
+  exports: [
+    ControllerModule,
+    CreatePersonHandler,
+    ReadPersonHandler,
+    ReadManyPersonHandler,
+    UpdatePersonHandler,
+    DeletePersonHandler,
+  ],
+})
+export class PersonModule {}

package/koala-nest/src/host/controllers/person/read-many-person.controller.ts

@@ -0,0 +1,24 @@
+import { ReadManyPersonHandler } from '@/application/person/read-many/read-many-person.handler';
+import { ReadManyPersonRequest } from '@/application/person/read-many/read-many-person.request';
+import { ReadManyPersonResponse } from '@/application/person/read-many/read-many-person.response';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { Get, Query } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { PERSON_ROUTER_CONFIG } from './router.config';
+
+@Controller(PERSON_ROUTER_CONFIG)
+export class ReadManyPersonController implements IController<
+  ReadManyPersonRequest,
+  ReadManyPersonResponse
+> {
+  constructor(private readonly handler: ReadManyPersonHandler) {}
+
+  @Get()
+  @ApiOkResponse({ type: ReadManyPersonResponse })
+  async handle(
+    @Query() query: ReadManyPersonRequest,
+  ): Promise<ReadManyPersonResponse> {
+    return await this.handler.handle(query);
+  }
+}

package/koala-nest/src/host/controllers/person/read-person.controller.ts

@@ -0,0 +1,21 @@
+import { ReadPersonHandler } from '@/application/person/read/read-person.handler';
+import { ReadPersonResponse } from '@/application/person/read/read-person.response';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { Get, Param } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { PERSON_ROUTER_CONFIG } from './router.config';
+
+@Controller(PERSON_ROUTER_CONFIG)
+export class ReadPersonController implements IController<
+  string,
+  ReadPersonResponse
+> {
+  constructor(private readonly handler: ReadPersonHandler) {}
+
+  @Get(':id')
+  @ApiOkResponse({ type: ReadPersonResponse })
+  async handle(@Param('id') id: string): Promise<ReadPersonResponse> {
+    return await this.handler.handle(+id);
+  }
+}

package/koala-nest/src/host/controllers/person/router.config.ts

@@ -0,0 +1,9 @@
+import { RouterConfigBase } from '../common/router-config.base';
+
+class PersonRouterConfig extends RouterConfigBase {
+  constructor() {
+    super('Person', '/person');
+  }
+}
+
+export const PERSON_ROUTER_CONFIG = new PersonRouterConfig();

package/koala-nest/src/host/controllers/person/update-person.controller.ts

@@ -0,0 +1,22 @@
+import { UpdatePersonHandler } from '@/application/person/update/update-person.handler';
+import { UpdatePersonRequest } from '@/application/person/update/update-person.request';
+import { Controller } from '@/host/decorators/controller.decorator';
+import { Body, HttpCode, HttpStatus, Put } from '@nestjs/common';
+import { ApiOkResponse } from '@nestjs/swagger';
+import { IController } from '../common/controller.base';
+import { PERSON_ROUTER_CONFIG } from './router.config';
+
+@Controller(PERSON_ROUTER_CONFIG)
+export class UpdatePersonController implements IController<
+  UpdatePersonRequest,
+  void
+> {
+  constructor(private readonly handler: UpdatePersonHandler) {}
+
+  @Put()
+  @ApiOkResponse()
+  @HttpCode(HttpStatus.OK)
+  handle(@Body() request: UpdatePersonRequest): Promise<void> {
+    return this.handler.handle(request);
+  }
+}

package/koala-nest/src/host/decorators/api-exclude-endpoint-diff-develop.decorator.ts

@@ -0,0 +1,9 @@
+import { EnvConfig } from '@/core/utils/env.config';
+import { ApiExcludeEndpoint } from '@nestjs/swagger';
+
+/**
+ * Oculta o endpoint na documentação OpenAPI fora do ambiente `develop`.
+ * Em `develop`, o Swagger inclui a rota normalmente.
+ */
+export const ApiExcludeEndpointDiffDevelop = () =>
+  ApiExcludeEndpoint(!EnvConfig.isEnvDevelop);

package/koala-nest/src/host/decorators/api-property-enum.decorator.ts

@@ -0,0 +1,49 @@
+import { ApiProperty, type ApiPropertyOptions } from '@nestjs/swagger';
+
+type ApiPropertyEnumOptions = Pick<
+  ApiPropertyOptions,
+  'enum' | 'isArray' | 'required'
+>;
+
+function resolveEnumValues(enumObject: Record<string, string | number>) {
+  const numericValues = Object.values(enumObject).filter(
+    (value) => typeof value === 'number',
+  );
+
+  if (numericValues.length > 0) {
+    return numericValues.map((value) => ({
+      value,
+      description: String(enumObject[value]),
+    }));
+  }
+
+  return Object.values(enumObject)
+    .filter((value) => typeof value === 'string')
+    .map((value) => ({
+      value,
+      description: String(value),
+    }));
+}
+
+/**
+ * Documenta enums no Swagger com descrição em Markdown.
+ */
+export function ApiPropertyEnum(options: ApiPropertyEnumOptions) {
+  return function (target: object, propertyKey: string | symbol) {
+    const enumObject = options.enum as Record<string, string | number>;
+    const enumValues = resolveEnumValues(enumObject);
+
+    const description = enumValues
+      .map((enumValue) => `${enumValue.description}: ${enumValue.value}`)
+      .join('\n');
+
+    const apiPropertyOptions = {
+      ...options,
+      description: description
+        ? ['```', description, '```'].join('\n')
+        : undefined,
+    } as ApiPropertyOptions;
+
+    ApiProperty(apiPropertyOptions)(target, propertyKey);
+  };
+}

package/koala-nest/src/host/decorators/api-property-only-develop.decorator.ts

@@ -0,0 +1,19 @@
+import { EnvConfig } from '@/core/utils/env.config';
+import {
+  ApiHideProperty,
+  ApiProperty,
+  type ApiPropertyOptions,
+} from '@nestjs/swagger';
+
+/**
+ * Documenta a propriedade no Swagger apenas no ambiente `develop`.
+ */
+export function ApiPropertyOnlyDevelop(options?: ApiPropertyOptions) {
+  return function (target: object, propertyKey: string | symbol) {
+    if (EnvConfig.isEnvDevelop) {
+      ApiProperty(options)(target, propertyKey);
+    } else {
+      ApiHideProperty()(target, propertyKey);
+    }
+  };
+}

package/koala-nest/src/host/decorators/controller.decorator.ts

@@ -0,0 +1,10 @@
+import { RouterConfigBase } from '../controllers/common/router-config.base';
+import { Controller as NestController } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+
+export function Controller(config: RouterConfigBase) {
+  return function (target: any) {
+    NestController(config.group)(target);
+    ApiTags(config.tag)(target);
+  };
+}