@talkpilot/core-db 1.3.4 → 1.3.6

package/dist/websitalk/scans/scans.getters.d.ts

@@ -0,0 +1,12 @@
+import { Collection, Filter, ObjectId } from "mongodb";
+import { QueryOptions } from "../../talkpilot/utils/query.utils";
+import type { ActiveScanStatus, Scan, ScanDoc } from "./scans.types";
+export declare const getScansCollection: () => Collection<Scan>;
+export declare const getScansByClientAndDateRange: (clientId: string, startDate: Date, endDate: Date) => Promise<ScanDoc[]>;
+export declare const getScanFieldsByClientAndDateRange: <K extends keyof Scan>(clientId: string, startDate: Date, endDate: Date, fields: K[]) => Promise<Pick<ScanDoc, "_id" | K>[]>;
+export declare const createScanDoc: (scan: Pick<Scan, "clientId" | "baseUrl" | "notifyPhoneNumber">) => Promise<import("mongodb").InsertOneResult<Scan>>;
+export declare const getActiveScanStatus: (clientId: string) => Promise<ActiveScanStatus>;
+export declare const updateScanDoc: (scanId: ObjectId, updates: Partial<Omit<Scan, "clientId" | "createdAt">>) => Promise<ScanDoc | null>;
+export declare const findScansByQuery: (query: Filter<Scan>, options?: QueryOptions) => Promise<ScanDoc[]>;
+export declare const countScans: (query: Filter<Scan>) => Promise<number>;
+//# sourceMappingURL=scans.getters.d.ts.map

package/dist/websitalk/scans/scans.getters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scans.getters.d.ts","sourceRoot":"","sources":["../../../src/websitalk/scans/scans.getters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEvD,OAAO,EAEL,YAAY,EACb,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EACV,gBAAgB,EAChB,IAAI,EACJ,OAAO,EAER,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,kBAAkB,QAAO,UAAU,CAAC,IAAI,CAEpD,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,UAAU,MAAM,EAChB,WAAW,IAAI,EACf,SAAS,IAAI,KACZ,OAAO,CAAC,OAAO,EAAE,CAUnB,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAAI,CAAC,SAAS,MAAM,IAAI,EACpE,UAAU,MAAM,EAChB,WAAW,IAAI,EACf,SAAS,IAAI,EACb,QAAQ,CAAC,EAAE,KACV,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,EAAE,CAkBpC,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,MAAM,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,mBAAmB,CAAC,qDAa/D,CAAC;AAIF,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,KACf,OAAO,CAAC,gBAAgB,CAW1B,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,QAAQ,QAAQ,EAChB,SAAS,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC,CAAC,KACrD,OAAO,CAAC,OAAO,GAAG,IAAI,CAMxB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,EACnB,UAAU,YAAY,KACrB,OAAO,CAAC,OAAO,EAAE,CAGnB,CAAC;AAEF,eAAO,MAAM,UAAU,GAAU,OAAO,MAAM,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,MAAM,CAEpE,CAAC"}

