@talkpilot/core-db 1.3.46 → 1.3.48

package/.cursor/rules/development.mdc

@@ -1,65 +1,65 @@
----
-description: Development standards and conventions for the core-db package
-globs: src/**/*.ts
-alwaysApply: true
----
-
-# Development Standards
-
-This package provides a centralized database layer for multiple domains (TalkPilot and Municipal). Follow these rules to maintain consistency and reliability.
-
-## Project Structure
-
-- **`src/talkpilot/`**: All database logic, types, and getters related to the TalkPilot domain.
-- **`src/municipal/`**: All database logic, types, and getters related to the Municipal Data domain.
-- **`src/test-utils/`**: Shared testing infrastructure, including factories and database utilities.
-
-## Database Connection Pattern
-
-Each domain is isolated. They have their own `db` instance and must be connected independently.
-
-```typescript
-import { mongodbClient, municipalDataMongodbClient } from '@talkpilot/core-db';
-
-// TalkPilot
-await mongodbClient.connect(uri);
-
-// Municipal
-await municipalDataMongodbClient.connect(uri);
-```
-
-## Creating New Getters
-
-1. **Location**: Place getters in the relevant domain folder (e.g., `src/talkpilot/agents/agents.getters.ts`).
-2. **Naming**: Use `find...` for multiple results and `get...ById` for single results.
-3. **Domain isolation**: Always use the `getDb()` function from the current domain's `index.ts`.
-
-## Environment Validation
-
-Always validate configuration "on-demand" within the `connect` methods using the validation utilities.
-
-```typescript
-import { validateConfig, validateMongoUri } from '../utils/validation';
-
-async connect(uri?: string) {
-  const mongodbUri = uri || process.env.MONGO_URI;
-  validateConfig('MONGO_URI', mongodbUri);
-  validateMongoUri(mongodbUri!);
-  // ... connection logic
-}
-```
-
-## Testing Standards
-
-1. **In-Memory DB**: Use `mongodb-memory-server` for all tests. It is automatically initialized in `src/__tests__/setup.ts`.
-2. **Factories**: Use the Fishery factories in `src/test-utils/factories/` to generate test data.
-3. **Organization**: Place tests in a `__tests__` folder within the relevant domain.
-
-```typescript
-import { createAgent } from '../../../test-utils/factories';
-
-it('should find agents', async () => {
-  const agent = createAgent({ name: 'Test' });
-  // ... test logic
-});
-```
+---
+description: Development standards and conventions for the core-db package
+globs: src/**/*.ts
+alwaysApply: true
+---
+
+# Development Standards
+
+This package provides a centralized database layer for multiple domains (TalkPilot and Municipal). Follow these rules to maintain consistency and reliability.
+
+## Project Structure
+
+- **`src/talkpilot/`**: All database logic, types, and getters related to the TalkPilot domain.
+- **`src/municipal/`**: All database logic, types, and getters related to the Municipal Data domain.
+- **`src/test-utils/`**: Shared testing infrastructure, including factories and database utilities.
+
+## Database Connection Pattern
+
+Each domain is isolated. They have their own `db` instance and must be connected independently.
+
+```typescript
+import { mongodbClient, municipalDataMongodbClient } from '@talkpilot/core-db';
+
+// TalkPilot
+await mongodbClient.connect(uri);
+
+// Municipal
+await municipalDataMongodbClient.connect(uri);
+```
+
+## Creating New Getters
+
+1. **Location**: Place getters in the relevant domain folder (e.g., `src/talkpilot/agents/agents.getters.ts`).
+2. **Naming**: Use `find...` for multiple results and `get...ById` for single results.
+3. **Domain isolation**: Always use the `getDb()` function from the current domain's `index.ts`.
+
+## Environment Validation
+
+Always validate configuration "on-demand" within the `connect` methods using the validation utilities.
+
+```typescript
+import { validateConfig, validateMongoUri } from '../utils/validation';
+
+async connect(uri?: string) {
+  const mongodbUri = uri || process.env.MONGO_URI;
+  validateConfig('MONGO_URI', mongodbUri);
+  validateMongoUri(mongodbUri!);
+  // ... connection logic
+}
+```
+
+## Testing Standards
+
+1. **In-Memory DB**: Use `mongodb-memory-server` for all tests. It is automatically initialized in `src/__tests__/setup.ts`.
+2. **Factories**: Use the Fishery factories in `src/test-utils/factories/` to generate test data.
+3. **Organization**: Place tests in a `__tests__` folder within the relevant domain.
+
+```typescript
+import { createAgent } from '../../../test-utils/factories';
+
+it('should find agents', async () => {
+  const agent = createAgent({ name: 'Test' });
+  // ... test logic
+});
+```

