@talkpilot/core-db 1.0.1

package/src/talkpilot/calls/calls.types.ts

@@ -0,0 +1,45 @@
+import { ObjectId, WithId } from 'mongodb';
+import { TranscriptionSegment } from '../results/results.types';
+
+export type Call = {
+  callSid: string;
+  flowId: ObjectId;
+  clientId: string;
+  sessionId: ObjectId | null;
+  runId?: string;
+  resultId: ObjectId;
+  customerPhoneNumber: string;
+  agentPhoneNumber: string;
+  isIncomingCall: boolean;
+  isOutgoingCall: boolean;
+  callLength: number;
+  transcription?: TranscriptionSegment[];
+  status?: string;
+  leads?: Record<string, string>[];
+  summary?: string;
+  recordingUrl?: string;
+  env: string;
+  updatedAt: Date;
+  createdAt: Date;
+  agentHungUp?: boolean;
+};
+
+export type ImmutableCallFields =
+  | 'customerPhoneNumber'
+  | 'agentPhoneNumber'
+  | 'isIncomingCall'
+  | 'isOutgoingCall'
+  | 'sessionId'
+  | 'callSid'
+  | 'flowId'
+  | 'clientId'
+  | 'runId'
+  | 'resultId'
+  | 'env'
+  | 'createdAt';
+
+export type CallUpdateParams = Partial<Omit<Call, ImmutableCallFields>>;
+
+export type CallDoc = WithId<Call>;
+
+export type CallsByHour = { hour: string; calls: number };

package/src/talkpilot/calls/index.ts

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

package/src/talkpilot/clientAudioBuffers/__tests__/clientAudioBuffer.getters.spec.ts

@@ -0,0 +1,78 @@
+import {
+  getClientAudioBuffersCollection,
+  insertClientAudioBuffer,
+  findClientAudioBuffersByCallSidAndRange,
+  getMergedAudioByCallSid,
+} from '../clientAudioBuffer.getters';
+import { ObjectId } from 'mongodb';
+import { createAudioBufferInput } from '../../../test-utils/factories';
+
+describe('clientAudioBuffers getters', () => {
+  it('should return the "clientAudioBuffers" collection', () => {
+    const collection = getClientAudioBuffersCollection();
+    expect(collection.collectionName).toBe('clientAudioBuffers');
+  });
+
+  it('should insert a client audio buffer and return insertedId', async () => {
+    const inputToCheck = createAudioBufferInput();
+    const result = await insertClientAudioBuffer(inputToCheck);
+    expect(result.insertedId).toBeInstanceOf(ObjectId);
+
+    const savedDoc = await getClientAudioBuffersCollection().findOne({ _id: result.insertedId });
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.createdAt).toBeInstanceOf(Date);
+    expect(savedDoc?.expiresAt).toBeInstanceOf(Date);
+  });
+
+  it('should return only buffers in the specified bucketStartMs range', async () => {
+    const callSid = 'CA1234567890abcdef1234567890abcdef';
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 500 }));
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 1000 }));
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 3000 }));
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 6000 }));
+
+    const result = await findClientAudioBuffersByCallSidAndRange(callSid, 500, 3000);
+    expect(result).toHaveLength(3);
+    const bucketStartValues = result.map((doc) => doc.bucketStartMs);
+    const bucketStartsSorted = bucketStartValues.sort((a, b) => a - b);
+    expect(bucketStartsSorted).toEqual([500, 1000, 3000]);
+  });
+
+  it('should return all buffers when no range is provided', async () => {
+    const callSid = 'CA1234567890abcdef1234567890abcdeg';
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 500 }));
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 1000 }));
+    await insertClientAudioBuffer(createAudioBufferInput({ callSid, bucketStartMs: 3000 }));
+
+    const result = await findClientAudioBuffersByCallSidAndRange(callSid);
+    expect(result).toHaveLength(3);
+    const bucketStartValues = result.map((doc) => doc.bucketStartMs);
+    const bucketStartsSorted = bucketStartValues.sort((a, b) => a - b);
+    expect(bucketStartsSorted).toEqual([500, 1000, 3000]);
+  });
+
+  it('should merge audio buffers by callSid in chronological order', async () => {
+    const callSid = 'CA1234567890abcdef1234567890abcdeh';
+
+    const firstBuffer = Buffer.from([1, 2]);
+    const secondBuffer = Buffer.from([3]);
+    const thirdBuffer = Buffer.from([4, 5]);
+
+    await insertClientAudioBuffer(
+      createAudioBufferInput({ callSid, bucketStartMs: 1000, data: secondBuffer })
+    );
+    await insertClientAudioBuffer(
+      createAudioBufferInput({ callSid, bucketStartMs: 500, data: firstBuffer })
+    );
+    await insertClientAudioBuffer(
+      createAudioBufferInput({ callSid, bucketStartMs: 3000, data: thirdBuffer })
+    );
+
+    const merged = await getMergedAudioByCallSid(callSid);
+    const expected = Buffer.concat([firstBuffer, secondBuffer, thirdBuffer]);
+
+    expect(merged).toBeInstanceOf(Buffer);
+    expect(merged.length).toBe(expected.length);
+    expect(merged.equals(expected)).toBe(true);
+  });
+});

