tychat-contracts 1.0.74 → 1.0.76

package/src/conversations/followup-events.dto.ts

@@ -0,0 +1,111 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsBoolean, IsISO8601, IsOptional, IsString, IsUUID, MaxLength, MinLength } from 'class-validator';
+
+export const TOPIC_MESSAGE_SENT = 'MESSAGE_SENT';
+export const TOPIC_MESSAGE_RECEIVED = 'MESSAGE_RECEIVED';
+export const TOPIC_FOLLOWUP_CONFIG_UPDATED = 'FOLLOWUP_CONFIG_UPDATED';
+export const TOPIC_APPOINTMENT_CHANGED = 'APPOINTMENT_CHANGED';
+
+export class FollowupConversationEventPayload {
+  @ApiProperty({ example: 'homolog' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  tenant: string;
+
+  @ApiProperty({ example: '3c593727-4505-495a-a054-c052acb4cf19' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  patientId: string;
+
+  @ApiProperty({ example: 'f3f50ecb-fb71-4d4b-a0dd-910ef6e3fd0a' })
+  @IsUUID()
+  sessionUuid: string;
+
+  @ApiProperty({ required: false, example: 1 })
+  @IsOptional()
+  unitId?: number;
+
+  @ApiProperty({ example: 'ia' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(50)
+  messageType: 'ia' | 'human' | 'patient';
+
+  @ApiProperty({ required: false, example: false })
+  @IsOptional()
+  @IsBoolean()
+  isFollowup?: boolean;
+
+  @ApiProperty({ example: '2026-03-30T12:03:14.000Z' })
+  @IsISO8601()
+  occurredAt: string;
+}
+
+export class FollowupConfigUpdatedEventPayload {
+  @ApiProperty({ example: 'homolog' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  tenant: string;
+
+  @ApiProperty({ required: false, example: 1 })
+  @IsOptional()
+  unitId?: number;
+
+  @ApiProperty({
+    description: 'Serialized follow-up configuration snapshot stored in cache.',
+    type: Object,
+  })
+  config: Record<string, unknown>;
+
+  @ApiProperty({ example: '2026-03-30T12:03:14.000Z' })
+  @IsISO8601()
+  occurredAt: string;
+}
+
+export class AppointmentChangedEventPayload {
+  @ApiProperty({ example: 'homolog' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  tenant: string;
+
+  @ApiProperty({ example: 'f3f50ecb-fb71-4d4b-a0dd-910ef6e3fd0a' })
+  @IsUUID()
+  appointmentId: string;
+
+  @ApiProperty({ example: '3c593727-4505-495a-a054-c052acb4cf19' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  patientId: string;
+
+  @ApiProperty({ example: 'sended' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(50)
+  status: string;
+
+  @ApiProperty({ required: false, example: 'pending' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  previousStatus?: string;
+
+  @ApiProperty({ required: false, example: '2026-03-30T15:00:00.000Z' })
+  @IsOptional()
+  @IsISO8601()
+  date?: string;
+
+  @ApiProperty({ required: false, example: '2026-03-30T16:00:00.000Z' })
+  @IsOptional()
+  @IsISO8601()
+  exitTime?: string;
+
+  @ApiProperty({ example: '2026-03-30T12:03:14.000Z' })
+  @IsISO8601()
+  occurredAt: string;
+}
+

package/src/conversations/followup-log-response.dto.ts

@@ -12,11 +12,6 @@ export class FollowupLogResponseDto {
   @IsNotEmpty()
   id: string;
 
-  @ApiProperty({ description: 'Tenant slug', example: 'clinic-alpha' })
-  @IsString()
-  @IsNotEmpty()
-  tenant: string;
-
   @ApiPropertyOptional({ description: 'Session UUID from conversation_sessions (null for appointment-based)' })
   @IsOptional()
   @IsString()

package/src/conversations/index.ts

@@ -7,3 +7,5 @@ export * from './conversation-response.dto';
 export * from './followup-type.dto';
 export * from './followup-config-response.dto';
 export * from './followup-log-response.dto';
+export * from './satisfaction-response.dto';
+export * from './followup-events.dto';

package/src/conversations/satisfaction-response.dto.ts

@@ -0,0 +1,116 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsInt,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Max,
+  MaxLength,
+  Min,
+} from 'class-validator';
+
+/** Valid satisfaction survey types. */
+export const SATISFACTION_TYPES = [
+  'satisfaction_booking',
+  'satisfaction_finished',
+] as const;
+
+export type SatisfactionTypeDto = (typeof SATISFACTION_TYPES)[number];
+
+/**
+ * Payload to save a patient's satisfaction rating.
+ * Sent from the conversation-service to the followup-service
+ * when the AI detects a numeric satisfaction response.
+ */
+export class SaveSatisfactionRequestDto {
+  @ApiProperty({ description: 'Tenant slug', example: 'clinic-alpha' })
+  @IsString()
+  @IsNotEmpty()
+  tenant: string;
+
+  @ApiProperty({ description: 'Patient UUID' })
+  @IsString()
+  @IsNotEmpty()
+  patientId: string;
+
+  @ApiProperty({ description: 'Appointment UUID linked to the satisfaction survey' })
+  @IsString()
+  @IsNotEmpty()
+  appointmentId: string;
+
+  @ApiProperty({
+    description: 'Type of satisfaction survey',
+    enum: SATISFACTION_TYPES,
+    example: 'satisfaction_booking',
+  })
+  @IsIn(SATISFACTION_TYPES)
+  satisfactionType: SatisfactionTypeDto;
+
+  @ApiProperty({ description: 'Patient satisfaction rating (1-5)', example: 4 })
+  @IsInt()
+  @Min(1)
+  @Max(5)
+  rating: number;
+
+  @ApiPropertyOptional({ description: 'Optional text comment from the patient', example: 'Otimo atendimento!' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  comment?: string;
+}
+
+/**
+ * Response DTO for a saved satisfaction rating.
+ */
+export class SatisfactionResponseDto {
+  @ApiProperty({ description: 'Primary key (UUID)' })
+  @IsString()
+  @IsNotEmpty()
+  id: string;
+
+  @ApiProperty({ description: 'Patient UUID' })
+  @IsString()
+  @IsNotEmpty()
+  patientId: string;
+
+  @ApiProperty({ description: 'Appointment UUID' })
+  @IsString()
+  @IsNotEmpty()
+  appointmentId: string;
+
+  @ApiProperty({
+    description: 'Type of satisfaction survey',
+    enum: SATISFACTION_TYPES,
+    example: 'satisfaction_finished',
+  })
+  @IsIn(SATISFACTION_TYPES)
+  satisfactionType: SatisfactionTypeDto;
+
+  @ApiProperty({ description: 'Patient satisfaction rating (1-5)', example: 5 })
+  @IsInt()
+  @Min(1)
+  @Max(5)
+  rating: number;
+
+  @ApiPropertyOptional({ description: 'Optional text comment from the patient' })
+  @IsOptional()
+  @IsString()
+  comment?: string | null;
+
+  @ApiProperty({ description: 'Timestamp when the response was recorded (ISO 8601)' })
+  @IsString()
+  @IsNotEmpty()
+  createdAt: string;
+}
+
+/**
+ * Response DTO for average satisfaction stats.
+ */
+export class SatisfactionAverageDto {
+  @ApiProperty({ description: 'Average rating', example: 4.2 })
+  average: number;
+
+  @ApiProperty({ description: 'Total number of responses', example: 42 })
+  count: number;
+}

package/src/tenants/index.ts

@@ -1,3 +1,5 @@
 export * from './update-tenant-environment-url.dto';
 export * from './get-tenant-by-address.query.dto';
 export * from './tenant-public-by-address-response.dto';
+export * from './whatsapp-provider-kind.dto';
+export * from './tenant-slug.util';

package/src/tenants/tenant-slug.util.ts

@@ -0,0 +1,56 @@
+/**
+ * Utility functions for tenant slug <-> domain transformations.
+ *
+ * Convention:
+ * - Slugs stored in DB use underscores for word separation (e.g. "clinica_sampaio")
+ *   or are single words (e.g. "homolog"). Hyphens are NOT allowed in slugs.
+ * - DNS hostnames use hyphens (underscores are invalid in DNS labels).
+ * - Conversion is bijective: slug "clinica_sampaio" <-> domain "clinica-sampaio"
+ *
+ * Examples:
+ * - Slug "homolog"          -> domain segment "homolog"           -> slug "homolog"
+ * - Slug "clinica_sampaio"  -> domain segment "clinica-sampaio"   -> slug "clinica_sampaio"
+ */
+
+/**
+ * Converts a tenant slug to a DNS-safe domain segment.
+ * Replaces underscores with hyphens and lowercases the result.
+ *
+ * @example slugToDomainSegment("clinica_sampaio") // "clinica-sampaio"
+ * @example slugToDomainSegment("homolog")         // "homolog"
+ */
+export function slugToDomainSegment(slug: string): string {
+  return (slug || 'default').toLowerCase().replace(/_/g, '-');
+}
+
+/**
+ * Converts a domain segment back to the tenant slug.
+ * Replaces hyphens with underscores (the stored DB format).
+ *
+ * @example domainSegmentToSlug("clinica-sampaio") // "clinica_sampaio"
+ * @example domainSegmentToSlug("homolog")         // "homolog"
+ */
+export function domainSegmentToSlug(domainSegment: string): string {
+  return (domainSegment || 'default').toLowerCase().replace(/-/g, '_');
+}
+
+/**
+ * Regex pattern that validates an acceptable tenant slug.
+ * Allows lowercase alphanumeric characters and underscores only (no hyphens).
+ * Must start and end with an alphanumeric character.
+ * Single-character slugs (e.g. "a") are allowed.
+ * Max 63 chars (DNS label limit after _ -> - conversion).
+ */
+export const TENANT_SLUG_REGEX = /^[a-z0-9]([a-z0-9_]*[a-z0-9])?$/;
+
+/**
+ * Validates whether a slug is acceptable.
+ * Rules:
+ * - Only lowercase letters, digits, and underscores (no hyphens)
+ * - Must start and end with a letter or digit
+ * - Length between 1 and 63 characters
+ */
+export function isValidTenantSlug(slug: string): boolean {
+  if (!slug || slug.length > 63) return false;
+  return TENANT_SLUG_REGEX.test(slug.toLowerCase());
+}

package/src/tenants/whatsapp-provider-kind.dto.ts

@@ -0,0 +1,12 @@
+/**
+ * Supported WhatsApp provider types for tenant instance provisioning.
+ *
+ * - `evolution_api`: Evolution API v2 (Baileys-based unofficial).
+ * - `whatsapp_official`: Meta Cloud API (official WhatsApp Business).
+ */
+export const WHATSAPP_PROVIDER_KINDS = [
+  'evolution_api',
+  'whatsapp_official',
+] as const;
+
+export type WhatsAppProviderKindDto = (typeof WHATSAPP_PROVIDER_KINDS)[number];