@kelpie/server 0.8.0 → 0.9.0

package/src/modules/people/service.ts

@@ -1,3 +1,5 @@
+import type { ConsentStatus, CustomFieldWireValue } from '@kelpie/schemas'
+
 import { changedKeys } from '../../lib/changes.ts'
 import { UNIQUE_VIOLATION, isReferenceViolation, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
@@ -19,11 +21,17 @@ import {
   deleteRecordsAttachedTo,
   deleteRecordsAttachedToCandidaciesOf,
 } from '../attachedRecords.ts'
-import { referencedElsewhere } from '../references.ts'
+import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
+import * as personLinks from '../personLinks.ts'
+import { referenceViolationTable } from '../../lib/database.ts'
+import { referencedByPipelineRecords, referencedElsewhere } from '../references.ts'
 import * as repository from './repository.ts'
 import { DEFAULT_PERSON_SORT, PERSON_SORTS } from './repository.ts'
 import type { PersonFilters, PersonRecord } from './repository.ts'
 import type { Influence, PreferredChannel, Relationship, SocialProfile } from './schema.ts'
+import { readConsentsFor, readConsentsForMany } from './consentHydration.ts'
+import type { EffectiveConsent } from './consentHydration.ts'
+import { applyManualConsentWrites, consentChangedPaths } from './personConsentWrites.ts'
 
 /**
  * People: who the workspace knows.
@@ -41,6 +49,7 @@ export interface PeopleDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
 }
 
 /**
@@ -52,6 +61,10 @@ export interface PeopleDependencies {
  */
 const PERSON_FIELD_LABELS: FieldLabels = {
   name: 'Name',
+  salutation: 'Salutation',
+  firstName: 'First name',
+  lastName: 'Last name',
+  suffix: 'Suffix',
   email: 'Email',
   phones: 'Phone numbers',
   socialProfiles: 'Social profiles',
@@ -63,6 +76,7 @@ const PERSON_FIELD_LABELS: FieldLabels = {
   summary: 'Summary',
   tags: 'Tags',
   lastContactedAt: 'Last contacted',
+  doNotContact: 'Do not contact',
 }
 
 /**
@@ -71,10 +85,27 @@ const PERSON_FIELD_LABELS: FieldLabels = {
  * Deliberately an alias rather than a parallel interface. A hand-written copy of
  * fifteen fields drifts from the table the first time one is added.
  */
-export type PersonView = Omit<PersonRecord, 'workspaceId'>
+export type PersonView = Omit<PersonRecord, 'workspaceId'> & {
+  /**
+   * The effective consent status for every workspace purpose. An entry with
+   * `inherited: true` has no explicit `person_consents` row and carries the
+   * purpose's `default_status`; the rest have their own row.
+   */
+  readonly consents: readonly EffectiveConsent[]
+}
+
+export interface PersonConsentWriteInput {
+  readonly purposeSlug: string
+  readonly status: ConsentStatus | null
+}
 
 export interface CreatePersonInput {
+  /** Already resolved. The route composes one from the parts when the caller sent none. */
   readonly name: string
+  readonly salutation: string | null
+  readonly firstName: string | null
+  readonly lastName: string | null
+  readonly suffix: string | null
   readonly email: string | null
   readonly phones: readonly string[]
   readonly socialProfiles: readonly SocialProfile[]
@@ -86,6 +117,15 @@ export interface CreatePersonInput {
   readonly summary: string
   readonly tags: readonly string[]
   readonly lastContactedAt: Date | null
+  readonly doNotContact: boolean
+  /**
+   * Consent writes for named purposes. `status: null` deletes the row and
+   * inherits the purpose default; anything else upserts `source: manual`.
+   * Absent purposes are left alone.
+   */
+  readonly consents: readonly PersonConsentWriteInput[]
+  /** Wire shape merge patch (undefined for a create without any): sent keys change, null clears. */
+  readonly customFields: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 /** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
@@ -99,10 +139,10 @@ export interface PeopleService {
   remove(actor: Actor, id: string): Promise<void>
 }
 
-function toView(record: PersonRecord): PersonView {
+function toView(record: PersonRecord, consents: readonly EffectiveConsent[]): PersonView {
   const { workspaceId: _workspaceId, ...view } = record
 
-  return view
+  return { ...view, consents }
 }
 
 /**
@@ -113,6 +153,10 @@ function toView(record: PersonRecord): PersonView {
 function toStoredColumns(input: UpdatePersonInput): Partial<repository.PersonColumns> {
   return {
     ...(input.name === undefined ? {} : { name: input.name }),
+    ...(input.salutation === undefined ? {} : { salutation: input.salutation }),
+    ...(input.firstName === undefined ? {} : { firstName: input.firstName }),
+    ...(input.lastName === undefined ? {} : { lastName: input.lastName }),
+    ...(input.suffix === undefined ? {} : { suffix: input.suffix }),
     ...(input.email === undefined ? {} : { email: input.email === null ? null : normaliseEmail(input.email) }),
     ...(input.phones === undefined ? {} : { phones: input.phones }),
     ...(input.socialProfiles === undefined ? {} : { socialProfiles: input.socialProfiles }),
@@ -124,6 +168,7 @@ function toStoredColumns(input: UpdatePersonInput): Partial<repository.PersonCol
     ...(input.summary === undefined ? {} : { summary: input.summary }),
     ...(input.tags === undefined ? {} : { tags: [...input.tags] }),
     ...(input.lastContactedAt === undefined ? {} : { lastContactedAt: input.lastContactedAt }),
+    ...(input.doNotContact === undefined ? {} : { doNotContact: input.doNotContact }),
   }
 }
 
@@ -151,12 +196,22 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
       const workspaceId = requireWorkspaceId(actor)
       const window = readListWindow(query, PERSON_SORTS, DEFAULT_PERSON_SORT)
       const rows = await repository.listPeople(dependencies.db, workspaceId, filters, window)
+      const consentsByPerson = await readConsentsForMany(
+        dependencies.db,
+        workspaceId,
+        rows.map((row) => row.id),
+      )
 
-      return mapPage(toPage(rows, window, (person) => person.id), toView)
+      return mapPage(toPage(rows, window, (person) => person.id), (record) =>
+        toView(record, consentsByPerson.get(record.id) ?? []),
+      )
     },
 
     async get(actor, id) {
-      return toView(await require(requireWorkspaceId(actor), id))
+      const workspaceId = requireWorkspaceId(actor)
+      const record = await require(workspaceId, id)
+      const consents = await readConsentsFor(dependencies.db, workspaceId, id)
+      return toView(record, consents)
     },
 
     async create(actor, input) {
@@ -165,6 +220,12 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
 
       return dependencies.transaction(
         async ({ tx, events }) => {
+          const customFields = await dependencies.customFields.forCreate(
+            tx,
+            workspaceId,
+            'person',
+            input.customFields,
+          )
           let created: PersonRecord
 
           try {
@@ -172,6 +233,10 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
               id,
               workspaceId,
               name: input.name,
+              salutation: input.salutation,
+              firstName: input.firstName,
+              lastName: input.lastName,
+              suffix: input.suffix,
               email: input.email === null ? null : normaliseEmail(input.email),
               phones: input.phones,
               socialProfiles: input.socialProfiles,
@@ -183,6 +248,8 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
               summary: input.summary,
               tags: [...input.tags],
               lastContactedAt: input.lastContactedAt,
+              doNotContact: input.doNotContact,
+              customFields,
             })
           } catch (error: unknown) {
             if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
@@ -192,6 +259,16 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
             throw error
           }
 
+          if (input.consents.length > 0) {
+            await applyManualConsentWrites(
+              tx,
+              workspaceId,
+              created.id,
+              input.consents,
+              dependencies.now(),
+            )
+          }
+
           await dependencies.recordActivity(tx, workspaceId, actor, {
             targetType: 'person',
             targetId: created.id,
@@ -210,7 +287,8 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
             recordActivity: dependencies.recordActivity,
           })
 
-          return toView(created)
+          const consents = await readConsentsFor(tx, workspaceId, created.id)
+          return toView(created, consents)
         },
         { workspaceId, actor: toEventActor(actor) },
       )
@@ -220,52 +298,100 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
       const workspaceId = requireWorkspaceId(actor)
       const existing = await require(workspaceId, id)
       const columns = toStoredColumns(changes)
-      const changed = changedKeys(existing, columns)
-
-      // A PATCH that changes nothing is not a write. Bumping `updated_at` for it
-      // would make the record look freshly touched to everything that sorts or
-      // filters by it.
-      if (changed.length === 0) {
-        return toView(existing)
-      }
+      const scalarChanged = changedKeys(existing, columns)
+      const consentWrites = changes.consents ?? []
 
       return dependencies.transaction(
         async ({ tx, events }) => {
+          const cf = await dependencies.customFields.forUpdate(
+            tx,
+            workspaceId,
+            'person',
+            existing.customFields,
+            changes.customFields,
+          )
+          const customFieldsChanged = cf !== undefined && cf.changedPaths.length > 0
+
+          const consentChanges =
+            consentWrites.length > 0
+              ? await applyManualConsentWrites(
+                  tx,
+                  workspaceId,
+                  id,
+                  consentWrites,
+                  dependencies.now(),
+                )
+              : []
+          const consentPaths = consentChangedPaths(consentChanges)
+          const consentActuallyChanged = consentPaths.length > 0
+
+          // A PATCH that changes nothing is not a write. Bumping `updated_at`
+          // would make the record look freshly touched to everything that sorts
+          // or filters by it.
+          if (
+            scalarChanged.length === 0 &&
+            !customFieldsChanged &&
+            !consentActuallyChanged
+          ) {
+            const consents = await readConsentsFor(tx, workspaceId, id)
+            return toView(existing, consents)
+          }
+
           let updated: PersonRecord | undefined
 
-          try {
-            updated = await repository.updatePerson(tx, workspaceId, id, {
-              ...columns,
-              updatedAt: dependencies.now(),
-            })
-          } catch (error: unknown) {
-            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
-              throw duplicateEmail()
+          if (scalarChanged.length > 0 || customFieldsChanged) {
+            try {
+              updated = await repository.updatePerson(tx, workspaceId, id, {
+                ...columns,
+                ...(customFieldsChanged ? { customFields: cf.merged } : {}),
+                updatedAt: dependencies.now(),
+              })
+            } catch (error: unknown) {
+              if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+                throw duplicateEmail()
+              }
+
+              throw error
             }
 
-            throw error
+            if (updated === undefined) {
+              throw AppError.notFound('Person not found')
+            }
+          } else {
+            updated = existing
           }
 
-          if (updated === undefined) {
-            throw AppError.notFound('Person not found')
-          }
+          const customFieldPaths = cf?.changedPaths ?? []
+          const activityChanged = [...scalarChanged, ...customFieldPaths, ...consentPaths]
 
-          await dependencies.recordActivity(tx, workspaceId, actor, {
-            targetType: 'person',
-            targetId: id,
-            kind: 'updated',
-            ...describeUpdate(changed, PERSON_FIELD_LABELS, existing, columns),
-          })
+          if (activityChanged.length > 0) {
+            const labels: Record<string, string> = { ...PERSON_FIELD_LABELS, ...cf?.labels }
+            for (const change of consentChanges) {
+              labels[`consents.${change.purposeSlug}`] = `Consent · ${change.purposeLabel}`
+            }
+            const before: Record<string, unknown> = { ...existing, ...cf?.flatBefore }
+            const after: Record<string, unknown> = { ...columns, ...cf?.flatAfter }
+            for (const change of consentChanges) {
+              before[`consents.${change.purposeSlug}`] = change.previousStatus ?? 'inherits'
+              after[`consents.${change.purposeSlug}`] = change.status ?? 'inherits'
+            }
+            await dependencies.recordActivity(tx, workspaceId, actor, {
+              targetType: 'person',
+              targetId: id,
+              kind: 'updated',
+              ...describeUpdate(activityChanged, labels, before, after),
+            })
+          }
 
           events.emit(
             'people.person.updated',
             { type: 'person', id },
-            { changed },
+            { changed: activityChanged },
           )
 
           // Sync auto-link when the email moved. Same-transaction rationale as
           // the create path above.
-          if (changed.includes('email')) {
+          if (scalarChanged.includes('email')) {
             await autoLinkPersonByEmailDomain(tx, events, workspaceId, updated, {
               createId: dependencies.createId,
               now: dependencies.now,
@@ -273,7 +399,8 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
             })
           }
 
-          return toView(updated)
+          const consents = await readConsentsFor(tx, workspaceId, id)
+          return toView(updated, consents)
         },
         { workspaceId, actor: toEventActor(actor) },
       )
@@ -295,14 +422,33 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
           // notes have to be taken here: no hiring service sees that delete.
           await deleteRecordsAttachedToCandidaciesOf(tx, workspaceId, id)
 
+          // A person delete failing on a foreign key aborts the enclosing
+          // transaction, so the follow-up read that names the referring pipeline
+          // types would run against a dead tx. Wrap only the delete in a nested
+          // transaction: drizzle emits SAVEPOINT/ROLLBACK TO for it, so the
+          // outer tx survives the refusal and the listLinkedTargetTypes read
+          // below sees person_links.
+          let deleteError: unknown = null
+
           try {
-            await repository.deletePerson(tx, workspaceId, id)
+            await tx.transaction(async (savepoint) => {
+              await repository.deletePerson(savepoint, workspaceId, id)
+            })
           } catch (error: unknown) {
-            if (isReferenceViolation(error)) {
-              throw referencedElsewhere(error, 'person')
+            deleteError = error
+          }
+
+          if (deleteError !== null) {
+            if (isReferenceViolation(deleteError)) {
+              if (referenceViolationTable(deleteError) === 'person_links') {
+                const types = await personLinks.listLinkedTargetTypes(tx, workspaceId, id)
+                throw referencedByPipelineRecords('person', types)
+              }
+
+              throw referencedElsewhere(deleteError, 'person')
             }
 
-            throw error
+            throw deleteError
           }
 
           events.emit('people.person.deleted', { type: 'person', id }, {})

package/src/modules/people/tools.ts

@@ -19,7 +19,11 @@ export function registerPeopleTools(mcp: McpToolRegistry, service: PeopleService
   registerCrudTools(mcp, {
     resource: 'people',
     subject: 'person',
-    about: 'Someone the workspace knows. A job title belongs to a position, never to the person.',
+    about:
+      'Someone the workspace knows. A job title belongs to a position, never to the person. ' +
+      'name is the display name every list shows; first_name, last_name, salutation and suffix ' +
+      'are optional parts beside it. A create with no name composes one from first_name and ' +
+      'last_name. Changing a part never rewrites name.',
     service,
     render: personResponse,
     listArgs,

package/src/modules/personLinks.ts

@@ -0,0 +1,278 @@
+import { and, asc, eq, inArray, sql } from 'drizzle-orm'
+import type { AnyPgColumn } from 'drizzle-orm/pg-core'
+import type { PipelineKind } from '@kelpie/schemas'
+
+import type { IdFactory } from '../lib/ids.ts'
+import type { Queryable } from '../runtime/transaction.ts'
+import { people, personLinks } from './people/schema.ts'
+
+/**
+ * Shared reader/writer for `person_links`, the polymorphic table that holds a
+ * person's involvement in a pipeline record. Every deal/opportunity/raise/
+ * partnership service reaches through here rather than owning its own join
+ * table. `personLinks` is defined in `people/schema.ts` because the person
+ * side of the relation is what gives it the real foreign key.
+ *
+ * All functions take the caller's `Queryable` and `workspaceId` so every
+ * query rides the `(workspace_id, target_type, target_id)` index and lands in
+ * whatever transaction the caller opened.
+ */
+
+/**
+ * One target the caller writes to. Kept named rather than positional so
+ * `linkPeople(db, ids, ws, 'deal', dealId, personIds)` cannot swap the last
+ * two arguments silently.
+ */
+export interface PipelineTarget {
+  readonly targetType: PipelineKind
+  readonly targetId: string
+}
+
+/**
+ * The people on one pipeline record, ordered by person_id so a response is
+ * stable across reads. Mirrors the deals repository's old `listPersonIds`.
+ */
+export async function listPersonIds(
+  db: Queryable,
+  workspaceId: string,
+  target: PipelineTarget,
+): Promise<string[]> {
+  const rows = await db
+    .select({ personId: personLinks.personId })
+    .from(personLinks)
+    .where(
+      and(
+        eq(personLinks.workspaceId, workspaceId),
+        eq(personLinks.targetType, target.targetType),
+        eq(personLinks.targetId, target.targetId),
+      ),
+    )
+    .orderBy(asc(personLinks.personId))
+
+  return rows.map((row) => row.personId)
+}
+
+/**
+ * The people on each of a page of pipeline records of one type, in one query
+ * rather than one per row. Ids missing from the map have no people.
+ */
+export async function listPersonIdsFor(
+  db: Queryable,
+  workspaceId: string,
+  targetType: PipelineKind,
+  targetIds: readonly string[],
+): Promise<ReadonlyMap<string, readonly string[]>> {
+  if (targetIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ targetId: personLinks.targetId, personId: personLinks.personId })
+    .from(personLinks)
+    .where(
+      and(
+        eq(personLinks.workspaceId, workspaceId),
+        eq(personLinks.targetType, targetType),
+        inArray(personLinks.targetId, targetIds),
+      ),
+    )
+    .orderBy(asc(personLinks.personId))
+
+  const byTarget = new Map<string, string[]>()
+
+  for (const row of rows) {
+    const existing = byTarget.get(row.targetId)
+
+    if (existing === undefined) {
+      byTarget.set(row.targetId, [row.personId])
+    } else {
+      existing.push(row.personId)
+    }
+  }
+
+  return byTarget
+}
+
+/**
+ * Every pipeline record a person is on, in one query. Used by the person
+ * activity roll-up and the agent-tasks person case, which used to run one
+ * query per join table.
+ */
+export async function listTargetsOfPerson(
+  db: Queryable,
+  workspaceId: string,
+  personId: string,
+): Promise<readonly PipelineTarget[]> {
+  const rows = await db
+    .select({ targetType: personLinks.targetType, targetId: personLinks.targetId })
+    .from(personLinks)
+    .where(and(eq(personLinks.workspaceId, workspaceId), eq(personLinks.personId, personId)))
+
+  return rows.map((row) => ({
+    targetType: row.targetType as PipelineKind,
+    targetId: row.targetId,
+  }))
+}
+
+/**
+ * The distinct target types still pointing at a person. Used by the 409 on
+ * person delete to name each pipeline the person is on, without loading every
+ * row.
+ */
+export async function listLinkedTargetTypes(
+  db: Queryable,
+  workspaceId: string,
+  personId: string,
+): Promise<readonly PipelineKind[]> {
+  const rows = await db
+    .selectDistinct({ targetType: personLinks.targetType })
+    .from(personLinks)
+    .where(and(eq(personLinks.workspaceId, workspaceId), eq(personLinks.personId, personId)))
+
+  return rows.map((row) => row.targetType as PipelineKind)
+}
+
+/** Bulk insert; callers pre-dedupe as today. No-op on empty. */
+export async function linkPeople(
+  db: Queryable,
+  createId: IdFactory,
+  workspaceId: string,
+  target: PipelineTarget,
+  personIds: readonly string[],
+): Promise<void> {
+  if (personIds.length === 0) {
+    return
+  }
+
+  await db.insert(personLinks).values(
+    personIds.map((personId) => ({
+      id: createId('personLink'),
+      workspaceId,
+      personId,
+      targetType: target.targetType,
+      targetId: target.targetId,
+    })),
+  )
+}
+
+/** Bulk delete matching a set of people. No-op on empty. */
+export async function unlinkPeople(
+  db: Queryable,
+  workspaceId: string,
+  target: PipelineTarget,
+  personIds: readonly string[],
+): Promise<void> {
+  if (personIds.length === 0) {
+    return
+  }
+
+  await db
+    .delete(personLinks)
+    .where(
+      and(
+        eq(personLinks.workspaceId, workspaceId),
+        eq(personLinks.targetType, target.targetType),
+        eq(personLinks.targetId, target.targetId),
+        inArray(personLinks.personId, personIds),
+      ),
+    )
+}
+
+/**
+ * Link one person, skipping if the row already exists. Used by the forms
+ * post-submit actions: a resubmitting visitor does not double-attach.
+ *
+ * @returns `true` when a row was inserted, `false` when the link already existed.
+ */
+export async function linkPersonIfAbsent(
+  db: Queryable,
+  createId: IdFactory,
+  workspaceId: string,
+  target: PipelineTarget,
+  personId: string,
+): Promise<boolean> {
+  const inserted = await db
+    .insert(personLinks)
+    .values({
+      id: createId('personLink'),
+      workspaceId,
+      personId,
+      targetType: target.targetType,
+      targetId: target.targetId,
+    })
+    .onConflictDoNothing({
+      target: [personLinks.personId, personLinks.targetType, personLinks.targetId],
+    })
+    .returning({ id: personLinks.id })
+
+  return inserted.length > 0
+}
+
+/**
+ * Target-side cleanup, called from `attachedRecords.deleteRecordsAttachedTo`
+ * when a pipeline record is deleted.
+ *
+ * @returns the number of rows removed.
+ */
+export async function deleteLinksForTarget(
+  db: Queryable,
+  workspaceId: string,
+  target: PipelineTarget,
+): Promise<number> {
+  const deleted = await db
+    .delete(personLinks)
+    .where(
+      and(
+        eq(personLinks.workspaceId, workspaceId),
+        eq(personLinks.targetType, target.targetType),
+        eq(personLinks.targetId, target.targetId),
+      ),
+    )
+    .returning({ id: personLinks.id })
+
+  return deleted.length
+}
+
+/**
+ * The `?person_id=` exists-subquery SQL builder, correlated on the outer
+ * table's id and workspace columns. Replaces the identical `hasAnyOfPeople`
+ * helpers that used to live in each pipeline module's repository.
+ */
+export function anyPersonLinked(
+  targetType: PipelineKind,
+  targetIdColumn: AnyPgColumn,
+  workspaceIdColumn: AnyPgColumn,
+  personIds: readonly string[],
+): ReturnType<typeof sql> {
+  return sql`exists (
+    select 1
+    from ${personLinks}
+    where ${personLinks.workspaceId} = ${workspaceIdColumn}
+      and ${personLinks.targetType} = ${targetType}
+      and ${personLinks.targetId} = ${targetIdColumn}
+      and ${inArray(personLinks.personId, personIds)}
+  )`
+}
+
+/**
+ * The names of these people in this workspace, keyed by id. Reads the
+ * `people` table because that is where names live; used by every pipeline
+ * service to validate `person_ids` and label the `linked`/`unlinked`
+ * activity. An id missing from the map does not exist in this workspace.
+ */
+export async function findPeopleNamed(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  if (personIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ id: people.id, name: people.name })
+    .from(people)
+    .where(and(eq(people.workspaceId, workspaceId), inArray(people.id, personIds)))
+
+  return new Map(rows.map((row) => [row.id, row.name]))
+}