@talkpilot/core-db 1.0.1

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

@@ -0,0 +1,234 @@
+import { CityName, getDb, ObjectId, Ticket } from '../index';
+import type { SubjectStatsItem } from './tickets.types';
+import { Collection, Filter, ObjectId as MongoObjectId } from 'mongodb';
+
+/**
+ * Generate a new ticket ID as a string
+ * @returns A new ObjectId as a string
+ */
+export const generateTicketId = (): string => {
+  return new ObjectId().toString();
+};
+
+export const getTicketsCollection = (): Collection<Ticket> => {
+  return getDb().collection<Ticket>('tickets');
+};
+
+export const findTickets = async (filter: Filter<Ticket> = {}): Promise<Ticket[]> => {
+  return await getTicketsCollection().find(filter).toArray();
+};
+
+export const findTicketsByCallSid = async (callSid: string): Promise<Ticket[]> => {
+  return await getTicketsCollection().find({ callSid }).toArray();
+};
+
+export const getTicketById = async (ticketId: string): Promise<Ticket | null> => {
+  const ticket = await getTicketsCollection().findOne({ _id: new ObjectId(ticketId) });
+  return ticket ? ticket : null;
+};
+
+export const createTicket = async (
+  ticketData: Omit<Ticket, '_id' | 'createdAt' | 'updatedAt'>,
+  ticketId?: string
+): Promise<MongoObjectId> => {
+  const ticket: Ticket = {
+    _id: ticketId ? new ObjectId(ticketId) : new ObjectId(),
+    ...ticketData,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+  const { insertedId } = await getTicketsCollection().insertOne(ticket);
+  return insertedId;
+};
+
+export const updateTicket = async (
+  ticketId: string,
+  data: Partial<Omit<Ticket, '_id' | 'createdAt' | 'updatedAt'>>
+): Promise<Ticket | null> => {
+  const result = await getTicketsCollection().findOneAndUpdate(
+    { _id: new ObjectId(ticketId) },
+    { $set: { ...data, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+  return result || null;
+};
+
+export const deleteTicket = async (ticketId: string): Promise<boolean> => {
+  const result = await getTicketsCollection().deleteOne({ _id: new ObjectId(ticketId) });
+  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 } },
+      {
+        $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);
+};
+/**
+ * Update ticket files by external call number
+ */
+export const updateTicketFilesByCallNumber = async (params: {
+  cityName: CityName;
+  callNumber: string;
+  image1?: string;
+  image2?: string;
+  image3?: string;
+}): Promise<boolean> => {
+  const { cityName, callNumber, image1, image2, image3 } = params;
+
+  const update: any = {};
+  if (image1) update['externalCallFields.image1'] = image1;
+  if (image2) update['externalCallFields.image2'] = image2;
+  if (image3) update['externalCallFields.image3'] = image3;
+
+  const result = await getTicketsCollection().updateOne(
+    {
+      cityName: cityName,
+      'externalCallFields.call_number': callNumber,
+    },
+    {
+      $set: {
+        ...update,
+        updatedAt: new Date(),
+      },
+    }
+  );
+
+  return result.matchedCount > 0;
+};
+
+/**
+ * Remove guestJwt from ticket by external call number
+ */
+export const clearGuestJwtByCallNumber = async (params: {
+  cityName: CityName;
+  callNumber: string;
+}): Promise<boolean> => {
+  const { cityName, callNumber } = params;
+
+  const result = await getTicketsCollection().updateOne(
+    { cityName, 'externalCallFields.call_number': callNumber },
+    { $unset: { guestJwt: '' }, $set: { updatedAt: new Date() } }
+  );
+
+  return result.matchedCount > 0;
+};

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

@@ -0,0 +1,39 @@
+import { ObjectId, WithId } from 'mongodb';
+import { CityName } from '../departmentsSubjects/departmentsSubjects.types';
+
+export type Ticket = {
+  _id: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+  callSid?: string;
+  cityName: CityName;
+  externalCallFields: {
+    // Request fields
+    first_name?: string;
+    last_name?: string;
+    event_description?: string;
+    street?: string;
+    house_number?: string;
+    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
+    image1?: string;
+    image2?: string;
+    image3?: string;
+  };
+  guestJwt?: string;
+};
+
+export type TicketDoc = WithId<Ticket>;
+
+/** Call count by department (subject). */
+export type SubjectStatsItem = {
+  subject_name: string;
+  subject_id: string;
+  count: number;
+  percentage: number;
+};

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

@@ -0,0 +1,38 @@
+import {
+  getFlowsCollection,
+  getSessionsCollection,
+  getResultsCollection,
+  getLeadsCollection,
+  getPhoneNumbersCollection,
+  getClientsCollection,
+  ObjectId,
+  getPlansCollection,
+  getSubscriptionsCollection,
+} from '../index';
+
+import { ObjectId as MongoObjectId } from 'mongodb';
+
+describe('talkpilot core/db', () => {
+  it.each([
+    ['flows', getFlowsCollection],
+    ['sessions', getSessionsCollection],
+    ['results', getResultsCollection],
+    ['leads', getLeadsCollection],
+    ['phone_numbers', getPhoneNumbersCollection],
+    ['clients', getClientsCollection],
+    ['plans', getPlansCollection],
+    ['subscriptions', getSubscriptionsCollection],
+  ])('%s collection helper returns a "%s" collection', (name, getter) => {
+    expect(getter().collectionName).toBe(name);
+  });
+
+  it('ObjectId re-export behaves like mongodb.ObjectId', () => {
+    expect(ObjectId).toBe(MongoObjectId);
+
+    const id = new ObjectId();
+
+    expect(id).toBeInstanceOf(MongoObjectId);
+    expect(ObjectId.isValid(id)).toBe(true);
+    expect(id.toHexString()).toHaveLength(24);
+  });
+});

package/src/talkpilot/__tests__/mongodb-client.spec.ts

@@ -0,0 +1,19 @@
+import { mongodbClient } from '../mongodb-client';
+import { getDb } from '../index';
+
+describe('MongoDBClient', () => {
+  it('should have a connected database instance from global setup', () => {
+    const db = getDb();
+    expect(db).toBeDefined();
+    expect(db.databaseName).toBe('test'); // Based on our setup.ts
+  });
+
+  it('should report as connected', async () => {
+    // Note: mongodbClient.connect() was called in global setup
+    // but through setDb, not necessarily through the client singleton instance
+    // since initTestDb calls setDb directly.
+    
+    // In a real scenario, you'd use the client.
+    expect(true).toBe(true); 
+  });
+});

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

@@ -0,0 +1,62 @@
+import { mongodbClient } from '../mongodb-client';
+import { MongoClient } from 'mongodb';
+
+describe('MongoDBClient Validation', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.MONGO_URI;
+    delete process.env.MONGODB_URI;
+    delete process.env.MONGODB_DB_NAME;
+    
+    // Force reset singleton state
+    (mongodbClient as any).client = null;
+    (mongodbClient as any).db = null;
+  });
+
+  afterAll(async () => {
+    process.env = originalEnv;
+    // Ensure we are disconnected
+    await mongodbClient.disconnect();
+  });
+
+  it('should throw error if no URI is provided', async () => {
+    await expect(mongodbClient.connect()).rejects.toThrow(
+      "[core-db] Configuration Error: 'MONGO_URI' is missing"
+    );
+  });
+
+  it('should throw error if an invalid URI format is provided', async () => {
+    await expect(mongodbClient.connect('not-a-mongo-uri')).rejects.toThrow(
+      "[core-db] Connection Error: The provided MongoDB URI is invalid"
+    );
+  });
+
+  it('should throw error if URI is valid but database name is missing', async () => {
+    // We mock the actual MongoClient connection so it doesn't try to hit a real network
+    const connectSpy = jest.spyOn(MongoClient.prototype, 'connect').mockResolvedValue({} as any);
+    
+    const uriWithoutDb = 'mongodb://127.0.0.1:27017'; 
+    await expect(mongodbClient.connect(uriWithoutDb)).rejects.toThrow(
+      "[core-db] Database name not specified"
+    );
+    
+    connectSpy.mockRestore();
+  });
+
+  it('should succeed when valid URI and DB name are provided', async () => {
+    const mockDb = { databaseName: 'my-db' };
+    const connectSpy = jest.spyOn(MongoClient.prototype, 'connect').mockResolvedValue({} as any);
+    const dbSpy = jest.spyOn(MongoClient.prototype, 'db').mockReturnValue(mockDb as any);
+    
+    const validUri = 'mongodb://127.0.0.1:27017/my-db';
+    await mongodbClient.connect(validUri);
+    
+    expect(mongodbClient.getDb()).toBeDefined();
+    expect(mongodbClient.getDb().databaseName).toBe('my-db');
+    
+    connectSpy.mockRestore();
+    dbSpy.mockRestore();
+  });
+});

