@dveloxsoft/dvs-client-nestjs

Cliente HTTP para microservicios DVS-Auth, DVS-User y DVS-Notification del ecosistema DveloxSoft.

Instalación

npm install @dveloxsoft/dvs-client-nestjs

Variables de Entorno

Esta librería utiliza las siguientes variables de entorno para funcionar:

| Variable | Descripción | Requerido | Valor por defecto | |----------|-------------|-----------|-------------------| | DVELOXSOFT_MS_AUTH_TOKEN | JWT token para autenticación con el gateway | Sí | (ninguno) | | DVELOXSOFT_MS_BASE_URL | URL base del gateway | No | https://ms.dveloxsoft.com | | DVELOXSOFT_MS_ORIGIN | Origen HTTP para headers | Sí | (ninguno) | | DVELOXSOFT_MS_REFERER | Referer HTTP para headers | Sí | (ninguno) | | HTTP_REQUEST_TIMEOUT | Timeout en milisegundos | No | 30000 |

Uso

En aplicación NestJS

import { Module } from '@nestjs/common';
import { DVSClientModule } from '@dveloxsoft/dvs-client-nestjs';

@Module({
  imports: [
    DVSClientModule.forRoot({
      // DVELOXSOFT_MS_AUTH_TOKEN es requerido
      authToken: process.env.DVELOXSOFT_MS_AUTH_TOKEN,
      // DVELOXSOFT_MS_BASE_URL tiene un valor por defecto: https://ms.dveloxsoft.com
      // Solo es necesario sobrescribirlo si se usa un gateway diferente
      baseUrl: process.env.DVELOXSOFT_MS_BASE_URL, // Opcional
      // DVELOXSOFT_MS_ORIGIN y DVELOXSOFT_MS_REFERER son requeridos
      defaultOrigin: process.env.DVELOXSOFT_MS_ORIGIN,
      defaultReferer: process.env.DVELOXSOFT_MS_REFERER,
      timeout: 30000,
    }),
  ],
})
export class AppModule {}

Ejemplo mínimo (usando valor por defecto para baseUrl)

Si su gateway está en https://ms.dveloxsoft.com, solo necesita proporcionar las variables requeridas:

@Module({
  imports: [
    DVSClientModule.forRoot({
      authToken: process.env.DVELOXSOFT_MS_AUTH_TOKEN, // Requerido
      defaultOrigin: process.env.DVELOXSOFT_MS_ORIGIN, // Requerido
      defaultReferer: process.env.DVELOXSOFT_MS_REFERER, // Requerido
      // baseUrl usa por defecto: https://ms.dveloxsoft.com
    }),
  ],
})
export class AppModule {}

Usar los clientes

import { Injectable } from '@nestjs/common';
import { DVSAuthClient, DVSUserClient, DVSNotificationClient } from '@dveloxsoft/dvs-client-nestjs';

@Injectable()
export class MyService {
  constructor(
    private readonly authClient: DVSAuthClient,
    private readonly userClient: DVSUserClient,
    private readonly notificationClient: DVSNotificationClient,
  ) {}
}

Access Token (Authorization Bearer)

Algunos endpoints requieren el header Authorization: Bearer <accessToken> en adición al x-ms-authorization-token.

Pasar access token como parámetro (método recomendado)

// Después del login
const { access_token } = await authClient.login({ email, password });
// Pasar el token como parámetro en cada llamada que lo requiera
const refreshed = await authClient.refreshToken({ refresh_token: refresh_token }, access_token);
const user = await userClient.findOne(userId, access_token);
const emailResult = await notificationClient.sendEmail(emailDto, access_token);

Ejemplos específicos por cliente

DVSAuthClient:

const loginResult = await authClient.login({ email, password }); // No requiere token
const refreshResult = await authClient.refreshToken({ refresh_token }, accessToken); // Requiere token
const activateResult = await authClient.activateAccount(code, pageId, accessToken); // Requiere token
const logoutResult = await authClient.logout(accessToken, refreshToken); // Requiere token

DVSUserClient:

const users = await userClient.findAll({}, accessToken); // Requiere token
const user = await userClient.findOne(userId, accessToken); // Requiere token
const updated = await userClient.update(userId, updateDto, accessToken); // Requiere token

