@talkpilot/core-db 1.3.75 → 1.3.77

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

@@ -1,530 +1,530 @@
-import {
-  getPhoneDataByPhoneNumber,
-  getPhoneNumbersCollection,
-  getPhoneNumbersForFlows,
-  getClientPhoneNumber,
-  getClientPhoneData,
-  createPhoneNumberEntity,
-  createPurchasedPhoneNumber,
-  getPrimaryPhoneFlowId,
-  findPhoneNumbersByClientId,
-  getOwnedPhoneNumber,
-  getPhoneNumberByClientAndFlow,
-  clearPhoneNumberFlow,
-  assignExclusiveFlow,
-  unbindFlowFromClientNumbers,
-} 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();
-    });
-  });
-
-  describe("findPhoneNumbersByClientId", () => {
-    it("returns only that client's numbers", async () => {
-      const clientId = "list-client";
-      await getPhoneNumbersCollection().insertMany([
-        createPhoneNumber({ client_id: clientId, phone_number: "+100" }),
-        createPhoneNumber({ client_id: clientId, phone_number: "+200" }),
-        createPhoneNumber({
-          client_id: "other-list-client",
-          phone_number: "+300",
-        }),
-      ]);
-
-      const docs = await findPhoneNumbersByClientId(clientId);
-      expect(docs.map((doc) => doc.phone_number).sort()).toEqual([
-        "+100",
-        "+200",
-      ]);
-    });
-  });
-
-  describe("getOwnedPhoneNumber", () => {
-    it("returns the number when it belongs to the client", async () => {
-      await getPhoneNumbersCollection().insertOne(
-        createPhoneNumber({
-          client_id: "owned-client",
-          phone_number: "+111",
-        }),
-      );
-
-      const doc = await getOwnedPhoneNumber("owned-client", "+111");
-      expect(doc?.phone_number).toBe("+111");
-    });
-
-    it("returns null when the number belongs to another client", async () => {
-      await getPhoneNumbersCollection().insertOne(
-        createPhoneNumber({
-          client_id: "owned-other",
-          phone_number: "+111",
-        }),
-      );
-
-      expect(await getOwnedPhoneNumber("owned-client", "+111")).toBeNull();
-    });
-  });
-
-  describe("getPhoneNumberByClientAndFlow", () => {
-    it("finds a number bound with ObjectId flow_id", async () => {
-      const clientId = "flow-oid-client";
-      const flowId = new ObjectId();
-      await getPhoneNumbersCollection().insertOne(
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+oid",
-          flow_id: flowId,
-        }),
-      );
-
-      expect(
-        (await getPhoneNumberByClientAndFlow(clientId, flowId.toHexString()))
-          ?.phone_number,
-      ).toBe("+oid");
-    });
-
-    it("finds a number bound with string-stored flow_id", async () => {
-      const clientId = "flow-str-client";
-      const flowId = new ObjectId();
-      const doc = createPhoneNumber({
-        client_id: clientId,
-        phone_number: "+str",
-      });
-      delete doc.flow_id;
-      await getPhoneNumbersCollection().insertOne({
-        ...doc,
-        flow_id: flowId.toHexString() as unknown as ObjectId,
-      });
-
-      expect(
-        (await getPhoneNumberByClientAndFlow(clientId, flowId.toHexString()))
-          ?.phone_number,
-      ).toBe("+str");
-    });
-
-    it("returns null for another client's bind", async () => {
-      const flowId = new ObjectId();
-      await getPhoneNumbersCollection().insertOne(
-        createPhoneNumber({
-          client_id: "flow-other-client",
-          flow_id: flowId,
-        }),
-      );
-
-      expect(
-        await getPhoneNumberByClientAndFlow(
-          "flow-lookup-client",
-          flowId.toHexString(),
-        ),
-      ).toBeNull();
-    });
-  });
-
-  describe("assignExclusiveFlow", () => {
-    it("binds the number and unsets the same client's previous bind", async () => {
-      const clientId = "exclusive-client";
-      const flowId = new ObjectId();
-      await getPhoneNumbersCollection().insertMany([
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+old",
-          flow_id: flowId,
-        }),
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+new",
-        }),
-        createPhoneNumber({
-          client_id: "exclusive-other",
-          phone_number: "+other",
-          flow_id: flowId,
-        }),
-      ]);
-
-      await assignExclusiveFlow(clientId, "+new", flowId.toHexString());
-
-      const [oldDoc, newDoc, otherDoc] = await Promise.all([
-        getPhoneNumbersCollection().findOne({ phone_number: "+old" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+new" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+other" }),
-      ]);
-      expect(oldDoc?.flow_id).toBeUndefined();
-      expect(newDoc?.flow_id?.toString()).toBe(flowId.toHexString());
-      expect(otherDoc?.flow_id?.toString()).toBe(flowId.toHexString());
-    });
-
-    it("steals when the previous bind stored flow_id as a string", async () => {
-      const clientId = "exclusive-string-client";
-      const flowId = new ObjectId();
-      const previous = createPhoneNumber({
-        client_id: clientId,
-        phone_number: "+old-str",
-      });
-      delete previous.flow_id;
-      await getPhoneNumbersCollection().insertMany([
-        {
-          ...previous,
-          flow_id: flowId.toHexString() as unknown as ObjectId,
-        },
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+new-str",
-        }),
-      ]);
-
-      await assignExclusiveFlow(clientId, "+new-str", flowId.toHexString());
-
-      const [oldDoc, newDoc] = await Promise.all([
-        getPhoneNumbersCollection().findOne({ phone_number: "+old-str" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+new-str" }),
-      ]);
-      expect(oldDoc?.flow_id).toBeUndefined();
-      expect(newDoc?.flow_id?.toString()).toBe(flowId.toHexString());
-    });
-  });
-
-  describe("clearPhoneNumberFlow", () => {
-    it("unsets flow_id on that number only", async () => {
-      const clientId = "clear-client";
-      const flowA = new ObjectId();
-      const flowB = new ObjectId();
-      await getPhoneNumbersCollection().insertMany([
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+a",
-          flow_id: flowA,
-        }),
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+b",
-          flow_id: flowB,
-        }),
-      ]);
-
-      await clearPhoneNumberFlow(clientId, "+a");
-
-      const [a, b] = await Promise.all([
-        getPhoneNumbersCollection().findOne({ phone_number: "+a" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+b" }),
-      ]);
-      expect(a?.flow_id).toBeUndefined();
-      expect(b?.flow_id?.toString()).toBe(flowB.toHexString());
-    });
-  });
-
-  describe("unbindFlowFromClientNumbers", () => {
-    it("clears ObjectId and string-stored flow_id for that client only", async () => {
-      const clientId = "unbind-client";
-      const flowId = new ObjectId();
-      const otherFlowId = new ObjectId();
-      const stringDoc = createPhoneNumber({
-        client_id: clientId,
-        phone_number: "+str-unbind",
-      });
-      delete stringDoc.flow_id;
-      await getPhoneNumbersCollection().insertMany([
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+oid-unbind",
-          flow_id: flowId,
-        }),
-        {
-          ...stringDoc,
-          flow_id: flowId.toHexString() as unknown as ObjectId,
-        },
-        createPhoneNumber({
-          client_id: clientId,
-          phone_number: "+keep",
-          flow_id: otherFlowId,
-        }),
-        createPhoneNumber({
-          client_id: "unbind-other",
-          phone_number: "+other-keep",
-          flow_id: flowId,
-        }),
-      ]);
-
-      await unbindFlowFromClientNumbers(clientId, flowId.toHexString());
-
-      const [oidDoc, strDoc, keep, other] = await Promise.all([
-        getPhoneNumbersCollection().findOne({ phone_number: "+oid-unbind" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+str-unbind" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+keep" }),
-        getPhoneNumbersCollection().findOne({ phone_number: "+other-keep" }),
-      ]);
-      expect(oidDoc?.flow_id).toBeUndefined();
-      expect(strDoc?.flow_id).toBeUndefined();
-      expect(keep?.flow_id?.toString()).toBe(otherFlowId.toHexString());
-      expect(other?.flow_id?.toString()).toBe(flowId.toHexString());
-    });
-  });
-});
+import {
+  getPhoneDataByPhoneNumber,
+  getPhoneNumbersCollection,
+  getPhoneNumbersForFlows,
+  getClientPhoneNumber,
+  getClientPhoneData,
+  createPhoneNumberEntity,
+  createPurchasedPhoneNumber,
+  getPrimaryPhoneFlowId,
+  findPhoneNumbersByClientId,
+  getOwnedPhoneNumber,
+  getPhoneNumberByClientAndFlow,
+  clearPhoneNumberFlow,
+  assignExclusiveFlow,
+  unbindFlowFromClientNumbers,
+} 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();
+    });
+  });
+
+  describe("findPhoneNumbersByClientId", () => {
+    it("returns only that client's numbers", async () => {
+      const clientId = "list-client";
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({ client_id: clientId, phone_number: "+100" }),
+        createPhoneNumber({ client_id: clientId, phone_number: "+200" }),
+        createPhoneNumber({
+          client_id: "other-list-client",
+          phone_number: "+300",
+        }),
+      ]);
+
+      const docs = await findPhoneNumbersByClientId(clientId);
+      expect(docs.map((doc) => doc.phone_number).sort()).toEqual([
+        "+100",
+        "+200",
+      ]);
+    });
+  });
+
+  describe("getOwnedPhoneNumber", () => {
+    it("returns the number when it belongs to the client", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({
+          client_id: "owned-client",
+          phone_number: "+111",
+        }),
+      );
+
+      const doc = await getOwnedPhoneNumber("owned-client", "+111");
+      expect(doc?.phone_number).toBe("+111");
+    });
+
+    it("returns null when the number belongs to another client", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({
+          client_id: "owned-other",
+          phone_number: "+111",
+        }),
+      );
+
+      expect(await getOwnedPhoneNumber("owned-client", "+111")).toBeNull();
+    });
+  });
+
+  describe("getPhoneNumberByClientAndFlow", () => {
+    it("finds a number bound with ObjectId flow_id", async () => {
+      const clientId = "flow-oid-client";
+      const flowId = new ObjectId();
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+oid",
+          flow_id: flowId,
+        }),
+      );
+
+      expect(
+        (await getPhoneNumberByClientAndFlow(clientId, flowId.toHexString()))
+          ?.phone_number,
+      ).toBe("+oid");
+    });
+
+    it("finds a number bound with string-stored flow_id", async () => {
+      const clientId = "flow-str-client";
+      const flowId = new ObjectId();
+      const doc = createPhoneNumber({
+        client_id: clientId,
+        phone_number: "+str",
+      });
+      delete doc.flow_id;
+      await getPhoneNumbersCollection().insertOne({
+        ...doc,
+        flow_id: flowId.toHexString() as unknown as ObjectId,
+      });
+
+      expect(
+        (await getPhoneNumberByClientAndFlow(clientId, flowId.toHexString()))
+          ?.phone_number,
+      ).toBe("+str");
+    });
+
+    it("returns null for another client's bind", async () => {
+      const flowId = new ObjectId();
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({
+          client_id: "flow-other-client",
+          flow_id: flowId,
+        }),
+      );
+
+      expect(
+        await getPhoneNumberByClientAndFlow(
+          "flow-lookup-client",
+          flowId.toHexString(),
+        ),
+      ).toBeNull();
+    });
+  });
+
+  describe("assignExclusiveFlow", () => {
+    it("binds the number and unsets the same client's previous bind", async () => {
+      const clientId = "exclusive-client";
+      const flowId = new ObjectId();
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+old",
+          flow_id: flowId,
+        }),
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+new",
+        }),
+        createPhoneNumber({
+          client_id: "exclusive-other",
+          phone_number: "+other",
+          flow_id: flowId,
+        }),
+      ]);
+
+      await assignExclusiveFlow(clientId, "+new", flowId.toHexString());
+
+      const [oldDoc, newDoc, otherDoc] = await Promise.all([
+        getPhoneNumbersCollection().findOne({ phone_number: "+old" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+new" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+other" }),
+      ]);
+      expect(oldDoc?.flow_id).toBeUndefined();
+      expect(newDoc?.flow_id?.toString()).toBe(flowId.toHexString());
+      expect(otherDoc?.flow_id?.toString()).toBe(flowId.toHexString());
+    });
+
+    it("steals when the previous bind stored flow_id as a string", async () => {
+      const clientId = "exclusive-string-client";
+      const flowId = new ObjectId();
+      const previous = createPhoneNumber({
+        client_id: clientId,
+        phone_number: "+old-str",
+      });
+      delete previous.flow_id;
+      await getPhoneNumbersCollection().insertMany([
+        {
+          ...previous,
+          flow_id: flowId.toHexString() as unknown as ObjectId,
+        },
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+new-str",
+        }),
+      ]);
+
+      await assignExclusiveFlow(clientId, "+new-str", flowId.toHexString());
+
+      const [oldDoc, newDoc] = await Promise.all([
+        getPhoneNumbersCollection().findOne({ phone_number: "+old-str" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+new-str" }),
+      ]);
+      expect(oldDoc?.flow_id).toBeUndefined();
+      expect(newDoc?.flow_id?.toString()).toBe(flowId.toHexString());
+    });
+  });
+
+  describe("clearPhoneNumberFlow", () => {
+    it("unsets flow_id on that number only", async () => {
+      const clientId = "clear-client";
+      const flowA = new ObjectId();
+      const flowB = new ObjectId();
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+a",
+          flow_id: flowA,
+        }),
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+b",
+          flow_id: flowB,
+        }),
+      ]);
+
+      await clearPhoneNumberFlow(clientId, "+a");
+
+      const [a, b] = await Promise.all([
+        getPhoneNumbersCollection().findOne({ phone_number: "+a" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+b" }),
+      ]);
+      expect(a?.flow_id).toBeUndefined();
+      expect(b?.flow_id?.toString()).toBe(flowB.toHexString());
+    });
+  });
+
+  describe("unbindFlowFromClientNumbers", () => {
+    it("clears ObjectId and string-stored flow_id for that client only", async () => {
+      const clientId = "unbind-client";
+      const flowId = new ObjectId();
+      const otherFlowId = new ObjectId();
+      const stringDoc = createPhoneNumber({
+        client_id: clientId,
+        phone_number: "+str-unbind",
+      });
+      delete stringDoc.flow_id;
+      await getPhoneNumbersCollection().insertMany([
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+oid-unbind",
+          flow_id: flowId,
+        }),
+        {
+          ...stringDoc,
+          flow_id: flowId.toHexString() as unknown as ObjectId,
+        },
+        createPhoneNumber({
+          client_id: clientId,
+          phone_number: "+keep",
+          flow_id: otherFlowId,
+        }),
+        createPhoneNumber({
+          client_id: "unbind-other",
+          phone_number: "+other-keep",
+          flow_id: flowId,
+        }),
+      ]);
+
+      await unbindFlowFromClientNumbers(clientId, flowId.toHexString());
+
+      const [oidDoc, strDoc, keep, other] = await Promise.all([
+        getPhoneNumbersCollection().findOne({ phone_number: "+oid-unbind" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+str-unbind" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+keep" }),
+        getPhoneNumbersCollection().findOne({ phone_number: "+other-keep" }),
+      ]);
+      expect(oidDoc?.flow_id).toBeUndefined();
+      expect(strDoc?.flow_id).toBeUndefined();
+      expect(keep?.flow_id?.toString()).toBe(otherFlowId.toHexString());
+      expect(other?.flow_id?.toString()).toBe(flowId.toHexString());
+    });
+  });
+});