package/src/talkpilot/agents/__tests__/agents.getters.spec.ts

@@ -0,0 +1,29 @@
+import { findAgents } from '../agents.getters';
+import { setDb } from '../../index';
+import { Db, Collection } from 'mongodb';
+import { createAgent } from '../../../test-utils/factories';
+
+describe('agents getters', () => {
+  let mockDb: Partial<Db>;
+  let mockCollection: Partial<Collection>;
+
+  beforeEach(() => {
+    const mockAgent = createAgent({ name: 'Agent Smith' });
+    mockCollection = {
+      find: jest.fn().mockReturnValue({
+        toArray: jest.fn().mockResolvedValue([mockAgent]),
+      }),
+    };
+    mockDb = {
+      collection: jest.fn().mockReturnValue(mockCollection),
+    };
+    setDb(mockDb as Db);
+  });
+
+  it('findAgents should return agents', async () => {
+    const result = await findAgents();
+    
+    expect(mockDb.collection).toHaveBeenCalledWith('agents');
+    expect(result[0].name).toBe('Agent Smith');
+  });
+});

package/src/talkpilot/agents/agents.getters.ts

@@ -0,0 +1,34 @@
+import { getDb, Agent, ObjectId } from '../index';
+
+export const getAgentsCollection = () => {
+  return getDb().collection<Agent>('agents');
+};
+
+export const findAgents = async (filter: any = {}) => {
+  return getAgentsCollection().find(filter).toArray();
+};
+
+export const findAgentById = (agentId: string) => {
+  return getAgentsCollection().findOne({ _id: new ObjectId(agentId) });
+};
+
+export const findAgentsByClientId = (clientId: string) => {
+  return getAgentsCollection().find({ clientId }).toArray();
+};
+
+export const createAgent = async (agent: Agent) => {
+  const { insertedId } = await getAgentsCollection().insertOne(agent);
+  return findAgentById(String(insertedId));
+};
+
+export const updateAgent = (agentId: string, data: Partial<Agent>) => {
+  return getAgentsCollection().findOneAndUpdate(
+    { _id: new ObjectId(agentId) },
+    { $set: data },
+    { returnDocument: 'after' }
+  );
+};
+
+export const removeAgent = (agentId: string) => {
+  return getAgentsCollection().deleteOne({ _id: new ObjectId(agentId) });
+};