package/src/talkpilot/clientAudioBuffers/clientAudioBuffer.getters.ts

@@ -0,0 +1,101 @@
+import { getDb } from '@core/db';
+import {
+  ClientAudioBufferDoc,
+  ClientAudioBufferType,
+  CreateAudioBufferInput,
+} from './clientsAudioBuffers.types';
+import { Collection, InsertOneResult } from 'mongodb';
+
+const getClientAudioBuffersCollection = (): Collection<ClientAudioBufferType> => {
+  return getDb().collection<ClientAudioBufferType>('clientAudioBuffers');
+};
+
+const insertClientAudioBuffer = async (
+  audioBufferInput: CreateAudioBufferInput
+): Promise<InsertOneResult<ClientAudioBufferType>> => {
+  const collection = getClientAudioBuffersCollection();
+  const realtimeDate = new Date();
+  const ttlMs = audioBufferInput.ttlMs ?? 3600_000;
+  const expiresAt = new Date(realtimeDate.getTime() + ttlMs);
+
+  const inputFieldsForDocument = {
+    callSid: audioBufferInput.callSid,
+    clientId: audioBufferInput.clientId,
+    bucketStartMs: audioBufferInput.bucketStartMs,
+    bucketDurationMs: audioBufferInput.bucketDurationMs,
+    data: audioBufferInput.data,
+  };
+  const clientAudioBufferMongoDocument: ClientAudioBufferType = {
+    ...inputFieldsForDocument,
+    codec: 'mulaw',
+    sampleRateHz: 8000,
+    channels: 1,
+    createdAt: realtimeDate,
+    expiresAt: expiresAt,
+  };
+  return collection.insertOne(clientAudioBufferMongoDocument);
+};
+
+const findClientAudioBuffersByCallSidAndRange = async (
+  callSid: string,
+  startMs?: number,
+  endMs?: number
+): Promise<ClientAudioBufferDoc[]> => {
+  const collection = getClientAudioBuffersCollection();
+  if (startMs === undefined) {
+    return collection.find({ callSid }).toArray();
+  }
+  const endMsToUse = endMs ?? Date.now();
+  return collection
+    .find({
+      callSid,
+      bucketStartMs: {
+        $gte: startMs,
+        $lte: endMsToUse,
+      },
+    })
+    .toArray();
+};
+
+const getAudioChunksByCallSid = async (callSid: string): Promise<Buffer[]> => {
+  const collection = getClientAudioBuffersCollection();
+  const chunks = await collection.find({ callSid }).toArray();
+
+  if (!chunks.length) {
+    return [];
+  }
+
+  chunks.sort((a: any, b: any) => a.bucketStartMs - b.bucketStartMs);
+
+  return chunks.map((chunk: any) => {
+    const data: any = chunk.data;
+
+    if (Buffer.isBuffer(data)) {
+      return data;
+    }
+
+    if (data?.buffer) {
+      return Buffer.from(data.buffer);
+    }
+
+    return Buffer.from(data);
+  });
+};
+
+const getMergedAudioByCallSid = async (callSid: string): Promise<Buffer> => {
+  const buffers = await getAudioChunksByCallSid(callSid);
+
+  if (!buffers.length) {
+    return Buffer.alloc(0);
+  }
+
+  return Buffer.concat(buffers);
+};
+
+export {
+  insertClientAudioBuffer,
+  getClientAudioBuffersCollection,
+  findClientAudioBuffersByCallSidAndRange,
+  getAudioChunksByCallSid,
+  getMergedAudioByCallSid,
+};

