@talkpilot/core-db 1.2.0 → 1.2.2

package/src/talkpilot/calls/calls.types.ts

@@ -1,171 +1,113 @@
-import { ObjectId, Sort, WithId } from "mongodb";
-import { TranscriptionSegment } from "../results";
-
-export const CONFERENCE_ROLE_CUSTOMER = "customer" as const;
-export const CONFERENCE_ROLE_SUPERVISOR = "supervisor" as const;
-
-export type ConferenceRole =
-  | typeof CONFERENCE_ROLE_CUSTOMER
-  | typeof CONFERENCE_ROLE_SUPERVISOR
-  | null;
-
-export type Call = {
-  callSid: string;
-  flowId: ObjectId;
-  clientId: string;
-  sessionId: ObjectId | null;
-  runId?: string;
-  resultId: ObjectId;
-  customerPhoneNumber: string;
-  agentPhoneNumber: string;
-  isIncomingCall: boolean;
-  isOutgoingCall: boolean;
-  callLength: number;
-  transcription?: TranscriptionSegment[];
-  status?: string;
-  leads?: Record<string, string>[];
-  summary?: string;
-  recordingUrl?: string;
-  env: string;
-  updatedAt: Date;
-  createdAt: Date;
-  isAnsweredByAnsweringMachine?: boolean;
-  agentHungUp?: boolean;
-  endReason?: string;
-  conferenceName?: string | null;
-  conferenceSid?: string | null;
-  conferenceParticipantSid?: string | null;
-  isConferenceCall?: boolean;
-  conferenceRole?: ConferenceRole;
-  redirectedCall?: boolean;
-  toolExecutions?: ToolExecution[];
-};
-
-export type ToolExecution = {
-  toolName: string;
-  executedAt: Date;
-  durationMs: number;
-  args: Record<string, unknown> | { _redacted: true };
-  meta: ToolExecutionMeta;
-  status: 'success' | 'error';
-  httpStatus?: number;
-  response?: Record<string, unknown>;
-};
-
-export type ToolExecutionMeta =
-    | {
-  kind: 'http';
-  url: string;
-  method: string;
-  flowToolId?: string;
-  runInBackground?: boolean;
-  sensitive?: boolean;
-}
-    | { kind: 'internal' };
-
-export type CallQueryOptions = {
-  sort?: Sort;
-  skip?: number;
-  limit?: number;
-};
-
-export type CallsFilterParams = {
-  clientId: string;
-  callSid?: string;
-  startDate?: Date;
-  endDate?: Date;
-  status?: string;
-  customerPhoneNumber?: string;
-  agentPhoneNumber?: string;
-  flowId?: string;
-  runId?: string;
-  sessionId?: string;
-  isIncoming?: boolean;
-  search?: string;
-};
-
-export type ImmutableCallFields =
-  | "customerPhoneNumber"
-  | "agentPhoneNumber"
-  | "isIncomingCall"
-  | "isOutgoingCall"
-  | "sessionId"
-  | "callSid"
-  | "flowId"
-  | "clientId"
-  | "runId"
-  | "resultId"
-  | "env"
-  | "createdAt";
-
-export type CallUpdateParams = Partial<Omit<Call, ImmutableCallFields>>;
-
-export type CallDoc = WithId<Call>;
-
-export type CallsByHour = { hour: string; calls: number };
-
-export type CountOpts = {
-  isOutgoingCall?: boolean;
-  isIncomingCall?: boolean;
-};
-
-export type DateRange = {
-  since?: Date;
-  until?: Date;
-};
-
-export type HourlyBucket = {
-  hour: string;
-  calls: number;
-}
-
-export type DailyBucket = {
-  date: string;
-  count: number;
-  completed: number;
-}
-
-export type CallLengthBuckets = {
-  short: number;
-  medium: number;
-  long: number;
-}
-
-export type DashboardKpis = {
-  totalCalls: number;
-  avgDurationSeconds: number;
-  timeSavedMinutes: number;
-  successRate: number;
-  completedCount: number;
-  failedCount: number;
-  noAnswerCount: number;
-  busyCount: number;
-}
-
-export type DashboardCharts = {
-  volumeData: DailyBucket[];
-  heatmap: Record<string, HourlyBucket[]>;
-  callLengthBuckets: CallLengthBuckets;
-}
-
-export type DashboardStatsParams = {
-  clientId: string;
-  startDate: string;
-  endDate: string;
-}
-
-export type RecentCall = {
-  callSid: string;
-  customerPhoneNumber: string;
-  status: string | undefined;
-  callLength: number;
-  createdAt: Date;
-  summary: string | undefined;
-  isIncomingCall: boolean;
-}
-
-export type DashboardStatsResult = {
-  kpis: DashboardKpis;
-  charts: DashboardCharts;
-  recentCalls: RecentCall[];
-}
+import { ObjectId, Sort, WithId } from "mongodb";
+import { TranscriptionSegment } from "../results";
+
+export const CONFERENCE_ROLE_CUSTOMER = "customer" as const;
+export const CONFERENCE_ROLE_SUPERVISOR = "supervisor" as const;
+
+export type ConferenceRole =
+  | typeof CONFERENCE_ROLE_CUSTOMER
+  | typeof CONFERENCE_ROLE_SUPERVISOR
+  | null;
+
+export type Call = {
+  callSid: string;
+  flowId: ObjectId;
+  clientId: string;
+  sessionId: ObjectId | null;
+  runId?: string;
+  resultId: ObjectId;
+  customerPhoneNumber: string;
+  agentPhoneNumber: string;
+  isIncomingCall: boolean;
+  isOutgoingCall: boolean;
+  callLength: number;
+  transcription?: TranscriptionSegment[];
+  status?: string;
+  leads?: Record<string, string>[];
+  summary?: string;
+  recordingUrl?: string;
+  env: string;
+  updatedAt: Date;
+  createdAt: Date;
+  isAnsweredByAnsweringMachine?: boolean;
+  agentHungUp?: boolean;
+  endReason?: string;
+  conferenceName?: string | null;
+  conferenceSid?: string | null;
+  conferenceParticipantSid?: string | null;
+  isConferenceCall?: boolean;
+  conferenceRole?: ConferenceRole;
+  redirectedCall?: boolean;
+  toolExecutions?: ToolExecution[];
+};
+
+export type ToolExecution = {
+  toolName: string;
+  executedAt: Date;
+  durationMs: number;
+  args: Record<string, unknown> | { _redacted: true };
+  meta: ToolExecutionMeta;
+  status: "success" | "error";
+  httpStatus?: number;
+  response?: Record<string, unknown>;
+};
+
+export type ToolExecutionMeta =
+  | {
+      kind: "http";
+      url: string;
+      method: string;
+      flowToolId?: string;
+      runInBackground?: boolean;
+      sensitive?: boolean;
+    }
+  | { kind: "internal" };
+
+export type CallQueryOptions = {
+  sort?: Sort;
+  skip?: number;
+  limit?: number;
+};
+
+export type CallsFilterParams = {
+  clientId: string;
+  callSid?: string;
+  startDate?: Date;
+  endDate?: Date;
+  status?: string;
+  customerPhoneNumber?: string;
+  agentPhoneNumber?: string;
+  flowId?: string;
+  runId?: string;
+  sessionId?: string;
+  isIncoming?: boolean;
+  search?: string;
+};
+
+export type ImmutableCallFields =
+  | "customerPhoneNumber"
+  | "agentPhoneNumber"
+  | "isIncomingCall"
+  | "isOutgoingCall"
+  | "sessionId"
+  | "callSid"
+  | "flowId"
+  | "clientId"
+  | "runId"
+  | "resultId"
+  | "env"
+  | "createdAt";
+
+export type CallUpdateParams = Partial<Omit<Call, ImmutableCallFields>>;
+
+export type CallDoc = WithId<Call>;
+
+export type CountOpts = {
+  isOutgoingCall?: boolean;
+  isIncomingCall?: boolean;
+};
+
+export type DateRange = {
+  since?: Date;
+  until?: Date;
+};

