@talkpilot/core-db 1.3.1 → 1.3.4

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

@@ -3,237 +3,173 @@ import { getCallsCollection } from "../calls.getters";
 import { getClientConfig } from "../../clientsConfig";
 import utc from "dayjs/plugin/utc";
 import timezonePlugin from "dayjs/plugin/timezone";
-import isoWeek from "dayjs/plugin/isoWeek";
-import quarterOfYear from "dayjs/plugin/quarterOfYear";
 import {
   DashboardAggregationResult,
   DashboardDailyTrendMetric,
+  DashboardHeatmapMetric,
   DashboardReportQuery,
   DashboardReportResponse,
   DashboardSummaryMetrics,
-  DashboardVolumeGranularity,
-} from "./calls.dashboard.types";
-
-export type {
-  DashboardVolumeGranularity,
-  DashboardReportQuery,
-  DashboardReportResponse,
+  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,
-  answeredDuration: 0,
 };
 
 dayjs.extend(utc);
 dayjs.extend(timezonePlugin);
-dayjs.extend(isoWeek);
-dayjs.extend(quarterOfYear);
-
-const BUCKET_UNIT: Record<DashboardVolumeGranularity, string> = {
-  hour: "hour",
-  day: "day",
-  week: "isoWeek",
-  month: "month",
-  quarter: "quarter",
-  year: "year",
-};
-
-function formatBucketKey(
-  bucketStart: dayjs.Dayjs,
-  granularity: DashboardVolumeGranularity,
-): string {
-  switch (granularity) {
-    case "hour":
-      return bucketStart.format("YYYY-MM-DDTHH:00");
-    case "day":
-    case "week":
-      return bucketStart.format("YYYY-MM-DD");
-    case "month":
-      return bucketStart.format("YYYY-MM");
-    case "quarter":
-      return `${bucketStart.format("YYYY")}-Q${bucketStart.quarter()}`;
-    case "year":
-      return bucketStart.format("YYYY");
-  }
-}
-
-function generateBucketKeys(
-  startDateObj: Date,
-  endDateObj: Date,
-  granularity: DashboardVolumeGranularity,
-  timezone: string,
-): string[] {
-  const unitName = BUCKET_UNIT[granularity];
-  const startOfUnit = unitName as dayjs.OpUnitType;
-  const stepUnit = (
-    unitName === "isoWeek" ? "week" : unitName
-  ) as dayjs.ManipulateType;
-  const end = dayjs(endDateObj).tz(timezone);
-  let cursor = dayjs(startDateObj).tz(timezone).startOf(startOfUnit);
-
-  const keys: string[] = [];
-  while (cursor.isBefore(end) || cursor.isSame(end, startOfUnit)) {
-    keys.push(formatBucketKey(cursor, granularity));
-    cursor = cursor.add(1, stepUnit);
-  }
-  return keys;
-}
-
-function fillVolumeGaps(
-  bucketKeys: string[],
-  volumeDataRaw: { date: string; completed: number }[],
-): DashboardDailyTrendMetric[] {
-  const completedByKey = new Map(
-    volumeDataRaw.map((d) => [d.date, d.completed]),
-  );
-  return bucketKeys.map((date) => ({
-    date,
-    completed: completedByKey.get(date) ?? 0,
-  }));
-}
-
-function resolveVolumeGranularity(
-  startDateObj: Date,
-  endDateObj: Date,
-): DashboardVolumeGranularity {
-  const spanDays = dayjs(endDateObj).diff(dayjs(startDateObj), "day");
 
-  if (spanDays <= 2) return "hour";
-  if (spanDays <= 60) return "day";
-  if (spanDays <= 365) return "week";
-  if (spanDays <= 730) return "month";
-  if (spanDays <= 1460) return "quarter";
-  return "year";
+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] },
+        },
+      },
+    },
+  ];
 }
 
