@talkpilot/core-db 1.3.64 → 1.3.66

package/src/talkpilot/calls/calls.getters.ts

@@ -1,277 +1,546 @@
-import {
-  Call,
-  CallDoc,
-  CallQueryOptions,
-  CallUpdateParams,
-  getDb,
-} from "../index";
-import type { CountOpts, DateRange, ToolExecution, CallStatus } from "./calls.types";
-import {
-  TOOL_EXECUTIONS_DEFAULT_LIMIT,
-  TOOL_EXECUTIONS_DEFAULT_SKIP,
-} from "./calls.constants";
-import { Filter, ObjectId } from "mongodb";
-import * as process from "node:process";
-import { applyQueryOptions } from "../utils/query.utils";
-import { DashboardHeatmapMetric } from "./dashboard/calls.dashboard.types";
-
-export const getCallsCollection = () => {
-  return getDb().collection<Call>("calls");
-};
-
-export const getCallByCallSid = (callSid: string) => {
-  return getCallsCollection().findOne({ callSid });
-};
-
-export const getCallsByPhoneNumber = (phoneNumber: string) => {
-  return getCallsCollection()
-    .find({ customerPhoneNumber: phoneNumber })
-    .toArray();
-};
-
-export const getCallsByClient = (clientId: string) => {
-  return getCallsCollection().find({ clientId }).toArray();
-};
-
-export const getCallsByFlow = (flowId: ObjectId) => {
-  return getCallsCollection().find({ flowId }).toArray();
-};
-
-export const createCallDoc = (
-  call: Omit<Call, "createdAt" | "updatedAt" | "env">,
-) => {
-  return getCallsCollection().insertOne({
-    ...call,
-    createdAt: new Date(),
-    updatedAt: new Date(),
-    env: process.env.ENV ?? "unknown",
-  });
-};
-
-export const updateCallByCallSid = async (
-  callSid: string,
-  updates: CallUpdateParams,
-): Promise<CallDoc | null> => {
-  return await getCallsCollection().findOneAndUpdate(
-    { callSid: callSid },
-    {
-      $set: {
-        ...updates,
-        updatedAt: new Date(),
-      },
-    },
-    { returnDocument: "after" },
-  );
-};
-
-export const getToolExecutionsByCallSid = async (
-  callSid: string,
-  opts?: Pick<CallQueryOptions, "skip" | "limit"> & { clientId?: string },
-): Promise<ToolExecution[]> => {
-  const skip = Math.max(0, opts?.skip ?? TOOL_EXECUTIONS_DEFAULT_SKIP);
-  const limit = Math.max(1, opts?.limit ?? TOOL_EXECUTIONS_DEFAULT_LIMIT);
-  const filter: Filter<Call> = { callSid };
-  if (opts?.clientId != null) filter.clientId = opts.clientId;
-  const call = await getCallsCollection().findOne(
-    filter,
-    { projection: { toolExecutions: { $slice: [skip, limit] } } },
-  );
-  return call?.toolExecutions ?? [];
-};
-
-export const updateCallStatusByCallSid = async (
-  callSid: string,
-  status: CallStatus,
-): Promise<CallDoc | null> =>
-  getCallsCollection().findOneAndUpdate(
-    { callSid },
-    { $set: { status, updatedAt: new Date() } },
-    { returnDocument: "after" },
-  );
-
-export const pushToolExecution = async (
-  callSid: string,
-  execution: ToolExecution,
-): Promise<void> => {
-  await getCallsCollection().updateOne(
-    { callSid },
-    { $push: { toolExecutions: execution } },
-  );
-};
-
-// get calls by client and date range
-//client here is the user id
-export const getCallsByClientAndDateRange = (
-  clientId: string,
-  startDate: Date,
-  endDate: Date,
-) => {
-  return getCallsCollection()
-    .find({
-      clientId,
-      createdAt: {
-        $gte: startDate,
-        $lte: endDate,
-      },
-    })
-    .toArray();
-};
-
-export const findCallsByQuery = async (
-  query: Filter<Call>,
-  options?: CallQueryOptions,
-): Promise<CallDoc[]> => {
-  const cursor = getCallsCollection().find(query);
-  return await applyQueryOptions(cursor, options).toArray();
-};
-
-export const countCalls = async (query: Filter<Call>): Promise<number> => {
-  return getCallsCollection().countDocuments(query);
-};
-
-export async function countCallsByPhoneInRange(
-  customerPhoneNumber: string,
-  opts: CountOpts = {},
-  range: DateRange = {},
-): Promise<number> {
-  const filter: Partial<Call> & { customerPhoneNumber: string } = {
-    customerPhoneNumber,
-  };
-
-  if (opts.isOutgoingCall !== undefined) {
-    filter.isOutgoingCall = opts.isOutgoingCall;
-  }
-  if (opts.isIncomingCall !== undefined) {
-    filter.isIncomingCall = opts.isIncomingCall;
-  }
-
-  if (range.since || range.until) {
-    (filter as Filter<Call>).createdAt = {
-      ...(range.since ? { $gte: range.since } : {}),
-      ...(range.until ? { $lt: range.until } : {}),
-    };
-  }
-
-  return getCallsCollection().countDocuments(filter as Filter<Call>);
-}
-
-export const range = {
-  between: (since: Date, until: Date): DateRange => ({ since, until }),
-  todayToNow: (): DateRange => ({ since: startOfDay(), until: new Date() }),
-  yesterday: (): DateRange => {
-    const s = startOfDay(addDays(new Date(), -1));
-    const e = addDays(s, 1);
-    return { since: s, until: e };
-  },
-  todayFull: (): DateRange => {
-    const s = startOfDay();
-    const e = addDays(s, 1);
-    return { since: s, until: e };
-  },
-  startOfDayToNow: (d: Date): DateRange => ({
-    since: startOfDay(d),
-    until: new Date(),
-  }),
-};
-
-export function startOfDay(d: Date = new Date()): Date {
-  const x = new Date(d);
-  x.setUTCHours(0, 0, 0, 0);
-  return x;
-}
-
-export function addDays(d: Date, days: number): Date {
-  const x = new Date(d);
-  x.setDate(x.getDate() + days);
-  return x;
-}
-
-/**
- * Aggregate calls stats for a date range (createdAt in [startStr, endStr] in timezone).
- * completed = agentHungUp=true or status='completed'.
- */
-export async function getCallsStatsForDateRange(
-  clientId: string,
-  startStr: string,
-  endStr: string,
-  timezone: string,
-): Promise<{ count: number; totalLen: number; completed: number }> {
-  const coll = getCallsCollection();
-  const out = await coll
-    .aggregate<{
-      _id: null;
-      count: number;
-      totalLen: number;
-      completed: number;
-    }>([
-      // 1. Restrict to the given client
-      { $match: { clientId } },
-      // 2. Derive dateLocal (createdAt as YYYY-MM-DD in timezone) and isCompleted (agentHungUp or status='completed')
-      {
-        $addFields: {
-          dateLocal: {
-            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
-          },
-          isCompleted: {
-            $or: [
-              { $eq: ["$agentHungUp", true] },
-              { $eq: ["$status", "completed"] },
-            ],
-          },
-        },
-      },
-      // 3. Keep only documents with dateLocal in [startStr, endStr] (inclusive)
-      { $match: { dateLocal: { $gte: startStr, $lte: endStr } } },
-      // 4. Single group: count, totalLen, completed
-      {
-        $group: {
-          _id: null,
-          count: { $sum: 1 },
-          totalLen: { $sum: "$callLength" },
-          completed: { $sum: { $cond: ["$isCompleted", 1, 0] } },
-        },
-      },
-    ])
-    .next();
-  return {
-    count: out?.count ?? 0,
-    totalLen: out?.totalLen ?? 0,
-    completed: out?.completed ?? 0,
-  };
-}
-
-/**
- * Aggregate calls by hour for a given date (createdAt converted to given timezone). Hour format "HH:mm".
- */
-export async function getCallsHourlyAggregation(
-  clientId: string,
-  dateStr: string,
-  timezone: string,
-): Promise<DashboardHeatmapMetric[]> {
-  const coll = getCallsCollection();
-  const rows = await coll
-    .aggregate<{ _id: number; calls: number }>([
-      // 1. Restrict to the given client
-      { $match: { clientId } },
-      {
-        $addFields: {
-          dateLocal: {
-            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
-          },
-          hour: { $hour: { date: "$createdAt", timezone } },
-        },
-      },
-      // 3. Keep only the requested date
-      { $match: { dateLocal: dateStr } },
-      // 4. Group by hour, sum calls per hour
-      { $group: { _id: "$hour", calls: { $sum: 1 } } },
-      // 5. Order by hour ascending (0..23)
-      { $sort: { _id: 1 } },
-    ])
-    .toArray();
-
-  return rows.map((r: any) => ({
-    hour: r._id,
-    calls: r.calls,
-  }));
-}
+import {
+  Call,
+  CallDoc,
+  CallQueryOptions,
+  CallUpdateParams,
+  getDb,
+} from "../index";
+import type {
+  CountOpts,
+  DateRange,
+  ToolExecution,
+  CallStatus,
+  ActiveCallsSummary,
+  TodayCallsSummary,
+  ClientCallStats,
+  SessionCallStats,
+  StatsDateRangeParams,
+} from "./calls.types";
+import {
+  TOOL_EXECUTIONS_DEFAULT_LIMIT,
+  TOOL_EXECUTIONS_DEFAULT_SKIP,
+  ACTIVE_STATUSES,
+  ACTIVE_CALLS_WINDOW_MS,
+  INCOMING_SESSION_ID,
+  ALL_STATUSES_FOR_BREAKDOWN,
+} from "./calls.constants";
+import { Filter, ObjectId } from "mongodb";
+import * as process from "node:process";
+import { applyQueryOptions } from "../utils/query.utils";
+import { DashboardHeatmapMetric } from "./dashboard/calls.dashboard.types";
+import {
+  formatYmdInTz,
+  startOfCalendarDayInTz,
+  endOfCalendarDayInTz,
+} from "../../utils/date.utils";
+
+export const getCallsCollection = () => {
+  return getDb().collection<Call>("calls");
+};
+
+export const getCallByCallSid = (callSid: string) => {
+  return getCallsCollection().findOne({ callSid });
+};
+
+export const getCallsByPhoneNumber = (phoneNumber: string) => {
+  return getCallsCollection()
+    .find({ customerPhoneNumber: phoneNumber })
+    .toArray();
+};
+
+export const getCallsByClient = (clientId: string) => {
+  return getCallsCollection().find({ clientId }).toArray();
+};
+
+export const getCallsByFlow = (flowId: ObjectId) => {
+  return getCallsCollection().find({ flowId }).toArray();
+};
+
+export const createCallDoc = (
+  call: Omit<Call, "createdAt" | "updatedAt" | "env">,
+) => {
+  return getCallsCollection().insertOne({
+    ...call,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    env: process.env.ENV ?? "unknown",
+  });
+};
+
+export const updateCallByCallSid = async (
+  callSid: string,
+  updates: CallUpdateParams,
+): Promise<CallDoc | null> => {
+  return await getCallsCollection().findOneAndUpdate(
+    { callSid: callSid },
+    {
+      $set: {
+        ...updates,
+        updatedAt: new Date(),
+      },
+    },
+    { returnDocument: "after" },
+  );
+};
+
+export const getToolExecutionsByCallSid = async (
+  callSid: string,
+  opts?: Pick<CallQueryOptions, "skip" | "limit"> & { clientId?: string },
+): Promise<ToolExecution[]> => {
+  const skip = Math.max(0, opts?.skip ?? TOOL_EXECUTIONS_DEFAULT_SKIP);
+  const limit = Math.max(1, opts?.limit ?? TOOL_EXECUTIONS_DEFAULT_LIMIT);
+  const filter: Filter<Call> = { callSid };
+  if (opts?.clientId != null) filter.clientId = opts.clientId;
+  const call = await getCallsCollection().findOne(
+    filter,
+    { projection: { toolExecutions: { $slice: [skip, limit] } } },
+  );
+  return call?.toolExecutions ?? [];
+};
+
+export const updateCallStatusByCallSid = async (
+  callSid: string,
+  status: CallStatus,
+): Promise<CallDoc | null> =>
+  getCallsCollection().findOneAndUpdate(
+    { callSid },
+    { $set: { status, updatedAt: new Date() } },
+    { returnDocument: "after" },
+  );
+
+export const pushToolExecution = async (
+  callSid: string,
+  execution: ToolExecution,
+): Promise<void> => {
+  await getCallsCollection().updateOne(
+    { callSid },
+    { $push: { toolExecutions: execution } },
+  );
+};
+
+// get calls by client and date range
+//client here is the user id
+export const getCallsByClientAndDateRange = (
+  clientId: string,
+  startDate: Date,
+  endDate: Date,
+) => {
+  return getCallsCollection()
+    .find({
+      clientId,
+      createdAt: {
+        $gte: startDate,
+        $lte: endDate,
+      },
+    })
+    .toArray();
+};
+
+export const findCallsByQuery = async (
+  query: Filter<Call>,
+  options?: CallQueryOptions,
+): Promise<CallDoc[]> => {
+  const cursor = getCallsCollection().find(query);
+  return await applyQueryOptions(cursor, options).toArray();
+};
+
+export const countCalls = async (query: Filter<Call>): Promise<number> => {
+  return getCallsCollection().countDocuments(query);
+};
+
+export async function countCallsByPhoneInRange(
+  customerPhoneNumber: string,
+  opts: CountOpts = {},
+  range: DateRange = {},
+): Promise<number> {
+  const filter: Partial<Call> & { customerPhoneNumber: string } = {
+    customerPhoneNumber,
+  };
+
+  if (opts.isOutgoingCall !== undefined) {
+    filter.isOutgoingCall = opts.isOutgoingCall;
+  }
+  if (opts.isIncomingCall !== undefined) {
+    filter.isIncomingCall = opts.isIncomingCall;
+  }
+
+  if (range.since || range.until) {
+    (filter as Filter<Call>).createdAt = {
+      ...(range.since ? { $gte: range.since } : {}),
+      ...(range.until ? { $lt: range.until } : {}),
+    };
+  }
+
+  return getCallsCollection().countDocuments(filter as Filter<Call>);
+}
+
+export const range = {
+  between: (since: Date, until: Date): DateRange => ({ since, until }),
+  todayToNow: (): DateRange => ({ since: startOfDay(), until: new Date() }),
+  yesterday: (): DateRange => {
+    const s = startOfDay(addDays(new Date(), -1));
+    const e = addDays(s, 1);
+    return { since: s, until: e };
+  },
+  todayFull: (): DateRange => {
+    const s = startOfDay();
+    const e = addDays(s, 1);
+    return { since: s, until: e };
+  },
+  startOfDayToNow: (d: Date): DateRange => ({
+    since: startOfDay(d),
+    until: new Date(),
+  }),
+};
+
+export function startOfDay(d: Date = new Date()): Date {
+  const x = new Date(d);
+  x.setUTCHours(0, 0, 0, 0);
+  return x;
+}
+
+export function addDays(d: Date, days: number): Date {
+  const x = new Date(d);
+  x.setDate(x.getDate() + days);
+  return x;
+}
+
+/**
+ * Aggregate calls stats for a date range (createdAt in [startStr, endStr] in timezone).
+ * completed = agentHungUp=true or status='completed'.
+ */
+export async function getCallsStatsForDateRange(
+  clientId: string,
+  startStr: string,
+  endStr: string,
+  timezone: string,
+): Promise<{ count: number; totalLen: number; completed: number }> {
+  const coll = getCallsCollection();
+  const out = await coll
+    .aggregate<{
+      _id: null;
+      count: number;
+      totalLen: number;
+      completed: number;
+    }>([
+      // 1. Restrict to the given client
+      { $match: { clientId } },
+      // 2. Derive dateLocal (createdAt as YYYY-MM-DD in timezone) and isCompleted (agentHungUp or status='completed')
+      {
+        $addFields: {
+          dateLocal: {
+            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
+          },
+          isCompleted: {
+            $or: [
+              { $eq: ["$agentHungUp", true] },
+              { $eq: ["$status", "completed"] },
+            ],
+          },
+        },
+      },
+      // 3. Keep only documents with dateLocal in [startStr, endStr] (inclusive)
+      { $match: { dateLocal: { $gte: startStr, $lte: endStr } } },
+      // 4. Single group: count, totalLen, completed
+      {
+        $group: {
+          _id: null,
+          count: { $sum: 1 },
+          totalLen: { $sum: "$callLength" },
+          completed: { $sum: { $cond: ["$isCompleted", 1, 0] } },
+        },
+      },
+    ])
+    .next();
+  return {
+    count: out?.count ?? 0,
+    totalLen: out?.totalLen ?? 0,
+    completed: out?.completed ?? 0,
+  };
+}
+
+/**
+ * Aggregate calls by hour for a given date (createdAt converted to given timezone). Hour format "HH:mm".
+ */
+export async function getCallsHourlyAggregation(
+  clientId: string,
+  dateStr: string,
+  timezone: string,
+): Promise<DashboardHeatmapMetric[]> {
+  const coll = getCallsCollection();
+  const rows = await coll
+    .aggregate<{ _id: number; calls: number }>([
+      // 1. Restrict to the given client
+      { $match: { clientId } },
+      {
+        $addFields: {
+          dateLocal: {
+            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
+          },
+          hour: { $hour: { date: "$createdAt", timezone } },
+        },
+      },
+      // 3. Keep only the requested date
+      { $match: { dateLocal: dateStr } },
+      // 4. Group by hour, sum calls per hour
+      { $group: { _id: "$hour", calls: { $sum: 1 } } },
+      // 5. Order by hour ascending (0..23)
+      { $sort: { _id: 1 } },
+    ])
+    .toArray();
+
+  return rows.map((r: any) => ({
+    hour: r._id,
+    calls: r.calls,
+  }));
+}
+
+type StatusCountFields = { [K in (typeof ALL_STATUSES_FOR_BREAKDOWN)[number]]: number };
+
+// One $sum/$cond accumulator per status in ALL_STATUSES_FOR_BREAKDOWN.
+const buildStatusCountFields = (field: string) =>
+  Object.fromEntries(
+    ALL_STATUSES_FOR_BREAKDOWN.map((status) => [
+      status,
+      { $sum: { $cond: [{ $eq: [field, status] }, 1, 0] } },
+    ]),
+  );
+
+const extractStatusCounts = (row: StatusCountFields): Record<string, number> =>
+  Object.fromEntries(ALL_STATUSES_FOR_BREAKDOWN.map((status) => [status, row[status] ?? 0]));
+
+const dateRangeFilter = (
+  dateFrom: string | undefined,
+  dateTo: string | undefined,
+  timezone: string,
+): { start: Date; end: Date } => {
+  const today = formatYmdInTz(new Date(), timezone);
+  return {
+    start: startOfCalendarDayInTz(dateFrom ?? today, timezone),
+    end: endOfCalendarDayInTz(dateTo ?? today, timezone),
+  };
+};
+
+const buildCallsStatsMatch = ({ dateFrom, dateTo, clientId, timezone = "UTC" }: StatsDateRangeParams) => {
+  const range = dateFrom || dateTo ? dateRangeFilter(dateFrom, dateTo, timezone) : null;
+  return {
+    ...(range ? { createdAt: { $gte: range.start, $lte: range.end } } : {}),
+    ...(clientId ? { clientId } : {}),
+  };
+};
+
+export const aggregateActiveCallsSummary = async (
+  clientId?: string,
+): Promise<ActiveCallsSummary> => {
+  const coll = getCallsCollection();
+  const twoHoursAgo = new Date(Date.now() - ACTIVE_CALLS_WINDOW_MS);
+
+  const match = {
+    status: { $in: ACTIVE_STATUSES },
+    updatedAt: { $gte: twoHoursAgo },
+    ...(clientId ? { clientId } : {}),
+  };
+
+  const facetResult = await coll
+    .aggregate<{
+      counts: { total: number; incoming: number; outgoing: number }[];
+      activeClients: { _id: string }[];
+    }>([
+      { $match: match },
+      {
+        $facet: {
+          counts: [
+            {
+              $group: {
+                _id: null,
+                total: { $sum: 1 },
+                incoming: { $sum: { $cond: ["$isIncomingCall", 1, 0] } },
+                outgoing: { $sum: { $cond: ["$isOutgoingCall", 1, 0] } },
+              },
+            },
+          ],
+          activeClients: [{ $group: { _id: "$clientId" } }],
+        },
+      },
+    ])
+    .next();
+
+  const counts = facetResult?.counts?.[0];
+
+  return {
+    total: counts?.total ?? 0,
+    incoming: counts?.incoming ?? 0,
+    outgoing: counts?.outgoing ?? 0,
+    activeClientIds: (facetResult?.activeClients ?? []).map((d) => d._id || "Unknown"),
+  };
+};
+
+export const aggregateTodayCallsSummary = async ({
+  dateFrom,
+  dateTo,
+  clientId,
+  timezone = "UTC",
+}: StatsDateRangeParams): Promise<TodayCallsSummary> => {
+  const coll = getCallsCollection();
+  const match = buildCallsStatsMatch({ dateFrom, dateTo, clientId, timezone });
+
+  const facetResult = await coll
+    .aggregate<{
+      byStatus: { _id: string; count: number }[];
+      byType: { _id: string; count: number }[];
+      total: { count: number }[];
+      totalSeconds: { seconds: number }[];
+    }>([
+      { $match: match },
+      {
+        $facet: {
+          byStatus: [{ $group: { _id: "$status", count: { $sum: 1 } } }],
+          byType: [
+            {
+              $group: {
+                _id: { $cond: ["$isIncomingCall", "incoming", "outgoing"] },
+                count: { $sum: 1 },
+              },
+            },
+          ],
+          total: [{ $group: { _id: null, count: { $sum: 1 } } }],
+          totalSeconds: [{ $group: { _id: null, seconds: { $sum: "$callLength" } } }],
+        },
+      },
+    ])
+    .next();
+
+  const byStatus: Record<string, number> = {};
+  (facetResult?.byStatus ?? []).forEach((s) => {
+    byStatus[s._id] = s.count;
+  });
+  const byType: Record<string, number> = {};
+  (facetResult?.byType ?? []).forEach((t) => {
+    byType[t._id] = t.count;
+  });
+
+  const totalSeconds = facetResult?.totalSeconds?.[0]?.seconds ?? 0;
+
+  return {
+    total: facetResult?.total?.[0]?.count ?? 0,
+    incoming: byType.incoming ?? 0,
+    outgoing: byType.outgoing ?? 0,
+    completed: byStatus.completed ?? 0,
+    failed: byStatus.failed ?? 0,
+    busy: byStatus.busy ?? 0,
+    noAnswer: byStatus["no-answer"] ?? 0,
+    totalMinutes: Math.ceil(totalSeconds / 60),
+  };
+};
+
+export const aggregateClientCallStats = async ({
+  dateFrom,
+  dateTo,
+  clientId,
+  timezone = "UTC",
+}: StatsDateRangeParams): Promise<ClientCallStats[]> => {
+  const coll = getCallsCollection();
+  const match = buildCallsStatsMatch({ dateFrom, dateTo, clientId, timezone });
+
+  const rows = await coll
+    .aggregate<
+      {
+        _id: string;
+        totalCalls: number;
+        totalSeconds: number;
+        lastCallDate: Date;
+      } & StatusCountFields
+    >([
+      { $match: match },
+      {
+        $group: {
+          _id: "$clientId",
+          totalCalls: { $sum: 1 },
+          ...buildStatusCountFields("$status"),
+          totalSeconds: { $sum: "$callLength" },
+          lastCallDate: { $max: "$createdAt" },
+        },
+      },
+      { $sort: { totalCalls: -1 } },
+    ])
+    .toArray();
+
+  return rows.map((r) => ({
+    clientId: r._id || "Unknown",
+    totalCalls: r.totalCalls,
+    statusCounts: extractStatusCounts(r),
+    totalMinutes: Math.ceil((r.totalSeconds || 0) / 60),
+    lastCallDate: r.lastCallDate,
+  }));
+};
+
+export const aggregateSessionCallStats = async ({
+  dateFrom,
+  dateTo,
+  clientId,
+  timezone = "UTC",
+}: StatsDateRangeParams): Promise<SessionCallStats[]> => {
+  const coll = getCallsCollection();
+  const match = buildCallsStatsMatch({ dateFrom, dateTo, clientId, timezone });
+
+  const rows = await coll
+    .aggregate<
+      {
+        _id: ObjectId | null;
+        sessionDoc: { session_name: string }[];
+        totalCalls: number;
+      } & StatusCountFields
+    >([
+      { $match: match },
+      {
+        $group: {
+          _id: "$sessionId",
+          totalCalls: { $sum: 1 },
+          ...buildStatusCountFields("$status"),
+        },
+      },
+      {
+        $lookup: {
+          from: "sessions",
+          localField: "_id",
+          foreignField: "_id",
+          as: "sessionDoc",
+        },
+      },
+      { $sort: { totalCalls: -1 } },
+    ])
+    .toArray();
+
+  return rows.map((r) => ({
+    // A null sessionId is an incoming call (expected), not a broken/orphaned one.
+    sessionId: r._id ? r._id.toString() : INCOMING_SESSION_ID,
+    sessionName: r._id ? r.sessionDoc[0]?.session_name || "Unknown" : "Incoming Call",
+    totalCalls: r.totalCalls,
+    statusCounts: extractStatusCounts(r),
+  }));
+};
+
+export const getAllClientsLastCallDate = async (): Promise<Map<string, Date>> => {
+  const rows = await getCallsCollection()
+    .aggregate<{ _id: string; lastCallDate: Date }>([
+      { $group: { _id: "$clientId", lastCallDate: { $max: "$createdAt" } } },
+    ])
+    .toArray();
+
+  return new Map(rows.map((r) => [r._id, r.lastCallDate]));
+};
+
+export const findClientIdsByCallSids = async (
+  callSids: string[],
+): Promise<Map<string, string>> => {
+  if (callSids.length === 0) return new Map();
+
+  const docs = await getCallsCollection()
+    .find(
+      { callSid: { $in: callSids } },
+      { projection: { _id: 0, clientId: 1, callSid: 1 } },
+    )
+    .toArray();
+
+  return new Map(docs.map((d) => [d.callSid, d.clientId]));
+};