@talkpilot/core-db 1.2.1 → 1.3.0

package/src/talkpilot/calls/__tests__/calls.statistics.spec.ts

@@ -0,0 +1,281 @@
+import {
+  aggregateCallsHourlyByRange,
+  aggregateCallsRouting,
+  aggregateCallsSummary,
+  aggregateCallsTrend,
+  findCallSidsWithDraftTicketsByCity,
+  findCallSidsWithTicketsByCity,
+  getCallsCollection,
+  getDepartmentsSubjectsCollection,
+  getTicketsCollection,
+  findSubjectsByCallSids,
+  rangeDurationDays,
+  rangeDurationMonths,
+  resolveTimeBucketFromRange,
+  ticketStatsDateScopeFromYmd,
+} from "../../../index";
+import type { Call } from "../calls.types";
+import type { CallsStatsFilter } from "../calls.statistics.types";
+import {
+  createDepartmentSubject,
+  createIncomingCallDoc,
+  createOutGoingCallDoc,
+  createTicket,
+} from "../../../test-utils/factories";
+const CLIENT_ID = "stats-client";
+const CITY = "tests" as const;
+const TZ = "Asia/Jerusalem";
+const at = (iso: string) => new Date(iso);
+
+const insertCall = (call: Call) =>
+  getCallsCollection().insertOne({ ...call, env: call.env ?? "test" });
+
+const incoming = (callSid: string, createdAt: string, extra?: Partial<Call>) =>
+  insertCall(
+    createIncomingCallDoc({
+      clientId: CLIENT_ID,
+      callSid,
+      createdAt: at(createdAt),
+      updatedAt: at(extra?.updatedAt?.toISOString() ?? createdAt),
+      ...extra,
+    }),
+  );
+
+const filter = (overrides?: Partial<CallsStatsFilter>): CallsStatsFilter => ({
+  clientId: CLIENT_ID,
+  startStr: "2026-05-01",
+  endStr: "2026-05-31",
+  timezone: TZ,
+  callSidsWithTickets: [],
+  callSidsWithDraftTickets: [],
+  ...overrides,
+});
+
+const ticketDateScope = (statsFilter: CallsStatsFilter) =>
+  ticketStatsDateScopeFromYmd(statsFilter.startStr, statsFilter.endStr, statsFilter.timezone);
+
+const summaryWithTicketSids = async (overrides?: Partial<CallsStatsFilter>) => {
+  const statsFilter = filter(overrides);
+  const dateScope = ticketDateScope(statsFilter);
+  const callSidsWithTickets = await findCallSidsWithTicketsByCity(CITY, dateScope);
+  const callSidsWithDraftTickets = await findCallSidsWithDraftTicketsByCity(CITY, dateScope);
+  return aggregateCallsSummary(filter({ callSidsWithTickets, callSidsWithDraftTickets, ...overrides }));
+};
+
+describe("calls statistics getters", () => {
+  beforeEach(async () => {
+    await incoming("CA-with-ticket", "2026-05-10T10:00:00.000Z", {
+      callLength: 120,
+      updatedAt: at("2026-05-10T10:02:00.000Z"),
+    });
+    await incoming("CA-transferred", "2026-05-11T14:00:00.000Z", {
+      callLength: 60,
+      redirectedCall: true,
+      updatedAt: at("2026-05-11T14:01:00.000Z"),
+    });
+    await incoming("CA-hijacked", "2026-05-12T09:00:00.000Z", {
+      callLength: 90,
+      isConferenceCall: true,
+      redirectedCall: false,
+      updatedAt: at("2026-05-12T09:01:30.000Z"),
+    });
+    await insertCall(
+      createOutGoingCallDoc({
+        clientId: CLIENT_ID,
+        callSid: "CA-outgoing",
+        createdAt: at("2026-05-10T11:00:00.000Z"),
+        updatedAt: at("2026-05-10T11:01:00.000Z"),
+      }),
+    );
+    await getTicketsCollection().insertOne(
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-with-ticket",
+        createdAt: at("2026-05-10T10:00:00.000Z"),
+        updatedAt: at("2026-05-10T10:00:00.000Z"),
+        externalCallFields: { event_subject_id: "100" },
+      }),
+    );
+  });
+
+  it("should exclude calls outside the filter date range from summary", async () => {
+    await incoming("CA-old", "2024-01-01T10:00:00.000Z", { callLength: 999 });
+    const summary = await aggregateCallsSummary(filter());
+    expect(summary).toMatchObject({ totalCalls: 3, avgDurationSeconds: 90 });
+  });
+
+  it("should aggregate summary with ticket sids and opened-ticket filter", async () => {
+    expect(await summaryWithTicketSids()).toEqual({
+      totalCalls: 3,
+      openTickets: 1,
+      draftTickets: 0,
+      avgDurationSeconds: 90,
+    });
+
+    const statsFilter = filter();
+    const callSidsWithTickets = await findCallSidsWithTicketsByCity(CITY, ticketDateScope(statsFilter));
+    const openedOnly = await aggregateCallsSummary(
+      filter({ callSidsWithTickets, ticketStatusFilters: ["opened"] }),
+    );
+    expect(openedOnly).toMatchObject({ totalCalls: 1, openTickets: 1 });
+  });
+
+  it("should classify routing into mutually exclusive buckets", async () => {
+    expect(await aggregateCallsRouting(filter())).toEqual({
+      transferred: 1,
+      hijacked: 1,
+      aiHandled: 1,
+    });
+  });
+
+  it("should resolve subjects by callSid with optional limit", async () => {
+    await getDepartmentsSubjectsCollection().insertOne(
+      createDepartmentSubject({ cityName: CITY, subject_id: "100", subjectName: "Water" }),
+    );
+    expect(await findSubjectsByCallSids(CITY, ["CA-with-ticket"])).toEqual([
+      { subject: "Water", count: 1 },
+    ]);
+
+    await getDepartmentsSubjectsCollection().insertMany([
+      createDepartmentSubject({ cityName: CITY, subject_id: "200", subjectName: "Roads" }),
+      createDepartmentSubject({ cityName: CITY, subject_id: "300", subjectName: "Lighting" }),
+    ]);
+    await getTicketsCollection().insertMany([
+      createTicket({ cityName: CITY, callSid: "CA-subject-1", externalCallFields: { event_subject_id: "200" } }),
+      createTicket({ cityName: CITY, callSid: "CA-subject-2", externalCallFields: { event_subject_id: "300" } }),
+    ]);
+    const sids = ["CA-subject-1", "CA-subject-2"];
+    expect(await findSubjectsByCallSids(CITY, sids)).toHaveLength(2);
+    expect(await findSubjectsByCallSids(CITY, sids, 1)).toHaveLength(1);
+  });
+
+  it("should aggregate hourly buckets with averages and optional hour window", async () => {
+    const statsFilter = filter();
+    const daysInRange = rangeDurationDays(statsFilter.startStr, statsFilter.endStr);
+    const full = await aggregateCallsHourlyByRange(statsFilter);
+
+    expect(full).toHaveLength(24);
+    expect(full[0]).toEqual({ hour: 0, totalCalls: 0, avgCalls: 0 });
+    expect(full.reduce((sum, h) => sum + h.totalCalls, 0)).toBe(3);
+    expect(full.find((h) => h.hour === 12)).toEqual({
+      hour: 12,
+      totalCalls: 1,
+      avgCalls: Math.round((1 / daysInRange) * 10) / 10,
+    });
+
+    expect(
+      (await aggregateCallsHourlyByRange(filter({ startStr: "2026-05-12", endStr: "2026-05-12" }))).find(
+        (h) => h.hour === 12,
+      ),
+    ).toEqual({ hour: 12, totalCalls: 1, avgCalls: 1 });
+
+    const avgForOneCall = Math.round((1 / daysInRange) * 10) / 10;
+    expect(await aggregateCallsHourlyByRange(filter({ hourFrom: 10, hourTo: 12 }))).toEqual([
+      { hour: 10, totalCalls: 0, avgCalls: 0 },
+      { hour: 11, totalCalls: 0, avgCalls: 0 },
+      { hour: 12, totalCalls: 1, avgCalls: avgForOneCall },
+    ]);
+  });
+
+  it("should fill day trend buckets with zeros", async () => {
+    expect(await aggregateCallsTrend(filter({ startStr: "2026-05-10", endStr: "2026-05-14" }), "day")).toEqual([
+      { bucket: "2026-05-10", totalCalls: 1, openTickets: 0 },
+      { bucket: "2026-05-11", totalCalls: 1, openTickets: 0 },
+      { bucket: "2026-05-12", totalCalls: 1, openTickets: 0 },
+      { bucket: "2026-05-13", totalCalls: 0, openTickets: 0 },
+      { bucket: "2026-05-14", totalCalls: 0, openTickets: 0 },
+    ]);
+  });
+
+  it("should bucket calls by calendar day in filter timezone", async () => {
+    await incoming("CA-jerusalem-midnight", "2026-05-09T21:00:00.000Z", { callLength: 45 });
+    expect(await aggregateCallsTrend(filter({ startStr: "2026-05-10", endStr: "2026-05-12" }), "day")).toEqual([
+      { bucket: "2026-05-10", totalCalls: 2, openTickets: 0 },
+      { bucket: "2026-05-11", totalCalls: 1, openTickets: 0 },
+      { bucket: "2026-05-12", totalCalls: 1, openTickets: 0 },
+    ]);
+  });
+
+  it("should pick month, week, or day bucket from calendar-month span", () => {
+    expect(rangeDurationMonths("2025-06-01", "2026-05-31")).toBe(12);
+    expect(resolveTimeBucketFromRange("2025-06-01", "2026-05-31")).toBe("month");
+    expect(resolveTimeBucketFromRange("2026-01-01", "2026-06-30")).toBe("week");
+    expect(resolveTimeBucketFromRange("2026-04-01", "2026-06-30")).toBe("day");
+  });
+
+  it("should fill month trend buckets with zeros", async () => {
+    await incoming("CA-feb", "2026-02-15T10:00:00.000Z");
+    await incoming("CA-apr", "2026-04-15T10:00:00.000Z");
+    const month = await aggregateCallsTrend(filter({ startStr: "2026-01-01", endStr: "2026-06-30" }), "month");
+    expect(month.map((row) => row.bucket)).toEqual([
+      "2026-01-01",
+      "2026-02-01",
+      "2026-03-01",
+      "2026-04-01",
+      "2026-05-01",
+      "2026-06-01",
+    ]);
+    expect(month.find((row) => row.bucket === "2026-02-01")).toMatchObject({ totalCalls: 1, openTickets: 0 });
+    expect(month.find((row) => row.bucket === "2026-05-01")).toMatchObject({ totalCalls: 3, openTickets: 0 });
+  });
+
+  it("should fill week trend buckets with zeros", async () => {
+    await incoming("CA-week-2", "2026-05-18T10:00:00.000Z");
+    expect(
+      await aggregateCallsTrend(filter({ startStr: "2026-05-04", endStr: "2026-05-24" }), "week"),
+    ).toEqual([
+      { bucket: "2026-05-04/2026-05-09", totalCalls: 0, openTickets: 0 },
+      { bucket: "2026-05-10/2026-05-16", totalCalls: 3, openTickets: 0 },
+      { bucket: "2026-05-17/2026-05-23", totalCalls: 1, openTickets: 0 },
+      { bucket: "2026-05-24/2026-05-24", totalCalls: 0, openTickets: 0 },
+    ]);
+  });
+
+  it("should complete every day bucket across a 12-month range without hanging (DST regression)", async () => {
+    const startStr = "2025-07-02";
+    const endStr = "2026-06-02";
+    const startedAt = Date.now();
+    const trend = await aggregateCallsTrend(filter({ startStr, endStr }), "day");
+    const elapsedMs = Date.now() - startedAt;
+
+    expect(trend).toHaveLength(rangeDurationDays(startStr, endStr));
+    expect(trend[0]).toEqual({ bucket: startStr, totalCalls: 0, openTickets: 0 });
+    expect(trend[trend.length - 1].bucket).toBe(endStr);
+    expect(elapsedMs).toBeLessThan(5000);
+  });
+
+  it("should count draft tickets and distinct draft call sids", async () => {
+    const descriptionDraft = createTicket({
+      cityName: CITY,
+      callSid: "CA-hijacked",
+      createdAt: at("2026-05-12T09:00:00.000Z"),
+      updatedAt: at("2026-05-12T09:00:00.000Z"),
+    });
+    descriptionDraft.externalCallFields = { event_description: "draft ticket" };
+    await getTicketsCollection().insertMany([
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-transferred",
+        createdAt: at("2026-05-11T14:00:00.000Z"),
+        updatedAt: at("2026-05-11T14:00:00.000Z"),
+        externalCallFields: { event_subject_id: "100" },
+      }),
+      descriptionDraft,
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-whitespace-draft",
+        createdAt: at("2026-05-12T10:00:00.000Z"),
+        updatedAt: at("2026-05-12T10:00:00.000Z"),
+        externalCallFields: { event_subject_id: "   " },
+      }),
+    ]);
+
+    const statsFilter = filter();
+    const dateScope = ticketDateScope(statsFilter);
+    const callSidsWithDraftTickets = await findCallSidsWithDraftTicketsByCity(CITY, dateScope);
+    const summary = await summaryWithTicketSids();
+
+    expect(callSidsWithDraftTickets.sort()).toEqual(["CA-hijacked", "CA-whitespace-draft"].sort());
+    expect(summary).toMatchObject({ openTickets: 3, draftTickets: 1 });
+  });
+});

