elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/billing/processors/snapshot.processor.ts

@@ -0,0 +1,181 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger } from '@nestjs/common';
+import type { Job } from 'bullmq';
+import { PrismaService } from '../../database/prisma.service.js';
+
+/**
+ * Runs daily at 00:05 (repeatable job).
+ * Finds payments whose period has ended with no corresponding
+ * BillingPeriodSnapshot and creates one for each, aggregating
+ * calls, WhatsApp sessions/messages, billing charges and STT usage
+ * over the expired period.
+ */
+@Processor('billing-snapshot')
+export class SnapshotProcessor extends WorkerHost {
+  private readonly logger = new Logger(SnapshotProcessor.name);
+
+  constructor(private readonly prisma: PrismaService) {
+    super();
+  }
+
+  async process(_job: Job): Promise<void> {
+    this.logger.debug('Running billing snapshot sweep');
+
+    try {
+      // 1. Find payments whose period has ended and no snapshot exists yet
+      const expiredPayments = await this.prisma.payment.findMany({
+        where: {
+          payment_period_end: { lt: new Date() },
+          billing_period_snapshots: { none: {} },
+        },
+        include: {
+          tenant: { include: { plan: true } },
+        },
+      });
+
+      if (expiredPayments.length === 0) {
+        this.logger.debug('No expired payments needing snapshots');
+        return;
+      }
+
+      this.logger.log(
+        `Billing snapshot: processing ${expiredPayments.length} expired payments`,
+      );
+
+      let createdCount = 0;
+
+      for (const payment of expiredPayments) {
+        try {
+          const tenantId = payment.payment_tenant_id;
+          const periodStart = payment.payment_period_start;
+          const periodEnd = payment.payment_period_end;
+          const periodFilter = { gte: periodStart, lte: periodEnd };
+
+          // 2. Aggregate usage within the period
+          const [
+            inboundAgg,
+            outboundAgg,
+            chargesAgg,
+            sessionAgg,
+            messageAgg,
+            aiMessageAgg,
+            sttAgg,
+          ] = await Promise.all([
+            // Inbound calls
+            this.prisma.call.aggregate({
+              where: {
+                call_tenant_id: tenantId,
+                call_created_at: periodFilter,
+                call_direction: 'inbound',
+              },
+              _count: { call_id: true },
+              _sum: { call_duration_seconds: true },
+            }),
+            // Outbound calls
+            this.prisma.call.aggregate({
+              where: {
+                call_tenant_id: tenantId,
+                call_created_at: periodFilter,
+                call_direction: 'outbound',
+              },
+              _count: { call_id: true },
+              _sum: { call_duration_seconds: true },
+            }),
+            // Billing charges
+            this.prisma.billingEvent.aggregate({
+              where: {
+                billing_tenant_id: tenantId,
+                billing_type: 'call_charge',
+                billing_created_at: periodFilter,
+              },
+              _sum: { billing_amount: true },
+            }),
+            // WhatsApp sessions
+            this.prisma.whatsappSession.aggregate({
+              where: {
+                session_tenant_id: tenantId,
+                session_created_at: periodFilter,
+              },
+              _count: { session_id: true },
+            }),
+            // WhatsApp messages (total)
+            this.prisma.whatsappMessage.aggregate({
+              where: {
+                msg_tenant_id: tenantId,
+                msg_created_at: periodFilter,
+              },
+              _count: { msg_id: true },
+            }),
+            // WhatsApp AI messages
+            this.prisma.whatsappMessage.aggregate({
+              where: {
+                msg_tenant_id: tenantId,
+                msg_created_at: periodFilter,
+                msg_sender: 'ai',
+              },
+              _count: { msg_id: true },
+            }),
+            // STT usage
+            this.prisma.sttUsage.aggregate({
+              where: {
+                stt_tenant_id: tenantId,
+                stt_created_at: periodFilter,
+              },
+              _count: { stt_id: true },
+              _sum: { stt_duration_seconds: true },
+            }),
+          ]);
+
+          const inboundCalls = inboundAgg._count.call_id ?? 0;
+          const outboundCalls = outboundAgg._count.call_id ?? 0;
+          const inboundSeconds = inboundAgg._sum.call_duration_seconds ?? 0;
+          const outboundSeconds = outboundAgg._sum.call_duration_seconds ?? 0;
+
+          // 3. Create BillingPeriodSnapshot
+          const snapshot = await this.prisma.billingPeriodSnapshot.create({
+            data: {
+              snapshot_tenant_id: tenantId,
+              snapshot_payment_id: payment.payment_id,
+              snapshot_plan_id: payment.tenant.tenant_plan_id ?? undefined,
+              snapshot_period_start: periodStart,
+              snapshot_period_end: periodEnd,
+              snapshot_total_calls: inboundCalls + outboundCalls,
+              snapshot_inbound_calls: inboundCalls,
+              snapshot_inbound_minutes: Math.ceil(inboundSeconds / 60),
+              snapshot_outbound_calls: outboundCalls,
+              snapshot_outbound_minutes: Math.ceil(outboundSeconds / 60),
+              snapshot_total_charges: chargesAgg._sum.billing_amount ?? 0,
+              snapshot_wa_total_sessions: sessionAgg._count.session_id ?? 0,
+              snapshot_wa_total_messages: messageAgg._count.msg_id ?? 0,
+              snapshot_wa_ai_messages: aiMessageAgg._count.msg_id ?? 0,
+              snapshot_wa_stt_count: sttAgg._count.stt_id ?? 0,
+              snapshot_wa_stt_seconds: sttAgg._sum.stt_duration_seconds ?? 0,
+            },
+          });
+
+          createdCount++;
+
+          this.logger.log(
+            `Created billing snapshot ${snapshot.snapshot_id} for tenant ${tenantId} ` +
+              `(${periodStart.toISOString()} - ${periodEnd.toISOString()})`,
+          );
+        } catch (error) {
+          this.logger.error(
+            `Failed to create snapshot for payment ${payment.payment_id}: ${(error as Error).message}`,
+          );
+          // Continue with next payment
+        }
+      }
+
+      this.logger.log(
+        `Billing snapshot sweep complete: ${createdCount} snapshots created out of ${expiredPayments.length} expired payments`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Billing snapshot sweep failed: ${(error as Error).message}`,
+        (error as Error).stack,
+      );
+      throw error;
+    }
+  }
+}

package/nestjs/src/calls/calls.controller.ts

@@ -0,0 +1,92 @@
+import {
+  Controller,
+  Get,
+  Param,
+  Query,
+  UseGuards,
+  BadRequestException,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
+import { CallsService } from './calls.service';
+import { QueryCallsDto } from './dto';
+import {
+  JwtAuthGuard,
+  PermissionsGuard,
+  ClinicAccessGuard,
+} from '../common/guards';
+import {
+  CurrentUser,
+  Permissions,
+  AccessibleClinics,
+} from '../common/decorators';
+import type { JwtPayload } from '../common/interfaces/jwt-payload.interface';
+
+@ApiTags('Calls')
+@Controller('calls')
+@UseGuards(JwtAuthGuard, PermissionsGuard, ClinicAccessGuard)
+@ApiBearerAuth()
+export class CallsController {
+  constructor(private readonly callsService: CallsService) {}
+
+  /* ------------------------------------------------------------------ */
+  /*  LIST                                                               */
+  /* ------------------------------------------------------------------ */
+
+  @Get()
+  @Permissions('calls:read')
+  @ApiOperation({ summary: 'List calls (paginated, with filters)' })
+  async findAll(
+    @CurrentUser() user: JwtPayload,
+    @AccessibleClinics() clinicIds: string[],
+    @Query() query: QueryCallsDto,
+  ) {
+    if (!user.tenantId) {
+      throw new BadRequestException('No tenant associated with this user');
+    }
+
+    return this.callsService.findAll(
+      user.tenantId,
+      clinicIds.length > 0 ? clinicIds : undefined,
+      query,
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  STATS                                                              */
+  /* ------------------------------------------------------------------ */
+
+  @Get('stats')
+  @Permissions('calls:read')
+  @ApiOperation({ summary: 'Get call stats (total, by direction, by status)' })
+  async getStats(
+    @CurrentUser() user: JwtPayload,
+    @AccessibleClinics() clinicIds: string[],
+  ) {
+    if (!user.tenantId) {
+      throw new BadRequestException('No tenant associated with this user');
+    }
+
+    return this.callsService.getStats(
+      user.tenantId,
+      clinicIds.length > 0 ? clinicIds : undefined,
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  SINGLE (with transcript + summary)                                 */
+  /* ------------------------------------------------------------------ */
+
+  @Get(':id')
+  @Permissions('calls:read')
+  @ApiOperation({ summary: 'Get call detail (includes transcript and summary)' })
+  async findById(
+    @Param('id') id: string,
+    @CurrentUser() user: JwtPayload,
+  ) {
+    if (!user.tenantId) {
+      throw new BadRequestException('No tenant associated with this user');
+    }
+
+    return this.callsService.findById(id, user.tenantId);
+  }
+}

package/nestjs/src/calls/calls.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { CallsController } from './calls.controller';
+import { CallsService } from './calls.service';
+
+@Module({
+  controllers: [CallsController],
+  providers: [CallsService],
+  exports: [CallsService],
+})
+export class CallsModule {}

package/nestjs/src/calls/calls.service.ts

@@ -0,0 +1,359 @@
+import { Injectable, NotFoundException, Logger } from '@nestjs/common';
+import { PrismaService } from '../database/prisma.service';
+import { QueryCallsDto } from './dto';
+
+@Injectable()
+export class CallsService {
+  private readonly logger = new Logger(CallsService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  /* ------------------------------------------------------------------ */
+  /*  LIST (paginated with filters)                                      */
+  /* ------------------------------------------------------------------ */
+
+  async findAll(
+    tenantId: string,
+    clinicIds?: string[],
+    query?: QueryCallsDto,
+  ) {
+    const page = query?.page ? parseInt(query.page, 10) : 1;
+    const limit = query?.limit ? parseInt(query.limit, 10) : 25;
+    const skip = (page - 1) * limit;
+
+    const where: any = { call_tenant_id: tenantId };
+
+    if (clinicIds && clinicIds.length > 0) {
+      where.call_clinic_id = { in: clinicIds };
+    }
+
+    if (query?.direction) {
+      where.call_direction = query.direction;
+    }
+
+    if (query?.status) {
+      where.call_status = query.status;
+    }
+
+    if (query?.agentId) {
+      where.call_agent_id = query.agentId;
+    }
+
+    if (query?.clinicId) {
+      where.call_clinic_id = query.clinicId;
+    }
+
+    if (query?.from || query?.to) {
+      where.call_created_at = {};
+      if (query.from) {
+        where.call_created_at.gte = new Date(query.from);
+      }
+      if (query.to) {
+        where.call_created_at.lte = new Date(query.to);
+      }
+    }
+
+    const [calls, total] = await Promise.all([
+      this.prisma.call.findMany({
+        where,
+        skip,
+        take: limit,
+        orderBy: { call_created_at: 'desc' },
+        include: {
+          agent: {
+            select: { agent_id: true, agent_name: true },
+          },
+          clinic: {
+            select: { clinic_id: true, clinic_name: true },
+          },
+          patient: {
+            select: {
+              patient_id: true,
+              patient_display_name: true,
+              patient_phone: true,
+            },
+          },
+        },
+      }),
+      this.prisma.call.count({ where }),
+    ]);
+
+    return {
+      data: calls.map((c) => this.formatCall(c)),
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  FIND BY ID (with call details)                                     */
+  /* ------------------------------------------------------------------ */
+
+  async findById(callId: string, tenantId: string) {
+    const call = await this.prisma.call.findFirst({
+      where: {
+        call_id: callId,
+        call_tenant_id: tenantId,
+      },
+      include: {
+        call_detail: true,
+        agent: {
+          select: { agent_id: true, agent_name: true },
+        },
+        clinic: {
+          select: { clinic_id: true, clinic_name: true },
+        },
+        patient: {
+          select: {
+            patient_id: true,
+            patient_display_name: true,
+            patient_phone: true,
+          },
+        },
+      },
+    });
+
+    if (!call) {
+      throw new NotFoundException('Call not found');
+    }
+
+    return this.formatCallDetail(call);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  STATS                                                              */
+  /* ------------------------------------------------------------------ */
+
+  async getStats(tenantId: string, clinicIds?: string[]) {
+    const where: any = { call_tenant_id: tenantId };
+
+    if (clinicIds && clinicIds.length > 0) {
+      where.call_clinic_id = { in: clinicIds };
+    }
+
+    const [
+      totalCalls,
+      totalDuration,
+      byDirection,
+      byStatus,
+    ] = await Promise.all([
+      this.prisma.call.count({ where }),
+      this.prisma.call.aggregate({
+        where,
+        _sum: { call_duration_seconds: true },
+      }),
+      this.prisma.call.groupBy({
+        by: ['call_direction'],
+        where,
+        _count: { call_id: true },
+      }),
+      this.prisma.call.groupBy({
+        by: ['call_status'],
+        where,
+        _count: { call_id: true },
+      }),
+    ]);
+
+    return {
+      totalCalls,
+      totalDurationSeconds: totalDuration._sum.call_duration_seconds ?? 0,
+      byDirection: byDirection.map((d) => ({
+        direction: d.call_direction,
+        count: d._count.call_id,
+      })),
+      byStatus: byStatus.map((s) => ({
+        status: s.call_status,
+        count: s._count.call_id,
+      })),
+    };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  CREATE (internal — used by webhook processor)                      */
+  /* ------------------------------------------------------------------ */
+
+  async create(data: {
+    tenantId: string;
+    clinicId: string;
+    agentId: string;
+    patientId?: string;
+    campaignId?: string;
+    conversationId?: string;
+    direction: string;
+    callerNumber: string;
+    calleeNumber: string;
+    durationSeconds?: number;
+    startTime?: Date;
+    endTime?: Date;
+    terminationReason?: string;
+    cost?: number;
+    language?: string;
+    elevenlabsStatus?: string;
+    status: string;
+    sentiment?: string;
+    categories?: string[];
+    waNotificationSent?: boolean;
+    // Call detail fields
+    transcript?: string;
+    llmSummary?: string;
+    extractedData?: any;
+    recordingUrl?: string;
+    recordingKey?: string;
+    analysis?: any;
+  }) {
+    return this.prisma.$transaction(async (tx) => {
+      const call = await tx.call.create({
+        data: {
+          call_tenant_id: data.tenantId,
+          call_clinic_id: data.clinicId,
+          call_agent_id: data.agentId,
+          ...(data.patientId && { call_patient_id: data.patientId }),
+          ...(data.campaignId && { call_campaign_id: data.campaignId }),
+          ...(data.conversationId && {
+            call_conversation_id: data.conversationId,
+          }),
+          call_direction: data.direction as any,
+          call_caller_number: data.callerNumber,
+          call_callee_number: data.calleeNumber,
+          call_duration_seconds: data.durationSeconds ?? 0,
+          ...(data.startTime && { call_start_time: data.startTime }),
+          ...(data.endTime && { call_end_time: data.endTime }),
+          ...(data.terminationReason && {
+            call_termination_reason: data.terminationReason,
+          }),
+          ...(data.cost !== undefined && { call_cost: data.cost }),
+          ...(data.language && { call_language: data.language }),
+          ...(data.elevenlabsStatus && {
+            call_elevenlabs_status: data.elevenlabsStatus,
+          }),
+          call_status: data.status as any,
+          ...(data.sentiment && { call_sentiment: data.sentiment as any }),
+          ...(data.categories && { call_categories: data.categories }),
+          ...(data.waNotificationSent !== undefined && {
+            call_wa_notification_sent: data.waNotificationSent,
+          }),
+        },
+      });
+
+      // Create call detail if any detail fields provided
+      if (
+        data.transcript !== undefined ||
+        data.llmSummary ||
+        data.extractedData ||
+        data.recordingUrl ||
+        data.recordingKey ||
+        data.analysis
+      ) {
+        await tx.callDetail.create({
+          data: {
+            detail_call_id: call.call_id,
+            ...(data.transcript !== undefined && {
+              detail_transcript: data.transcript,
+            }),
+            ...(data.llmSummary && { detail_llm_summary: data.llmSummary }),
+            ...(data.extractedData && {
+              detail_extracted_data: data.extractedData,
+            }),
+            ...(data.recordingUrl && {
+              detail_recording_url: data.recordingUrl,
+            }),
+            ...(data.recordingKey && {
+              detail_recording_key: data.recordingKey,
+            }),
+            ...(data.analysis && { detail_analysis: data.analysis }),
+          },
+        });
+      }
+
+      this.logger.log(
+        `Call created: ${call.call_id} (tenant=${data.tenantId}, direction=${data.direction})`,
+      );
+
+      return call;
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  FIND BY CONVERSATION ID                                            */
+  /* ------------------------------------------------------------------ */
+
+  async findByConversationId(conversationId: string) {
+    return this.prisma.call.findFirst({
+      where: { call_conversation_id: conversationId },
+      include: {
+        call_detail: true,
+      },
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  PRIVATE HELPERS                                                    */
+  /* ------------------------------------------------------------------ */
+
+  private formatCall(call: any) {
+    return {
+      id: call.call_id,
+      tenantId: call.call_tenant_id,
+      clinicId: call.call_clinic_id,
+      patientId: call.call_patient_id,
+      agentId: call.call_agent_id,
+      campaignId: call.call_campaign_id,
+      conversationId: call.call_conversation_id,
+      direction: call.call_direction,
+      callerNumber: call.call_caller_number,
+      calleeNumber: call.call_callee_number,
+      durationSeconds: call.call_duration_seconds,
+      startTime: call.call_start_time,
+      endTime: call.call_end_time,
+      terminationReason: call.call_termination_reason,
+      cost: call.call_cost,
+      language: call.call_language,
+      elevenlabsStatus: call.call_elevenlabs_status,
+      status: call.call_status,
+      sentiment: call.call_sentiment,
+      categories: call.call_categories,
+      waNotificationSent: call.call_wa_notification_sent,
+      createdAt: call.call_created_at,
+      updatedAt: call.call_updated_at,
+      agent: call.agent
+        ? { id: call.agent.agent_id, name: call.agent.agent_name }
+        : null,
+      clinic: call.clinic
+        ? { id: call.clinic.clinic_id, name: call.clinic.clinic_name }
+        : null,
+      patient: call.patient
+        ? {
+            id: call.patient.patient_id,
+            displayName: call.patient.patient_display_name,
+            phone: call.patient.patient_phone,
+          }
+        : null,
+    };
+  }
+
+  private formatCallDetail(call: any) {
+    const base = this.formatCall(call);
+    const detail = call.call_detail;
+
+    return {
+      ...base,
+      detail: detail
+        ? {
+            id: detail.detail_id,
+            transcript: detail.detail_transcript,
+            llmSummary: detail.detail_llm_summary,
+            extractedData: detail.detail_extracted_data,
+            recordingUrl: detail.detail_recording_url,
+            recordingKey: detail.detail_recording_key,
+            analysis: detail.detail_analysis,
+            createdAt: detail.detail_created_at,
+            updatedAt: detail.detail_updated_at,
+          }
+        : null,
+    };
+  }
+}

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

@@ -0,0 +1 @@
+export { QueryCallsDto } from './query-calls.dto';

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

@@ -0,0 +1,46 @@
+import { IsOptional, IsString, IsIn, IsDateString } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class QueryCallsDto {
+  @ApiPropertyOptional({ example: 1, default: 1 })
+  @IsOptional()
+  @IsString()
+  page?: string;
+
+  @ApiPropertyOptional({ example: 25, default: 25 })
+  @IsOptional()
+  @IsString()
+  limit?: string;
+
+  @ApiPropertyOptional({ enum: ['inbound', 'outbound'] })
+  @IsOptional()
+  @IsIn(['inbound', 'outbound'])
+  direction?: string;
+
+  @ApiPropertyOptional({
+    enum: ['completed', 'failed', 'no_answer', 'voicemail', 'transferred'],
+  })
+  @IsOptional()
+  @IsIn(['completed', 'failed', 'no_answer', 'voicemail', 'transferred'])
+  status?: string;
+
+  @ApiPropertyOptional({ description: 'Filter by agent ID' })
+  @IsOptional()
+  @IsString()
+  agentId?: string;
+
+  @ApiPropertyOptional({ description: 'Filter by clinic ID' })
+  @IsOptional()
+  @IsString()
+  clinicId?: string;
+
+  @ApiPropertyOptional({ description: 'Start date (ISO)', example: '2024-01-01' })
+  @IsOptional()
+  @IsDateString()
+  from?: string;
+
+  @ApiPropertyOptional({ description: 'End date (ISO)', example: '2024-12-31' })
+  @IsOptional()
+  @IsDateString()
+  to?: string;
+}