L1:# @talkpilot/core-db

NPM Version @talkpilot/core-db is the shared TypeScript database package that wires TalkPilot APIs, municipal CRM integrations, and internal tools to a single, type-safe MongoDB surface. Every repo (MIS, CIS, TalkPilot Server, etc.) imports this package to avoid re-implementing connections, collections, or validation helpers.

Purpose

• Provide a reliable, multi-domain MongoDB layer for TalkPilot and municipal data.
• Export typed getters, vector search helpers, and document factories so services can focus on behavior instead of schema wiring.
• Manage connection lifecycles, environment configuration, and test helpers from one place so every repo reuses the same plumbing.

Main Concepts

• Multi-domain clients – src/connection.ts exposes mongodbClient (TalkPilot) and municipalDataMongodbClient, each of which resolves MONGO_URI, DB overrides, and default names.
• Domain-specific getters – src/talkpilot/ and src/municipal/ host typed getters (agents, calls, streets, tickets, etc.), vector-search helpers, and service-friendly adapters that keep caller code DRY.
• Product-specific clients (future) – While the package currently exposes the shared TalkPilot + municipal clients, we expect each product (CIS, MIS, TalkPilot Server) to eventually get its own domain-specific client helpers or wrappers so the shared core can remain stable while new consumers add targeted extensions.
• Test helpers – src/test-utils/ plus src/__tests__/ reuse MongoMemoryServer and shared factories so tests start with clean data regardless of the consuming repo.
• Utility layers – src/utils/ contains shared validation, pagination, and environment helpers that complement the getters.
• Bulk-write helpers – src/bulkWrite/ exposes small, domain-agnostic functions (buildSetOp, buildUpsertOp, buildInsertOp, buildDeleteOp) that construct correctly-shaped MongoDB bulk-write operations from a filter and field values — no collection- or domain-specific knowledge required.
• Configuration domain – src/configuration/ hosts the configuration database (a prompts collection so far) — a place for cross-service settings that used to be hardcoded in consuming repos, editable without a deploy.
• Environment awareness – Defaults, fallbacks, and process.env lookups ensure local, CI, and Cloud Run clients all connect using the right URI/DB names.

Key Components

• src/connection.ts – Central connection logic that resolves URIs/DB names from env vars (MONGO_URI, MONGODB_URI, TALKPILOT_DB_NAME, MUNICIPAL_DB_NAME) and reuses a single MongoClient.
• src/talkpilot/ – Call history, agents, flows, sessions, leads, subscriptions, and support helpers exposed as getters plus helper enums/types for each collection.
• src/municipal/ – Municipal-specific collections (cities, streets, departmentsSubjects, tickets, residents, etc.) plus vector search helpers and Ash Bina helpers used by MIS.
• src/utils/ – Shared helpers such as resolveConnection, pagination utilities, and schema validation helper functions.
• src/bulkWrite/ – Generic bulk-write op constructors (buildSetOp, buildUpsertOp, buildInsertOp, buildDeleteOp) usable with any collection's document type.
• src/configuration/ – configurationMongodbClient plus the prompts collection (Prompt type, getPromptByName, findPrompts, getAllPrompts, getPromptsByProduct).
• src/config.ts – Centralized process.env reads for the configuration domain — add new env-backed fields here instead of reading process.env inline elsewhere.
• src/test-utils/ and src/__tests__/ – Utilities that bootstrap MongoMemoryServer, expose factories, and make sure Jest environments can stub database calls predictably.
• dist/ – Compiled output consumed by downstream repos (CJS + ESM + type defs).

Domain APIs

• TalkPilot domain – Imports like findAgents, getFlows, findCalls, and vectorSearchCalls live in src/talkpilot. These functions are the canonical access pattern for call history, session metadata, and provider configs.
• Municipal domain – Helpers such as findStreets, getMunicipalCities, findDepartmentSubjects, and createTicket live under src/municipal and feed MIS workflows (street hints, subject matching, Ash Bina tickets).
• Configuration domain – getPromptByName, findPrompts, getAllPrompts, and getPromptsByProduct live under src/configuration and back MIS's moked_106 prompt lookups (defaults, overridable per-client via clientConfig.toolsPrompts).

Environment variables

| Variable | Purpose | Required | |---------------------|-----------------------------------------------------------------------------------|----------| | MONGO_URI | Primary MongoDB connection string for every domain (overridden by MONGODB_URI). | ✅ | | MONGODB_URI | Alternate connection string used when Mongo needs a second URI parameter. | ✅ | | TALKPILOT_DB_NAME | Optional override for the TalkPilot database name (defaults from URI path). | ❌ | | MUNICIPAL_DB_NAME | Optional override for the municipal database name (defaults to municipal-data). | ❌ | | CONFIGURATION_DB_NAME | Optional override for the configuration database name (defaults to configuration). | ❌ | | ENV | Free-form label used in logs/validators (defaults to unknown). | ❌ |

If you pass a uri directly to mongodbClient.connect() or municipalDataMongodbClient.connect(), the client will prefer that value over the env vars.

Getting Started

Prerequisites

• Node.js 22.x+ (aligns with downstream services).
• npm 11+ or Yarn.
• MongoDB accessible from your environment or a MongoMemoryServer for tests.

Setup

1. Clone the repo and install dependencies:

   git clone https://github.com/talkpilot/core-db.git
   cd core-db
   npm install

2. Build the package before using it locally:

   npm run build

3. Import @talkpilot/core-db from another project by pointing package.json at the local path during development or installing the published release.

Sample .env

MONGO_URI=mongodb://localhost:27017
TALKPILOT_DB_NAME=talkpilot-dev
MUNICIPAL_DB_NAME=municipal-dev
CONFIGURATION_DB_NAME=configuration-dev
ENV=development

Adjust MONGO_URI to match the running Mongo instance and configure talkpilot/municipal/configuration DB names if you want to keep them separate.

Local development

1. Run npm install.
2. Build the compiled output: npm run build.
3. Execute tests: npm run test.
4. Use npm link or npm pack to consume the freshly built package from other repos (CIS, MIS, TalkPilot Server).

Development guide

DEVELOPMENT.md contains the tactical steps for contributors. At a glance:

• Node 18+/TypeScript is required (aligns with downstream services).
• Run npm install → npm run build after cloning.
• Use npm link/npm link @talkpilot/core-db to test the package locally before publishing.
• When adding getters, define types, implement the function, export it through the domain index.ts, and add a corresponding test under the domain’s __tests__ folder.
• Always rely on the provided test factories (src/test-utils/factories) to seed data so tests remain consistent.
• Jest with mongodb-memory-server is the only execution path we have to verify this core utility—unit tests are the safety net for every change.