package/src/talkpilot/clientAudioBuffers/clientsAudioBuffers.types.ts

@@ -0,0 +1,25 @@
+import { WithId } from 'mongodb';
+
+export type ClientAudioBufferType = {
+  callSid: string;
+  clientId: string;
+  bucketStartMs: number;
+  bucketDurationMs: number;
+  codec: 'mulaw';
+  sampleRateHz: 8000;
+  channels: 1;
+  data: Buffer;
+  expiresAt: Date;
+  createdAt: Date;
+};
+
+export type CreateAudioBufferInput = {
+  callSid: string;
+  clientId: string;
+  bucketStartMs: number;
+  bucketDurationMs: number;
+  data: Buffer;
+  ttlMs?: number;
+};
+
+export type ClientAudioBufferDoc = WithId<ClientAudioBufferType>;

package/src/talkpilot/clients/clients.getters.ts

@@ -0,0 +1,11 @@
+import { getDb, Client } from '../index';
+import { Collection } from 'mongodb';
+
+export const getClientsCollection = (): Collection<Client> => {
+  return getDb().collection<Client>('clients');
+};
+
+export const getClientByAPIKey = async (apiKey: string): Promise<Client | null> => {
+  const client = await getClientsCollection().findOne({ apiKey, isActive: true });
+  return client ? client : null;
+};

package/src/talkpilot/clients/clients.types.ts

@@ -0,0 +1,12 @@
+import { ObjectId } from 'mongodb';
+
+export type Client = {
+  _id?: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+  clientId: string;
+  isActive?: boolean | null;
+  apiKey?: string | null;
+  credits: number;
+  managedBy?: string;
+};

package/src/talkpilot/clients/index.ts

@@ -0,0 +1,2 @@
+export * from './clients.getters';
+export type { Client } from './clients.types';

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

@@ -0,0 +1,28 @@
+import { createClientConfigDoc, getClientConfig } from '../clientsConfig.getters';
+import { createClientConfig } from '../../../test-utils/factories';
+
+describe('db.clientsConfig', () => {
+  describe('getClientConfig', () => {
+    it('should return client config by clientId', async () => {
+      const clientId = 'test-client-id';
+      const clientConfig = createClientConfig({
+        clientId,
+        products: { feature1: true, feature2: false } as any,
+      });
+
+      await createClientConfigDoc(clientConfig);
+
+      const result = await getClientConfig(clientId);
+
+      expect(result).toMatchObject({
+        clientId,
+        products: { feature1: true, feature2: false },
+      });
+    });
+
+    it('should return null for non-existent clientId', async () => {
+      const result = await getClientConfig('non-existent-client');
+      expect(result).toBeNull();
+    });
+  });
+});

package/src/talkpilot/clientsConfig/clientsConfig.getters.ts

@@ -0,0 +1,20 @@
+import { ClientConfigDoc, getDb } from '../index';
+import { Collection } from 'mongodb';
+
+export const getClientsConfigCollection = (): Collection<ClientConfigDoc> => {
+  return getDb().collection('clientsConfig');
+};
+
+export const getClientConfig = (clientId: string) => {
+  return getClientsConfigCollection().findOne({ clientId });
+};
+
+export const getClientConfigByPhone = async (
+  phoneNumber: string
+): Promise<ClientConfigDoc | null> => {
+  return getClientsConfigCollection().findOne({ phoneNumber });
+};
+
+export const createClientConfigDoc = async (clientConfig: ClientConfigDoc): Promise<void> => {
+  await getClientsConfigCollection().insertOne(clientConfig);
+};

package/src/talkpilot/clientsConfig/clientsConfig.types.ts

