@talkpilot/core-db 1.3.87 → 1.3.89

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

@@ -0,0 +1,194 @@
+import {
+  clientExistsInAnyCollection,
+  deleteClientDataAcrossDomains,
+} from "../clients.lifecycle";
+import { getPhoneNumbersCollection } from "../../phone_numbers/phone_numbers.getter";
+import * as auditLogsGetters from "../../auditLogs/auditLogs.getters";
+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);
+        expect(summary.auditLogged).toBe(true);
+        expect(summary.auditError).toBeUndefined();
+        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 still delete the data and report auditLogged: false when the audit write fails", async () => {
+      const clientId = "auditWriteFails";
+      await getPhoneNumbersCollection().insertOne(
+        createPhoneNumber({ client_id: clientId }),
+      );
+      const insertAuditLog = jest
+        .spyOn(auditLogsGetters, "insertAuditLog")
+        .mockRejectedValueOnce(new Error("audit write failed"));
+
+      const summary = await deleteClientDataAcrossDomains(
+        clientId,
+        "admin@callai.co.il",
+      );
+
+      expect(summary).toMatchObject({
+        deleted: true,
+        allSucceeded: true,
+        auditLogged: false,
+        auditError: "audit write failed",
+      });
+      expect(await clientExistsInAnyCollection(clientId)).toBe(false);
+
+      insertAuditLog.mockRestore();
+    });
+
+    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,4 @@
+/** Collections to always skip during client deletion — e.g. auditLogs, which must survive it. */
+export const DELETE_DENYLIST: string[] = ["auditLogs"];
+
+export const BACKOFFICE_ROLES = ["admin", "viewer"] as const;

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

@@ -1,5 +1,13 @@
-import { getDb, Client } from "../index";
-import { Collection } from "mongodb";
+import { getDb, getPhoneNumbersCollection, Client } from "../index";
+import { Collection, Filter } from "mongodb";
+import { applyQueryOptions } from "../utils/query.utils";
+import { escapeRegex } from "../../utils/regex.utils";
+import {
+  BackofficeRole,
+  ClientsPage,
+  ClientsPageParams,
+  ClientsPageRow,
+} from "./clients.types";
 
 export const getClientsCollection = (): Collection<Client> => {
   return getDb().collection<Client>("clients");
@@ -15,5 +23,86 @@ export const getClientByAPIKey = async (
   return client ? client : null;
 };
 
+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 });
+
+export const getBackofficeRole = async (
+  clientId: string,
+): Promise<BackofficeRole | null> => {
+  const client = await getClientsCollection().findOne(
+    { clientId },
+    { projection: { "roles.backoffice": 1 } },
+  );
+  const flags = client?.roles?.backoffice;
+  if (flags?.admin) return "admin";
+  if (flags?.viewer) return "viewer";
+  return null;
+};
+
+export const setBackofficeRole = async (
+  clientId: string,
+  role: BackofficeRole | null,
+): Promise<boolean> => {
+  const { matchedCount } = await getClientsCollection().updateOne(
+    { clientId },
+    {
+      $set: {
+        "roles.backoffice.admin": role === "admin",
+        "roles.backoffice.viewer": role === "viewer",
+      },
+    },
+  );
+  return matchedCount > 0;
+};
+
+export const countBackofficeAdmins = (): Promise<number> =>
+  getClientsCollection().countDocuments({ "roles.backoffice.admin": true });
+
+export const findClientsPage = async ({
+  skip,
+  limit,
+  clientId,
+  clientIds,
+  excludeClientIds,
+  search,
+}: ClientsPageParams): Promise<ClientsPage> => {
+  const conditions: Filter<Client>[] = [];
+  if (clientId) {
+    conditions.push({ clientId });
+  }
+  if (clientIds) {
+    conditions.push({ clientId: { $in: clientIds } });
+  }
+  if (excludeClientIds) {
+    conditions.push({ clientId: { $nin: excludeClientIds } });
+  }
+
+  const text = search?.trim();
+  if (text) {
+    const pattern = new RegExp(escapeRegex(text), "i");
+    const clientIdsByPhone = await getPhoneNumbersCollection().distinct("client_id", {
+      phone_number: pattern,
+    });
+    conditions.push({
+      $or: [{ clientId: pattern }, { clientId: { $in: clientIdsByPhone } }],
+    });
+  }
+
+  const filter: Filter<Client> =
+    conditions.length > 0 ? { $and: conditions } : {};
+  const collection = getClientsCollection();
+  const [clients, total] = await Promise.all([
+    applyQueryOptions(
+      collection.find<ClientsPageRow>(filter, { projection: { clientId: 1, credits: 1 } }),
+      { sort: { createdAt: -1, _id: -1 }, skip, limit },
+    ).toArray(),
+    collection.countDocuments(filter),
+  ]);
+  return { clients, total };
+};

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