package/src/talkpilot/agents/agents.types.ts

@@ -0,0 +1,14 @@
+import { WithId } from 'mongodb';
+
+export type Agent = {
+  name: string;
+  language: string;
+  voice: string;
+  instructions: string;
+  labels: string[];
+  clientId: string;
+  role: string;
+  gender: 'male' | 'female';
+};
+
+export type AgentDoc = WithId<Agent>;

package/src/talkpilot/agents/index.ts

@@ -0,0 +1,2 @@
+export * from './agents.getters';
+export * from './agents.types';

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

@@ -0,0 +1,56 @@
+import {
+  createCallDoc,
+  getCallsByFlow,
+  getCallsByClient,
+  getCallsByPhoneNumber,
+  getCallByCallSid,
+} from '../calls.getters';
+import { ObjectId } from 'mongodb';
+import { createOutGoingCallDoc } from '../../../test-utils/factories';
+
+describe('db.calls', () => {
+  it('should return calls by flow', async () => {
+    const flowId = new ObjectId();
+    const call1 = createOutGoingCallDoc({ flowId });
+    const call2 = createOutGoingCallDoc({ flowId });
+
+    await createCallDoc(call1);
+    await createCallDoc(call2);
+
+    const result = await getCallsByFlow(flowId);
+
+    expect(result.length).toBe(2);
+    expect(result).toMatchObject([
+      { callSid: call1.callSid },
+      { callSid: call2.callSid }
+    ]);
+  });
+
+  it('should get call by callSid', async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallByCallSid(call.callSid);
+
+    expect(result).toBeDefined();
+    expect(result?.callSid).toBe(call.callSid);
+  });
+
+  it('should get calls by client', async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallsByClient(call.clientId);
+
+    expect(result.some(c => c.callSid === call.callSid)).toBe(true);
+  });
+
+  it('should get calls by phone number', async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallsByPhoneNumber(call.customerPhoneNumber);
+
+    expect(result.some(c => c.callSid === call.callSid)).toBe(true);
+  });
+});

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

