@talkpilot/core-db 1.3.1 → 1.3.4

package/dist/utils/date.utils.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Shared timezone-aware date helpers for statistics aggregations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.endOfCalendarDayInTz = exports.startOfCalendarDayInTz = exports.dateAtNoonUtc = exports.getWeekdayInTz = exports.getYmdInTz = exports.formatYmdInTz = exports.incrementYmd = exports.addDaysToDateStr = exports.formatDate = exports.toUtcDate = exports.ymdToStr = exports.parseYmd = exports.WEEKDAY = exports.DAY_MS = void 0;
+/** Milliseconds in a single day. */
+exports.DAY_MS = 24 * 60 * 60 * 1000;
+/** Maps a short weekday name (as produced by Intl) to its index (Sun = 0). */
+exports.WEEKDAY = {
+    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. */
+const parseYmd = (dateStr) => {
+    const [y, m, d] = dateStr.split("-").map(Number);
+    return [y, m, d];
+};
+exports.parseYmd = parseYmd;
+/** Builds a zero-padded `YYYY-MM-DD` string from numeric parts. */
+const ymdToStr = (y, m, d) => `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+exports.ymdToStr = ymdToStr;
+/** Parses a `YYYY-MM-DD` string as midnight UTC. */
+const toUtcDate = (dateStr) => new Date(`${dateStr}T00:00:00.000Z`);
+exports.toUtcDate = toUtcDate;
+/** Formats a date as a `YYYY-MM-DD` string in UTC. */
+const formatDate = (date) => date.toISOString().slice(0, 10);
+exports.formatDate = formatDate;
+/** Adds `days` to a `YYYY-MM-DD` string, returning the resulting `YYYY-MM-DD`. */
+const addDaysToDateStr = (dateStr, days) => (0, exports.formatDate)(new Date((0, exports.toUtcDate)(dateStr).getTime() + days * exports.DAY_MS));
+exports.addDaysToDateStr = addDaysToDateStr;
+/** Next civil calendar day (proleptic Gregorian). Avoids DST 24h steps that can stall iteration. */
+const incrementYmd = (y, m, d) => {
+    const next = new Date(Date.UTC(y, m - 1, d + 1));
+    return [next.getUTCFullYear(), next.getUTCMonth() + 1, next.getUTCDate()];
+};
+exports.incrementYmd = incrementYmd;
+/**
+ * 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`.
+ */
+const formatYmdInTz = (date, timezone) => new Intl.DateTimeFormat("en-CA", { timeZone: timezone }).format(date);
+exports.formatYmdInTz = formatYmdInTz;
+/**
+ * Returns the calendar day in the given timezone as numeric parts.
+ * Reads parts by `type` (not string order), so `en-US` is fine here.
+ */
+const getYmdInTz = (date, timezone) => {
+    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 };
+};
+exports.getYmdInTz = getYmdInTz;
+/** Weekday index (Sun = 0) of a date in the given timezone. */
+const getWeekdayInTz = (date, timezone) => exports.WEEKDAY[new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "short" }).format(date)] ?? 0;
+exports.getWeekdayInTz = getWeekdayInTz;
+/**
+ * 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.
+ */
+const dateAtNoonUtc = (dateStr) => {
+    const [y, m, d] = (0, exports.parseYmd)(dateStr);
+    return new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
+};
+exports.dateAtNoonUtc = dateAtNoonUtc;
+/**
+ * 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.
+ */
+const startOfCalendarDayInTz = (dateStr, timezone) => {
+    const anchor = (0, exports.dateAtNoonUtc)(dateStr).getTime();
+    let low = anchor - 2 * exports.DAY_MS;
+    let high = anchor + exports.DAY_MS;
+    while (high - low > 1 /* ms */) {
+        const mid = Math.floor((low + high) / 2);
+        if ((0, exports.formatYmdInTz)(new Date(mid), timezone) >= dateStr)
+            high = mid;
+        else
+            low = mid;
+    }
+    return new Date(high);
+};
+exports.startOfCalendarDayInTz = startOfCalendarDayInTz;
+/** UTC instant at the last millisecond of the given calendar day in `timezone`. */
+const endOfCalendarDayInTz = (dateStr, timezone) => {
+    const [y, m, d] = (0, exports.parseYmd)(dateStr);
+    const nextDay = new Date(Date.UTC(y, m - 1, d + 1)).toISOString().slice(0, 10);
+    return new Date((0, exports.startOfCalendarDayInTz)(nextDay, timezone).getTime() - 1);
+};
+exports.endOfCalendarDayInTz = endOfCalendarDayInTz;
+//# sourceMappingURL=date.utils.js.map

