tychat-contracts 1.0.80 → 1.0.82

package/src/appointments/available-slots-query.dto.ts

@@ -4,6 +4,7 @@ import {
   IsArray,
   IsOptional,
   IsUUID,
+  Matches,
 } from 'class-validator';
 
 export class AvailableSlotsQueryDto {
@@ -28,5 +29,23 @@ export class AvailableSlotsQueryDto {
   @IsOptional()
   @IsUUID('4')
   userId?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Início do intervalo (YYYY-MM-DD). Com `endDate`, delimita o período. Se ambos forem omitidos, usa só o mês civil atual.',
+    example: '2026-03-01',
+  })
+  @IsOptional()
+  @Matches(/^\d{4}-\d{2}-\d{2}$/)
+  startDate?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Fim do intervalo (YYYY-MM-DD), inclusivo. Se omitido com `startDate`, usa o fim do mês de `startDate`.',
+    example: '2026-03-31',
+  })
+  @IsOptional()
+  @Matches(/^\d{4}-\d{2}-\d{2}$/)
+  endDate?: string;
 }
 

package/src/appointments/available-slots-response.dto.ts

@@ -1,35 +1,40 @@
 import { ApiProperty } from '@nestjs/swagger';
 import {
   IsArray,
+  IsInt,
   IsNotEmpty,
   IsString,
   Matches,
+  Min,
+  Max,
+  ValidateNested,
 } from 'class-validator';
+import { Type } from 'class-transformer';
 
