@talkpilot/core-db 1.3.35 → 1.3.37

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

@@ -0,0 +1,123 @@
+import {
+  getClientsConfigCollection,
+  incrementClientQuotaUsage,
+  listClientIdsWithConfiguredQuota,
+  resetClientQuotaUsage,
+} from "../../clientsConfig/clientsConfig.getters";
+import { getClientsCollection } from "../clients.getters";
+import {
+  markQuotaAlertSent,
+  markQuotaExpiredSent,
+  updateQuotaAlertsConfig,
+} from "../clients.quota.getters";
+
+describe("quota getters", () => {
+  beforeEach(async () => {
+    await getClientsConfigCollection().deleteMany({});
+    await getClientsCollection().deleteMany({});
+  });
+
+  const seed = async (clientId: string, configQuota: object, clientQuota?: object) => {
+    await getClientsConfigCollection().insertOne({
+      clientId,
+      products: {},
+      quota: configQuota,
+    } as any);
+    if (clientQuota !== undefined) {
+      await getClientsCollection().insertOne({
+        clientId,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        credits: 0,
+        quota: clientQuota,
+      } as any);
+    }
+  };
+
+  it("updateQuotaAlertsConfig stores alerts on clients", async () => {
+    const clientId = "quota-alerts";
+    await seed(clientId, { totalQuota: 100, usedQuota: 5 });
+
+    await updateQuotaAlertsConfig(clientId, [
+      { thresholdPct: 50, recipientEmails: ["a@example.com"] },
+      { thresholdPct: 80, recipientEmails: ["b@example.com", "c@example.com"] },
+    ]);
+
+    const client = await getClientsCollection().findOne({ clientId });
+    expect(client?.quota?.alerts).toEqual([
+      { thresholdPct: 50, recipientEmails: ["a@example.com"] },
+      { thresholdPct: 80, recipientEmails: ["b@example.com", "c@example.com"] },
+    ]);
+
+    const config = await getClientsConfigCollection().findOne({ clientId });
+    expect(config?.quota).toEqual({ totalQuota: 100, usedQuota: 5 });
+  });
+
+  it("markQuotaAlertSent returns true only on first transition", async () => {
+    const clientId = "quota-alert-sent";
+    await seed(
+      clientId,
+      { totalQuota: 100, usedQuota: 0 },
+      { alerts: [{ thresholdPct: 50, recipientEmails: ["a@b.com"] }] },
+    );
+
+    expect(await markQuotaAlertSent(clientId, 0)).toBe(true);
+    expect(await markQuotaAlertSent(clientId, 0)).toBe(false);
+
+    const client = await getClientsCollection().findOne({ clientId });
+    expect(client?.quota?.alerts?.[0]?.thresholdSent).toBe(true);
+  });
+
+  it("markQuotaExpiredSent returns true only on first transition", async () => {
+    const clientId = "quota-notify";
+    await seed(clientId, { totalQuota: 10, usedQuota: 10 });
+
+    expect(await markQuotaExpiredSent(clientId)).toBe(true);
+    expect(await markQuotaExpiredSent(clientId)).toBe(false);
+
+    const client = await getClientsCollection().findOne({ clientId });
+    expect(client?.quota?.expiredSent).toBe(true);
+  });
+
+  it("listClientIdsWithConfiguredQuota returns clientIds with totalQuota set", async () => {
+    await seed("quota-a", { totalQuota: 100, usedQuota: 0 });
+    await seed("quota-b", { totalQuota: 50, usedQuota: 10 });
+    await getClientsConfigCollection().insertOne({
+      clientId: "no-quota",
+      products: {},
+    } as any);
+
+    const ids = await listClientIdsWithConfiguredQuota();
+    expect(ids.sort()).toEqual(["quota-a", "quota-b"]);
+  });
+
+  it("incrementClientQuotaUsage increments usedQuota on clientsConfig", async () => {
+    const clientId = "quota-inc";
+    await seed(clientId, { totalQuota: 100, usedQuota: 3 });
+
+    await incrementClientQuotaUsage(clientId, 2);
+    const config = await getClientsConfigCollection().findOne({ clientId });
+    expect(config?.quota?.usedQuota).toBe(5);
+  });
+
+  it("resetClientQuotaUsage zeros usedQuota and clears client quota flags", async () => {
+    const clientId = "quota-reset";
+    await seed(
+      clientId,
+      { totalQuota: 100, usedQuota: 50 },
+      {
+        expiredSent: true,
+        alerts: [{ thresholdPct: 50, recipientEmails: ["a@b.com"], thresholdSent: true }],
+      },
+    );
+
+    await resetClientQuotaUsage(clientId);
+
+    const config = await getClientsConfigCollection().findOne({ clientId });
+    expect(config?.quota?.usedQuota).toBe(0);
+
+    const client = await getClientsCollection().findOne({ clientId });
+    expect(client?.quota?.expiredSent).toBeUndefined();
+    expect(client?.quota?.alerts?.[0]?.thresholdSent).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,119 @@
+import { getClientConfig } from "../clientsConfig/clientsConfig.getters";
+import { getClientsCollection } from "./clients.getters";
+import type {
+  ClientQuotaState,
+  QuotaAlertInput,
+} from "./clients.quota.types";
+
+export async function getClientQuotaState(
+  clientId: string,
+): Promise<ClientQuotaState | null> {
+  const [config, client] = await Promise.all([
+    getClientConfig(clientId),
+    getClientsCollection().findOne({ clientId }),
+  ]);
+
+  const usage = config?.quota;
+  if (usage?.totalQuota === undefined || usage?.totalQuota === null) return null;
+
+  const settings = client?.quota;
+
+  return {
+    totalQuota: usage.totalQuota,
+    usedQuota: usage.usedQuota ?? 0,
+    expiresAt: usage.expiresAt,
+    alerts: settings?.alerts,
+    expiredSent: settings?.expiredSent,
+  };
+}
+
+const ensureClientDoc = async (clientId: string): Promise<void> => {
+  const now = new Date();
+  await getClientsCollection().updateOne(
+    { clientId },
+    { $setOnInsert: { clientId, createdAt: now, updatedAt: now, credits: 0 } },
+    { upsert: true },
+  );
+  await getClientsCollection().updateOne({ clientId }, { $set: { updatedAt: now } });
+};
+
+export async function updateQuotaAlertsConfig(
+  clientId: string,
+  alerts: QuotaAlertInput[],
+): Promise<void> {
+  const config = await getClientConfig(clientId);
+  if (!config) {
+    throw new Error(`No client config found for clientId: ${clientId}`);
+  }
+
+  await ensureClientDoc(clientId);
+  const state = await getClientQuotaState(clientId);
+  const existing = state?.alerts ?? [];
+  const sentByThreshold = new Map(
+    existing.filter((a) => a.thresholdSent).map((a) => [a.thresholdPct, true]),
+  );
+  const merged = alerts.map((alert) => ({
+    thresholdPct: alert.thresholdPct,
+    recipientEmails: alert.recipientEmails,
+    ...(sentByThreshold.get(alert.thresholdPct) ? { thresholdSent: true as const } : {}),
+  }));
+
+  const result = await getClientsCollection().updateOne(
+    { clientId },
+    { $set: { "quota.alerts": merged, updatedAt: new Date() } },
+  );
+
+  if (result.matchedCount === 0) {
+    throw new Error(`No client found for clientId: ${clientId}`);
+  }
+}
+
+export async function markQuotaAlertSent(
+  clientId: string,
+  alertIndex: number,
+): Promise<boolean> {
+  await ensureClientDoc(clientId);
+  const result = await getClientsCollection().findOneAndUpdate(
+    {
+      clientId,
+      [`quota.alerts.${alertIndex}.thresholdSent`]: { $ne: true },
+    },
+    { $set: { [`quota.alerts.${alertIndex}.thresholdSent`]: true, updatedAt: new Date() } },
+    { returnDocument: "after" },
+  );
+
+  return result !== null;
+}
+
+export async function markQuotaExpiredSent(clientId: string): Promise<boolean> {
+  await ensureClientDoc(clientId);
+  const result = await getClientsCollection().findOneAndUpdate(
+    {
+      clientId,
+      "quota.expiredSent": { $ne: true },
+    },
+    { $set: { "quota.expiredSent": true, updatedAt: new Date() } },
+    { returnDocument: "after" },
+  );
+
+  return result !== null;
+}
+
+export async function resetClientQuotaSettings(clientId: string): Promise<void> {
+  const client = await getClientsCollection().findOne({ clientId });
+  const alerts =
+    client?.quota?.alerts?.map(({ thresholdSent: _s, ...alert }) => alert) ?? [];
+
+  if (client) {
+    await getClientsCollection().updateOne(
+      { clientId },
+      {
+        $set: {
+          ...(alerts.length ? { "quota.alerts": alerts } : {}),
+          updatedAt: new Date(),
+        },
+        $unset: { "quota.expiredSent": "" },
+      },
+    );
+  }
+}

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

@@ -0,0 +1,27 @@
+export type QuotaThresholdAlert = {
+  thresholdPct: number;
+  recipientEmails: string[];
+  thresholdSent?: boolean;
+};
+
+export type ClientQuotaSettings = {
+  /** Up to 3 threshold alerts, each with up to 3 recipient emails. */
+  alerts?: QuotaThresholdAlert[];
+  /** Set after expired-quota email is sent successfully. */
+  expiredSent?: boolean;
+};
+
+export type QuotaAlertInput = {
+  thresholdPct: number;
+  recipientEmails: string[];
+};
+
+export type ClientQuotaUsage = {
+  totalQuota: number;
+  usedQuota: number;
+  expiresAt?: Date;
+  /** Human-readable account label for quota alert emails. */
+  clientDisplayName?: string;
+};
+
+export type ClientQuotaState = ClientQuotaUsage & ClientQuotaSettings;

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

@@ -1,4 +1,7 @@
 import { ObjectId } from "mongodb";
+import { ClientQuotaSettings } from "./clients.quota.types";
+
+export type { QuotaThresholdAlert, ClientQuotaSettings, QuotaAlertInput, ClientQuotaUsage, ClientQuotaState } from "./clients.quota.types";
 
 export type Client = {
   _id?: ObjectId;
@@ -9,6 +12,7 @@ export type Client = {
   apiKey?: string | null;
   credits: number;
   managedBy?: string;
+  quota?: ClientQuotaSettings;
 };
 
 export type ClientDoc = Client & { _id: ObjectId };

package/src/talkpilot/clients/index.ts

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

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

@@ -1,6 +1,7 @@
 import {
   createClientConfigDoc,
   getClientConfig,
+  getClientDisplayName,
 } from "../clientsConfig.getters";
 import { createClientConfig } from "../../../test-utils/factories";
 
@@ -59,6 +60,31 @@ describe("db.clientsConfig", () => {
       expect(result).toBeNull();
     });
 
+    it("should return quota.clientDisplayName when set on client config", async () => {
+      const clientId = "display-name-client";
+      await createClientConfigDoc(
+        createClientConfig({
+          clientId,
+          quota: { totalQuota: 100, usedQuota: 0, clientDisplayName: "Acme Corp" },
+        }),
+      );
+
+      expect(await getClientDisplayName(clientId)).toBe("Acme Corp");
+    });
+
+    it("should return '-' when quota.clientDisplayName is missing", async () => {
+      const clientId = "no-display-name-client";
+      await createClientConfigDoc(
+        createClientConfig({ clientId, quota: { totalQuota: 100, usedQuota: 0 } }),
+      );
+
+      expect(await getClientDisplayName(clientId)).toBe("-");
+    });
+
+    it("should return '-' when client config is missing", async () => {
+      expect(await getClientDisplayName("missing-client")).toBe("-");
+    });
+
     it("given moked_106 with both toolsPrompts when saved and retrieved then both prompts are persisted", async () => {
       // Given
       const clientId = "tools-prompts-both";

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

@@ -7,6 +7,7 @@ import {
   KnownProductKey,
 } from "../index";
 import { Collection } from "mongodb";
+import { resetClientQuotaSettings } from "../clients/clients.quota.getters";
 
 export const getClientsConfigCollection = (): Collection<ClientConfigDoc> => {
   return getDb().collection<ClientConfigDoc>("clientsConfig");
@@ -16,6 +17,15 @@ export const getClientConfig = (clientId: string) => {
   return getClientsConfigCollection().findOne({ clientId });
 };
 
+export const getClientDisplayName = async (clientId: string): Promise<string> => {
+  const doc = await getClientsConfigCollection().findOne(
+    { clientId },
+    { projection: { "quota.clientDisplayName": 1, _id: 0 } },
+  );
+  const name = doc?.quota?.clientDisplayName?.trim();
+  return name || "-";
+};
+
 export const getClientConfigByPhone = async (phone: string) => {
   const client = await findClientByPhoneNumber(phone);
   if (!client) return null;
@@ -77,3 +87,47 @@ export const clearActiveScanId = async (clientId: string): Promise<void> => {
     throw new Error(`No client config found for clientId: ${clientId}`);
   }
 };
+
+export async function listClientIdsWithConfiguredQuota(): Promise<string[]> {
+  const docs = await getClientsConfigCollection()
+    .find({ "quota.totalQuota": { $exists: true, $ne: null } })
+    .project({ clientId: 1, _id: 0 })
+    .toArray();
+
+  return docs.map(({ clientId }) => clientId);
+}
+
+export async function incrementClientQuotaUsage(
+  clientId: string,
+  amount: number = 1,
+): Promise<void> {
+  const result = await getClientsConfigCollection().updateOne(
+    { clientId, "quota.totalQuota": { $exists: true } },
+    { $inc: { "quota.usedQuota": amount } },
+  );
+
+  if (result.matchedCount === 0) {
+    return;
+  }
+}
+
+export async function resetClientQuotaUsage(clientId: string): Promise<void> {
+  const result = await getClientsConfigCollection().updateOne(
+    { clientId },
+    { $set: { "quota.usedQuota": 0 } },
+  );
+
+  if (result.matchedCount === 0) {
+    throw new Error(`No client config found for clientId: ${clientId}`);
+  }
+
+  await resetClientQuotaSettings(clientId);
+}
+
+export {
+  getClientQuotaState,
+  updateQuotaAlertsConfig,
+  markQuotaAlertSent,
+  markQuotaExpiredSent,
+  resetClientQuotaSettings,
+} from "../clients/clients.quota.getters";

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

@@ -113,6 +113,8 @@ export type CommunicationsConfig = {
   whatsapp?: WhatsappConfig;
 };
 
+import type { ClientQuotaUsage } from "../clients/clients.quota.types";
+
 export type ClientConfig<P extends Products = Products> = {
   clientId: string;
   phoneNumber?: string;
@@ -121,6 +123,7 @@ export type ClientConfig<P extends Products = Products> = {
   timezone?: string;
   communications?: CommunicationsConfig;
   callLengthThresholds?: CallLengthThresholds;
+  quota?: ClientQuotaUsage;
 };
 
 export type ClientConfigDoc<P extends Products = Products> = WithId<