@@ -0,0 +1,132 @@
+import { Db } from "mongodb";
+import { getDb, insertAuditLog } from "../index";
+import type { AuditLogEntry } from "../auditLogs/auditLogs.types";
+import { getDb as getMunicipalDataDb } from "../../municipal";
+import { DELETE_DENYLIST } from "./clients.constants";
+import {
+  AuditLogResult,
+  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),
+          };
+        }
+      }),
+  );
+};
+
+// The data is already deleted at this point — a failed audit write must not abort the caller.
+const tryInsertAuditLog = async (entry: AuditLogEntry): Promise<AuditLogResult> => {
+  try {
+    await insertAuditLog(entry);
+    return { auditLogged: true };
+  } catch (error) {
+    return {
+      auditLogged: false,
+      auditError: 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);
+
+  const auditResult = await tryInsertAuditLog({
+    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,
+    ...auditResult,
+  };
+};

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

@@ -1,8 +1,21 @@
 import { ObjectId } from "mongodb";
 import { ClientQuotaSettings } from "./clients.quota.types";
+import { BACKOFFICE_ROLES } from "./clients.constants";
 
 export type { QuotaThresholdAlert, ClientQuotaSettings, QuotaAlertInput, ClientQuotaUsage, ClientQuotaState } from "./clients.quota.types";
 
+export type BackofficeRole = (typeof BACKOFFICE_ROLES)[number];
+
+export type BackofficeRoleFlags = {
+  admin?: boolean;
+  viewer?: boolean;
+};
+
+export type ClientRoles = {
+  admin?: boolean;
+  backoffice?: BackofficeRoleFlags;
+};
+
 export type Client = {
   _id?: ObjectId;
   createdAt: Date;
@@ -13,6 +26,51 @@ export type Client = {
   credits: number;
   managedBy?: string;
   quota?: ClientQuotaSettings;
+  roles?: ClientRoles;
 };
 
 export type ClientDoc = Client & { _id: ObjectId };
+
+export type ClientsPageParams = {
+  skip: number;
+  limit: number;
+  /** Exact clientId match. */
+  clientId?: string;
+  /** Only these clients, e.g. the ones with calls in a date range. */
+  clientIds?: string[];
+  /** Every client except these, e.g. the ones that called since an inactivity cutoff. */
+  excludeClientIds?: string[];
+  /** Case-insensitive "contains" on the clientId or on any of the client's phone numbers. */
+  search?: string;
+};
+
+export type ClientsPageRow = Pick<ClientDoc, "_id" | "clientId" | "credits">;
+
+export type ClientsPage = {
+  clients: ClientsPageRow[];
+  total: number;
+};
+
+export type CollectionMatch = { collectionName: string; matched: boolean };
+
+export type CollectionDeleteResult = {
+  collectionName: string;
+  deletedCount: number;
+  success: boolean;
+  error?: string;
+};
+
+export type AuditLogResult = {
+  auditLogged: boolean;
+  auditError?: string;
+};
+
+/** Discriminated union: `deleted` tells you which shape you got without guessing. */
+export type DeleteClientDataSummary =
+  | { clientId: string; deleted: false; reason: string }
+  | ({
+      clientId: string;
+      deleted: true;
+      results: CollectionDeleteResult[];
+      allSucceeded: boolean;
+    } & AuditLogResult);

package/src/talkpilot/clients/index.ts

@@ -1,4 +1,6 @@
+export * from "./clients.constants";
 export * from "./clients.getters";
 export * from "./clients.types";
 export * from "./clients.quota.getters";
 export * from "./clients.quota.types";
+export * from "./clients.lifecycle";

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

@@ -6,9 +6,6 @@ import {
   setContextNoteEntries,
   setContextNoteConfig,
   deleteContextNoteEntry,
-  appendContextNoteEntry,
-  updateContextNoteEntryFields,
-  pullContextNoteEntry,
 } from "../contextNotes.getters";
 import { ObjectId } from "../../index";
 import {
@@ -206,144 +203,6 @@ describe("contextNotes getters", () => {
     expect(saved?.notes[0]._id.toString()).toBe(noteToKeep._id.toString());
   });
 
-  it("should append one note without replacing the others", async () => {
-    const kept = createContextNoteEntry({ title: "kept" });
-    const doc = buildContextNote({ notes: [kept] });
-    await createContextNote(doc);
-    const now = new Date("2026-10-18T12:00:00.000Z");
-
-    const added = await appendContextNoteEntry(
-      doc.clientId,
-      doc.product,
-      {
-        title: "added",
-        content: "new content",
-        activeFrom: now,
-        expiresAt: null,
-      },
-      now,
-    );
-
-    const saved = await getContextNotesCollection().findOne({
-      clientId: doc.clientId,
-      product: doc.product,
-    });
-    expect(saved?.notes).toHaveLength(2);
-    expect(saved?.notes[0]._id.toString()).toBe(kept._id.toString());
-    expect(saved?.notes[1].title).toBe("added");
-    expect(added._id.toString()).toBe(saved?.notes[1]._id.toString());
-    expect(added.createdAt).toEqual(now);
-  });
-
-  it("should create the document when appending the first note", async () => {
-    const clientId = new ObjectId().toString();
-    const now = new Date("2026-10-18T12:00:00.000Z");
-
-    const added = await appendContextNoteEntry(
-      clientId,
-      "Municipal",
-      {
-        title: "first",
-        content: "content",
-        activeFrom: now,
-        expiresAt: null,
-      },
-      now,
-    );
-
-    const saved = await getContextNotes(clientId, "Municipal");
-    expect(saved).toHaveLength(1);
-    expect(saved[0].notes).toHaveLength(1);
-    expect(saved[0].notes[0]._id.toString()).toBe(added._id.toString());
-  });
-
-  it("should update one note and leave the others unchanged", async () => {
-    const kept = createContextNoteEntry({ title: "kept" });
-    const target = createContextNoteEntry({ title: "before" });
-    const doc = buildContextNote({ notes: [kept, target] });
-    await createContextNote(doc);
-    const now = new Date("2026-10-18T13:00:00.000Z");
-    const activeFrom = new Date("2026-10-01T00:00:00.000Z");
-
-    const updated = await updateContextNoteEntryFields(
-      doc.clientId,
-      doc.product,
-      target._id,
-      {
-        title: "after",
-        content: "changed",
-        activeFrom,
-        expiresAt: null,
-      },
-      now,
-    );
-
-    const saved = await getContextNotesCollection().findOne({
-      clientId: doc.clientId,
-      product: doc.product,
-    });
-    expect(updated?.title).toBe("after");
-    expect(updated?.updatedAt).toEqual(now);
-    expect(saved?.notes).toHaveLength(2);
-    expect(saved?.notes[0].title).toBe("kept");
-    expect(saved?.notes[1].title).toBe("after");
-    expect(saved?.notes[1].content).toBe("changed");
-    expect(saved?.notes[1].createdAt).toEqual(target.createdAt);
-  });
-
-  it("should return null when updating a missing note", async () => {
-    const doc = buildContextNote({ notes: [createContextNoteEntry()] });
-    await createContextNote(doc);
-
-    const updated = await updateContextNoteEntryFields(
-      doc.clientId,
-      doc.product,
-      new ObjectId(),
-      {
-        title: "missing",
-        content: "missing",
-        activeFrom: new Date(),
-        expiresAt: null,
-      },
-    );
-
-    expect(updated).toBeNull();
-  });
-
-  it("should pull one note and leave the others", async () => {
-    const kept = createContextNoteEntry();
-    const removed = createContextNoteEntry();
-    const doc = buildContextNote({ notes: [kept, removed] });
-    await createContextNote(doc);
-
-    const pulled = await pullContextNoteEntry(
-      doc.clientId,
-      doc.product,
-      removed._id,
-    );
-
-    const saved = await getContextNotesCollection().findOne({
-      clientId: doc.clientId,
-      product: doc.product,
-    });
-    expect(pulled).toBe(true);
-    expect(saved?.notes).toHaveLength(1);
-    expect(saved?.notes[0]._id.toString()).toBe(kept._id.toString());
-  });
-
-  it("should return false when pulling a missing note", async () => {
-    const doc = buildContextNote({ notes: [createContextNoteEntry()] });
-    await createContextNote(doc);
-
-    const pulled = await pullContextNoteEntry(
-      doc.clientId,
-      doc.product,
-      new ObjectId(),
-    );
-
-    expect(pulled).toBe(false);
-  });
-
   it("should return false when deleteContextNoteEntry targets a non-existent note", async () => {
     const doc = buildContextNote({ notes: [] });
     const id = await createContextNote(doc);