@talkpilot/core-db 1.0.1

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

@@ -0,0 +1,83 @@
+import { ObjectId } from 'mongodb';
+import { faker } from '@faker-js/faker';
+import {
+  getGroupsCollection,
+  findGroups,
+  createGroup,
+  updateGroup,
+  removeGroup,
+} from '../groups.getters';
+import { createGroup as createGroupDoc } from '../../../test-utils/factories';
+
+describe('db.groups', () => {
+  describe('getGroupsCollection', () => {
+    it('returns the "groups" collection', () => {
+      expect(getGroupsCollection().collectionName).toBe('groups');
+    });
+  });
+
+  describe('findGroups', () => {
+    it('returns groups matching the provided filter', async () => {
+      const clientId = faker.string.uuid();
+      const g1 = createGroupDoc({ clientId, name: 'Group A' });
+      const g2 = createGroupDoc({ clientId, name: 'Group B' });
+      const gOther = createGroupDoc({ clientId: faker.string.uuid(), name: 'Group C' });
+
+      await getGroupsCollection().insertMany([g1, g2, gOther]);
+
+      const result = await findGroups({ clientId });
+      const names = result.map((g) => g.name).sort();
+
+      expect(result).toHaveLength(2);
+      expect(names).toEqual(['Group A', 'Group B']);
+    });
+  });
+
+  describe('createGroup', () => {
+    it('inserts a group and returns insertedId', async () => {
+      const toInsert = createGroupDoc({ name: 'New Group' });
+
+      const insertedId = await createGroup(toInsert);
+      expect(insertedId).toBeInstanceOf(ObjectId);
+
+      const fromDb = await getGroupsCollection().findOne({ _id: insertedId });
+      expect(fromDb?.name).toBe('New Group');
+      expect(fromDb?.clientId).toBe(toInsert.clientId);
+    });
+  });
+
+  describe('updateGroup', () => {
+    it('updates the group and sets updatedAt, returning the updated document', async () => {
+      const original = createGroupDoc({ name: 'Before', description: 'Old desc' });
+      const { insertedId } = await getGroupsCollection().insertOne(original);
+      const before = await getGroupsCollection().findOne({ _id: insertedId });
+
+      // Add a small delay to ensure updatedAt will be different
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const res = await updateGroup(
+        { _id: insertedId },
+        { name: 'After', description: 'New desc' }
+      );
+
+      expect(res?._id).toEqual(insertedId);
+      expect(res?.name).toBe('After');
+      expect(res?.description).toBe('New desc');
+      expect(new Date(res!.updatedAt).getTime()).toBeGreaterThan(
+        new Date(before!.updatedAt).getTime()
+      );
+    });
+  });
+
+  describe('removeGroup', () => {
+    it('removes a group by string id', async () => {
+      const { insertedId } = await getGroupsCollection().insertOne(createGroupDoc());
+
+      const result = await removeGroup(insertedId.toHexString());
+      expect(result.deletedCount).toBe(1);
+
+      const check = await getGroupsCollection().findOne({ _id: insertedId });
+      expect(check).toBeNull();
+    });
+  });
+});

package/src/talkpilot/groups/__tests__/phone.utils.spec.ts

@@ -0,0 +1,32 @@
+import { enrichPhoneNumber, isValidE164 } from '../phone.utils';
+
+describe('Phone Utilities', () => {
+  describe('enrichPhoneNumber', () => {
+    it('should enrich Israeli number', () => {
+      const result = enrichPhoneNumber('+972507725874');
+      expect(result?.e164).toBe('+972507725874');
+      expect(result?.region).toBeDefined();
+      expect(result?.countryCallingCode).toBe('972');
+    });
+
+    it('should enrich US number', () => {
+      const result = enrichPhoneNumber('+12025551234');
+      expect(result?.region).toBe('US');
+      expect(result?.countryCallingCode).toBe('1');
+    });
+
+    it('should return null for invalid', () => {
+      expect(enrichPhoneNumber('invalid')).toBeNull();
+      expect(enrichPhoneNumber('0507725874')).toBeNull();
+    });
+  });
+
+  describe('isValidE164', () => {
+    it('should validate E.164 format', () => {
+      expect(isValidE164('+972508832983')).toBe(true);
+      expect(isValidE164('+12025551234')).toBe(true);
+      expect(isValidE164('0501234567')).toBe(false);
+      expect(isValidE164('invalid')).toBe(false);
+    });
+  });
+});