@@ -0,0 +1,134 @@
+import { getDb, Call, CallDoc, CallUpdateParams } from '../index';
+import type { CallsByHour } from './calls.types';
+import { ObjectId } from 'mongodb';
+import * as process from 'node:process';
+
+export const getCallsCollection = () => {
+  return getDb().collection<Call>('calls');
+};
+
+export const getCallByCallSid = (callSid: string) => {
+  return getCallsCollection().findOne({ callSid });
+};
+
+export const getCallsByPhoneNumber = (phoneNumber: string) => {
+  return getCallsCollection().find({ customerPhoneNumber: phoneNumber }).toArray();
+};
+
+export const getCallsByClient = (clientId: string) => {
+  return getCallsCollection().find({ clientId }).toArray();
+};
+
+export const getCallsByFlow = (flowId: ObjectId) => {
+  return getCallsCollection().find({ flowId }).toArray();
+};
+
+export const createCallDoc = (call: Omit<Call, 'createdAt' | 'updatedAt' | 'env'>) => {
+  return getCallsCollection().insertOne({
+    ...call,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    env: process.env.ENV ?? 'unknown',
+  });
+};
+
+export const updateCallByCallSid = async (
+  callSid: string,
+  updates: CallUpdateParams
+): Promise<CallDoc | null> => {
+  const result = await getCallsCollection().findOneAndUpdate(
+    { callSid: callSid },
+    {
+      $set: {
+        ...updates,
+        updatedAt: new Date(),
+      },
+    },
+    { returnDocument: 'after' }
+  );
+
+  return result;
+};
+
+/**
+ * Aggregate calls stats for a date range (createdAt in [startStr, endStr] in timezone).
+ * completed = agentHungUp=true or status='completed'.
+ */
+export async function getCallsStatsForDateRange(
+  clientId: string,
+  startStr: string,
+  endStr: string,
+  timezone: string
+): Promise<{ count: number; totalLen: number; completed: number }> {
+  const coll = getCallsCollection();
+  const out = await coll
+    .aggregate<{ _id: null; count: number; totalLen: number; completed: number }>([
+      // 1. Restrict to the given client
+      { $match: { clientId } },
+      // 2. Derive dateLocal (createdAt as YYYY-MM-DD in timezone) and isCompleted (agentHungUp or status='completed')
+      {
+        $addFields: {
+          dateLocal: {
+            $dateToString: { format: '%Y-%m-%d', date: '$createdAt', timezone },
+          },
+          isCompleted: {
+            $or: [{ $eq: ['$agentHungUp', true] }, { $eq: ['$status', 'completed'] }],
+          },
+        },
+      },
+      // 3. Keep only documents with dateLocal in [startStr, endStr] (inclusive)
+      { $match: { dateLocal: { $gte: startStr, $lte: endStr } } },
+      // 4. Single group: count, totalLen, completed
+      {
+        $group: {
+          _id: null,
+          count: { $sum: 1 },
+          totalLen: { $sum: '$callLength' },
+          completed: { $sum: { $cond: ['$isCompleted', 1, 0] } },
+        },
+      },
+    ])
+    .next();
+  return {
+    count: out?.count ?? 0,
+    totalLen: out?.totalLen ?? 0,
+    completed: out?.completed ?? 0,
+  };
+}
+
+/**
+ * Aggregate calls by hour for a given date (createdAt converted to given timezone). Hour format "HH:mm".
+ */
+export async function getCallsHourlyAggregation(
+  clientId: string,
+  dateStr: string,
+  timezone: string
+): Promise<CallsByHour[]> {
+  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: {
+            $dateToString: { format: '%Y-%m-%d', date: '$createdAt', timezone },
+          },
+          hour: { $hour: { date: '$createdAt', timezone } },
+        },
+      },
+      // 3. Keep only the requested date
+      { $match: { dateLocal: dateStr } },
+      // 4. Group by hour, sum calls per hour
+      { $group: { _id: '$hour', calls: { $sum: 1 } } },
+      // 5. Order by hour ascending (0..23)
+      { $sort: { _id: 1 } },
+    ])
+    .toArray();
+
+  return rows.map((r: any) => ({
+    hour: `${String(r._id).padStart(2, '0')}:00`,
+    calls: r.calls,
+  }));
+}