Refer to DEVELOPMENT.md for the full walkthrough, token instructions, and factory samples.

🧪 Testing

• npm run test – Jest suite (factories, utils, integration mocks) powered by mongodb-memory-server.
• Tests rely on src/__tests__/setup.ts to bootstrap the in-memory Mongo instances and wire shared factories/helpers before each run.
• When adding getters, helpers, or domain logic, create focused coverage inside the consuming domain’s __tests__/ folder and use the provided factories to keep fixtures consistent.

@talkpilot/core-db does not run in a product UI or feature branch—unit tests are the only reliable execution path to ensure your changes work. Every change must ship with a unit test so downstream repos can upgrade without surprises; treat the test suite as the canonical safety net for this core utility package.

🧹 Lint & build verification

• npm run lint – Run ESLint over src/**/*.{ts,tsx}.
• npm run format – Format the source files with Prettier.
• npm run build – Compile TypeScript and emit dist/ (used by downstream consumers).

✅ Pre-push checklist

1. npm run build.
2. npm run test.
3. npm run format.

Publishing & release notes

• Releases are handled by npm version <patch|minor|major> followed by npm publish. The package is a private @talkpilot dependency, so every contributor must install the shared npm automation token into their global ~/.npmrc before running publish or npm install.

• The shared token is rotated periodically—if you see authentication failures, request the refreshed token, update your ~/.npmrc, and retry. Never commit credentials to source control.

• After publishing, downstream repos (CIS, MIS, TalkPilot Server, etc.) should run npm update @talkpilot/core-db so they receive the latest helpers/bug fixes.

• Cloud Build & Cloud Run jobs that depend on this package pick up the new version the next time they rebuild their container; the services pull the compiled dist/ output and type definitions when installing the dependency.

• Release process, when to publish, branch hygiene, and the function-signature versioning policy: see DEVELOPMENT.md.

Version history

