elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/tools/handlers/validation.tools.ts

@@ -0,0 +1,152 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Tool } from '../tool.decorator.js';
+import type { ToolContext, ToolResult } from '../tool.interfaces.js';
+import { PrismaService } from '../../database/prisma.service.js';
+
+@Injectable()
+export class ValidationTools {
+  private readonly logger = new Logger(ValidationTools.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+  ) {}
+
+  @Tool({
+    name: 'confirm_appointment_validation',
+    description: 'Record patient confirmation/cancellation/reschedule during appointment validation call',
+    parameters: {
+      type: 'object',
+      properties: {
+        result: {
+          type: 'string',
+          enum: ['confirmed', 'cancelled', 'reschedule'],
+          description: 'Validation result from the patient',
+        },
+        reschedule_request: {
+          type: 'string',
+          description: 'Patient reschedule preference (if result is reschedule)',
+        },
+        patient_message: {
+          type: 'string',
+          description: 'Additional message from the patient',
+        },
+      },
+      required: ['result'],
+    },
+    requiredFeatures: ['appointment_validation'],
+    channels: ['voice_call'],
+  })
+  async confirmAppointmentValidation(
+    ctx: ToolContext,
+    params: {
+      result: 'confirmed' | 'cancelled' | 'reschedule';
+      reschedule_request?: string;
+      patient_message?: string;
+    },
+  ): Promise<ToolResult> {
+    try {
+      const conversationId = ctx.channelMetadata.conversationId;
+      if (!conversationId) {
+        return {
+          data: 'No conversation ID found in context — cannot identify validation entry',
+          isError: true,
+        };
+      }
+
+      // Find validation entry by conversation_id
+      const entry = await this.prisma.appointmentValidationEntry.findFirst({
+        where: { bentry_conversation_id: conversationId },
+        include: {
+          batch: {
+            select: {
+              batch_tenant_id: true,
+            },
+          },
+        },
+      });
+
+      if (!entry) {
+        return {
+          data: `No validation entry found for conversation ${conversationId}`,
+          isError: true,
+        };
+      }
+
+      // Verify tenant ownership
+      if (entry.batch.batch_tenant_id !== ctx.tenantId) {
+        return {
+          data: 'Validation entry does not belong to this tenant',
+          isError: true,
+        };
+      }
+
+      // Update the entry with validation result
+      await this.prisma.appointmentValidationEntry.update({
+        where: { bentry_id: entry.bentry_id },
+        data: {
+          bentry_validation_result: params.result as any,
+          bentry_call_status: 'completed',
+          ...(params.reschedule_request && {
+            bentry_reschedule_request: params.reschedule_request,
+          }),
+          ...(params.patient_message && {
+            bentry_patient_message: params.patient_message,
+          }),
+          bentry_result_at: new Date(),
+        },
+      });
+
+      // If this entry is linked to an appointment, update appointment status too
+      if (entry.bentry_appointment_id) {
+        try {
+          if (params.result === 'confirmed') {
+            await this.prisma.appointment.update({
+              where: { appt_id: entry.bentry_appointment_id },
+              data: { appt_status: 'confirmed' },
+            });
+          } else if (params.result === 'cancelled') {
+            await this.prisma.appointment.update({
+              where: { appt_id: entry.bentry_appointment_id },
+              data: {
+                appt_status: 'cancelled',
+                appt_cancelled_at: new Date(),
+                appt_notes: params.patient_message
+                  ? `[Validation Call] ${params.patient_message}`
+                  : '[Validation Call] Cancelled by patient',
+              },
+            });
+          }
+          // For 'reschedule', leave the appointment as-is; staff will handle it manually
+        } catch (apptErr: any) {
+          // Fire-and-forget: log but don't fail the tool result
+          this.logger.warn(
+            `Failed to update linked appointment ${entry.bentry_appointment_id}: ${apptErr.message}`,
+          );
+        }
+      }
+
+      this.logger.log(
+        `Validation result recorded: ${params.result} for conversation ${conversationId} (entry=${entry.bentry_id})`,
+      );
+
+      return {
+        data: {
+          recorded: true,
+          result: params.result,
+          entry_id: entry.bentry_id,
+          appointment_updated: !!entry.bentry_appointment_id,
+        },
+        isError: false,
+      };
+    } catch (err: any) {
+      this.logger.error(
+        `confirm_appointment_validation failed: ${err.message}`,
+        err.stack,
+      );
+      return {
+        data: err.message ?? 'Failed to record validation result',
+        isError: true,
+      };
+    }
+  }
+}

package/nestjs/src/tools/tool-registry.service.ts

