@talkpilot/core-db 1.0.1

package/src/talkpilot/plans/plans.types.ts

@@ -0,0 +1,84 @@
+import { Sort, ObjectId, WithId } from 'mongodb';
+
+export const CURRENCY_CODES = ['ILS', 'USD', 'EUR'] as const;
+export type CurrencyCode = (typeof CURRENCY_CODES)[number];
+
+/** Required fields for creating a new plan */
+export const PLAN_REQUIRED_FIELDS = [
+  'productKey',
+  'name',
+  'monthlyCallQuota',
+  'currency',
+  'priceMonthlyMinor',
+  'isActive',
+];
+
+/** All allowed fields that can be set/updated on a plan (excluding system fields) */
+export const PLAN_ALLOWED_FIELDS = [
+  'productKey',
+  'name',
+  'monthlyCallQuota',
+  'currency',
+  'priceMonthlyMinor',
+  'region',
+  'countryCode',
+  'isActive',
+  'originalPlanId',
+  'tax',
+  'metadata',
+  'updatedAt',
+];
+
+/** Logical product family, like "basic-500". Multiple regional variants can share it. */
+export type ProductKey = 'basic-500' | 'pro-1100' | 'scale-6000' | (string & {});
+
+/** Optional targeting to keep variants explicit */
+export type RegionCode = 'IL' | 'EU' | 'US' | (string & {});
+export type CountryCode = 'IL' | 'DE' | 'FR' | 'ES' | 'GB' | (string & {});
+
+export type Tax = {
+  vatIncluded: boolean;
+  vatRatePct: number;
+  countryCode?: CountryCode;
+};
+
+export type Plan = {
+  productKey: ProductKey;
+  name: string;
+  monthlyCallQuota: number;
+  currency: CurrencyCode;
+  priceMonthlyMinor: number;
+  region?: RegionCode;
+  countryCode?: CountryCode;
+  isActive: boolean;
+  isFree?: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+  originalPlanId?: string;
+  tax?: Tax;
+  metadata?: Record<string, unknown>;
+};
+
+export type SimplePlanFilter = {
+  _id?: ObjectId | string;
+  productKey?: ProductKey;
+  isActive?: boolean;
+  currency?: CurrencyCode;
+  region?: RegionCode;
+  countryCode?: CountryCode;
+  originalPlanId?: string;
+};
+
+export type PlanFilter = SimplePlanFilter & {
+  or?: SimplePlanFilter[];
+  and?: SimplePlanFilter[];
+};
+
+export type PlanQueryOptions = {
+  sort?: Sort;
+  limit?: number;
+};
+
+// Convenient aliases
+export type PlanDoc = WithId<Plan>;
+export type Plans = PlanDoc[];

package/src/talkpilot/results/index.ts

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

package/src/talkpilot/results/results.getter.ts

@@ -0,0 +1,26 @@
+import type { Collection } from 'mongodb';
+import { getDb, ObjectId, Session } from '../index';
+import type { Result } from './results.types';
+
+export const getResultsCollection = (): Collection<Result> => getDb().collection<Result>('results');
+
+export const createRunId = (): string => {
+  return `run_${new ObjectId().toString()}`;
+};
+
+export const initializeResultDocument = async (
+  clientId: string,
+  session?: Session
+): Promise<Result> => {
+  const { insertedId } = await getResultsCollection().insertOne({
+    runId: createRunId(),
+    date: new Date(),
+    calls: [],
+    sessionId: session ? session._id!.toString() : 'incomingCall',
+    sessionName: session ? session.session_name : 'incomingCall',
+    clientId,
+  });
+  const result = await getResultsCollection().findOne({ _id: insertedId });
+  if (!result) throw new Error('Failed to initialized result');
+  return result;
+};

package/src/talkpilot/results/results.schema.ts