| Version | Note | |---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1.1.9 | Maintenance release (build, test, format). | | 1.3.4 | Added new statistics getters for call & ticket dashboards (CP-149): summary, trend, hourly, and routing for calls, plus open/draft/subject ticket stats. Removed the legacy getters getTicketsCountByCityAndDateRange and getTicketsSubjectStats. | | 1.3.5 | Added the muniIssues collection & module (CP-1115): the MuniIssue document type, createMuniIssue (accepts a caller-supplied _id for a two-way Jira link), generateMuniIssueId, getMuniIssueById / getMuniIssueByJiraKey, a $jsonSchema validator with indexes (unique jira.key), and ensureMuniIssuesCollection to provision it at boot. | | 1.3.6 | Added contextNotes and products modules under src/talkpilot/. | | 1.3.7 | Added disableGenericPrompt optional boolean field to the Flow type and schema (CP-704). | | 1.3.8 | Ticket-count Map getters (CP-1200): deprecated string[] ticket getters and CallsStatsFilter fields, added Map<string, number> replacements; fixed ticket counting in aggregateCallsSummary. | | 1.3.9 | Fixed wrap-around hour filter boundary guards (CP-1166): excluded first-day morning calls and last-day evening calls from wrap-around windows. | | 1.3.10 | Added optional isDraft flag to Ticket (CP-1390): explicit draft marking with legacy fallback for existing tickets. | | 1.3.11 | Fixed pre-existing broken type declaration import in clientsConfig.types.d.ts that caused consumer tsc builds to fail. | | 1.3.12 | Added callsWithTickets to CallsSummaryAggregation (CP-1200): distinct call count with at least one open ticket, enabling accurate ticketOpenRate and not_opened calculations in consumers. | | 1.3.13 | Faulty release (redundant). Published with Flow.useRedisTranscription at the flow level; superseded by 1.3.14. | | 1.3.14 | Added FlowTool.useRedisTranscription optional flag to control whether cached Redis transcriptions are used (defaults to false). | | 1.3.15 | Multi-scan support for WebsiteTalk (CP-1372): websiteUrls collection, Scan.websiteUrlId, OVERWRITTEN status, activeScanId on WebsiteTalkProduct. Breaking: Scan.baseUrl removed; getActiveScanStatus removed. | | 1.3.16 | Refactored WebsiteTalk scan status constants (CP-1372): SCAN_STATUSES object map, FINISHED_SCAN_STATUSES derived from it, isInProgressScan moved to scans.utils. No breaking API changes. | | 1.3.17 | Twilio call-status semantics for Websitalk dashboard: inCallCount KPI (in-progress + answered), busy is line-busy only; updateCallStatusByCallSid; expanded CallStatus union; timeSavedMinutes from completed only. | | 1.3.18 | WebsiteTalk multi-website API (CP-1372): ships websiteUrls module, scan getters by websiteUrlId, activeScanId getters on clientsConfig. Note: 1.3.17 did not include these — they landed after merge. Breaking: WebsiteTalkProduct.defaultBaseUrl removed from type. | | 1.3.19 | WebsiteTalk flow provisioning (WTIS activate-scan): optional flowId on WebsiteTalkProduct; bindClientPhoneToFlow(clientId, flowId) sets flow_id on the client's primary phone_numbers document so inbound calls route to the provisioned TalkPilot flow. | | 1.3.20 | FINAL_STATUSES constant for terminal Twilio call statuses (no-answer, completed, busy, failed, canceled) in calls.constants. | | 1.3.21 | Added ToolExecutionStep type, steps field to ToolExecution, and pushToolExecution getter (CP-1093). Added ToolExecutionStepLevel named type and TOOL_EXECUTIONS_DEFAULT_LIMIT/SKIP constants. Widened ToolExecutionStep.data to Record<string, unknown> \| string — allows plain string steps alongside structured JSON. Added optional ToolExecutionStep.payload for structured drill-down data. | | 1.3.22 | CallsFilterParams.status typed as CallStatus instead of string — aligns call-query filters with the Twilio status union from 1.3.17. | | 1.3.23 | Merge of 1.3.21 and 1.3.22 — combines the ToolExecutionStep/steps/pushToolExecution work (CP-1093) with the CallsFilterParams.status: CallStatus fix. Adds CallStatusValues (const object) with CallStatus and ALL_CALL_STATUSES derived from it. CallStatus still does not include "redirected" — tracked separately. | | 1.3.24 | Breaking: removed flowId from WebsiteTalkProduct — flow source of truth is phone_numbers.flow_id. Added getPrimaryPhoneFlowId(clientId). | | 1.3.25 | Added disconnectDb() to close all MongoDB clients opened by ensureDbConnected() — for one-shot scripts that must exit cleanly. | | 1.3.28 | Soft-delete (isActive) on Streets/DepartmentSubjects, new bulk-write getters, MongoDB type re-exports, and the generic bulkWrite op-builder module. | | 1.3.29 | Added client call-quota module (CP-1500): ClientConfig.quota for usage limits (totalQuota, usedQuota, expiresAt), alert settings on clients, and getters for state, increment/reset, threshold alerts, and expiry notification tracking. | | 1.3.32 | clientDisplayName lives on clientsConfig.quota (not top-level). getClientDisplayName returns "-" when unset; never exposes clientId. | | 1.3.33 | Added configuration database module (CP-1560): configurationMongodbClient + a read-only Prompts-style collection for prompts previously hardcoded in consuming repos (e.g. MIS). | | 1.3.35 | Fixed the configuration collection name (Prompts → prompts, matches the lowercase convention used elsewhere). Breaking if you inserted documents into a collection literally named Prompts. Added Prompt.productName (required) + getPromptsByProduct. Centralized configuration-DB env var reads into src/config.ts. | | 1.3.36 | Publish combining the 1.3.33/1.3.35 configuration-DB work with the latest main (client quota + clientDisplayName + bulk-write/streets/departmentSubjects updates — see 1.3.28/1.3.29/1.3.32). No new code of its own. | | 1.3.37 | Added models and internalModels collections under configuration (CP-1624): realtime/stt model catalog (ModelDoc, getModelByModelId, getModelsByProvider, getModelsByType, getAvailableModelsByType) and a name-keyed settings store (InternalModel, getInternalModelByName) for cross-service config previously hardcoded in consuming repos (e.g. TalkPilot Server's realtime/STT catalogs and its live transcription model). Read-only, same as prompts — documents are seeded/managed manually. | | 1.3.38 | Added optional transcriptionComparison field to Call (CP-1594): per-{provider}-{model} side-channel transcription comparison results, same segment shape as Call.transcription. | | 1.3.39 | Multi-scan support for WebsiteTalk (CP-1628): clientsConfig.activeScanIds (up to MAX_ACTIVE_SCANS) and primaryScanId replace the single activeScanId for search; addActiveScanId/removeActiveScanId/getActiveScanIds, setPrimaryScanId/clearPrimaryScanId/getPrimaryScanId. getActiveScanIds falls back to the legacy singular field, so pre-migration clients keep working. | | 1.3.40 | Live scan progress for WebsiteTalk (CP-1527): scanResources module with KPI counts, board pagination, and page detail; terminal snapshot fields on Scan. | | 1.3.47 | Added optional accountOwnerEmail field to WebsiteTalkProduct (CP-1715): the recipient for the end-of-call summary email, set once from the client's login email and editable in Settings. | | 1.3.48 | Fixed getScanPages search (CP-1726): user search input was passed unescaped into MongoDB's $regex, so a URL/title containing regex-special characters (e.g. ?) failed to match even when the document existed. Added escapeRegex() and applied it before building the url/title $regex filter. No API changes. | | 1.3.49 | Internal tools configuration on flows (CP-1723): Flow.internalTools keyed by tool name (enabled, optional maxCalls, per-parameter description/value overrides) with matching $jsonSchema validator, plus createFlow / updateFlowById mutators and the FlowUpdateParams type so consumers stop writing to the flows collection directly. | | 1.3.57 | Phone-number bind getters: list by client, exclusive flow assign, unbind, and flow_id match for ObjectId or leftover string. getClientByClientId. | | 1.3.61 | Optional activeFlowId on WebsiteTalkProduct (CP-1849). WebsiteTalk updates this flow instead of the flow on a phone number. | | 1.3.62 | Pause/Resume support for WebsiteTalk scans (CP-1752): PAUSED and CANCELED added to SCAN_STATUSES (PAUSED deliberately excluded from FINISHED_SCAN_STATUSES — pausing isn't done, CANCELED is). Added Scan.pausedAt, tracked across pause/resume so elapsed-time display can freeze correctly instead of counting the paused duration. | | 1.3.64 | New callTokenUsage collection with incrementCallTokenUsage (CP-1810): per-call realtime token usage, one document per callSid. | | 1.3.65 | Flow.beforeCallEvent as an optional HTTP config object (url required; timeoutMs, sendUserAuthToken, allowedKeys, wait). afterCallEvent remains an optional Pub/Sub string. | | 1.3.69 | Municipal residents collection: optional resident fields (cityName, firstName, lastName, idNumber, phoneNumber, address) with exact-match getters by phone, by idNumber, and by phone+idNumber (city-scoped). Schema + indexes exported; collection is created out of band. | | 1.3.71 | Who ended a call (CP-1873): optional Call.endedBy (system / agent / user), CallEndedByValues, and setCallEndedBy (first write wins). Breaking vs 1.3.69–1.3.70: the value resident was replaced by user. | | 1.3.74 | Added human to CallEndedByValues (CP-1873): a human agent ended the call, after a transfer or in a conference. | | 1.3.82 | Complaint tracking on muniIssues (CP-1888): optional status / response / updatedAt; an editable TalkPilot response with up to MUNI_ISSUE_MAX_RESPONSE_IMAGES (5) response.imageUrls and response.updatedAt; updateMuniIssueStatus, setMuniIssueResponse, findMuniIssuesByClient, countMuniIssuesByClient, getMuniIssueByIdForClient; index clientId_1_createdAt_-1. | | 1.3.88 | Single-note writes on contextNotes (CP-1998): append, update, or remove one entry without replacing the rest of the list. |

1.1.9

1. npm run build.
2. npm run test.
3. npm run format.

1.3.4 — Call & ticket statistics (CP-149)

New call statistics getters for dashboards (summary, trend, hourly, routing) and ticket statistics scoped to the same date range (open tickets, draft tickets, subject breakdowns).

Removed

| Removed | Replacement | |-------------------------------------|-----------------------------------------------------------------------------------------------------------------| | getTicketsCountByCityAndDateRange | aggregateCallsSummary + findCallSidTicketCountsByCity — note: returns Map<string, number>, not string[] | | getTicketsSubjectStats | findSubjectsByCityAndDateRange | | SubjectStatsItem | SubjectItem |

Do I need to update my app?

Yes — if you used any of the removed functions above.

1.3.5 — Muni issues (CP-1115)

New muniIssues module under src/municipal/ for issues reported from the call-log screen. The document is written to the municipal DB after its Jira ticket is created.

Added

| Export | Purpose | |----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | MuniIssue / CreateMuniIssueInput | Document type and insert-input type (issueContent + jira domains). | | createMuniIssue(input, id) | Insert an issue; requires a caller-supplied _id from MIS (via generateMuniIssueId) so it matches the id embedded in the Jira ticket (two-way link). | | generateMuniIssueId() | Pre-generate the _id to pass to createMuniIssue. | | getMuniIssueById / getMuniIssueByJiraKey | Lookups by our id or by the Jira key. | | ensureMuniIssuesCollection() | Provision the $jsonSchema validator and indexes (unique jira.key); run once at MIS boot. |

Do I need to update my app?

No — purely additive. New consumers (MIS) import these from @talkpilot/core-db.

1.3.6 — Context Notes & Products

Context Notes — new contextNotes collection under src/talkpilot/ for per-client, per-product notes injected into AI calls at runtime. Each document holds a systemPrompt and a list of time-bounded entries (activeFrom, expiresAt). Two setters with split ownership: setContextNoteEntries for the notes list and setContextNoteConfig for systemPrompt and product.

Products — new products collection under src/talkpilot/ cataloguing TalkPilot products. Each document has a stable name and an optional displayName locale map (Record<string, string>) for UI display.

Added

| Export | Purpose | |----------------------------------------------|-----------------------------------------------------------------| | getContextNotes(clientId, product) | Fetch context note documents for a client/product pair. | | createContextNote(input) | Insert a new context note document. | | setContextNoteEntries(id, clientId, notes) | Replace the notes list on an existing document. | | setContextNoteConfig(id, clientId, config) | Update systemPrompt and/or product on an existing document. | | getAllProducts() | Fetch the full product catalogue. |

Do I need to update my app?

No — purely additive.

1.3.7 — Generic prompt control (CP-704)

Added an optional boolean field to the Flow type and MongoDB schema.

Added

| Export | Purpose | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| | Flow.disableGenericPrompt | Optional boolean. When true, disables the generic prompt for the flow. Existing flows without this field continue to work unchanged. |

Do I need to update my app?

No — the field is optional and fully backwards-compatible.

1.3.8 — Ticket-count Map getters (CP-1200)

Adds Map<string, number> ticket getters that return per-call ticket counts. The old string[] getters and filter fields are kept and marked @deprecated.

Deprecated → Replacement

| Deprecated | Replacement | |---------------------------------------------|--------------------------------------------------------------| | findCallSidsWithTicketsByCity | findCallSidTicketCountsByCity → Map<string, number> | | findCallSidsWithDraftTicketsByCity | findCallSidDraftTicketCountsByCity → Map<string, number> | | CallsStatsFilter.callSidsWithTickets | CallsStatsFilter.callSidTicketCounts | | CallsStatsFilter.callSidsWithDraftTickets | CallsStatsFilter.callSidDraftTicketCounts |

Do I need to update my app?

No — the old fields still compile. Migrate when convenient.

1.3.9 — Wrap-around hour filter boundary guards (CP-1166)

When hourFrom > hourTo (e.g. 23:00–13:00), two silent miscounting bugs existed:

• First-day morning: calls before hourTo on the first day (e.g. 08:00 on Jun 8) were counted even though the window starts at hourFrom that day. Fixed by adding dateLocal > startStr to the after-midnight leg.
• Last-day evening: calls at or after hourFrom on the last day (e.g. 23:30 on Jun 9) were counted even though the window ends at hourTo that day. Fixed by adding dateLocal < endStr to the before-midnight leg.

Affects: aggregateCallsTrend, aggregateCallsSummary, aggregateCallsHourlyByRange, aggregateCallsRouting, findFilteredCallSids, findSubjectsByCityAndDateRange.

Do I need to update my app?

No API changes — both fixes correct silent miscounting. Upgrading is recommended if you use a wrap-around hour window.

1.3.10 — Ticket draft flag (CP-1390)

Added an optional isDraft boolean field to the Ticket type.

Added

| Export | Purpose | |------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Ticket.isDraft | Optional boolean. When true, the ticket is a draft. When false, it is not. When absent (legacy tickets), draft detection falls back to the previous event_subject_id heuristic. |

Affects: findCallSidDraftTicketCountsByCity, findCallSidsWithDraftTicketsByCity (draft filtering in ticket statistics).

Do I need to update my app?

No — purely additive. Existing tickets without isDraft continue to work unchanged. New consumers (MIS) can pass isDraft: true when creating a draft ticket.

1.3.11 — Fix clientsConfig type declaration import

Fixed a pre-existing broken import path in the published clientsConfig.types.d.ts (introduced in an earlier release, unrelated to 1.3.10). Consumer TypeScript builds could fail with:

Cannot find module 'src/utils/shared.types' or its corresponding type declarations.

The import now uses a relative path (../../utils/shared.types) so tsc resolves it correctly from node_modules/@talkpilot/core-db/dist/.

Do I need to update my app?

Yes — upgrade to 1.3.11 if your build failed with the error above (affects any version that shipped the broken declaration). No API or behavior changes otherwise.

1.3.12 — Calls-with-tickets count (CP-1200)

Added callsWithTickets to CallsSummaryAggregation — the number of distinct calls that opened at least one ticket. Use this field (instead of openTickets) to compute call-level rates and "calls without a ticket" counts.

Do I need to update my app?

Yes — replace openTickets with callsWithTickets wherever you compute ticketOpenRate or not_opened.

1.3.13 — Faulty release

This release incorrectly placed useRedisTranscription on Flow instead of FlowTool. It is redundant and should be skipped.

1.3.14 — Redis transcription flag

Added an optional FlowTool.useRedisTranscription boolean that tells consumers whether to read transcriptions from Redis. Defaults to false when omitted.

Do I need to update my app?

No — this flag is optional. Only update if you want to opt into the Redis transcription path.

1.3.15 — Multi-scan configuration (CP-1372)

Adds websiteUrls collection (CRUD getters), migrates scans from baseUrl to websiteUrlId, adds OVERWRITTEN scan status, and replaces defaultBaseUrl/logoUrl on WebsiteTalkProduct with activeScanId (+ getters).

Breaking

| Removed / changed | Replacement | | --- | --- | | Scan.baseUrl | Scan.websiteUrlId | | WebsiteTalkProduct.defaultBaseUrl | websiteUrls collection | | getActiveScanStatus(clientId) | getInProgressScanByWebsiteUrl, findInProgressScansByClient |

Do I need to update my app?

Yes — WTIS, CoreBrain, and CoreCrawler must adopt websiteUrlId and the new getters before upgrading.

1.3.16 — Scan status constants refactor (CP-1372)

Centralizes scan status values under a single SCAN_STATUSES object map and derives terminal statuses from it.

Changed

| Area | What | | --- | --- | | SCAN_STATUSES | Object map (SCAN_STATUSES.CHECKING, SCAN_STATUSES.COMPLETED, …) instead of separate exported string constants. | | FINISHED_SCAN_STATUSES | Derived from SCAN_STATUSES (COMPLETED, FAILED, OVERWRITTEN). | | isInProgressScan | Moved to scans.utils.ts (exported from scans index). | | ScanStatus type | Derived from (typeof SCAN_STATUSES)[keyof typeof SCAN_STATUSES]. |

Do I need to update my app?

No — behavior is unchanged. If you imported removed aliases like COMPLETED_SCAN_STATUS, switch to SCAN_STATUSES.COMPLETED (or keep using string literals / ScanStatus type).

1.3.17 — Twilio call-status semantics (CP-1521)

Aligns dashboard KPIs and call-status updates with Twilio semantics so in-call counts update in real time.

Added

| Export | Purpose | | --- | --- | | updateCallStatusByCallSid(callSid, status) | Set the current call status by callSid. | | IN_CALL_STATUSES | ["in-progress", "answered"] — statuses counted as in-call. | | DashboardSummaryMetrics.inCallCount | Replaces busyCount; counts in-progress + answered calls. |

Changed

| Area | What | | --- | --- | | Dashboard KPIs | busyCount → inCallCount; busy is line-busy only, not in-call. | | timeSavedMinutes | Computed from completed calls only. | | CallStatus union | Expanded for Twilio-aligned statuses. |

Do I need to update my app?

Yes — if you read busyCount from dashboard KPIs, switch to inCallCount.

1.3.18 — WebsiteTalk multi-website API (CP-1372)

Ships the full persistence API for multi-website / multi-scan. Versions 1.3.15–1.3.16 documented the design; 1.3.17 did not export these symbols (CP-1372 merged into main after the 1.3.17 release). Upgrade to 1.3.18 if you see missing-export errors such as getActiveScanId, getWebsiteUrlById, or WebsiteUrlDoc.

websiteUrls module

| Export | Purpose | | --- | --- | | WebsiteUrl / WebsiteUrlDoc / CreateWebsiteUrlInput | Document types. | | getWebsiteUrlsCollection() | Collection access. | | getWebsiteUrlsByClient(clientId) | All websites for a client. | | getWebsiteUrlById(id) | Lookup by id. | | findWebsiteUrls(filter?) | Flexible query. | | createWebsiteUrl({ clientId, name, baseUrl }) | Create. | | updateWebsiteUrl(id, updates) | Update name / baseUrl. | | deleteWebsiteUrl(id) | Delete by id. |

clientsConfig — selected scan

| Export | Purpose | | --- | --- | | getActiveScanId(clientId) | Read products.websiteTalk.activeScanId. | | updateActiveScanId(clientId, scanId) | Set the active scan for search. | | clearActiveScanId(clientId) | Unset activeScanId. |

scans — by websiteUrlId

| Export | Purpose | | --- | --- | | getScanById(id) | Lookup by id. | | getScansByWebsiteUrl(websiteUrlId) | All scans for a website. | | getLatestScanByWebsiteUrl(websiteUrlId) | Most recent scan. | | getInProgressScanByWebsiteUrl(websiteUrlId) | Latest scan if still in progress. | | findInProgressScansByClient(clientId) | All in-progress scans for a client. | | hasScansForWebsiteUrl(websiteUrlId) | Whether any scans exist. | | getLatestCompletedScanByWebsiteUrl(websiteUrlId) | Most recent COMPLETED scan. | | updateScanDoc(scanId, updates) | Partial update (e.g. mark OVERWRITTEN). | | deleteScansByWebsiteUrl(websiteUrlId) | Delete all scans for a website. |

Breaking / type changes

| Removed | Replacement | | --- | --- | | WebsiteTalkProduct.defaultBaseUrl | websiteUrls collection (name, baseUrl) | | Scan.baseUrl | Scan.websiteUrlId (see 1.3.15) |

OVERWRITTEN scan status

• OVERWRITTEN is part of ScanStatus / SCAN_STATUSES.
• Marking previous COMPLETED scans as overwritten is not done in createScanDoc — implement in the service layer (e.g. via updateScanDoc).

Not in core-db (service layer)

• resolveActiveWebsiteContext — join activeScanId → scan → websiteUrl.
• Migration from legacy defaultBaseUrl.

Do I need to update my app?

Yes — WTIS, CoreBrain, and CoreCrawler should upgrade to 1.3.18 and import the symbols above from @talkpilot/core-db. Stop reading defaultBaseUrl from WebsiteTalkProduct; use websiteUrls instead.

1.3.19 — WebsiteTalk flow provisioning (WTIS activate-scan)

Persists the TalkPilot flow id on the client product config and links the client's primary phone number to that flow so inbound calls use the WebsiteTalk flow after activate-scan.

clientsConfig — WebsiteTalkProduct

| Field | Purpose | | --- | --- | | WebsiteTalkProduct.flowId? | Optional TalkPilot flow _id (hex string). Set by WTIS after POST /flows/add_new_flow; reused on later activations via PUT /flows/edit_flow/:id. |

phone_numbers

| Export | Purpose | | --- | --- | | bindClientPhoneToFlow(clientId, flowId) | Updates the primary phone_numbers row for clientId, setting flow_id to the given TalkPilot flow. Throws if no primary phone exists. |

Typical service-layer flow (WTIS)

1. Build flow payload from template + companyInfo (generated at activate time).
2. Create or update the flow via TalkPilot Server API (add_new_flow / edit_flow).
3. On first create: updateProductConfig(clientId, "websiteTalk", { flowId }).
4. bindClientPhoneToFlow(clientId, flowId) — ensure the phone routes to the flow.
5. updateActiveScanId(clientId, scanId) — point search at the activated scan.

Not in core-db (service layer)

• Flow template substitution, Claude companyInfo generation, Firebase Storage template download, TalkPilot flow create/update HTTP calls.

Do I need to update my app?

No — purely additive. WTIS should upgrade to 1.3.19 (or later) and import bindClientPhoneToFlow plus WebsiteTalkProduct.flowId when implementing activate-scan flow provisioning.

1.3.20 — FINAL_STATUSES call-status constant

Centralizes terminal Twilio call statuses so consumers (e.g. TalkPilot Server callResultService) don't duplicate the list locally.

Added

| Export | Purpose | | --- | --- | | FINAL_STATUSES | ["no-answer", "completed", "busy", "failed", "canceled"] — statuses where no further Twilio callbacks are expected. Pair with IN_CALL_STATUSES for live vs terminal semantics. |

Do I need to update my app?

No — purely additive. Replace local FINAL_STATUSES arrays with import { FINAL_STATUSES } from "@talkpilot/core-db" when convenient.

1.3.21 — Tool execution steps & push getter (CP-1093)

Added ToolExecutionStep type, steps field on ToolExecution, pushToolExecution getter, named ToolExecutionStepLevel type, and pagination constants.

Added

| Export | Purpose | | --- | --- | | ToolExecutionStepLevel | Named type: "info" \| "warn" \| "error". | | ToolExecution.steps | Optional ToolExecutionStep[]. Ordered log of intermediate steps within a tool call (e.g. audio_enrichment, google_places, subject_classification). Absent on executions recorded before this version. | | ToolExecutionStep.payload | Optional Record<string, unknown>. Structured data for UI drill-down, alongside the human-readable data field. | | pushToolExecution(callSid, execution) | Append a ToolExecution to the call's toolExecutions array via $push. | | getToolExecutionsByCallSid(callSid, opts?) | Fetch the toolExecutions array for a call. opts.skip and opts.limit (default TOOL_EXECUTIONS_DEFAULT_LIMIT = 50) support pagination. Returns [] when the call has no executions or does not exist. | | TOOL_EXECUTIONS_DEFAULT_LIMIT | 50 — default page size for getToolExecutionsByCallSid. | | TOOL_EXECUTIONS_DEFAULT_SKIP | 0 — default skip for getToolExecutionsByCallSid. |

Do I need to update my app?

No — purely additive. All new fields are optional and existing documents continue to work unchanged.

1.3.22 — CallsFilterParams.status type alignment

Tightens the status filter field on CallsFilterParams from string to CallStatus so call-query consumers get compile-time validation against the Twilio-aligned status union introduced in 1.3.17.

Changed

| Area | What | | --- | --- | | CallsFilterParams.status | string → CallStatus |

Do I need to update my app?

Only if you pass a non-CallStatus string to CallsFilterParams.status — fix the value or cast. No runtime behavior change.

1.3.23 — Merge of 1.3.21 and 1.3.22, plus CallStatusValues

Combines the CP-1093 tool-execution-steps work (1.3.21) with the CallsFilterParams.status type fix (1.3.22); both were published independently from diverging branches.

Added

| Export | Purpose | | --- | --- | | CallStatusValues | as const object mapping named keys (Completed, Failed, ...) to the 9 raw Twilio-aligned status strings — gives enum-like dot access (CallStatusValues.Completed) while CallStatus stays a plain string-literal union (no breaking change for existing status === "completed" comparisons). | | CallStatus | Now derived from CallStatusValues ((typeof CallStatusValues)[keyof typeof CallStatusValues]) instead of a hand-written union — single source of truth. | | ALL_CALL_STATUSES | CallStatus[] — Object.values(CallStatusValues), for runtime validation of raw input (e.g. HTTP query params) against CallStatus. |

Do I need to update my app? No — CallStatus is structurally identical to before (same 9 string literals); this is a source-only refactor.

CallStatus still does not include "redirected" — tracked separately.

1.3.28 — Soft-delete support and generic bulk-write helpers

Adds an isActive soft-delete convention, bulk-write getters for Streets/DepartmentSubjects, MongoDB type re-exports, and a generic bulk-write op-builder module.

Added

| Export | Purpose | | --- | --- | | Street.isActive / DepartmentSubject.isActive | Optional soft-delete flag; createStreet defaults it to true. | | bulkWriteStreets / bulkWriteDepartmentsSubjects | Passthrough bulk-write for each collection. | | findDepartmentSubjectsByFilter | Query subjects by an arbitrary filter. | | updateDepartmentSubjectActive | Set isActive on a subject by _id. | | ObjectId, Filter, BulkWriteOp, BulkWriteError, OptionalUnlessRequiredId | Re-exported from mongodb. | | buildSetOp, buildUpsertOp, buildInsertOp, buildDeleteOp | Generic bulk-write op builders — filter/fields in, a shaped op out. |

Do I need to update my app?

No — purely additive.

1.3.29 — Client call quota (CP-1500)

Per-client call quota with usage counters, optional expiration, and configurable threshold/expiry email alerts. Usage lives on clientsConfig; alert config and send-tracking live on clients. TalkPilot Server consumes these getters to block calls when quota is exceeded or expired and to send notification emails.

Data model

| Location | Field | Purpose | | --- | --- | --- | | clientsConfig.quota | totalQuota, usedQuota, expiresAt? | Call allowance and consumption. getClientQuotaState returns null when totalQuota is unset (quota disabled for that client). | | clients.quota | alerts?, expiredSent? | Up to 3 threshold alerts (each with up to 3 recipient emails) and a flag set after the expiry email is sent. |

Added

| Export | Purpose | | --- | --- | | ClientQuotaUsage | Usage shape: totalQuota, usedQuota, optional expiresAt. | | ClientQuotaSettings | Alert settings on the clients doc: alerts, expiredSent. | | ClientQuotaState | Merged view returned by getClientQuotaState (usage + settings). | | QuotaThresholdAlert / QuotaAlertInput | Threshold alert with thresholdPct, recipientEmails, and optional thresholdSent send-tracking. | | getClientQuotaState(clientId) | Read combined quota state; null when no quota is configured. | | incrementClientQuotaUsage(clientId, amount?) | Atomically increment clientsConfig.quota.usedQuota (default amount = 1). No-op when quota.totalQuota is absent. | | resetClientQuotaUsage(clientId) | Reset usedQuota to 0 and clear alert/expiry send flags via resetClientQuotaSettings. | | updateQuotaAlertsConfig(clientId, alerts) | Replace threshold alert config; preserves thresholdSent for unchanged thresholds. | | markQuotaAlertSent(clientId, alertIndex) | Idempotently mark a threshold alert as sent; returns whether the update applied. | | markQuotaExpiredSent(clientId) | Idempotently mark the expiry notification as sent; returns whether the update applied. | | resetClientQuotaSettings(clientId) | Clear expiredSent and strip thresholdSent from alerts (keeps alert definitions). |

Do I need to update my app?

No — purely additive. TalkPilot Server should upgrade to 1.3.29 (or later) to enforce quota on inbound/outbound calls and to drive threshold/expiry emails via the new getters.

1.3.32 — Quota clientDisplayName

Optional human-readable account label stored on clientsConfig.quota for quota notification emails. TalkPilot Server uses getClientDisplayName instead of exposing raw clientId in alert/expiry email copy.

Changed

| Area | What | | --- | --- | | ClientQuotaUsage.clientDisplayName? | Optional display name on clientsConfig.quota — e.g. "Acme Corp". Included in ClientQuotaState via getClientQuotaState. |

Added

| Export | Purpose | | --- | --- | | getClientDisplayName(clientId) | Returns trimmed quota.clientDisplayName, or "-" when unset, missing, or blank. Never falls back to clientId. |

Do I need to update my app?

No — purely additive. Set clientsConfig.quota.clientDisplayName when provisioning quota for a client. TalkPilot Server should upgrade to 1.3.32 (or later) to use the label in quota emails.

1.3.33 — Configuration database & Prompts collection (CP-1560)

New configuration database with a prompts collection, so prompts previously hardcoded in consuming repos (e.g. MIS's moked_106 street/subject search and transcription prompts) can be stored centrally and edited without a deploy. Ships the read path only — documents are seeded/managed manually (e.g. via Compass), not through this package.

Added

| Export | Purpose | | --- | --- | | configurationMongodbClient | MongoDB client for the configuration database (default name configuration, override with CONFIGURATION_DB_NAME). | | getConfigurationDb / setConfigurationDb / ConfigurationObjectId | DB handle accessors and ObjectId, matching the other domains. | | Prompt | Document type: { _id, name, content, createdAt, updatedAt }, keyed by unique name. | | getPromptByName(name) | Fetch a single prompt by its unique name. Returns null if absent. | | findPrompts(filter?) | Flexible query over the collection. | | getAllPrompts() | Fetch every prompt. | | getPromptsCollection() | Raw collection access. |

ensureDbConnected() / disconnectDb() now also connect/disconnect the configuration client alongside talkpilot/municipal/websitalk.

Do I need to update my app?

No — purely additive. Consumers opt in by importing the getters above.

1.3.35 — Prompts fixes: collection name, productName, centralized config

Breaking

| Changed | What | | --- | --- | | Collection name | "Prompts" → "prompts" (lowercase, matching every other collection in core-db). MongoDB collection names are case-sensitive — if you inserted documents into a collection literally named Prompts under 1.3.33, move them to prompts. |

Added

| Export | Purpose | | --- | --- | | Prompt.productName | Required KnownProductKey ("municipal" \| "clinics" \| "websiteTalk"). Existing documents need this field backfilled. | | getPromptsByProduct(productName) | Fetch all prompts for a given product. |

Internal

• Configuration-DB env var reads (MONGO_URI, MONGODB_URI, CONFIGURATION_DB_NAME) centralized into src/config.ts (configurationDbConfig) — no consumer-facing change.

Do I need to update my app?

Only if you inserted documents into the old Prompts (capital P) collection — move them to prompts. Also backfill productName on any existing prompt documents (e.g. "municipal"), since it's now a required field on the type.

1.3.36 — Merge with main

Publishes the 1.3.33/1.3.35 configuration-DB work alongside the latest main — client call-quota, clientDisplayName, and bulk-write/streets/departmentSubjects updates (see 1.3.28, 1.3.29, 1.3.32). No new code of its own; this version exists to ship both branches' work together.

Do I need to update my app?

No — purely additive, same as the versions it combines.

1.3.37 — Model catalog & internal model settings (CP-1624)

New models and internalModels collections under the configuration database, so AI model catalogs and cross-service settings previously hardcoded in consuming repos (e.g. TalkPilot Server's realtime/STT model lists and its live transcription model) can be stored centrally and edited without a deploy. Ships the read path only, same as prompts — documents are seeded/managed manually (e.g. via Compass).

Added — models

| Export | Purpose | | --- | --- | | ModelDoc (RealtimeModelDoc \| SttModelDoc) | Document type discriminated by type: { _id, modelId, name, description?, available, features?, configDefaults?, createdAt, updatedAt }, plus provider (RealtimeModelProvider for type: "realtime", SttModelProvider for type: "stt"). | | MODEL_TYPES, REALTIME_MODEL_PROVIDERS, STT_MODEL_PROVIDERS | Known type/provider value lists the types above are derived from. | | getModelByModelId(modelId, type?) | Fetch a single model by its modelId, optionally scoped to a type. | | getModelsByProvider(provider, type?) | Fetch all models for a given provider, optionally scoped to a type. | | getModelsByType(type) | Fetch all models of a given type. | | getAvailableModelsByType(type) | Same as above, pre-filtered to available: true. | | findModels(filter?) | Flexible query over the collection. | | getModelsCollection() | Raw collection access. |

Added — internalModels

| Export | Purpose | | --- | --- | | InternalModel | Document type: { _id, name, provider, model, config?, createdAt, updatedAt }, keyed by unique name — e.g. a "transcriptionModel" document. | | getInternalModelByName(name) | Fetch a single internal model config by its unique name. Returns null if absent. | | findInternalModels(filter?) | Flexible query over the collection. | | getAllInternalModels() | Fetch every internal model. | | getInternalModelsCollection() | Raw collection access. |

ensureDbConnected() / disconnectDb() already covered the configuration client from 1.3.33 — no change there.

Do I need to update my app?

No — purely additive. Consumers opt in by importing the getters above.

1.3.38 — Transcription comparison field (CP-1594)

Added an optional transcriptionComparison field to Call, for consumers that run side-channel transcription comparisons across multiple providers/models alongside the real transcription field.

Added

| Export | Purpose | | --- | --- | | Call.transcriptionComparison | Optional Record<string, TranscriptionSegment[]> — one entry per {provider}-{model} key, each an array of TranscriptionSegment in the same shape as Call.transcription. |

Do I need to update my app?

No — purely additive. Existing documents and consumers continue to work unchanged.

1.3.39 — Multi-scan support for WebsiteTalk (CP-1628)

Adds support for multiple simultaneously active scans per client (up to MAX_ACTIVE_SCANS, currently 3), plus a primaryScanId that decouples "which scans back search" from "which scan seeds the call's opening line."

Added

| Export | Purpose | | --- | --- | | MAX_ACTIVE_SCANS | Max number of scans a client may have active at once. | | WebsiteTalkProduct.activeScanIds | Optional scan id list backing search, alongside the legacy singular activeScanId. | | WebsiteTalkProduct.primaryScanId | Optional single scan id whose content seeds the phone call's opening description. | | getActiveScanIds(clientId) | Returns activeScanIds, falling back to wrapping the legacy activeScanId when the list is absent. | | addActiveScanId(clientId, scanId) | Adds a scan to the active list; throws once MAX_ACTIVE_SCANS is reached. | | removeActiveScanId(clientId, scanId) | Removes a scan from the active list; also clears the legacy singular field when it matches. | | getPrimaryScanId / setPrimaryScanId / clearPrimaryScanId | Read/set/clear the primary scan id. |

Do I need to update my app?

No — purely additive, and getActiveScanIds keeps working for clients still on the legacy singular activeScanId. WTIS should upgrade to 1.3.39 to use the new multi-scan getters.

1.3.40 — Live scan progress (CP-1527)

Adds the scanResources module so WebsiteTalk can show live per-page scan progress. Use getScanKpiCounts for status totals while a scan is running (do not use Scan.pagesCompleted / related fields for live UI — those are a finalize-only snapshot), getScanPages for a cursor-paginated board column, and getScanResourceById for page detail. Scan also gains optional terminal fields (startedAt, completedAt, pagesCompleted, pagesFailedPermanent, pagesDuplicate) written once when the scan finishes.

1.3.47 — Account owner email for WebsiteTalk (CP-1715)

Adds an optional accountOwnerEmail field to WebsiteTalkProduct, used by the new end-of-call summary email feature: the recipient is filled in once from the client's login email and can be edited afterward in Settings.

Added

| Export | Purpose | | --- | --- | | WebsiteTalkProduct.accountOwnerEmail | Optional email address that receives the end-of-call summary email. |

Do I need to update my app?

No — purely additive.

1.3.48 — Fix getScanPages search regex escaping (CP-1726)

getScanPages passed the raw search string straight into MongoDB's $regex without escaping. Regex-special characters in the input (most commonly ? in a URL's query string) changed the meaning of the pattern instead of matching literally, so searching for a URL/title containing one returned zero results even though the document existed and was fully processed.

Fixed

| Area | What | | --- | --- | | getScanPages (scanResources.getters.ts) | Search input is now escaped via the new escapeRegex() helper (scanResources.utils.ts) before being used in the url/title $regex filter. Plain-text searches are unaffected. |

Do I need to update my app?

No API changes. WTIS (the only current consumer of getScanPages) should upgrade to 1.3.48 or later to pick up the fix.

1.3.57 — Phone-number bind getters

TalkPilot can bind any owned number to a flow without querying Mongo in the service layer. flow_id is matched as ObjectId or as a leftover string.

Added

| Export | Purpose | | --- | --- | | getClientByClientId(clientId) | Fetch a client by clientId. | | findPhoneNumbersByClientId(clientId) | All phone_numbers for a client. | | getOwnedPhoneNumber(clientId, phoneNumber) | One number that belongs to the client, or null. | | getPhoneNumberByClientAndFlow(clientId, flowId) | Number bound to that flow for that client. | | clearPhoneNumberFlow(clientId, phoneNumber) | Unset flow_id on one number. | | assignExclusiveFlow(clientId, phoneNumber, flowId) | Bind the number and clear the same flow on the client's other numbers. | | unbindFlowFromClientNumbers(clientId, flowId) | Unset flow_id on every number of that client pointing at the flow. |

Do I need to update my app?

No — purely additive. TalkPilot Server should upgrade to 1.3.57 for multi-number bind/list.

1.3.61 — WebsiteTalk active flow (CP-1849)

Optional activeFlowId on WebsiteTalkProduct. WTIS reads this field when it updates the call script, instead of the flow attached to a phone number.

Added

| Field | Purpose | | --- | --- | | WebsiteTalkProduct.activeFlowId | TalkPilot flow id edited by Update flow. |

Do I need to update my app?

No — the field is optional. WTIS should upgrade to 1.3.61 so the call-script update can use it.

1.3.71 — Who ended the call (CP-1873)

Records who ended a connected call. Unset for calls that never connected (busy, no-answer) and for calls moved to a conference.

Added

| Item | Purpose | | --- | --- | | Call.endedBy | system (our platform, e.g. silence timeout), agent (the bot ended the flow) or user (the caller hung up). | | CallEndedByValues / CallEndedBy | Const object and the type derived from it, same pattern as CallStatusValues. | | setCallEndedBy(callSid, endedBy) | Writes only if endedBy is not set yet; returns true when this call wrote it. |

endedBy is not part of CallUpdateParams, so updateCallByCallSid cannot overwrite it.

Do I need to update my app?

TalkPilot Server must upgrade to 1.3.71 to write the field. 1.3.69–1.3.70 used resident instead of user — don't use them.

1.3.74 — Human agent ended the call (CP-1873)

New CallEndedByValues.Human ("human"): a human agent ended the call, either after a transfer or in a conference.

Do I need to update my app?

No — purely additive. TalkPilot Server should upgrade to 1.3.74 to write it.

1.3.85 — Single context-note writes (CP-1998)

Append, update, or remove one note on a client/product document without replacing the rest of the notes array. appendContextNoteEntry creates the document when none exists yet. setContextNoteEntries still replaces the whole list.

Added

| Export | Purpose | | --- | --- | | ContextNoteEntryWrite | Fields the caller sets: title, content, activeFrom, expiresAt. The getter assigns _id, createdAt, and updatedAt. | | appendContextNoteEntry(clientId, product, entry, now?) | Pushes one note and upserts the document. Returns the stored entry. | | updateContextNoteEntryFields(clientId, product, noteId, entry, now?) | Replaces one note's writable fields and updatedAt. Leaves createdAt and the other notes alone. Returns null when the note is missing. | | pullContextNoteEntry(clientId, product, noteId) | Removes one note by id. Returns false when nothing changed. |

Do I need to update my app?

No — purely additive. Use these instead of setContextNoteEntries when only one note changes.

🛠 CI/CD & deployment

• This package is consumed by Cloud Build-based services (TalkPilot Server, MIS, CIS) as a dependency when Docker images are built. Keep dist/ in sync with your builds because the compiled artifact is what downstream services install.
• Releases require the shared npm token documented in DEVELOPMENT.md; consult that guide for contribution, linking, and token rotation procedures.

Resources

• DEVELOPMENT.md (setup, tooling, publishing, token management)
• src/test-utils and the __tests__ folder for examples of MongoMemoryServer wiring.