package/src/talkpilot/calls/dashboard/calls.dashboard.ts

@@ -0,0 +1,243 @@
+import dayjs from "dayjs";
+import { getCallsCollection } from "../calls.getters";
+import { getClientConfig } from "../../clientsConfig";
+import utc from "dayjs/plugin/utc";
+import timezonePlugin from "dayjs/plugin/timezone";
+import {
+  DashboardAggregationResult,
+  DashboardDailyTrendMetric,
+  DashboardHeatmapMetric,
+  DashboardReportQuery,
+  DashboardReportResponse,
+  DashboardSummaryMetrics,
+  RawDailyAggregationResult,
+  RawHourlyAggregationResult,
+} from "./calls.dashboard.types";
+import { CallLengthThresholds } from "src/utils/shared.types";
+
+const DEFAULT_KPI_DATA = {
+  totalCalls: 0,
+  totalDuration: 0,
+  completedCount: 0,
+  failedCount: 0,
+  noAnswerCount: 0,
+  busyCount: 0,
+};
+
+dayjs.extend(utc);
+dayjs.extend(timezonePlugin);
+
+function buildKpisPipeline() {
+  return [
+    {
+      $group: {
+        _id: null,
+        totalCalls: { $sum: 1 },
+        totalDuration: { $sum: "$callLength" },
+        completedCount: {
+          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
+        },
+        failedCount: {
+          $sum: { $cond: [{ $eq: ["$status", "failed"] }, 1, 0] },
+        },
+        noAnswerCount: {
+          $sum: { $cond: [{ $eq: ["$status", "no-answer"] }, 1, 0] },
+        },
+        busyCount: {
+          $sum: { $cond: [{ $eq: ["$status", "busy"] }, 1, 0] },
+        },
+      },
+    },
+  ];
+}
+
+function buildDailyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          $dateToString: {
+            format: "%Y-%m-%d",
+            date: "$createdAt",
+            timezone: timezone,
+          },
+        },
+        count: { $sum: 1 },
+        completed: {
+          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
+        },
+      },
+    },
+    { $sort: { _id: 1 } },
+  ];
+}
+
+function buildHourlyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          day: {
+            $dateToString: {
+              format: "%Y-%m-%d",
+              date: "$createdAt",
+              timezone: timezone,
+            },
+          },
+          hour: { $hour: { date: "$createdAt", timezone: timezone } },
+        },
+        count: { $sum: 1 },
+      },
+    },
+  ];
+}
+
+export function buildCallLengthBucketsPipeline(
+  thresholds: CallLengthThresholds,
+) {
+  const { shortThreshold, mediumThreshold } = thresholds;
+
+  return [
+    {
+      $group: {
+        _id: null,
+        short: {
+          $sum: { $cond: [{ $lt: ["$callLength", shortThreshold] }, 1, 0] },
+        },
+        medium: {
+          $sum: {
+            $cond: [
+              {
+                $and: [
+                  { $gte: ["$callLength", shortThreshold] },
+                  { $lte: ["$callLength", mediumThreshold] },
+                ],
+              },
+              1,
+              0,
+            ],
+          },
+        },
+        long: {
+          $sum: { $cond: [{ $gt: ["$callLength", mediumThreshold] }, 1, 0] },
+        },
+      },
+    },
+  ];
+}
+
+function buildHeatmapData(
+  hourlyDataRaw: RawHourlyAggregationResult[],
+): Record<string, DashboardHeatmapMetric[]> {
+  const heatmapMap = new Map<string, Map<number, number>>();
+
+  for (const bucket of hourlyDataRaw) {
+    const dayKey = bucket._id.day;
+    const hour = bucket._id.hour;
+    if (!heatmapMap.has(dayKey)) heatmapMap.set(dayKey, new Map());
+    heatmapMap.get(dayKey)!.set(hour, bucket.count);
+  }
+
+  const toSortedBuckets = (
+    map: Map<number, number>,
+  ): DashboardHeatmapMetric[] =>
+    Array.from(map.entries())
+      .sort(([a], [b]) => a - b)
+      .map(([h, c]) => ({
+        hour: h,
+        calls: c,
+      }));
+
+  const heatmap: Record<string, DashboardHeatmapMetric[]> = {};
+  for (const [day, hourMap] of Array.from(heatmapMap.entries()).sort()) {
+    heatmap[day] = toSortedBuckets(hourMap);
+  }
+
+  return heatmap;
+}
+
+export async function getDashboardStats(
+  params: DashboardReportQuery,
+): Promise<DashboardReportResponse> {
+  const { clientId, startDate, endDate } = params;
+  const clientConfig = await getClientConfig(clientId);
+  const timezone = clientConfig?.timezone ?? "UTC";
+
+  const startDateObj = dayjs.tz(startDate, timezone).startOf("day").toDate();
+  const endDateObj = dayjs.tz(endDate, timezone).endOf("day").toDate();
+
+  const thresholds: CallLengthThresholds = {
+    shortThreshold: clientConfig?.callLengthThresholds?.shortThreshold ?? 60,
+    mediumThreshold: clientConfig?.callLengthThresholds?.mediumThreshold ?? 180,
+  };
+
+  const pipeline = [
+    {
+      $match: {
+        clientId,
+        createdAt: { $gte: startDateObj, $lte: endDateObj },
+      },
+    },
+    {
+      $facet: {
+        kpis: buildKpisPipeline(),
+        dailyData: buildDailyDataPipeline(timezone),
+        hourlyData: buildHourlyDataPipeline(timezone),
+        callLengthBuckets: buildCallLengthBucketsPipeline(thresholds),
+      },
+    },
+  ];
+
+  const callsCollection = getCallsCollection();
+  const [aggregatedResult] = await callsCollection
+    .aggregate<DashboardAggregationResult>(pipeline)
+    .toArray();
+
+  const kpiData = aggregatedResult?.kpis?.[0] ?? DEFAULT_KPI_DATA;
+  const dailyDataRaw = aggregatedResult?.dailyData ?? [];
+  const hourlyDataRaw = aggregatedResult?.hourlyData ?? [];
+  const callLengthRaw = aggregatedResult?.callLengthBuckets?.[0] ?? {
+    short: 0,
+    medium: 0,
+    long: 0,
+  };
+
+  const kpis: DashboardSummaryMetrics = {
+    totalCalls: kpiData.totalCalls,
+    avgDurationSeconds:
+      kpiData.totalCalls > 0
+        ? Math.round((kpiData.totalDuration ?? 0) / kpiData.totalCalls)
+        : 0,
+    timeSavedMinutes: Math.round((kpiData.totalDuration ?? 0) / 60),
+    successRate:
+      kpiData.totalCalls > 0
+        ? Math.round((kpiData.completedCount / kpiData.totalCalls) * 1000) / 10
+        : 0,
+    completedCount: kpiData.completedCount,
+    failedCount: kpiData.failedCount,
+    noAnswerCount: kpiData.noAnswerCount,
+    busyCount: kpiData.busyCount,
+  };
+
+  const volumeData: DashboardDailyTrendMetric[] = dailyDataRaw.map((d) => ({
+    date: d._id,
+    count: d.count,
+    completed: d.completed,
+  }));
+
+  const heatmap = buildHeatmapData(hourlyDataRaw);
+
+  const response: DashboardReportResponse = {
+    kpis,
+    charts: {
+      volumeData,
+      heatmap,
+      callLengthBuckets: {
+        short: callLengthRaw.short,
+        medium: callLengthRaw.medium,
+        long: callLengthRaw.long,
+      },
+    },
+  };
+  return response;
+}

