@talkpilot/core-db 1.3.50 → 1.3.52

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

@@ -1,282 +1,496 @@
-import {
-  getPhoneDataByPhoneNumber,
-  getPhoneNumbersCollection,
-  getPhoneNumbersForFlows,
-  getClientPhoneNumber,
-  getClientPhoneData,
-  createPhoneNumberEntity,
-  createPurchasedPhoneNumber,
-  getPrimaryPhoneFlowId,
-} from "../phone_numbers.getter";
-import { getFlowsCollection } from "../../flows/flows.getter";
-import { createFlow, createPhoneNumber } from "../../../test-utils/factories";
-import { ObjectId } from "mongodb";
-
-describe("db.phoneNumbers", () => {
-  describe("getPhoneDataByPhoneNumber", () => {
-    it("return phone number data with flow", async () => {
-      const flow = createFlow({
-        clientId: "test-client-id",
-        conversationSettings: {
-          interruptions: {
-            enableInterruptionDetection: true,
-            interruptionWindowSeconds: 60,
-            interruptionThresholdSeconds: 10,
-            interruptionInstruction:
-              "I am hearing background noise that makes it hard for me to focus on what you are saying. Please try to move to a quieter place or reduce the noise so I can better assist you.",
-          },
-          silence: {
-            enableSilenceDetection: true,
-            firstWarningSilenceSeconds: 5,
-            firstWarningInstruction:
-              "I have not heard you for a few seconds. If you are still on the line, please say something so we can continue.",
-            secondWarningSilenceSeconds: 10,
-            secondWarningInstruction:
-              "I still have not heard anything from you. If you do not respond in the next few seconds, I will have to end this call.",
-            disconnectSilenceSeconds: 30,
-          },
-        },
-      });
-      const phoneData = createPhoneNumber({
-        flow_id: flow._id,
-        client_id: "test-client-id",
-      });
-
-      await getFlowsCollection().insertOne(flow);
-      await getPhoneNumbersCollection().insertOne(phoneData);
-
-      const result = await getPhoneDataByPhoneNumber(phoneData.phone_number);
-
-      expect(result).toBeDefined();
-      expect(result).toMatchObject({
-        client_id: phoneData.client_id,
-        phone_number: phoneData.phone_number,
-        flow_id: flow._id,
-      });
-      // Specifically check if the flow was joined correctly
-      expect(result?.flow.flowName).toBe(flow.flowName);
-      expect(
-        result?.flow.conversationSettings?.silence?.firstWarningSilenceSeconds,
-      ).toBe(5);
-    });
-  });
-
-  describe("getClientPhoneNumber", () => {
-    it("return phone number by client id", async () => {
-      const flow = createFlow();
-      const phoneData = createPhoneNumber({
-        flow_id: flow._id,
-        is_primary: true,
-      });
-
-      await getFlowsCollection().insertOne(flow);
-      await getPhoneNumbersCollection().insertOne(phoneData);
-
-      const result = await getClientPhoneNumber(phoneData.client_id);
-      expect(result).toBe(phoneData.phone_number);
-    });
-  });
-
-  describe("getClientPhoneData", () => {
-    it("returns primary phone data by default", async () => {
-      const clientId = "multiPhoneClient";
-      const phone1 = createPhoneNumber({
-        client_id: clientId,
-        is_primary: false,
-        phone_number: "1",
-        createdAt: new Date("2023-01-01"),
-      });
-      const phone2 = createPhoneNumber({
-        client_id: clientId,
-        is_primary: true,
-        phone_number: "2",
-        createdAt: new Date("2023-01-02"),
-      });
-
-      await getPhoneNumbersCollection().insertOne(phone1);
-      await getPhoneNumbersCollection().insertOne(phone2);
-
-      const result = await getClientPhoneData(clientId);
-      expect(result?.phone_number).toBe("2");
-    });
-
-    it("returns most recent non-primary phone data if isPrimary is false", async () => {
-      const clientId = "multiPhoneClient2";
-      const phone1 = createPhoneNumber({
-        client_id: clientId,
-        is_primary: false,
-        phone_number: "1",
-        createdAt: new Date("2023-01-01"),
-      });
-      const phone2 = createPhoneNumber({
-        client_id: clientId,
-        is_primary: false,
-        phone_number: "2",
-        createdAt: new Date("2023-01-02"),
-      });
-      const phone3 = createPhoneNumber({
-        client_id: clientId,
-        is_primary: true,
-        phone_number: "3",
-        createdAt: new Date("2023-01-03"),
-      });
-
-      await getPhoneNumbersCollection().insertOne(phone1);
-      await getPhoneNumbersCollection().insertOne(phone2);
-      await getPhoneNumbersCollection().insertOne(phone3);
-
-      const result = await getClientPhoneData(clientId, false);
-      expect(result?.phone_number).toBe("2");
-    });
-  });
-
-  describe("getPhoneNumbersForFlows", () => {
-    it("returns all phone numbers for the client with flow ObjectIds, newest first", async () => {
-      const clientId = "flowsClient";
-      const flow1 = createFlow({ clientId });
-      const flow2 = createFlow({ clientId });
-      await getFlowsCollection().insertMany([flow1, flow2]);
-
-      const older = createPhoneNumber({
-        client_id: clientId,
-        flow_id: flow1._id,
-        phone_number: "+100",
-        is_primary: true,
-        createdAt: new Date("2023-01-01"),
-      });
-      const newer = createPhoneNumber({
-        client_id: clientId,
-        flow_id: flow2._id,
-        phone_number: "+200",
-        is_primary: false,
-        createdAt: new Date("2023-06-01"),
-      });
-
-      await getPhoneNumbersCollection().insertMany([older, newer]);
-
-      const result = await getPhoneNumbersForFlows(clientId);
-
-      expect(result).toHaveLength(2);
-      expect(result[0]).toEqual({
-        flowId: String(flow2._id),
-        phoneNumber: "+200",
-        isPrimary: false,
-      });
-      expect(result[1]).toEqual({
-        flowId: String(flow1._id),
-        phoneNumber: "+100",
-        isPrimary: true,
-      });
-    });
-
-    it("returns 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 () => {
-      const clientA = "clientA";
-      const clientB = "clientB";
-      const flow = createFlow();
-      await getFlowsCollection().insertOne(flow);
-      const phone = createPhoneNumber({
-        client_id: clientA,
-        flow_id: flow._id,
-      });
-      await getPhoneNumbersCollection().insertOne(phone);
-
-      const result = await getPhoneNumbersForFlows(clientB);
-      expect(result).toEqual([]);
-    });
-  });
-
-  describe("createPhoneNumberEntity", () => {
-    it("creates first phone number as primary", async () => {
-      const clientId = "newClient";
-      const flowId = new ObjectId().toHexString();
-      const phoneNumber = "+123456789";
-
-      const result = await createPhoneNumberEntity(
-        phoneNumber,
-        flowId,
-        clientId,
-      );
-      expect(result.phone_number).toBe(phoneNumber);
-      expect(result.is_primary).toBe(true);
-    });
-
-    it("creates subsequent phone number as non-primary", async () => {
-      const clientId = "existingClient";
-      const flowId = new ObjectId().toHexString();
-
-      // Create first one
-      await createPhoneNumberEntity("+111", flowId, clientId);
-
-      // Create second one
-      const result = await createPhoneNumberEntity("+222", flowId, clientId);
-      expect(result.phone_number).toBe("+222");
-      expect(result.is_primary).toBe(false);
-    });
-  });
-
-  describe("createPurchasedPhoneNumber", () => {
-    it("persists a phone_numbers document with provider payload and flow", async () => {
-      const clientId = "purchasedClientDb";
-      const flowId = new ObjectId().toHexString();
-      const phoneNumber = "+15551234567";
-      const providerPayload = {
-        provider: "twilio" as const,
-        provider_sid: "PNxxxxxxxx",
-      };
-
-      await createPurchasedPhoneNumber(
-        phoneNumber,
-        providerPayload,
-        clientId,
-        flowId,
-      );
-
-      // Re-read from Mongo to confirm insert succeeded (not only the function return value).
-      const stored = await getPhoneNumbersCollection().findOne({
-        phone_number: phoneNumber,
-      });
-      expect(stored).not.toBeNull();
-      expect(stored).toMatchObject({
-        phone_number: phoneNumber,
-        client_id: clientId,
-        provider: "twilio",
-        provider_sid: "PNxxxxxxxx",
-        flow_id: new ObjectId(flowId),
-      });
-    });
-  });
-
-  describe("getPrimaryPhoneFlowId", () => {
-    it("returns flow_id from primary phone as string", async () => {
-      const clientId = "primaryFlowClient";
-      const flowId = new ObjectId();
-      await getPhoneNumbersCollection().insertOne(
-        createPhoneNumber({
-          client_id: clientId,
-          is_primary: true,
-          flow_id: flowId,
-        }),
-      );
-
-      expect(await getPrimaryPhoneFlowId(clientId)).toBe(flowId.toHexString());
-    });
-
-    it("returns 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 () => {
-      const clientId = "phoneNoFlow";
-      const phone = createPhoneNumber({ client_id: clientId, is_primary: true });
-      delete phone.flow_id;
-      await getPhoneNumbersCollection().insertOne(phone);
-
-      expect(await getPrimaryPhoneFlowId(clientId)).toBeNull();
-    });
-  });
-});
+import {
+  getPhoneDataByPhoneNumber,
+  getPhoneNumbersCollection,
+  getPhoneNumbersForFlows,
+  getClientPhoneNumber,
+  getClientPhoneData,
+  createPhoneNumberEntity,
+  createPurchasedPhoneNumber,
+  getPrimaryPhoneFlowId,
+  getClientPhones,
+  getAllClientPhoneMappings,
+  getDistinctClientPhonePairs,
+  findClientsByPhoneNumbers,
+  deletePhoneNumberRecords,
+} from "../phone_numbers.getter";
+import { getFlowsCollection } from "../../flows/flows.getter";
+import { createFlow, createPhoneNumber } from "../../../test-utils/factories";
+import { ObjectId } from "mongodb";
+
+describe("db.phoneNumbers", () => {
+  describe("getPhoneDataByPhoneNumber", () => {
+    it("should return phone number data with flow", async () => {
+      const flow = createFlow({
+        clientId: "test-client-id",
+        conversationSettings: {
+          interruptions: {
+            enableInterruptionDetection: true,
+            interruptionWindowSeconds: 60,
+            interruptionThresholdSeconds: 10,
+            interruptionInstruction:
+              "I am hearing background noise that makes it hard for me to focus on what you are saying. Please try to move to a quieter place or reduce the noise so I can better assist you.",
+          },
+          silence: {
+            enableSilenceDetection: true,
+            firstWarningSilenceSeconds: 5,
+            firstWarningInstruction:
+              "I have not heard you for a few seconds. If you are still on the line, please say something so we can continue.",
+            secondWarningSilenceSeconds: 10,
+            secondWarningInstruction:
+              "I still have not heard anything from you. If you do not respond in the next few seconds, I will have to end this call.",
+            disconnectSilenceSeconds: 30,
+          },
+        },
+      });
+      const phoneData = createPhoneNumber({
+        flow_id: flow._id,
+        client_id: "test-client-id",
+      });
+
+      await getFlowsCollection().insertOne(flow);
+      await getPhoneNumbersCollection().insertOne(phoneData);
+
+      const result = await getPhoneDataByPhoneNumber(phoneData.phone_number);
+
+      expect(result).toBeDefined();
+      expect(result).toMatchObject({
+        client_id: phoneData.client_id,
+        phone_number: phoneData.phone_number,
+        flow_id: flow._id,
+      });
+      // Specifically check if the flow was joined correctly
+      expect(result?.flow.flowName).toBe(flow.flowName);
+      expect(
+        result?.flow.conversationSettings?.silence?.firstWarningSilenceSeconds,
+      ).toBe(5);
+    });
+  });
+
+  describe("getClientPhoneNumber", () => {
+    it("should return phone number by client id", async () => {
+      const flow = createFlow();
+      const phoneData = createPhoneNumber({
+        flow_id: flow._id,
+        is_primary: true,
+      });
+
+      await getFlowsCollection().insertOne(flow);
+      await getPhoneNumbersCollection().insertOne(phoneData);
+
+      const result = await getClientPhoneNumber(phoneData.client_id);
+      expect(result).toBe(phoneData.phone_number);
+    });
+  });
+
+  describe("getClientPhoneData", () => {
+    it("should return primary phone data by default", async () => {
+      const clientId = "multiPhoneClient";
+      const phone1 = createPhoneNumber({
+        client_id: clientId,
+        is_primary: false,
+        phone_number: "1",
+        createdAt: new Date("2023-01-01"),
+      });
+      const phone2 = createPhoneNumber({
+        client_id: clientId,
+        is_primary: true,
+        phone_number: "2",
+        createdAt: new Date("2023-01-02"),
+      });
+
+      await getPhoneNumbersCollection().insertOne(phone1);
+      await getPhoneNumbersCollection().insertOne(phone2);
+
+      const result = await getClientPhoneData(clientId);
+      expect(result?.phone_number).toBe("2");
+    });
+
+    it("should return most recent non-primary phone data if isPrimary is false", async () => {
+      const clientId = "multiPhoneClient2";
+      const phone1 = createPhoneNumber({
+        client_id: clientId,
+        is_primary: false,
+        phone_number: "1",
+        createdAt: new Date("2023-01-01"),
+      });
+      const phone2 = createPhoneNumber({
+        client_id: clientId,
+        is_primary: false,
+        phone_number: "2",
+        createdAt: new Date("2023-01-02"),
+      });
+      const phone3 = createPhoneNumber({
+        client_id: clientId,
+        is_primary: true,
+        phone_number: "3",
+        createdAt: new Date("2023-01-03"),
+      });
+
+      await getPhoneNumbersCollection().insertOne(phone1);
+      await getPhoneNumbersCollection().insertOne(phone2);
+      await getPhoneNumbersCollection().insertOne(phone3);
+
+      const result = await getClientPhoneData(clientId, false);
+      expect(result?.phone_number).toBe("2");
+    });
+  });
+
+  describe("getPhoneNumbersForFlows", () => {
+    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 });
+      await getFlowsCollection().insertMany([flow1, flow2]);
+
+      const older = createPhoneNumber({
+        client_id: clientId,
+        flow_id: flow1._id,
+        phone_number: "+100",
+        is_primary: true,
+        createdAt: new Date("2023-01-01"),
+      });
+      const newer = createPhoneNumber({
+        client_id: clientId,
+        flow_id: flow2._id,
+        phone_number: "+200",
+        is_primary: false,
+        createdAt: new Date("2023-06-01"),
+      });
+
+      await getPhoneNumbersCollection().insertMany([older, newer]);
+
+      const result = await getPhoneNumbersForFlows(clientId);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        flowId: String(flow2._id),
+        phoneNumber: "+200",
+        isPrimary: false,
+      });
+      expect(result[1]).toEqual({
+        flowId: String(flow1._id),
+        phoneNumber: "+100",
+        isPrimary: true,
+      });
+    });
+
+    it("should return an empty array when the client has no phone numbers", async () => {
+      const result = await getPhoneNumbersForFlows("noSuchClient");
+      expect(result).toEqual([]);
+    });
+
+    it("should not include phone numbers for other clients", async () => {
+      const clientA = "clientA";
+      const clientB = "clientB";
+      const flow = createFlow();
+      await getFlowsCollection().insertOne(flow);
+      const phone = createPhoneNumber({
+        client_id: clientA,
+        flow_id: flow._id,
+      });
+      await getPhoneNumbersCollection().insertOne(phone);
+
+      const result = await getPhoneNumbersForFlows(clientB);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("createPhoneNumberEntity", () => {
+    it("should create first phone number as primary", async () => {
+      const clientId = "newClient";
+      const flowId = new ObjectId().toHexString();
+      const phoneNumber = "+123456789";
+
+      const result = await createPhoneNumberEntity(
+        phoneNumber,
+        flowId,
+        clientId,
+      );
+      expect(result.phone_number).toBe(phoneNumber);
+      expect(result.is_primary).toBe(true);
+    });
+
+    it("should create subsequent phone number as non-primary", async () => {
+      const clientId = "existingClient";
+      const flowId = new ObjectId().toHexString();
+
+      // Create first one
+      await createPhoneNumberEntity("+111", flowId, clientId);
+
+      // Create second one
+      const result = await createPhoneNumberEntity("+222", flowId, clientId);
+      expect(result.phone_number).toBe("+222");
+      expect(result.is_primary).toBe(false);
+    });
+  });
+
+  describe("createPurchasedPhoneNumber", () => {
+    it("should persist a phone_numbers document with provider payload and flow", async () => {
+      const clientId = "purchasedClientDb";
+      const flowId = new ObjectId().toHexString();
+      const phoneNumber = "+15551234567";
+      const providerPayload = {
+        provider: "twilio" as const,
+        provider_sid: "PNxxxxxxxx",
+      };
+
+      await createPurchasedPhoneNumber(
+        phoneNumber,
+        providerPayload,
+        clientId,
+        flowId,
+      );
+
+      // Re-read from Mongo to confirm insert succeeded (not only the function return value).
+      const stored = await getPhoneNumbersCollection().findOne({
+        phone_number: phoneNumber,
+      });
+      expect(stored).not.toBeNull();
+      expect(stored).toMatchObject({
+        phone_number: phoneNumber,
+        client_id: clientId,
+        provider: "twilio",
+        provider_sid: "PNxxxxxxxx",
+        flow_id: new ObjectId(flowId),
+      });
+    });
+  });
+
+  describe("getPrimaryPhoneFlowId", () => {
+    it("should return flow_id from primary phone as string", async () => {
+      const clientId = "primaryFlowClient";
+      const flowId = new ObjectId();
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({
+          client_id: clientId,
+          is_primary: true,
+          flow_id: flowId,
+        }),
+      );
+
+      expect(await getPrimaryPhoneFlowId(clientId)).toBe(flowId.toHexString());
+    });
+
+    it("should return null when client has no primary phone", async () => {
+      expect(await getPrimaryPhoneFlowId("no-phone-client")).toBeNull();
+    });
+
+    it("should return null when primary phone has no flow_id", async () => {
+      const clientId = "phoneNoFlow";
+      const phone = createPhoneNumber({ client_id: clientId, is_primary: true });
+      delete phone.flow_id;
+      await getPhoneNumbersCollection().insertOne(phone);
+
+      expect(await getPrimaryPhoneFlowId(clientId)).toBeNull();
+    });
+  });
+
+  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("getAllClientPhoneMappings", () => {
+    it("should return a Map of clientId to phone number across all clients", async () => {
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: "mapClientA", phone_number: "+111" }),
+        createPhoneNumber({ client_id: "mapClientB", phone_number: "+222" }),
+      ]);
+
+      const result = await getAllClientPhoneMappings();
+
+      expect(result).toBeInstanceOf(Map);
+      expect(result.get("mapClientA")).toBe("+111");
+      expect(result.get("mapClientB")).toBe("+222");
+    });
+
+    it("should return an empty Map when there are no phone numbers", async () => {
+      const result = await getAllClientPhoneMappings();
+      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 getAllClientPhoneMappings();
+
+      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 getAllClientPhoneMappings();
+
+      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" },
+          { clientId: "pairClientB", phoneNumber: "+600" },
+        ]),
+      );
+      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" },
+          { clientId: "sharedClientB", phoneNumber: "+700" },
+        ]),
+      );
+    });
+  });
+
+  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);
+    });
+  });
+});