@talkpilot/core-db 1.3.35 → 1.3.36

package/README.md

@@ -160,6 +160,9 @@ Refer to `DEVELOPMENT.md` for the full walkthrough, token instructions, and fact
 | 1.3.24  | **Breaking:** removed `flowId` from `WebsiteTalkProduct` — flow source of truth is `phone_numbers.flow_id`. Added `getPrimaryPhoneFlowId(clientId)`. |
 | 1.3.25  | Added `disconnectDb()` to close all MongoDB clients opened by `ensureDbConnected()` — for one-shot scripts that must exit cleanly. |
 | 1.3.28  | Soft-delete (`isActive`) on Streets/DepartmentSubjects, new bulk-write getters, MongoDB type re-exports, and the generic `bulkWrite` op-builder module. |
+| 1.3.29  | Added client call-quota module (CP-1500): `ClientConfig.quota` for usage limits (`totalQuota`, `usedQuota`, `expiresAt`), alert settings on `clients`, and getters for state, increment/reset, threshold alerts, and expiry notification tracking. |
+| 1.3.32  | `clientDisplayName` lives on `clientsConfig.quota` (not top-level). `getClientDisplayName` returns `"-"` when unset; never exposes `clientId`. |
+
 ### 1.1.9
 
 1. `npm run build`.
@@ -544,6 +547,57 @@ Adds an `isActive` soft-delete convention, bulk-write getters for Streets/Depart
 
 No — purely additive.
 
+### 1.3.29 — Client call quota (CP-1500)
+
+Per-client call quota with usage counters, optional expiration, and configurable threshold/expiry email alerts. Usage lives on clientsConfig; alert config and send-tracking live on clients. TalkPilot Server consumes these getters to block calls when quota is exceeded or expired and to send notification emails.
+
+**Data model**
+
+| Location | Field | Purpose |
+| --- | --- | --- |
+| `clientsConfig.quota` | `totalQuota`, `usedQuota`, `expiresAt?` | Call allowance and consumption. `getClientQuotaState` returns `null` when `totalQuota` is unset (quota disabled for that client). |
+| `clients.quota` | `alerts?`, `expiredSent?` | Up to 3 threshold alerts (each with up to 3 recipient emails) and a flag set after the expiry email is sent. |
+
+**Added**
+
+| Export | Purpose |
+| --- | --- |
+| `ClientQuotaUsage` | Usage shape: `totalQuota`, `usedQuota`, optional `expiresAt`. |
+| `ClientQuotaSettings` | Alert settings on the `clients` doc: `alerts`, `expiredSent`. |
+| `ClientQuotaState` | Merged view returned by `getClientQuotaState` (usage + settings). |
+| `QuotaThresholdAlert` / `QuotaAlertInput` | Threshold alert with `thresholdPct`, `recipientEmails`, and optional `thresholdSent` send-tracking. |
+| `getClientQuotaState(clientId)` | Read combined quota state; `null` when no quota is configured. |
+| `incrementClientQuotaUsage(clientId, amount?)` | Atomically increment `clientsConfig.quota.usedQuota` (default `amount = 1`). No-op when `quota.totalQuota` is absent. |
+| `resetClientQuotaUsage(clientId)` | Reset `usedQuota` to `0` and clear alert/expiry send flags via `resetClientQuotaSettings`. |
+| `updateQuotaAlertsConfig(clientId, alerts)` | Replace threshold alert config; preserves `thresholdSent` for unchanged thresholds. |
+| `markQuotaAlertSent(clientId, alertIndex)` | Idempotently mark a threshold alert as sent; returns whether the update applied. |
+| `markQuotaExpiredSent(clientId)` | Idempotently mark the expiry notification as sent; returns whether the update applied. |
+| `resetClientQuotaSettings(clientId)` | Clear `expiredSent` and strip `thresholdSent` from alerts (keeps alert definitions). |
+
+**Do I need to update my app?**
+
+No — purely additive. TalkPilot Server should upgrade to 1.3.29 (or later) to enforce quota on inbound/outbound calls and to drive threshold/expiry emails via the new getters.
+
+### 1.3.32 — Quota `clientDisplayName`
+
+Optional human-readable account label stored on `clientsConfig.quota` for quota notification emails. TalkPilot Server uses `getClientDisplayName` instead of exposing raw `clientId` in alert/expiry email copy.
+
+**Changed**
+
+| Area | What |
+| --- | --- |
+| `ClientQuotaUsage.clientDisplayName?` | Optional display name on `clientsConfig.quota` — e.g. `"Acme Corp"`. Included in `ClientQuotaState` via `getClientQuotaState`. |
+
+**Added**
+
+| Export | Purpose |
+| --- | --- |
+| `getClientDisplayName(clientId)` | Returns trimmed `quota.clientDisplayName`, or `"-"` when unset, missing, or blank. Never falls back to `clientId`. |
+
+**Do I need to update my app?**
+
+No — purely additive. Set `clientsConfig.quota.clientDisplayName` when provisioning quota for a client. **TalkPilot Server** should upgrade to **1.3.32** (or later) to use the label in quota emails.
+
 ## 🛠 CI/CD & deployment
 
 - This package is consumed by Cloud Build-based services (TalkPilot Server, MIS, CIS) as a dependency when Docker images are built. Keep `dist/` in sync with your builds because the compiled artifact is what downstream services install.