@@ -0,0 +1,25 @@
+export const resultMongoSchema = {
+  bsonType: 'object',
+  required: [
+    '_id',
+    'sessionId',
+    'status',
+    'callLength',
+    'date',
+    'userAnswer',
+    'systemSessionId',
+    'clientId',
+  ],
+  properties: {
+    _id: { bsonType: 'objectId' },
+    sessionId: { bsonType: 'string' },
+    status: { bsonType: 'string' },
+    callLength: { bsonType: 'string' },
+    date: { bsonType: 'date' },
+    userAnswer: { bsonType: 'string' },
+    recordingUrl: { bsonType: ['string', 'null'] },
+    systemSessionId: { bsonType: 'string' },
+    clientId: { bsonType: 'string' },
+  },
+  additionalProperties: false,
+} as const;

package/src/talkpilot/results/results.types.ts

@@ -0,0 +1,32 @@
+import { ObjectId } from 'mongodb';
+
+export interface Result {
+  _id?: ObjectId;
+  calls: CallResult[];
+  clientId: string;
+  date: Date;
+  runId: string;
+  sessionId: ObjectId | string;
+  sessionName: string;
+}
+
+export interface CallResult {
+  callSid: string;
+  status: string;
+  date: Date;
+  statuses: string[];
+  userAnswer: string | null;
+  color: string | null;
+  name: string | null;
+  callLength: string;
+  answeredBy: string | null;
+  to: string;
+  from: string;
+  transcription: TranscriptionSegment[];
+  flowId: ObjectId | string;
+  recordingUrl: string | null;
+}
+
+export type TranscriptionSegment =
+  | { assistant: string; user?: never }
+  | { user: string; assistant?: never };

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

@@ -0,0 +1,43 @@
+import { findSessionOfIncomingCall, getSessionsCollection } from '../sessions.getter';
+import { getFlowsCollection } from '../../flows/flows.getter';
+import { getPhoneNumbersCollection } from '../../phone_numbers/phone_numbers.getter';
+import { createFlow, createPhoneNumber, createSession } from '../../../test-utils/factories';
+import { faker } from '@faker-js/faker';
+
+describe('sessions', () => {
+  describe('findSessionOfIncomingCall()', () => {
+    it('returns session by incoming phone number', async () => {
+      const to = faker.phone.number();
+      const from = faker.phone.number();
+      const flow = createFlow();
+      const phoneNumberData = createPhoneNumber({ phone_number: to, flow_id: flow._id });
+      const json = {
+        [faker.lorem.word()]: faker.lorem.sentence(),
+        [faker.lorem.word()]: faker.number.int(),
+        [faker.lorem.word()]: faker.datatype.boolean(),
+        [faker.lorem.word()]: faker.internet.email(),
+      };
+
+      const session = createSession({
+        flow_id: flow._id,
+        phone_numbers: [{ phoneNumber: from, gender: 'male', name: 'yakov' }],
+        json,
+      });
+
+      await getFlowsCollection().insertOne(flow);
+      await getPhoneNumbersCollection().insertOne(phoneNumberData);
+      await getSessionsCollection().insertOne(session);
+
+      const result = await findSessionOfIncomingCall(from, to);
+      expect(result).toBeDefined();
+      expect(result?.phone_numbers[0].phoneNumber).toEqual(from);
+      expect(result?.flow_id).toEqual(flow._id);
+      expect(result?.json).toEqual(json);
+    });
+
+    it('returns null if receiver phone number is not found', async () => {
+      const result = await findSessionOfIncomingCall('any-from', 'non-existent-to');
+      expect(result).toBeNull();
+    });
+  });
+});

package/src/talkpilot/sessions/index.ts

@@ -0,0 +1,2 @@
+export { getSessionsCollection } from './sessions.getter';
+export type { Session } from './sessions.types';

package/src/talkpilot/sessions/sessions.getter.ts

