@talkpilot/core-db 1.1.8 → 1.1.10

package/src/talkpilot/leads/index.ts

@@ -1,2 +1,2 @@
-export { getLeadsCollection } from './leads.getter';
-export type { Lead, LeadItem, LeadProperty } from './leads.types';
+export { getLeadsCollection } from "./leads.getter";
+export type { Lead, LeadItem, LeadProperty } from "./leads.types";

package/src/talkpilot/leads/leads.getter.ts

@@ -1,5 +1,6 @@
-import type { Collection } from 'mongodb';
-import { getDb } from '../index';
-import type { Lead } from './leads.types';
+import type { Collection } from "mongodb";
+import { getDb } from "../index";
+import type { Lead } from "./leads.types";
 
-export const getLeadsCollection = (): Collection<Lead> => getDb().collection<Lead>('leads');
+export const getLeadsCollection = (): Collection<Lead> =>
+  getDb().collection<Lead>("leads");

package/src/talkpilot/leads/leads.schema.ts

@@ -1,27 +1,27 @@
 export const leadsMongoSchema = {
-  bsonType: 'object',
-  required: ['flowId', 'clientId', 'createdAt', 'leads'],
+  bsonType: "object",
+  required: ["flowId", "clientId", "createdAt", "leads"],
   properties: {
-    _id: { bsonType: 'objectId' },
-    flowId: { bsonType: 'string' },
-    clientId: { bsonType: 'string' },
-    createdAt: { bsonType: 'date' },
+    _id: { bsonType: "objectId" },
+    flowId: { bsonType: "string" },
+    clientId: { bsonType: "string" },
+    createdAt: { bsonType: "date" },
     leads: {
-      bsonType: 'array',
+      bsonType: "array",
       items: {
-        bsonType: 'object',
-        required: ['callSid', 'timestamp'],
+        bsonType: "object",
+        required: ["callSid", "timestamp"],
         properties: {
-          callSid: { bsonType: 'string' },
-          timestamp: { bsonType: 'date' },
+          callSid: { bsonType: "string" },
+          timestamp: { bsonType: "date" },
           properties: {
-            bsonType: 'array',
+            bsonType: "array",
             items: {
-              bsonType: 'object',
-              required: ['name', 'value'],
+              bsonType: "object",
+              required: ["name", "value"],
               properties: {
-                name: { bsonType: 'string' },
-                value: { bsonType: 'string' },
+                name: { bsonType: "string" },
+                value: { bsonType: "string" },
               },
             },
           },

package/src/talkpilot/leads/leads.types.ts

@@ -1,4 +1,4 @@
-import { ObjectId } from 'mongodb';
+import { ObjectId } from "mongodb";
 
 export interface LeadProperty {
   name: string;

package/src/talkpilot/mongodb-client.ts

@@ -1,6 +1,6 @@
-import { MongoClient, Db } from 'mongodb';
-import { setDb } from './index';
-import { validateConfig, validateMongoUri } from '../utils/validation';
+import { MongoClient, Db } from "mongodb";
+import { setDb } from "./index";
+import { validateConfig, validateMongoUri } from "../utils/validation";
 
 class MongoDBClient {
   private client: MongoClient | null = null;
@@ -22,7 +22,7 @@ class MongoDBClient {
     }
 
     const mongodbUri = uri || process.env.MONGO_URI || process.env.MONGODB_URI;
-    validateConfig('MONGO_URI', mongodbUri);
+    validateConfig("MONGO_URI", mongodbUri);
     validateMongoUri(mongodbUri!);
 
     try {
@@ -30,13 +30,13 @@ class MongoDBClient {
       await this.client.connect();
 
       const dbNameFromUri = this.extractDatabaseName(mongodbUri!);
-      const dbNameFromEnv = process.env.MONGODB_DB_NAME;
-      const dbName = databaseName || dbNameFromUri || dbNameFromEnv;
+      const dbName =
+        databaseName || process.env.TALKPILOT_DB_NAME || dbNameFromUri;
 
       if (!dbName) {
         throw new Error(
-          '[core-db] Database name not specified. Please pass databaseName to connect(), ' +
-          'add it to the URI, or set MONGODB_DB_NAME.'
+          "[core-db] Database name not specified. Please pass databaseName to connect(), " +
+            "add it to the URI, or set TALKPILOT_DB_NAME.",
         );
       }
 
@@ -44,7 +44,7 @@ class MongoDBClient {
       setDb(this.db);
       console.info(`[core-db] TalkPilot MongoDB connected: ${dbName}`);
     } catch (error) {
-      console.error('[core-db] TalkPilot connection failed', error as Error);
+      console.error("[core-db] TalkPilot connection failed", error);
       throw error;
     }
   }
@@ -55,9 +55,9 @@ class MongoDBClient {
         await this.client.close();
         this.client = null;
         this.db = null;
-        console.info('MongoDB disconnected successfully');
+        console.info("MongoDB disconnected successfully");
       } catch (error) {
-        console.error('Error disconnecting from MongoDB', error as Error);
+        console.error("[core-db] Disconnection failed", error);
         throw error;
       }
     }
@@ -65,7 +65,7 @@ class MongoDBClient {
 
   getDb(): Db {
     if (!this.db) {
-      throw new Error('Database not initialized. Call connect() first.');
+      throw new Error("Database not initialized. Call connect() first.");
     }
     return this.db;
   }

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

@@ -1,9 +1,11 @@
 import {
   getPhoneDataByPhoneNumber,
   getPhoneNumbersCollection,
+  getPhoneNumbersForFlows,
   getClientPhoneNumber,
   getClientPhoneData,
   createPhoneNumberEntity,
+  createPurchasedPhoneNumber,
 } from '../phone_numbers.getter';
 import { getFlowsCollection } from '../../flows/flows.getter';
 import { createFlow, createPhoneNumber } from '../../../test-utils/factories';
@@ -13,31 +15,37 @@ describe('db.phoneNumbers', () => {
   describe('getPhoneDataByPhoneNumber', () => {
     it('return phone number data with flow', async () => {
       const flow = createFlow({
-        clientId: 'test-client-id',
+        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.',
+            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.',
+            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.',
+            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' });
-      
+      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,
@@ -46,15 +54,20 @@ describe('db.phoneNumbers', () => {
       });
       // Specifically check if the flow was joined correctly
       expect(result?.flow.flowName).toBe(flow.flowName);
-      expect(result?.flow.conversationSettings?.silence?.firstWarningSilenceSeconds).toBe(5);
+      expect(
+        result?.flow.conversationSettings?.silence?.firstWarningSilenceSeconds,
+      ).toBe(5);
     });
   });
 
-  describe('getClientPhoneNumber', () => {
-    it('return phone number by client id', async () => {
+  describe("getClientPhoneNumber", () => {
+    it("return phone number by client id", async () => {
       const flow = createFlow();
-      const phoneData = createPhoneNumber({ flow_id: flow._id, is_primary: true });
-      
+      const phoneData = createPhoneNumber({
+        flow_id: flow._id,
+        is_primary: true,
+      });
+
       await getFlowsCollection().insertOne(flow);
       await getPhoneNumbersCollection().insertOne(phoneData);
 
@@ -63,31 +76,113 @@ describe('db.phoneNumbers', () => {
     });
   });
 
-  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') });
+  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');
+      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') });
+    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');
+      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([]);
     });
   });
 
@@ -95,24 +190,58 @@ describe('db.phoneNumbers', () => {
     it('creates first phone number as primary', async () => {
       const clientId = 'newClient';
       const flowId = new ObjectId().toHexString();
-      const phoneNumber = '+123456789';
+      const phoneNumber = "+123456789";
 
-      const result = await createPhoneNumberEntity(phoneNumber, flowId, clientId);
+      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';
+    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);
-      
+      await createPhoneNumberEntity("+111", flowId, clientId);
+
       // Create second one
-      const result = await createPhoneNumberEntity('+222', flowId, clientId);
-      expect(result.phone_number).toBe('+222');
+      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),
+      });
+    });
+  });
 });

package/src/talkpilot/phone_numbers/index.ts

@@ -1,2 +1,2 @@
 export * from './phone_numbers.getter';
-export type { PhoneNumber } from './phone_numbers.types';
+export type * from './phone_numbers.types';

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

@@ -1,4 +1,4 @@
-import type { Collection } from 'mongodb';
+import type { Collection } from "mongodb";
 import {
   Client,
   getClientsCollection,
@@ -7,32 +7,54 @@ import {
   ObjectId,
   findSubscriptions,
 } from '../index';
-import { PhoneNumber, PhoneNumberWithFlow } from './phone_numbers.types';
+import {
+  ClientPhoneNumberForFlow,
+  PhoneNumber,
+  PhoneNumberWithFlow,
+  PurchasedPhoneProviderPayload
+} from "./phone_numbers.types";
 
 export const getPhoneNumbersCollection = (): Collection<PhoneNumber> =>
-  getDb().collection<PhoneNumber>('phone_numbers');
+  getDb().collection<PhoneNumber>("phone_numbers");
 
 export const getPhoneDataByPhoneNumber = async (
-  phoneNumber: string
+  phoneNumber: string,
 ): Promise<PhoneNumberWithFlow | null> => {
-  const phoneCallData = await getPhoneNumbersCollection().findOne({ phone_number: phoneNumber });
+  const phoneCallData = await getPhoneNumbersCollection().findOne({
+    phone_number: phoneNumber,
+  });
   if (!phoneCallData) {
-    throw new Error('PhoneNumber not found');
+    throw new Error("PhoneNumber not found");
   }
-  const flow = await getFlowsCollection().findOne({ _id: new ObjectId(phoneCallData.flow_id) });
+  const flow = await getFlowsCollection().findOne({
+    _id: new ObjectId(phoneCallData.flow_id),
+  });
   if (!flow) {
-    throw new Error('Flow not found');
+    throw new Error("Flow not found");
   }
   const [subscription] =
-    (await findSubscriptions({ clientId: phoneCallData.client_id, isActive: true })) || [];
+    (await findSubscriptions({
+      clientId: phoneCallData.client_id,
+      isActive: true,
+    })) || [];
 
-  return { ...phoneCallData, flow, subscriptionId: subscription?._id?.toString() ?? undefined };
+  return {
+    ...phoneCallData,
+    flow,
+    subscriptionId: subscription?._id?.toString() ?? undefined,
+  };
 };
 
-export const getClientPrimaryPhoneNumber = async (clientId: string): Promise<string | null> => {
+export const getClientPrimaryPhoneNumber = async (
+  clientId: string,
+): Promise<string | null> => {
   return (
-    (await getPhoneNumbersCollection().findOne({ client_id: clientId, is_primary: true }))
-      ?.phone_number ?? null
+    (
+      await getPhoneNumbersCollection().findOne({
+        client_id: clientId,
+        is_primary: true,
+      })
+    )?.phone_number ?? null
   );
 };
 
@@ -40,17 +62,37 @@ export const getClientPhoneNumber = getClientPrimaryPhoneNumber;
 
 export const getClientPhoneData = async (
   clientId: string,
-  isPrimary?: boolean
+  isPrimary?: boolean,
 ): Promise<PhoneNumber | null> => {
   const filter = { client_id: clientId, is_primary: isPrimary !== false };
-  const options = isPrimary === false ? { sort: { createdAt: -1 } as const } : {};
+  const options =
+    isPrimary === false ? { sort: { createdAt: -1 } as const } : {};
   return getPhoneNumbersCollection().findOne(filter, options);
 };
 
+export const getPhoneNumbersForFlows = async (
+  clientId: string,
+): Promise<ClientPhoneNumberForFlow[]> => {
+  const docs = await getPhoneNumbersCollection()
+    .find({
+      client_id: clientId,
+      flow_id: { $exists: true, $type: "objectId" },
+    })
+    .project({ _id: 0, flow_id: 1, phone_number: 1, is_primary: 1 })
+    .sort({ createdAt: -1 })
+    .toArray();
+
+  return docs.map((doc) => ({
+    flowId: String(doc.flow_id),
+    phoneNumber: doc.phone_number,
+    isPrimary: doc.is_primary,
+  }));
+};
+
 export const createPhoneNumberEntity = async (
   phoneNumber: string,
   flowId: string,
-  clientId: string
+  clientId: string,
 ): Promise<PhoneNumber> => {
   const existing = await getClientPhoneData(clientId);
   const isPrimary = !existing;
@@ -64,15 +106,49 @@ export const createPhoneNumberEntity = async (
     updatedAt: new Date(),
   });
   const phoneNumberData = await getClientPhoneData(clientId, isPrimary);
-  if (!phoneNumberData) throw new Error('Failed to create phoneNumber');
+  if (!phoneNumberData) throw new Error("Failed to create phoneNumber");
   return phoneNumberData;
 };
 
+/** API-purchased number; `flowId` may be omitted until the number is bound to a flow. */
+export const createPurchasedPhoneNumber = async (
+  phoneNumber: string,
+  providerPayload: PurchasedPhoneProviderPayload,
+  clientId: string,
+  flowId?: string | null,
+): Promise<PhoneNumber> => {
+  const existingPhoneForClient = await getClientPhoneData(clientId);
+  const isPrimary = !existingPhoneForClient;
+
+  const now = new Date();
+  const trimmedFlowId = flowId?.trim();
+  const flowObjectId = trimmedFlowId ? new ObjectId(trimmedFlowId) : undefined;
+
+  const doc: PhoneNumber = {
+    phone_number: phoneNumber,
+    client_id: clientId,
+    is_primary: isPrimary,
+    ...providerPayload,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  if (flowObjectId) {
+    doc.flow_id = flowObjectId;
+  }
+
+  await getPhoneNumbersCollection().insertOne(doc);
+
+  const created = await getClientPhoneData(clientId, isPrimary);
+  if (!created) throw new Error('Failed to create phoneNumber');
+  return created;
+};
+
 export const findClientByPhoneNumber = async (phoneNumber: string): Promise<Client> => {
   const phoneData = await getPhoneNumbersCollection().findOne({ phone_number: phoneNumber });
   if (!phoneData) throw new Error('Failed to get phone data');
   const clientId = phoneData.client_id;
   const client = await getClientsCollection().findOne({ clientId });
-  if (!client) throw new Error('Failed to get client');
+  if (!client) throw new Error("Failed to get client");
   return client;
 };

package/src/talkpilot/phone_numbers/phone_numbers.schema.ts

@@ -1,12 +1,15 @@
 export const phoneNumbersMongoSchema = {
   bsonType: 'object',
-  required: ['client_id', 'flow_id', 'phone_number'],
+  required: ['client_id', 'phone_number'],
   properties: {
     _id: { bsonType: 'objectId' },
     client_id: { bsonType: 'string' },
-    flow_id: { bsonType: 'string' },
+    flow_id: { bsonType: ['objectId', 'string'] },
     phone_number: { bsonType: 'string' },
     is_primary: { bsonType: 'bool' },
+    provider: { bsonType: 'string' },
+    provider_sid: { bsonType: 'string' },
+    friendly_name: { bsonType: 'string' },
     createdAt: { bsonType: 'date' },
     updatedAt: { bsonType: 'date' },
   },

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

@@ -1,15 +1,30 @@
-import { ObjectId, WithId } from "mongodb";
-import { Flow } from "../flows/flows.types";
+import { ObjectId, WithId } from 'mongodb';
+import { Flow } from '../flows/flows.types';
+
+export type PurchasedPhoneProviderPayload = {
+  provider: 'twilio' | 'telnyx';
+  provider_sid: string;
+  friendly_name?: string;
+};
 
 export type PhoneNumber = {
   _id?: ObjectId;
   client_id: string;
-  flow_id: ObjectId;
+  flow_id?: ObjectId;
   phone_number: string;
   subscriptionId?: string;
   is_primary: boolean;
+  provider?: 'twilio' | 'telnyx';
+  provider_sid?: string;
+  friendly_name?: string;
   createdAt: Date;
   updatedAt: Date;
 };
 
 export type PhoneNumberWithFlow = WithId<PhoneNumber> & { flow: Flow };
+
+export type ClientPhoneNumberForFlow = {
+  flowId: string;
+  phoneNumber: string;
+  isPrimary: boolean;
+};