package/dist/websitalk/scans/scans.getters.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countScans = exports.findScansByQuery = exports.updateScanDoc = exports.getActiveScanStatus = exports.createScanDoc = exports.getScanFieldsByClientAndDateRange = exports.getScansByClientAndDateRange = exports.getScansCollection = void 0;
+const index_1 = require("../index");
+const query_utils_1 = require("../../talkpilot/utils/query.utils");
+const getScansCollection = () => {
+    return (0, index_1.getDb)().collection("scans");
+};
+exports.getScansCollection = getScansCollection;
+const getScansByClientAndDateRange = (clientId, startDate, endDate) => {
+    return (0, exports.getScansCollection)()
+        .find({
+        clientId,
+        createdAt: {
+            $gte: startDate,
+            $lte: endDate,
+        },
+    })
+        .toArray();
+};
+exports.getScansByClientAndDateRange = getScansByClientAndDateRange;
+const getScanFieldsByClientAndDateRange = (clientId, startDate, endDate, fields) => {
+    const projection = fields.reduce((acc, field) => {
+        acc[field] = 1;
+        return acc;
+    }, {});
+    return (0, exports.getScansCollection)()
+        .find({
+        clientId,
+        createdAt: {
+            $gte: startDate,
+            $lte: endDate,
+        },
+    }, { projection })
+        .toArray();
+};
+exports.getScanFieldsByClientAndDateRange = getScanFieldsByClientAndDateRange;
+const createScanDoc = (scan) => {
+    return (0, exports.getScansCollection)().insertOne({
+        ...scan,
+        status: "CHECKING",
+        activeTasksCount: 0,
+        pagesScanned: 0,
+        pagesSkipped: 0,
+        skipped: [],
+        siteChrome: {},
+        createdAt: new Date(),
+        updatedAt: new Date(),
+    });
+};
+exports.createScanDoc = createScanDoc;
+const FINISHED_SCAN_STATUSES = ["COMPLETED", "FAILED"];
+const getActiveScanStatus = async (clientId) => {
+    const latestScan = await (0, exports.getScansCollection)().findOne({ clientId }, { sort: { createdAt: -1 } });
+    if (!latestScan || FINISHED_SCAN_STATUSES.includes(latestScan.status)) {
+        return { isActive: false };
+    }
+    return { isActive: true, status: latestScan.status };
+};
+exports.getActiveScanStatus = getActiveScanStatus;
+const updateScanDoc = async (scanId, updates) => {
+    return await (0, exports.getScansCollection)().findOneAndUpdate({ _id: scanId }, { $set: { ...updates, updatedAt: new Date() } }, { returnDocument: "after" });
+};
+exports.updateScanDoc = updateScanDoc;
+const findScansByQuery = async (query, options) => {
+    const cursor = (0, exports.getScansCollection)().find(query);
+    return await (0, query_utils_1.applyQueryOptions)(cursor, options).toArray();
+};
+exports.findScansByQuery = findScansByQuery;
+const countScans = async (query) => {
+    return (0, exports.getScansCollection)().countDocuments(query);
+};
+exports.countScans = countScans;
+//# sourceMappingURL=scans.getters.js.map

package/dist/websitalk/scans/scans.getters.js.map

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

package/dist/websitalk/scans/scans.types.d.ts

@@ -0,0 +1,45 @@
+import { WithId } from "mongodb";
+export type ScanStatus = "CHECKING" | "PREPARING" | "SCANNING" | "PROCESSING" | "COMPLETED" | "FAILED";
+export type ActiveScanStatus = {
+    isActive: true;
+    status: ScanStatus;
+} | {
+    isActive: false;
+};
+export type SiteChromeEntry = {
+    url: string;
+    urlCanonical?: string | null;
+    title?: string | null;
+    h1?: string | null;
+    language?: string | null;
+    sourceType?: string | null;
+    status?: string | null;
+    context?: string | null;
+    contentHash?: string | null;
+    errorMessage?: string | null;
+    breadcrumbs?: unknown;
+    description?: string | null;
+    sourceUrl?: string | null;
+    fetchedAt?: Date | null;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+export type SkippedEntry = {
+    path: string;
+    reason: string;
+};
+export type Scan = {
+    clientId: string;
+    baseUrl: string;
+    notifyPhoneNumber?: string | null;
+    status: ScanStatus;
+    activeTasksCount: number;
+    pagesScanned: number;
+    pagesSkipped: number;
+    skipped: SkippedEntry[];
+    siteChrome: SiteChromeEntry;
+    createdAt: Date;
+    updatedAt: Date;
+};
+export type ScanDoc = WithId<Scan>;
+//# sourceMappingURL=scans.types.d.ts.map

package/dist/websitalk/scans/scans.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scans.types.d.ts","sourceRoot":"","sources":["../../../src/websitalk/scans/scans.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,WAAW,GACX,UAAU,GACV,YAAY,GACZ,WAAW,GACX,QAAQ,CAAC;AAEb,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACtC;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAC;AAExB,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC"}

package/dist/websitalk/scans/scans.types.js

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

package/dist/websitalk/scans/scans.types.js.map

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

package/jest.config.js

@@ -11,6 +11,7 @@ module.exports = {
     }],
   },
   setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  maxWorkers: 1,
   verbose: true,
   forceExit: true,
   clearMocks: true,

