@talkpilot/core-db 1.0.1

package/src/municipal/departmentsSubjects/departmentsSubjects.getters.ts

@@ -0,0 +1,273 @@
+import { getDb, DepartmentSubject } from '../index';
+import { Collection, Filter } from 'mongodb';
+import { CityName, VectorSearchResult } from './departmentsSubjects.types';
+
+export const getDepartmentsSubjectsCollection = (): Collection<DepartmentSubject> => {
+  return getDb().collection<DepartmentSubject>('departmentsSubjects');
+};
+
+/**
+ * Get all departments subjects for a given city.
+ * No DB sort; tree build does not depend on order. Callers that need alphabetical order
+ * sort in memory (e.g. sortTreeAlphabetically in full-tree-subjects.service).
+ * @param cityName - City name to filter subjects
+ * @param withEmbeddings - Whether to include embedding and embedding_model fields (default: false)
+ * @returns Array of all department subjects for the city
+ */
+export const getAllDepartmentsSubjectsByCity = async (
+  cityName: CityName,
+  withEmbeddings: boolean = false
+): Promise<DepartmentSubject[]> => {
+  const collection = getDepartmentsSubjectsCollection();
+  const query = collection.find({ cityName });
+
+  if (!withEmbeddings) {
+    return (await query
+      .project({ embedding: 0, embedding_model: 0 })
+      .toArray()) as DepartmentSubject[];
+  }
+
+  return await query.toArray();
+};
+
+/**
+ * Perform vector search on departmentsSubjects collection
+ * @param queryVector - The embedding vector to search with
+ * @param cityName - City name to filter results
+ * @param limit - Maximum number of results (default: 5)
+ * @param numCandidates - Number of candidates to consider (default: 800)
+ * @returns Array of vector search results
+ */
+export const vectorSearchDepartmentsSubjects = async (
+  queryVector: number[],
+  cityName: CityName,
+  limit: number = 5,
+  numCandidates: number = 800
+): Promise<VectorSearchResult[]> => {
+  const collection = getDepartmentsSubjectsCollection();
+  const indexName = 'subjectTreesIndex';
+
+  const results = await collection
+    .aggregate<VectorSearchResult>([
+      {
+        $vectorSearch: {
+          index: indexName,
+          path: 'embedding',
+          queryVector,
+          numCandidates,
+          limit,
+          filter: { cityName },
+        },
+      },
+      {
+        $project: {
+          _id: 0,
+          subjectName: 1,
+          subject_id: { $toInt: '$subject_id' }, // Convert string to number
+          sub_subject_name: 1,
+          sub_subject_id: 1,
+          descriptions: 1,
+          guidelines: 1,
+          score: { $meta: 'vectorSearchScore' },
+        },
+      },
+    ])
+    .toArray();
+
+  return results;
+};
+
+export const addDepartmentSubjectInstruction = async (
+  filter: Filter<DepartmentSubject>,
+  instructionText: string
+): Promise<DepartmentSubject | null> => {
+  const newInstruction = {
+    id: Date.now(),
+    instruction: instructionText,
+  };
+
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    {
+      $push: { instructions: newInstruction },
+      $set: { updatedAt: new Date() },
+    },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+export const updateDepartmentSubjectInstruction = async (
+  filter: Filter<DepartmentSubject>,
+  instructionId: number,
+  newInstructionText: string
+): Promise<DepartmentSubject | null> => {
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    { ...filter, 'instructions.id': instructionId },
+    { $set: { 'instructions.$.instruction': newInstructionText, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+export const removeDepartmentSubjectInstruction = async (
+  filter: Filter<DepartmentSubject>,
+  instructionId: number
+): Promise<DepartmentSubject | null> => {
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    {
+      $pull: { instructions: { id: instructionId } },
+      $set: { updatedAt: new Date() },
+    },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+export const addDepartmentSubjectCommunication = async (
+  filter: Filter<DepartmentSubject>,
+  communication: {
+    type: 'free_text_sms' | 'upload_url_sms';
+    message_text?: string;
+    template_id?: string;
+    to?: string;
+  }
+): Promise<DepartmentSubject | null> => {
+  const newCommunication = {
+    id: Date.now(),
+    type: communication.type,
+    ...(communication.message_text !== undefined && { message_text: communication.message_text }),
+    is_deleted: false,
+    ...(communication.template_id !== undefined && { template_id: communication.template_id }),
+    ...(communication.to !== undefined && { to: communication.to }),
+  };
+
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    {
+      $push: { communications: newCommunication },
+      $set: { updatedAt: new Date() },
+    },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+export const updateDepartmentSubjectCommunication = async (
+  filter: Filter<DepartmentSubject>,
+  communicationId: number,
+  updates: {
+    type?: 'free_text_sms' | 'upload_url_sms';
+    message_text?: string | null;
+    template_id?: string | null;
+    to?: string | null;
+    is_deleted?: boolean | null;
+  }
+): Promise<DepartmentSubject | null> => {
+  const setFields: Record<string, unknown> = { updatedAt: new Date() };
+  if (updates.type !== undefined) setFields['communications.$.type'] = updates.type;
+  if (updates.message_text !== undefined)
+    setFields['communications.$.message_text'] = updates.message_text;
+  if (updates.template_id !== undefined)
+    setFields['communications.$.template_id'] = updates.template_id;
+  if (updates.to !== undefined) setFields['communications.$.to'] = updates.to;
+  if (updates.is_deleted !== undefined)
+    setFields['communications.$.is_deleted'] = updates.is_deleted;
+
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    { ...filter, 'communications.id': communicationId },
+    { $set: setFields },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+export const removeDepartmentSubjectCommunication = async (
+  filter: Filter<DepartmentSubject>,
+  communicationId: number
+): Promise<DepartmentSubject | null> => {
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    {
+      $pull: { communications: { id: communicationId } },
+      $set: { updatedAt: new Date() },
+    },
+    { returnDocument: 'after' }
+  );
+
+  return result || null;
+};
+
+/**
+ * Get department subject by subject_id, sub_subject_id, and cityName
+ * @param subjectId - Subject ID (from event_subject_id)
+ * @param subSubjectId - Sub-subject ID (from event_sub_subject_id, optional)
+ * @param cityName - City name to filter results
+ * @returns DepartmentSubject document or null if not found
+ */
+export const getDepartmentSubjectBySubjectIds = async (
+  subjectId: string,
+  subSubjectId: string,
+  cityName: CityName
+): Promise<DepartmentSubject | null> => {
+  const collection = getDepartmentsSubjectsCollection();
+
+  const filter: Filter<DepartmentSubject> = {
+    subject_id: subjectId,
+    cityName,
+  };
+
+  if (subSubjectId) {
+    filter.sub_subject_id = subSubjectId;
+  }
+
+  const result = await collection.findOne(filter);
+
+  return result || null;
+};
+
+/**
+ * Update or create guidelines field for a department subject
+ * @param filter - MongoDB filter to find the document
+ * @param guidelines - Guidelines text to set
+ * @returns Updated DepartmentSubject document or null if not found
+ */
+export const updateDepartmentSubjectGuidelines = async (
+  filter: Filter<DepartmentSubject>,
+  guidelines: string
+): Promise<DepartmentSubject | null> => {
+  // $set will create the field if it doesn't exist
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    { $set: { guidelines, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+  return result || null;
+};
+
+/**
+ * Clear guidelines field from a department subject document (sets it to null)
+ * @param filter - MongoDB filter to find the document
+ * @returns Updated DepartmentSubject document or null if not found
+ */
+export const deleteDepartmentSubjectGuidelines = async (
+  filter: Filter<DepartmentSubject>
+): Promise<DepartmentSubject | null> => {
+  // $set clears the field by setting it to null (keeps the field in the document)
+  const result = await getDepartmentsSubjectsCollection().findOneAndUpdate(
+    filter,
+    { $set: { guidelines: null, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+  return result || null;
+};
+
+export const findSubjectByQuery = async (query: Partial<DepartmentSubject>) => {
+  return await getDepartmentsSubjectsCollection().findOne(query);
+};

package/src/municipal/departmentsSubjects/departmentsSubjects.types.ts

@@ -0,0 +1,76 @@
+import { ObjectId, WithId } from 'mongodb';
+import { Request } from 'express';
+import { ClientConfigDoc, Products } from '../../talkpilot/clientsConfig/clientsConfig.types';
+
+export type DepartmentSubject = {
+  _id: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+  subjectName: string; // e.g. "אחזקה- איטום"
+  subject_id: string; // e.g. "6121"
+  sub_subject_name: string; // e.g. "איטום"
+  sub_subject_id: string; // e.g. "6123"
+  sub_subject_name2?: string; // e.g. "ניקיון באגם" (level 3 - grandchild)
+  sub_subject_id2?: string; // e.g. "2898" (level 3 - grandchild)
+  descriptions: string[]; // array of guideline / example descriptions
+  embedding_text?: string; // the text used to create the embedding
+  embedding?: number[]; // length should match embedding_dims (e.g. 1536)
+  embedding_model?: string; // e.g. "text-embedding-3-small"
+  embedding_dims?: number; // e.g. 1536
+  cityName: CityName;
+  guidelines?: string | null;
+  instructions?: Instruction[];
+  communications?: Communication[];
+  sla?: number;
+};
+
+export interface Instruction {
+  id: number;
+  instruction: string;
+}
+
+export interface Communication {
+  id: number;
+  type: CommunicationType;
+  message_text?: string;
+  template_id?: string;
+  to?: string;
+  is_deleted?: boolean;
+}
+
+export type DepartmentSubjectDoc = WithId<DepartmentSubject>;
+
+/**
+ * Vector search result from MongoDB
+ */
+export type VectorSearchResult = {
+  subjectName: string;
+  subject_id: number;
+  sub_subject_id: string;
+  sub_subject_id2?: string | null;
+  sub_subject_name: string;
+  sub_subject_name2?: string | null;
+  descriptions?: string[];
+  guidelines?: string | null;
+  instructions?: string | null;
+  score?: number;
+};
+
+/**
+ * City name type for municipal data
+ */
+// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+export type CityName = 'ashdod' | 'maltar' | 'billit' | 'hashkelon' | 'eilat' | 'tests' | string;
+export type CommunicationType = 'free_text_sms' | 'upload_url_sms';
+
+/**
+ * Extended Express Request type with client configuration
+ */
+export type RequestWithClientConfig = Request & {
+  uid: string;
+  clientConfig: ClientConfigDoc<Products>;
+  isGuest: boolean;
+  claims: Record<string, unknown>;
+  crmName?: string;
+  callSid?: string;
+};

package/src/municipal/departmentsSubjects/index.ts

@@ -0,0 +1,11 @@
+export * from './departmentsSubjects.getters';
+export type {
+  DepartmentSubject,
+  DepartmentSubjectDoc,
+  VectorSearchResult,
+  CityName,
+  RequestWithClientConfig,
+  Communication,
+  Instruction,
+} from './departmentsSubjects.types';
+

package/src/municipal/index.ts

@@ -0,0 +1,18 @@
+import { Db, ObjectId as MongoObjectId } from 'mongodb';
+
+export * from './cities';
+export * from './streets';
+export * from './departmentsSubjects';
+export * from './tickets';
+export { municipalDataMongodbClient } from './mongodb-client';
+
+let db: Db;
+export const setDb = (d: Db) => {
+  db = d;
+};
+export const getDb = (): Db => {
+  if (!db) throw new Error('Municipal Data DB not initialised');
+  return db;
+};
+
+export const ObjectId = MongoObjectId;

package/src/municipal/mongodb-client.ts

@@ -0,0 +1,58 @@
+import { MongoClient, Db } from 'mongodb';
+import { setDb } from './index';
+import { validateConfig, validateMongoUri } from '../utils/validation';
+
+class MunicipalDataMongoDBClient {
+  private client: MongoClient | null = null;
+  private db: Db | null = null;
+  private readonly defaultDbName = 'municipal-data';
+
+  async connect(uri?: string, dbName?: string): Promise<void> {
+    if (this.client) {
+      return;
+    }
+
+    const mongodbUri = uri || process.env.MONGO_URI || process.env.MONGODB_URI;
+    validateConfig('MONGO_URI', mongodbUri);
+    validateMongoUri(mongodbUri!);
+
+    try {
+      this.client = new MongoClient(mongodbUri!);
+      await this.client.connect();
+      const targetDbName = dbName || this.defaultDbName;
+      this.db = this.client.db(targetDbName);
+      setDb(this.db);
+      console.info(`[core-db] Municipal MongoDB connected: ${targetDbName}`);
+    } catch (error) {
+      console.error('[core-db] Municipal connection failed', error as Error);
+      throw error;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      try {
+        await this.client.close();
+        this.client = null;
+        this.db = null;
+        console.info('Municipal Data MongoDB disconnected successfully');
+      } catch (error) {
+        console.error('Error disconnecting from Municipal Data MongoDB', error as Error);
+        throw error;
+      }
+    }
+  }
+
+  getDb(): Db {
+    if (!this.db) {
+      throw new Error('Municipal Data database not initialized. Call connect() first.');
+    }
+    return this.db;
+  }
+
+  isConnected(): boolean {
+    return this.client !== null && this.client !== undefined;
+  }
+}
+
+export const municipalDataMongodbClient = new MunicipalDataMongoDBClient();

package/src/municipal/streets/index.ts

@@ -0,0 +1,2 @@
+export * from './streets.getters';
+export type { Street, StreetDoc, StreetHint } from './streets.types';

package/src/municipal/streets/streets.getters.ts

@@ -0,0 +1,105 @@
+import { CityName, getDb, ObjectId, Street } from '../index';
+import type { StreetHint } from './streets.types';
+import { Collection, Filter, ObjectId as MongoObjectId } from 'mongodb';
+
+export const getStreetsCollection = (): Collection<Street> => {
+  return getDb().collection<Street>('streets');
+};
+
+export const findStreets = async (filter: Filter<Street> = {}): Promise<Street[]> => {
+  return await getStreetsCollection().find(filter).toArray();
+};
+
+export const getStreetById = async (streetId: string): Promise<Street | null> => {
+  const street = await getStreetsCollection().findOne({ _id: new ObjectId(streetId) });
+  return street ? street : null;
+};
+
+export const getStreetsByCityName = async (cityName: CityName): Promise<Street[]> => {
+  return await getStreetsCollection().find({ cityName }).sort({ name: 1 }).toArray();
+};
+
+export const getStreetByStreetId = async (streetId: string): Promise<Street | null> => {
+  const street = await getStreetsCollection().findOne({ id: streetId });
+  return street ? street : null;
+};
+
+/** Get street by business id and city. Use this when the client's city is known so the same id in another city is not returned. */
+export const getStreetByStreetIdAndCity = async (
+  streetId: string,
+  cityName: CityName
+): Promise<Street | null> => {
+  const street = await getStreetsCollection().findOne({ id: streetId, cityName });
+  return street ? street : null;
+};
+
+export const createStreet = async (
+  streetData: Omit<Street, '_id' | 'createdAt' | 'updatedAt'>
+): Promise<MongoObjectId> => {
+  const street: Omit<Street, '_id'> = {
+    ...streetData,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+  const { insertedId } = await getStreetsCollection().insertOne(street as Street);
+  return insertedId;
+};
+
+export const updateStreet = async (
+  streetId: string,
+  data: Partial<Omit<Street, '_id' | 'createdAt' | 'updatedAt'>>
+): Promise<Street | null> => {
+  const result = await getStreetsCollection().findOneAndUpdate(
+    { _id: new ObjectId(streetId) },
+    { $set: { ...data, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+  return result || null;
+};
+
+/**
+ * Add or update a street hint on an already-fetched street.
+ * Only place that creates a new hint id (Date.getTime().toString()). Returns null if hint.id provided but not found, or text empty.
+ */
+export const upsertStreetHintOnStreet = async (
+  street: Street,
+  hint: Partial<StreetHint> & Pick<StreetHint, 'text'>
+): Promise<Street | null> => {
+  const text = hint.text.trim();
+  if (!text) return null;
+
+  const hints = street.hints || [];
+  let updatedHints: StreetHint[];
+
+  if (hint.id != null && hint.id !== '') {
+    const hintIndex = hints.findIndex((h) => String(h.id) === String(hint.id));
+    if (hintIndex === -1) return null;
+    updatedHints = [...hints];
+    updatedHints[hintIndex] = { id: String(hint.id), text };
+  } else {
+    updatedHints = [...hints, { id: new Date().getTime().toString(), text }];
+  }
+
+  return updateStreet(street._id.toString(), { hints: updatedHints });
+};
+
+/** Remove a hint from a street. streetId is the street business id (e.g. "703"). Updates document updatedAt. */
+export const deleteStreetHint = async (
+  streetId: string,
+  hintId: string
+): Promise<Street | null> => {
+  const result = await getStreetsCollection().findOneAndUpdate(
+    { id: streetId },
+    { $pull: { hints: { id: hintId } }, $set: { updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+  if (result) {
+    console.info('Street hint deleted', { streetId, hintId });
+  }
+  return result || null;
+};
+
+export const deleteStreet = async (streetId: string): Promise<boolean> => {
+  const result = await getStreetsCollection().deleteOne({ _id: new ObjectId(streetId) });
+  return result.deletedCount > 0;
+};

package/src/municipal/streets/streets.types.ts

@@ -0,0 +1,18 @@
+import { ObjectId, WithId } from 'mongodb';
+
+export type StreetHint = {
+  id: string;
+  text: string;
+};
+
+export type Street = {
+  _id: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+  id: string;
+  name: string;
+  cityName: string;
+  hints?: StreetHint[];
+};
+
+export type StreetDoc = WithId<Street>;

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

@@ -0,0 +1,30 @@
+import { findTicketsByCallSid } from '../tickets.getters';
+import { setDb } from '../../index';
+import { Db, Collection } from 'mongodb';
+import { createTicket } from '../../../test-utils/factories';
+
+describe('tickets getters', () => {
+  let mockDb: Partial<Db>;
+  let mockCollection: Partial<Collection>;
+
+  beforeEach(() => {
+    const mockTicket = createTicket({ callSid: '123' });
+    mockCollection = {
+      find: jest.fn().mockReturnValue({
+        toArray: jest.fn().mockResolvedValue([mockTicket]),
+      }),
+    };
+    mockDb = {
+      collection: jest.fn().mockReturnValue(mockCollection),
+    };
+    setDb(mockDb as Db);
+  });
+
+  it('findTicketsByCallSid should return tickets for the given callSid', async () => {
+    const result = await findTicketsByCallSid('123');
+    
+    expect(mockDb.collection).toHaveBeenCalledWith('tickets');
+    expect(mockCollection.find).toHaveBeenCalledWith({ callSid: '123' });
+    expect(result[0].callSid).toBe('123');
+  });
+});

package/src/municipal/tickets/index.ts

@@ -0,0 +1,2 @@
+export * from './tickets.getters';
+export type { Ticket, TicketDoc, SubjectStatsItem } from './tickets.types';