@talkpilot/core-db 1.3.88 → 1.3.89

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

@@ -4,22 +4,39 @@ import {
   CallQueryOptions,
   CallUpdateParams,
   getDb,
+  getClientsCollection,
 } from "../index";
 import type {
   CountOpts,
   DateRange,
   ToolExecution,
   CallStatus,
+  ActiveCallsSummary,
+  TodayCallsSummary,
+  ClientCallStatsPage,
+  ClientCallStatsParams,
+  SessionCallStats,
+  StatsDateRangeParams,
   CallEndedBy,
 } from "./calls.types";
 import {
   TOOL_EXECUTIONS_DEFAULT_LIMIT,
   TOOL_EXECUTIONS_DEFAULT_SKIP,
+  ACTIVE_STATUSES,
+  ACTIVE_CALLS_WINDOW_MS,
+  INCOMING_SESSION_ID,
+  UNKNOWN_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");
@@ -293,3 +310,306 @@ export async function getCallsHourlyAggregation(
     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,
+  clientIds,
+  timezone = "UTC",
+}: StatsDateRangeParams) => {
+  const range = dateFrom || dateTo ? dateRangeFilter(dateFrom, dateTo, timezone) : null;
+  const clientConditions = [
+    ...(clientId ? [{ clientId }] : []),
+    ...(clientIds ? [{ clientId: { $in: clientIds } }] : []),
+  ];
+  return {
+    ...(range ? { createdAt: { $gte: range.start, $lte: range.end } } : {}),
+    ...(clientConditions.length > 0 ? { $and: clientConditions } : {}),
+  };
+};
+
+export const findClientIdsWithCalls = async ({
+  dateFrom,
+  dateTo,
+  timezone = "UTC",
+}: StatsDateRangeParams): Promise<string[]> =>
+  getCallsCollection().distinct("clientId", buildCallsStatsMatch({ dateFrom, dateTo, timezone }));
+
+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,
+  clientIds,
+  timezone = "UTC",
+  skip = 0,
+  limit,
+}: ClientCallStatsParams): Promise<ClientCallStatsPage> => {
+  const [result] = await getCallsCollection()
+    .aggregate<{
+      rows: ({
+        _id: string;
+        totalCalls: number;
+        totalSeconds: number;
+        lastCallDate: Date;
+      } & StatusCountFields)[];
+      total: { count: number }[];
+    }>([
+      { $match: buildCallsStatsMatch({ dateFrom, dateTo, clientId, clientIds, timezone }) },
+      {
+        $group: {
+          _id: "$clientId",
+          totalCalls: { $sum: 1 },
+          ...buildStatusCountFields("$status"),
+          totalSeconds: { $sum: "$callLength" },
+          lastCallDate: { $max: "$createdAt" },
+        },
+      },
+      {
+        $lookup: {
+          from: getClientsCollection().collectionName,
+          localField: "_id",
+          foreignField: "clientId",
+          as: "client",
+        },
+      },
+      { $match: { "client.0": { $exists: true } } },
+      { $project: { client: 0 } },
+      { $sort: { totalCalls: -1, _id: 1 } },
+      {
+        $facet: {
+          rows: [{ $skip: skip }, ...(limit ? [{ $limit: limit }] : [])],
+          total: [{ $count: "count" }],
+        },
+      },
+    ])
+    .toArray();
+
+  return {
+    rows: (result?.rows ?? []).map((r) => ({
+      clientId: r._id,
+      totalCalls: r.totalCalls,
+      statusCounts: extractStatusCounts(r),
+      totalMinutes: Math.ceil((r.totalSeconds || 0) / 60),
+      lastCallDate: r.lastCallDate,
+    })),
+    total: result?.total[0]?.count ?? 0,
+  };
+};
+
+export const aggregateSessionCallStats = async ({
+  dateFrom,
+  dateTo,
+  clientId,
+  timezone = "UTC",
+}: StatsDateRangeParams): Promise<SessionCallStats[]> => {
+  const coll = getCallsCollection();
+  const match = buildCallsStatsMatch({ dateFrom, dateTo, clientId, timezone });
+
+  const sessionGroupKey = {
+    $cond: [
+      { $eq: ["$isIncomingCall", true] },
+      INCOMING_SESSION_ID,
+      { $ifNull: ["$sessionId", UNKNOWN_SESSION_ID] },
+    ],
+  };
+
+  const rows = await coll
+    .aggregate<
+      {
+        _id: ObjectId | string;
+        sessionDoc: { session_name: string }[];
+        totalCalls: number;
+      } & StatusCountFields
+    >([
+      { $match: match },
+      {
+        $group: {
+          _id: sessionGroupKey,
+          totalCalls: { $sum: 1 },
+          ...buildStatusCountFields("$status"),
+        },
+      },
+      {
+        $lookup: {
+          from: "sessions",
+          localField: "_id",
+          foreignField: "_id",
+          as: "sessionDoc",
+        },
+      },
+      { $sort: { totalCalls: -1 } },
+    ])
+    .toArray();
+
+  return rows.map((r) => ({
+    sessionId: r._id.toString(),
+    // No session, or a deleted/unnamed one, has no name to look up: that is "Unknown".
+    sessionName:
+      r._id === INCOMING_SESSION_ID
+        ? "Incoming Call"
+        : r.sessionDoc[0]?.session_name || "Unknown",
+    totalCalls: r.totalCalls,
+    statusCounts: extractStatusCounts(r),
+  }));
+};
+
+export const findLastCallDatesByClientIds = async (
+  clientIds: string[],
+): Promise<Map<string, Date>> => {
+  if (clientIds.length === 0) return new Map();
+
+  const rows = await getCallsCollection()
+    .aggregate<{ _id: string; lastCallDate: Date }>([
+      { $match: { clientId: { $in: clientIds } } },
+      { $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]));
+};

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