package/dist/utils/date.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.utils.js","sourceRoot":"","sources":["../../src/utils/date.utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/statistics.aggregation.d.ts

@@ -0,0 +1,20 @@
+/** Default server-side cap for statistics aggregations (30s). */
+export declare const DEFAULT_STATS_MAX_TIME_MS = 30000;
+/** Log a warning when SID arrays exceed this size (BSON / pipeline pressure). */
+export declare const MAX_RECOMMENDED_SID_ARRAY_SIZE = 10000;
+export type StatisticsAggregationOptions = {
+    maxTimeMS?: number;
+};
+export declare class StatisticsTimeoutError extends Error {
+    constructor(maxTimeMS: number);
+}
+export declare const resolveMaxTimeMS: (options?: StatisticsAggregationOptions) => number;
+/** Builds a constant lookup object for O(1) membership checks via $getField. */
+export declare const buildCallSidLookup: (callSids: string[]) => Record<string, true>;
+/**
+ * $expr that is true when `$callSid` is in `callSids`.
+ * Prefer over `$in` for large arrays embedded in aggregation pipelines.
+ */
+export declare const callSidInSetExpr: (callSids: string[]) => Record<string, unknown>;
+export declare const warnIfLargeSidArray: (label: string, callSids: string[]) => void;
+//# sourceMappingURL=statistics.aggregation.d.ts.map

package/dist/utils/statistics.aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.aggregation.d.ts","sourceRoot":"","sources":["../../src/utils/statistics.aggregation.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAErD,MAAM,MAAM,4BAA4B,GAAG;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,SAAS,EAAE,MAAM;CAI9B;AAED,eAAO,MAAM,gBAAgB,GAAI,UAAU,4BAA4B,KAAG,MACzB,CAAC;AAElD,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CACK,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,MAAM,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAW1E,CAAC;AAEH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,KAAG,IAMvE,CAAC"}

package/dist/utils/statistics.aggregation.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnIfLargeSidArray = exports.callSidInSetExpr = exports.buildCallSidLookup = exports.resolveMaxTimeMS = exports.StatisticsTimeoutError = exports.MAX_RECOMMENDED_SID_ARRAY_SIZE = exports.DEFAULT_STATS_MAX_TIME_MS = void 0;
+/** Default server-side cap for statistics aggregations (30s). */
+exports.DEFAULT_STATS_MAX_TIME_MS = 30_000;
+/** Log a warning when SID arrays exceed this size (BSON / pipeline pressure). */
+exports.MAX_RECOMMENDED_SID_ARRAY_SIZE = 10_000;
+class StatisticsTimeoutError extends Error {
+    constructor(maxTimeMS) {
+        super(`Statistics aggregation exceeded maxTimeMS (${maxTimeMS})`);
+        this.name = "StatisticsTimeoutError";
+    }
+}
+exports.StatisticsTimeoutError = StatisticsTimeoutError;
+const resolveMaxTimeMS = (options) => options?.maxTimeMS ?? exports.DEFAULT_STATS_MAX_TIME_MS;
+exports.resolveMaxTimeMS = resolveMaxTimeMS;
+/** Builds a constant lookup object for O(1) membership checks via $getField. */
+const buildCallSidLookup = (callSids) => Object.fromEntries(callSids.map((sid) => [sid, true]));
+exports.buildCallSidLookup = buildCallSidLookup;
+/**
+ * $expr that is true when `$callSid` is in `callSids`.
+ * Prefer over `$in` for large arrays embedded in aggregation pipelines.
+ */
+const callSidInSetExpr = (callSids) => ({
+    $eq: [
+        {
+            $getField: {
+                field: "$callSid",
+                input: (0, exports.buildCallSidLookup)(callSids),
+                default: false,
+            },
+        },
+        true,
+    ],
+});
+exports.callSidInSetExpr = callSidInSetExpr;
+const warnIfLargeSidArray = (label, callSids) => {
+    if (callSids.length > exports.MAX_RECOMMENDED_SID_ARRAY_SIZE) {
+        console.warn(`[core-db statistics] ${label}: ${callSids.length} call SIDs exceeds recommended max (${exports.MAX_RECOMMENDED_SID_ARRAY_SIZE}). Narrow the date range or cache SIDs once per request.`);
+    }
+};
+exports.warnIfLargeSidArray = warnIfLargeSidArray;
+//# sourceMappingURL=statistics.aggregation.js.map