package/package.json

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

package/src/connection.ts

@@ -1,5 +1,6 @@
 import { mongodbClient } from "./talkpilot";
 import { municipalDataMongodbClient } from "./municipal";
+import { websitalkMongodbClient } from "./websitalk";
 
 let isConnected = false;
 
@@ -15,6 +16,7 @@ export async function ensureDbConnected() {
   const mongoUri = process.env.MONGO_URI || process.env.MONGODB_URI;
   const talkpilotUri = mongoUri;
   const municipalUri = mongoUri;
+  const websiteTalkUri = mongoUri;
 
   if (!talkpilotUri) {
     console.warn("[core-db] MONGO_URI is not set");
@@ -38,5 +40,15 @@ export async function ensureDbConnected() {
     );
   }
 
+  if (!websiteTalkUri) {
+    console.warn("[core-db] MONGO_URI is not set");
+  } else {
+    const dbName = process.env.WEBSITALK_DB_NAME;
+    await websitalkMongodbClient.connect(websiteTalkUri, dbName);
+    console.info(
+      `[core-db] Connected to Website Talk MongoDB: ${dbName || "website-talk (default)"}`,
+    );
+  }
+
   isConnected = true;
 }

package/src/index.ts

@@ -13,4 +13,14 @@ export * from "./municipal/streets";
 export * from "./municipal/departmentsSubjects";
 export * from "./municipal/tickets";
 export * from "./municipal/systemInstructions";
+export * from "./municipal/muniIssues";
 export * from "./municipal/utils/types";
+
+export {
+  websitalkMongodbClient,
+  getDb as getWebsitalkDb,
+  setDb as setWebsitalkDb,
+  ObjectId as WebsitalkObjectId,
+} from "./websitalk";
+export * from "./websitalk/scans/scans.getters";
+export type * from "./websitalk/scans/scans.types";

package/src/municipal/index.ts

@@ -5,6 +5,7 @@ export * from "./streets";
 export * from "./departmentsSubjects";
 export * from "./tickets";
 export * from "./systemInstructions";
+export * from "./muniIssues";
 export * from "./utils/types";
 export { CityName } from "./utils/types";
 export { municipalDataMongodbClient } from "./mongodb-client";

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

@@ -0,0 +1,92 @@
+import { createMuniIssue } from "../muniIssues.setters";
+import {
+  generateMuniIssueId,
+  getMuniIssueById,
+  getMuniIssueByJiraKey,
+} from "../muniIssues.getters";
+import { createMuniIssueInput } from "../../../test-utils/factories";
+
+describe("muniIssues setters", () => {
+  describe("createMuniIssue", () => {
+    it("should insert a well-formed document with createdAt and nested content/jira", async () => {
+      const input = createMuniIssueInput();
+      const id = generateMuniIssueId();
+
+      const insertedId = await createMuniIssue(input, id);
+
+      const saved = await getMuniIssueById(insertedId.toString());
+      expect(saved).toMatchObject({
+        callSid: input.callSid,
+        clientId: input.clientId,
+        cityName: input.cityName,
+        issueContent: input.issueContent,
+        jira: input.jira,
+      });
+      expect(saved?.createdAt).toBeInstanceOf(Date);
+    });
+
+    it("should default jira.syncStatus to created when not provided", async () => {
+      const id = generateMuniIssueId();
+
+      const insertedId = await createMuniIssue(
+        createMuniIssueInput({ jira: { key: "CP-9" } }),
+        id,
+      );
+
+      const saved = await getMuniIssueById(insertedId.toString());
+      expect(saved?.jira.syncStatus).toBe("created");
+    });
+
+    it("should store long issueDescription and desiredBehavior in full", async () => {
+      const issueDescription = "a".repeat(2000);
+      const desiredBehavior = "b".repeat(2000);
+      const id = generateMuniIssueId();
+
+      const insertedId = await createMuniIssue(
+        createMuniIssueInput({
+          issueContent: {
+            issuerName: "Dana",
+            issuerRole: "Agent",
+            issueDescription,
+            desiredBehavior,
+          },
+        }),
+        id,
+      );
+
+      const saved = await getMuniIssueById(insertedId.toString());
+      expect(saved?.issueContent.issueDescription).toHaveLength(2000);
+      expect(saved?.issueContent.desiredBehavior).toBe(desiredBehavior);
+    });
+
+    it("should persist the caller-supplied _id so the Jira ticket can link back", async () => {
+      const id = generateMuniIssueId();
+
+      const insertedId = await createMuniIssue(createMuniIssueInput(), id);
+
+      expect(insertedId.toString()).toBe(id.toString());
+      expect(await getMuniIssueById(id.toString())).not.toBeNull();
+    });
+  });
+
+  describe("getMuniIssueById", () => {
+    it("should return null for an unknown or malformed id instead of throwing", async () => {
+      expect(await getMuniIssueById(generateMuniIssueId().toString())).toBeNull();
+      expect(await getMuniIssueById("not-a-valid-id")).toBeNull();
+    });
+  });
+
+  describe("getMuniIssueByJiraKey", () => {
+    it("should find the issue with the given Jira key", async () => {
+      await createMuniIssue(
+        createMuniIssueInput({ jira: { key: "CP-555" } }),
+        generateMuniIssueId(),
+      );
+
+      const found = await getMuniIssueByJiraKey("CP-555");
+
+      expect(found?.jira.key).toBe("CP-555");
+      expect(await getMuniIssueByJiraKey("CP-nope")).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,92 @@
+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);
+    });
+  });
+});