-const VOLUME_DATE_FORMATS: Partial<Record<DashboardVolumeGranularity, string>> =
-  {
-    hour: "%Y-%m-%dT%H:00",
-    day: "%Y-%m-%d",
-    month: "%Y-%m",
-    year: "%Y",
-  };
-
-function buildVolumeBucketIdExpression(
-  timezone: string,
-  granularity: DashboardVolumeGranularity,
-) {
-  if (granularity === "week") {
-    return {
-      $dateToString: {
-        format: "%Y-%m-%d",
-        date: {
-          $dateTrunc: {
+function buildDailyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          $dateToString: {
+            format: "%Y-%m-%d",
             date: "$createdAt",
-            unit: "week",
-            timezone,
-            startOfWeek: "monday",
+            timezone: timezone,
           },
         },
-        timezone,
+        count: { $sum: 1 },
+        completed: {
+          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
+        },
       },
-    };
-  }
+    },
+    { $sort: { _id: 1 } },
+  ];
+}
 
-  if (granularity === "quarter") {
-    return {
-      $concat: [
-        { $toString: { $year: { date: "$createdAt", timezone } } },
-        "-Q",
-        {
-          $toString: {
-            $add: [
-              {
-                $trunc: {
-                  $divide: [
-                    {
-                      $subtract: [
-                        { $month: { date: "$createdAt", timezone } },
-                        1,
-                      ],
-                    },
-                    3,
-                  ],
-                },
-              },
-              1,
-            ],
+function buildHourlyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          day: {
+            $dateToString: {
+              format: "%Y-%m-%d",
+              date: "$createdAt",
+              timezone: timezone,
+            },
           },
+          hour: { $hour: { date: "$createdAt", timezone: timezone } },
         },
-      ],
-    };
-  }
-
-  return {
-    $dateToString: {
-      format: VOLUME_DATE_FORMATS[granularity],
-      date: "$createdAt",
-      timezone,
+        count: { $sum: 1 },
+      },
     },
-  };
+  ];
 }
 
