@talkpilot/core-db 1.2.1 → 1.2.2

package/dist/utils/shared.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.types.js","sourceRoot":"","sources":["../../src/utils/shared.types.ts"],"names":[],"mappings":""}

package/jest.config.js

@@ -1,19 +1,19 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} */
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
-  testPathIgnorePatterns: ['<rootDir>/src/__tests__/legacy/'],
-  testMatch: ['**/__tests__/**/*.spec.ts', '**/*.spec.ts'],
-  transform: {
-    '^.+\\.tsx?$': ['ts-jest', {
-      tsconfig: 'tsconfig.json',
-    }],
-  },
-  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
-  verbose: true,
-  forceExit: true,
-  clearMocks: true,
-  resetMocks: true,
-  restoreMocks: true,
-};
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testPathIgnorePatterns: ['<rootDir>/src/__tests__/legacy/'],
+  testMatch: ['**/__tests__/**/*.spec.ts', '**/*.spec.ts'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: 'tsconfig.json',
+    }],
+  },
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  verbose: true,
+  forceExit: true,
+  clearMocks: true,
+  resetMocks: true,
+  restoreMocks: true,
+};

package/package.json

@@ -1,45 +1,46 @@
-{
-  "name": "@talkpilot/core-db",
-  "version": "1.2.1",
-  "description": "Core database package for centralized connections and ORM integration.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "jest",
-    "lint": "eslint 'src/**/*.{ts,tsx}'",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "prepare": "npm run build"
-  },
-  "keywords": [
-    "database",
-    "orm",
-    "typescript",
-    "postgres",
-    "db-client"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "express": "^4.18.0",
-    "google-libphonenumber": "^3.2.0",
-    "mongodb": "^6.11.0"
-  },
-  "devDependencies": {
-    "@faker-js/faker": "^8.0.0",
-    "@types/express": "^4.17.0",
-    "@types/google-libphonenumber": "^7.4.0",
-    "@types/jest": "^29.0.0",
-    "@types/node": "^20.0.0",
-    "fishery": "^2.4.0",
-    "jest": "^29.0.0",
-    "mongodb-memory-server": "^10.0.0",
-    "prettier": "^3.8.2",
-    "ts-jest": "^29.0.0",
-    "typescript": "^5.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@talkpilot/core-db",
+  "version": "1.2.2",
+  "description": "Core database package for centralized connections and ORM integration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "database",
+    "orm",
+    "typescript",
+    "postgres",
+    "db-client"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "dayjs": "^1.11.21",
+    "express": "^4.18.0",
+    "google-libphonenumber": "^3.2.0",
+    "mongodb": "^6.11.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.0.0",
+    "@types/express": "^4.17.0",
+    "@types/google-libphonenumber": "^7.4.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "fishery": "^2.4.0",
+    "jest": "^29.0.0",
+    "mongodb-memory-server": "^10.0.0",
+    "prettier": "^3.8.2",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { getDashboardStats } from "../dashboard/calls.dashboard";
+import { getCallsCollection } from "../calls.getters";
+import { getClientsConfigCollection } from "../../clientsConfig/clientsConfig.getters";
+
+describe("getDashboardStats", () => {
+  beforeEach(async () => {
+    await getCallsCollection().deleteMany({});
+    await getClientsConfigCollection().deleteMany({});
+  });
+
+  afterEach(async () => {
+    await getCallsCollection().deleteMany({});
+    await getClientsConfigCollection().deleteMany({});
+  });
+
+  it("should return correct empty dashboard stats when no calls exist", async () => {
+    const clientId = "client-dash-123";
+
+    await getClientsConfigCollection().insertOne({
+      clientId,
+      timezone: "UTC",
+      products: {},
+    } as any);
+
+    const params = {
+      clientId,
+      startDate: "2026-05-01",
+      endDate: "2026-05-31",
+    };
+
+    const result = await getDashboardStats(params);
+
+    expect(result).toBeDefined();
+    expect(result.kpis.totalCalls).toBe(0);
+    expect(result.kpis.completedCount).toBe(0);
+    expect(result.kpis.avgDurationSeconds).toBe(0);
+    expect(result.charts.volumeData).toEqual([]);
+    expect(result.charts.heatmap).toEqual({});
+    expect(result.charts.callLengthBuckets).toEqual({
+      short: 0,
+      medium: 0,
+      long: 0,
+    });
+  });
+});

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

@@ -10,7 +10,7 @@ import {
   getCallsCollection,
   pushToolExecution,
 } from "../calls.getters";
-import type { ToolExecution } from '../calls.types';
+import type { ToolExecution } from "../calls.types";
 import { ObjectId } from "mongodb";
 import { createOutGoingCallDoc } from "../../../test-utils/factories";
 
@@ -115,7 +115,7 @@ describe("db.calls", () => {
     });
   });
 
