elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/appointments/dto/create-appointment.dto.ts

@@ -0,0 +1,72 @@
+import {
+  IsString,
+  IsOptional,
+  IsInt,
+  IsIn,
+  IsDateString,
+  Min,
+  MaxLength,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateAppointmentDto {
+  @ApiProperty({ description: 'Patient ID' })
+  @IsString()
+  patientId: string;
+
+  @ApiProperty({ description: 'Clinic ID' })
+  @IsString()
+  clinicId: string;
+
+  @ApiPropertyOptional({ description: 'Doctor (user) ID' })
+  @IsOptional()
+  @IsString()
+  doctorId?: string;
+
+  @ApiPropertyOptional({ description: 'Treatment ID' })
+  @IsOptional()
+  @IsString()
+  treatmentId?: string;
+
+  @ApiPropertyOptional({ description: 'Treatment plan item ID' })
+  @IsOptional()
+  @IsString()
+  treatmentPlanItemId?: string;
+
+  @ApiProperty({ example: '2026-04-10T09:00:00.000Z', description: 'Start time (ISO 8601)' })
+  @IsDateString()
+  startTime: string;
+
+  @ApiProperty({ example: '2026-04-10T09:30:00.000Z', description: 'End time (ISO 8601)' })
+  @IsDateString()
+  endTime: string;
+
+  @ApiProperty({ example: 30, description: 'Duration in minutes' })
+  @IsInt()
+  @Min(1)
+  durationMinutes: number;
+
+  @ApiPropertyOptional({
+    example: 'appointment',
+    enum: ['appointment', 'walk_in', 'follow_up', 'consultation'],
+    default: 'appointment',
+  })
+  @IsOptional()
+  @IsIn(['appointment', 'walk_in', 'follow_up', 'consultation'])
+  type?: string;
+
+  @ApiPropertyOptional({
+    example: 'dashboard',
+    enum: ['whatsapp', 'voice_call', 'dashboard', 'walk_in'],
+    default: 'dashboard',
+  })
+  @IsOptional()
+  @IsIn(['whatsapp', 'voice_call', 'dashboard', 'walk_in'])
+  source?: string;
+
+  @ApiPropertyOptional({ example: 'Patient prefers morning slots' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  notes?: string;
+}

package/nestjs/src/appointments/dto/index.ts

@@ -0,0 +1,4 @@
+export { CreateAppointmentDto } from './create-appointment.dto';
+export { UpdateAppointmentDto } from './update-appointment.dto';
+export { UpdateStatusDto } from './update-status.dto';
+export { QueryAppointmentsDto } from './query-appointments.dto';

package/nestjs/src/appointments/dto/query-appointments.dto.ts

@@ -0,0 +1,60 @@
+import { IsString, IsOptional, IsIn } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class QueryAppointmentsDto {
+  @ApiPropertyOptional({ example: '1', default: '1' })
+  @IsOptional()
+  @IsString()
+  page?: string;
+
+  @ApiPropertyOptional({ example: '25', default: '25' })
+  @IsOptional()
+  @IsString()
+  limit?: string;
+
+  @ApiPropertyOptional({ description: 'Filter by clinic ID' })
+  @IsOptional()
+  @IsString()
+  clinicId?: string;
+
+  @ApiPropertyOptional({ description: 'Filter by doctor ID' })
+  @IsOptional()
+  @IsString()
+  doctorId?: string;
+
+  @ApiPropertyOptional({ description: 'Filter by patient ID' })
+  @IsOptional()
+  @IsString()
+  patientId?: string;
+
+  @ApiPropertyOptional({
+    enum: ['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show'],
+  })
+  @IsOptional()
+  @IsIn(['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show'])
+  status?: string;
+
+  @ApiPropertyOptional({
+    enum: ['appointment', 'walk_in', 'follow_up', 'consultation'],
+  })
+  @IsOptional()
+  @IsIn(['appointment', 'walk_in', 'follow_up', 'consultation'])
+  type?: string;
+
+  @ApiPropertyOptional({
+    enum: ['whatsapp', 'voice_call', 'dashboard', 'walk_in'],
+  })
+  @IsOptional()
+  @IsIn(['whatsapp', 'voice_call', 'dashboard', 'walk_in'])
+  source?: string;
+
+  @ApiPropertyOptional({ example: '2026-04-01', description: 'From date (inclusive, ISO date)' })
+  @IsOptional()
+  @IsString()
+  from?: string;
+
+  @ApiPropertyOptional({ example: '2026-04-30', description: 'To date (inclusive, ISO date)' })
+  @IsOptional()
+  @IsString()
+  to?: string;
+}

package/nestjs/src/appointments/dto/update-appointment.dto.ts

@@ -0,0 +1,43 @@
+import {
+  IsString,
+  IsOptional,
+  IsInt,
+  IsDateString,
+  Min,
+  MaxLength,
+} from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class UpdateAppointmentDto {
+  @ApiPropertyOptional({ description: 'Doctor (user) ID' })
+  @IsOptional()
+  @IsString()
+  doctorId?: string;
+
+  @ApiPropertyOptional({ description: 'Treatment ID' })
+  @IsOptional()
+  @IsString()
+  treatmentId?: string;
+
+  @ApiPropertyOptional({ example: '2026-04-10T09:00:00.000Z', description: 'Start time (ISO 8601)' })
+  @IsOptional()
+  @IsDateString()
+  startTime?: string;
+
+  @ApiPropertyOptional({ example: '2026-04-10T09:30:00.000Z', description: 'End time (ISO 8601)' })
+  @IsOptional()
+  @IsDateString()
+  endTime?: string;
+
+  @ApiPropertyOptional({ example: 30, description: 'Duration in minutes' })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  durationMinutes?: number;
+
+  @ApiPropertyOptional({ example: 'Rescheduled by patient request' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  notes?: string;
+}

package/nestjs/src/appointments/dto/update-status.dto.ts

@@ -0,0 +1,18 @@
+import { IsString, IsOptional, IsIn, MaxLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class UpdateStatusDto {
+  @ApiProperty({
+    example: 'confirmed',
+    enum: ['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show'],
+  })
+  @IsString()
+  @IsIn(['scheduled', 'confirmed', 'in_progress', 'completed', 'cancelled', 'no_show'])
+  status: string;
+
+  @ApiPropertyOptional({ example: 'Patient did not show up', description: 'Reason for cancellation' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000)
+  cancelledReason?: string;
+}

package/nestjs/src/appointments/processors/reminder.processor.ts

@@ -0,0 +1,243 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { Job } from 'bullmq';
+import { PrismaService } from '../../database/prisma.service.js';
+import { EncryptionService } from '../../integrations/encryption/encryption.service.js';
+import { MetaWhatsAppService } from '../../integrations/meta-business/meta-whatsapp.service.js';
+
+/**
+ * Runs every hour (repeatable job).
+ * Sends WhatsApp reminder messages for upcoming appointments:
+ *  - 24h reminder: appt_start_time between now+23h and now+25h
+ *  - 2h reminder:  appt_start_time between now+1.5h and now+2.5h
+ */
+@Processor('appointment-reminder')
+export class ReminderProcessor extends WorkerHost {
+  private readonly logger = new Logger(ReminderProcessor.name);
+  private readonly tokenEncryptionKey: string;
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly config: ConfigService,
+    private readonly encryption: EncryptionService,
+    private readonly metaWhatsApp: MetaWhatsAppService,
+  ) {
+    super();
+    this.tokenEncryptionKey = this.config.get<string>(
+      'META_TOKEN_ENCRYPTION_KEY',
+      '',
+    );
+  }
+
+  async process(_job: Job): Promise<void> {
+    this.logger.debug('Running appointment reminder sweep');
+
+    try {
+      const now = new Date();
+      const h23 = new Date(now.getTime() + 23 * 60 * 60 * 1000);
+      const h25 = new Date(now.getTime() + 25 * 60 * 60 * 1000);
+      const h1_5 = new Date(now.getTime() + 1.5 * 60 * 60 * 1000);
+      const h2_5 = new Date(now.getTime() + 2.5 * 60 * 60 * 1000);
+
+      // Find appointments needing 24h or 2h reminders
+      const appointments = await this.prisma.appointment.findMany({
+        where: {
+          appt_status: { in: ['scheduled', 'confirmed'] },
+          OR: [
+            {
+              appt_start_time: { gte: h23, lte: h25 },
+              appt_reminder_sent_24h: false,
+            },
+            {
+              appt_start_time: { gte: h1_5, lte: h2_5 },
+              appt_reminder_sent_2h: false,
+            },
+          ],
+        },
+        include: {
+          patient: {
+            select: {
+              patient_id: true,
+              patient_display_name: true,
+              patient_phone: true,
+            },
+          },
+          clinic: {
+            select: {
+              clinic_id: true,
+              clinic_name: true,
+              clinic_timezone: true,
+            },
+          },
+        },
+      });
+
+      if (appointments.length === 0) {
+        this.logger.debug('No appointments needing reminders');
+        return;
+      }
+
+      this.logger.log(
+        `Appointment reminders: processing ${appointments.length} appointments`,
+      );
+
+      let sentCount = 0;
+      let failCount = 0;
+
+      for (const appt of appointments) {
+        try {
+          const is24h =
+            appt.appt_start_time >= h23 &&
+            appt.appt_start_time <= h25 &&
+            !appt.appt_reminder_sent_24h;
+
+          const is2h =
+            appt.appt_start_time >= h1_5 &&
+            appt.appt_start_time <= h2_5 &&
+            !appt.appt_reminder_sent_2h;
+
+          if (!is24h && !is2h) {
+            continue;
+          }
+
+          // Get the clinic's active WhatsApp Meta connection
+          const metaConnection = await this.prisma.clinicMetaConnection.findFirst({
+            where: {
+              meta_clinic_id: appt.clinic.clinic_id,
+              meta_type: 'whatsapp',
+              meta_is_active: true,
+            },
+          });
+
+          if (
+            !metaConnection?.meta_phone_number_id ||
+            !metaConnection?.meta_encrypted_access_token
+          ) {
+            this.logger.warn(
+              `No active Meta WhatsApp connection for clinic ${appt.clinic.clinic_id}, ` +
+                `skipping reminder for appointment ${appt.appt_id}`,
+            );
+            failCount++;
+            continue;
+          }
+
+          // Decrypt the access token
+          let accessToken: string;
+          try {
+            accessToken = this.tokenEncryptionKey
+              ? this.encryption.decrypt(
+                  metaConnection.meta_encrypted_access_token,
+                  this.tokenEncryptionKey,
+                )
+              : metaConnection.meta_encrypted_access_token;
+          } catch {
+            // Fallback: token might not be encrypted in dev environments
+            accessToken = metaConnection.meta_encrypted_access_token;
+          }
+
+          const patientName =
+            appt.patient?.patient_display_name ||
+            appt.appt_patient_name ||
+            'Hasta';
+          const patientPhone = appt.patient?.patient_phone || appt.appt_patient_phone;
+
+          if (!patientPhone) {
+            this.logger.warn(
+              `No phone number for appointment ${appt.appt_id}, skipping reminder`,
+            );
+            failCount++;
+            continue;
+          }
+
+          // Format the appointment time in the clinic's timezone
+          const timeStr = this.formatTime(
+            appt.appt_start_time,
+            appt.clinic.clinic_timezone ?? 'Europe/Istanbul',
+          );
+
+          const clinicName = appt.clinic.clinic_name;
+
+          // Build and send the reminder message
+          if (is24h) {
+            const message =
+              `Merhaba ${patientName}, yarin saat ${timeStr} randevunuz bulunmaktadir. ${clinicName}`;
+
+            await this.metaWhatsApp.sendMessage(
+              metaConnection.meta_phone_number_id,
+              patientPhone,
+              message,
+              accessToken,
+            );
+
+            await this.prisma.appointment.update({
+              where: { appt_id: appt.appt_id },
+              data: { appt_reminder_sent_24h: true },
+            });
+
+            sentCount++;
+            this.logger.debug(
+              `Sent 24h reminder for appointment ${appt.appt_id} to ${patientPhone}`,
+            );
+          }
+
+          if (is2h) {
+            const message =
+              `Merhaba ${patientName}, 2 saat sonra saat ${timeStr} randevunuz var. ${clinicName}`;
+
+            await this.metaWhatsApp.sendMessage(
+              metaConnection.meta_phone_number_id,
+              patientPhone,
+              message,
+              accessToken,
+            );
+
+            await this.prisma.appointment.update({
+              where: { appt_id: appt.appt_id },
+              data: { appt_reminder_sent_2h: true },
+            });
+
+            sentCount++;
+            this.logger.debug(
+              `Sent 2h reminder for appointment ${appt.appt_id} to ${patientPhone}`,
+            );
+          }
+        } catch (error) {
+          failCount++;
+          this.logger.error(
+            `Failed to send reminder for appointment ${appt.appt_id}: ${(error as Error).message}`,
+          );
+          // Continue with next appointment
+        }
+      }
+
+      this.logger.log(
+        `Appointment reminders complete: ${sentCount} sent, ${failCount} failed out of ${appointments.length}`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Appointment reminder sweep failed: ${(error as Error).message}`,
+        (error as Error).stack,
+      );
+      throw error;
+    }
+  }
+
+  /** Format a Date as HH:MM in the given timezone. */
+  private formatTime(date: Date, timezone: string): string {
+    try {
+      const formatter = new Intl.DateTimeFormat('tr-TR', {
+        timeZone: timezone,
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+      });
+      return formatter.format(date);
+    } catch {
+      // Fallback if timezone is invalid
+      const h = date.getHours().toString().padStart(2, '0');
+      const m = date.getMinutes().toString().padStart(2, '0');
+      return `${h}:${m}`;
+    }
+  }
+}

package/nestjs/src/audit/audit.controller.ts

@@ -0,0 +1,84 @@
+import {
+  Controller,
+  Get,
+  Param,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth, ApiQuery } from '@nestjs/swagger';
+import { AuditService } from './audit.service';
+import { JwtAuthGuard, PermissionsGuard } from '../common/guards';
+import { CurrentUser, Permissions } from '../common/decorators';
+import type { JwtPayload } from '../common/interfaces/jwt-payload.interface';
+
+@ApiTags('Audit Logs')
+@Controller('audit-logs')
+@UseGuards(JwtAuthGuard, PermissionsGuard)
+@ApiBearerAuth()
+export class AuditController {
+  constructor(private readonly auditService: AuditService) {}
+
+  @Get()
+  @Permissions('audit:read')
+  @ApiOperation({ summary: 'List audit logs (tenant-scoped, paginated)' })
+  @ApiQuery({ name: 'action', required: false })
+  @ApiQuery({ name: 'entity', required: false })
+  @ApiQuery({ name: 'userId', required: false })
+  @ApiQuery({ name: 'clinicId', required: false })
+  @ApiQuery({ name: 'from', required: false, description: 'ISO date string' })
+  @ApiQuery({ name: 'to', required: false, description: 'ISO date string' })
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async findAll(
+    @CurrentUser() user: JwtPayload,
+    @Query('action') action?: string,
+    @Query('entity') entity?: string,
+    @Query('userId') userId?: string,
+    @Query('clinicId') clinicId?: string,
+    @Query('from') from?: string,
+    @Query('to') to?: string,
+    @Query('page') page?: string,
+    @Query('limit') limit?: string,
+  ) {
+    // Superadmin sees all; tenant-scoped users only see their tenant's logs
+    const tenantId =
+      user.role === 'superadmin' ? undefined : user.tenantId ?? undefined;
+
+    return this.auditService.findAll(tenantId, {
+      action,
+      entity,
+      userId,
+      clinicId,
+      from,
+      to,
+      page: page ? parseInt(page, 10) : 1,
+      limit: limit ? parseInt(limit, 10) : 50,
+    });
+  }
+
+  @Get('entity/:entity/:entityId')
+  @Permissions('audit:read')
+  @ApiOperation({ summary: 'Get audit history for a specific entity' })
+  async findByEntity(
+    @Param('entity') entity: string,
+    @Param('entityId') entityId: string,
+  ) {
+    return this.auditService.findByEntity(entity, entityId);
+  }
+
+  @Get('user/:userId')
+  @Permissions('audit:read')
+  @ApiOperation({ summary: 'Get all audit logs for a user' })
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async findByUser(
+    @Param('userId') userId: string,
+    @Query('page') page?: string,
+    @Query('limit') limit?: string,
+  ) {
+    return this.auditService.findByUser(userId, {
+      page: page ? parseInt(page, 10) : 1,
+      limit: limit ? parseInt(limit, 10) : 50,
+    });
+  }
+}

package/nestjs/src/audit/audit.decorator.ts

@@ -0,0 +1,20 @@
+import { applyDecorators, SetMetadata, UseInterceptors } from '@nestjs/common';
+import { AuditInterceptor } from './audit.interceptor';
+
+export const AUDIT_ACTION_KEY = 'audit_action';
+export const AUDIT_ENTITY_KEY = 'audit_entity';
+
+/**
+ * Marks a controller method for automatic audit logging.
+ * Use on mutating endpoints (POST, PUT, DELETE).
+ *
+ * @param action - e.g. 'create', 'update', 'delete'
+ * @param entity - e.g. 'patient', 'tenant', 'clinic'
+ */
+export function Auditable(action: string, entity: string) {
+  return applyDecorators(
+    SetMetadata(AUDIT_ACTION_KEY, action),
+    SetMetadata(AUDIT_ENTITY_KEY, entity),
+    UseInterceptors(AuditInterceptor),
+  );
+}

package/nestjs/src/audit/audit.interceptor.ts

@@ -0,0 +1,67 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Logger,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable, tap } from 'rxjs';
+import { AuditService } from './audit.service';
+import { AUDIT_ACTION_KEY, AUDIT_ENTITY_KEY } from './audit.decorator';
+import type { JwtPayload } from '../common/interfaces/jwt-payload.interface';
+
+@Injectable()
+export class AuditInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(AuditInterceptor.name);
+
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly auditService: AuditService,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const action = this.reflector.get<string>(
+      AUDIT_ACTION_KEY,
+      context.getHandler(),
+    );
+    const entity = this.reflector.get<string>(
+      AUDIT_ENTITY_KEY,
+      context.getHandler(),
+    );
+
+    if (!action || !entity) {
+      return next.handle();
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user as JwtPayload | undefined;
+    const entityId =
+      request.params?.id ?? request.params?.entityId ?? 'unknown';
+
+    return next.handle().pipe(
+      tap({
+        next: (responseBody) => {
+          this.auditService
+            .log({
+              tenantId: user?.tenantId ?? undefined,
+              userId: user?.sub,
+              userRole: user?.role,
+              action,
+              entity,
+              entityId: String(entityId),
+              ip: request.ip,
+              userAgent: request.headers?.['user-agent'],
+              requestId: request.id,
+            })
+            .catch((err) =>
+              this.logger.error('Failed to write audit log', err),
+            );
+        },
+        error: () => {
+          // Do not audit failed requests
+        },
+      }),
+    );
+  }
+}

package/nestjs/src/audit/audit.interfaces.ts

@@ -0,0 +1,15 @@
+export interface AuditEvent {
+  tenantId?: string;
+  clinicId?: string;
+  userId?: string;
+  userEmail?: string;
+  userRole?: string;
+  action: string;
+  entity: string;
+  entityId: string;
+  changes?: Record<string, { old: any; new: any }> | null;
+  ip?: string;
+  userAgent?: string;
+  requestId?: string;
+  reason?: string;
+}

package/nestjs/src/audit/audit.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { AuditController } from './audit.controller';
+import { AuditService } from './audit.service';
+import { AuditInterceptor } from './audit.interceptor';
+
+@Global()
+@Module({
+  controllers: [AuditController],
+  providers: [AuditService, AuditInterceptor],
+  exports: [AuditService, AuditInterceptor],
+})
+export class AuditModule {}