-function buildKpisPipeline() {
+export function buildCallLengthBucketsPipeline(
+  thresholds: CallLengthThresholds,
+) {
+  const { shortThreshold, mediumThreshold } = thresholds;
+
   return [
     {
       $group: {
         _id: null,
-        completedCount: {
-          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
+        short: {
+          $sum: { $cond: [{ $lt: ["$callLength", shortThreshold] }, 1, 0] },
         },
-        busyCount: {
-          $sum: { $cond: [{ $eq: ["$status", "busy"] }, 1, 0] },
-        },
-        answeredDuration: {
+        medium: {
           $sum: {
             $cond: [
-              { $in: ["$status", ["completed", "busy"]] },
-              "$callLength",
+              {
+                $and: [
+                  { $gte: ["$callLength", shortThreshold] },
+                  { $lte: ["$callLength", mediumThreshold] },
+                ],
+              },
+              1,
               0,
             ],
           },
         },
+        long: {
+          $sum: { $cond: [{ $gt: ["$callLength", mediumThreshold] }, 1, 0] },
+        },
       },
     },
   ];
 }
 
-function buildVolumeDataPipeline(
-  timezone: string,
-  granularity: DashboardVolumeGranularity,
-) {
-  return [
-    {
-      $group: {
-        _id: buildVolumeBucketIdExpression(timezone, granularity),
-        completed: {
-          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
-        },
-      },
-    },
-    { $sort: { _id: 1 } },
-  ];
+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,
-    granularity: requestedGranularity,
-  } = params;
+  const { clientId, startDate, endDate } = params;
   const clientConfig = await getClientConfig(clientId);
   const timezone = clientConfig?.timezone ?? "UTC";
 
-  const startDateObj = dayjs(startDate).tz(timezone).startOf("day").toDate();
-  const endDateObj = dayjs(endDate).tz(timezone).endOf("day").toDate();
+  const startDateObj = dayjs.tz(startDate, timezone).startOf("day").toDate();
+  const endDateObj = dayjs.tz(endDate, timezone).endOf("day").toDate();
 
-  const granularity =
-    requestedGranularity ?? resolveVolumeGranularity(startDateObj, endDateObj);
+  const thresholds: CallLengthThresholds = {
+    shortThreshold: clientConfig?.callLengthThresholds?.shortThreshold ?? 60,
+    mediumThreshold: clientConfig?.callLengthThresholds?.mediumThreshold ?? 180,
+  };
 
   const pipeline = [
     {
@@ -245,7 +181,9 @@ export async function getDashboardStats(
     {
       $facet: {
         kpis: buildKpisPipeline(),
-        volumeData: buildVolumeDataPipeline(timezone, granularity),
+        dailyData: buildDailyDataPipeline(timezone),
+        hourlyData: buildHourlyDataPipeline(timezone),
+        callLengthBuckets: buildCallLengthBucketsPipeline(thresholds),
       },
     },
   ];
@@ -256,36 +194,49 @@ export async function getDashboardStats(
     .toArray();
 
   const kpiData = aggregatedResult?.kpis?.[0] ?? DEFAULT_KPI_DATA;
-  const volumeDataRaw = aggregatedResult?.volumeData ?? [];
-
-  const answeredCount = kpiData.completedCount + kpiData.busyCount;
-  const answeredDuration = kpiData.answeredDuration ?? 0;
+  const dailyDataRaw = aggregatedResult?.dailyData ?? [];
+  const hourlyDataRaw = aggregatedResult?.hourlyData ?? [];
+  const callLengthRaw = aggregatedResult?.callLengthBuckets?.[0] ?? {
+    short: 0,
+    medium: 0,
+    long: 0,
+  };
 
   const kpis: DashboardSummaryMetrics = {
-    totalCalls: answeredCount,
+    totalCalls: kpiData.totalCalls,
     avgDurationSeconds:
-      answeredCount > 0 ? Math.round(answeredDuration / answeredCount) : 0,
-    timeSavedMinutes: Math.round(answeredDuration / 60),
+      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 bucketKeys = generateBucketKeys(
-    startDateObj,
-    endDateObj,
-    granularity,
-    timezone,
-  );
-  const volumeData: DashboardDailyTrendMetric[] = fillVolumeGaps(
-    bucketKeys,
-    volumeDataRaw.map((d) => ({ date: d._id, completed: d.completed })),
-  );
+  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,
-      volumeGranularity: granularity,
+      heatmap,
+      callLengthBuckets: {
+        short: callLengthRaw.short,
+        medium: callLengthRaw.medium,
+        long: callLengthRaw.long,
+      },
     },
   };
   return response;

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

@@ -5,35 +5,37 @@ export type DashboardHeatmapMetric = {
 
 export type DashboardDailyTrendMetric = {
   date: string;
+  count: number;
   completed: number;
 };
 
-export type DashboardVolumeGranularity =
-  | "hour"
-  | "day"
-  | "week"
-  | "month"
-  | "quarter"
-  | "year";
+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[];
-  volumeGranularity: DashboardVolumeGranularity;
+  heatmap: Record<string, DashboardHeatmapMetric[]>;
+  callLengthBuckets: DashboardDurationSegments;
 };
 
 export type DashboardReportQuery = {
   clientId: string;
   startDate: string;
   endDate: string;
-  granularity?: DashboardVolumeGranularity;
 };
 
 export type DashboardReportResponse = {
@@ -41,17 +43,28 @@ export type DashboardReportResponse = {
   charts: DashboardVisualData;
 };
 type RawKpiResult = {
+  totalCalls: number;
+  totalDuration: number | null;
   completedCount: number;
+  failedCount: number;
+  noAnswerCount: number;
   busyCount: number;
-  answeredDuration: number | null;
 };
 
-export type RawVolumeAggregationResult = {
+export type RawDailyAggregationResult = {
   _id: string;
+  count: number;
   completed: number;
 };
 
+export type RawHourlyAggregationResult = {
+  _id: { day: string; hour: number };
+  count: number;
+};
+
 export interface DashboardAggregationResult {
   kpis: RawKpiResult[];
-  volumeData: RawVolumeAggregationResult[];
+  dailyData: RawDailyAggregationResult[];
+  hourlyData: RawHourlyAggregationResult[];
+  callLengthBuckets: DashboardDurationSegments[];
 }

package/src/talkpilot/calls/index.ts

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

package/src/talkpilot/clientsConfig/__tests__/clientsConfig.spec.ts

@@ -36,6 +36,10 @@ describe("db.clientsConfig", () => {
             timezone: "Asia/Jerusalem",
             language: "he",
             defaultBaseUrl: "https://acme.example",
+            scheduler: {
+              type: "cron",
+              schedule: "0 9 * * 1-5",
+            },
           },
         },
       });
@@ -53,6 +57,9 @@ describe("db.clientsConfig", () => {
             timezone: "Asia/Jerusalem",
             language: "he",
             defaultBaseUrl: "https://acme.example",
+            scheduler: {
+              type: "cron",
+            },
           },
         },
       });

package/src/utils/date.utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared timezone-aware date helpers for statistics aggregations.
+ */
+
+/** Milliseconds in a single day. */
+export const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Maps a short weekday name (as produced by Intl) to its index (Sun = 0). */
+export const WEEKDAY: Record<string, number> = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+};
+
+/** Parses a `YYYY-MM-DD` string into `[year, month, day]` numbers. */
+export const parseYmd = (dateStr: string): [number, number, number] => {
+  const [y, m, d] = dateStr.split("-").map(Number);
+  return [y, m, d];
+};
+
+/** Builds a zero-padded `YYYY-MM-DD` string from numeric parts. */
+export const ymdToStr = (y: number, m: number, d: number): string =>
+  `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+
+/** Parses a `YYYY-MM-DD` string as midnight UTC. */
+export const toUtcDate = (dateStr: string): Date =>
+  new Date(`${dateStr}T00:00:00.000Z`);
+
+/** Formats a date as a `YYYY-MM-DD` string in UTC. */
+export const formatDate = (date: Date): string => date.toISOString().slice(0, 10);
+
+/** Adds `days` to a `YYYY-MM-DD` string, returning the resulting `YYYY-MM-DD`. */
+export const addDaysToDateStr = (dateStr: string, days: number): string =>
+  formatDate(new Date(toUtcDate(dateStr).getTime() + days * DAY_MS));
+
+/** Next civil calendar day (proleptic Gregorian). Avoids DST 24h steps that can stall iteration. */
+export const incrementYmd = (
+  y: number,
+  m: number,
+  d: number,
+): [number, number, number] => {
+  const next = new Date(Date.UTC(y, m - 1, d + 1));
+  return [next.getUTCFullYear(), next.getUTCMonth() + 1, next.getUTCDate()];
+};
+
+/**
+ * Formats a date as the calendar day in the given timezone.
+ * `en-CA` yields ISO-8601 `YYYY-MM-DD`, which is lexicographically sortable
+ * (string compare == chronological compare) and matches MongoDB's `%Y-%m-%d`.
+ */
+export const formatYmdInTz = (date: Date, timezone: string): string =>
+  new Intl.DateTimeFormat("en-CA", { timeZone: timezone }).format(date);
+
+/**
+ * Returns the calendar day in the given timezone as numeric parts.
+ * Reads parts by `type` (not string order), so `en-US` is fine here.
+ */
+export const getYmdInTz = (date: Date, timezone: string) => {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+    })
+      .formatToParts(date)
+      .map((p) => [p.type, Number(p.value)]),
+  );
+  return { y: parts.year, m: parts.month, d: parts.day };
+};
+
+/** Weekday index (Sun = 0) of a date in the given timezone. */
+export const getWeekdayInTz = (date: Date, timezone: string): number =>
+  WEEKDAY[
+    new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "short" }).format(
+      date,
+    )
+  ] ?? 0;
+
+/**
+ * Returns the given `YYYY-MM-DD` day at noon UTC — a stable anchor inside the
+ * calendar day, far from midnight so timezone/DST shifts can't cross a date boundary.
+ */
+export const dateAtNoonUtc = (dateStr: string): Date => {
+  const [y, m, d] = parseYmd(dateStr);
+  return new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
+};
+
+/**
+ * UTC instant at the start of the given `YYYY-MM-DD` calendar day in `timezone`.
+ * Binary-searches the boundary so it stays correct across DST transitions.
+ */
+export const startOfCalendarDayInTz = (dateStr: string, timezone: string): Date => {
+  const anchor = dateAtNoonUtc(dateStr).getTime();
+  let low = anchor - 2 * DAY_MS;
+  let high = anchor + DAY_MS;
+
+  while (high - low > 1 /* ms */) {
+    const mid = Math.floor((low + high) / 2);
+    if (formatYmdInTz(new Date(mid), timezone) >= dateStr) high = mid;
+    else low = mid;
+  }
+
+  return new Date(high);
+};
+
+/** UTC instant at the last millisecond of the given calendar day in `timezone`. */
+export const endOfCalendarDayInTz = (dateStr: string, timezone: string): Date => {
+  const [y, m, d] = parseYmd(dateStr);
+  const nextDay = new Date(Date.UTC(y, m - 1, d + 1)).toISOString().slice(0, 10);
+  return new Date(startOfCalendarDayInTz(nextDay, timezone).getTime() - 1);
+};