package/src/municipal/muniIssues/index.ts

@@ -0,0 +1,17 @@
+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";

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

@@ -0,0 +1,18 @@
+/** 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;

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

@@ -0,0 +1,24 @@
+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 });
+};

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

@@ -0,0 +1,66 @@
+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 },
+];

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

@@ -0,0 +1,24 @@
+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;
+};

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

@@ -0,0 +1,65 @@
+import { Db, Document, MongoServerError } from "mongodb";
+import { getDb } from "../index";
+import {
+  MUNI_ISSUES_COLLECTION,
+  NAMESPACE_EXISTS,
+  VALIDATION_LEVEL,
+  VALIDATION_ACTION,
+} from "./muniIssues.constants";
+import { muniIssuesIndexes, muniIssuesJsonSchema } from "./muniIssues.schema";
+
+const applyValidator = (db: Db, validator: Document): Promise<unknown> =>
+  db.command({
+    collMod: MUNI_ISSUES_COLLECTION,
+    validator,
+    validationLevel: VALIDATION_LEVEL,
+    validationAction: VALIDATION_ACTION,
+  });
+
+// Provisions validator and indexes: createCollection first, collMod if already exists.
+export const ensureMuniIssuesCollection = async (): Promise<void> => {
+  const db = getDb();
+  const validator = { $jsonSchema: muniIssuesJsonSchema };
+
+  const existing = await db
+    .listCollections({ name: MUNI_ISSUES_COLLECTION })
+    .toArray();
+
+  if (existing.length === 0) {
+    try {
+      await db.createCollection(MUNI_ISSUES_COLLECTION, {
+        validator,
+        validationLevel: VALIDATION_LEVEL,
+        validationAction: VALIDATION_ACTION,
+      });
+    } catch (err) {
+      // NamespaceExists race: collection exists — apply validator via collMod.
+      if (err instanceof MongoServerError && err.code === NAMESPACE_EXISTS) {
+        await applyValidator(db, validator);
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    await applyValidator(db, validator);
+  }
+
+  await db.collection(MUNI_ISSUES_COLLECTION).createIndexes(muniIssuesIndexes);
+};
+
+// Per-Db cache so each test's in-memory Db re-provisions.
+const provisioningByDb = new WeakMap<Db, Promise<void>>();
+
+// Once per Db; evicts failed run so the next call retries.
+export const ensureMuniIssuesCollectionOnce = (): Promise<void> => {
+  const db = getDb();
+  let provisioning = provisioningByDb.get(db);
+  if (!provisioning) {
+    provisioning = ensureMuniIssuesCollection().catch((err) => {
+      provisioningByDb.delete(db);
+      throw err;
+    });
+    provisioningByDb.set(db, provisioning);
+  }
+  return provisioning;
+};