package/src/talkpilot/groups/groups.getters.ts

@@ -0,0 +1,27 @@
+import { getDb, ObjectId, Group } from '../index';
+import { Collection, Filter } from 'mongodb';
+
+export const getGroupsCollection = (): Collection<Group> => {
+  return getDb().collection<Group>('groups');
+};
+
+export const findGroups = async (filter: Filter<Group>): Promise<Group[]> => {
+  return await getGroupsCollection().find(filter).toArray();
+};
+
+export const createGroup = async (group: Group) => {
+  const { insertedId } = await getGroupsCollection().insertOne(group);
+  return insertedId;
+};
+
+export const updateGroup = async (filter: Filter<Group>, data: Partial<Group>) => {
+  return await getGroupsCollection().findOneAndUpdate(
+    filter,
+    { $set: { ...data, updatedAt: new Date() } },
+    { returnDocument: 'after' }
+  );
+};
+
+export const removeGroup = async (groupId: string) => {
+  return await getGroupsCollection().deleteOne({ _id: new ObjectId(groupId) });
+};

package/src/talkpilot/groups/groups.types.ts

@@ -0,0 +1,29 @@
+import { WithId } from 'mongodb';
+export type E164 = `+${string}`;
+export type CountryISO = Uppercase<string>;
+
+export type Phone = {
+  e164: E164;
+  region?: CountryISO;
+  countryCallingCode?: string;
+  national?: string;
+  ext?: string;
+  formatted?: string;
+};
+
+export type GroupContact = {
+  name: string;
+  phone: Phone;
+  gender: string;
+};
+
+export type Group = {
+  clientId: string;
+  createdAt: Date;
+  updatedAt: Date;
+  name: string;
+  description: string;
+  contacts: GroupContact[];
+};
+
+export type GroupDoc = WithId<Group>;

package/src/talkpilot/groups/index.ts

@@ -0,0 +1,2 @@
+export * from './groups.getters';
+export * from './groups.types';

package/src/talkpilot/groups/phone.utils.ts

@@ -0,0 +1,40 @@
+import { PhoneNumberUtil, PhoneNumberFormat } from 'google-libphonenumber';
+import type { Phone, E164, CountryISO } from './groups.types';
+
+const phoneUtil = PhoneNumberUtil.getInstance();
+
+export const enrichPhoneNumber = (e164: string): Phone | null => {
+  try {
+    const phoneNumber = phoneUtil.parse(e164, 'ZZ');
+    if (!phoneUtil.isValidNumber(phoneNumber)) {
+      return null;
+    }
+
+    const normalizedE164 = phoneUtil.format(phoneNumber, PhoneNumberFormat.E164) as E164;
+    const region = phoneUtil.getRegionCodeForNumber(phoneNumber) as CountryISO;
+    const countryCallingCode = phoneNumber.getCountryCode()?.toString();
+    const national = phoneNumber.getNationalNumber()?.toString();
+    const ext = phoneNumber.getExtension() || undefined;
+    const formatted = phoneUtil.format(phoneNumber, PhoneNumberFormat.INTERNATIONAL);
+
+    return {
+      e164: normalizedE164,
+      region,
+      countryCallingCode,
+      national,
+      ext,
+      formatted,
+    };
+  } catch (error) {
+    return null;
+  }
+};
+
+export const isValidE164 = (e164: string): boolean => {
+  try {
+    const phoneNumber = phoneUtil.parse(e164, 'ZZ');
+    return phoneUtil.isValidNumber(phoneNumber);
+  } catch (error) {
+    return false;
+  }
+};