package/src/talkpilot/calls/calls.constants.ts

@@ -0,0 +1,20 @@
+/** Customer role within a conference call. */
+export const CONFERENCE_ROLE_CUSTOMER = "customer" as const;
+
+/** Supervisor role within a conference call. */
+export const CONFERENCE_ROLE_SUPERVISOR = "supervisor" as const;
+
+/** Hours in a single day. */
+export const HOURS_PER_DAY = 24;
+
+/** Max execution time (ms) for calls statistics aggregations. */
+export const STATS_MAX_TIME_MS = 30_000;
+
+/**
+ * When the client calls bar chart should group by week or month instead of day:
+ *   > MONTH threshold  -> one bar per month
+ *   > WEEK threshold   -> one bar per week
+ *   otherwise          -> one bar per day
+ */
+export const TREND_MONTH_BUCKET_MIN_MONTHS = 6;
+export const TREND_WEEK_BUCKET_MIN_MONTHS = 3;

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

@@ -5,10 +5,11 @@ import {
   CallUpdateParams,
   getDb,
 } from "../index";
-import type { CallsByHour, CountOpts, DateRange, ToolExecution } from "./calls.types";
+import type { CountOpts, DateRange, ToolExecution } from "./calls.types";
 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");
@@ -61,11 +62,11 @@ export const updateCallByCallSid = async (
 
 export const pushToolExecution = async (
   callSid: string,
-  execution: ToolExecution
+  execution: ToolExecution,
 ): Promise<void> => {
   await getCallsCollection().updateOne(
     { callSid },
-    { $push: { toolExecutions: execution } }
+    { $push: { toolExecutions: execution } },
   );
 };
 
@@ -217,13 +218,12 @@ export async function getCallsHourlyAggregation(
   clientId: string,
   dateStr: string,
   timezone: string,
-): Promise<CallsByHour[]> {
+): Promise<DashboardHeatmapMetric[]> {
   const coll = getCallsCollection();
   const rows = await coll
     .aggregate<{ _id: number; calls: number }>([
       // 1. Restrict to the given client
       { $match: { clientId } },
-      // 2. Derive dateLocal (createdAt as YYYY-MM-DD in timezone) and hour (0–23 from createdAt in timezone)
       {
         $addFields: {
           dateLocal: {
@@ -242,7 +242,7 @@ export async function getCallsHourlyAggregation(
     .toArray();
 
   return rows.map((r: any) => ({
-    hour: `${String(r._id).padStart(2, "0")}:00`,
+    hour: r._id,
     calls: r.calls,
   }));
 }