@@ -0,0 +1,55 @@
+import { WithId } from 'mongodb';
+
+/**
+ * Configuration for initiating a call for short SLA
+ */
+export type InitiateCallForShortSlaConfig = {
+  active: boolean;
+  max_hours: number;
+  contacts?: { name: string; phoneNumber: string }[];
+  flow_id?: string | string[];
+};
+
+/**
+ * Moked 106 configuration structure
+ */
+export type Moked106Config = {
+  initiate_call_for_short_sla?: InitiateCallForShortSlaConfig;
+  avoidSaveTickets?: boolean;
+  withUploadImagesSms?: boolean;
+};
+
+/**
+ * Municipal products structure
+ */
+export type MunicipalProduct = {
+  moked_106?: Moked106Config;
+  cityName: string;
+  crmName?: string;
+  cityDisplayName?: string;
+  cityLogoURL?: string;
+  timezone: string;
+  websiteUrl?: string;
+  isProductionReady?: boolean;
+  municipalDisplayName?: string;
+};
+
+/**
+ * Products structure
+ */
+export type Products = {
+  municipal?: MunicipalProduct;
+  [key: string]: unknown; // Allow other products
+};
+
+/**
+ * Client configuration type
+ * @template P - Products type (defaults to Products for type safety)
+ */
+export type ClientConfig<P extends Products = Products> = {
+  clientId: string;
+  phoneNumber?: string;
+  products: P;
+};
+
+export type ClientConfigDoc<P extends Products = Products> = WithId<ClientConfig<P>>;

package/src/talkpilot/clientsConfig/index.ts

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

package/src/talkpilot/flows/flows.getter.ts

@@ -0,0 +1,11 @@
+import type { Collection, ObjectId, WithId } from 'mongodb';
+import { getDb } from '../index';
+import type { Flow } from './flows.types';
+
+export const getFlowsCollection = (): Collection<Flow> => {
+  return getDb().collection<Flow>('flows');
+};
+
+export const findFlowById = (flowId: ObjectId, clientId: string): Promise<WithId<Flow> | null> => {
+  return getFlowsCollection().findOne({ _id: flowId, clientId });
+};

package/src/talkpilot/flows/flows.schema.ts

@@ -0,0 +1,90 @@
+export const flowMongoSchema = {
+  bsonType: 'object',
+  required: ['flowName', 'systemInstructions', 'initialSentence', 'interactions'],
+  properties: {
+    _id: { bsonType: 'objectId' },
+    flowName: { bsonType: 'string' },
+    clientId: { bsonType: 'string' },
+    systemInstructions: { bsonType: 'string' },
+    initialSentence: { bsonType: 'string' },
+    voice: { bsonType: ['string', 'null'] },
+    interactions: {
+      bsonType: 'array',
+      items: {
+        bsonType: 'object',
+        required: ['id', 'type', 'text', 'position'],
+        properties: {
+          id: { bsonType: 'string' },
+          type: { bsonType: 'string' },
+          text: { bsonType: 'string' },
+          successStatus: { bsonType: ['string', 'null'] },
+          conditions: {
+            bsonType: ['array', 'null'],
+            items: {
+              bsonType: 'object',
+              required: ['conditionString'],
+              properties: {
+                conditionString: { bsonType: 'string' },
+                nodeType: { bsonType: ['string', 'null'] },
+                id: { bsonType: ['string', 'null'] },
+              },
+            },
+          },
+          defaultNodeType: { bsonType: ['string', 'null'] },
+          defaultChild: {
+            bsonType: ['object', 'null'],
+            properties: { id: { bsonType: 'string' } },
+          },
+          position: {
+            bsonType: 'object',
+            required: ['x', 'y'],
+            properties: {
+              x: { bsonType: 'number' },
+              y: { bsonType: 'number' },
+            },
+          },
+          name: { bsonType: ['string', 'null'] },
+          children: { bsonType: ['array', 'null'], items: { bsonType: 'string' } },
+          resultsLabel: { bsonType: ['string', 'null'] },
+          resultsColor: { bsonType: ['string', 'null'] },
+        },
+      },
+    },
+    edges: {
+      bsonType: ['array', 'null'],
+      items: {
+        bsonType: 'object',
+        required: ['id', 'source', 'target'],
+        properties: {
+          id: { bsonType: 'string' },
+          source: { bsonType: 'string' },
+          target: { bsonType: 'string' },
+          label: { bsonType: ['string', 'null'] },
+        },
+      },
+    },
+    metaKeys: {
+      bsonType: ['array', 'null'],
+      items: {
+        bsonType: 'object',
+        required: ['key'],
+        properties: {
+          key: { bsonType: 'string' },
+          required: { bsonType: 'bool' },
+        },
+      },
+    },
+    userProperties: {
+      bsonType: ['array', 'null'],
+      items: {
+        bsonType: 'object',
+        required: ['name', 'description'],
+        properties: {
+          name: { bsonType: 'string' },
+          description: { bsonType: 'string' },
+        },
+      },
+    },
+  },
+  additionalProperties: false,
+} as const;