package/AGENTS.md

@@ -1,49 +1,49 @@
-# AI Agent Guide for core-db
-
-Ground truth for AI coding agents in this repository. This is `@talkpilot/core-db` — the only package that should talk to Mongo. `.cursor/rules/development.mdc` exists but may lag (TalkPilot + Municipal only); do not expand those rules in an unrelated ticket.
-
-## What this is
-Shared Mongo layer: typed getters, schemas, factories, indexes. Consumed by TalkPilot, municipal, WebsiteTalk, and clinic services. Publishing a version here is how other repos pick up schema/getter changes.
-
-## Coding philosophy
-- Strict TypeScript. No `any`; use `unknown` and narrow.
-- No narrating comments.
-- Split types, getters, and schemas into separate files.
-
-## Project structure
-- `src/talkpilot/` — calls, flows, sessions, clients, phone numbers, subscriptions, …
-- `src/municipal/` — cities, streets, tickets, departmentsSubjects, …
-- `src/websitalk/` — scans, scanResources, websiteUrls.
-- `src/configuration/` — prompts, models.
-- `src/test-utils/` — Fishery factories and test DB helpers.
-- `src/utils/` — validation, pagination, shared types.
-- `dist/` is what consumers import — generated, tests excluded from the build.
-
-## Copy this
-New getter: `src/<domain>/<entity>/<entity>.types.ts` + `<entity>.getter.ts` (or `*.getters.ts`) + optional `<entity>.schema.ts` + barrel `index.ts` + `__tests__/<entity>.spec.ts`.
-Export it from `src/index.ts`.
-Examples: `src/talkpilot/calls/calls.getters.ts`, `src/talkpilot/phone_numbers/phone_numbers.getter.ts`.
-
-Naming: `find*` for many, `get*ById` (or equivalent single-doc) for one. Always use that domain’s `getDb()` / collection helper — never another domain’s client. Exception already on disk: `src/talkpilot/calls/calls.statistics.getters.ts` imports municipal `tickets.statistics.getters` — do not “clean that up.”
-
-## Where data lives
-This repo **owns** `mongodb`. Four isolated clients — connect each independently:
-
-- `mongodbClient` — TalkPilot
-- `municipalDataMongodbClient` — municipal
-- `websitalkMongodbClient` — WebsiteTalk
-- `configurationMongodbClient` — configuration
-
-Do not cross-import getters across domains, except the talkpilot call-stats → municipal tickets exception above.
-
-## Do / don't
-- Do not put HTTP, Express, or business orchestration here.
-- Validate `MONGO_URI` (and siblings) on demand in `connect()`, using `src/utils/validation`.
-- After a getter/schema change: bump package version, build, publish; then bump the consumer. Downstream pins skew — do not assume they are on latest.
-- `prepare` runs `build` on install.
-
-## Siblings
-Every Node service should call getters from here. If a service is about to `getDb().collection` or `import from 'mongodb'`, the getter belongs in this PR first.
-
-## Tests
-Jest + `mongodb-memory-server` (`src/__tests__/setup.ts`). Factories in `src/test-utils/factories/`. Colocate `__tests__/` under the domain.
+# AI Agent Guide for core-db
+
+Ground truth for AI coding agents in this repository. This is `@talkpilot/core-db` — the only package that should talk to Mongo. `.cursor/rules/development.mdc` exists but may lag (TalkPilot + Municipal only); do not expand those rules in an unrelated ticket.
+
+## What this is
+Shared Mongo layer: typed getters, schemas, factories, indexes. Consumed by TalkPilot, municipal, WebsiteTalk, and clinic services. Publishing a version here is how other repos pick up schema/getter changes.
+
+## Coding philosophy
+- Strict TypeScript. No `any`; use `unknown` and narrow.
+- No narrating comments.
+- Split types, getters, and schemas into separate files.
+
+## Project structure
+- `src/talkpilot/` — calls, flows, sessions, clients, phone numbers, subscriptions, …
+- `src/municipal/` — cities, streets, tickets, departmentsSubjects, …
+- `src/websitalk/` — scans, scanResources, websiteUrls.
+- `src/configuration/` — prompts, models.
+- `src/test-utils/` — Fishery factories and test DB helpers.
+- `src/utils/` — validation, pagination, shared types.
+- `dist/` is what consumers import — generated, tests excluded from the build.
+
+## Copy this
+New getter: `src/<domain>/<entity>/<entity>.types.ts` + `<entity>.getter.ts` (or `*.getters.ts`) + optional `<entity>.schema.ts` + barrel `index.ts` + `__tests__/<entity>.spec.ts`.
+Export it from `src/index.ts`.
+Examples: `src/talkpilot/calls/calls.getters.ts`, `src/talkpilot/phone_numbers/phone_numbers.getter.ts`.
+
+Naming: `find*` for many, `get*ById` (or equivalent single-doc) for one. Always use that domain’s `getDb()` / collection helper — never another domain’s client. Exception already on disk: `src/talkpilot/calls/calls.statistics.getters.ts` imports municipal `tickets.statistics.getters` — do not “clean that up.”
+
+## Where data lives
+This repo **owns** `mongodb`. Four isolated clients — connect each independently:
+
+- `mongodbClient` — TalkPilot
+- `municipalDataMongodbClient` — municipal
+- `websitalkMongodbClient` — WebsiteTalk
+- `configurationMongodbClient` — configuration
+
+Do not cross-import getters across domains, except the talkpilot call-stats → municipal tickets exception above.
+
+## Do / don't
+- Do not put HTTP, Express, or business orchestration here.
+- Validate `MONGO_URI` (and siblings) on demand in `connect()`, using `src/utils/validation`.
+- After a getter/schema change: bump package version, build, publish; then bump the consumer. Downstream pins skew — do not assume they are on latest.
+- `prepare` runs `build` on install.
+
+## Siblings
+Every Node service should call getters from here. If a service is about to `getDb().collection` or `import from 'mongodb'`, the getter belongs in this PR first.
+
+## Tests
+Jest + `mongodb-memory-server` (`src/__tests__/setup.ts`). Factories in `src/test-utils/factories/`. Colocate `__tests__/` under the domain.