package/src/talkpilot/index.ts

@@ -0,0 +1,27 @@
+import { Db, ObjectId as MongoObjectId } from 'mongodb';
+
+export * from './flows';
+export * from './results';
+export * from './sessions';
+export * from './phone_numbers';
+export * from './leads';
+export * from './clients';
+export * from './agents';
+export * from './plans';
+export * from './subscriptions';
+export * from './groups';
+export * from './calls';
+export * from './clientAudioBuffers/clientAudioBuffer.getters';
+export * from './clientsConfig';
+export { mongodbClient } from './mongodb-client';
+
+let db: Db;
+export const setDb = (d: Db) => {
+  db = d;
+};
+export const getDb = (): Db => {
+  if (!db) throw new Error('DB not initialised');
+  return db;
+};
+
+export const ObjectId = MongoObjectId;

package/src/talkpilot/leads/index.ts

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

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

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

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

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

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

@@ -0,0 +1,20 @@
+import { ObjectId } from 'mongodb';
+
+export interface LeadProperty {
+  name: string;
+  value: string;
+}
+
+export interface LeadItem {
+  callSid: string;
+  timestamp: Date;
+  properties?: LeadProperty[];
+}
+
+export interface Lead {
+  _id?: ObjectId;
+  flowId: ObjectId;
+  clientId: string;
+  createdAt: Date;
+  leads: LeadItem[];
+}

package/src/talkpilot/mongodb-client.ts

@@ -0,0 +1,78 @@
+import { MongoClient, Db } from 'mongodb';
+import { setDb } from './index';
+import { validateConfig, validateMongoUri } from '../utils/validation';
+
+class MongoDBClient {
+  private client: MongoClient | null = null;
+  private db: Db | null = null;
+
+  private extractDatabaseName(uri: string): string | null {
+    try {
+      const url = new URL(uri);
+      const dbName = url.pathname.slice(1);
+      return dbName || null;
+    } catch {
+      return null;
+    }
+  }
+
+  async connect(uri?: string, databaseName?: string): Promise<void> {
+    if (this.client) {
+      return;
+    }
+
+    const mongodbUri = uri || process.env.MONGO_URI || process.env.MONGODB_URI;
+    validateConfig('MONGO_URI', mongodbUri);
+    validateMongoUri(mongodbUri!);
+
+    try {
+      this.client = new MongoClient(mongodbUri!);
+      await this.client.connect();
+
+      const dbNameFromUri = this.extractDatabaseName(mongodbUri!);
+      const dbNameFromEnv = process.env.MONGODB_DB_NAME;
+      const dbName = databaseName || dbNameFromUri || dbNameFromEnv;
+
+      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.'
+        );
+      }
+
+      this.db = this.client.db(dbName);
+      setDb(this.db);
+      console.info(`[core-db] TalkPilot MongoDB connected: ${dbName}`);
+    } catch (error) {
+      console.error('[core-db] TalkPilot connection failed', error as Error);
+      throw error;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      try {
+        await this.client.close();
+        this.client = null;
+        this.db = null;
+        console.info('MongoDB disconnected successfully');
+      } catch (error) {
+        console.error('Error disconnecting from MongoDB', error as Error);
+        throw error;
+      }
+    }
+  }
+
+  getDb(): Db {
+    if (!this.db) {
+      throw new Error('Database not initialized. Call connect() first.');
+    }
+    return this.db;
+  }
+
+  isConnected(): boolean {
+    return this.client !== null && this.client !== undefined;
+  }
+}
+
+export const mongodbClient = new MongoDBClient();

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