-export class AvailableDaySlotsDto {
+/** Dia do mês com lista de horários (formato HH:mm). */
+export class AvailableSlotsDayHoursDto {
   @ApiProperty({
-    description: 'Data do dia disponível para agendamentos (formato YYYY-MM-DD)',
-    example: '2026-03-10',
+    description: 'Dia do mês (1–31)',
+    example: 15,
   })
-  @IsString()
-  @IsNotEmpty()
-  @Matches(/^\d{4}-\d{2}-\d{2}$/)
-  date: string;
+  @IsInt()
+  @Min(1)
+  @Max(31)
+  day: number;
 
   @ApiProperty({
-    description:
-      'Lista de horários disponíveis para agendamento no dia (formato HH:mm)',
+    description: 'Horários disponíveis neste dia',
     example: ['08:00', '08:30', '09:00'],
   })
   @IsArray()
   @IsString({ each: true })
   @Matches(/^\d{2}:\d{2}$/, { each: true })
-  slots: string[];
+  hours: string[];
 }
 
-export class AvailableMonthSlotsDto {
+export class AvailableSlotsProcedureMonthDto {
   @ApiProperty({
-    description: 'Mês de referência (formato YYYY-MM)',
+    description: 'Mês (YYYY-MM)',
     example: '2026-03',
   })
   @IsString()
@@ -38,20 +43,58 @@ export class AvailableMonthSlotsDto {
   month: string;
 
   @ApiProperty({
-    description: 'Dias e horários disponíveis dentro do mês',
-    type: [AvailableDaySlotsDto],
+    description: 'Dias do mês com horários',
+    type: [AvailableSlotsDayHoursDto],
+  })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => AvailableSlotsDayHoursDto)
+  days: AvailableSlotsDayHoursDto[];
+}
+
+export class AvailableSlotsProcedureItemDto {
+  @ApiProperty({
+    description: 'Nome do procedimento',
+    example: 'Consulta de rotina',
+  })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @ApiProperty({
+    description: 'Disponibilidade por mês',
+    type: [AvailableSlotsProcedureMonthDto],
   })
   @IsArray()
-  days: AvailableDaySlotsDto[];
+  @ValidateNested({ each: true })
+  @Type(() => AvailableSlotsProcedureMonthDto)
+  slots: AvailableSlotsProcedureMonthDto[];
 }
 
-export class AvailableSlotsResponseDto {
+export class AvailableSlotsProfessionalNameDto {
+  @ApiProperty({
+    description: 'Nome do profissional (vazio ou “Clínica” quando não filtrado por profissional)',
+    example: 'Dr. João Silva',
+  })
+  @IsString()
+  name: string;
+}
+
+export class AvailableSlotsProfessionalItemDto {
+  @ApiProperty({ type: AvailableSlotsProfessionalNameDto })
+  @ValidateNested()
+  @Type(() => AvailableSlotsProfessionalNameDto)
+  professional: AvailableSlotsProfessionalNameDto;
+
   @ApiProperty({
-    description:
-      'Meses, dias e horários disponíveis para agendamentos nos próximos três meses',
-    type: [AvailableMonthSlotsDto],
+    description: 'Um item por procedimento solicitado',
+    type: [AvailableSlotsProcedureItemDto],
   })
   @IsArray()
-  months: AvailableMonthSlotsDto[];
+  @ValidateNested({ each: true })
+  @Type(() => AvailableSlotsProcedureItemDto)
+  procedures: AvailableSlotsProcedureItemDto[];
 }
 
+/** Resposta de GET available-slots: array com um elemento (profissional + procedimentos). */
+export type AvailableSlotsGroupedResponseDto = AvailableSlotsProfessionalItemDto[];

package/src/billing/billing-response.dto.ts

@@ -1,10 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import {
-  BILLING_GATEWAYS,
-  BILLING_METHODS,
   BILLING_STATUSES,
-  BillingGatewayDto,
-  BillingMethodDto,
   BillingStatusDto,
 } from './create-billing.dto';
 
@@ -34,19 +30,11 @@ export class BillingResponseDto {
   })
   status: BillingStatusDto;
 
-  @ApiProperty({
-    description: 'Payment method',
-    enum: BILLING_METHODS,
-    example: 'PIX',
-  })
-  method: BillingMethodDto;
-
-  @ApiProperty({
-    description: 'Payment gateway',
-    enum: BILLING_GATEWAYS,
-    example: 'ASAAS',
+  @ApiPropertyOptional({
+    description: 'Payment ID from payment-gateway service (UUID)',
+    example: '550e8400-e29b-41d4-a716-446655440002',
   })
-  gateway: BillingGatewayDto;
+  paymentId?: string | null;
 
   @ApiProperty({
     description: 'Due date (ISO 8601)',

package/src/billing/create-billing.dto.ts

@@ -18,18 +18,6 @@ export const BILLING_STATUSES = [
 ] as const;
 export type BillingStatusDto = (typeof BILLING_STATUSES)[number];
 
-export const BILLING_METHODS = [
-  'PIX',
-  'CREDIT_CARD',
-  'DEBIT_CARD',
-  'VOUCHER',
-  'CASH',
-] as const;
-export type BillingMethodDto = (typeof BILLING_METHODS)[number];
-
-export const BILLING_GATEWAYS = ['ASAAS', 'MERCADO_PAGO', 'STRIPE'] as const;
-export type BillingGatewayDto = (typeof BILLING_GATEWAYS)[number];
-
 export class CreateBillingDto {
   @ApiProperty({
     description: 'Tenant ID (UUID)',
@@ -57,23 +45,13 @@ export class CreateBillingDto {
   @IsEnum(BILLING_STATUSES)
   status?: BillingStatusDto;
 
-  @ApiProperty({
-    description: 'Payment method',
-    enum: BILLING_METHODS,
-    example: 'PIX',
-  })
-  @IsEnum(BILLING_METHODS)
-  @IsNotEmpty()
-  method: BillingMethodDto;
-
-  @ApiProperty({
-    description: 'Payment gateway',
-    enum: BILLING_GATEWAYS,
-    example: 'ASAAS',
+  @ApiPropertyOptional({
+    description: 'Payment ID from payment-gateway service (UUID)',
+    example: '550e8400-e29b-41d4-a716-446655440002',
   })
-  @IsEnum(BILLING_GATEWAYS)
-  @IsNotEmpty()
-  gateway: BillingGatewayDto;
+  @IsOptional()
+  @IsUUID('4')
+  paymentId?: string;
 
   @ApiProperty({
     description: 'Due date (ISO 8601)',

package/src/billing/list-billings-query.dto.ts

@@ -1,11 +1,7 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
 import { IsEnum, IsInt, IsOptional, IsUUID, Max, Min } from 'class-validator';
 import {
-  BILLING_GATEWAYS,
-  BILLING_METHODS,
   BILLING_STATUSES,
-  BillingGatewayDto,
-  BillingMethodDto,
   BillingStatusDto,
 } from './create-billing.dto';
 
@@ -28,22 +24,12 @@ export class ListBillingsQueryDto {
   status?: BillingStatusDto;
 
   @ApiPropertyOptional({
-    description: 'Billing method filter',
-    enum: BILLING_METHODS,
-    example: 'PIX',
+    description: 'Payment ID filter (UUID)',
+    example: '550e8400-e29b-41d4-a716-446655440002',
   })
   @IsOptional()
-  @IsEnum(BILLING_METHODS)
-  method?: BillingMethodDto;
-
-  @ApiPropertyOptional({
-    description: 'Billing gateway filter',
-    enum: BILLING_GATEWAYS,
-    example: 'ASAAS',
-  })
-  @IsOptional()
-  @IsEnum(BILLING_GATEWAYS)
-  gateway?: BillingGatewayDto;
+  @IsUUID('4')
+  paymentId?: string;
 
   @ApiPropertyOptional({
     description: 'Page number (starting at 1)',

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './specialties';
 export * from './professionals';
 export * from './payments';
 export * from './billing';
+export * from './payment-gateway';
 export * from './ai';
 export * from './storage';
 export * from './notifications';

package/src/payment-gateway/create-gateway-payment.dto.ts

@@ -0,0 +1,122 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsDateString,
+  IsEnum,
+  IsNotEmpty,
+  IsNumber,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import {
+  PAYMENT_GATEWAYS,
+  PaymentGatewayDto,
+  GATEWAY_PAYMENT_METHODS,
+  GatewayPaymentMethodDto,
+} from './payment-gateway.enums';
+
+/**
+ * Optional customer data for gateway registration.
+ */
+export class GatewayCustomerDto {
+  @ApiProperty({ description: 'Customer name', example: 'John Doe' })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @ApiProperty({ description: 'Customer email', example: 'john@example.com' })
+  @IsString()
+  @IsNotEmpty()
+  email: string;
+
+  @ApiPropertyOptional({ description: 'Customer CPF/CNPJ', example: '12345678900' })
+  @IsOptional()
+  @IsString()
+  cpfCnpj?: string;
+
+  @ApiPropertyOptional({ description: 'Customer phone', example: '+5511999999999' })
+  @IsOptional()
+  @IsString()
+  phone?: string;
+}
+
+/**
+ * DTO for creating a payment through the payment gateway service.
+ */
+export class CreateGatewayPaymentDto {
+  @ApiProperty({
+    description: 'Tenant ID (UUID)',
+    example: '550e8400-e29b-41d4-a716-446655440000',
+  })
+  @IsUUID('4')
+  @IsNotEmpty()
+  tenantId: string;
+
+  @ApiProperty({
+    description: 'Billing ID from billing service (UUID)',
+    example: '550e8400-e29b-41d4-a716-446655440001',
+  })
+  @IsUUID('4')
+  @IsNotEmpty()
+  billingId: string;
+
+  @ApiProperty({
+    description: 'Payment amount',
+    example: 99.90,
+    minimum: 0.01,
+  })
+  @IsNumber()
+  @Min(0.01)
+  amount: number;
+
+  @ApiProperty({
+    description: 'Payment gateway to use',
+    enum: PAYMENT_GATEWAYS,
+    example: 'ASAAS',
+  })
+  @IsEnum(PAYMENT_GATEWAYS)
+  @IsNotEmpty()
+  gateway: PaymentGatewayDto;
+
+  @ApiProperty({
+    description: 'Payment method',
+    enum: GATEWAY_PAYMENT_METHODS,
+    example: 'PIX',
+  })
+  @IsEnum(GATEWAY_PAYMENT_METHODS)
+  @IsNotEmpty()
+  method: GatewayPaymentMethodDto;
+
+  @ApiProperty({
+    description: 'Due date (ISO 8601)',
+    example: '2026-04-15T00:00:00.000Z',
+  })
+  @IsDateString()
+  dueDate: string;
+
+  @ApiPropertyOptional({
+    description: 'Description of the payment',
+    example: 'Monthly subscription - April 2026',
+  })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiPropertyOptional({
+    description: 'Customer data for gateway registration',
+  })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => GatewayCustomerDto)
+  customer?: GatewayCustomerDto;
+
+  @ApiPropertyOptional({
+    description: 'Additional metadata as JSON',
+    example: { invoiceNumber: 'INV-001' },
+  })
+  @IsOptional()
+  metadata?: Record<string, unknown>;
+}

package/src/payment-gateway/gateway-payment-response.dto.ts

@@ -0,0 +1,65 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  PAYMENT_GATEWAYS,
+  PaymentGatewayDto,
+  GATEWAY_PAYMENT_METHODS,
+  GatewayPaymentMethodDto,
+  GATEWAY_PAYMENT_STATUSES,
+  GatewayPaymentStatusDto,
+} from './payment-gateway.enums';
+
+/**
+ * Response DTO for a gateway payment record.
+ */
+export class GatewayPaymentResponseDto {
+  @ApiProperty({ description: 'Payment ID (UUID)', example: '550e8400-e29b-41d4-a716-446655440111' })
+  id: string;
+
+  @ApiProperty({ description: 'Tenant ID (UUID)', example: '550e8400-e29b-41d4-a716-446655440000' })
+  tenantId: string;
+
+  @ApiProperty({ description: 'Billing ID (UUID)', example: '550e8400-e29b-41d4-a716-446655440001' })
+  billingId: string;
+
+  @ApiProperty({ description: 'Payment amount', example: 99.90 })
+  amount: number;
+
+  @ApiProperty({ description: 'Payment gateway', enum: PAYMENT_GATEWAYS, example: 'ASAAS' })
+  gateway: PaymentGatewayDto;
+
+  @ApiProperty({ description: 'Payment method', enum: GATEWAY_PAYMENT_METHODS, example: 'PIX' })
+  method: GatewayPaymentMethodDto;
+
+  @ApiProperty({ description: 'Payment status', enum: GATEWAY_PAYMENT_STATUSES, example: 'PENDING' })
+  status: GatewayPaymentStatusDto;
+
+  @ApiPropertyOptional({ description: 'External ID from the gateway', example: 'pay_abc123' })
+  externalId?: string | null;
+
+  @ApiPropertyOptional({ description: 'Error message if payment failed', example: null })
+  errorMessage?: string | null;
+
+  @ApiPropertyOptional({ description: 'Additional metadata', example: {} })
+  metadata?: Record<string, unknown> | null;
+
+  @ApiProperty({ description: 'Due date (ISO 8601)', example: '2026-04-15T00:00:00.000Z' })
+  dueDate: string;
+
+  @ApiPropertyOptional({ description: 'Date when payment was confirmed (ISO 8601)', example: null })
+  paidAt?: string | null;
+
+  @ApiPropertyOptional({ description: 'Payment expiration date (ISO 8601)', example: null })
+  expiresAt?: string | null;
+
+  @ApiPropertyOptional({ description: 'Refund amount if partially/fully refunded', example: null })
+  refundAmount?: number | null;
+
+  @ApiProperty({ description: 'Creation timestamp (ISO 8601)', example: '2026-03-14T12:00:00.000Z' })
+  createdAt: string;
+
+  @ApiProperty({ description: 'Last update timestamp (ISO 8601)', example: '2026-03-14T12:00:00.000Z' })
+  updatedAt: string;
+
+  @ApiPropertyOptional({ description: 'Soft deletion timestamp (ISO 8601)', example: null })
+  deletedAt?: string | null;
+}

package/src/payment-gateway/index.ts

@@ -0,0 +1,7 @@
+export * from './payment-gateway.enums';
+export * from './create-gateway-payment.dto';
+export * from './update-gateway-payment.dto';
+export * from './gateway-payment-response.dto';
+export * from './list-gateway-payments-query.dto';
+export * from './payment-gateway-kafka-topics';
+export * from './webhook-payload.dto';

package/src/payment-gateway/list-gateway-payments-query.dto.ts

@@ -0,0 +1,53 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEnum, IsInt, IsOptional, IsUUID, Max, Min } from 'class-validator';
+import {
+  PAYMENT_GATEWAYS,
+  PaymentGatewayDto,
+  GATEWAY_PAYMENT_METHODS,
+  GatewayPaymentMethodDto,
+  GATEWAY_PAYMENT_STATUSES,
+  GatewayPaymentStatusDto,
+} from './payment-gateway.enums';
+
+/**
+ * Query DTO for listing gateway payments with optional filters and pagination.
+ */
+export class ListGatewayPaymentsQueryDto {
+  @ApiPropertyOptional({ description: 'Tenant ID filter (UUID)', example: '550e8400-e29b-41d4-a716-446655440000' })
+  @IsOptional()
+  @IsUUID('4')
+  tenantId?: string;
+
+  @ApiPropertyOptional({ description: 'Billing ID filter (UUID)' })
+  @IsOptional()
+  @IsUUID('4')
+  billingId?: string;
+
+  @ApiPropertyOptional({ description: 'Gateway filter', enum: PAYMENT_GATEWAYS })
+  @IsOptional()
+  @IsEnum(PAYMENT_GATEWAYS)
+  gateway?: PaymentGatewayDto;
+
+  @ApiPropertyOptional({ description: 'Method filter', enum: GATEWAY_PAYMENT_METHODS })
+  @IsOptional()
+  @IsEnum(GATEWAY_PAYMENT_METHODS)
+  method?: GatewayPaymentMethodDto;
+
+  @ApiPropertyOptional({ description: 'Status filter', enum: GATEWAY_PAYMENT_STATUSES })
+  @IsOptional()
+  @IsEnum(GATEWAY_PAYMENT_STATUSES)
+  status?: GatewayPaymentStatusDto;
+
+  @ApiPropertyOptional({ description: 'Page number (starting at 1)', example: 1, minimum: 1, default: 1 })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ description: 'Records per page', example: 20, minimum: 1, maximum: 100, default: 20 })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+}

package/src/payment-gateway/payment-gateway-kafka-topics.ts

@@ -0,0 +1,25 @@
+/**
+ * Kafka topic names used by the payment-gateway service.
+ * Topics follow the pattern: payment.{action}
+ */
+
+/** Topic for creating a new payment through a gateway. */
+export const TOPIC_PAYMENT_CREATE = 'payment.create';
+
+/** Topic for canceling an existing payment. */
+export const TOPIC_PAYMENT_CANCEL = 'payment.cancel';
+
+/** Topic for requesting a refund. */
+export const TOPIC_PAYMENT_REFUND = 'payment.refund';
+
+/** Topic for querying payment status. */
+export const TOPIC_PAYMENT_STATUS = 'payment.status';
+
+/** Topic for listing payments (RPC). */
+export const TOPIC_PAYMENT_FIND_ALL = 'payment.findAll';
+
+/** Topic for finding a single payment (RPC). */
+export const TOPIC_PAYMENT_FIND_ONE = 'payment.findOne';
+
+/** Topic for payment webhook events (internal broadcast). */
+export const TOPIC_PAYMENT_WEBHOOK = 'payment.webhook';

package/src/payment-gateway/payment-gateway.enums.ts

@@ -0,0 +1,34 @@
+/**
+ * Supported payment gateways.
+ */
+export const PAYMENT_GATEWAYS = ['ASAAS', 'MERCADO_PAGO', 'STRIPE'] as const;
+export type PaymentGatewayDto = (typeof PAYMENT_GATEWAYS)[number];
+
+/**
+ * Payment methods supported across gateways.
+ */
+export const GATEWAY_PAYMENT_METHODS = [
+  'PIX',
+  'CREDIT_CARD',
+  'DEBIT_CARD',
+  'BOLETO',
+  'VOUCHER',
+  'CASH',
+] as const;
+export type GatewayPaymentMethodDto = (typeof GATEWAY_PAYMENT_METHODS)[number];
+
+/**
+ * Payment statuses tracked by the payment gateway.
+ */
+export const GATEWAY_PAYMENT_STATUSES = [
+  'PENDING',
+  'PROCESSING',
+  'CONFIRMED',
+  'PAYED',
+  'REFUNDED',
+  'CANCELED',
+  'FAILED',
+  'OVERDUE',
+  'EXPIRED',
+] as const;
+export type GatewayPaymentStatusDto = (typeof GATEWAY_PAYMENT_STATUSES)[number];

package/src/payment-gateway/update-gateway-payment.dto.ts

@@ -0,0 +1,7 @@
+import { PartialType } from '@nestjs/swagger';
+import { CreateGatewayPaymentDto } from './create-gateway-payment.dto';
+
+/**
+ * DTO for updating an existing gateway payment (all fields optional).
+ */
+export class UpdateGatewayPaymentDto extends PartialType(CreateGatewayPaymentDto) {}

package/src/payment-gateway/webhook-payload.dto.ts

@@ -0,0 +1,32 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEnum, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { PAYMENT_GATEWAYS, PaymentGatewayDto, GATEWAY_PAYMENT_STATUSES, GatewayPaymentStatusDto } from './payment-gateway.enums';
+
+/**
+ * Normalized webhook event payload received from any payment gateway.
+ */
+export class GatewayWebhookEventDto {
+  @ApiProperty({ description: 'Payment gateway that originated the event', enum: PAYMENT_GATEWAYS })
+  @IsEnum(PAYMENT_GATEWAYS)
+  @IsNotEmpty()
+  gateway: PaymentGatewayDto;
+
+  @ApiProperty({ description: 'Event type from the gateway', example: 'PAYMENT_RECEIVED' })
+  @IsString()
+  @IsNotEmpty()
+  eventType: string;
+
+  @ApiProperty({ description: 'External payment ID from the gateway', example: 'pay_abc123' })
+  @IsString()
+  @IsNotEmpty()
+  externalId: string;
+
+  @ApiPropertyOptional({ description: 'New payment status after the event', enum: GATEWAY_PAYMENT_STATUSES })
+  @IsOptional()
+  @IsEnum(GATEWAY_PAYMENT_STATUSES)
+  status?: GatewayPaymentStatusDto;
+
+  @ApiPropertyOptional({ description: 'Raw payload from the gateway for auditing' })
+  @IsOptional()
+  rawPayload?: Record<string, unknown>;
+}