@talkpilot/core-db 1.2.1 → 1.3.0

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

@@ -0,0 +1,243 @@
+import dayjs from "dayjs";
+import { getCallsCollection } from "../calls.getters";
+import { getClientConfig } from "../../clientsConfig";
+import utc from "dayjs/plugin/utc";
+import timezonePlugin from "dayjs/plugin/timezone";
+import {
+  DashboardAggregationResult,
+  DashboardDailyTrendMetric,
+  DashboardHeatmapMetric,
+  DashboardReportQuery,
+  DashboardReportResponse,
+  DashboardSummaryMetrics,
+  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,
+};
+
+dayjs.extend(utc);
+dayjs.extend(timezonePlugin);
+
+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] },
+        },
+      },
+    },
+  ];
+}
+
+function buildDailyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          $dateToString: {
+            format: "%Y-%m-%d",
+            date: "$createdAt",
+            timezone: timezone,
+          },
+        },
+        count: { $sum: 1 },
+        completed: {
+          $sum: { $cond: [{ $eq: ["$status", "completed"] }, 1, 0] },
+        },
+      },
+    },
+    { $sort: { _id: 1 } },
+  ];
+}
+
+function buildHourlyDataPipeline(timezone: string) {
+  return [
+    {
+      $group: {
+        _id: {
+          day: {
+            $dateToString: {
+              format: "%Y-%m-%d",
+              date: "$createdAt",
+              timezone: timezone,
+            },
+          },
+          hour: { $hour: { date: "$createdAt", timezone: timezone } },
+        },
+        count: { $sum: 1 },
+      },
+    },
+  ];
+}
+
+export function buildCallLengthBucketsPipeline(
+  thresholds: CallLengthThresholds,
+) {
+  const { shortThreshold, mediumThreshold } = thresholds;
+
+  return [
+    {
+      $group: {
+        _id: null,
+        short: {
+          $sum: { $cond: [{ $lt: ["$callLength", shortThreshold] }, 1, 0] },
+        },
+        medium: {
+          $sum: {
+            $cond: [
+              {
+                $and: [
+                  { $gte: ["$callLength", shortThreshold] },
+                  { $lte: ["$callLength", mediumThreshold] },
+                ],
+              },
+              1,
+              0,
+            ],
+          },
+        },
+        long: {
+          $sum: { $cond: [{ $gt: ["$callLength", mediumThreshold] }, 1, 0] },
+        },
+      },
+    },
+  ];
+}
+
+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 } = params;
+  const clientConfig = await getClientConfig(clientId);
+  const timezone = clientConfig?.timezone ?? "UTC";
+
+  const startDateObj = dayjs.tz(startDate, timezone).startOf("day").toDate();
+  const endDateObj = dayjs.tz(endDate, timezone).endOf("day").toDate();
+
+  const thresholds: CallLengthThresholds = {
+    shortThreshold: clientConfig?.callLengthThresholds?.shortThreshold ?? 60,
+    mediumThreshold: clientConfig?.callLengthThresholds?.mediumThreshold ?? 180,
+  };
+
+  const pipeline = [
+    {
+      $match: {
+        clientId,
+        createdAt: { $gte: startDateObj, $lte: endDateObj },
+      },
+    },
+    {
+      $facet: {
+        kpis: buildKpisPipeline(),
+        dailyData: buildDailyDataPipeline(timezone),
+        hourlyData: buildHourlyDataPipeline(timezone),
+        callLengthBuckets: buildCallLengthBucketsPipeline(thresholds),
+      },
+    },
+  ];
+
+  const callsCollection = getCallsCollection();
+  const [aggregatedResult] = await callsCollection
+    .aggregate<DashboardAggregationResult>(pipeline)
+    .toArray();
+
+  const kpiData = aggregatedResult?.kpis?.[0] ?? DEFAULT_KPI_DATA;
+  const dailyDataRaw = aggregatedResult?.dailyData ?? [];
+  const hourlyDataRaw = aggregatedResult?.hourlyData ?? [];
+  const callLengthRaw = aggregatedResult?.callLengthBuckets?.[0] ?? {
+    short: 0,
+    medium: 0,
+    long: 0,
+  };
+
+  const kpis: DashboardSummaryMetrics = {
+    totalCalls: kpiData.totalCalls,
+    avgDurationSeconds:
+      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 volumeData: DashboardDailyTrendMetric[] = dailyDataRaw.map((d) => ({
+    date: d._id,
+    count: d.count,
+    completed: d.completed,
+  }));
+
+  const heatmap = buildHeatmapData(hourlyDataRaw);
+
+  const response: DashboardReportResponse = {
+    kpis,
+    charts: {
+      volumeData,
+      heatmap,
+      callLengthBuckets: {
+        short: callLengthRaw.short,
+        medium: callLengthRaw.medium,
+        long: callLengthRaw.long,
+      },
+    },
+  };
+  return response;
+}

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