@@ -0,0 +1,43 @@
+import {
+  getPhoneDataByPhoneNumber,
+  getPhoneNumbersCollection,
+  getClientPhoneNumber,
+} from '../phone_numbers.getter';
+import { getFlowsCollection } from '../../flows/flows.getter';
+import { createFlow, createPhoneNumber } from '../../../test-utils/factories';
+
+describe('db.phoneNumbers', () => {
+  describe('getPhoneDataByPhoneNumber', () => {
+    it('return phone number data with flow', async () => {
+      const flow = createFlow({ clientId: '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,
+        phone_number: phoneData.phone_number,
+        flow_id: flow._id,
+      });
+      // Specifically check if the flow was joined correctly
+      expect(result?.flow.flowName).toBe(flow.flowName);
+    });
+  });
+
+  describe('getClientPhoneNumber', () => {
+    it('return phone number by client id', async () => {
+      const flow = createFlow();
+      const phoneData = createPhoneNumber({ flow_id: flow._id });
+      
+      await getFlowsCollection().insertOne(flow);
+      await getPhoneNumbersCollection().insertOne(phoneData);
+
+      const result = await getClientPhoneNumber(phoneData.client_id);
+      expect(result).toBe(phoneData.phone_number);
+    });
+  });
+});

package/src/talkpilot/phone_numbers/index.ts

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

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

@@ -0,0 +1,47 @@
+import type { Collection } from 'mongodb';
+import { getDb, ObjectId } from '../index';
+import { findFlowById } from '../flows/flows.getter';
+import type { PhoneNumber, PhoneNumberWithFlow } from './phone_numbers.types';
+
+export const getPhoneNumbersCollection = (): Collection<PhoneNumber> =>
+  getDb().collection<PhoneNumber>('phone_numbers');
+
+export const getPhoneDataByPhoneNumber = async (
+  phoneNumber: string
+): Promise<PhoneNumberWithFlow | null> => {
+  const phoneData = await getPhoneNumbersCollection().findOne({ phone_number: phoneNumber });
+  if (!phoneData) return null;
+  const flow = await findFlowById(phoneData.flow_id, phoneData.client_id);
+  if (!flow) return null;
+  return { ...phoneData, flow };
+};
+
+export const getClientPhoneNumber = async (clientId: string): Promise<string | null> => {
+  return (await getPhoneNumbersCollection().findOne({ client_id: clientId }))?.phone_number ?? null;
+};
+
+export const getClientPhoneData = async (clientId: string): Promise<PhoneNumber | null> => {
+  const phoneNumberData = await getPhoneNumbersCollection().findOne({
+    client_id: clientId,
+  });
+  return phoneNumberData;
+};
+
+export const createPhoneNumberEntity = async (
+  phoneNumber: string,
+  flowId: string,
+  clientId: string,
+  isPrimary = true,
+): Promise<PhoneNumber> => {
+  await getPhoneNumbersCollection().insertOne({
+    phone_number: phoneNumber,
+    flow_id: new ObjectId(flowId),
+    client_id: clientId,
+    is_primary: isPrimary,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  });
+  const phoneNumberData = await getClientPhoneData(clientId);
+  if (!phoneNumberData) throw new Error('Failed to create phoneNumber');
+  return phoneNumberData;
+};

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

@@ -0,0 +1,14 @@
+export const phoneNumbersMongoSchema = {
+  bsonType: 'object',
+  required: ['client_id', 'flow_id', 'phone_number'],
+  properties: {
+    _id: { bsonType: 'objectId' },
+    client_id: { bsonType: 'string' },
+    flow_id: { bsonType: 'string' },
+    phone_number: { bsonType: 'string' },
+    is_primary: { bsonType: 'bool' },
+    createdAt: { bsonType: 'date' },
+    updatedAt: { bsonType: 'date' },
+  },
+  additionalProperties: false,
+} as const;

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