package/dist/talkpilot/clients/clients.quota.getters.d.ts

@@ -0,0 +1,7 @@
+import type { ClientQuotaState, QuotaAlertInput } from "./clients.quota.types";
+export declare function getClientQuotaState(clientId: string): Promise<ClientQuotaState | null>;
+export declare function updateQuotaAlertsConfig(clientId: string, alerts: QuotaAlertInput[]): Promise<void>;
+export declare function markQuotaAlertSent(clientId: string, alertIndex: number): Promise<boolean>;
+export declare function markQuotaExpiredSent(clientId: string): Promise<boolean>;
+export declare function resetClientQuotaSettings(clientId: string): Promise<void>;
+//# sourceMappingURL=clients.quota.getters.d.ts.map

package/dist/talkpilot/clients/clients.quota.getters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.quota.getters.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.quota.getters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAE/B,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAkBlC;AAYD,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,eAAe,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY7E;AAED,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E"}

package/dist/talkpilot/clients/clients.quota.getters.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientQuotaState = getClientQuotaState;
+exports.updateQuotaAlertsConfig = updateQuotaAlertsConfig;
+exports.markQuotaAlertSent = markQuotaAlertSent;
+exports.markQuotaExpiredSent = markQuotaExpiredSent;
+exports.resetClientQuotaSettings = resetClientQuotaSettings;
+const clientsConfig_getters_1 = require("../clientsConfig/clientsConfig.getters");
+const clients_getters_1 = require("./clients.getters");
+async function getClientQuotaState(clientId) {
+    const [config, client] = await Promise.all([
+        (0, clientsConfig_getters_1.getClientConfig)(clientId),
+        (0, clients_getters_1.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) => {
+    const now = new Date();
+    await (0, clients_getters_1.getClientsCollection)().updateOne({ clientId }, { $setOnInsert: { clientId, createdAt: now, updatedAt: now, credits: 0 } }, { upsert: true });
+    await (0, clients_getters_1.getClientsCollection)().updateOne({ clientId }, { $set: { updatedAt: now } });
+};
+async function updateQuotaAlertsConfig(clientId, alerts) {
+    const config = await (0, clientsConfig_getters_1.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 } : {}),
+    }));
+    const result = await (0, clients_getters_1.getClientsCollection)().updateOne({ clientId }, { $set: { "quota.alerts": merged, updatedAt: new Date() } });
+    if (result.matchedCount === 0) {
+        throw new Error(`No client found for clientId: ${clientId}`);
+    }
+}
+async function markQuotaAlertSent(clientId, alertIndex) {
+    await ensureClientDoc(clientId);
+    const result = await (0, clients_getters_1.getClientsCollection)().findOneAndUpdate({
+        clientId,
+        [`quota.alerts.${alertIndex}.thresholdSent`]: { $ne: true },
+    }, { $set: { [`quota.alerts.${alertIndex}.thresholdSent`]: true, updatedAt: new Date() } }, { returnDocument: "after" });
+    return result !== null;
+}
+async function markQuotaExpiredSent(clientId) {
+    await ensureClientDoc(clientId);
+    const result = await (0, clients_getters_1.getClientsCollection)().findOneAndUpdate({
+        clientId,
+        "quota.expiredSent": { $ne: true },
+    }, { $set: { "quota.expiredSent": true, updatedAt: new Date() } }, { returnDocument: "after" });
+    return result !== null;
+}
+async function resetClientQuotaSettings(clientId) {
+    const client = await (0, clients_getters_1.getClientsCollection)().findOne({ clientId });
+    const alerts = client?.quota?.alerts?.map(({ thresholdSent: _s, ...alert }) => alert) ?? [];
+    if (client) {
+        await (0, clients_getters_1.getClientsCollection)().updateOne({ clientId }, {
+            $set: {
+                ...(alerts.length ? { "quota.alerts": alerts } : {}),
+                updatedAt: new Date(),
+            },
+            $unset: { "quota.expiredSent": "" },
+        });
+    }
+}
+//# sourceMappingURL=clients.quota.getters.js.map