@@ -166,3 +166,55 @@ export type DateRange = {
   since?: Date;
   until?: Date;
 };
+
+export type StatsDateRangeParams = {
+  dateFrom?: string;
+  dateTo?: string;
+  clientId?: string;
+  /** Restricts to these clients. Combined with clientId, both must match. */
+  clientIds?: string[];
+  timezone?: string;
+};
+
+export type ClientCallStatsParams = StatsDateRangeParams & {
+  skip?: number;
+  limit?: number;
+};
+
+export type ActiveCallsSummary = {
+  total: number;
+  incoming: number;
+  outgoing: number;
+  activeClientIds: string[];
+};
+
+export type TodayCallsSummary = {
+  total: number;
+  incoming: number;
+  outgoing: number;
+  completed: number;
+  failed: number;
+  busy: number;
+  noAnswer: number;
+  totalMinutes: number;
+};
+
+export type ClientCallStats = {
+  clientId: string;
+  totalCalls: number;
+  statusCounts: Record<string, number>;
+  totalMinutes: number;
+  lastCallDate: Date;
+};
+
+export type ClientCallStatsPage = {
+  rows: ClientCallStats[];
+  total: number;
+};
+
+export type SessionCallStats = {
+  sessionId: string;
+  sessionName: string;
+  totalCalls: number;
+  statusCounts: Record<string, number>;
+};

package/src/talkpilot/clients/__tests__/clients.getters.spec.ts