@@ -0,0 +1,28 @@
+import { ObjectId } from 'mongodb';
+import type { Collection, WithId } from 'mongodb';
+import { getDb, getPhoneNumbersCollection } from '../index';
+import type { Session } from './sessions.types';
+
+export const getSessionsCollection = (): Collection<Session> =>
+  getDb().collection<Session>('sessions');
+
+export const findSessionById = (
+  sessionId: ObjectId,
+  clientId: string
+): Promise<WithId<Session> | null> => {
+  return getSessionsCollection().findOne({ _id: sessionId, clientId: clientId });
+};
+
+export const findSessionOfIncomingCall = async (from: string, to: string) => {
+  const receiverPhoneData = await getPhoneNumbersCollection().findOne({ phone_number: to });
+  if (!receiverPhoneData) {
+    return null;
+  }
+  const session = await getSessionsCollection().findOne({
+    flow_id: new ObjectId(receiverPhoneData.flow_id),
+    phone_numbers: {
+      $elemMatch: { phoneNumber: from },
+    },
+  });
+  return session;
+};

package/src/talkpilot/sessions/sessions.schema.ts

@@ -0,0 +1,34 @@
+export const sessionMongoSchema = {
+  bsonType: 'object',
+  required: ['session_name'],
+  properties: {
+    _id: { bsonType: 'objectId' },
+    session_name: { bsonType: 'string' },
+    company_name: { bsonType: ['string', 'null'] },
+    flow_id: { bsonType: ['objectId', 'string', 'null'] },
+    metaKeys: {
+      bsonType: ['array', 'null'],
+      items: {
+        bsonType: 'object',
+        required: ['key'],
+        properties: {
+          key: { bsonType: 'string' },
+          value: { bsonType: 'string' },
+        },
+      },
+    },
+    phone_numbers: {
+      bsonType: 'array',
+      items: {
+        bsonType: 'object',
+        required: ['name', 'phoneNumber'],
+        properties: {
+          name: { bsonType: 'string' },
+          phoneNumber: { bsonType: 'string' },
+        },
+      },
+    },
+    voice: { bsonType: ['string', 'null'] },
+  },
+  additionalProperties: false,
+} as const;

package/src/talkpilot/sessions/sessions.types.ts

@@ -0,0 +1,28 @@
+import { ObjectId } from 'mongodb';
+
+export type Session = {
+  _id?: ObjectId;
+
+  session_name: string;
+  company_name?: string | null;
+  flow_id?: ObjectId | string | null;
+  clientId: string;
+
+  metaKeys?: Array<{
+    key: string;
+    value?: string;
+  }> | null;
+
+  phone_numbers: Array<{
+    name: string;
+    phoneNumber: string;
+    gender: 'male' | 'female';
+  }>;
+
+  voice?: string | null;
+  json: Record<string, any> | null;
+
+  // Timestamps
+  createdAt?: Date;
+  updatedAt?: Date;
+};

package/src/talkpilot/subscriptions/__tests__/subscriptions.getters.utils.spec.ts

@@ -0,0 +1,42 @@
+import { ObjectId } from 'mongodb';
+import { buildSimpleQuery, buildDateRangeFilter } from '../subscriptions.getters.utils';
+import { SimpleSubscriptionFilter } from '../subscriptions.types';
+
+describe('subscriptions.getters.utils', () => {
+  describe('buildSimpleQuery', () => {
+    it('returns empty query when filter is empty', () => {
+      const filter: SimpleSubscriptionFilter = {};
+      const result = buildSimpleQuery(filter);
+      expect(result).toEqual({});
+    });
+
+    it('converts _id string to ObjectId', () => {
+      const id = '507f1f77bcf86cd799439011';
+      const filter: SimpleSubscriptionFilter = { _id: id };
+      const result = buildSimpleQuery(filter);
+      expect(result._id).toBeInstanceOf(ObjectId);
+      expect((result._id as ObjectId).toHexString()).toBe(id);
+    });
+
+    it('includes valid simple fields', () => {
+      const filter: SimpleSubscriptionFilter = {
+        clientId: 'abc',
+        isActive: true,
+      };
+      const result = buildSimpleQuery(filter);
+      expect(result).toEqual({ clientId: 'abc', isActive: true });
+    });
+  });
+
+  describe('buildDateRangeFilter', () => {
+    it('returns a mongo date range filter', () => {
+      const from = new Date('2023-01-01');
+      const to = new Date('2023-01-02');
+      const result = buildDateRangeFilter(from, to);
+      expect(result).toEqual({
+        $gte: from,
+        $lt: to,
+      });
+    });
+  });
+});

