@talkpilot/core-db 1.3.88 → 1.3.89

package/src/talkpilot/contextNotes/contextNotes.getters.ts

@@ -1,10 +1,6 @@
 import { Collection, ObjectId, WithId } from "mongodb";
 import { getDb } from "../index";
-import type {
-  ContextNote,
-  ContextNoteEntry,
-  ContextNoteEntryWrite,
-} from "./contextNotes.types";
+import type { ContextNote, ContextNoteEntry } from "./contextNotes.types";
 
 export const getContextNotesCollection = (): Collection<ContextNote> => {
   return getDb().collection<ContextNote>("contextNotes");
@@ -75,76 +71,6 @@ export const setContextNoteConfig = async (
   return result.matchedCount > 0;
 };
 
-const findNoteEntryById = (
-  doc: WithId<ContextNote> | null,
-  noteId: ObjectId,
-): ContextNoteEntry | null =>
-  doc?.notes.find((note) => note._id.equals(noteId)) ?? null;
-
-/** Appends one note. Other notes on the document are left untouched. */
-export const appendContextNoteEntry = async (
-  clientId: string,
-  product: string,
-  entry: ContextNoteEntryWrite,
-  now: Date = new Date(),
-): Promise<ContextNoteEntry> => {
-  const note: ContextNoteEntry = {
-    _id: new ObjectId(),
-    title: entry.title,
-    content: entry.content,
-    activeFrom: entry.activeFrom,
-    expiresAt: entry.expiresAt,
-    createdAt: now,
-    updatedAt: now,
-  };
-
-  const saved = await getContextNotesCollection().findOneAndUpdate(
-    { clientId, product },
-    { $push: { notes: note } },
-    { upsert: true, returnDocument: "after" },
-  );
-
-  return findNoteEntryById(saved, note._id) ?? note;
-};
-
-/** Replaces one note's fields. Other notes on the document are left untouched. */
-export const updateContextNoteEntryFields = async (
-  clientId: string,
-  product: string,
-  noteId: ObjectId,
-  entry: ContextNoteEntryWrite,
-  now: Date = new Date(),
-): Promise<ContextNoteEntry | null> => {
-  const saved = await getContextNotesCollection().findOneAndUpdate(
-    { clientId, product, "notes._id": noteId },
-    {
-      $set: {
-        "notes.$.title": entry.title,
-        "notes.$.content": entry.content,
-        "notes.$.activeFrom": entry.activeFrom,
-        "notes.$.expiresAt": entry.expiresAt,
-        "notes.$.updatedAt": now,
-      },
-    },
-    { returnDocument: "after" },
-  );
-
-  return findNoteEntryById(saved, noteId);
-};
-
-/** Removes one note by id. Other notes on the document are left untouched. */
-export const pullContextNoteEntry = async (
-  clientId: string,
-  product: string,
-  noteId: ObjectId,
-): Promise<boolean> => {
-  const result = await getContextNotesCollection().updateOne(
-    { clientId, product, "notes._id": noteId },
-    { $pull: { notes: { _id: noteId } } },
-  );
-  return result.modifiedCount > 0;
-};
-
 /** Removes a single note entry from a document by its _id. */
 export const deleteContextNoteEntry = async (
   id: ObjectId,

package/src/talkpilot/contextNotes/contextNotes.types.ts

@@ -10,13 +10,6 @@ export type ContextNoteEntry = {
   updatedAt: Date;
 };
 
-export type ContextNoteEntryWrite = {
-  title: string;
-  content: string;
-  activeFrom: Date;
-  expiresAt: Date | null;
-};
-
 export type ContextNote = {
   _id: ObjectId;
   clientId: string;

package/src/talkpilot/index.ts

@@ -2,6 +2,7 @@ import { Db, ObjectId as MongoObjectId } from "mongodb";
 
 export * from "./flows";
 export * from "./contextNotes";
+export * from "./auditLogs";
 export * from "./products";
 export * from "./results";
 export * from "./sessions";

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

@@ -7,6 +7,11 @@ import {
   createPhoneNumberEntity,
   createPurchasedPhoneNumber,
   getPrimaryPhoneFlowId,
+  getClientPhones,
+  findPhonesByClientIds,
+  getDistinctClientPhonePairs,
+  findClientsByPhoneNumbers,
+  deletePhoneNumberRecords,
   findPhoneNumbersByClientId,
   getOwnedPhoneNumber,
   getPhoneNumberByClientAndFlow,
@@ -20,7 +25,7 @@ import { ObjectId } from "mongodb";
 
 describe("db.phoneNumbers", () => {
   describe("getPhoneDataByPhoneNumber", () => {
-    it("return phone number data with flow", async () => {
+    it("should return phone number data with flow", async () => {
       const flow = createFlow({
         clientId: "test-client-id",
         conversationSettings: {
@@ -68,7 +73,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("getClientPhoneNumber", () => {
-    it("return phone number by client id", async () => {
+    it("should return phone number by client id", async () => {
       const flow = createFlow();
       const phoneData = createPhoneNumber({
         flow_id: flow._id,
@@ -84,7 +89,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("getClientPhoneData", () => {
-    it("returns primary phone data by default", async () => {
+    it("should return primary phone data by default", async () => {
       const clientId = "multiPhoneClient";
       const phone1 = createPhoneNumber({
         client_id: clientId,
@@ -106,7 +111,7 @@ describe("db.phoneNumbers", () => {
       expect(result?.phone_number).toBe("2");
     });
 
-    it("returns most recent non-primary phone data if isPrimary is false", async () => {
+    it("should return most recent non-primary phone data if isPrimary is false", async () => {
       const clientId = "multiPhoneClient2";
       const phone1 = createPhoneNumber({
         client_id: clientId,
@@ -137,7 +142,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("getPhoneNumbersForFlows", () => {
-    it("returns all phone numbers for the client with flow ObjectIds, newest first", async () => {
+    it("should return all phone numbers for the client with flow ObjectIds, newest first", async () => {
       const clientId = "flowsClient";
       const flow1 = createFlow({ clientId });
       const flow2 = createFlow({ clientId });
@@ -175,12 +180,12 @@ describe("db.phoneNumbers", () => {
       });
     });
 
-    it("returns an empty array when the client has no phone numbers", async () => {
+    it("should return 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 () => {
+    it("should not include phone numbers for other clients", async () => {
       const clientA = "clientA";
       const clientB = "clientB";
       const flow = createFlow();
@@ -197,7 +202,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("createPhoneNumberEntity", () => {
-    it("creates first phone number as primary", async () => {
+    it("should create first phone number as primary", async () => {
       const clientId = "newClient";
       const flowId = new ObjectId().toHexString();
       const phoneNumber = "+123456789";
@@ -211,7 +216,7 @@ describe("db.phoneNumbers", () => {
       expect(result.is_primary).toBe(true);
     });
 
-    it("creates subsequent phone number as non-primary", async () => {
+    it("should create subsequent phone number as non-primary", async () => {
       const clientId = "existingClient";
       const flowId = new ObjectId().toHexString();
 
@@ -226,7 +231,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("createPurchasedPhoneNumber", () => {
-    it("persists a phone_numbers document with provider payload and flow", async () => {
+    it("should persist a phone_numbers document with provider payload and flow", async () => {
       const clientId = "purchasedClientDb";
       const flowId = new ObjectId().toHexString();
       const phoneNumber = "+15551234567";
@@ -258,7 +263,7 @@ describe("db.phoneNumbers", () => {
   });
 
   describe("getPrimaryPhoneFlowId", () => {
-    it("returns flow_id from primary phone as string", async () => {
+    it("should return flow_id from primary phone as string", async () => {
       const clientId = "primaryFlowClient";
       const flowId = new ObjectId();
       await getPhoneNumbersCollection().insertOne(
@@ -272,11 +277,11 @@ describe("db.phoneNumbers", () => {
       expect(await getPrimaryPhoneFlowId(clientId)).toBe(flowId.toHexString());
     });
 
-    it("returns null when client has no primary phone", async () => {
+    it("should return null when client has no primary phone", async () => {
       expect(await getPrimaryPhoneFlowId("no-phone-client")).toBeNull();
     });
 
-    it("returns null when primary phone has no flow_id", async () => {
+    it("should return null when primary phone has no flow_id", async () => {
       const clientId = "phoneNoFlow";
       const phone = createPhoneNumber({
         client_id: clientId,
@@ -289,6 +294,272 @@ describe("db.phoneNumbers", () => {
     });
   });
 
+  describe("getClientPhones", () => {
+    it("should return all phone numbers for the given client, projected to phoneNumber only", async () => {
+      const clientId = "phonesClientA";
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: clientId, phone_number: "+100" }),
+        createPhoneNumber({ client_id: clientId, phone_number: "+200" }),
+      ]);
+
+      const result = await getClientPhones(clientId);
+
+      expect(result).toHaveLength(2);
+      expect(result).toEqual(
+        expect.arrayContaining([
+          { phoneNumber: "+100" },
+          { phoneNumber: "+200" },
+        ]),
+      );
+    });
+
+    it("should not include phone numbers belonging to other clients", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: "someOtherClient" }),
+      );
+
+      const result = await getClientPhones("phonesClientB");
+      expect(result).toEqual([]);
+    });
+
+    it("should remove exact duplicate phone records for the same client", async () => {
+      const clientId = "phonesClientDup";
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: clientId, phone_number: "+300" }),
+        createPhoneNumber({ client_id: clientId, phone_number: "+300" }),
+        createPhoneNumber({ client_id: clientId, phone_number: "+400" }),
+      ]);
+
+      const result = await getClientPhones(clientId);
+
+      expect(result).toHaveLength(2);
+      expect(result).toEqual(
+        expect.arrayContaining([
+          { phoneNumber: "+300" },
+          { phoneNumber: "+400" },
+        ]),
+      );
+    });
+  });
+
+  describe("findPhonesByClientIds", () => {
+    it("should return a Map of clientId to phone number for the requested clients only", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "mapClientA", phone_number: "+111" }),
+        createPhoneNumber({ client_id: "mapClientB", phone_number: "+222" }),
+        createPhoneNumber({ client_id: "mapClientC", phone_number: "+333" }),
+      ]);
+
+      const result = await findPhonesByClientIds(["mapClientA", "mapClientB"]);
+
+      expect(result).toBeInstanceOf(Map);
+      expect(result.get("mapClientA")).toBe("+111");
+      expect(result.get("mapClientB")).toBe("+222");
+      expect(result.has("mapClientC")).toBe(false);
+    });
+
+    it("should return an empty Map for an empty list of clients", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: "mapClientA", phone_number: "+111" }),
+      );
+
+      const result = await findPhonesByClientIds([]);
+
+      expect(result.size).toBe(0);
+    });
+
+    it("should skip clients that have no phone number", async () => {
+      const result = await findPhonesByClientIds(["clientWithoutPhone"]);
+      expect(result.size).toBe(0);
+    });
+
+    it("should return the most recently updated phone number when a client has several", async () => {
+      const clientId = "mapClientRecent";
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+old",
+          updatedAt: new Date("2023-01-01"),
+        }),
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+new",
+          updatedAt: new Date("2023-06-01"),
+        }),
+      ]);
+
+      const result = await findPhonesByClientIds([clientId]);
+
+      expect(result.get(clientId)).toBe("+new");
+    });
+
+    it("should prefer the is_primary number over a more recently updated non-primary one", async () => {
+      const clientId = "mapClientPrimary";
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+primary",
+          is_primary: true,
+          updatedAt: new Date("2023-01-01"),
+        }),
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+secondary",
+          is_primary: false,
+          updatedAt: new Date("2023-06-01"),
+        }),
+      ]);
+
+      const result = await findPhonesByClientIds([clientId]);
+
+      expect(result.get(clientId)).toBe("+primary");
+    });
+  });
+
+  describe("getDistinctClientPhonePairs", () => {
+    it("should return unique client+phone pairs, collapsing exact duplicates", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "pairClientA", phone_number: "+500" }),
+        createPhoneNumber({ client_id: "pairClientA", phone_number: "+500" }),
+        createPhoneNumber({ client_id: "pairClientB", phone_number: "+600" }),
+      ]);
+
+      const result = await getDistinctClientPhonePairs();
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          { clientId: "pairClientA", phoneNumber: "+500", isPrimary: true },
+          { clientId: "pairClientB", phoneNumber: "+600", isPrimary: true },
+        ]),
+      );
+      expect(
+        result.filter(
+          (p) => p.clientId === "pairClientA" && p.phoneNumber === "+500",
+        ),
+      ).toHaveLength(1);
+    });
+
+    it("should keep separate pairs when the same number is shared by different clients", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "sharedClientA", phone_number: "+700" }),
+        createPhoneNumber({ client_id: "sharedClientB", phone_number: "+700" }),
+      ]);
+
+      const result = await getDistinctClientPhonePairs();
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          { clientId: "sharedClientA", phoneNumber: "+700", isPrimary: true },
+          { clientId: "sharedClientB", phoneNumber: "+700", isPrimary: true },
+        ]),
+      );
+    });
+
+    it("should report isPrimary: false for a non-primary number", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "mixedClient", phone_number: "+900", is_primary: true }),
+        createPhoneNumber({ client_id: "mixedClient", phone_number: "+901", is_primary: false }),
+      ]);
+
+      const result = await getDistinctClientPhonePairs();
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          { clientId: "mixedClient", phoneNumber: "+900", isPrimary: true },
+          { clientId: "mixedClient", phoneNumber: "+901", isPrimary: false },
+        ]),
+      );
+    });
+
+    it("should report isPrimary: false when no phone_numbers document for that client is marked primary", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: "noPrimaryClient", phone_number: "+902", is_primary: false }),
+      );
+
+      const result = await getDistinctClientPhonePairs();
+
+      expect(result).toContainEqual({
+        clientId: "noPrimaryClient",
+        phoneNumber: "+902",
+        isPrimary: false,
+      });
+    });
+  });
+
+  describe("getDistinctClientPhonePairs with clientIds", () => {
+    it("should return only the pairs of the given clients", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "wantedPairClient", phone_number: "+111" }),
+        createPhoneNumber({ client_id: "otherPairClient", phone_number: "+222" }),
+      ]);
+
+      const result = await getDistinctClientPhonePairs(["wantedPairClient"]);
+
+      expect(result).toEqual([
+        { clientId: "wantedPairClient", phoneNumber: "+111", isPrimary: true },
+      ]);
+    });
+  });
+
+  describe("findClientsByPhoneNumbers", () => {
+    it("should return other clients sharing each phone number, excluding the given client", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "excludeMe", phone_number: "+800" }),
+        createPhoneNumber({ client_id: "otherClient1", phone_number: "+800" }),
+        createPhoneNumber({ client_id: "otherClient2", phone_number: "+800" }),
+      ]);
+
+      const result = await findClientsByPhoneNumbers(["+800"], "excludeMe");
+
+      expect(result.get("+800")).toEqual(
+        expect.arrayContaining(["otherClient1", "otherClient2"]),
+      );
+      expect(result.get("+800")).not.toContain("excludeMe");
+    });
+
+    it("should return an empty array for a phone number with no other clients", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: "soleOwner", phone_number: "+900" }),
+      );
+
+      const result = await findClientsByPhoneNumbers(["+900"], "soleOwner");
+
+      expect(result.get("+900")).toEqual([]);
+    });
+
+    it("should return an empty map immediately when given no phone numbers", async () => {
+      const result = await findClientsByPhoneNumbers([]);
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe("deletePhoneNumberRecords", () => {
+    it("should delete every record for the given phone number across all clients", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "delClientA", phone_number: "+1000" }),
+        createPhoneNumber({ client_id: "delClientB", phone_number: "+1000" }),
+        createPhoneNumber({ client_id: "delClientC", phone_number: "+2000" }),
+      ]);
+
+      const deletedCount = await deletePhoneNumberRecords("+1000");
+
+      expect(deletedCount).toBe(2);
+      const remaining = await getPhoneNumbersCollection()
+        .find({ phone_number: "+1000" })
+        .toArray();
+      expect(remaining).toHaveLength(0);
+      const untouched = await getPhoneNumbersCollection().findOne({
+        phone_number: "+2000",
+      });
+      expect(untouched?.client_id).toBe("delClientC");
+    });
+
+    it("should return 0 when no records match the phone number", async () => {
+      const deletedCount = await deletePhoneNumberRecords("+9999999");
+      expect(deletedCount).toBe(0);
+    });
+  });
+
   describe("findPhoneNumbersByClientId", () => {
     it("returns only that client's numbers", async () => {
       const clientId = "list-client";

package/src/talkpilot/phone_numbers/phone_numbers.getter.ts

@@ -9,6 +9,7 @@ import {
 } from "../index";
 import {
   ClientPhoneNumberForFlow,
+  ClientPhonePair,
   PhoneNumber,
   PhoneNumberWithFlow,
   PurchasedPhoneProviderPayload,
@@ -158,7 +159,9 @@ export const findClientByPhoneNumber = async (
   return client;
 };
 
-export const getPrimaryPhoneFlowId = async (clientId: string): Promise<string | null> => {
+export const getPrimaryPhoneFlowId = async (
+  clientId: string,
+): Promise<string | null> => {
   const phone = await getClientPhoneData(clientId);
   return phone?.flow_id ? String(phone.flow_id) : null;
 };
@@ -176,6 +179,91 @@ export const bindClientPhoneToFlow = async (
   }
 };
 
+export const getClientPhones = async (
+  clientId: string,
+): Promise<{ phoneNumber: string }[]> => {
+  const docs = await getPhoneNumbersCollection()
+    .aggregate<{ _id: string }>([
+      { $match: { client_id: clientId } },
+      { $group: { _id: "$phone_number" } },
+    ])
+    .toArray();
+  return docs.map((d) => ({ phoneNumber: d._id }));
+};
+
+export const findPhonesByClientIds = async (
+  clientIds: string[],
+): Promise<Map<string, string>> => {
+  if (clientIds.length === 0) return new Map();
+
+  const docs = await getPhoneNumbersCollection()
+    .aggregate<{ _id: string; phone_number: string }>([
+      { $match: { client_id: { $in: clientIds } } },
+      { $sort: { is_primary: -1, updatedAt: -1 } },
+      { $group: { _id: "$client_id", phone_number: { $first: "$phone_number" } } },
+    ])
+    .toArray();
+  return new Map(docs.map((d) => [d._id, d.phone_number]));
+};
+
+export const getDistinctClientPhonePairs = async (
+  clientIds?: string[],
+): Promise<ClientPhonePair[]> => {
+  const docs = await getPhoneNumbersCollection()
+    .aggregate<{
+      _id: { client_id: string; phone_number: string };
+      isPrimary: boolean;
+    }>([
+      ...(clientIds ? [{ $match: { client_id: { $in: clientIds } } }] : []),
+      {
+        $group: {
+          _id: { client_id: "$client_id", phone_number: "$phone_number" },
+          isPrimary: { $max: "$is_primary" },
+        },
+      },
+    ])
+    .toArray();
+  return docs.map((d) => ({
+    clientId: d._id.client_id,
+    phoneNumber: d._id.phone_number,
+    isPrimary: Boolean(d.isPrimary),
+  }));
+};
+
+export const findClientsByPhoneNumbers = async (
+  phoneNumbers: string[],
+  excludeClientId?: string,
+): Promise<Map<string, string[]>> => {
+  const result = new Map<string, string[]>(
+    phoneNumbers.map((p) => [p, [] as string[]]),
+  );
+  if (phoneNumbers.length === 0) return result;
+
+  const docs = await getPhoneNumbersCollection()
+    .aggregate<{ _id: string; clientIds: string[] }>([
+      {
+        $match: {
+          phone_number: { $in: phoneNumbers },
+          ...(excludeClientId ? { client_id: { $ne: excludeClientId } } : {}),
+        },
+      },
+      { $group: { _id: "$phone_number", clientIds: { $addToSet: "$client_id" } } },
+    ])
+    .toArray();
+
+  docs.forEach((d) => result.set(d._id, d.clientIds));
+  return result;
+};
+
+/** Deletes this number's record for every client that references it. Check `findClientsByPhoneNumbers` first to see who's affected. */
+export const deletePhoneNumberRecords = async (
+  phoneNumber: string,
+): Promise<number> => {
+  const result = await getPhoneNumbersCollection().deleteMany({
+    phone_number: phoneNumber,
+  });
+  return result.deletedCount;
+};
 export const findPhoneNumbersByClientId = (
   clientId: string,
 ): Promise<PhoneNumber[]> =>

package/src/talkpilot/phone_numbers/phone_numbers.types.ts

@@ -28,3 +28,9 @@ export type ClientPhoneNumberForFlow = {
   phoneNumber: string;
   isPrimary: boolean;
 };
+
+export type ClientPhonePair = {
+  clientId: string;
+  phoneNumber: string;
+  isPrimary: boolean;
+};

package/src/test-utils/factories/index.ts

@@ -1,4 +1,5 @@
 export * from "./talkpilot/agents";
+export * from "./talkpilot/clients";
 export * from "./talkpilot/calls";
 export * from "./talkpilot/clientAudioBuffers";
 export * from "./talkpilot/clientsConfig";
@@ -7,6 +8,7 @@ export * from "./talkpilot/contextNotes";
 export * from "./talkpilot/groups";
 export * from "./talkpilot/phone_numbers";
 export * from "./talkpilot/sessions";
+export * from "./talkpilot/results";
 export * from "./municipal/cities";
 export * from "./municipal/departmentsSubjects";
 export * from "./municipal/muniIssues";

package/src/test-utils/factories/talkpilot/clients.ts

@@ -0,0 +1,21 @@
+import { Factory } from "fishery";
+import { ObjectId } from "mongodb";
+import { faker } from "@faker-js/faker";
+import type { Client } from "../../../talkpilot";
+
+export const clientFactory = Factory.define<Client & { _id?: ObjectId }>(
+  () => ({
+    _id: new ObjectId(),
+    clientId: faker.string.uuid(),
+    isActive: true,
+    credits: faker.number.int({ min: 0, max: 1000 }),
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }),
+);
+
+export function createClient(
+  overrides?: Partial<Client>,
+): Client & { _id?: ObjectId } {
+  return clientFactory.build(overrides);
+}