# 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.