package/DEVELOPMENT.md

@@ -1,141 +1,141 @@
-# Development Guide
-
-Welcome to the `core-db` development guide. This document explains how to set up, develop, and test this package.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js (v18 or later)
-- TypeScript
-
-### Setup
-
-1. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-2. Build the project:
-   ```bash
-   npm run build
-   ```
-
-## Local Development
-
-Use `npm pack` to test local changes in a consuming project.
-
-1. In the `core-db` folder, build and pack:
-   ```bash
-   npm run build && npm pack
-   ```
-   This produces a file like `talkpilot-core-db-x.y.z.tgz` in the project root.
-
-2. In the consuming project, install it:
-   ```bash
-   npm install /path/to/core-db/talkpilot-core-db-x.y.z.tgz
-   ```
-
-3. After making further changes to `core-db`, repeat step 1 and reinstall in the consuming project.
-
-## Adding a New Getter
-
-1. **Define Types**: Add your data types in the relevant domain's `types.ts` file.
-2. **Implement Getter**: Add the function in the `getters.ts` file.
-3. **Export**: Ensure the getter is exported from the domain's `index.ts` and finally from the main `src/index.ts`.
-4. **Test**: Create a test in the domain's `__tests__` folder.
-
-## Signature Immutability
-
-`core-db` is a shared package consumed by multiple services that may not all update at the same time. A signature change that looks harmless locally can silently break a service that hasn't picked up the new version yet.
-
-**Rules:**
-
-- **Never change an existing parameter's type or name.**
-- **Never add a required parameter** to an existing function.
-- **Never remove a function.** Mark it `@deprecated` instead (see below).
-- **Safe additions only**: you may add optional parameters or parameters with defaults — existing callers will continue to compile without changes.
-
-**Deprecating instead of deleting:**
-
-When a function is no longer the right approach, mark it deprecated and explain why. Consumers can then migrate on their own schedule.
-
-```ts
-/**
- * @deprecated Use `newFunction` instead — reason for the change.
- */
-export const oldFunction = (...) => { ... };
-```
-
-The deprecation comment must include either the name of the replacement or a clear explanation of why the function was retired, so a consumer reading the warning knows exactly what to do.
-
-## Testing
-
-We use Jest with `mongodb-memory-server` for fast, isolated database tests.
-
-### Running Tests
-
-```bash
-npm test
-```
-
-### Using Factories
-
-Always use factories to generate test data to keep tests clean and maintainable.
-
-```typescript
-import { createCallDoc } from '../calls.getters';
-import { createOutGoingCallDoc } from '../../../test-utils/factories';
-
-it('should save a call', async () => {
-  const call = createOutGoingCallDoc({ callSid: 'CA123' });
-  await createCallDoc(call);
-  // ... assertions
-});
-```
-
-## Build Process
-
-The project is built using TypeScript (`tsc`). The output is generated in the `dist/` directory.
-
-- `main`: `dist/index.js`
-- `types`: `dist/index.d.ts`
-
-The `prepare` script in `package.json` ensures that the project is built automatically when installed via a Git URL.
-
-## Releasing a New Version
-
-Publish **only after the PR is approved and merged** — never from an unreviewed branch. Then, from the merged `main`:
-
-1. **Pull** the latest `main` so you publish exactly what was reviewed (see also [Branch Hygiene](#branch-hygiene)).
-2. **Bump the version** with `npm version <patch|minor|major>` (or edit `package.json`). Never reuse a number that already exists on the registry — check first with `npm view @talkpilot/core-db versions`.
-3. **Verify**: `npm run build` and `npm test` (the Pre-push checklist in the README).
-4. **Publish**: `npm publish` (requires the shared token — see [Team Access & Authentication](#team-access--authentication)).
-5. Downstream repos pick it up via `npm update @talkpilot/core-db` or their next container build.
-
-Add a short release note for the version in the README (the version table and per-version section).
-
-### If a published version turns out to be broken
-
-Never republish or unpublish — a reused or missing number leaves a confusing gap in the registry. Instead, publish a **new** version with the fix, and add a one-line warning to the broken version's row in the README version table (e.g. "⚠️ do not use — <reason>; upgrade to <next version>") so consumers know to skip it.
-
-## Team Access & Authentication
-
-To allow the whole team to publish and install without adding individual npm accounts, we use a shared **npm Granular Access Token**.
-
-### One-time Local Setup
-
-Each developer needs to add the shared token to their local npm configuration. Do **NOT** add this to the project's `.npmrc` file, as it will be committed to Git.
-
-1. Get the shared **npm Automation Token**.
-2. Open (or create) your global npm configuration file:
-   ```bash
-   nano ~/.npmrc
-   ```
-3. Add the following line (replace `[TOKEN]` with the actual token):
-   ```text
-   //registry.npmjs.org/:_authToken=[TOKEN]
-   ```
-4. Save and exit.
-
-Now you can run `npm publish` and `npm install` for scoped `@talkpilot` packages without being prompted for credentials.
+# Development Guide
+
+Welcome to the `core-db` development guide. This document explains how to set up, develop, and test this package.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (v18 or later)
+- TypeScript
+
+### Setup
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Build the project:
+   ```bash
+   npm run build
+   ```
+
+## Local Development
+
+Use `npm pack` to test local changes in a consuming project.
+
+1. In the `core-db` folder, build and pack:
+   ```bash
+   npm run build && npm pack
+   ```
+   This produces a file like `talkpilot-core-db-x.y.z.tgz` in the project root.
+
+2. In the consuming project, install it:
+   ```bash
+   npm install /path/to/core-db/talkpilot-core-db-x.y.z.tgz
+   ```
+
+3. After making further changes to `core-db`, repeat step 1 and reinstall in the consuming project.
+
+## Adding a New Getter
+
+1. **Define Types**: Add your data types in the relevant domain's `types.ts` file.
+2. **Implement Getter**: Add the function in the `getters.ts` file.
+3. **Export**: Ensure the getter is exported from the domain's `index.ts` and finally from the main `src/index.ts`.
+4. **Test**: Create a test in the domain's `__tests__` folder.
+
+## Signature Immutability
+
+`core-db` is a shared package consumed by multiple services that may not all update at the same time. A signature change that looks harmless locally can silently break a service that hasn't picked up the new version yet.
+
+**Rules:**
+
+- **Never change an existing parameter's type or name.**
+- **Never add a required parameter** to an existing function.
+- **Never remove a function.** Mark it `@deprecated` instead (see below).
+- **Safe additions only**: you may add optional parameters or parameters with defaults — existing callers will continue to compile without changes.
+
+**Deprecating instead of deleting:**
+
+When a function is no longer the right approach, mark it deprecated and explain why. Consumers can then migrate on their own schedule.
+
+```ts
+/**
+ * @deprecated Use `newFunction` instead — reason for the change.
+ */
+export const oldFunction = (...) => { ... };
+```
+
+The deprecation comment must include either the name of the replacement or a clear explanation of why the function was retired, so a consumer reading the warning knows exactly what to do.
+
+## Testing
+
+We use Jest with `mongodb-memory-server` for fast, isolated database tests.
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Using Factories
+
+Always use factories to generate test data to keep tests clean and maintainable.
+
+```typescript
+import { createCallDoc } from '../calls.getters';
+import { createOutGoingCallDoc } from '../../../test-utils/factories';
+
+it('should save a call', async () => {
+  const call = createOutGoingCallDoc({ callSid: 'CA123' });
+  await createCallDoc(call);
+  // ... assertions
+});
+```
+
+## Build Process
+
+The project is built using TypeScript (`tsc`). The output is generated in the `dist/` directory.
+
+- `main`: `dist/index.js`
+- `types`: `dist/index.d.ts`
+
+The `prepare` script in `package.json` ensures that the project is built automatically when installed via a Git URL.
+
+## Releasing a New Version
+
+Publish **only after the PR is approved and merged** — never from an unreviewed branch. Then, from the merged `main`:
+
+1. **Pull** the latest `main` so you publish exactly what was reviewed (see also [Branch Hygiene](#branch-hygiene)).
+2. **Bump the version** with `npm version <patch|minor|major>` (or edit `package.json`). Never reuse a number that already exists on the registry — check first with `npm view @talkpilot/core-db versions`.
+3. **Verify**: `npm run build` and `npm test` (the Pre-push checklist in the README).
+4. **Publish**: `npm publish` (requires the shared token — see [Team Access & Authentication](#team-access--authentication)).
+5. Downstream repos pick it up via `npm update @talkpilot/core-db` or their next container build.
+
+Add a short release note for the version in the README (the version table and per-version section).
+
+### If a published version turns out to be broken
+
+Never republish or unpublish — a reused or missing number leaves a confusing gap in the registry. Instead, publish a **new** version with the fix, and add a one-line warning to the broken version's row in the README version table (e.g. "⚠️ do not use — <reason>; upgrade to <next version>") so consumers know to skip it.
+
+## Team Access & Authentication
+
+To allow the whole team to publish and install without adding individual npm accounts, we use a shared **npm Granular Access Token**.
+
+### One-time Local Setup
+
+Each developer needs to add the shared token to their local npm configuration. Do **NOT** add this to the project's `.npmrc` file, as it will be committed to Git.
+
+1. Get the shared **npm Automation Token**.
+2. Open (or create) your global npm configuration file:
+   ```bash
+   nano ~/.npmrc
+   ```
+3. Add the following line (replace `[TOKEN]` with the actual token):
+   ```text
+   //registry.npmjs.org/:_authToken=[TOKEN]
+   ```
+4. Save and exit.
+
+Now you can run `npm publish` and `npm install` for scoped `@talkpilot` packages without being prompted for credentials.