@@ -0,0 +1,70 @@
+export type DashboardHeatmapMetric = {
+  hour: number;
+  calls: number;
+};
+
+export type DashboardDailyTrendMetric = {
+  date: string;
+  count: number;
+  completed: number;
+};
+
+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[];
+  heatmap: Record<string, DashboardHeatmapMetric[]>;
+  callLengthBuckets: DashboardDurationSegments;
+};
+
+export type DashboardReportQuery = {
+  clientId: string;
+  startDate: string;
+  endDate: string;
+};
+
+export type DashboardReportResponse = {
+  kpis: DashboardSummaryMetrics;
+  charts: DashboardVisualData;
+};
+type RawKpiResult = {
+  totalCalls: number;
+  totalDuration: number | null;
+  completedCount: number;
+  failedCount: number;
+  noAnswerCount: number;
+  busyCount: number;
+};
+
+export type RawDailyAggregationResult = {
+  _id: string;
+  count: number;
+  completed: number;
+};
+
+export type RawHourlyAggregationResult = {
+  _id: { day: string; hour: number };
+  count: number;
+};
+
+export interface DashboardAggregationResult {
+  kpis: RawKpiResult[];
+  dailyData: RawDailyAggregationResult[];
+  hourlyData: RawHourlyAggregationResult[];
+  callLengthBuckets: DashboardDurationSegments[];
+}

package/src/talkpilot/calls/index.ts

@@ -1,2 +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.getters.spec.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import {
+  getClientsConfigCollection,
+  updateProductConfig,
+} from "../clientsConfig.getters";
+
+describe("updateProductConfig", () => {
+  beforeEach(async () => {
+    await getClientsConfigCollection().deleteMany({});
+  });
+
+  afterEach(async () => {
+    await getClientsConfigCollection().deleteMany({});
+  });
+
+  it("should update partial fields using correct dot notation", async () => {
+    const clientId = "client-123";
+    const collection = getClientsConfigCollection();
+
+    await collection.insertOne({
+      clientId,
+      products: {
+        websiteTalk: {
+          language: "English",
+          companyName: "OldCorp",
+          defaultBaseUrl: "https://old-url.com",
+          logoUrl: "",
+          timezone: "UTC",
+        },
+      },
+    } as any);
+
+    const updates = { language: "Hebrew", companyName: "TestCorp" };
+    await updateProductConfig(clientId, "websiteTalk", updates);
+
+    const updatedDoc = await collection.findOne({ clientId });
+
+    expect(updatedDoc).toBeDefined();
+    expect(updatedDoc?.products.websiteTalk?.language).toBe("Hebrew");
+    expect(updatedDoc?.products.websiteTalk?.companyName).toBe("TestCorp");
+    expect(updatedDoc?.products.websiteTalk?.defaultBaseUrl).toBe(
+      "https://old-url.com",
+    );
+  });
+
+  it("should throw an error if no client config is found", async () => {
+    await expect(
+      updateProductConfig("invalid-client", "websiteTalk", {
+        language: "English",
+      }),
+    ).rejects.toThrow("No client config found for clientId: invalid-client");
+  });
+});

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

@@ -38,8 +38,8 @@ describe("db.clientsConfig", () => {
             defaultBaseUrl: "https://acme.example",
             scheduler: {
               type: "cron",
-              schedule: "0 9 * * 1-5"
-           },
+              schedule: "0 9 * * 1-5",
+            },
           },
         },
       });