@@ -0,0 +1,221 @@
+import {
+  Injectable,
+  Logger,
+  OnModuleInit,
+  NotFoundException,
+} from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { PrismaService } from '../database/prisma.service.js';
+import { TOOL_METADATA_KEY, type ToolDefinition } from './tool.decorator.js';
+import type { ToolContext, ToolResult, RegisteredTool } from './tool.interfaces.js';
+import type { AIToolDefinition } from '../integrations/ai/ai.interface.js';
+
+@Injectable()
+export class ToolRegistryService implements OnModuleInit {
+  private readonly logger = new Logger(ToolRegistryService.name);
+  private readonly tools = new Map<string, RegisteredTool>();
+
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly reflector: Reflector,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /* ------------------------------------------------------------------ */
+  /*  BOOTSTRAP — discover all @Tool() decorated methods                 */
+  /* ------------------------------------------------------------------ */
+
+  onModuleInit() {
+    const wrappers = this.discovery.getProviders();
+
+    for (const wrapper of wrappers) {
+      let instance: any;
+      try {
+        instance = wrapper.instance;
+      } catch {
+        continue;
+      }
+
+      if (!instance || typeof instance !== 'object') continue;
+
+      let prototype: any;
+      try {
+        prototype = Object.getPrototypeOf(instance);
+      } catch {
+        continue;
+      }
+      if (!prototype) continue;
+
+      // Skip non-application classes (BullMQ queues, adapters, etc.)
+      const className = prototype?.constructor?.name ?? '';
+      if (['Queue', 'Worker', 'FlowProducer', 'Redis', 'EventEmitter2'].includes(className)) {
+        continue;
+      }
+
+      let methodNames: string[];
+      try {
+        methodNames = Object.getOwnPropertyNames(prototype).filter(
+          (m) => m !== 'constructor' && typeof prototype[m] === 'function',
+        );
+      } catch {
+        continue;
+      }
+
+      for (const methodName of methodNames) {
+        const definition = this.reflector.get<ToolDefinition>(
+          TOOL_METADATA_KEY,
+          prototype[methodName],
+        );
+
+        if (!definition) continue;
+
+        if (this.tools.has(definition.name)) {
+          this.logger.warn(
+            `Duplicate tool name "${definition.name}" — overwriting`,
+          );
+        }
+
+        this.tools.set(definition.name, {
+          definition,
+          instance,
+          method: prototype[methodName].bind(instance),
+        });
+
+        this.logger.log(`Registered tool: ${definition.name}`);
+      }
+    }
+
+    this.logger.log(`Total tools registered: ${this.tools.size}`);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  QUERY                                                              */
+  /* ------------------------------------------------------------------ */
+
+  /** Return ALL enabled tool definitions (for admin UI picker). */
+  getAllTools(): ToolDefinition[] {
+    return [...this.tools.values()]
+      .filter((t) => t.definition.enabled !== false)
+      .map((t) => t.definition);
+  }
+
+  /** Return tool definitions available for given feature flags + channel */
+  getAvailableTools(
+    features: string[],
+    channel: string,
+  ): ToolDefinition[] {
+    const result: ToolDefinition[] = [];
+
+    for (const { definition } of this.tools.values()) {
+      // Skip disabled tools
+      if (definition.enabled === false) continue;
+
+      // Check required features
+      if (definition.requiredFeatures?.length) {
+        const hasAll = definition.requiredFeatures.every((f) =>
+          features.includes(f),
+        );
+        if (!hasAll) continue;
+      }
+
+      // Check channel restriction
+      if (definition.channels?.length) {
+        if (!definition.channels.includes(channel)) continue;
+      }
+
+      result.push(definition);
+    }
+
+    return result;
+  }
+
+  /**
+   * Return tools as AIToolDefinition[] for use with AIService.converse().
+   * Filters by tenant features + channel.
+   */
+  getAITools(features: string[], channel: string): AIToolDefinition[] {
+    return this.getAvailableTools(features, channel).map((def) => ({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+    }));
+  }
+
+  /**
+   * Create an onToolCall handler for AIService.converse().
+   * Executes the matching registered tool and returns the result as JSON string.
+   */
+  createToolCallHandler(ctx: ToolContext): (name: string, args: Record<string, any>) => Promise<string> {
+    return async (name: string, args: Record<string, any>): Promise<string> => {
+      const result = await this.execute(name, ctx, args);
+      return JSON.stringify(result.data);
+    };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  EXECUTE                                                            */
+  /* ------------------------------------------------------------------ */
+
+  async execute(
+    toolName: string,
+    ctx: ToolContext,
+    params: Record<string, any>,
+  ): Promise<ToolResult> {
+    const registered = this.tools.get(toolName);
+    if (!registered) {
+      throw new NotFoundException(`Unknown tool: ${toolName}`);
+    }
+
+    const startMs = Date.now();
+    let result: ToolResult;
+
+    try {
+      result = await registered.method(ctx, params);
+    } catch (err: any) {
+      result = {
+        data: err.message ?? 'Tool execution failed',
+        isError: true,
+      };
+    }
+
+    const durationMs = Date.now() - startMs;
+
+    // Fire-and-forget log to tool_execution_logs
+    this.logExecution(toolName, ctx, params, result, durationMs).catch(
+      (logErr) =>
+        this.logger.error(
+          `Failed to log tool execution: ${logErr.message}`,
+        ),
+    );
+
+    return result;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  INTERNAL — persist execution log                                   */
+  /* ------------------------------------------------------------------ */
+
+  private async logExecution(
+    toolName: string,
+    ctx: ToolContext,
+    params: Record<string, any>,
+    result: ToolResult,
+    durationMs: number,
+  ): Promise<void> {
+    await this.prisma.toolExecutionLog.create({
+      data: {
+        toollog_tenant_id: ctx.tenantId,
+        toollog_clinic_id: ctx.clinicId,
+        toollog_tool_name: toolName,
+        toollog_channel: ctx.channel,
+        toollog_patient_phone: ctx.patientPhone,
+        toollog_conversation_id:
+          ctx.channelMetadata.conversationId ?? null,
+        toollog_parameters: params as any,
+        toollog_result: result.data as any,
+        toollog_is_error: result.isError,
+        toollog_duration_ms: durationMs,
+      },
+    });
+  }
+}

package/nestjs/src/tools/tool.decorator.ts

@@ -0,0 +1,16 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const TOOL_METADATA_KEY = 'tool:definition';
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, any>; // JSON Schema
+  requiredFeatures?: string[];
+  channels?: string[];
+  /** Set to false to hide from the admin tool picker and exclude from runtime. Defaults to true. */
+  enabled?: boolean;
+}
+
+export const Tool = (definition: ToolDefinition): MethodDecorator =>
+  SetMetadata(TOOL_METADATA_KEY, definition);

package/nestjs/src/tools/tool.interfaces.ts

@@ -0,0 +1,26 @@
+export interface ToolContext {
+  tenantId: string;
+  clinicId: string | null;
+  patientPhone: string;
+  patientName: string;
+  patientId?: string;
+  channel: 'whatsapp' | 'voice_call' | 'instagram' | 'test_chat';
+  channelMetadata: {
+    chatId?: string;
+    sessionId?: string;
+    conversationId?: string;
+    agentId?: string;
+    phoneNumberId?: string;
+  };
+}
+
+export interface ToolResult {
+  data: any;
+  isError: boolean;
+}
+
+export interface RegisteredTool {
+  definition: import('./tool.decorator.js').ToolDefinition;
+  instance: any;
+  method: (...args: any[]) => Promise<ToolResult>;
+}

package/nestjs/src/tools/tools.module.ts

@@ -0,0 +1,50 @@
+import { Module, forwardRef } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { ToolRegistryService } from './tool-registry.service.js';
+import { ElevenLabsWsAdapter } from './adapters/elevenlabs-ws.adapter.js';
+import { ElevenLabsHttpAdapter } from './adapters/elevenlabs-http.adapter.js';
+import { CalendarTools } from './handlers/calendar.tools.js';
+import { OperatorTools } from './handlers/operator.tools.js';
+import { PatientTools } from './handlers/patient.tools.js';
+import { ValidationTools } from './handlers/validation.tools.js';
+import { PaymentTools } from './handlers/payment.tools.js';
+import { NotificationTools } from './handlers/notification.tools.js';
+import { AppointmentsModule } from '../appointments/appointments.module.js';
+import { PatientsModule } from '../patients/patients.module.js';
+import { WhatsAppModule } from '../whatsapp/whatsapp.module.js';
+import { ElevenLabsModule } from '../integrations/elevenlabs/elevenlabs.module.js';
+import { MetaBusinessModule } from '../integrations/meta-business/meta-business.module.js';
+
+@Module({
+  imports: [
+    DiscoveryModule,
+    AppointmentsModule,
+    PatientsModule,
+    ElevenLabsModule,
+    MetaBusinessModule,
+    // WhatsAppModule imports ToolsModule, so we use forwardRef to break the cycle
+    forwardRef(() => WhatsAppModule),
+  ],
+  providers: [
+    // Registry
+    ToolRegistryService,
+
+    // Adapters
+    ElevenLabsWsAdapter,
+    ElevenLabsHttpAdapter,
+
+    // Tool handlers
+    CalendarTools,
+    OperatorTools,
+    PatientTools,
+    ValidationTools,
+    PaymentTools,
+    NotificationTools,
+  ],
+  exports: [
+    ToolRegistryService,
+    ElevenLabsWsAdapter,
+    ElevenLabsHttpAdapter,
+  ],
+})
+export class ToolsModule {}

package/nestjs/src/treatments/dto/create-plan-item.dto.ts

@@ -0,0 +1,27 @@
+import { IsString, IsOptional, MinLength, MaxLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreatePlanItemDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  treatmentId?: string;
+
+  @ApiProperty({ example: 'Kanal Tedavisi' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name: string;
+
+  @ApiPropertyOptional({ example: '14' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  toothNumber?: string;
+
+  @ApiPropertyOptional({ example: 'Hasta hassasiyet bildirdi' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  notes?: string;
+}

package/nestjs/src/treatments/dto/create-treatment-plan.dto.ts

@@ -0,0 +1,69 @@
+import {
+  IsString,
+  IsOptional,
+  IsArray,
+  ValidateNested,
+  MinLength,
+  MaxLength,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreatePlanItemInlineDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  treatmentId?: string;
+
+  @ApiProperty({ example: 'Kanal Tedavisi' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name: string;
+
+  @ApiPropertyOptional({ example: '14' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  toothNumber?: string;
+
+  @ApiPropertyOptional({ example: 'Hasta hassasiyet bildirdi' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  notes?: string;
+}
+
+export class CreateTreatmentPlanDto {
+  @ApiProperty()
+  @IsString()
+  patientId: string;
+
+  @ApiProperty()
+  @IsString()
+  clinicId: string;
+
+  @ApiProperty({ example: 'Estetik Tedavi Planı' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  doctorId?: string;
+
+  @ApiPropertyOptional({ example: 'Hastanın genel durumu iyi' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(5000)
+  notes?: string;
+
+  @ApiPropertyOptional({ type: [CreatePlanItemInlineDto] })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => CreatePlanItemInlineDto)
+  items?: CreatePlanItemInlineDto[];
+}

package/nestjs/src/treatments/dto/create-treatment.dto.ts

@@ -0,0 +1,59 @@
+import {
+  IsString,
+  IsOptional,
+  IsInt,
+  IsNumber,
+  MinLength,
+  MaxLength,
+  Min,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateTreatmentDto {
+  @ApiProperty({ example: 'Diş Beyazlatma' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name: string;
+
+  @ApiPropertyOptional({ example: 'Estetik' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  category?: string;
+
+  @ApiPropertyOptional({ example: 'Profesyonel diş beyazlatma işlemi' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  description?: string;
+
+  @ApiPropertyOptional({ example: 30, default: 30 })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  durationMinutes?: number;
+
+  @ApiPropertyOptional({ example: 1500.0 })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  price?: number | null;
+
+  @ApiPropertyOptional({ example: 'TRY', default: 'TRY' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(10)
+  currency?: string;
+
+  @ApiPropertyOptional({ example: 180 })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  recallDays?: number | null;
+
+  @ApiPropertyOptional({ example: 'uuid', description: 'null = available at all clinics' })
+  @IsOptional()
+  @IsString()
+  clinicId?: string | null;
+}

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

@@ -0,0 +1,6 @@
+export { CreateTreatmentDto } from './create-treatment.dto';
+export { UpdateTreatmentDto } from './update-treatment.dto';
+export { CreateTreatmentPlanDto } from './create-treatment-plan.dto';
+export { UpdateTreatmentPlanDto } from './update-treatment-plan.dto';
+export { CreatePlanItemDto } from './create-plan-item.dto';
+export { UpdatePlanItemDto } from './update-plan-item.dto';

package/nestjs/src/treatments/dto/update-plan-item.dto.ts

@@ -0,0 +1,23 @@
+import { IsString, IsOptional, IsIn, MaxLength } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class UpdatePlanItemDto {
+  @ApiPropertyOptional({
+    enum: ['planned', 'scheduled', 'in_progress', 'completed', 'cancelled'],
+  })
+  @IsOptional()
+  @IsString()
+  @IsIn(['planned', 'scheduled', 'in_progress', 'completed', 'cancelled'])
+  status?: 'planned' | 'scheduled' | 'in_progress' | 'completed' | 'cancelled';
+
+  @ApiPropertyOptional({ example: 'Tedavi tamamlandı' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  notes?: string;
+
+  @ApiPropertyOptional({ description: 'Link to appointment' })
+  @IsOptional()
+  @IsString()
+  appointmentId?: string;
+}

package/nestjs/src/treatments/dto/update-treatment-plan.dto.ts

@@ -0,0 +1,22 @@
+import { IsString, IsOptional, IsIn, MaxLength } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class UpdateTreatmentPlanDto {
+  @ApiPropertyOptional({ example: 'Estetik Tedavi Planı v2' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  name?: string;
+
+  @ApiPropertyOptional({ example: 'Güncellenmiş notlar' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(5000)
+  notes?: string;
+
+  @ApiPropertyOptional({ enum: ['active', 'completed', 'cancelled'] })
+  @IsOptional()
+  @IsString()
+  @IsIn(['active', 'completed', 'cancelled'])
+  status?: 'active' | 'completed' | 'cancelled';
+}