package/dist/utils/statistics.aggregation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.aggregation.js","sourceRoot":"","sources":["../../src/utils/statistics.aggregation.ts"],"names":[],"mappings":";;;AAAA,iEAAiE;AACpD,QAAA,yBAAyB,GAAG,MAAM,CAAC;AAEhD,iFAAiF;AACpE,QAAA,8BAA8B,GAAG,MAAM,CAAC;AAMrD,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,SAAiB;QAC3B,KAAK,CAAC,8CAA8C,SAAS,GAAG,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAEM,MAAM,gBAAgB,GAAG,CAAC,OAAsC,EAAU,EAAE,CACjF,OAAO,EAAE,SAAS,IAAI,iCAAyB,CAAC;AADrC,QAAA,gBAAgB,oBACqB;AAElD,gFAAgF;AACzE,MAAM,kBAAkB,GAAG,CAAC,QAAkB,EAAwB,EAAE,CAC7E,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAyB,CAAC;AADpE,QAAA,kBAAkB,sBACkD;AAEjF;;;GAGG;AACI,MAAM,gBAAgB,GAAG,CAAC,QAAkB,EAA2B,EAAE,CAAC,CAAC;IAChF,GAAG,EAAE;QACH;YACE,SAAS,EAAE;gBACT,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,IAAA,0BAAkB,EAAC,QAAQ,CAAC;gBACnC,OAAO,EAAE,KAAK;aACf;SACF;QACD,IAAI;KACL;CACF,CAAC,CAAC;AAXU,QAAA,gBAAgB,oBAW1B;AAEI,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAE,QAAkB,EAAQ,EAAE;IAC7E,IAAI,QAAQ,CAAC,MAAM,GAAG,sCAA8B,EAAE,CAAC;QACrD,OAAO,CAAC,IAAI,CACV,wBAAwB,KAAK,KAAK,QAAQ,CAAC,MAAM,uCAAuC,sCAA8B,0DAA0D,CACjL,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AANW,QAAA,mBAAmB,uBAM9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talkpilot/core-db",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "description": "Core database package for centralized connections and ORM integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/municipal/tickets/__tests__/tickets.getters.spec.ts

@@ -1,7 +1,4 @@
-import {
-  findTicketsByCallSid,
-  getTicketsCountByCityAndDateRange,
-} from "../tickets.getters";
+import { findTicketsByCallSid } from "../tickets.getters";
 import { setDb } from "../../index";
 import { Db, Collection } from "mongodb";
 import { createTicket } from "../../../test-utils/factories";
@@ -30,37 +27,4 @@ describe("tickets getters", () => {
     expect(mockCollection.find).toHaveBeenCalledWith({ callSid: "123" });
     expect(result[0].callSid).toBe("123");
   });
