@talkpilot/core-db 1.3.71 → 1.3.74

package/README.md

@@ -183,6 +183,7 @@ Refer to `DEVELOPMENT.md` for the full walkthrough, token instructions, and fact
 | 1.3.62  | Pause/Resume support for WebsiteTalk scans (CP-1752): `PAUSED` and `CANCELED` added to `SCAN_STATUSES` (`PAUSED` deliberately excluded from `FINISHED_SCAN_STATUSES` — pausing isn't done, `CANCELED` is). Added `Scan.pausedAt`, tracked across pause/resume so elapsed-time display can freeze correctly instead of counting the paused duration. |
 | 1.3.64  | New `callTokenUsage` collection with `incrementCallTokenUsage` (CP-1810): per-call realtime token usage, one document per `callSid`. |
 | 1.3.71  | Who ended a call (CP-1873): optional `Call.endedBy` (`system` / `agent` / `user`), `CallEndedByValues`, and `setCallEndedBy` (first write wins). **Breaking** vs 1.3.69–1.3.70: the value `resident` was replaced by `user`. |
+| 1.3.74  | Added `human` to `CallEndedByValues` (CP-1873): a human agent ended the call, after a transfer or in a conference. |
 
 ### 1.1.9
 
@@ -823,6 +824,14 @@ Records who ended a connected call. Unset for calls that never connected (busy,
 
 **TalkPilot Server** must upgrade to **1.3.71** to write the field. 1.3.69–1.3.70 used `resident` instead of `user` — don't use them.
 
+### 1.3.74 — Human agent ended the call (CP-1873)
+
+New `CallEndedByValues.Human` (`"human"`): a human agent ended the call, either after a transfer or in a conference.
+
+**Do I need to update my app?**
+
+No — purely additive. **TalkPilot Server** should upgrade to **1.3.74** to write it.
+
 ## 🛠 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/calls/calls.constants.d.ts

@@ -32,10 +32,11 @@ export declare const CallStatusValues: {
     readonly Canceled: "canceled";
 };
 export declare const ALL_CALL_STATUSES: ("in-progress" | "answered" | "no-answer" | "completed" | "busy" | "failed" | "canceled" | "initiated" | "ringing")[];
-/** Who ended a connected call: our platform, the bot (end flow), or the caller. */
+/** Who ended a connected call: our platform, the AI agent (end flow), the caller, or a human agent. */
 export declare const CallEndedByValues: {
     readonly System: "system";
     readonly Agent: "agent";
     readonly User: "user";
+    readonly Human: "human";
 };
 //# sourceMappingURL=calls.constants.d.ts.map

package/dist/talkpilot/calls/calls.constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calls.constants.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/calls/calls.constants.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,EAAG,UAAmB,CAAC;AAE5D,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,EAAG,YAAqB,CAAC;AAEhE,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,sCAAuC,CAAC;AAErE,4EAA4E;AAC5E,eAAO,MAAM,cAAc,mEAMjB,CAAC;AAEX,6BAA6B;AAC7B,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,iBAAiB,uHAAkC,CAAC;AAEjE,mFAAmF;AACnF,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC"}
+{"version":3,"file":"calls.constants.d.ts","sourceRoot":"","sources":["../../../src/talkpilot/calls/calls.constants.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,EAAG,UAAmB,CAAC;AAE5D,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,EAAG,YAAqB,CAAC;AAEhE,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,sCAAuC,CAAC;AAErE,4EAA4E;AAC5E,eAAO,MAAM,cAAc,mEAMjB,CAAC;AAEX,6BAA6B;AAC7B,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,iBAAiB,uHAAkC,CAAC;AAEjE,uGAAuG;AACvG,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC"}

package/dist/talkpilot/calls/calls.constants.js

@@ -41,10 +41,11 @@ exports.CallStatusValues = {
     Canceled: "canceled",
 };
 exports.ALL_CALL_STATUSES = Object.values(exports.CallStatusValues);
-/** Who ended a connected call: our platform, the bot (end flow), or the caller. */
+/** Who ended a connected call: our platform, the AI agent (end flow), the caller, or a human agent. */
 exports.CallEndedByValues = {
     System: "system",
     Agent: "agent",
     User: "user",
+    Human: "human",
 };
 //# sourceMappingURL=calls.constants.js.map

package/dist/talkpilot/calls/calls.constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"calls.constants.js","sourceRoot":"","sources":["../../../src/talkpilot/calls/calls.constants.ts"],"names":[],"mappings":";;;AAAA,8CAA8C;AACjC,QAAA,wBAAwB,GAAG,UAAmB,CAAC;AAE5D,gDAAgD;AACnC,QAAA,0BAA0B,GAAG,YAAqB,CAAC;AAEhE,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,CAAC,aAAa,EAAE,UAAU,CAAU,CAAC;AAErE,4EAA4E;AAC/D,QAAA,cAAc,GAAG;IAC5B,WAAW;IACX,WAAW;IACX,MAAM;IACN,QAAQ;IACR,UAAU;CACF,CAAC;AAEX,6BAA6B;AAChB,QAAA,aAAa,GAAG,EAAE,CAAC;AAEhC,iEAAiE;AACpD,QAAA,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;;GAKG;AACU,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAClC,QAAA,4BAA4B,GAAG,CAAC,CAAC;AAEjC,QAAA,4BAA4B,GAAG,CAAC,CAAC;AACjC,QAAA,6BAA6B,GAAG,EAAE,CAAC;AAEnC,QAAA,gBAAgB,GAAG;IAC9B,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,aAAa;IACzB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,WAAW;IACrB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEE,QAAA,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC;AAEjE,mFAAmF;AACtE,QAAA,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACJ,CAAC"}
+{"version":3,"file":"calls.constants.js","sourceRoot":"","sources":["../../../src/talkpilot/calls/calls.constants.ts"],"names":[],"mappings":";;;AAAA,8CAA8C;AACjC,QAAA,wBAAwB,GAAG,UAAmB,CAAC;AAE5D,gDAAgD;AACnC,QAAA,0BAA0B,GAAG,YAAqB,CAAC;AAEhE,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,CAAC,aAAa,EAAE,UAAU,CAAU,CAAC;AAErE,4EAA4E;AAC/D,QAAA,cAAc,GAAG;IAC5B,WAAW;IACX,WAAW;IACX,MAAM;IACN,QAAQ;IACR,UAAU;CACF,CAAC;AAEX,6BAA6B;AAChB,QAAA,aAAa,GAAG,EAAE,CAAC;AAEhC,iEAAiE;AACpD,QAAA,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;;GAKG;AACU,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAClC,QAAA,4BAA4B,GAAG,CAAC,CAAC;AAEjC,QAAA,4BAA4B,GAAG,CAAC,CAAC;AACjC,QAAA,6BAA6B,GAAG,EAAE,CAAC;AAEnC,QAAA,gBAAgB,GAAG;IAC9B,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,aAAa;IACzB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,WAAW;IACrB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEE,QAAA,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC;AAEjE,uGAAuG;AAC1F,QAAA,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;CACN,CAAC"}

package/package.json

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

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

@@ -1,519 +1,519 @@
-import {
-  createCallDoc,
-  getCallsByFlow,
-  getCallsByClient,
-  getCallsByPhoneNumber,
-  getCallByCallSid,
-  findCallsByQuery,
-  countCalls,
-  getCallsByClientAndDateRange,
-  getCallsCollection,
-  pushToolExecution,
-  getToolExecutionsByCallSid,
-  updateCallStatusByCallSid,
-  setCallEndedBy,
-} from "../calls.getters";
-import type { ToolExecution, ToolExecutionStep } from "../calls.types";
-import { ObjectId } from "mongodb";
-import { createOutGoingCallDoc } from "../../../test-utils/factories";
-
-describe("db.calls", () => {
-  it("should return calls by flow", async () => {
-    const flowId = new ObjectId();
-    const call1 = createOutGoingCallDoc({ flowId });
-    const call2 = createOutGoingCallDoc({ flowId });
-
-    await createCallDoc(call1);
-    await createCallDoc(call2);
-
-    const result = await getCallsByFlow(flowId);
-
-    expect(result.length).toBe(2);
-    expect(result).toMatchObject([
-      { callSid: call1.callSid },
-      { callSid: call2.callSid },
-    ]);
-  });
-
-  it("should get call by callSid", async () => {
-    const call = createOutGoingCallDoc();
-    await createCallDoc(call);
-
-    const result = await getCallByCallSid(call.callSid);
-
-    expect(result).toBeDefined();
-    expect(result?.callSid).toBe(call.callSid);
-  });
-
-  it("should get calls by client", async () => {
-    const call = createOutGoingCallDoc();
-    await createCallDoc(call);
-
-    const result = await getCallsByClient(call.clientId);
-
-    expect(result.some((c) => c.callSid === call.callSid)).toBe(true);
-  });
-
-  it("should get calls by phone number", async () => {
-    const call = createOutGoingCallDoc();
-    await createCallDoc(call);
-
-    const result = await getCallsByPhoneNumber(call.customerPhoneNumber);
-
-    expect(result.some((c) => c.callSid === call.callSid)).toBe(true);
-  });
-
-  it("should set current status only via updateCallStatusByCallSid", async () => {
-    const call = createOutGoingCallDoc({ status: "ringing" });
-    await createCallDoc(call);
-
-    const updated = await updateCallStatusByCallSid(call.callSid, "in-progress");
-
-    expect(updated?.status).toBe("in-progress");
-    expect(await getCallByCallSid(call.callSid)).toMatchObject({
-      status: "in-progress",
-    });
-  });
-
-  describe("setCallEndedBy()", () => {
-    it("should set endedBy when it is not set yet", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-
-      const written = await setCallEndedBy(call.callSid, "user");
-
-      expect(written).toBe(true);
-      expect(await getCallByCallSid(call.callSid)).toMatchObject({
-        endedBy: "user",
-      });
-    });
-
-    it("should keep the first value when called again", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-
-      await setCallEndedBy(call.callSid, "user");
-      const written = await setCallEndedBy(call.callSid, "agent");
-
-      expect(written).toBe(false);
-      expect(await getCallByCallSid(call.callSid)).toMatchObject({
-        endedBy: "user",
-      });
-    });
-
-    it("should let only one of two concurrent writers win", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-
-      const results = await Promise.all([
-        setCallEndedBy(call.callSid, "user"),
-        setCallEndedBy(call.callSid, "system"),
-      ]);
-
-      expect(results.filter(Boolean)).toHaveLength(1);
-      const stored = await getCallByCallSid(call.callSid);
-      expect(stored?.endedBy).toBe(results[0] ? "user" : "system");
-    });
-
-    it("should return false when the call does not exist", async () => {
-      await expect(setCallEndedBy("nonexistent-sid", "system")).resolves.toBe(
-        false,
-      );
-    });
-  });
-
-  describe("findCallsByQuery()", () => {
-    it("should find calls by status with limit and sort", async () => {
-      const clientId = "client123";
-      const call1 = createOutGoingCallDoc({ clientId, status: "completed" });
-      const call2 = createOutGoingCallDoc({ clientId, status: "completed" });
-      const call3 = createOutGoingCallDoc({ clientId, status: "busy" });
-
-      // We need to control createdAt to test sort. We'll insert directly.
-      await getCallsCollection().insertOne({
-        ...call1,
-        createdAt: new Date("2023-01-01"),
-        updatedAt: new Date(),
-        env: "test",
-      });
-      await getCallsCollection().insertOne({
-        ...call2,
-        createdAt: new Date("2023-01-02"),
-        updatedAt: new Date(),
-        env: "test",
-      });
-      await getCallsCollection().insertOne({
-        ...call3,
-        createdAt: new Date(),
-        updatedAt: new Date(),
-        env: "test",
-      });
-
-      const result = await findCallsByQuery(
-        { clientId, status: "completed" },
-        { sort: { createdAt: -1 }, limit: 1 },
-      );
-
-      expect(result.length).toBe(1);
-      expect(result[0].callSid).toBe(call2.callSid);
-    });
-  });
-
-  describe("countCalls()", () => {
-    it("should count calls matching query", async () => {
-      const clientId = "countClient";
-      await createCallDoc(
-        createOutGoingCallDoc({ clientId, status: "completed" }),
-      );
-      await createCallDoc(
-        createOutGoingCallDoc({ clientId, status: "completed" }),
-      );
-      await createCallDoc(
-        createOutGoingCallDoc({ clientId, status: "failed" }),
-      );
-
-      const count = await countCalls({ clientId, status: "completed" });
-      expect(count).toBe(2);
-    });
-  });
-
-  describe("pushToolExecution()", () => {
-    let callSid: string;
-
-    beforeEach(async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      callSid = call.callSid;
-    });
-
-    const makeHttpExecution = (
-      overrides?: Partial<ToolExecution>,
-    ): ToolExecution => ({
-      toolName: "sendSms",
-      executedAt: new Date(),
-      durationMs: 120,
-      args: { to: "+1234567890", message: "hello" },
-      meta: {
-        kind: "http",
-        url: "https://api.example.com/sms",
-        method: "POST",
-      },
-      status: "success",
-      httpStatus: 200,
-      ...overrides,
-    });
-
-    it("should append an execution to a call with none", async () => {
-      const execution = makeHttpExecution();
-      await pushToolExecution(callSid, execution);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions).toHaveLength(1);
-      expect(result?.toolExecutions?.[0]).toMatchObject({
-        toolName: "sendSms",
-        status: "success",
-        httpStatus: 200,
-      });
-    });
-
-    it("should maintain insertion order across multiple pushes", async () => {
-      const first = makeHttpExecution({ toolName: "first" });
-      const second = makeHttpExecution({ toolName: "second" });
-      const third = makeHttpExecution({ toolName: "third" });
-
-      await pushToolExecution(callSid, first);
-      await pushToolExecution(callSid, second);
-      await pushToolExecution(callSid, third);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.map((e) => e.toolName)).toEqual([
-        "first",
-        "second",
-        "third",
-      ]);
-    });
-
-    it("should store an internal tool execution", async () => {
-      const execution: ToolExecution = {
-        toolName: "endFlow",
-        executedAt: new Date(),
-        durationMs: 5,
-        args: {},
-        meta: { kind: "internal" },
-        status: "success",
-      };
-
-      await pushToolExecution(callSid, execution);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0]).toMatchObject({
-        toolName: "endFlow",
-        meta: { kind: "internal" },
-      });
-    });
-
-    it("should store redacted args for sensitive tools", async () => {
-      const execution = makeHttpExecution({ args: { _redacted: true } });
-      await pushToolExecution(callSid, execution);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0].args).toEqual({ _redacted: true });
-    });
-
-    it("should store an error execution", async () => {
-      const execution = makeHttpExecution({ status: "error", httpStatus: 500 });
-      await pushToolExecution(callSid, execution);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0]).toMatchObject({
-        status: "error",
-        httpStatus: 500,
-      });
-    });
-
-    it("should be a no-op for an unknown callSid", async () => {
-      await expect(
-        pushToolExecution("nonexistent-sid", makeHttpExecution()),
-      ).resolves.not.toThrow();
-    });
-
-    it("should store the response body", async () => {
-      const execution = makeHttpExecution({
-        response: { userId: "123", status: "sent" },
-      });
-      await pushToolExecution(callSid, execution);
-
-      const result = await getCallByCallSid(callSid);
-      expect(result?.toolExecutions?.[0].response).toEqual({
-        userId: "123",
-        status: "sent",
-      });
-    });
-  });
-
-  describe("getToolExecutionsByCallSid()", () => {
-    const makeExecution = (
-      overrides?: Partial<ToolExecution>,
-    ): ToolExecution => ({
-      toolName: "testTool",
-      executedAt: new Date(),
-      durationMs: 100,
-      args: { query: "test" },
-      meta: { kind: "http", url: "https://example.com", method: "POST" },
-      status: "success",
-      httpStatus: 200,
-      ...overrides,
-    });
-
-    it("returns all executions for a call", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "first" }));
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "second" }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result).toHaveLength(2);
-      expect(result.map((e) => e.toolName)).toEqual(["first", "second"]);
-    });
-
-    it("returns an empty array when the call has no executions", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result).toEqual([]);
-    });
-
-    it("returns an empty array for an unknown callSid", async () => {
-      const result = await getToolExecutionsByCallSid("nonexistent-sid");
-
-      expect(result).toEqual([]);
-    });
-
-    it("respects skip and limit for pagination", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      for (const name of ["a", "b", "c", "d", "e"]) {
-        await pushToolExecution(call.callSid, makeExecution({ toolName: name }));
-      }
-
-      const page1 = await getToolExecutionsByCallSid(call.callSid, { skip: 0, limit: 2 });
-      const page2 = await getToolExecutionsByCallSid(call.callSid, { skip: 2, limit: 2 });
-      const page3 = await getToolExecutionsByCallSid(call.callSid, { skip: 4, limit: 2 });
-
-      expect(page1.map((e) => e.toolName)).toEqual(["a", "b"]);
-      expect(page2.map((e) => e.toolName)).toEqual(["c", "d"]);
-      expect(page3.map((e) => e.toolName)).toEqual(["e"]);
-    });
-
-    it("includes steps when present", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      const steps: ToolExecutionStep[] = [
-        { timestamp: new Date("2024-01-01T10:00:00Z"), label: "audio_enrichment", level: "info", data: { audioUsed: true } },
-        { timestamp: new Date("2024-01-01T10:00:01Z"), label: "subject_classification", level: "warn" },
-      ];
-      await pushToolExecution(call.callSid, makeExecution({ steps }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result[0].steps).toHaveLength(2);
-      const s0 = result[0].steps![0];
-      expect(s0.label).toBe("audio_enrichment");
-      expect(s0.level).toBe("info");
-      expect(new Date(s0.timestamp).toISOString()).toBe("2024-01-01T10:00:00.000Z");
-      expect(s0.data).toEqual({ audioUsed: true });
-      const s1 = result[0].steps![1];
-      expect(s1.label).toBe("subject_classification");
-      expect(s1.level).toBe("warn");
-      expect(s1.data).toBeUndefined();
-    });
-
-    it("includes step payload when present", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      const steps: ToolExecutionStep[] = [
-        {
-          timestamp: new Date("2024-01-01T10:00:00Z"),
-          label: "subject_classification",
-          level: "info",
-          data: "Classified as: ניקיון / אשפה",
-          payload: { subject: "ניקיון", subSubject: "אשפה", ids: { subject: "abc", subSubject: "def" } },
-        },
-      ];
-      await pushToolExecution(call.callSid, makeExecution({ steps }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      const s0 = result[0].steps![0];
-      expect(s0.data).toBe("Classified as: ניקיון / אשפה");
-      expect(s0.payload).toEqual({ subject: "ניקיון", subSubject: "אשפה", ids: { subject: "abc", subSubject: "def" } });
-    });
-
-    it("does not require step payload to be present", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      const steps: ToolExecutionStep[] = [
-        { timestamp: new Date(), label: "user_query", level: "info", data: "Query: הרצל" },
-      ];
-      await pushToolExecution(call.callSid, makeExecution({ steps }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result[0].steps![0].payload).toBeUndefined();
-    });
-
-    it("does not require steps to be present", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution());
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result[0].steps).toBeUndefined();
-    });
-
-    it("returns at most 50 executions by default", async () => {
-      const call = createOutGoingCallDoc();
-      await getCallsCollection().insertOne({
-        ...call,
-        createdAt: new Date(),
-        updatedAt: new Date(),
-        env: "test",
-        toolExecutions: Array.from({ length: 51 }, (_, i) =>
-          makeExecution({ toolName: `tool${i}` }),
-        ),
-      });
-
-      const result = await getToolExecutionsByCallSid(call.callSid);
-
-      expect(result).toHaveLength(50);
-      expect(result[0].toolName).toBe("tool0");
-      expect(result[49].toolName).toBe("tool49");
-    });
-
-    it("clamps negative skip to 0", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "only" }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid, { skip: -5 });
-
-      expect(result).toHaveLength(1);
-      expect(result[0].toolName).toBe("only");
-    });
-
-    it("clamps negative limit to 1", async () => {
-      const call = createOutGoingCallDoc();
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "first" }));
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "second" }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid, { limit: -1 });
-
-      expect(result).toHaveLength(1);
-    });
-
-    it("returns executions when clientId matches the call's client", async () => {
-      const call = createOutGoingCallDoc({ clientId: "clientA" });
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "secret" }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid, { clientId: "clientA" });
-
-      expect(result).toHaveLength(1);
-      expect(result[0].toolName).toBe("secret");
-    });
-
-    it("returns empty when clientId does not match the call's client", async () => {
-      const call = createOutGoingCallDoc({ clientId: "clientA" });
-      await createCallDoc(call);
-      await pushToolExecution(call.callSid, makeExecution({ toolName: "secret" }));
-
-      const result = await getToolExecutionsByCallSid(call.callSid, { clientId: "clientB" });
-
-      expect(result).toEqual([]);
-    });
-  });
-
-  describe("getCallsByClientAndDateRange()", () => {
-    it("should return calls within date range", async () => {
-      const clientId = "dateRangeClient";
-      const startDate = new Date("2023-05-01");
-      const endDate = new Date("2023-05-31");
-
-      const callInside = createOutGoingCallDoc({ clientId });
-      const callBefore = createOutGoingCallDoc({ clientId });
-      const callAfter = createOutGoingCallDoc({ clientId });
-
-      await getCallsCollection().insertOne({
-        ...callInside,
-        createdAt: new Date("2023-05-15"),
-        updatedAt: new Date(),
-        env: "test",
-      });
-      await getCallsCollection().insertOne({
-        ...callBefore,
-        createdAt: new Date("2023-04-30"),
-        updatedAt: new Date(),
-        env: "test",
-      });
-      await getCallsCollection().insertOne({
-        ...callAfter,
-        createdAt: new Date("2023-06-01"),
-        updatedAt: new Date(),
-        env: "test",
-      });
-
-      const result = await getCallsByClientAndDateRange(
-        clientId,
-        startDate,
-        endDate,
-      );
-      expect(result.length).toBe(1);
-      expect(result[0].callSid).toBe(callInside.callSid);
-    });
-  });
-});
+import {
+  createCallDoc,
+  getCallsByFlow,
+  getCallsByClient,
+  getCallsByPhoneNumber,
+  getCallByCallSid,
+  findCallsByQuery,
+  countCalls,
+  getCallsByClientAndDateRange,
+  getCallsCollection,
+  pushToolExecution,
+  getToolExecutionsByCallSid,
+  updateCallStatusByCallSid,
+  setCallEndedBy,
+} from "../calls.getters";
+import type { ToolExecution, ToolExecutionStep } from "../calls.types";
+import { ObjectId } from "mongodb";
+import { createOutGoingCallDoc } from "../../../test-utils/factories";
+
+describe("db.calls", () => {
+  it("should return calls by flow", async () => {
+    const flowId = new ObjectId();
+    const call1 = createOutGoingCallDoc({ flowId });
+    const call2 = createOutGoingCallDoc({ flowId });
+
+    await createCallDoc(call1);
+    await createCallDoc(call2);
+
+    const result = await getCallsByFlow(flowId);
+
+    expect(result.length).toBe(2);
+    expect(result).toMatchObject([
+      { callSid: call1.callSid },
+      { callSid: call2.callSid },
+    ]);
+  });
+
+  it("should get call by callSid", async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallByCallSid(call.callSid);
+
+    expect(result).toBeDefined();
+    expect(result?.callSid).toBe(call.callSid);
+  });
+
+  it("should get calls by client", async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallsByClient(call.clientId);
+
+    expect(result.some((c) => c.callSid === call.callSid)).toBe(true);
+  });
+
+  it("should get calls by phone number", async () => {
+    const call = createOutGoingCallDoc();
+    await createCallDoc(call);
+
+    const result = await getCallsByPhoneNumber(call.customerPhoneNumber);
+
+    expect(result.some((c) => c.callSid === call.callSid)).toBe(true);
+  });
+
+  it("should set current status only via updateCallStatusByCallSid", async () => {
+    const call = createOutGoingCallDoc({ status: "ringing" });
+    await createCallDoc(call);
+
+    const updated = await updateCallStatusByCallSid(call.callSid, "in-progress");
+
+    expect(updated?.status).toBe("in-progress");
+    expect(await getCallByCallSid(call.callSid)).toMatchObject({
+      status: "in-progress",
+    });
+  });
+
+  describe("setCallEndedBy()", () => {
+    it("should set endedBy when it is not set yet", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+
+      const written = await setCallEndedBy(call.callSid, "user");
+
+      expect(written).toBe(true);
+      expect(await getCallByCallSid(call.callSid)).toMatchObject({
+        endedBy: "user",
+      });
+    });
+
+    it("should keep the first value when called again", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+
+      await setCallEndedBy(call.callSid, "user");
+      const written = await setCallEndedBy(call.callSid, "agent");
+
+      expect(written).toBe(false);
+      expect(await getCallByCallSid(call.callSid)).toMatchObject({
+        endedBy: "user",
+      });
+    });
+
+    it("should let only one of two concurrent writers win", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+
+      const results = await Promise.all([
+        setCallEndedBy(call.callSid, "user"),
+        setCallEndedBy(call.callSid, "human"),
+      ]);
+
+      expect(results.filter(Boolean)).toHaveLength(1);
+      const stored = await getCallByCallSid(call.callSid);
+      expect(stored?.endedBy).toBe(results[0] ? "user" : "human");
+    });
+
+    it("should return false when the call does not exist", async () => {
+      await expect(setCallEndedBy("nonexistent-sid", "system")).resolves.toBe(
+        false,
+      );
+    });
+  });
+
+  describe("findCallsByQuery()", () => {
+    it("should find calls by status with limit and sort", async () => {
+      const clientId = "client123";
+      const call1 = createOutGoingCallDoc({ clientId, status: "completed" });
+      const call2 = createOutGoingCallDoc({ clientId, status: "completed" });
+      const call3 = createOutGoingCallDoc({ clientId, status: "busy" });
+
+      // We need to control createdAt to test sort. We'll insert directly.
+      await getCallsCollection().insertOne({
+        ...call1,
+        createdAt: new Date("2023-01-01"),
+        updatedAt: new Date(),
+        env: "test",
+      });
+      await getCallsCollection().insertOne({
+        ...call2,
+        createdAt: new Date("2023-01-02"),
+        updatedAt: new Date(),
+        env: "test",
+      });
+      await getCallsCollection().insertOne({
+        ...call3,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        env: "test",
+      });
+
+      const result = await findCallsByQuery(
+        { clientId, status: "completed" },
+        { sort: { createdAt: -1 }, limit: 1 },
+      );
+
+      expect(result.length).toBe(1);
+      expect(result[0].callSid).toBe(call2.callSid);
+    });
+  });
+
+  describe("countCalls()", () => {
+    it("should count calls matching query", async () => {
+      const clientId = "countClient";
+      await createCallDoc(
+        createOutGoingCallDoc({ clientId, status: "completed" }),
+      );
+      await createCallDoc(
+        createOutGoingCallDoc({ clientId, status: "completed" }),
+      );
+      await createCallDoc(
+        createOutGoingCallDoc({ clientId, status: "failed" }),
+      );
+
+      const count = await countCalls({ clientId, status: "completed" });
+      expect(count).toBe(2);
+    });
+  });
+
+  describe("pushToolExecution()", () => {
+    let callSid: string;
+
+    beforeEach(async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      callSid = call.callSid;
+    });
+
+    const makeHttpExecution = (
+      overrides?: Partial<ToolExecution>,
+    ): ToolExecution => ({
+      toolName: "sendSms",
+      executedAt: new Date(),
+      durationMs: 120,
+      args: { to: "+1234567890", message: "hello" },
+      meta: {
+        kind: "http",
+        url: "https://api.example.com/sms",
+        method: "POST",
+      },
+      status: "success",
+      httpStatus: 200,
+      ...overrides,
+    });
+
+    it("should append an execution to a call with none", async () => {
+      const execution = makeHttpExecution();
+      await pushToolExecution(callSid, execution);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions).toHaveLength(1);
+      expect(result?.toolExecutions?.[0]).toMatchObject({
+        toolName: "sendSms",
+        status: "success",
+        httpStatus: 200,
+      });
+    });
+
+    it("should maintain insertion order across multiple pushes", async () => {
+      const first = makeHttpExecution({ toolName: "first" });
+      const second = makeHttpExecution({ toolName: "second" });
+      const third = makeHttpExecution({ toolName: "third" });
+
+      await pushToolExecution(callSid, first);
+      await pushToolExecution(callSid, second);
+      await pushToolExecution(callSid, third);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions?.map((e) => e.toolName)).toEqual([
+        "first",
+        "second",
+        "third",
+      ]);
+    });
+
+    it("should store an internal tool execution", async () => {
+      const execution: ToolExecution = {
+        toolName: "endFlow",
+        executedAt: new Date(),
+        durationMs: 5,
+        args: {},
+        meta: { kind: "internal" },
+        status: "success",
+      };
+
+      await pushToolExecution(callSid, execution);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions?.[0]).toMatchObject({
+        toolName: "endFlow",
+        meta: { kind: "internal" },
+      });
+    });
+
+    it("should store redacted args for sensitive tools", async () => {
+      const execution = makeHttpExecution({ args: { _redacted: true } });
+      await pushToolExecution(callSid, execution);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions?.[0].args).toEqual({ _redacted: true });
+    });
+
+    it("should store an error execution", async () => {
+      const execution = makeHttpExecution({ status: "error", httpStatus: 500 });
+      await pushToolExecution(callSid, execution);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions?.[0]).toMatchObject({
+        status: "error",
+        httpStatus: 500,
+      });
+    });
+
+    it("should be a no-op for an unknown callSid", async () => {
+      await expect(
+        pushToolExecution("nonexistent-sid", makeHttpExecution()),
+      ).resolves.not.toThrow();
+    });
+
+    it("should store the response body", async () => {
+      const execution = makeHttpExecution({
+        response: { userId: "123", status: "sent" },
+      });
+      await pushToolExecution(callSid, execution);
+
+      const result = await getCallByCallSid(callSid);
+      expect(result?.toolExecutions?.[0].response).toEqual({
+        userId: "123",
+        status: "sent",
+      });
+    });
+  });
+
+  describe("getToolExecutionsByCallSid()", () => {
+    const makeExecution = (
+      overrides?: Partial<ToolExecution>,
+    ): ToolExecution => ({
+      toolName: "testTool",
+      executedAt: new Date(),
+      durationMs: 100,
+      args: { query: "test" },
+      meta: { kind: "http", url: "https://example.com", method: "POST" },
+      status: "success",
+      httpStatus: 200,
+      ...overrides,
+    });
+
+    it("returns all executions for a call", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "first" }));
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "second" }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result).toHaveLength(2);
+      expect(result.map((e) => e.toolName)).toEqual(["first", "second"]);
+    });
+
+    it("returns an empty array when the call has no executions", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result).toEqual([]);
+    });
+
+    it("returns an empty array for an unknown callSid", async () => {
+      const result = await getToolExecutionsByCallSid("nonexistent-sid");
+
+      expect(result).toEqual([]);
+    });
+
+    it("respects skip and limit for pagination", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      for (const name of ["a", "b", "c", "d", "e"]) {
+        await pushToolExecution(call.callSid, makeExecution({ toolName: name }));
+      }
+
+      const page1 = await getToolExecutionsByCallSid(call.callSid, { skip: 0, limit: 2 });
+      const page2 = await getToolExecutionsByCallSid(call.callSid, { skip: 2, limit: 2 });
+      const page3 = await getToolExecutionsByCallSid(call.callSid, { skip: 4, limit: 2 });
+
+      expect(page1.map((e) => e.toolName)).toEqual(["a", "b"]);
+      expect(page2.map((e) => e.toolName)).toEqual(["c", "d"]);
+      expect(page3.map((e) => e.toolName)).toEqual(["e"]);
+    });
+
+    it("includes steps when present", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      const steps: ToolExecutionStep[] = [
+        { timestamp: new Date("2024-01-01T10:00:00Z"), label: "audio_enrichment", level: "info", data: { audioUsed: true } },
+        { timestamp: new Date("2024-01-01T10:00:01Z"), label: "subject_classification", level: "warn" },
+      ];
+      await pushToolExecution(call.callSid, makeExecution({ steps }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result[0].steps).toHaveLength(2);
+      const s0 = result[0].steps![0];
+      expect(s0.label).toBe("audio_enrichment");
+      expect(s0.level).toBe("info");
+      expect(new Date(s0.timestamp).toISOString()).toBe("2024-01-01T10:00:00.000Z");
+      expect(s0.data).toEqual({ audioUsed: true });
+      const s1 = result[0].steps![1];
+      expect(s1.label).toBe("subject_classification");
+      expect(s1.level).toBe("warn");
+      expect(s1.data).toBeUndefined();
+    });
+
+    it("includes step payload when present", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      const steps: ToolExecutionStep[] = [
+        {
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+          label: "subject_classification",
+          level: "info",
+          data: "Classified as: ניקיון / אשפה",
+          payload: { subject: "ניקיון", subSubject: "אשפה", ids: { subject: "abc", subSubject: "def" } },
+        },
+      ];
+      await pushToolExecution(call.callSid, makeExecution({ steps }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      const s0 = result[0].steps![0];
+      expect(s0.data).toBe("Classified as: ניקיון / אשפה");
+      expect(s0.payload).toEqual({ subject: "ניקיון", subSubject: "אשפה", ids: { subject: "abc", subSubject: "def" } });
+    });
+
+    it("does not require step payload to be present", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      const steps: ToolExecutionStep[] = [
+        { timestamp: new Date(), label: "user_query", level: "info", data: "Query: הרצל" },
+      ];
+      await pushToolExecution(call.callSid, makeExecution({ steps }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result[0].steps![0].payload).toBeUndefined();
+    });
+
+    it("does not require steps to be present", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution());
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result[0].steps).toBeUndefined();
+    });
+
+    it("returns at most 50 executions by default", async () => {
+      const call = createOutGoingCallDoc();
+      await getCallsCollection().insertOne({
+        ...call,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        env: "test",
+        toolExecutions: Array.from({ length: 51 }, (_, i) =>
+          makeExecution({ toolName: `tool${i}` }),
+        ),
+      });
+
+      const result = await getToolExecutionsByCallSid(call.callSid);
+
+      expect(result).toHaveLength(50);
+      expect(result[0].toolName).toBe("tool0");
+      expect(result[49].toolName).toBe("tool49");
+    });
+
+    it("clamps negative skip to 0", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "only" }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid, { skip: -5 });
+
+      expect(result).toHaveLength(1);
+      expect(result[0].toolName).toBe("only");
+    });
+
+    it("clamps negative limit to 1", async () => {
+      const call = createOutGoingCallDoc();
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "first" }));
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "second" }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid, { limit: -1 });
+
+      expect(result).toHaveLength(1);
+    });
+
+    it("returns executions when clientId matches the call's client", async () => {
+      const call = createOutGoingCallDoc({ clientId: "clientA" });
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "secret" }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid, { clientId: "clientA" });
+
+      expect(result).toHaveLength(1);
+      expect(result[0].toolName).toBe("secret");
+    });
+
+    it("returns empty when clientId does not match the call's client", async () => {
+      const call = createOutGoingCallDoc({ clientId: "clientA" });
+      await createCallDoc(call);
+      await pushToolExecution(call.callSid, makeExecution({ toolName: "secret" }));
+
+      const result = await getToolExecutionsByCallSid(call.callSid, { clientId: "clientB" });
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("getCallsByClientAndDateRange()", () => {
+    it("should return calls within date range", async () => {
+      const clientId = "dateRangeClient";
+      const startDate = new Date("2023-05-01");
+      const endDate = new Date("2023-05-31");
+
+      const callInside = createOutGoingCallDoc({ clientId });
+      const callBefore = createOutGoingCallDoc({ clientId });
+      const callAfter = createOutGoingCallDoc({ clientId });
+
+      await getCallsCollection().insertOne({
+        ...callInside,
+        createdAt: new Date("2023-05-15"),
+        updatedAt: new Date(),
+        env: "test",
+      });
+      await getCallsCollection().insertOne({
+        ...callBefore,
+        createdAt: new Date("2023-04-30"),
+        updatedAt: new Date(),
+        env: "test",
+      });
+      await getCallsCollection().insertOne({
+        ...callAfter,
+        createdAt: new Date("2023-06-01"),
+        updatedAt: new Date(),
+        env: "test",
+      });
+
+      const result = await getCallsByClientAndDateRange(
+        clientId,
+        startDate,
+        endDate,
+      );
+      expect(result.length).toBe(1);
+      expect(result[0].callSid).toBe(callInside.callSid);
+    });
+  });
+});

package/src/talkpilot/calls/calls.constants.ts

@@ -48,9 +48,10 @@ export const CallStatusValues = {
 
 export const ALL_CALL_STATUSES = Object.values(CallStatusValues);
 
-/** Who ended a connected call: our platform, the bot (end flow), or the caller. */
+/** Who ended a connected call: our platform, the AI agent (end flow), the caller, or a human agent. */
 export const CallEndedByValues = {
   System: "system",
   Agent: "agent",
   User: "user",
+  Human: "human",
 } as const;