package/dist/talkpilot/clients/clients.quota.getters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.quota.getters.js","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.quota.getters.ts"],"names":[],"mappings":"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"}

package/dist/talkpilot/clients/clients.quota.types.d.ts

@@ -0,0 +1,24 @@
+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;
+//# sourceMappingURL=clients.quota.types.d.ts.map

package/dist/talkpilot/clients/clients.quota.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.quota.types.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.quota.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,mBAAmB,CAAC"}

package/dist/talkpilot/clients/clients.quota.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=clients.quota.types.js.map

package/dist/talkpilot/clients/clients.quota.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.quota.types.js","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.quota.types.ts"],"names":[],"mappings":""}

package/dist/talkpilot/clients/clients.types.d.ts

@@ -1,4 +1,6 @@
 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;
     createdAt: Date;
@@ -8,6 +10,7 @@ export type Client = {
     apiKey?: string | null;
     credits: number;
     managedBy?: string;
+    quota?: ClientQuotaSettings;
 };
 export type ClientDoc = Client & {
     _id: ObjectId;

package/dist/talkpilot/clients/clients.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clients.types.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,MAAM,MAAM,GAAG;IACnB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC"}
+{"version":3,"file":"clients.types.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/clients.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE3I,MAAM,MAAM,MAAM,GAAG;IACnB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC"}

package/dist/talkpilot/clients/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./clients.getters";
 export * from "./clients.types";
+export * from "./clients.quota.getters";
+export * from "./clients.quota.types";
 //# sourceMappingURL=index.d.ts.map

package/dist/talkpilot/clients/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/talkpilot/clients/index.js

@@ -16,4 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./clients.getters"), exports);
 __exportStar(require("./clients.types"), exports);
+__exportStar(require("./clients.quota.getters"), exports);
+__exportStar(require("./clients.quota.types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/talkpilot/clients/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/talkpilot/clients/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/talkpilot/clients/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,kDAAgC;AAChC,0DAAwC;AACxC,wDAAsC"}

package/dist/talkpilot/clientsConfig/clientsConfig.getters.d.ts

@@ -2,10 +2,15 @@ import { ClientConfigDoc, Products, KnownProductKey } from "../index";
 import { Collection } from "mongodb";
 export declare const getClientsConfigCollection: () => Collection<ClientConfigDoc>;
 export declare const getClientConfig: (clientId: string) => Promise<import("mongodb").WithId<ClientConfigDoc> | null>;
+export declare const getClientDisplayName: (clientId: string) => Promise<string>;
 export declare const getClientConfigByPhone: (phone: string) => Promise<import("mongodb").WithId<ClientConfigDoc> | null>;
 export declare const createClientConfigDoc: (clientConfig: ClientConfigDoc) => Promise<void>;
 export declare function updateProductConfig<K extends KnownProductKey>(clientId: string, productKey: K, updates: Partial<Products[K]>): Promise<void>;
 export declare const getActiveScanId: (clientId: string) => Promise<string | undefined>;
 export declare const updateActiveScanId: (clientId: string, scanId: string) => Promise<void>;
 export declare const clearActiveScanId: (clientId: string) => Promise<void>;
+export declare function listClientIdsWithConfiguredQuota(): Promise<string[]>;
+export declare function incrementClientQuotaUsage(clientId: string, amount?: number): Promise<void>;
+export declare function resetClientQuotaUsage(clientId: string): Promise<void>;
+export { getClientQuotaState, updateQuotaAlertsConfig, markQuotaAlertSent, markQuotaExpiredSent, resetClientQuotaSettings, } from "../clients/clients.quota.getters";
 //# sourceMappingURL=clientsConfig.getters.d.ts.map

package/dist/talkpilot/clientsConfig/clientsConfig.getters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clientsConfig.getters.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.getters.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAGf,QAAQ,EAER,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,eAAO,MAAM,0BAA0B,QAAO,UAAU,CAAC,eAAe,CAEvE,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,8DAE/C,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,OAAO,MAAM,8DAIzD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,cAAc,eAAe,KAC5B,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EACjE,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAG5B,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,QAAQ,MAAM,KACb,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,IAAI,CAQtE,CAAC"}
+{"version":3,"file":"clientsConfig.getters.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.getters.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAGf,QAAQ,EAER,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,eAAO,MAAM,0BAA0B,QAAO,UAAU,CAAC,eAAe,CAEvE,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,8DAE/C,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAO3E,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,OAAO,MAAM,8DAIzD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,cAAc,eAAe,KAC5B,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EACjE,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAG5B,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,QAAQ,MAAM,KACb,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,IAAI,CAQtE,CAAC;AAEF,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAO1E;AAED,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3E;AAED,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kCAAkC,CAAC"}

package/dist/talkpilot/clientsConfig/clientsConfig.getters.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearActiveScanId = exports.updateActiveScanId = exports.getActiveScanId = exports.createClientConfigDoc = exports.getClientConfigByPhone = exports.getClientConfig = exports.getClientsConfigCollection = void 0;
+exports.resetClientQuotaSettings = exports.markQuotaExpiredSent = exports.markQuotaAlertSent = exports.updateQuotaAlertsConfig = exports.getClientQuotaState = exports.clearActiveScanId = exports.updateActiveScanId = exports.getActiveScanId = exports.createClientConfigDoc = exports.getClientConfigByPhone = exports.getClientDisplayName = exports.getClientConfig = exports.getClientsConfigCollection = void 0;
 exports.updateProductConfig = updateProductConfig;
+exports.listClientIdsWithConfiguredQuota = listClientIdsWithConfiguredQuota;
+exports.incrementClientQuotaUsage = incrementClientQuotaUsage;
+exports.resetClientQuotaUsage = resetClientQuotaUsage;
 const index_1 = require("../index");
+const clients_quota_getters_1 = require("../clients/clients.quota.getters");
 const getClientsConfigCollection = () => {
     return (0, index_1.getDb)().collection("clientsConfig");
 };
@@ -11,6 +15,12 @@ const getClientConfig = (clientId) => {
     return (0, exports.getClientsConfigCollection)().findOne({ clientId });
 };
 exports.getClientConfig = getClientConfig;
+const getClientDisplayName = async (clientId) => {
+    const doc = await (0, exports.getClientsConfigCollection)().findOne({ clientId }, { projection: { "quota.clientDisplayName": 1, _id: 0 } });
+    const name = doc?.quota?.clientDisplayName?.trim();
+    return name || "-";
+};
+exports.getClientDisplayName = getClientDisplayName;
 const getClientConfigByPhone = async (phone) => {
     const client = await (0, index_1.findClientByPhoneNumber)(phone);
     if (!client)
@@ -51,4 +61,30 @@ const clearActiveScanId = async (clientId) => {
     }
 };
 exports.clearActiveScanId = clearActiveScanId;
+async function listClientIdsWithConfiguredQuota() {
+    const docs = await (0, exports.getClientsConfigCollection)()
+        .find({ "quota.totalQuota": { $exists: true, $ne: null } })
+        .project({ clientId: 1, _id: 0 })
+        .toArray();
+    return docs.map(({ clientId }) => clientId);
+}
+async function incrementClientQuotaUsage(clientId, amount = 1) {
+    const result = await (0, exports.getClientsConfigCollection)().updateOne({ clientId, "quota.totalQuota": { $exists: true } }, { $inc: { "quota.usedQuota": amount } });
+    if (result.matchedCount === 0) {
+        return;
+    }
+}
+async function resetClientQuotaUsage(clientId) {
+    const result = await (0, exports.getClientsConfigCollection)().updateOne({ clientId }, { $set: { "quota.usedQuota": 0 } });
+    if (result.matchedCount === 0) {
+        throw new Error(`No client config found for clientId: ${clientId}`);
+    }
+    await (0, clients_quota_getters_1.resetClientQuotaSettings)(clientId);
+}
+var clients_quota_getters_2 = require("../clients/clients.quota.getters");
+Object.defineProperty(exports, "getClientQuotaState", { enumerable: true, get: function () { return clients_quota_getters_2.getClientQuotaState; } });
+Object.defineProperty(exports, "updateQuotaAlertsConfig", { enumerable: true, get: function () { return clients_quota_getters_2.updateQuotaAlertsConfig; } });
+Object.defineProperty(exports, "markQuotaAlertSent", { enumerable: true, get: function () { return clients_quota_getters_2.markQuotaAlertSent; } });
+Object.defineProperty(exports, "markQuotaExpiredSent", { enumerable: true, get: function () { return clients_quota_getters_2.markQuotaExpiredSent; } });
+Object.defineProperty(exports, "resetClientQuotaSettings", { enumerable: true, get: function () { return clients_quota_getters_2.resetClientQuotaSettings; } });
 //# sourceMappingURL=clientsConfig.getters.js.map

package/dist/talkpilot/clientsConfig/clientsConfig.getters.js.map

@@ -1 +1 @@
-{"version":3,"file":"clientsConfig.getters.js","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.getters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clientsConfig.getters.js","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.getters.ts"],"names":[],"mappings":"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"}

package/dist/talkpilot/clientsConfig/clientsConfig.types.d.ts

@@ -75,6 +75,7 @@ export type CommunicationsConfig = {
     sms?: SmsConfig;
     whatsapp?: WhatsappConfig;
 };
+import type { ClientQuotaUsage } from "../clients/clients.quota.types";
 export type ClientConfig<P extends Products = Products> = {
     clientId: string;
     phoneNumber?: string;
@@ -83,6 +84,7 @@ export type ClientConfig<P extends Products = Products> = {
     timezone?: string;
     communications?: CommunicationsConfig;
     callLengthThresholds?: CallLengthThresholds;
+    quota?: ClientQuotaUsage;
 };
 export type ClientConfigDoc<P extends Products = Products> = WithId<ClientConfig<P>>;
 //# sourceMappingURL=clientsConfig.types.d.ts.map

package/dist/talkpilot/clientsConfig/clientsConfig.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clientsConfig.types.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clientsConfig.types.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/clientsConfig/clientsConfig.types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talkpilot/core-db",
-  "version": "1.3.35",
+  "version": "1.3.36",
   "description": "Core database package for centralized connections and ORM integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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<