@talkpilot/core-db 1.3.75 → 1.3.77

package/src/municipal/muniIssues/__tests__/muniIssues.setup.spec.ts

@@ -1,92 +1,93 @@
-import {
-  ensureMuniIssuesCollection,
-  ensureMuniIssuesCollectionOnce,
-} from "../muniIssues.setup";
-import {
-  generateMuniIssueId,
-  getMuniIssuesCollection,
-} from "../muniIssues.getters";
-import { createMuniIssue } from "../muniIssues.setters";
-import { getDb } from "../../index";
-import { MUNI_ISSUES_COLLECTION } from "../muniIssues.constants";
-import { createMuniIssueInput } from "../../../test-utils/factories";
-
-describe("muniIssues setup", () => {
-  describe("ensureMuniIssuesCollection", () => {
-    it("should create the collection with a validator and the declared indexes", async () => {
-      await ensureMuniIssuesCollection();
-
-      const [collection] = (await getDb()
-        .listCollections({ name: MUNI_ISSUES_COLLECTION })
-        .toArray()) as { options?: { validator?: unknown } }[];
-      expect(collection?.options?.validator).toHaveProperty("$jsonSchema");
-
-      const indexNames = (await getMuniIssuesCollection().indexes()).map(
-        (i) => i.name,
-      );
-      expect(indexNames).toEqual(
-        expect.arrayContaining([
-          "callSid_1",
-          "createdAt_-1",
-          "jira_key_unique",
-        ]),
-      );
-    });
-
-    it("should accept a valid document and reject ones that violate the schema", async () => {
-      await ensureMuniIssuesCollection();
-
-      await expect(
-        createMuniIssue(createMuniIssueInput(), generateMuniIssueId()),
-      ).resolves.toBeDefined();
-
-      // Missing required issueContent fields → DB validation rejects it.
-      await expect(
-        getMuniIssuesCollection().insertOne({
-          callSid: "CA-bad",
-          createdAt: new Date(),
-        } as never),
-      ).rejects.toThrow();
-
-      // jira.syncStatus outside the enum → DB validation rejects it.
-      await expect(
-        createMuniIssue(
-          createMuniIssueInput({
-            jira: { key: "CP-99", syncStatus: "weird" as never },
-          }),
-          generateMuniIssueId(),
-        ),
-      ).rejects.toThrow();
-    });
-
-    it("should enforce the unique jira.key index", async () => {
-      await ensureMuniIssuesCollection();
-      const input = createMuniIssueInput();
-      await createMuniIssue(input, generateMuniIssueId());
-
-      // Same jira.key on a second insert violates the unique index.
-      await expect(
-        createMuniIssue(input, generateMuniIssueId()),
-      ).rejects.toThrow();
-    });
-
-    it("should be idempotent when run twice", async () => {
-      await ensureMuniIssuesCollection();
-      await expect(ensureMuniIssuesCollection()).resolves.toBeUndefined();
-    });
-  });
-
-  describe("ensureMuniIssuesCollectionOnce", () => {
-    it("should run the provisioning work at most once per process", async () => {
-      const createSpy = jest.spyOn(getDb(), "createCollection");
-
-      await Promise.all([
-        ensureMuniIssuesCollectionOnce(),
-        ensureMuniIssuesCollectionOnce(),
-      ]);
-      await ensureMuniIssuesCollectionOnce();
-
-      expect(createSpy).toHaveBeenCalledTimes(1);
-    });
-  });
-});
+import {
+  ensureMuniIssuesCollection,
+  ensureMuniIssuesCollectionOnce,
+} from "../muniIssues.setup";
+import {
+  generateMuniIssueId,
+  getMuniIssuesCollection,
+} from "../muniIssues.getters";
+import { createMuniIssue } from "../muniIssues.setters";
+import { getDb } from "../../index";
+import { MUNI_ISSUES_COLLECTION } from "../muniIssues.constants";
+import { createMuniIssueInput } from "../../../test-utils/factories";
+
+describe("muniIssues setup", () => {
+  describe("ensureMuniIssuesCollection", () => {
+    it("should create the collection with a validator and the declared indexes", async () => {
+      await ensureMuniIssuesCollection();
+
+      const [collection] = (await getDb()
+        .listCollections({ name: MUNI_ISSUES_COLLECTION })
+        .toArray()) as { options?: { validator?: unknown } }[];
+      expect(collection?.options?.validator).toHaveProperty("$jsonSchema");
+
+      const indexNames = (await getMuniIssuesCollection().indexes()).map(
+        (i) => i.name,
+      );
+      expect(indexNames).toEqual(
+        expect.arrayContaining([
+          "callSid_1",
+          "createdAt_-1",
+          "clientId_1_createdAt_-1",
+          "jira_key_unique",
+        ]),
+      );
+    });
+
+    it("should accept a valid document and reject ones that violate the schema", async () => {
+      await ensureMuniIssuesCollection();
+
+      await expect(
+        createMuniIssue(createMuniIssueInput(), generateMuniIssueId()),
+      ).resolves.toBeDefined();
+
+      // Missing required issueContent fields → DB validation rejects it.
+      await expect(
+        getMuniIssuesCollection().insertOne({
+          callSid: "CA-bad",
+          createdAt: new Date(),
+        } as never),
+      ).rejects.toThrow();
+
+      // jira.syncStatus outside the enum → DB validation rejects it.
+      await expect(
+        createMuniIssue(
+          createMuniIssueInput({
+            jira: { key: "CP-99", syncStatus: "weird" as never },
+          }),
+          generateMuniIssueId(),
+        ),
+      ).rejects.toThrow();
+    });
+
+    it("should enforce the unique jira.key index", async () => {
+      await ensureMuniIssuesCollection();
+      const input = createMuniIssueInput();
+      await createMuniIssue(input, generateMuniIssueId());
+
+      // Same jira.key on a second insert violates the unique index.
+      await expect(
+        createMuniIssue(input, generateMuniIssueId()),
+      ).rejects.toThrow();
+    });
+
+    it("should be idempotent when run twice", async () => {
+      await ensureMuniIssuesCollection();
+      await expect(ensureMuniIssuesCollection()).resolves.toBeUndefined();
+    });
+  });
+
+  describe("ensureMuniIssuesCollectionOnce", () => {
+    it("should run the provisioning work at most once per process", async () => {
+      const createSpy = jest.spyOn(getDb(), "createCollection");
+
+      await Promise.all([
+        ensureMuniIssuesCollectionOnce(),
+        ensureMuniIssuesCollectionOnce(),
+      ]);
+      await ensureMuniIssuesCollectionOnce();
+
+      expect(createSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/municipal/muniIssues/index.ts

@@ -1,17 +1,22 @@
-export * from "./muniIssues.getters";
-export * from "./muniIssues.setters";
-export * from "./muniIssues.setup";
-export {
-  MUNI_ISSUES_COLLECTION,
-  MUNI_ISSUE_SYNC_STATUSES,
-  MUNI_ISSUE_TEXT_MAX_LENGTH,
-  MUNI_ISSUE_NAME_MAX_LENGTH,
-} from "./muniIssues.constants";
-export { muniIssuesJsonSchema, muniIssuesIndexes } from "./muniIssues.schema";
-export type {
-  MuniIssue,
-  MuniIssueContent,
-  MuniIssueJira,
-  MuniIssueSyncStatus,
-  CreateMuniIssueInput,
-} from "./muniIssues.types";
+export * from "./muniIssues.getters";
+export * from "./muniIssues.setters";
+export * from "./muniIssues.setup";
+export {
+  MUNI_ISSUES_COLLECTION,
+  MUNI_ISSUE_STATUSES,
+  MUNI_ISSUE_SYNC_STATUSES,
+  MUNI_ISSUE_TEXT_MAX_LENGTH,
+  MUNI_ISSUE_NAME_MAX_LENGTH,
+} from "./muniIssues.constants";
+export { muniIssuesJsonSchema, muniIssuesIndexes } from "./muniIssues.schema";
+export type {
+  MuniIssue,
+  MuniIssueContent,
+  MuniIssueJira,
+  MuniIssueSyncStatus,
+  MuniIssueStatus,
+  MuniIssueResponse,
+  CreateMuniIssueInput,
+  SetMuniIssueResponseInput,
+  FindMuniIssuesOptions,
+} from "./muniIssues.types";

package/src/municipal/muniIssues/muniIssues.constants.ts

@@ -1,18 +1,26 @@
-/** Mongo collection name for reported municipal issues. */
-export const MUNI_ISSUES_COLLECTION = "muniIssues";
-
-/** Sync state of the issue's Jira ticket at write time. */
-export const MUNI_ISSUE_SYNC_STATUSES = ["created", "failed"] as const;
-
-/** Max length for the long free-text fields — well above the ~2000-char target. */
-export const MUNI_ISSUE_TEXT_MAX_LENGTH = 5000;
-
-/** Max length for the short identity fields (a person's name and role). */
-export const MUNI_ISSUE_NAME_MAX_LENGTH = 200;
-
-/** MongoDB error 48 (NamespaceExists): collection already exists, e.g. concurrent createCollection. */
-export const NAMESPACE_EXISTS = 48;
-
-/** Reject (not just flag) writes that fail the $jsonSchema validator. */
-export const VALIDATION_LEVEL = "strict" as const;
-export const VALIDATION_ACTION = "error" as const;
+/** Mongo collection name for reported municipal issues. */
+export const MUNI_ISSUES_COLLECTION = "muniIssues";
+
+/** Sync state of the issue's Jira ticket at write time. */
+export const MUNI_ISSUE_SYNC_STATUSES = ["created", "failed"] as const;
+
+/** Customer-facing complaint status, set manually by the TalkPilot team. */
+export const MUNI_ISSUE_STATUSES = [
+  "in_review",
+  "in_progress",
+  "resolved",
+  "no_issue_found",
+] as const;
+
+/** Max length for the long free-text fields — well above the ~2000-char target. */
+export const MUNI_ISSUE_TEXT_MAX_LENGTH = 5000;
+
+/** Max length for the short identity fields (a person's name and role). */
+export const MUNI_ISSUE_NAME_MAX_LENGTH = 200;
+
+/** MongoDB error 48 (NamespaceExists): collection already exists, e.g. concurrent createCollection. */
+export const NAMESPACE_EXISTS = 48;
+
+/** Reject (not just flag) writes that fail the $jsonSchema validator. */
+export const VALIDATION_LEVEL = "strict" as const;
+export const VALIDATION_ACTION = "error" as const;

package/src/municipal/muniIssues/muniIssues.getters.ts

@@ -1,24 +1,68 @@
-import { Collection, ObjectId } from "mongodb";
-import { getDb } from "../index";
-import { MuniIssue } from "./muniIssues.types";
-import { MUNI_ISSUES_COLLECTION } from "./muniIssues.constants";
-
-export const getMuniIssuesCollection = (): Collection<MuniIssue> => {
-  return getDb().collection<MuniIssue>(MUNI_ISSUES_COLLECTION);
-};
-
-export const generateMuniIssueId = (): ObjectId => new ObjectId();
-
-export const getMuniIssueById = async (
-  id: string,
-): Promise<MuniIssue | null> => {
-  // A malformed id is treated as not-found rather than throwing on `new ObjectId`.
-  if (!ObjectId.isValid(id)) return null;
-  return getMuniIssuesCollection().findOne({ _id: new ObjectId(id) });
-};
-
-export const getMuniIssueByJiraKey = async (
-  jiraKey: string,
-): Promise<MuniIssue | null> => {
-  return getMuniIssuesCollection().findOne({ "jira.key": jiraKey });
-};
+import { Collection, Filter, ObjectId } from "mongodb";
+import { getDb } from "../index";
+import { FindMuniIssuesOptions, MuniIssue } from "./muniIssues.types";
+import { MUNI_ISSUES_COLLECTION } from "./muniIssues.constants";
+
+export const getMuniIssuesCollection = (): Collection<MuniIssue> => {
+  return getDb().collection<MuniIssue>(MUNI_ISSUES_COLLECTION);
+};
+
+export const generateMuniIssueId = (): ObjectId => new ObjectId();
+
+export const getMuniIssueById = async (
+  id: string,
+): Promise<MuniIssue | null> => {
+  // A malformed id is treated as not-found rather than throwing on `new ObjectId`.
+  if (!ObjectId.isValid(id)) return null;
+  return getMuniIssuesCollection().findOne({ _id: new ObjectId(id) });
+};
+
+export const getMuniIssueByJiraKey = async (
+  jiraKey: string,
+): Promise<MuniIssue | null> => {
+  return getMuniIssuesCollection().findOne({ "jira.key": jiraKey });
+};
+
+// Tracked issues of one client. Issues without a status predate complaint tracking and are excluded.
+const clientIssuesFilter = (
+  clientId: string,
+  answered?: boolean,
+): Filter<MuniIssue> => ({
+  clientId,
+  status: { $exists: true },
+  ...(answered !== undefined && { response: { $exists: answered } }),
+});
+
+/** A client's tracked issues, newest first. `limit` 0 means no limit (Mongo). */
+export const findMuniIssuesByClient = async (
+  clientId: string,
+  { answered, skip = 0, limit = 0 }: FindMuniIssuesOptions = {},
+): Promise<MuniIssue[]> => {
+  return getMuniIssuesCollection()
+    .find(clientIssuesFilter(clientId, answered))
+    .sort({ createdAt: -1 })
+    .skip(skip)
+    .limit(limit)
+    .toArray();
+};
+
+export const countMuniIssuesByClient = async (
+  clientId: string,
+  { answered }: Pick<FindMuniIssuesOptions, "answered"> = {},
+): Promise<number> => {
+  return getMuniIssuesCollection().countDocuments(
+    clientIssuesFilter(clientId, answered),
+  );
+};
+
+/** One tracked issue, only if it belongs to the client. */
+export const getMuniIssueByIdForClient = async (
+  id: string,
+  clientId: string,
+): Promise<MuniIssue | null> => {
+  if (!ObjectId.isValid(id)) return null;
+  return getMuniIssuesCollection().findOne({
+    ...clientIssuesFilter(clientId),
+    _id: new ObjectId(id),
+  });
+};

package/src/municipal/muniIssues/muniIssues.schema.ts

@@ -1,66 +1,80 @@
-import type { Document, IndexDescription } from "mongodb";
-import {
-  MUNI_ISSUE_SYNC_STATUSES,
-  MUNI_ISSUE_TEXT_MAX_LENGTH,
-  MUNI_ISSUE_NAME_MAX_LENGTH,
-} from "./muniIssues.constants";
-
-export const muniIssuesJsonSchema: Document = {
-  bsonType: "object",
-  required: [
-    "callSid",
-    "clientId",
-    "cityName",
-    "issueContent",
-    "jira",
-    "createdAt",
-  ],
-  properties: {
-    callSid: { bsonType: "string" },
-    clientId: { bsonType: "string" },
-    cityName: { bsonType: "string" },
-    issueContent: {
-      bsonType: "object",
-      required: [
-        "issuerName",
-        "issuerRole",
-        "issueDescription",
-        "desiredBehavior",
-      ],
-      properties: {
-        issuerName: {
-          bsonType: "string",
-          maxLength: MUNI_ISSUE_NAME_MAX_LENGTH,
-        },
-        issuerRole: {
-          bsonType: "string",
-          maxLength: MUNI_ISSUE_NAME_MAX_LENGTH,
-        },
-        issueDescription: {
-          bsonType: "string",
-          maxLength: MUNI_ISSUE_TEXT_MAX_LENGTH,
-        },
-        desiredBehavior: {
-          bsonType: "string",
-          maxLength: MUNI_ISSUE_TEXT_MAX_LENGTH,
-        },
-      },
-    },
-    jira: {
-      bsonType: "object",
-      required: ["key", "syncStatus"],
-      properties: {
-        key: { bsonType: "string" },
-        syncStatus: { enum: [...MUNI_ISSUE_SYNC_STATUSES] },
-      },
-    },
-    createdAt: { bsonType: "date" },
-  },
-};
-
-export const muniIssuesIndexes: IndexDescription[] = [
-  { key: { callSid: 1 }, name: "callSid_1" },
-  { key: { createdAt: -1 }, name: "createdAt_-1" },
-  // Unique: one stored document per Jira ticket, guarding against duplicate writes.
-  { key: { "jira.key": 1 }, name: "jira_key_unique", unique: true },
-];
+import type { Document, IndexDescription } from "mongodb";
+import {
+  MUNI_ISSUE_STATUSES,
+  MUNI_ISSUE_SYNC_STATUSES,
+  MUNI_ISSUE_TEXT_MAX_LENGTH,
+  MUNI_ISSUE_NAME_MAX_LENGTH,
+} from "./muniIssues.constants";
+
+export const muniIssuesJsonSchema: Document = {
+  bsonType: "object",
+  required: [
+    "callSid",
+    "clientId",
+    "cityName",
+    "issueContent",
+    "jira",
+    "createdAt",
+  ],
+  properties: {
+    callSid: { bsonType: "string" },
+    clientId: { bsonType: "string" },
+    cityName: { bsonType: "string" },
+    issueContent: {
+      bsonType: "object",
+      required: [
+        "issuerName",
+        "issuerRole",
+        "issueDescription",
+        "desiredBehavior",
+      ],
+      properties: {
+        issuerName: {
+          bsonType: "string",
+          maxLength: MUNI_ISSUE_NAME_MAX_LENGTH,
+        },
+        issuerRole: {
+          bsonType: "string",
+          maxLength: MUNI_ISSUE_NAME_MAX_LENGTH,
+        },
+        issueDescription: {
+          bsonType: "string",
+          maxLength: MUNI_ISSUE_TEXT_MAX_LENGTH,
+        },
+        desiredBehavior: {
+          bsonType: "string",
+          maxLength: MUNI_ISSUE_TEXT_MAX_LENGTH,
+        },
+      },
+    },
+    jira: {
+      bsonType: "object",
+      required: ["key", "syncStatus"],
+      properties: {
+        key: { bsonType: "string" },
+        syncStatus: { enum: [...MUNI_ISSUE_SYNC_STATUSES] },
+      },
+    },
+    createdAt: { bsonType: "date" },
+    status: { enum: [...MUNI_ISSUE_STATUSES] },
+    response: {
+      bsonType: "object",
+      required: ["text", "createdAt"],
+      properties: {
+        text: { bsonType: "string", maxLength: MUNI_ISSUE_TEXT_MAX_LENGTH },
+        imageUrl: { bsonType: "string" },
+        createdAt: { bsonType: "date" },
+      },
+    },
+    updatedAt: { bsonType: "date" },
+  },
+};
+
+export const muniIssuesIndexes: IndexDescription[] = [
+  { key: { callSid: 1 }, name: "callSid_1" },
+  { key: { createdAt: -1 }, name: "createdAt_-1" },
+  // Complaint list: one municipality's issues, newest first.
+  { key: { clientId: 1, createdAt: -1 }, name: "clientId_1_createdAt_-1" },
+  // Unique: one stored document per Jira ticket, guarding against duplicate writes.
+  { key: { "jira.key": 1 }, name: "jira_key_unique", unique: true },
+];

package/src/municipal/muniIssues/muniIssues.setters.ts

@@ -1,24 +1,80 @@
-import { ObjectId } from "mongodb";
-import { CreateMuniIssueInput, MuniIssue } from "./muniIssues.types";
-import { getMuniIssuesCollection } from "./muniIssues.getters";
-import { ensureMuniIssuesCollectionOnce } from "./muniIssues.setup";
-
-// Required `id`: MIS pre-generates it (generateMuniIssueId) and embeds it in the Jira ticket — the two-way link.
-export const createMuniIssue = async (
-  issueData: CreateMuniIssueInput,
-  id: ObjectId,
-): Promise<ObjectId> => {
-  await ensureMuniIssuesCollectionOnce();
-
-  const issue: MuniIssue = {
-    _id: id,
-    ...issueData,
-    jira: {
-      ...issueData.jira,
-      syncStatus: issueData.jira.syncStatus ?? "created",
-    },
-    createdAt: new Date(),
-  };
-  const { insertedId } = await getMuniIssuesCollection().insertOne(issue);
-  return insertedId;
-};
+import { Filter, ObjectId } from "mongodb";
+import {
+  CreateMuniIssueInput,
+  MuniIssue,
+  MuniIssueStatus,
+  SetMuniIssueResponseInput,
+} from "./muniIssues.types";
+import { getMuniIssuesCollection } from "./muniIssues.getters";
+import { ensureMuniIssuesCollectionOnce } from "./muniIssues.setup";
+
+// Required `id`: MIS pre-generates it (generateMuniIssueId) and embeds it in the Jira ticket — the two-way link.
+export const createMuniIssue = async (
+  issueData: CreateMuniIssueInput,
+  id: ObjectId,
+): Promise<ObjectId> => {
+  await ensureMuniIssuesCollectionOnce();
+
+  const now = new Date();
+  const issue: MuniIssue = {
+    _id: id,
+    ...issueData,
+    jira: {
+      ...issueData.jira,
+      syncStatus: issueData.jira.syncStatus ?? "created",
+    },
+    status: "in_review",
+    createdAt: now,
+    updatedAt: now,
+  };
+  const { insertedId } = await getMuniIssuesCollection().insertOne(issue);
+  return insertedId;
+};
+
+// An issue of this client that is tracked (has a status) and not yet answered.
+// The `response` condition is the lock: once answered, no further writes match.
+const openIssueFilter = (id: string, clientId: string): Filter<MuniIssue> => ({
+  _id: new ObjectId(id),
+  clientId,
+  status: { $exists: true },
+  response: { $exists: false },
+});
+
+/** Changes the status of an unanswered issue. Returns false if none matched. */
+export const updateMuniIssueStatus = async (
+  id: string,
+  clientId: string,
+  status: MuniIssueStatus,
+): Promise<boolean> => {
+  if (!ObjectId.isValid(id)) return false;
+  await ensureMuniIssuesCollectionOnce();
+
+  const { matchedCount } = await getMuniIssuesCollection().updateOne(
+    openIssueFilter(id, clientId),
+    { $set: { status, updatedAt: new Date() } },
+  );
+  return matchedCount > 0;
+};
+
+/** Saves the single TalkPilot response, which locks the issue. Returns false if none matched. */
+export const setMuniIssueResponse = async (
+  id: string,
+  clientId: string,
+  { status, text, imageUrl }: SetMuniIssueResponseInput,
+): Promise<boolean> => {
+  if (!ObjectId.isValid(id)) return false;
+  await ensureMuniIssuesCollectionOnce();
+
+  const now = new Date();
+  const { matchedCount } = await getMuniIssuesCollection().updateOne(
+    openIssueFilter(id, clientId),
+    {
+      $set: {
+        status,
+        response: { text, ...(imageUrl && { imageUrl }), createdAt: now },
+        updatedAt: now,
+      },
+    },
+  );
+  return matchedCount > 0;
+};