@talkpilot/core-db 1.3.1 → 1.3.4

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

@@ -0,0 +1,587 @@
+import { getCallsCollection } from "./calls.getters";
+import {
+  HOURS_PER_DAY,
+  STATS_MAX_TIME_MS,
+  TREND_MONTH_BUCKET_MIN_MONTHS,
+  TREND_WEEK_BUCKET_MIN_MONTHS,
+} from "./calls.constants";
+import {
+  addDaysToDateStr,
+  DAY_MS,
+  dateAtNoonUtc,
+  formatYmdInTz,
+  getWeekdayInTz,
+  getYmdInTz,
+  incrementYmd,
+  parseYmd,
+  toUtcDate,
+  ymdToStr,
+} from "../../utils/date.utils";
+import {
+  findTicketSubjectRows,
+  ticketStatsDateScopeFromYmd,
+} from "../../municipal/tickets/tickets.statistics.getters";
+import type { CityName } from "../../municipal/utils/types";
+import type {
+  SubjectItem,
+  TicketStatsDateScope,
+} from "../../municipal/tickets/tickets.types";
+import type {
+  CallRoutingFilter,
+  CallsHourlyBucket,
+  CallsRoutingAggregation,
+  CallsStatsFilter,
+  CallsSummaryAggregation,
+  CallsTrendBucket,
+  ResolvedTimeBucket,
+} from "./calls.statistics.types";
+
+const emptySummary = (): CallsSummaryAggregation => ({
+  totalCalls: 0,
+  avgDurationSeconds: 0,
+  openTickets: 0,
+  draftTickets: 0,
+});
+
+const emptyRouting = (): CallsRoutingAggregation => ({
+  aiHandled: 0,
+  transferred: 0,
+  hijacked: 0,
+});
+
+const isTransferred = { $eq: ["$redirectedCall", true] };
+
+const isHijacked = {
+  $and: [
+    { $eq: ["$isConferenceCall", true] },
+    { $ne: ["$redirectedCall", true] },
+  ],
+};
+
+const countIf = (condition: Record<string, unknown>) => ({
+  $sum: { $cond: [condition, 1, 0] },
+});
+
+const needsTicketStatusFilter = (filters?: CallsStatsFilter["ticketStatusFilters"]) => {
+  if (!filters?.length) return false;
+  const hasOpened = filters.includes("opened");
+  const hasNotOpened = filters.includes("not_opened");
+  return hasOpened !== hasNotOpened;
+};
+
+const routingMatch = (routing?: CallRoutingFilter[]) => {
+  if (!routing?.length) return null;
+
+  const clauses: Record<string, unknown>[] = [];
+  if (routing.includes("transferred")) clauses.push({ redirectedCall: true });
+  if (routing.includes("hijacked")) {
+    clauses.push({ isConferenceCall: true, redirectedCall: { $ne: true } });
+  }
+  if (routing.includes("ai_only")) {
+    clauses.push({
+      redirectedCall: { $ne: true },
+      $or: [
+        { isConferenceCall: { $ne: true } },
+        { isConferenceCall: { $exists: false } },
+      ],
+    });
+  }
+
+  return clauses.length ? { $or: clauses } : null;
+};
+
+const ticketStatusMatch = (filter: CallsStatsFilter) => {
+  if (!needsTicketStatusFilter(filter.ticketStatusFilters)) return null;
+
+  const sids = filter.callSidsWithTickets ?? [];
+  const openedOnly = filter.ticketStatusFilters?.includes("opened");
+  return { callSid: openedOnly ? { $in: sids } : { $nin: sids } };
+};
+
+// "HH:mm" → minute-of-day (0-1439), for the per-call time-of-day filter.
+const parseMinuteOfDay = (time?: string): number | undefined =>
+  time == null ? undefined : Number(time.slice(0, 2)) * 60 + Number(time.slice(3, 5));
+
+const hourMatch = (filter: CallsStatsFilter): Record<string, unknown> | null => {
+  const from = parseMinuteOfDay(filter.hourFrom);
+  const to = parseMinuteOfDay(filter.hourTo);
+  if (from == null && to == null) return null;
+
+  // hourTo is exclusive: a call counts when minuteOfDay is in [from, to).
+  // from > to → the range wraps past midnight: minuteOfDay >= from OR < to
+  if (from != null && to != null && from > to) {
+    return { $or: [{ minuteOfDay: { $gte: from } }, { minuteOfDay: { $lt: to } }] };
+  }
+
+  const minuteOfDay: Record<string, unknown> = {};
+  if (from != null) minuteOfDay.$gte = from;
+  if (to != null) minuteOfDay.$lt = to;
+  return { minuteOfDay };
+};
+
+const createdAtMatchForFilter = (
+  filter: CallsStatsFilter,
+): { createdAt: { $gte: Date; $lte: Date } } => {
+  const bounds = ticketStatsDateScopeFromYmd(
+    filter.startStr,
+    filter.endStr,
+    filter.timezone,
+  );
+  return { createdAt: { $gte: bounds.from!, $lte: bounds.to! } };
+};
+
+const buildCallsMatchStages = (filter: CallsStatsFilter): Record<string, unknown>[] => {
+  const hourRange = hourMatch(filter);
+  const routing = routingMatch(filter.callRouting);
+  const ticketMatch = ticketStatusMatch(filter);
+
+  return [
+    {
+      $match: {
+        clientId: filter.clientId,
+        isIncomingCall: true,
+        ...createdAtMatchForFilter(filter),
+      },
+    },
+    {
+      $addFields: {
+        dateLocal: {
+          $dateToString: {
+            format: "%Y-%m-%d",
+            date: "$createdAt",
+            timezone: filter.timezone,
+          },
+        },
+        hour: { $hour: { date: "$createdAt", timezone: filter.timezone } },
+        minuteOfDay: {
+          $add: [
+            { $multiply: [{ $hour: { date: "$createdAt", timezone: filter.timezone } }, 60] },
+            { $minute: { date: "$createdAt", timezone: filter.timezone } },
+          ],
+        },
+      },
+    },
+    { $match: { dateLocal: { $gte: filter.startStr, $lte: filter.endStr } } },
+    ...(hourRange ? [{ $match: hourRange }] : []),
+    ...(routing ? [{ $match: routing }] : []),
+    ...(ticketMatch ? [{ $match: ticketMatch }] : []),
+  ];
+};
+
+const aggregateCalls = (
+  filter: CallsStatsFilter,
+  ...tail: Record<string, unknown>[]
+) =>
+  getCallsCollection().aggregate([...buildCallsMatchStages(filter), ...tail], {
+    maxTimeMS: STATS_MAX_TIME_MS,
+  });
+
+const trendBucketExpr = (bucket: ResolvedTimeBucket, timezone: string) =>
+  bucket === "day"
+    ? { bucket: "$dateLocal" }
+    : {
+        bucket: {
+          $dateToString: {
+            format: "%Y-%m-%d",
+            date: { $dateTrunc: { date: "$createdAt", unit: bucket, timezone } },
+            timezone,
+          },
+        },
+      };
+
+const mapTrendRow = (row: {
+  _id: unknown;
+  totalCalls: number;
+  openTickets: number;
+}): CallsTrendBucket => ({
+  bucket: String(row._id),
+  totalCalls: row.totalCalls,
+  openTickets: row.openTickets,
+});
+
+export const rangeDurationDays = (startStr: string, endStr: string): number => {
+  const start = toUtcDate(startStr).getTime();
+  const end = toUtcDate(endStr).getTime();
+  return Math.floor((end - start) / DAY_MS) + 1;
+};
+
+/**
+ * Number of distinct calendar months the [startStr, endStr] range spans, inclusive.
+ * Counts month boundaries rather than 30-day periods: e.g. Jan 31 -> Feb 1 returns 2.
+ */
+export const rangeDurationMonths = (startStr: string, endStr: string): number => {
+  const [sy, sm] = parseYmd(startStr);
+  const [ey, em] = parseYmd(endStr);
+  return (ey - sy) * 12 + (em - sm) + 1;
+};
+
+/**
+ * Chooses how the client calls-over-time bar chart groups each column:
+ * one bar per day, week, or calendar month. Short ranges stay daily; longer
+ * ones switch to weekly or monthly so the chart does not show hundreds of bars.
+ */
+export const resolveTimeBucketFromRange = (
+  startStr: string,
+  endStr: string,
+): ResolvedTimeBucket => {
+  const months = rangeDurationMonths(startStr, endStr);
+  if (months > TREND_MONTH_BUCKET_MIN_MONTHS) return "month";
+  if (months > TREND_WEEK_BUCKET_MIN_MONTHS) return "week";
+  return "day";
+};
+
+const weekBucketKeyForDate = (dateStr: string, timezone: string): string => {
+  const anchor = dateAtNoonUtc(dateStr);
+  const weekStart = new Date(anchor.getTime() - getWeekdayInTz(anchor, timezone) * DAY_MS);
+  return formatYmdInTz(weekStart, timezone);
+};
+
+const formatWeekBucketRange = (
+  weekStartStr: string,
+  clipStartStr: string,
+  clipEndStr: string,
+): string => {
+  const weekEndStr = addDaysToDateStr(weekStartStr, 6);
+  const start = weekStartStr < clipStartStr ? clipStartStr : weekStartStr;
+  const end = weekEndStr > clipEndStr ? clipEndStr : weekEndStr;
+  return `${start}/${end}`;
+};
+
+const monthBucketKey = (y: number, m: number): string =>
+  `${y}-${String(m).padStart(2, "0")}-01`;
+
+const emptyTrendBucket = (bucket: string): CallsTrendBucket => ({
+  bucket,
+  totalCalls: 0,
+  openTickets: 0,
+});
+
+const indexTrendRowsByBucket = (rows: CallsTrendBucket[]) =>
+  new Map(rows.map((row) => [row.bucket, row]));
+
+const fillDailyTrendBuckets = (
+  rows: CallsTrendBucket[],
+  startStr: string,
+  endStr: string,
+): CallsTrendBucket[] => {
+  const byBucket = indexTrendRowsByBucket(rows);
+  const filled: CallsTrendBucket[] = [];
+
+  for (let cursor = startStr; cursor <= endStr; cursor = ymdToStr(...incrementYmd(...parseYmd(cursor)))) {
+    filled.push(byBucket.get(cursor) ?? emptyTrendBucket(cursor));
+  }
+
+  return filled;
+};
+
+const fillMonthlyTrendBuckets = (
+  rows: CallsTrendBucket[],
+  startStr: string,
+  endStr: string,
+  timezone: string,
+): CallsTrendBucket[] => {
+  const byBucket = indexTrendRowsByBucket(rows);
+  const startParts = getYmdInTz(dateAtNoonUtc(startStr), timezone);
+  const endParts = getYmdInTz(dateAtNoonUtc(endStr), timezone);
+
+  const filled: CallsTrendBucket[] = [];
+  let { y, m } = startParts;
+
+  while (y < endParts.y || (y === endParts.y && m <= endParts.m)) {
+    const bucket = monthBucketKey(y, m);
+    filled.push(byBucket.get(bucket) ?? emptyTrendBucket(bucket));
+    m += 1;
+    if (m > 12) {
+      m = 1;
+      y += 1;
+    }
+  }
+
+  return filled;
+};
+
+const fillWeeklyTrendBuckets = (
+  rows: CallsTrendBucket[],
+  startStr: string,
+  endStr: string,
+  timezone: string,
+): CallsTrendBucket[] => {
+  const byBucket = indexTrendRowsByBucket(rows);
+  const filled: CallsTrendBucket[] = [];
+  const seen = new Set<string>();
+
+  for (let i = 0, days = rangeDurationDays(startStr, endStr); i < days; i += 1) {
+    const bucket = formatWeekBucketRange(
+      weekBucketKeyForDate(addDaysToDateStr(startStr, i), timezone),
+      startStr,
+      endStr,
+    );
+    if (seen.has(bucket)) continue;
+    seen.add(bucket);
+    filled.push(byBucket.get(bucket) ?? emptyTrendBucket(bucket));
+  }
+
+  return filled;
+};
+
+const fillTrendBuckets = (
+  rows: CallsTrendBucket[],
+  bucket: ResolvedTimeBucket,
+  startStr: string,
+  endStr: string,
+  timezone: string,
+): CallsTrendBucket[] => {
+  switch (bucket) {
+    case "day":
+      return fillDailyTrendBuckets(rows, startStr, endStr);
+    case "week":
+      return fillWeeklyTrendBuckets(rows, startStr, endStr, timezone);
+    case "month":
+      return fillMonthlyTrendBuckets(rows, startStr, endStr, timezone);
+    default: {
+      return fillDailyTrendBuckets(rows, startStr, endStr);
+    }
+  }
+};
+
+const resolveHourRange = (filter: CallsStatsFilter): { hourFrom: number; hourTo: number } => {
+  const from = parseMinuteOfDay(filter.hourFrom);
+  const to = parseMinuteOfDay(filter.hourTo);
+  if (from == null && to == null) return { hourFrom: 0, hourTo: HOURS_PER_DAY - 1 };
+  return {
+    hourFrom: from == null ? 0 : Math.floor(from / 60),
+    // hourTo is exclusive: last populated bucket is the hour holding minute (to - 1).
+    hourTo: to == null ? HOURS_PER_DAY - 1 : Math.floor((to - 1) / 60),
+  };
+};
+
+const roundOneDecimal = (value: number): number => Math.round(value * 10) / 10;
+
+const toHourlyDistribution = (
+  rows: { _id: unknown; totalCalls: number }[],
+  hourRange: { hourFrom: number; hourTo: number },
+  daysInRange: number,
+): CallsHourlyBucket[] => {
+  const counts = new Map(rows.map((r) => [Number(r._id), r.totalCalls]));
+  const { hourFrom, hourTo } = hourRange;
+  const buckets: CallsHourlyBucket[] = [];
+
+  const pushHour = (hour: number) => {
+    const totalCalls = counts.get(hour) ?? 0;
+    buckets.push({
+      hour,
+      totalCalls,
+      avgCalls: roundOneDecimal(daysInRange > 0 ? totalCalls / daysInRange : 0),
+    });
+  };
+
+  if (hourFrom <= hourTo) {
+    for (let hour = hourFrom; hour <= hourTo; hour += 1) pushHour(hour);
+  } else {
+    // Wraps past midnight: hourFrom..23, then 0..hourTo.
+    for (let hour = hourFrom; hour < HOURS_PER_DAY; hour += 1) pushHour(hour);
+    for (let hour = 0; hour <= hourTo; hour += 1) pushHour(hour);
+  }
+
+  return buckets;
+};
+
+export const aggregateCallsSummary = async (
+  filter: CallsStatsFilter,
+): Promise<CallsSummaryAggregation> => {
+  const hasTickets = Boolean(filter.callSidsWithTickets?.length || filter.callSidsWithDraftTickets?.length);
+  const hasStatusFilter = needsTicketStatusFilter(filter.ticketStatusFilters);
+
+  if (!hasTickets && !hasStatusFilter) {
+    const result = await aggregateCalls(filter, {
+      $group: { _id: null, totalCalls: { $sum: 1 }, avgDurationSeconds: { $avg: "$callLength" } },
+    }).next();
+    if (!result) return emptySummary();
+    return {
+      totalCalls: result.totalCalls,
+      avgDurationSeconds: roundOneDecimal(result.avgDurationSeconds ?? 0),
+      openTickets: 0,
+      draftTickets: 0,
+    };
+  }
+
+  // Single pass: project per-call data, handle ticket status filter and counting in JS.
+  // Avoids embedding callSidsWithTickets inside any MongoDB pipeline stage.
+  const rows = await aggregateCalls(
+    { ...filter, ticketStatusFilters: undefined },
+    { $project: { _id: 0, callSid: 1, callLength: 1 } },
+  ).toArray();
+
+  const ticketSet = new Set(filter.callSidsWithTickets ?? []);
+  const draftSet = new Set(filter.callSidsWithDraftTickets ?? []);
+  const openedOnly = hasStatusFilter && filter.ticketStatusFilters!.includes("opened");
+  const notOpenedOnly = hasStatusFilter && filter.ticketStatusFilters!.includes("not_opened");
+
+  let totalCalls = 0;
+  let totalDuration = 0;
+  let openTickets = 0;
+  let draftTickets = 0;
+
+  for (const row of rows) {
+    const sid = row.callSid as string;
+    const hasTicket = ticketSet.has(sid);
+    if (openedOnly && !hasTicket) continue;
+    if (notOpenedOnly && hasTicket) continue;
+    totalCalls += 1;
+    totalDuration += (row.callLength as number | undefined) ?? 0;
+    if (hasTicket) openTickets += 1;
+    if (draftSet.has(sid)) draftTickets += 1;
+  }
+
+  if (!totalCalls) return emptySummary();
+
+  return {
+    totalCalls,
+    avgDurationSeconds: roundOneDecimal(totalDuration / totalCalls),
+    openTickets,
+    draftTickets,
+  };
+};
+
+export const aggregateCallsTrend = async (
+  filter: CallsStatsFilter,
+  bucket: ResolvedTimeBucket,
+): Promise<CallsTrendBucket[]> => {
+  const ticketSet = filter.callSidsWithTickets?.length
+    ? new Set(filter.callSidsWithTickets)
+    : null;
+
+  if (ticketSet) {
+    const rows = await aggregateCalls(
+      { ...filter, ticketStatusFilters: undefined },
+      { $addFields: trendBucketExpr(bucket, filter.timezone) },
+      { $project: { _id: 0, bucket: 1, callSid: 1 } },
+    ).toArray();
+
+    const openedOnly = needsTicketStatusFilter(filter.ticketStatusFilters) && filter.ticketStatusFilters!.includes("opened");
+    const notOpenedOnly = needsTicketStatusFilter(filter.ticketStatusFilters) && filter.ticketStatusFilters!.includes("not_opened");
+
+    const byBucket = new Map<string, { totalCalls: number; openTickets: number }>();
+    for (const row of rows) {
+      const sid = row.callSid as string;
+      const hasTicket = ticketSet.has(sid);
+      if (openedOnly && !hasTicket) continue;
+      if (notOpenedOnly && hasTicket) continue;
+      const label =
+        bucket === "week"
+          ? formatWeekBucketRange(String(row.bucket), filter.startStr, filter.endStr)
+          : String(row.bucket);
+      const cur = byBucket.get(label) ?? { totalCalls: 0, openTickets: 0 };
+      cur.totalCalls += 1;
+      if (hasTicket) cur.openTickets += 1;
+      byBucket.set(label, cur);
+    }
+
+    const mappedRows = [...byBucket.entries()]
+      .map(([label, counts]) => ({ bucket: label, ...counts }));
+
+    return fillTrendBuckets(mappedRows, bucket, filter.startStr, filter.endStr, filter.timezone);
+  }
+
+  const rows = await aggregateCalls(
+    filter,
+    { $addFields: trendBucketExpr(bucket, filter.timezone) },
+    { $group: { _id: "$bucket", totalCalls: { $sum: 1 } } },
+    { $sort: { _id: 1 } },
+  ).toArray();
+
+  const mappedRows =
+    bucket === "week"
+      ? rows.map((row) => ({
+          bucket: formatWeekBucketRange(String(row._id), filter.startStr, filter.endStr),
+          totalCalls: row.totalCalls as number,
+          openTickets: 0,
+        }))
+      : rows.map((row) =>
+          mapTrendRow({ _id: row._id, totalCalls: row.totalCalls as number, openTickets: 0 }),
+        );
+
+  return fillTrendBuckets(mappedRows, bucket, filter.startStr, filter.endStr, filter.timezone);
+};
+
+export const aggregateCallsHourlyByRange = async (
+  filter: CallsStatsFilter,
+): Promise<CallsHourlyBucket[]> => {
+  const rows = await aggregateCalls(
+    filter,
+    { $group: { _id: "$hour", totalCalls: { $sum: 1 } } },
+    { $sort: { _id: 1 } },
+  ).toArray();
+
+  return toHourlyDistribution(
+    rows.map((r) => ({ _id: r._id, totalCalls: r.totalCalls as number })),
+    resolveHourRange(filter),
+    rangeDurationDays(filter.startStr, filter.endStr),
+  );
+};
+
+export const aggregateCallsRouting = async (
+  filter: CallsStatsFilter,
+): Promise<CallsRoutingAggregation> => {
+  const result = await aggregateCalls(
+    filter,
+    {
+      $group: {
+        _id: null,
+        transferred: countIf(isTransferred),
+        hijacked: countIf(isHijacked),
+        totalCalls: { $sum: 1 },
+      },
+    },
+    {
+      $addFields: {
+        aiHandled: {
+          $subtract: ["$totalCalls", { $add: ["$transferred", "$hijacked"] }],
+        },
+      },
+    },
+  ).next();
+
+  if (!result) return emptyRouting();
+
+  return {
+    aiHandled: result.aiHandled,
+    transferred: result.transferred,
+    hijacked: result.hijacked,
+  };
+};
+
+export const findFilteredCallSids = async (filter: CallsStatsFilter): Promise<string[]> => {
+  const rows = await aggregateCalls(
+    filter,
+    { $group: { _id: "$callSid" } },
+  ).toArray();
+  return rows.map((r) => String(r._id)).filter(Boolean);
+};
+
+/**
+ * "Subjects" panel: ticket count per subject, for calls passing the filters.
+ * Calls and tickets are in separate DBs, so we join in code — filtered call IDs
+ * from calls, subjects from tickets. Returns the full list sorted most-common
+ * first; callers slice if they want a top-N.
+ */
+export const findSubjectsByCityAndDateRange = async (
+  cityName: CityName,
+  filter: CallsStatsFilter,
+  dateScope: TicketStatsDateScope,
+): Promise<SubjectItem[]> => {
+  const filteredCallSids = new Set(await findFilteredCallSids(filter));
+  if (!filteredCallSids.size) return [];
+
+  const rows = await findTicketSubjectRows(cityName, dateScope);
+
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    if (!filteredCallSids.has(row.callSid)) continue;
+    counts.set(row.subject, (counts.get(row.subject) ?? 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .map(([subject, count]) => ({ subject, count }))
+    .sort((a, b) => b.count - a.count || a.subject.localeCompare(b.subject));
+};

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

@@ -0,0 +1,44 @@
+export type ResolvedTimeBucket = "day" | "week" | "month";
+
+export type TicketStatusFilter = "opened" | "not_opened";
+export type CallRoutingFilter = "ai_only" | "transferred" | "hijacked";
+
+export type CallsStatsFilter = {
+  clientId: string;
+  startStr: string;
+  endStr: string;
+  timezone: string;
+  hourFrom?: string; // HH:mm
+  hourTo?: string; // HH:mm
+  callRouting?: CallRoutingFilter[];
+  callSidsWithTickets?: string[];
+  /** Call SIDs whose municipal ticket matches the draft-ticket definition (see tickets statistics getters). */
+  callSidsWithDraftTickets?: string[];
+  ticketStatusFilters?: TicketStatusFilter[];
+};
+
+export type CallsSummaryAggregation = {
+  totalCalls: number;
+  avgDurationSeconds: number;
+  openTickets: number;
+  draftTickets: number;
+};
+
+export type CallsTrendBucket = {
+  /** Day: YYYY-MM-DD; week: YYYY-MM-DD/YYYY-MM-DD (inclusive, clipped to filter); month: YYYY-MM-01 */
+  bucket: string;
+  totalCalls: number;
+  openTickets: number;
+};
+
+export type CallsHourlyBucket = {
+  hour: number;
+  totalCalls: number;
+  avgCalls: number;
+};
+
+export type CallsRoutingAggregation = {
+  aiHandled: number;
+  transferred: number;
+  hijacked: number;
+};

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

@@ -2,8 +2,10 @@ import { ObjectId, Sort, WithId } from "mongodb";
 import { TranscriptionSegment } from "../results";
 import { LeadProperty } from "../leads";
 
-export const CONFERENCE_ROLE_CUSTOMER = "customer" as const;
-export const CONFERENCE_ROLE_SUPERVISOR = "supervisor" as const;
+import {
+  CONFERENCE_ROLE_CUSTOMER,
+  CONFERENCE_ROLE_SUPERVISOR,
+} from "./calls.constants";
 
 export type ConferenceRole =
   | typeof CONFERENCE_ROLE_CUSTOMER