@talkpilot/core-db 1.3.64 → 1.3.66

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

@@ -1,149 +1,189 @@
-import { ObjectId, Sort, WithId } from "mongodb";
-import { TranscriptionSegment } from "../results";
-import { LeadProperty } from "../leads";
-
-import {
-  CallStatusValues,
-  CONFERENCE_ROLE_CUSTOMER,
-  CONFERENCE_ROLE_SUPERVISOR,
-} from "./calls.constants";
-
-export type ConferenceRole =
-  | typeof CONFERENCE_ROLE_CUSTOMER
-  | typeof CONFERENCE_ROLE_SUPERVISOR
-  | null;
-
-export type CallStatus = (typeof CallStatusValues)[keyof typeof CallStatusValues];
-
-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?: CallStatus;
-  leads?: LeadProperty[];
-  summary?: string;
-  recordingUrl?: string;
-  env: string;
-  updatedAt: Date;
-  createdAt: Date;
-  isAnsweredByAnsweringMachine?: boolean;
-  agentHungUp?: boolean;
-  endReason?: string;
-  conferenceName?: string | null;
-  conferenceSid?: string | null;
-  conferenceParticipantSid?: string | null;
-  isConferenceCall?: boolean;
-  conferenceRole?: ConferenceRole;
-  redirectedCall?: boolean;
-  /** Present only on redirected calls: what the dialled leg did. */
-  redirectCallLog?: RedirectCallLog;
-  toolExecutions?: ToolExecution[];
-  transcriptionComparison?: Record<string, TranscriptionSegment[]>;
-};
-
-/**
- * The outcome of the <Dial> that transferred a call, reported by Twilio when the
- * dialled leg ends. `durationSeconds` is the bridged time, which is 0 when the
- * destination never answered.
- */
-export type RedirectCallLog = {
-  childCallSid?: string;
-  to?: string;
-  status: CallStatus;
-  durationSeconds: number;
-  endedAt: Date;
-};
-
-export type ToolExecution = {
-  toolName: string;
-  executedAt: Date;
-  durationMs: number;
-  args: Record<string, unknown> | { _redacted: true };
-  meta: ToolExecutionMeta;
-  status: "success" | "error";
-  httpStatus?: number;
-  response?: Record<string, unknown>;
-  steps?: ToolExecutionStep[];
-};
-
-export type ToolExecutionStepLevel = "info" | "warn" | "error";
-
-export type ToolExecutionStep = {
-  timestamp: Date;
-  label: string;
-  level: ToolExecutionStepLevel;
-  data?: Record<string, unknown> | string;
-  payload?: Record<string, unknown>;
-};
-
-export type ToolExecutionMeta =
-  | {
-      kind: "http";
-      url: string;
-      method: string;
-      flowToolId?: string;
-      runInBackground?: boolean;
-      sensitive?: boolean;
-    }
-  | { kind: "internal" };
-
-export type CallQueryOptions = {
-  sort?: Sort;
-  skip?: number;
-  limit?: number;
-};
-
-export type CallsFilterParams = {
-  clientId: string;
-  callSid?: string;
-  startDate?: Date;
-  endDate?: Date;
-  status?: CallStatus;
-  customerPhoneNumber?: string;
-  agentPhoneNumber?: string;
-  flowId?: string;
-  runId?: string;
-  sessionId?: string;
-  isIncoming?: boolean;
-  search?: string;
-};
-
-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>;
-
-/** @deprecated use DashboardHeatmapMetric instead */
-export type CallsByHour = { hour: number; calls: number };
-
-export type CountOpts = {
-  isOutgoingCall?: boolean;
-  isIncomingCall?: boolean;
-};
-
-export type DateRange = {
-  since?: Date;
-  until?: Date;
-};
+import { ObjectId, Sort, WithId } from "mongodb";
+import { TranscriptionSegment } from "../results";
+import { LeadProperty } from "../leads";
+
+import {
+  CallStatusValues,
+  CONFERENCE_ROLE_CUSTOMER,
+  CONFERENCE_ROLE_SUPERVISOR,
+} from "./calls.constants";
+
+export type ConferenceRole =
+  | typeof CONFERENCE_ROLE_CUSTOMER
+  | typeof CONFERENCE_ROLE_SUPERVISOR
+  | null;
+
+export type CallStatus = (typeof CallStatusValues)[keyof typeof CallStatusValues];
+
+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?: CallStatus;
+  leads?: LeadProperty[];
+  summary?: string;
+  recordingUrl?: string;
+  env: string;
+  updatedAt: Date;
+  createdAt: Date;
+  isAnsweredByAnsweringMachine?: boolean;
+  agentHungUp?: boolean;
+  endReason?: string;
+  conferenceName?: string | null;
+  conferenceSid?: string | null;
+  conferenceParticipantSid?: string | null;
+  isConferenceCall?: boolean;
+  conferenceRole?: ConferenceRole;
+  redirectedCall?: boolean;
+  /** Present only on redirected calls: what the dialled leg did. */
+  redirectCallLog?: RedirectCallLog;
+  toolExecutions?: ToolExecution[];
+  transcriptionComparison?: Record<string, TranscriptionSegment[]>;
+};
+
+/**
+ * The outcome of the <Dial> that transferred a call, reported by Twilio when the
+ * dialled leg ends. `durationSeconds` is the bridged time, which is 0 when the
+ * destination never answered.
+ */
+export type RedirectCallLog = {
+  childCallSid?: string;
+  to?: string;
+  status: CallStatus;
+  durationSeconds: number;
+  endedAt: Date;
+};
+
+export type ToolExecution = {
+  toolName: string;
+  executedAt: Date;
+  durationMs: number;
+  args: Record<string, unknown> | { _redacted: true };
+  meta: ToolExecutionMeta;
+  status: "success" | "error";
+  httpStatus?: number;
+  response?: Record<string, unknown>;
+  steps?: ToolExecutionStep[];
+};
+
+export type ToolExecutionStepLevel = "info" | "warn" | "error";
+
+export type ToolExecutionStep = {
+  timestamp: Date;
+  label: string;
+  level: ToolExecutionStepLevel;
+  data?: Record<string, unknown> | string;
+  payload?: Record<string, unknown>;
+};
+
+export type ToolExecutionMeta =
+  | {
+      kind: "http";
+      url: string;
+      method: string;
+      flowToolId?: string;
+      runInBackground?: boolean;
+      sensitive?: boolean;
+    }
+  | { kind: "internal" };
+
+export type CallQueryOptions = {
+  sort?: Sort;
+  skip?: number;
+  limit?: number;
+};
+
+export type CallsFilterParams = {
+  clientId: string;
+  callSid?: string;
+  startDate?: Date;
+  endDate?: Date;
+  status?: CallStatus;
+  customerPhoneNumber?: string;
+  agentPhoneNumber?: string;
+  flowId?: string;
+  runId?: string;
+  sessionId?: string;
+  isIncoming?: boolean;
+  search?: string;
+};
+
+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>;
+
+/** @deprecated use DashboardHeatmapMetric instead */
+export type CallsByHour = { hour: number; calls: number };
+
+export type CountOpts = {
+  isOutgoingCall?: boolean;
+  isIncomingCall?: boolean;
+};
+
+export type DateRange = {
+  since?: Date;
+  until?: Date;
+};
+
+export type StatsDateRangeParams = {
+  dateFrom?: string;
+  dateTo?: string;
+  clientId?: string;
+  timezone?: string;
+};
+
+export type ActiveCallsSummary = {
+  total: number;
+  incoming: number;
+  outgoing: number;
+  activeClientIds: string[];
+};
+
+export type TodayCallsSummary = {
+  total: number;
+  incoming: number;
+  outgoing: number;
+  completed: number;
+  failed: number;
+  busy: number;
+  noAnswer: number;
+  totalMinutes: number;
+};
+
+export type ClientCallStats = {
+  clientId: string;
+  totalCalls: number;
+  statusCounts: Record<string, number>;
+  totalMinutes: number;
+  lastCallDate: Date;
+};
+
+export type SessionCallStats = {
+  sessionId: string;
+  sessionName: string;
+  totalCalls: number;
+  statusCounts: Record<string, number>;
+};

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