-
-  it("getTicketsCountByCityAndDateRange should not count tickets without callSid", async () => {
-    const aggregateNext = jest.fn().mockResolvedValue({ n: 1 });
-    mockCollection = {
-      ...mockCollection,
-      aggregate: jest.fn().mockReturnValue({
-        next: aggregateNext,
-      }),
-    };
-    mockDb = {
-      collection: jest.fn().mockReturnValue(mockCollection),
-    };
-    setDb(mockDb as Db);
-
-    const result = await getTicketsCountByCityAndDateRange(
-      "ashdod",
-      "2026-01-01",
-      "2026-01-31",
-      "Asia/Jerusalem",
-    );
-
-    expect(mockCollection.aggregate).toHaveBeenCalledWith(
-      expect.arrayContaining([
-        {
-          $match: {
-            cityName: "ashdod",
-            callSid: { $exists: true, $nin: [null, ""] },
-          },
-        },
-      ]),
-    );
-    expect(result).toBe(1);
-  });
 });

package/src/municipal/tickets/__tests__/tickets.statistics.spec.ts

@@ -0,0 +1,51 @@
+import {
+  findCallSidsWithDraftTicketsByCity,
+  findCallSidsWithTicketsByCity,
+  getTicketsCollection,
+  ticketStatsDateScopeFromYmd,
+} from "../../../index";
+import { createTicket } from "../../../test-utils/factories";
+
+const CITY = "tests" as const;
+const TZ = "Asia/Jerusalem";
+const mayScope = () => ticketStatsDateScopeFromYmd("2026-05-01", "2026-05-31", TZ);
+
+describe("tickets statistics getters", () => {
+  it("should scope callSid lookups to the provided createdAt range", async () => {
+    await getTicketsCollection().insertMany([
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-in-range",
+        createdAt: new Date("2026-05-15T10:00:00.000Z"),
+        updatedAt: new Date("2026-05-15T10:00:00.000Z"),
+      }),
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-out-of-range",
+        createdAt: new Date("2024-01-01T10:00:00.000Z"),
+        updatedAt: new Date("2024-01-01T10:00:00.000Z"),
+      }),
+    ]);
+    expect(await findCallSidsWithTicketsByCity(CITY, mayScope())).toEqual(["CA-in-range"]);
+  });
+
+  it("should treat whitespace-only event_subject_id as draft", async () => {
+    await getTicketsCollection().insertMany([
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-draft-whitespace",
+        createdAt: new Date("2026-05-15T10:00:00.000Z"),
+        updatedAt: new Date("2026-05-15T10:00:00.000Z"),
+        externalCallFields: { event_subject_id: "  \t  " },
+      }),
+      createTicket({
+        cityName: CITY,
+        callSid: "CA-not-draft",
+        createdAt: new Date("2026-05-16T10:00:00.000Z"),
+        updatedAt: new Date("2026-05-16T10:00:00.000Z"),
+        externalCallFields: { event_subject_id: "100" },
+      }),
+    ]);
+    expect(await findCallSidsWithDraftTicketsByCity(CITY, mayScope())).toEqual(["CA-draft-whitespace"]);
+  });
+});

package/src/municipal/tickets/index.ts

@@ -1,2 +1,3 @@
 export * from "./tickets.getters";
-export type { Ticket, TicketDoc, SubjectStatsItem } from "./tickets.types";
+export * from "./tickets.statistics.getters";
+export type { Ticket, TicketDoc, SubjectItem, TicketStatsDateScope, TicketSubjectRow } from "./tickets.types";

package/src/municipal/tickets/tickets.constants.ts

@@ -0,0 +1,8 @@
+/** Label used when a ticket has no resolvable department/subject. */
+export const UNCLASSIFIED = "ללא מחלקה";
+
+/** Max execution time (ms) for ticket statistics aggregations. */
+export const STATS_MAX_TIME_MS = 30_000;
+
+/** Default look-back window (days) for ticket statistics date ranges. */
+export const DEFAULT_LOOKBACK_DAYS = 30;

package/src/municipal/tickets/tickets.getters.ts

@@ -1,5 +1,4 @@
 import { CityName, getDb, ObjectId, Ticket } from "../index";