package/src/talkpilot/subscriptions/index.ts

@@ -0,0 +1,3 @@
+export * from './subscriptions.types';
+export * from './subscriptions.getters';
+export * from './subscriptions.getters.utils';

package/src/talkpilot/subscriptions/subscriptions.getters.ts

@@ -0,0 +1,147 @@
+import { getDb } from '../index';
+import {
+  Subscription,
+  SubscriptionDoc,
+  SimpleSubscriptionFilter,
+  SubscriptionFilter,
+  SubscriptionQueryOptions,
+} from './subscriptions.types';
+import { ObjectId, Filter } from 'mongodb';
+import { buildSimpleQuery } from './subscriptions.getters.utils';
+
+export const getSubscriptionsCollection = () => {
+  return getDb().collection<Subscription>('subscriptions');
+};
+
+/**
+ * A simple filter for Subscription: each field may be a value or a MongoDB operator expression
+ */
+
+export const findSubscriptions = async (
+  filter?: SubscriptionFilter,
+  options?: SubscriptionQueryOptions
+): Promise<SubscriptionDoc[]> => {
+  let query: Filter<Subscription> = {};
+
+  if (filter) {
+    const simpleFilter: SimpleSubscriptionFilter = {
+      _id: filter._id,
+      clientId: filter.clientId,
+      planId: filter.planId,
+      startDate: filter.startDate,
+      endDate: filter.endDate,
+      isActive: filter.isActive,
+      createdAt: filter.createdAt,
+      nextRenewalDate: filter.nextRenewalDate,
+    };
+    const baseQuery = buildSimpleQuery(simpleFilter);
+    if (Object.keys(baseQuery).length > 0) {
+      query = baseQuery;
+    }
+    if (filter.or && filter.or.length > 0) {
+      query.$or = filter.or.map(buildSimpleQuery);
+    }
+    if (filter.and && filter.and.length > 0) {
+      query.$and = filter.and.map(buildSimpleQuery);
+    }
+  }
+
+  let queryBuilder = getSubscriptionsCollection().find(query);
+  if (options?.sort) {
+    queryBuilder = queryBuilder.sort(options.sort);
+  }
+  if (options?.limit) {
+    queryBuilder = queryBuilder.limit(options.limit);
+  }
+
+  return await queryBuilder.toArray();
+};
+
+export const createSubscriptionDoc = async (
+  subscriptionData: Omit<Subscription, 'createdAt' | 'updatedAt'>
+): Promise<SubscriptionDoc> => {
+  const now = new Date();
+  const result = await getSubscriptionsCollection().insertOne({
+    ...subscriptionData,
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  const subscriptions = await findSubscriptions({ _id: result.insertedId });
+  if (!subscriptions[0]) throw new Error('Failed to retrieve created subscription');
+  return subscriptions[0];
+};
+
+export const updateSubscriptionDoc = async (
+  subscriptionId: ObjectId,
+  updates: Partial<Subscription>
+): Promise<SubscriptionDoc | null> => {
+  return await getSubscriptionsCollection().findOneAndUpdate(
+    { _id: subscriptionId },
+    {
+      $set: {
+        ...updates,
+        updatedAt: new Date(),
+      },
+    },
+    {
+      returnDocument: 'after',
+    }
+  );
+};
+
+export const incrementSubscriptionUsage = async (
+  subscriptionId: ObjectId,
+  amount: number = 1
+): Promise<SubscriptionDoc | null> => {
+  const fieldToIncrement = 'cycles.$[activeCycle].usage.usedCalls';
+  return await getSubscriptionsCollection().findOneAndUpdate(
+    { _id: subscriptionId, 'cycles.isActive': true },
+    {
+      $inc: { [fieldToIncrement]: amount },
+      $set: { updatedAt: new Date() },
+    },
+    {
+      arrayFilters: [{ 'activeCycle.isActive': true }],
+      returnDocument: 'after',
+    }
+  );
+};
+
+export const deactivateCurrentSubscriptionCycle = async (
+  subscriptionId: ObjectId,
+  nextRenewalDate: Date
+): Promise<void> => {
+  await getSubscriptionsCollection().updateOne(
+    { _id: subscriptionId, 'cycles.isActive': true },
+    {
+      $set: {
+        'cycles.$[activeCycle].isActive': false,
+        nextRenewalDate: nextRenewalDate,
+        updatedAt: new Date(),
+      },
+    },
+    {
+      arrayFilters: [{ 'activeCycle.isActive': true }],
+    }
+  );
+};
+
+export const pushNewSubscriptionCycle = async (
+  subscriptionId: ObjectId,
+  newCycle: Subscription['cycles'][number]
+): Promise<SubscriptionDoc | null> => {
+  const result = await getSubscriptionsCollection().findOneAndUpdate(
+    { _id: subscriptionId },
+    {
+      $push: {
+        cycles: newCycle,
+      },
+    },
+    {
+      returnDocument: 'after',
+    }
+  );
+
+  return result;
+};

package/src/talkpilot/subscriptions/subscriptions.getters.utils.ts

@@ -0,0 +1,26 @@
+import { ObjectId, Filter } from 'mongodb';
+import { Subscription, SimpleSubscriptionFilter, simpleFields, SimpleField } from '../index';
+
+export const buildSimpleQuery = (filter: SimpleSubscriptionFilter): Filter<Subscription> => {
+  const query: Filter<Subscription> = {};
+
+  if (filter._id) {
+    query._id = new ObjectId(filter._id);
+  }
+
+  simpleFields.forEach((field: SimpleField) => {
+    const val = filter[field];
+    if (val !== undefined) {
+      query[field] = val as any;
+    }
+  });
+
+  return query;
+};
+
+export const buildDateRangeFilter = (from: Date, to: Date) => {
+  return {
+    $gte: from,
+    $lt: to,
+  };
+};

package/src/talkpilot/subscriptions/subscriptions.types.ts

@@ -0,0 +1,65 @@
+import { Filter, ObjectId, WithId, Sort } from 'mongodb';
+import { PlanDoc } from '../plans/plans.types';
+
+export type SubscriptionCycle = {
+  usage: {
+    usedCalls: number;
+  };
+  startDate: Date;
+  endDate: Date;
+  cycleNumber: number;
+  isActive: boolean;
+};
+
+export type Subscription = {
+  clientId: string;
+  planId: string;
+  planSnapshot: PlanDoc;
+  startDate: Date;
+  endDate?: Date; // optional, if we want to predefine the end date
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+  nextRenewalDate: Date;
+  cycles: SubscriptionCycle[];
+};
+
+export type SubscriptionDoc = WithId<Subscription>;
+export type Subscriptions = SubscriptionDoc[];
+
+// Define which Subscription fields we allow in a simple filter
+export const simpleFields = [
+  'clientId',
+  'planId',
+  'startDate',
+  'endDate',
+  'isActive',
+  'createdAt',
+  'nextRenewalDate',
+] as const;
+export type SimpleField = (typeof simpleFields)[number];
+
+/**
+ * A simple filter for Subscription: each field may be a literal or a MongoDB operator
+ */
+export type SimpleSubscriptionFilter = {
+  _id?: ObjectId | string;
+} & {
+  [K in keyof Subscription]?: Filter<Subscription>[K];
+};
+
+/**
+ * Composite filter allowing nested OR/AND arrays
+ */
+export type SubscriptionFilter = SimpleSubscriptionFilter & {
+  or?: SimpleSubscriptionFilter[];
+  and?: SimpleSubscriptionFilter[];
+};
+
+/**
+ * Query options for sorting and limiting results
+ */
+export type SubscriptionQueryOptions = {
+  sort?: Sort;
+  limit?: number;
+};

package/src/test-utils/db-utils.ts

@@ -0,0 +1,24 @@
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { MongoClient, Db } from 'mongodb';
+import { setDb, setMunicipalDataDb } from '../index';
+
+let mongoServer: MongoMemoryServer;
+let client: MongoClient;
+
+export async function initTestDb(): Promise<Db> {
+  mongoServer = await MongoMemoryServer.create({
+    instance: { ip: '127.0.0.1' },
+  });
+  client = new MongoClient(mongoServer.getUri());
+  await client.connect();
+  const talkpilotDb = client.db();
+  const municipalDb = client.db('municipal-data');
+  setDb(talkpilotDb);
+  setMunicipalDataDb(municipalDb);
+  return talkpilotDb;
+}
+
+export async function closeTestDb(): Promise<void> {
+  if (client) await client.close();
+  if (mongoServer) await mongoServer.stop();
+}

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

@@ -0,0 +1,12 @@
+export * from './talkpilot/agents';
+export * from './talkpilot/calls';
+export * from './talkpilot/clientAudioBuffers';
+export * from './talkpilot/clientsConfig';
+export * from './talkpilot/flows';
+export * from './talkpilot/groups';
+export * from './talkpilot/phone_numbers';
+export * from './talkpilot/sessions';
+export * from './municipal/cities';
+export * from './municipal/departmentsSubjects';
+export * from './municipal/streets';
+export * from './municipal/tickets';

package/src/test-utils/factories/municipal/cities.ts

@@ -0,0 +1,16 @@
+import { Factory } from 'fishery';
+import { ObjectId } from 'mongodb';
+import { faker } from '@faker-js/faker';
+import type { City } from '../../../municipal/cities/cities.types';
+
+export const cityFactory = Factory.define<City>(() => ({
+  _id: new ObjectId(),
+  name: faker.location.city().toLowerCase().replace(/\s/g, '_'),
+  displayName: faker.location.city(),
+  createdAt: new Date(),
+  updatedAt: new Date(),
+}));
+
+export function createCity(overrides?: Partial<City>): City {
+  return cityFactory.build(overrides);
+}

package/src/test-utils/factories/municipal/departmentsSubjects.ts

@@ -0,0 +1,29 @@
+import { Factory } from 'fishery';
+import { ObjectId } from 'mongodb';
+import { faker } from '@faker-js/faker';
+import type {
+  DepartmentSubject,
+  CityName,
+} from '../../../municipal/departmentsSubjects/departmentsSubjects.types';
+
+const VALID_CITIES: CityName[] = ['ashdod', 'maltar', 'billit', 'hashkelon', 'tests'];
+
+export const departmentSubjectFactory = Factory.define<DepartmentSubject>(() => ({
+  _id: new ObjectId(),
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  subjectName: faker.lorem.words(2),
+  subject_id: faker.string.numeric(4),
+  sub_subject_name: faker.lorem.word(),
+  sub_subject_id: faker.string.numeric(4),
+  descriptions: [faker.lorem.sentence()],
+  cityName: faker.helpers.arrayElement(VALID_CITIES),
+  guidelines: null,
+  instructions: [],
+  communications: [],
+  sla: faker.number.int({ min: 24, max: 720 }),
+}));
+
+export function createDepartmentSubject(overrides?: Partial<DepartmentSubject>): DepartmentSubject {
+  return departmentSubjectFactory.build(overrides);
+}