@talkpilot/core-db 1.1.18 → 1.2.0

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

@@ -1,282 +1,282 @@
-import { CityName, DepartmentSubject, getDb } from "../index";
-import { Collection, Filter } from "mongodb";
-import { 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";
-
-  return 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();
-};
-
-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);
-};
+import { CityName, DepartmentSubject, getDb } from "../index";
+import { Collection, Filter } from "mongodb";
+import { 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";
+
+  return 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();
+};
+
+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);
+};