-import type { SubjectStatsItem } from "./tickets.types";
 import { Collection, Filter, ObjectId as MongoObjectId } from "mongodb";
 
 /**
@@ -68,145 +67,6 @@ export const deleteTicket = async (ticketId: string): Promise<boolean> => {
   return result.deletedCount > 0;
 };
 
-/**
- * Count tickets by city and date range (createdAt converted to given timezone).
- * Used as "open" tickets count when status is not available.
- */
-export async function getTicketsCountByCityAndDateRange(
-  cityName: string,
-  startStr: string,
-  endStr: string,
-  timezone: string,
-): Promise<number> {
-  const doc = await getTicketsCollection()
-    .aggregate<{ n: number }>([
-      { $match: { cityName, callSid: { $exists: true, $nin: [null, ""] } } },
-      {
-        $addFields: {
-          dateLocal: {
-            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
-          },
-        },
-      },
-      { $match: { dateLocal: { $gte: startStr, $lte: endStr } } },
-      { $count: "n" },
-    ])
-    .next();
-  return doc?.n ?? 0;
-}
-
-/**
- * Count of tickets by department (subject) from departmentsSubjects. Different departments (subject_id) are grouped, and sub-subjects are unified under their department.
- * Date filter: createdAt in [startStr, endStr] (in the given timezone). Fallback to "Unclassified" when no match is found in the lookup.
- */
-export async function getTicketsSubjectStats(
-  cityName: string,
-  startStr: string,
-  endStr: string,
-  timezone: string,
-): Promise<SubjectStatsItem[]> {
-  const coll = getTicketsCollection();
-  const rows = await coll
-    .aggregate<{ _id: string; subject: string; count: number }>([
-      { $match: { cityName } },
-      {
-        $addFields: {
-          dateLocal: {
-            $dateToString: { format: "%Y-%m-%d", date: "$createdAt", timezone },
-          },
-        },
-      },
-      { $match: { dateLocal: { $gte: startStr, $lte: endStr } } },
-      {
-        $addFields: {
-          effectiveSubjectId: {
-            $ifNull: [
-              "$externalCallFields.event_subject_id",
-              {
-                $ifNull: [
-                  "$externalCallFields.event_sub_subject_id",
-                  "$externalCallFields.event_sub_subject_id2",
-                ],
-              },
-            ],
-          },
-        },
-      },
-      {
-        $lookup: {
-          from: "departmentsSubjects",
-          let: { sid: "$effectiveSubjectId", c: cityName },
-          pipeline: [
-            {
-              $match: {
-                $expr: {
-                  $and: [
-                    { $eq: ["$cityName", "$$c"] },
-                    {
-                      $or: [
-                        { $eq: ["$subject_id", { $ifNull: ["$$sid", ""] }] },
-                        {
-                          $eq: ["$sub_subject_id", { $ifNull: ["$$sid", ""] }],
-                        },
-                        {
-                          $eq: ["$sub_subject_id2", { $ifNull: ["$$sid", ""] }],
-                        },
-                      ],
-                    },
-                  ],
-                },
-              },
-            },
-            { $limit: 1 },
-          ],
-          as: "subj",
-        },
-      },
-      {
-        $addFields: {
-          subject_id: {
-            $cond: {
-              if: { $gt: [{ $size: "$subj" }, 0] },
-              then: {
-                $ifNull: [{ $arrayElemAt: ["$subj.subject_id", 0] }, ""],
-              },
-              else: "",
-            },
-          },
-          subject: {
-            $cond: {
-              if: { $gt: [{ $size: "$subj" }, 0] },
-              then: {
-                $ifNull: [
-                  { $arrayElemAt: ["$subj.subjectName", 0] },
-                  "Unclassified",
-                ],
-              },
-              else: "Unclassified",
-            },
-          },
-        },
-      },
-      {
-        $group: {
-          _id: "$subject_id",
-          subject: { $first: "$subject" },
-          count: { $sum: 1 },
-        },
-      },
-      { $sort: { count: -1 } },
-    ])
-    .toArray();
-
-  const total = rows.reduce((s: number, r: any) => s + r.count, 0);
-  return rows.map((r: any) => ({
-    subject_name: r.subject,
-    subject_id: r._id,
-    count: r.count,
-    percentage: total > 0 ? Math.round((r.count / total) * 100) : 0,
-  }));
-}
-
 export const findTicketByQuery = async (query: Partial<Ticket>) => {
   return await getTicketsCollection().findOne(query);
 };