-  describe('pushToolExecution()', () => {
+  describe("pushToolExecution()", () => {
     let callSid: string;
 
     beforeEach(async () => {
@@ -124,63 +124,73 @@ describe("db.calls", () => {
       callSid = call.callSid;
     });
 
-    const makeHttpExecution = (overrides?: Partial<ToolExecution>): ToolExecution => ({
-      toolName: 'sendSms',
+    const makeHttpExecution = (
+      overrides?: Partial<ToolExecution>,
+    ): ToolExecution => ({
+      toolName: "sendSms",
       executedAt: new Date(),
       durationMs: 120,
-      args: { to: '+1234567890', message: 'hello' },
-      meta: { kind: 'http', url: 'https://api.example.com/sms', method: 'POST' },
-      status: 'success',
+      args: { to: "+1234567890", message: "hello" },
+      meta: {
+        kind: "http",
+        url: "https://api.example.com/sms",
+        method: "POST",
+      },
+      status: "success",
       httpStatus: 200,
       ...overrides,
     });
 
-    it('should append an execution to a call with none', async () => {
+    it("should append an execution to a call with none", async () => {
       const execution = makeHttpExecution();
       await pushToolExecution(callSid, execution);
 
       const result = await getCallByCallSid(callSid);
       expect(result?.toolExecutions).toHaveLength(1);
       expect(result?.toolExecutions?.[0]).toMatchObject({
-        toolName: 'sendSms',
-        status: 'success',
+        toolName: "sendSms",
+        status: "success",
         httpStatus: 200,
       });
     });
 
-    it('should maintain insertion order across multiple pushes', async () => {
-      const first = makeHttpExecution({ toolName: 'first' });
-      const second = makeHttpExecution({ toolName: 'second' });
-      const third = makeHttpExecution({ toolName: 'third' });
+    it("should maintain insertion order across multiple pushes", async () => {
+      const first = makeHttpExecution({ toolName: "first" });
+      const second = makeHttpExecution({ toolName: "second" });
+      const third = makeHttpExecution({ toolName: "third" });
 
       await pushToolExecution(callSid, first);
       await pushToolExecution(callSid, second);
       await pushToolExecution(callSid, third);
 
       const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.map(e => e.toolName)).toEqual(['first', 'second', 'third']);
+      expect(result?.toolExecutions?.map((e) => e.toolName)).toEqual([
+        "first",
+        "second",
+        "third",
+      ]);
     });
 
-    it('should store an internal tool execution', async () => {
+    it("should store an internal tool execution", async () => {
       const execution: ToolExecution = {
-        toolName: 'endFlow',
+        toolName: "endFlow",
         executedAt: new Date(),
         durationMs: 5,
         args: {},
-        meta: { kind: 'internal' },
-        status: 'success',
+        meta: { kind: "internal" },
+        status: "success",
       };
 
       await pushToolExecution(callSid, execution);
 
       const result = await getCallByCallSid(callSid);
       expect(result?.toolExecutions?.[0]).toMatchObject({
-        toolName: 'endFlow',
-        meta: { kind: 'internal' },
+        toolName: "endFlow",
+        meta: { kind: "internal" },
       });
     });
 
-    it('should store redacted args for sensitive tools', async () => {
+    it("should store redacted args for sensitive tools", async () => {
       const execution = makeHttpExecution({ args: { _redacted: true } });
       await pushToolExecution(callSid, execution);
 
@@ -188,26 +198,34 @@ describe("db.calls", () => {
       expect(result?.toolExecutions?.[0].args).toEqual({ _redacted: true });
     });
 
-    it('should store an error execution', async () => {
-      const execution = makeHttpExecution({ status: 'error', httpStatus: 500 });
+    it("should store an error execution", async () => {
+      const execution = makeHttpExecution({ status: "error", httpStatus: 500 });
       await pushToolExecution(callSid, execution);
 
       const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0]).toMatchObject({ status: 'error', httpStatus: 500 });
+      expect(result?.toolExecutions?.[0]).toMatchObject({
+        status: "error",
+        httpStatus: 500,
+      });
     });
 
-    it('should be a no-op for an unknown callSid', async () => {
-      await expect(pushToolExecution('nonexistent-sid', makeHttpExecution())).resolves.not.toThrow();
+    it("should be a no-op for an unknown callSid", async () => {
+      await expect(
+        pushToolExecution("nonexistent-sid", makeHttpExecution()),
+      ).resolves.not.toThrow();
     });
 
-    it('should store the response body', async () => {
+    it("should store the response body", async () => {
       const execution = makeHttpExecution({
-        response: { userId: '123', status: 'sent' },
+        response: { userId: "123", status: "sent" },
       });
       await pushToolExecution(callSid, execution);
 
       const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0].response).toEqual({ userId: '123', status: 'sent' });
+      expect(result?.toolExecutions?.[0].response).toEqual({
+        userId: "123",
+        status: "sent",
+      });
     });
   });
 

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,
   }));
 }

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

@@ -47,21 +47,21 @@ export type ToolExecution = {
   durationMs: number;
   args: Record<string, unknown> | { _redacted: true };
   meta: ToolExecutionMeta;
-  status: 'success' | 'error';
+  status: "success" | "error";
   httpStatus?: number;
   response?: Record<string, unknown>;
 };
 
 export type ToolExecutionMeta =
-    | {
-  kind: 'http';
-  url: string;
-  method: string;
-  flowToolId?: string;
-  runInBackground?: boolean;
-  sensitive?: boolean;
-}
-    | { kind: 'internal' };
+  | {
+      kind: "http";
+      url: string;
+      method: string;
+      flowToolId?: string;
+      runInBackground?: boolean;
+      sensitive?: boolean;
+    }
+  | { kind: "internal" };
 
 export type CallQueryOptions = {
   sort?: Sort;
@@ -102,8 +102,6 @@ export type CallUpdateParams = Partial<Omit<Call, ImmutableCallFields>>;
 
 export type CallDoc = WithId<Call>;
 
-export type CallsByHour = { hour: string; calls: number };
-
 export type CountOpts = {
   isOutgoingCall?: boolean;
   isIncomingCall?: boolean;

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;
+}