@@ -0,0 +1,51 @@
+import { getClientsCollection, getAllClientCredits, getAllClientIds } from "../clients.getters";
+import { createClient } from "../../../test-utils/factories";
+
+describe("db.clients", () => {
+  describe("getAllClientCredits", () => {
+    it("should return a Map of clientId to credits across all clients", async () => {
+      await getClientsCollection().insertMany([
+        createClient({ clientId: "creditsClientA", credits: 100 }),
+        createClient({ clientId: "creditsClientB", credits: 250 }),
+      ]);
+
+      const result = await getAllClientCredits();
+
+      expect(result).toBeInstanceOf(Map);
+      expect(result.get("creditsClientA")).toBe(100);
+      expect(result.get("creditsClientB")).toBe(250);
+    });
+
+    it("should default missing credits to 0", async () => {
+      const client = createClient({ clientId: "noCreditsClient" });
+      delete (client as { credits?: number }).credits;
+      await getClientsCollection().insertOne(client);
+
+      const result = await getAllClientCredits();
+      expect(result.get("noCreditsClient")).toBe(0);
+    });
+
+    it("should return an empty Map when there are no clients", async () => {
+      const result = await getAllClientCredits();
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe("getAllClientIds", () => {
+    it("should return the ids of all clients", async () => {
+      await getClientsCollection().insertMany([
+        createClient({ clientId: "idClientA" }),
+        createClient({ clientId: "idClientB" }),
+      ]);
+
+      const result = await getAllClientIds();
+
+      expect(result.sort()).toEqual(["idClientA", "idClientB"]);
+    });
+
+    it("should return an empty array when there are no clients", async () => {
+      const result = await getAllClientIds();
+      expect(result).toEqual([]);
+    });
+  });
+});

package/src/talkpilot/clients/__tests__/clients.lifecycle.spec.ts

@@ -0,0 +1,166 @@
+import {
+  clientExistsInAnyCollection,
+  deleteClientDataAcrossDomains,
+} from "../clients.lifecycle";
+import { getPhoneNumbersCollection } from "../../phone_numbers/phone_numbers.getter";
+import {
+  createMuniIssue,
+  generateMuniIssueId,
+  getAuditLogsCollection,
+  getScansCollection,
+} from "../../../index";
+import {
+  createPhoneNumber,
+  createMuniIssueInput,
+  createScanFixture,
+} from "../../../test-utils/factories";
+
+describe("db.clients.lifecycle", () => {
+  describe("clientExistsInAnyCollection", () => {
+    it("should return true when the client exists only in phone_numbers (client_id field)", async () => {
+      const clientId = "existsPhoneOnly";
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: clientId }),
+      );
+
+      expect(await clientExistsInAnyCollection(clientId)).toBe(true);
+    });
+
+    it("should return true when the client exists only in muniIssues (municipal DB)", async () => {
+      const clientId = "existsMuniOnly";
+      await createMuniIssue(
+        createMuniIssueInput({ clientId }),
+        generateMuniIssueId(),
+      );
+
+      expect(await clientExistsInAnyCollection(clientId)).toBe(true);
+    });
+
+    it("should return false when the client does not exist anywhere", async () => {
+      expect(await clientExistsInAnyCollection("noSuchClientAtAll")).toBe(
+        false,
+      );
+    });
+
+    it("should not consider websitalk data (scans/websiteUrls) at all", async () => {
+      const clientId = "onlyInWebsitalk";
+      await getScansCollection().insertOne(createScanFixture({ clientId }));
+
+      expect(await clientExistsInAnyCollection(clientId)).toBe(false);
+    });
+
+    it("should not be fooled by unrelated collections lacking a clientId/client_id field", async () => {
+      await global.db
+        .collection("someUnrelatedCollection")
+        .insertOne({ someField: "someValue" });
+
+      expect(await clientExistsInAnyCollection("noSuchClientAtAll")).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("deleteClientDataAcrossDomains", () => {
+    it("should return deleted:false with a reason and delete nothing when the client does not exist", async () => {
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: "unrelatedClient" }),
+      );
+
+      const summary = await deleteClientDataAcrossDomains(
+        "missingClient",
+        "admin@callai.co.il",
+      );
+
+      expect(summary.deleted).toBe(false);
+      if (!summary.deleted) {
+        expect(summary.reason).toBeTruthy();
+      }
+      expect(
+        await getPhoneNumbersCollection().findOne({
+          client_id: "unrelatedClient",
+        }),
+      ).not.toBeNull();
+    });
+
+    it("should not write an audit log entry when the client does not exist", async () => {
+      await deleteClientDataAcrossDomains(
+        "missingClientNoAudit",
+        "admin@callai.co.il",
+      );
+
+      expect(
+        await getAuditLogsCollection().findOne({
+          clientId: "missingClientNoAudit",
+        }),
+      ).toBeNull();
+    });
+
+    it("should delete the client's data across talkpilot and municipal domains", async () => {
+      const clientId = "deleteMeEverywhere";
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: clientId }),
+      );
+      await createMuniIssue(
+        createMuniIssueInput({ clientId }),
+        generateMuniIssueId(),
+      );
+
+      const adminEmail = "admin@callai.co.il";
+      const summary = await deleteClientDataAcrossDomains(
+        clientId,
+        adminEmail,
+      );
+
+      expect(summary.deleted).toBe(true);
+      if (summary.deleted) {
+        expect(summary.allSucceeded).toBe(true);
+        const byName = (name: string) =>
+          summary.results.find((r) => r.collectionName === name);
+        expect(byName("phone_numbers")?.deletedCount).toBe(1);
+        expect(byName("muniIssues")?.deletedCount).toBe(1);
+      }
+
+      expect(await clientExistsInAnyCollection(clientId)).toBe(false);
+
+      // The audit entry itself must survive the client's own deletion.
+      const auditEntry = await getAuditLogsCollection().findOne({ clientId });
+      expect(auditEntry).toMatchObject({
+        clientId,
+        adminEmail,
+        action: "delete",
+      });
+      expect(auditEntry?.timestamp).toBeInstanceOf(Date);
+    });
+
+    it("should not touch websitalk data (scans/websiteUrls) — callers must call the external website-talk deletion API separately", async () => {
+      const clientId = "hasWebsitalkData";
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: clientId }),
+      );
+      await getScansCollection().insertOne(createScanFixture({ clientId }));
+
+      await deleteClientDataAcrossDomains(clientId, "admin@callai.co.il");
+
+      expect(
+        await getScansCollection().findOne({ clientId }),
+      ).not.toBeNull();
+    });
+
+    it("should not delete unrelated clients' data", async () => {
+      const targetClient = "deleteTarget";
+      const otherClient = "keepMeClient";
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: targetClient }),
+      );
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: otherClient }),
+      );
+
+      await deleteClientDataAcrossDomains(targetClient, "admin@callai.co.il");
+
+      expect(
+        await getPhoneNumbersCollection().findOne({ client_id: otherClient }),
+      ).not.toBeNull();
+    });
+  });
+});