package/src/municipal/tickets/tickets.statistics.aggregation.ts

@@ -0,0 +1,96 @@
+import { CityName } from "../utils/types";
+import { STATS_MAX_TIME_MS, UNCLASSIFIED } from "./tickets.constants";
+import { getTicketsCollection } from "./tickets.getters";
+import type { TicketStatsDateRange } from "./tickets.types";
+
+const effectiveSubjectIdExpr = {
+  $ifNull: [
+    "$externalCallFields.event_subject_id",
+    {
+      $ifNull: [
+        "$externalCallFields.event_sub_subject_id",
+        "$externalCallFields.event_sub_subject_id2",
+      ],
+    },
+  ],
+};
+
+const departmentsSubjectsLookup = (cityName: CityName) => ({
+  $lookup: {
+    from: "departmentsSubjects",
+    let: { sid: "$effectiveSubjectId", c: cityName },
+    pipeline: [
+      {
+        $match: {
+          $expr: {
+            $and: [
+              { $eq: ["$cityName", "$$c"] },
+              {
+                $or: [
+                  { $eq: ["$subject_id", { $ifNull: ["$$sid", ""] }] },
+                  { $eq: ["$sub_subject_id", { $ifNull: ["$$sid", ""] }] },
+                  { $eq: ["$sub_subject_id2", { $ifNull: ["$$sid", ""] }] },
+                ],
+              },
+            ],
+          },
+        },
+      },
+      { $limit: 1 },
+    ],
+    as: "subj",
+  },
+});
+
+const subjectLabelExpr = {
+  $cond: {
+    if: { $gt: [{ $size: "$subj" }, 0] },
+    then: {
+      $ifNull: [{ $arrayElemAt: ["$subj.subjectName", 0] }, UNCLASSIFIED],
+    },
+    else: UNCLASSIFIED,
+  },
+};
+
+const ticketDateMatch = (dateRange: TicketStatsDateRange) => ({
+  createdAt: { $gte: dateRange.from, $lte: dateRange.to },
+});
+
+export const isDraftSubjectIdExpr = {
+  $or: [
+    { $eq: [{ $type: "$externalCallFields.event_subject_id" }, "missing"] },
+    { $eq: ["$externalCallFields.event_subject_id", null] },
+    {
+      $regexMatch: {
+        input: { $ifNull: ["$externalCallFields.event_subject_id", ""] },
+        regex: /^\s*$/,
+      },
+    },
+  ],
+};
+
+export const ticketsWithCallSidMatch = (
+  cityName: CityName,
+  dateRange: TicketStatsDateRange,
+) => ({
+  cityName,
+  callSid: { $exists: true, $nin: [null, ""] },
+  ...ticketDateMatch(dateRange),
+});
+
+export const subjectResolutionStages = (
+  cityName: CityName,
+): Record<string, unknown>[] => [
+  { $addFields: { effectiveSubjectId: effectiveSubjectIdExpr } },
+  departmentsSubjectsLookup(cityName),
+  { $addFields: { subject: subjectLabelExpr } },
+];
+
+export const runTicketStatsAggregate = async <T>(
+  pipeline: Record<string, unknown>[],
+): Promise<T[]> => {
+  const rows = await getTicketsCollection()
+    .aggregate(pipeline, { maxTimeMS: STATS_MAX_TIME_MS })
+    .toArray();
+  return rows as T[];
+};

package/src/municipal/tickets/tickets.statistics.getters.ts

