@talkpilot/core-db 1.1.14 → 1.1.16

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

@@ -1,19 +1,20 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} */
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
-  testPathIgnorePatterns: ['<rootDir>/src/__tests__/legacy/'],
-  testMatch: ['**/__tests__/**/*.spec.ts', '**/*.spec.ts'],
-  transform: {
-    '^.+\\.tsx?$': ['ts-jest', {
-      tsconfig: 'tsconfig.json',
-    }],
-  },
-  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
-  verbose: true,
-  forceExit: true,
-  clearMocks: true,
-  resetMocks: true,
-  restoreMocks: true,
-};
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testPathIgnorePatterns: ['<rootDir>/src/__tests__/legacy/'],
+  testMatch: ['**/__tests__/**/*.spec.ts', '**/*.spec.ts'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: 'tsconfig.json',
+    }],
+  },
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  maxWorkers: 1,
+  verbose: true,
+  forceExit: true,
+  clearMocks: true,
+  resetMocks: true,
+  restoreMocks: true,
+};

package/package.json

@@ -1,45 +1,46 @@
-{
-  "name": "@talkpilot/core-db",
-  "version": "1.1.14",
-  "description": "Core database package for centralized connections and ORM integration.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "jest",
-    "lint": "eslint 'src/**/*.{ts,tsx}'",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "prepare": "npm run build"
-  },
-  "keywords": [
-    "database",
-    "orm",
-    "typescript",
-    "postgres",
-    "db-client"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "express": "^4.18.0",
-    "google-libphonenumber": "^3.2.0",
-    "mongodb": "^6.11.0"
-  },
-  "devDependencies": {
-    "@faker-js/faker": "^8.0.0",
-    "@types/express": "^4.17.0",
-    "@types/google-libphonenumber": "^7.4.0",
-    "@types/jest": "^29.0.0",
-    "@types/node": "^20.0.0",
-    "fishery": "^2.4.0",
-    "jest": "^29.0.0",
-    "mongodb-memory-server": "^10.0.0",
-    "prettier": "^3.8.2",
-    "ts-jest": "^29.0.0",
-    "typescript": "^5.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@talkpilot/core-db",
+  "version": "1.1.16",
+  "description": "Core database package for centralized connections and ORM integration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "database",
+    "orm",
+    "typescript",
+    "postgres",
+    "db-client"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "dayjs": "^1.11.21",
+    "express": "^4.18.0",
+    "google-libphonenumber": "^3.2.0",
+    "mongodb": "^6.11.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.0.0",
+    "@types/express": "^4.17.0",
+    "@types/google-libphonenumber": "^7.4.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "fishery": "^2.4.0",
+    "jest": "^29.0.0",
+    "mongodb-memory-server": "^10.0.0",
+    "prettier": "^3.8.2",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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,94 @@
+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 },
+];