@talkpilot/core-db 1.3.5 → 1.3.7

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/DEVELOPMENT.md

@@ -1,126 +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
-
-If you want to use this package in another project locally without publishing it:
-
-1. In the `core-db` folder:
-   ```bash
-   npm link
-   ```
-
-2. In your PROJECT folder:
-   ```bash
-   npm link @talkpilot/core-db
-   ```
-
-## Branch Hygiene
-
-When you start a new branch — and periodically while working on it — merge into your branch any sibling branches whose PRs have already been approved/merged. Building on the latest agreed-upon code prevents drift and avoids surprise integration conflicts when your own PR is reviewed.
-
-## 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.
-
-## Changing a Function's Signature
-
-Never change a published function's signature in place — consumers pin to a version, so a silent change breaks them on the next `npm update`. Instead:
-
-1. Add a **new versioned function** alongside the old one (e.g. `getFoo` → `getFooV2`) carrying the new signature.
-2. Mark the old one `@deprecated` in its JSDoc with a one-line message that names the replacement and recommends migrating to the newer version.
-3. Remove the deprecated function only in a later release, once no consumer references it.
-
-## 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.