@@ -0,0 +1,71 @@
+import { CityName } from "../utils/types";
+import {
+  DAY_MS,
+  endOfCalendarDayInTz,
+  startOfCalendarDayInTz,
+} from "../../utils/date.utils";
+import { DEFAULT_LOOKBACK_DAYS } from "./tickets.constants";
+import {
+  isDraftSubjectIdExpr,
+  runTicketStatsAggregate,
+  subjectResolutionStages,
+  ticketsWithCallSidMatch,
+} from "./tickets.statistics.aggregation";
+import type {
+  TicketStatsDateRange,
+  TicketStatsDateScope,
+  TicketSubjectRow,
+} from "./tickets.types";
+
+export const resolveTicketStatsDateRange = (
+  dateScope?: TicketStatsDateScope,
+): TicketStatsDateRange => {
+  const to = dateScope?.to ?? new Date();
+  const from =
+    dateScope?.from ?? new Date(to.getTime() - DEFAULT_LOOKBACK_DAYS * DAY_MS);
+  return { from, to };
+};
+
+export const ticketStatsDateScopeFromYmd = (
+  startStr: string,
+  endStr: string,
+  timezone: string,
+): TicketStatsDateScope => ({
+  from: startOfCalendarDayInTz(startStr, timezone),
+  to: endOfCalendarDayInTz(endStr, timezone),
+});
+
+export const findCallSidsWithTicketsByCity = async (
+  cityName: CityName,
+  dateScope?: TicketStatsDateScope,
+): Promise<string[]> => {
+  const rows = await runTicketStatsAggregate<{ _id: unknown }>([
+    { $match: ticketsWithCallSidMatch(cityName, resolveTicketStatsDateRange(dateScope)) },
+    { $group: { _id: "$callSid" } },
+  ]);
+  return rows.map((r) => String(r._id)).filter(Boolean);
+};
+
+export const findCallSidsWithDraftTicketsByCity = async (
+  cityName: CityName,
+  dateScope?: TicketStatsDateScope,
+): Promise<string[]> => {
+  const rows = await runTicketStatsAggregate<{ _id: unknown }>([
+    { $match: ticketsWithCallSidMatch(cityName, resolveTicketStatsDateRange(dateScope)) },
+    { $match: { $expr: isDraftSubjectIdExpr } },
+    { $group: { _id: "$callSid" } },
+  ]);
+  return rows.map((r) => String(r._id)).filter(Boolean);
+};
+
+export const findTicketSubjectRows = async (
+  cityName: CityName,
+  dateScope?: TicketStatsDateScope,
+): Promise<TicketSubjectRow[]> => {
+  const rows = await runTicketStatsAggregate<{ callSid: unknown; subject: unknown }>([
+    { $match: ticketsWithCallSidMatch(cityName, resolveTicketStatsDateRange(dateScope)) },
+    ...subjectResolutionStages(cityName),
+    { $project: { _id: 0, callSid: 1, subject: 1 } },
+  ]);
+  return rows.map((r) => ({ callSid: String(r.callSid), subject: String(r.subject) }));
+};

package/src/municipal/tickets/tickets.types.ts

@@ -9,7 +9,6 @@ export type Ticket = {
   callSid?: string;
   cityName: CityName;
   externalCallFields: {
-    // Request fields
     first_name?: string;
     last_name?: string;
     event_description?: string;
@@ -18,10 +17,9 @@ export type Ticket = {
     event_subject_id?: string;
     event_sub_subject_id?: string;
     event_sub_subject_id2?: string | null;
-    // Response fields (only if external call was successful)
     call_number?: string;
-    status?: number; // Response status from Bina API (1 = success)
-    error?: string; // Error message from Bina API if any
+    status?: number;
+    error?: string;
     image1?: string;
     image2?: string;
     image3?: string;
@@ -34,10 +32,22 @@ export type Ticket = {
 
 export type TicketDoc = WithId<Ticket>;
 
-/** Call count by department (subject). */
-export type SubjectStatsItem = {
-  subject_name: string;
-  subject_id: string;
+export type SubjectItem = {
+  subject: string;
   count: number;
-  percentage: number;
+};
+
+export type TicketSubjectRow = {
+  callSid: string;
+  subject: string;
+};
+
+export type TicketStatsDateScope = {
+  from?: Date;
+  to?: Date;
+};
+
+export type TicketStatsDateRange = {
+  from: Date;
+  to: Date;
 };