package/src/talkpilot/flows/flows.types.ts

@@ -0,0 +1,151 @@
+import { ObjectId } from 'mongodb';
+
+/* ----------  Basic helpers  ---------- */
+
+export type Position = { x: number; y: number };
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export type QuestionType = 'open' | 'multiple' | 'table';
+export type SelectionType = 'single' | 'multiple';
+
+export type Question = {
+  id: string;
+  type: QuestionType;
+  text: string;
+  repeatAnswer?: boolean;
+  // For 'multiple' type questions:
+  answers?: string[] | null;
+  selectionType?: SelectionType | null; // 'single' = choose one, 'multiple' = choose one or more
+  // For 'table' type questions:
+  tableHeader?: string | null;
+  tableRows?: string[] | null;
+  tableColumns?: string[] | null; // These are the answer options shared across all rows
+  // Note: 'table' questions can also have selectionType to indicate if each row allows single or multiple selections
+};
+
+export type NodeKind =
+  | 'start'
+  | 'say'
+  | 'condition'
+  | 'improvise'
+  | 'tool'
+  | 'sendMessage'
+  | 'questionsList'
+  | 'end';
+type BaseNode = {
+  id: string;
+  type: NodeKind;
+  text: string;
+
+  name?: string | null;
+  position: Position;
+  children?: string[] | null;
+  successStatus?: string | null;
+  questions?: Question[] | null;
+};
+
+export type StartNode = BaseNode & { type: 'start' };
+
+export type SayNode = BaseNode & { type: 'say' };
+
+export type ConditionNode = BaseNode & {
+  type: 'condition';
+  conditions: Array<{
+    conditionString: string;
+    nodeType?: string | null;
+    id?: string | null;
+  }>;
+  defaultNodeType?: string | null;
+  defaultChild?: { id?: string } | null;
+};
+
+export type ImproviseNode = BaseNode & { type: 'improvise' };
+
+export type FlowTool = {
+  id: string;
+  name: string;
+  description?: string;
+  url: string;
+  method: HttpMethod;
+  headers?: Record<string, string>;
+  parameters: Record<string, unknown>;
+  bodyFormat?: 'json' | 'form-data';
+};
+
+export type SendMethod = 'sms' | 'whatsapp';
+
+export type SendMessageNode = BaseNode & {
+  type: 'sendMessage';
+  /** Which channel to use. If omitted, decide at runtime (e.g., default to whatsapp). */
+  send_method: SendMethod;
+  /** Destination phone (E.164 or templated string like "{{userPhone}}"). */
+  phone_number: string;
+};
+
+export type ToolNode = BaseNode & {
+  type: 'tool';
+  name: string;
+  text: string;
+};
+
+export type QuestionsListNode = BaseNode & {
+  type: 'questionsList';
+  questions: Question[];
+};
+
+export type EndNode = BaseNode & { type: 'end' };
+
+export type Interaction =
+  | StartNode
+  | SayNode
+  | ConditionNode
+  | ImproviseNode
+  | ToolNode
+  | SendMessageNode
+  | QuestionsListNode
+  | EndNode;
+
+export type Edge = {
+  id: string;
+  source: string;
+  target: string;
+  label?: string | null;
+};
+
+export type MetaKey = {
+  key: string;
+  required?: boolean;
+};
+
+export type UserProperty = {
+  name: string;
+  description: string;
+};
+
+/* ----------  The Flow object ---------- */
+
+export type Flow = {
+  freeTextContent?: string;
+  isFreeText?: boolean;
+  _id?: ObjectId;
+
+  flowName: string;
+  clientId: string;
+
+  systemInstructions: string;
+  initialSentence: string;
+  voice?: string;
+
+  insights: string[];
+
+  interactions: Interaction[];
+
+  edges?: Edge[] | null;
+  metaKeys?: MetaKey[] | null;
+  userProperties?: UserProperty[] | null;
+  tools?: FlowTool[];
+
+  // Timestamps
+  createdAt?: Date;
+  updatedAt?: Date;
+};

package/src/talkpilot/flows/index.ts

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