elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/billing/billing.service.ts

@@ -0,0 +1,398 @@
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { PrismaService } from '../database/prisma.service';
+import { Prisma } from '@prisma/client';
+import { RecordPaymentDto, QueryBillingDto } from './dto';
+
+@Injectable()
+export class BillingService {
+  private readonly logger = new Logger(BillingService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  /* ------------------------------------------------------------------ */
+  /*  LOG CALL CHARGE                                                    */
+  /* ------------------------------------------------------------------ */
+
+  async logCallCharge(
+    tenantId: string,
+    clinicId: string | null,
+    callId: string,
+    durationSeconds: number,
+  ) {
+    // Load tenant + plan to get overage rate
+    const tenant = await this.prisma.tenant.findUnique({
+      where: { tenant_id: tenantId },
+      include: { plan: true },
+    });
+
+    if (!tenant?.plan) {
+      this.logger.warn(
+        `Skipping call charge — tenant ${tenantId} has no plan`,
+      );
+      return null;
+    }
+
+    const billableMinutes = Math.ceil(durationSeconds / 60);
+    const cost = new Prisma.Decimal(billableMinutes).mul(
+      tenant.plan.plan_overage_rate,
+    );
+
+    return this.prisma.billingEvent.create({
+      data: {
+        billing_tenant_id: tenantId,
+        billing_clinic_id: clinicId ?? undefined,
+        billing_type: 'call_charge',
+        billing_amount: cost,
+        billing_call_id: callId,
+        billing_description: `Call charge: ${billableMinutes} min × ${tenant.plan.plan_overage_rate} TRY`,
+      },
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  USAGE SUMMARY                                                      */
+  /* ------------------------------------------------------------------ */
+
+  async getUsageSummary(tenantId: string) {
+    // Get tenant with plan
+    const tenant = await this.prisma.tenant.findUnique({
+      where: { tenant_id: tenantId },
+      include: { plan: true },
+    });
+
+    if (!tenant) {
+      throw new NotFoundException('Tenant not found');
+    }
+
+    // Find active payment (period not yet expired)
+    const activePayment = await this.getActivePayment(tenantId);
+
+    const periodStart = activePayment?.payment_period_start ?? null;
+    const periodEnd = activePayment?.payment_period_end ?? null;
+
+    // Build date filter for the active period
+    const periodFilter =
+      periodStart && periodEnd
+        ? { gte: periodStart, lte: periodEnd }
+        : undefined;
+
+    // Aggregate calls within the period
+    const [callAgg, sessionAgg] = await Promise.all([
+      periodFilter
+        ? this.prisma.call.aggregate({
+            where: {
+              call_tenant_id: tenantId,
+              call_created_at: periodFilter,
+            },
+            _count: { call_id: true },
+            _sum: { call_duration_seconds: true },
+          })
+        : { _count: { call_id: 0 }, _sum: { call_duration_seconds: 0 } },
+
+      periodFilter
+        ? this.prisma.whatsappSession.aggregate({
+            where: {
+              session_tenant_id: tenantId,
+              session_created_at: periodFilter,
+            },
+            _count: { session_id: true },
+          })
+        : { _count: { session_id: 0 } },
+    ]);
+
+    // Aggregate inbound / outbound separately
+    const [inboundAgg, outboundAgg] = await Promise.all([
+      periodFilter
+        ? 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 },
+          })
+        : { _count: { call_id: 0 }, _sum: { call_duration_seconds: 0 } },
+
+      periodFilter
+        ? 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 },
+          })
+        : { _count: { call_id: 0 }, _sum: { call_duration_seconds: 0 } },
+    ]);
+
+    const plan = tenant.plan;
+    const inboundMinutesUsed = Math.ceil(
+      (inboundAgg._sum.call_duration_seconds ?? 0) / 60,
+    );
+    const outboundMinutesUsed = Math.ceil(
+      (outboundAgg._sum.call_duration_seconds ?? 0) / 60,
+    );
+
+    return {
+      tenantId,
+      plan: plan
+        ? {
+            id: plan.plan_id,
+            name: plan.plan_name,
+            slug: plan.plan_slug,
+          }
+        : null,
+      period: {
+        start: periodStart,
+        end: periodEnd,
+        paymentId: activePayment?.payment_id ?? null,
+      },
+      usage: {
+        totalCalls: callAgg._count.call_id ?? 0,
+        totalDurationSeconds: callAgg._sum.call_duration_seconds ?? 0,
+        inbound: {
+          calls: inboundAgg._count.call_id ?? 0,
+          minutes: inboundMinutesUsed,
+          limit: plan?.plan_included_inbound_minutes ?? 0,
+          callLimit: plan?.plan_included_inbound_calls ?? 0,
+        },
+        outbound: {
+          calls: outboundAgg._count.call_id ?? 0,
+          minutes: outboundMinutesUsed,
+          limit: plan?.plan_included_outbound_minutes ?? 0,
+          callLimit: plan?.plan_included_outbound_calls ?? 0,
+        },
+        whatsapp: {
+          sessions: sessionAgg._count.session_id ?? 0,
+          limit: plan?.plan_included_wa_chats ?? 0,
+        },
+      },
+      extraMinutes: activePayment?.payment_extra_minutes ?? 0,
+    };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  ACTIVE PAYMENT                                                     */
+  /* ------------------------------------------------------------------ */
+
+  async getActivePayment(tenantId: string) {
+    return this.prisma.payment.findFirst({
+      where: {
+        payment_tenant_id: tenantId,
+        payment_period_end: { gt: new Date() },
+      },
+      orderBy: { payment_period_end: 'desc' },
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  DAILY TREND                                                        */
+  /* ------------------------------------------------------------------ */
+
+  async getDailyTrend(tenantId: string, days = 30) {
+    const since = new Date();
+    since.setDate(since.getDate() - days);
+    since.setHours(0, 0, 0, 0);
+
+    const rows = await this.prisma.$queryRaw<
+      { day: Date; call_count: bigint; total_seconds: bigint }[]
+    >`
+      SELECT
+        DATE_TRUNC('day', call_created_at) AS day,
+        COUNT(*)::bigint                   AS call_count,
+        COALESCE(SUM(call_duration_seconds), 0)::bigint AS total_seconds
+      FROM calls
+      WHERE call_tenant_id = ${tenantId}
+        AND call_created_at >= ${since}
+      GROUP BY day
+      ORDER BY day
+    `;
+
+    return rows.map((r) => ({
+      date: r.day.toISOString().slice(0, 10),
+      calls: Number(r.call_count),
+      durationSeconds: Number(r.total_seconds),
+    }));
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  SNAPSHOTS                                                          */
+  /* ------------------------------------------------------------------ */
+
+  async getSnapshots(tenantId: string) {
+    return this.prisma.billingPeriodSnapshot.findMany({
+      where: { snapshot_tenant_id: tenantId },
+      orderBy: { snapshot_period_start: 'desc' },
+      include: { payment: true },
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  HISTORY (paginated billing events)                                 */
+  /* ------------------------------------------------------------------ */
+
+  async getHistory(tenantId: string, query?: QueryBillingDto) {
+    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: Prisma.BillingEventWhereInput = {
+      billing_tenant_id: tenantId,
+    };
+
+    if (query?.type) {
+      where.billing_type = query.type as any;
+    }
+
+    if (query?.from || query?.to) {
+      where.billing_created_at = {};
+      if (query.from) where.billing_created_at.gte = new Date(query.from);
+      if (query.to) where.billing_created_at.lte = new Date(query.to);
+    }
+
+    const [data, total] = await Promise.all([
+      this.prisma.billingEvent.findMany({
+        where,
+        orderBy: { billing_created_at: 'desc' },
+        skip,
+        take: limit,
+        include: { clinic: true, call: true },
+      }),
+      this.prisma.billingEvent.count({ where }),
+    ]);
+
+    return {
+      data,
+      meta: {
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  RECORD PAYMENT                                                     */
+  /* ------------------------------------------------------------------ */
+
+  async recordPayment(
+    tenantId: string,
+    userId: string,
+    dto: RecordPaymentDto,
+  ) {
+    return this.prisma.payment.create({
+      data: {
+        payment_tenant_id: tenantId,
+        payment_type: dto.type,
+        payment_plan_slug: dto.planSlug,
+        payment_plan_name: dto.planName,
+        payment_amount: dto.amount,
+        payment_extra_minutes: dto.extraMinutes ?? 0,
+        payment_period_start: new Date(dto.periodStart),
+        payment_period_end: new Date(dto.periodEnd),
+        payment_method: dto.method ?? 'cash',
+        payment_notes: dto.notes ?? '',
+        payment_recorded_by_id: userId,
+      },
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  SNAPSHOT EXPIRED PERIODS  (called by BullMQ job)                   */
+  /* ------------------------------------------------------------------ */
+
+  async snapshotExpiredPeriods() {
+    // 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) return [];
+
+    const snapshots: string[] = [];
+
+    for (const payment of expiredPayments) {
+      const tenantId = payment.payment_tenant_id;
+      const periodStart = payment.payment_period_start;
+      const periodEnd = payment.payment_period_end;
+      const periodFilter = { gte: periodStart, lte: periodEnd };
+
+      // Aggregate call stats for the period
+      const [inboundAgg, outboundAgg, sessionAgg, chargesAgg] =
+        await Promise.all([
+          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 },
+          }),
+          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 },
+          }),
+          this.prisma.whatsappSession.aggregate({
+            where: {
+              session_tenant_id: tenantId,
+              session_created_at: periodFilter,
+            },
+            _count: { session_id: true },
+          }),
+          this.prisma.billingEvent.aggregate({
+            where: {
+              billing_tenant_id: tenantId,
+              billing_type: 'call_charge',
+              billing_created_at: periodFilter,
+            },
+            _sum: { billing_amount: 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;
+
+      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,
+        },
+      });
+
+      snapshots.push(snapshot.snapshot_id);
+
+      this.logger.log(
+        `Created billing snapshot ${snapshot.snapshot_id} for tenant ${tenantId} period ${periodStart.toISOString()} - ${periodEnd.toISOString()}`,
+      );
+    }
+
+    return snapshots;
+  }
+}

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

@@ -0,0 +1,2 @@
+export { RecordPaymentDto } from './record-payment.dto';
+export { QueryBillingDto } from './query-billing.dto';

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

@@ -0,0 +1,29 @@
+import { IsOptional, IsString, IsIn, IsDateString } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class QueryBillingDto {
+  @ApiPropertyOptional({ example: 1, default: 1 })
+  @IsOptional()
+  @IsString()
+  page?: string;
+
+  @ApiPropertyOptional({ example: 25, default: 25 })
+  @IsOptional()
+  @IsString()
+  limit?: string;
+
+  @ApiPropertyOptional({ description: 'Start date (ISO)', example: '2026-01-01' })
+  @IsOptional()
+  @IsDateString()
+  from?: string;
+
+  @ApiPropertyOptional({ description: 'End date (ISO)', example: '2026-12-31' })
+  @IsOptional()
+  @IsDateString()
+  to?: string;
+
+  @ApiPropertyOptional({ enum: ['call_charge', 'subscription', 'top_up', 'refund'] })
+  @IsOptional()
+  @IsIn(['call_charge', 'subscription', 'top_up', 'refund'])
+  type?: string;
+}

package/nestjs/src/billing/dto/record-payment.dto.ts

@@ -0,0 +1,60 @@
+import {
+  IsString,
+  IsNumber,
+  IsInt,
+  IsOptional,
+  IsIn,
+  IsDateString,
+  Min,
+  MinLength,
+  MaxLength,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class RecordPaymentDto {
+  @ApiProperty({ enum: ['subscription', 'top_up'] })
+  @IsIn(['subscription', 'top_up'])
+  type: 'subscription' | 'top_up';
+
+  @ApiProperty({ example: 'starter' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  planSlug: string;
+
+  @ApiProperty({ example: 'Starter' })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  planName: string;
+
+  @ApiProperty({ example: 499.99 })
+  @IsNumber()
+  @Min(0)
+  amount: number;
+
+  @ApiPropertyOptional({ example: 100, default: 0 })
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  extraMinutes?: number;
+
+  @ApiProperty({ example: '2026-04-01', description: 'Period start (ISO date)' })
+  @IsDateString()
+  periodStart: string;
+
+  @ApiProperty({ example: '2026-05-01', description: 'Period end (ISO date)' })
+  @IsDateString()
+  periodEnd: string;
+
+  @ApiPropertyOptional({ enum: ['cash', 'bank_transfer', 'other'], default: 'cash' })
+  @IsOptional()
+  @IsIn(['cash', 'bank_transfer', 'other'])
+  method?: 'cash' | 'bank_transfer' | 'other';
+
+  @ApiPropertyOptional({ example: 'Paid via bank transfer ref #123' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000)
+  notes?: string;
+}

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

@@ -0,0 +1,216 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger } from '@nestjs/common';
+import type { Job } from 'bullmq';
+import { PrismaService } from '../../database/prisma.service.js';
+
+/** Metrics we monitor against plan limits. */
+type AlertMetric = 'inbound_minutes' | 'inbound_calls' | 'wa_chats';
+
+/** Alert thresholds (percentage). */
+const THRESHOLDS = [75, 90, 100] as const;
+
+/** Map threshold value to the AlertType enum in the schema. */
+function thresholdToAlertType(threshold: number): 'usage_75' | 'usage_90' | 'usage_100' {
+  if (threshold === 75) return 'usage_75';
+  if (threshold === 90) return 'usage_90';
+  return 'usage_100';
+}
+
+/** Map metric name to the AlertService enum in the schema. */
+function metricToAlertService(metric: AlertMetric): 'inbound_minutes' | 'inbound_calls' | 'wa_chats' {
+  return metric;
+}
+
+/**
+ * Runs daily at 09:00 (repeatable job).
+ * Checks each tenant with an active payment period against plan limits
+ * and creates BillingAlert records when usage crosses threshold percentages.
+ * The unique constraint on (tenant, type, service, payment) prevents duplicates.
+ */
+@Processor('billing-alerts')
+export class AlertsProcessor extends WorkerHost {
+  private readonly logger = new Logger(AlertsProcessor.name);
+
+  constructor(private readonly prisma: PrismaService) {
+    super();
+  }
+
+  async process(_job: Job): Promise<void> {
+    this.logger.debug('Running billing alerts check');
+
+    try {
+      const now = new Date();
+
+      // 1. Find all active payments (period not yet expired) with tenant + plan
+      const activePayments = await this.prisma.payment.findMany({
+        where: {
+          payment_period_end: { gt: now },
+        },
+        include: {
+          tenant: { include: { plan: true } },
+        },
+      });
+
+      if (activePayments.length === 0) {
+        this.logger.debug('No active payments to check');
+        return;
+      }
+
+      let alertsCreated = 0;
+
+      for (const payment of activePayments) {
+        const tenant = payment.tenant;
+        const plan = tenant.plan;
+
+        if (!plan) {
+          continue;
+        }
+
+        const tenantId = tenant.tenant_id;
+        const paymentId = payment.payment_id;
+        const periodFilter = {
+          gte: payment.payment_period_start,
+          lte: payment.payment_period_end,
+        };
+
+        try {
+          // 2. Aggregate current usage
+          const [inboundAgg, sessionAgg] = await Promise.all([
+            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 },
+            }),
+            this.prisma.whatsappSession.aggregate({
+              where: {
+                session_tenant_id: tenantId,
+                session_created_at: periodFilter,
+              },
+              _count: { session_id: true },
+            }),
+          ]);
+
+          const inboundMinutes = Math.ceil(
+            (inboundAgg._sum.call_duration_seconds ?? 0) / 60,
+          );
+          const inboundCalls = inboundAgg._count.call_id ?? 0;
+          const waSessions = sessionAgg._count.session_id ?? 0;
+
+          // 3. Build metric/limit/used tuples
+          const metrics: Array<{
+            metric: AlertMetric;
+            used: number;
+            limit: number;
+          }> = [
+            {
+              metric: 'inbound_minutes',
+              used: inboundMinutes,
+              limit: plan.plan_included_inbound_minutes,
+            },
+            {
+              metric: 'inbound_calls',
+              used: inboundCalls,
+              limit: plan.plan_included_inbound_calls,
+            },
+            {
+              metric: 'wa_chats',
+              used: waSessions,
+              limit: plan.plan_included_wa_chats,
+            },
+          ];
+
+          // 4. Check each metric against each threshold
+          for (const { metric, used, limit } of metrics) {
+            if (limit <= 0) continue; // No limit configured
+
+            const pctUsed = (used / limit) * 100;
+
+            for (const threshold of THRESHOLDS) {
+              if (pctUsed >= threshold) {
+                const created = await this.tryCreateAlert(
+                  tenantId,
+                  thresholdToAlertType(threshold),
+                  metricToAlertService(metric),
+                  paymentId,
+                );
+                if (created) {
+                  alertsCreated++;
+                  this.logger.log(
+                    `Alert sent: ${tenant.tenant_name} reached ${threshold}% of ${metric} ` +
+                      `(${used}/${limit})`,
+                  );
+                }
+              }
+            }
+          }
+
+          // 5. Check period expiring (within 3 days)
+          const threeDaysFromNow = new Date(now.getTime() + 3 * 24 * 60 * 60 * 1000);
+          if (payment.payment_period_end <= threeDaysFromNow) {
+            const created = await this.tryCreateAlert(
+              tenantId,
+              'period_expiring',
+              'billing_period',
+              paymentId,
+            );
+            if (created) {
+              alertsCreated++;
+              this.logger.log(
+                `Alert sent: ${tenant.tenant_name} billing period expiring on ${payment.payment_period_end.toISOString()}`,
+              );
+            }
+          }
+        } catch (error) {
+          this.logger.error(
+            `Failed to check alerts for tenant ${tenantId}: ${(error as Error).message}`,
+          );
+          // Continue with next tenant
+        }
+      }
+
+      this.logger.log(
+        `Billing alerts check complete: ${alertsCreated} new alerts created for ${activePayments.length} active payments`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Billing alerts check failed: ${(error as Error).message}`,
+        (error as Error).stack,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Attempt to create a BillingAlert. Returns true if created,
+   * false if the unique constraint prevented a duplicate.
+   */
+  private async tryCreateAlert(
+    tenantId: string,
+    alertType: string,
+    alertService: string,
+    paymentId: string,
+  ): Promise<boolean> {
+    try {
+      await this.prisma.billingAlert.create({
+        data: {
+          alert_tenant_id: tenantId,
+          alert_type: alertType as any,
+          alert_service: alertService as any,
+          alert_payment_id: paymentId,
+        },
+      });
+      return true;
+    } catch (error) {
+      // Unique constraint violation — alert already exists
+      const code = (error as any)?.code;
+      if (code === 'P2002') {
+        return false;
+      }
+      throw error;
+    }
+  }
+}