@@ -94,10 +94,12 @@ describe("db.clientsConfig", () => {
       const result = await getClientConfig(clientId);
 
       // Then
-      expect(result?.products.municipal?.moked_106?.toolsPrompts).toMatchObject({
-        findSubjectsSystemPrompt: "Custom subjects prompt",
-        findStreetsSystemPrompt: "Custom streets prompt",
-      });
+      expect(result?.products.municipal?.moked_106?.toolsPrompts).toMatchObject(
+        {
+          findSubjectsSystemPrompt: "Custom subjects prompt",
+          findStreetsSystemPrompt: "Custom streets prompt",
+        },
+      );
     });
 
     it("given moked_106 with findSubjectsSystemPrompt only when saved and retrieved then findStreetsSystemPrompt is undefined", async () => {
@@ -123,8 +125,14 @@ describe("db.clientsConfig", () => {
       const result = await getClientConfig(clientId);
 
       // Then
-      expect(result?.products.municipal?.moked_106?.toolsPrompts?.findSubjectsSystemPrompt).toBe("Subjects only prompt");
-      expect(result?.products.municipal?.moked_106?.toolsPrompts?.findStreetsSystemPrompt).toBeUndefined();
+      expect(
+        result?.products.municipal?.moked_106?.toolsPrompts
+          ?.findSubjectsSystemPrompt,
+      ).toBe("Subjects only prompt");
+      expect(
+        result?.products.municipal?.moked_106?.toolsPrompts
+          ?.findStreetsSystemPrompt,
+      ).toBeUndefined();
     });
 
     it("given moked_106 without toolsPrompts when saved and retrieved then toolsPrompts is undefined", async () => {
@@ -148,7 +156,9 @@ describe("db.clientsConfig", () => {
       const result = await getClientConfig(clientId);
 
       // Then
-      expect(result?.products.municipal?.moked_106?.toolsPrompts).toBeUndefined();
+      expect(
+        result?.products.municipal?.moked_106?.toolsPrompts,
+      ).toBeUndefined();
     });
 
     it("should support communications config", async () => {

package/src/talkpilot/clientsConfig/clientsConfig.getters.ts

@@ -1,4 +1,11 @@
-import { ClientConfigDoc, getDb, findClientByPhoneNumber } from "../index";
+import {
+  ClientConfigDoc,
+  getDb,
+  findClientByPhoneNumber,
+  Products,
+  KNOWN_PRODUCT_KEYS,
+  KnownProductKey,
+} from "../index";
 import { Collection } from "mongodb";
 
 export const getClientsConfigCollection = (): Collection<ClientConfigDoc> => {
@@ -20,3 +27,29 @@ export const createClientConfigDoc = async (
 ): Promise<void> => {
   await getClientsConfigCollection().insertOne(clientConfig);
 };
+
+export async function updateProductConfig<K extends KnownProductKey>(
+  clientId: string,
+  productKey: K,
+  updates: Partial<Products[K]>,
+): Promise<void> {
+  if (!KNOWN_PRODUCT_KEYS.includes(productKey as KnownProductKey)) {
+    throw new Error(
+      `Invalid product key: "${productKey}". Must be one of: ${KNOWN_PRODUCT_KEYS.join(", ")}`,
+    );
+  }
+
+  const setOperations: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(updates)) {
+    setOperations[`products.${productKey}.${key}`] = value;
+  }
+
+  const result = await getClientsConfigCollection().updateOne(
+    { clientId },
+    { $set: setOperations },
+  );
+
+  if (result.matchedCount === 0) {
+    throw new Error(`No client config found for clientId: ${clientId}`);
+  }
+}

package/src/talkpilot/clientsConfig/clientsConfig.types.ts

@@ -1,4 +1,5 @@
 import { WithId } from "mongodb";
+import { CallLengthThresholds } from "src/utils/shared.types";
 
 // ---------------------------------------------------------------------------
 // Moked106 (MIS)
@@ -26,6 +27,13 @@ export type Moked106Config = {
   toolsPrompts?: Moked106ToolPrompts;
 };
 
+export const KNOWN_PRODUCT_KEYS = [
+  "municipal",
+  "clinics",
+  "websiteTalk",
+] as const;
+export type KnownProductKey = (typeof KNOWN_PRODUCT_KEYS)[number];
+
 /** Product config for the MIS */
 export type MunicipalProduct = {
   moked_106?: Moked106Config;
@@ -55,7 +63,6 @@ export type WebsiteTalkProduct = {
   timezone: string;
   language: string;
   defaultBaseUrl: string;
-  scheduler?: WebsiteTalkScheduler;
 };
 
 // ---------------------------------------------------------------------------
@@ -112,6 +119,7 @@ export type ClientConfig<P extends Products = Products> = {
   products: P;
   timezone?: string;
   communications?: CommunicationsConfig;
+  callLengthThresholds?: CallLengthThresholds;
 };
 
 export type ClientConfigDoc<P extends Products = Products> = WithId<

package/src/talkpilot/flows/__tests__/flows.schema.spec.ts

@@ -61,7 +61,11 @@ describe("flowMongoSchema", () => {
       "backgroundToolOnce",
     ]);
 
-    expect(toolItem.properties).toHaveProperty('backgroundContinuationInstructions');
-    expect(toolItem.properties.backgroundContinuationInstructions.bsonType).toBe('string');
+    expect(toolItem.properties).toHaveProperty(
+      "backgroundContinuationInstructions",
+    );
+    expect(
+      toolItem.properties.backgroundContinuationInstructions.bsonType,
+    ).toBe("string");
   });
 });

package/src/talkpilot/flows/flows.schema.ts

@@ -143,7 +143,7 @@ export const flowMongoSchema = {
             bsonType: "string",
             enum: ["backgroundToolAlways", "backgroundToolOnce"],
           },
-          backgroundContinuationInstructions: { bsonType: 'string' },
+          backgroundContinuationInstructions: { bsonType: "string" },
         },
         additionalProperties: false,
       },

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

@@ -6,14 +6,14 @@ import {
   getClientPhoneData,
   createPhoneNumberEntity,
   createPurchasedPhoneNumber,
-} from '../phone_numbers.getter';
-import { getFlowsCollection } from '../../flows/flows.getter';
-import { createFlow, createPhoneNumber } from '../../../test-utils/factories';
-import { ObjectId } from 'mongodb';
-
-describe('db.phoneNumbers', () => {
-  describe('getPhoneDataByPhoneNumber', () => {
-    it('return phone number data with flow', async () => {
+} from "../phone_numbers.getter";
+import { getFlowsCollection } from "../../flows/flows.getter";
+import { createFlow, createPhoneNumber } from "../../../test-utils/factories";
+import { ObjectId } from "mongodb";
+
+describe("db.phoneNumbers", () => {
+  describe("getPhoneDataByPhoneNumber", () => {
+    it("return phone number data with flow", async () => {
       const flow = createFlow({
         clientId: "test-client-id",
         conversationSettings: {
@@ -129,9 +129,9 @@ describe('db.phoneNumbers', () => {
     });
   });
 
-  describe('getPhoneNumbersForFlows', () => {
-    it('returns all phone numbers for the client with flow ObjectIds, newest first', async () => {
-      const clientId = 'flowsClient';
+  describe("getPhoneNumbersForFlows", () => {
+    it("returns all phone numbers for the client with flow ObjectIds, newest first", async () => {
+      const clientId = "flowsClient";
       const flow1 = createFlow({ clientId });
       const flow2 = createFlow({ clientId });
       await getFlowsCollection().insertMany([flow1, flow2]);
@@ -139,16 +139,16 @@ describe('db.phoneNumbers', () => {
       const older = createPhoneNumber({
         client_id: clientId,
         flow_id: flow1._id,
-        phone_number: '+100',
+        phone_number: "+100",
         is_primary: true,
-        createdAt: new Date('2023-01-01'),
+        createdAt: new Date("2023-01-01"),
       });
       const newer = createPhoneNumber({
         client_id: clientId,
         flow_id: flow2._id,
-        phone_number: '+200',
+        phone_number: "+200",
         is_primary: false,
-        createdAt: new Date('2023-06-01'),
+        createdAt: new Date("2023-06-01"),
       });
 
       await getPhoneNumbersCollection().insertMany([older, newer]);
@@ -158,27 +158,30 @@ describe('db.phoneNumbers', () => {
       expect(result).toHaveLength(2);
       expect(result[0]).toEqual({
         flowId: String(flow2._id),
-        phoneNumber: '+200',
+        phoneNumber: "+200",
         isPrimary: false,
       });
       expect(result[1]).toEqual({
         flowId: String(flow1._id),
-        phoneNumber: '+100',
+        phoneNumber: "+100",
         isPrimary: true,
       });
     });
 
-    it('returns an empty array when the client has no phone numbers', async () => {
-      const result = await getPhoneNumbersForFlows('noSuchClient');
+    it("returns an empty array when the client has no phone numbers", async () => {
+      const result = await getPhoneNumbersForFlows("noSuchClient");
       expect(result).toEqual([]);
     });
 
-    it('does not include phone numbers for other clients', async () => {
-      const clientA = 'clientA';
-      const clientB = 'clientB';
+    it("does not include phone numbers for other clients", async () => {
+      const clientA = "clientA";
+      const clientB = "clientB";
       const flow = createFlow();
       await getFlowsCollection().insertOne(flow);
-      const phone = createPhoneNumber({ client_id: clientA, flow_id: flow._id });
+      const phone = createPhoneNumber({
+        client_id: clientA,
+        flow_id: flow._id,
+      });
       await getPhoneNumbersCollection().insertOne(phone);
 
       const result = await getPhoneNumbersForFlows(clientB);
@@ -186,9 +189,9 @@ describe('db.phoneNumbers', () => {
     });
   });
 
-  describe('createPhoneNumberEntity', () => {
-    it('creates first phone number as primary', async () => {
-      const clientId = 'newClient';
+  describe("createPhoneNumberEntity", () => {
+    it("creates first phone number as primary", async () => {
+      const clientId = "newClient";
       const flowId = new ObjectId().toHexString();
       const phoneNumber = "+123456789";
 
@@ -215,14 +218,14 @@ describe('db.phoneNumbers', () => {
     });
   });
 
-  describe('createPurchasedPhoneNumber', () => {
-    it('persists a phone_numbers document with provider payload and flow', async () => {
-      const clientId = 'purchasedClientDb';
+  describe("createPurchasedPhoneNumber", () => {
+    it("persists a phone_numbers document with provider payload and flow", async () => {
+      const clientId = "purchasedClientDb";
       const flowId = new ObjectId().toHexString();
-      const phoneNumber = '+15551234567';
+      const phoneNumber = "+15551234567";
       const providerPayload = {
-        provider: 'twilio' as const,
-        provider_sid: 'PNxxxxxxxx',
+        provider: "twilio" as const,
+        provider_sid: "PNxxxxxxxx",
       };
 
       await createPurchasedPhoneNumber(
@@ -233,13 +236,15 @@ describe('db.phoneNumbers', () => {
       );
 
       // Re-read from Mongo to confirm insert succeeded (not only the function return value).
-      const stored = await getPhoneNumbersCollection().findOne({ phone_number: phoneNumber });
+      const stored = await getPhoneNumbersCollection().findOne({
+        phone_number: phoneNumber,
+      });
       expect(stored).not.toBeNull();
       expect(stored).toMatchObject({
         phone_number: phoneNumber,
         client_id: clientId,
-        provider: 'twilio',
-        provider_sid: 'PNxxxxxxxx',
+        provider: "twilio",
+        provider_sid: "PNxxxxxxxx",
         flow_id: new ObjectId(flowId),
       });
     });

package/src/talkpilot/phone_numbers/index.ts

@@ -1,2 +1,2 @@
-export * from './phone_numbers.getter';
-export type * from './phone_numbers.types';
+export * from "./phone_numbers.getter";
+export type * from "./phone_numbers.types";