package/src/talkpilot/clients/clients.constants.ts

@@ -0,0 +1,2 @@
+/** Collections to always skip during client deletion — e.g. auditLogs, which must survive it. */
+export const DELETE_DENYLIST: string[] = ["auditLogs"];

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

@@ -15,5 +15,18 @@ export const getClientByAPIKey = async (
   return client ? client : null;
 };
 
+export const getAllClientCredits = async (): Promise<Map<string, number>> => {
+  const docs = await getClientsCollection()
+    .find({}, { projection: { clientId: 1, credits: 1 } })
+    .toArray();
+  return new Map(docs.map((c) => [c.clientId, c.credits ?? 0]));
+};
+
+export const getAllClientIds = async (): Promise<string[]> => {
+  const docs = await getClientsCollection()
+    .find({}, { projection: { clientId: 1 } })
+    .toArray();
+  return docs.map((c) => c.clientId);
+};
 export const getClientByClientId = (clientId: string): Promise<Client | null> =>
   getClientsCollection().findOne({ clientId });

package/src/talkpilot/clients/clients.lifecycle.ts

@@ -0,0 +1,116 @@
+import { Db } from "mongodb";
+import { getDb, insertAuditLog } from "../index";
+import { getDb as getMunicipalDataDb } from "../../municipal";
+import { DELETE_DENYLIST } from "./clients.constants";
+import {
+  CollectionMatch,
+  CollectionDeleteResult,
+  DeleteClientDataSummary,
+} from "./clients.types";
+
+// Skips websitalk on purpose — see the warning on `deleteClientDataAcrossDomains` below.
+const findClientMatchInDb = async (
+  db: Db,
+  clientId: string,
+): Promise<CollectionMatch[]> => {
+  const collections = await db.listCollections().toArray();
+  return Promise.all(
+    collections
+      .filter((c) => !DELETE_DENYLIST.includes(c.name))
+      .map(async (c) => {
+        const doc = await db
+          .collection(c.name)
+          .findOne({ $or: [{ clientId }, { client_id: clientId }] });
+        return { collectionName: c.name, matched: !!doc };
+      }),
+  );
+};
+
+export const clientExistsInAnyCollection = async (
+  clientId: string,
+): Promise<boolean> => {
+  const [talkpilotResults, municipalResults] = await Promise.all([
+    findClientMatchInDb(getDb(), clientId),
+    findClientMatchInDb(getMunicipalDataDb(), clientId),
+  ]);
+  return [...talkpilotResults, ...municipalResults].some((r) => r.matched);
+};
+
+const deleteClientFromDb = async (
+  db: Db,
+  clientId: string,
+): Promise<CollectionDeleteResult[]> => {
+  const collections = await db.listCollections().toArray();
+  return Promise.all(
+    collections
+      .filter((c) => !DELETE_DENYLIST.includes(c.name))
+      .map(async (c) => {
+        try {
+          const result = await db
+            .collection(c.name)
+            .deleteMany({ $or: [{ clientId }, { client_id: clientId }] });
+          return {
+            collectionName: c.name,
+            deletedCount: result.deletedCount,
+            success: true,
+          };
+        } catch (error) {
+          return {
+            collectionName: c.name,
+            deletedCount: 0,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      }),
+  );
+};
+
+/**
+ * Deletes a client's data across talkpilot/municipal collections and logs the action.
+ *
+ * ⚠️ Does NOT delete website-talk data — `scans`/`websiteUrls` are the lookup key an
+ * external API needs to clean up that domain. Callers must invoke that API separately.
+ */
+export const deleteClientDataAcrossDomains = async (
+  clientId: string,
+  adminEmail: string,
+): Promise<DeleteClientDataSummary> => {
+  const exists = await clientExistsInAnyCollection(clientId);
+  if (!exists) {
+    return {
+      clientId,
+      deleted: false,
+      reason: "Client does not exist in any collection",
+    };
+  }
+
+  const [talkpilotResults, municipalResults] = await Promise.all([
+    deleteClientFromDb(getDb(), clientId),
+    deleteClientFromDb(getMunicipalDataDb(), clientId),
+  ]);
+  const results = [...talkpilotResults, ...municipalResults];
+  const allSucceeded = results.every((r) => r.success);
+
+  await insertAuditLog({
+    clientId,
+    adminEmail,
+    action: "delete",
+    timestamp: new Date(),
+    allSucceeded,
+    ...(allSucceeded
+      ? {}
+      : {
+          failedCollections: results
+            .filter((r) => !r.success)
+            .map((r) => r.collectionName),
+        }),
+  });
+
+  return {
+    clientId,
+    deleted: true,
+    results,
+    allSucceeded,
+  };
+};