@@ -0,0 +1,15 @@
+import { ObjectId, WithId } from "mongodb";
+import { Flow } from "../flows/flows.types";
+
+export type PhoneNumber = {
+  _id?: ObjectId;
+  client_id: string;
+  flow_id: ObjectId;
+  phone_number: string;
+  subscriptionId?: string;
+  is_primary: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type PhoneNumberWithFlow = WithId<PhoneNumber> & { flow: Flow };

package/src/talkpilot/plans/index.ts

@@ -0,0 +1,2 @@
+export * from './plans.types';
+export * from './plans.getters';

package/src/talkpilot/plans/plans.getters.ts

@@ -0,0 +1,121 @@
+import { Plan, getDb, PlanDoc, PlanFilter, SimplePlanFilter, PlanQueryOptions } from '../index';
+import { ObjectId, Filter } from 'mongodb';
+
+export const getPlansCollection = () => {
+  return getDb().collection<Plan>('plans');
+};
+
+/**
+ * Converts a simple filter to MongoDB query format
+ */
+const buildSimpleQuery = (filter: SimplePlanFilter): Filter<Plan> => {
+  const query: Filter<Plan> = {};
+
+  if (filter._id) {
+    query._id = new ObjectId(filter._id);
+  }
+  if (filter.productKey !== undefined) {
+    query.productKey = filter.productKey;
+  }
+  if (filter.isActive !== undefined) {
+    query.isActive = filter.isActive;
+  }
+  if (filter.currency !== undefined) {
+    query.currency = filter.currency;
+  }
+  if (filter.region !== undefined) {
+    query.region = filter.region;
+  }
+  if (filter.countryCode !== undefined) {
+    query.countryCode = filter.countryCode;
+  }
+  if (filter.originalPlanId !== undefined) {
+    query.originalPlanId = filter.originalPlanId;
+  }
+
+  return query;
+};
+
+/**
+ * Generic function to find plans with flexible filtering
+ */
+export const findPlans = async (
+  filter?: PlanFilter,
+  options?: PlanQueryOptions
+): Promise<PlanDoc[]> => {
+  let query: Filter<Plan> = {};
+
+  if (filter) {
+    // Build the base query from simple filter properties
+    const simpleFilter: SimplePlanFilter = {
+      _id: filter._id,
+      productKey: filter.productKey,
+      isActive: filter.isActive,
+      currency: filter.currency,
+      region: filter.region,
+      countryCode: filter.countryCode,
+      originalPlanId: filter.originalPlanId,
+    };
+
+    // Apply simple filters if any are present
+    const baseQuery = buildSimpleQuery(simpleFilter);
+    if (Object.keys(baseQuery).length > 0) {
+      query = baseQuery;
+    }
+
+    // Add OR conditions if present
+    if (filter.or && filter.or.length > 0) {
+      query.$or = filter.or.map(buildSimpleQuery);
+    }
+
+    // Add AND conditions if present
+    if (filter.and && filter.and.length > 0) {
+      query.$and = filter.and.map(buildSimpleQuery);
+    }
+  }
+
+  let queryBuilder = getPlansCollection().find(query);
+
+  if (options?.sort) {
+    queryBuilder = queryBuilder.sort(options.sort);
+  }
+  if (options?.limit) {
+    queryBuilder = queryBuilder.limit(options.limit);
+  }
+
+  return await queryBuilder.toArray();
+};
+
+export const createPlanDoc = async (
+  planData: Omit<Plan, 'createdAt' | 'updatedAt'>
+): Promise<PlanDoc> => {
+  const now = new Date();
+  const result = await getPlansCollection().insertOne({
+    ...planData,
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  const plans = await findPlans({ _id: result.insertedId });
+  if (!plans[0]) throw new Error('Failed to retrieve created plan');
+  return plans[0];
+};
+
+export const updatePlanDoc = async (
+  planId: ObjectId,
+  updates: Partial<Pick<Plan, 'isActive'>>
+): Promise<PlanDoc | null> => {
+  const result = await getPlansCollection().findOneAndUpdate(
+    { _id: planId },
+    {
+      $set: {
+        ...updates,
+        updatedAt: new Date(),
+      },
+    },
+    {
+      returnDocument: 'after',
+    }
+  );
+  return result;
+};