DVSNotificationClient:

const emailResult = await notificationClient.sendEmail(emailDto, access_token); // Requiere token
const template = await notificationClient.createTemplate(templateDto, access_token); // Requiere token

Validación

La librería lanzará un error al intentar crear los clientes si faltan las siguientes variables de entorno requeridas:

• DVELOXSOFT_MS_AUTH_TOKEN - Token JWT para autenticación con el gateway
• DVELOXSOFT_MS_ORIGIN - Origen HTTP para headers
• DVELOXSOFT_MS_REFERER - Referer HTTP para headers

La variable DVELOXSOFT_MS_BASE_URL tiene un valor por defecto (https://ms.dveloxsoft.com) y no es estrictamente requerida. Si no está definida, se usará el valor por defecto.

Ejemplo de error si faltan variables requeridas:

Error: DVELOXSOFT_MS_AUTH_TOKEN is required. Provide it via forRoot() or set it as an environment variable.

Custom HTTP Client Integration

By default, the library uses Axios as the HTTP client. However, you can provide your own HTTP client implementation for greater flexibility or to use a different HTTP library (like fetch, ky, undici, etc.).

Creating a Custom HTTP Client

Your custom HTTP client must implement the HttpClient interface:

import { HttpClient, HttpRequestConfig, HttpResponse } from '@dveloxsoft/dvs-client-nestjs';

class MyHttpClient implements HttpClient {
  async get<T = any>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>> {
    // Your implementation here
  }
   
  async post<T = any>(url: string, data?: any, config?: HttpRequestConfig): Promise<HttpResponse<T>> {
    // Your implementation here
  }
   
  // Implement all other methods: put, delete, request
}

Using with forRoot()

You can pass your custom HTTP client when configuring the module:

import { Module } from '@nestjs/common';
import { DVSClientModule } from '@dveloxsoft/dvs-client-nestjs';
import { MyHttpClient } from './my-http-client';

@Module({
  imports: [
    DVSClientModule.forRoot({
      authToken: process.env.DVELOXSOFT_MS_AUTH_TOKEN,
      defaultOrigin: process.env.DVELOXSOFT_MS_ORIGIN,
      defaultReferer: process.env.DVELOXSOFT_MS_REFERER,
      // Pass your custom HTTP client instance
      httpClient: new MyHttpClient(),
    }),
  ],
})
export class AppModule {}

Using with Factory Function

Alternatively, you can provide a factory function that creates the HTTP client:

import { Module } from '@nestjs/common';
import { DVSClientModule } from '@dveloxsoft/dvs-client-nestjs';
import { HttpClientConfig } from '@dveloxsoft/dvs-client-nestjs/src/client/types';

function createMyHttpClient(config: HttpClientConfig): HttpClient {
  return new MyHttpClient(/* config parameters if needed */);
}

@Module({
  imports: [
    DVSClientModule.forRoot({
      authToken: process.env.DVELOXSOFT_MS_AUTH_TOKEN,
      defaultOrigin: process.env.DVELOXSOFT_MS_ORIGIN,
      defaultReferer: process.env.DVELOXSOFT_MS_REFERER,
      // Pass a factory function that creates your HTTP client
      httpClient: createMyHttpClient,
    }),
  ],
})
export class AppModule {}

When to Use a Custom HTTP Client

• To use a different HTTP library (fetch, ky, undici, etc.)
• For specialized request logging or monitoring
• To implement custom retry mechanisms
• For testing with mocked HTTP clients
• To comply with organizational HTTP client standards

API

DVSAuthClient

• login(dto: LoginDto) - Iniciar sesión (no requiere access token)
• register(dto: RegisterDto) - Registrar usuario (no requiere access token)
• refreshToken(dto: RefreshTokenDto, accessToken: string) - Refrescar token (requiere access token)
• requestPasswordReset(dto: PasswordResetRequestDto, accessToken: string) - Solicitar reset de contraseña (requiere access token)
• validateResetToken(token: string) - Validar token de reset (no requiere access token)
• resetPassword(dto: ResetPasswordDto) - Resetear contraseña (no requiere access token)
• activateAccount(code: string, pageId: string, accessToken: string) - Activar cuenta (requiere access token)
• resendConfirmationToken(email: string, accessToken: string) - Reenviar token de confirmación (requiere access token)
• verifyTwoFactor(dto: TwoFactorDto, accessToken: string) - Verificar 2FA (requiere access token)
• setupTwoFactor(userId: string, accessToken: string) - Configurar 2FA (requiere access token)
• confirmTwoFactorSetup(dto: TwoFactorDto, accessToken: string) - Confirmar configuración 2FA (requiere access token)
• disableTwoFactor(userId: string, accessToken: string) - Deshabilitar 2FA (requiere access token)
• logout(accessToken: string, refreshToken?: string) - Cerrar sesión (requiere access token)

DVSUserClient

• create(dto: CreateUserDto) - Crear usuario (no requiere access token)
• findAll(options: PaginationOptions = {}, accessToken: string) - Listar usuarios con paginación (requiere access token)
• findOne(id: string | number, accessToken: string) - Obtener usuario por ID (requiere access token)
• findByEmail(email: string, accessToken: string, includePassword?: boolean) - Buscar por email (requiere access token)
• update(id: string | number, dto: UpdateUserDto, accessToken: string) - Actualizar usuario (requiere access token)
• delete(id: string | number, accessToken: string) - Eliminar usuario (requiere access token)
• deleteWithData(id: string | number, accessToken: string) - Eliminar con datos relacionados (requiere access token)
• search(email: string, accessToken: string, companyId?: string) - Buscar usuarios (requiere access token)
• getFullDetail(email: string, pages: string[], accessToken: string) - Obtener detalle completo (requiere access token)
• findPartner(email: string, accessToken: string) - Buscar partner (requiere access token)
• updateLastLogin(userId: string | number, accessToken: string) - Actualizar último login (requiere access token)
• resetPassword(email: string, accessToken: string, password: string, pageId?: string) - Resetear contraseña (requiere access token)
• verifyTwoFactor(userId: string, accessToken: string, code: string) - Verificar 2FA (requiere access token)
• setupTwoFactor(dto: SetupTwoFactorDto, accessToken: string) - Configurar 2FA (requiere access token)
• confirmTwoFactorSetup(userId: string, accessToken: string, code: string) - Confirmar 2FA (requiere access token)
• enableTwoFactor(userId: string | number, accessToken: string) - Habilitar 2FA (requiere access token)
• disableTwoFactor(userId: string | number, accessToken: string) - Deshabilitar 2FA (requiere access token)
• subscribeNewsletter(email: string, accessToken: string, pageId?: string) - Suscribir a newsletter (requiere access token)

DVSNotificationClient

Send Email

• sendEmail(dto: SendEmailDto, accessToken: string) - Enviar correo directamente (requiere access token)
• sendEmailByTrigger(dto: SendEmailTriggerDto, accessToken: string) - Enviar correo por trigger (requiere access token)

Email Templates

• createTemplate(dto: CreateEmailTemplateDto, accessToken: string) - Crear plantilla (requiere access token)
• getAllTemplates(options: PaginationOptions = {}, accessToken: string) - Listar todas las plantillas (requiere access token)
• getTemplatesByCompany(companyId: string, options: PaginationOptions = {}, accessToken: string) - Listar por empresa (requiere access token)
• getTemplate(id: string, accessToken: string) - Obtener plantilla por ID (requiere access token)
• updateTemplate(id: string, dto: UpdateEmailTemplateDto, accessToken: string) - Actualizar plantilla (requiere access token)
• deleteTemplate(id: string, accessToken: string) - Eliminar plantilla (requiere access token)
• testTemplate(template: string, accessToken: string) - Probar plantilla (requiere access token)
• testEmailConfig(config: TestEmailDto, accessToken: string) - Probar configuración SMTP (requiere access token)
• deleteAllTemplates(ids: string[], accessToken: string) - Eliminar múltiples plantillas (requiere access token)
• deleteTemplatesByCompany(companyId: string, accessToken: string) - Eliminar por empresa (requiere access token)