package/src/talkpilot/calls/dashboard/calls.dashboard.types.ts

@@ -0,0 +1,70 @@
+export type DashboardHeatmapMetric = {
+  hour: number;
+  calls: number;
+};
+
+export type DashboardDailyTrendMetric = {
+  date: string;
+  count: number;
+  completed: number;
+};
+
+export type DashboardDurationSegments = {
+  short: number;
+  medium: number;
+  long: number;
+};
+
+export type DashboardSummaryMetrics = {
+  totalCalls: number;
+  avgDurationSeconds: number;
+  timeSavedMinutes: number;
+  successRate: number;
+  completedCount: number;
+  failedCount: number;
+  noAnswerCount: number;
+  busyCount: number;
+};
+
+export type DashboardVisualData = {
+  volumeData: DashboardDailyTrendMetric[];
+  heatmap: Record<string, DashboardHeatmapMetric[]>;
+  callLengthBuckets: DashboardDurationSegments;
+};
+
+export type DashboardReportQuery = {
+  clientId: string;
+  startDate: string;
+  endDate: string;
+};
+
+export type DashboardReportResponse = {
+  kpis: DashboardSummaryMetrics;
+  charts: DashboardVisualData;
+};
+type RawKpiResult = {
+  totalCalls: number;
+  totalDuration: number | null;
+  completedCount: number;
+  failedCount: number;
+  noAnswerCount: number;
+  busyCount: number;
+};
+
+export type RawDailyAggregationResult = {
+  _id: string;
+  count: number;
+  completed: number;
+};
+
+export type RawHourlyAggregationResult = {
+  _id: { day: string; hour: number };
+  count: number;
+};
+
+export interface DashboardAggregationResult {
+  kpis: RawKpiResult[];
+  dailyData: RawDailyAggregationResult[];
+  hourlyData: RawHourlyAggregationResult[];
+  callLengthBuckets: DashboardDurationSegments[];
+}

package/src/talkpilot/calls/index.ts

@@ -1,2 +1,3 @@
-export * from "./calls.types";
-export * from "./calls.getters";
+export * from "./calls.types";
+export * from "./calls.getters";
+export * from "./dashboard/calls.dashboard";