@@ -0,0 +1,224 @@
+import {
+  getClientsCollection,
+  getAllClientIds,
+  getBackofficeRole,
+  setBackofficeRole,
+  countBackofficeAdmins,
+  findClientsPage,
+} from "../clients.getters";
+import { getPhoneNumbersCollection } from "../../phone_numbers/phone_numbers.getter";
+import { createClient, createPhoneNumber } from "../../../test-utils/factories";
+
+describe("db.clients", () => {
+  describe("getAllClientIds", () => {
+    it("should return the ids of all clients", async () => {
+      await getClientsCollection().insertMany([
+        createClient({ clientId: "idClientA" }),
+        createClient({ clientId: "idClientB" }),
+      ]);
+
+      const result = await getAllClientIds();
+
+      expect(result.sort()).toEqual(["idClientA", "idClientB"]);
+    });
+
+    it("should return an empty array when there are no clients", async () => {
+      const result = await getAllClientIds();
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("getBackofficeRole", () => {
+    it("returns 'admin' when backoffice.admin is set", async () => {
+      await getClientsCollection().insertOne(
+        createClient({
+          clientId: "roleAdmin",
+          roles: { backoffice: { admin: true } },
+        }),
+      );
+      expect(await getBackofficeRole("roleAdmin")).toBe("admin");
+    });
+
+    it("returns 'viewer' when only backoffice.viewer is set", async () => {
+      await getClientsCollection().insertOne(
+        createClient({
+          clientId: "roleViewer",
+          roles: { backoffice: { viewer: true } },
+        }),
+      );
+      expect(await getBackofficeRole("roleViewer")).toBe("viewer");
+    });
+
+    it("lets admin win when both flags are set", async () => {
+      await getClientsCollection().insertOne(
+        createClient({
+          clientId: "roleBoth",
+          roles: { backoffice: { admin: true, viewer: true } },
+        }),
+      );
+      expect(await getBackofficeRole("roleBoth")).toBe("admin");
+    });
+
+    it("ignores the legacy roles.admin flag", async () => {
+      await getClientsCollection().insertOne(
+        createClient({ clientId: "legacyAdmin", roles: { admin: true } }),
+      );
+      expect(await getBackofficeRole("legacyAdmin")).toBeNull();
+    });
+
+    it("returns null for false flags, a client without roles, and an unknown client", async () => {
+      await getClientsCollection().insertMany([
+        createClient({
+          clientId: "roleFalse",
+          roles: { backoffice: { admin: false, viewer: false } },
+        }),
+        createClient({ clientId: "noRoles" }),
+      ]);
+      expect(await getBackofficeRole("roleFalse")).toBeNull();
+      expect(await getBackofficeRole("noRoles")).toBeNull();
+      expect(await getBackofficeRole("missing")).toBeNull();
+    });
+  });
+
+  describe("setBackofficeRole", () => {
+    it("sets one role, clears the other, and leaves roles.admin alone", async () => {
+      await getClientsCollection().insertOne(
+        createClient({
+          clientId: "switchRole",
+          roles: { admin: true, backoffice: { admin: true } },
+        }),
+      );
+
+      expect(await setBackofficeRole("switchRole", "viewer")).toBe(true);
+      expect(await getBackofficeRole("switchRole")).toBe("viewer");
+
+      await setBackofficeRole("switchRole", null);
+      expect(await getBackofficeRole("switchRole")).toBeNull();
+
+      const doc = await getClientsCollection().findOne({
+        clientId: "switchRole",
+      });
+      expect(doc?.roles?.admin).toBe(true);
+    });
+
+    it("returns false for an unknown client", async () => {
+      expect(await setBackofficeRole("missing", "admin")).toBe(false);
+    });
+  });
+
+  describe("countBackofficeAdmins", () => {
+    it("counts only clients with the backoffice admin flag", async () => {
+      await getClientsCollection().insertMany([
+        createClient({
+          clientId: "adminOne",
+          roles: { backoffice: { admin: true } },
+        }),
+        createClient({
+          clientId: "viewerOne",
+          roles: { backoffice: { viewer: true } },
+        }),
+        createClient({ clientId: "legacyOnly", roles: { admin: true } }),
+      ]);
+      expect(await countBackofficeAdmins()).toBe(1);
+    });
+  });
+
+  describe("findClientsPage", () => {
+    const insertClientsCreatedAt = (...clientIds: string[]) =>
+      getClientsCollection().insertMany(
+        clientIds.map((clientId, index) =>
+          createClient({
+            clientId,
+            createdAt: new Date(Date.UTC(2026, 0, index + 1)),
+          }),
+        ),
+      );
+
+    it("returns one page, newest client first, with the total across all pages", async () => {
+      await insertClientsCreatedAt("pageOldest", "pageMiddle", "pageNewest");
+
+      const firstPage = await findClientsPage({ skip: 0, limit: 2 });
+      const secondPage = await findClientsPage({ skip: 2, limit: 2 });
+
+      expect(firstPage.clients.map((c) => c.clientId)).toEqual([
+        "pageNewest",
+        "pageMiddle",
+      ]);
+      expect(firstPage.total).toBe(3);
+      expect(secondPage.clients.map((c) => c.clientId)).toEqual(["pageOldest"]);
+      expect(secondPage.total).toBe(3);
+    });
+
+    it("searches the clientId case-insensitively", async () => {
+      await insertClientsCreatedAt("SearchMe-1", "other-client");
+
+      const page = await findClientsPage({
+        skip: 0,
+        limit: 10,
+        search: "searchme",
+      });
+
+      expect(page.clients.map((c) => c.clientId)).toEqual(["SearchMe-1"]);
+      expect(page.total).toBe(1);
+    });
+
+    it("searches phone numbers, treating regex characters like + as plain text", async () => {
+      await insertClientsCreatedAt("phoneOwner", "noPhoneMatch");
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: "phoneOwner",
+          phone_number: "+97233823446",
+        }),
+        createPhoneNumber({
+          client_id: "noPhoneMatch",
+          phone_number: "+97250000000",
+        }),
+      ]);
+
+      const page = await findClientsPage({
+        skip: 0,
+        limit: 10,
+        search: "+9723382",
+      });
+
+      expect(page.clients.map((c) => c.clientId)).toEqual(["phoneOwner"]);
+    });
+
+    it("filters to one exact clientId", async () => {
+      await insertClientsCreatedAt("exactClient", "exactClient-2");
+
+      const page = await findClientsPage({
+        skip: 0,
+        limit: 10,
+        clientId: "exactClient",
+      });
+
+      expect(page.clients.map((c) => c.clientId)).toEqual(["exactClient"]);
+    });
+
+    it("restricts to clientIds and leaves out excludeClientIds", async () => {
+      await insertClientsCreatedAt("listA", "listB", "listC");
+
+      const included = await findClientsPage({
+        skip: 0,
+        limit: 10,
+        clientIds: ["listA", "listC"],
+      });
+      const excluded = await findClientsPage({
+        skip: 0,
+        limit: 10,
+        excludeClientIds: ["listA"],
+      });
+
+      expect(included.clients.map((c) => c.clientId)).toEqual([
+        "listC",
+        "listA",
+      ]);
+      expect(excluded.clients.map((c) => c.clientId)).toEqual([
+        "listC",
+        "listB",
+      ]);
+      expect(excluded.total).toBe(2);
+    });
+  });
+});