@kelpie/server 0.8.0 → 0.9.0

package/src/modules/partnerships/service.ts

@@ -1,3 +1,5 @@
+import type { CustomFieldWireValue } from '@kelpie/schemas'
+
 import { changedKeys } from '../../lib/changes.ts'
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
@@ -20,6 +22,8 @@ import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as companyRepository from '../companies/repository.ts'
+import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
+import * as personLinks from '../personLinks.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
 import type { PipelineStageRecord } from '../pipelines/repository.ts'
 import * as repository from './repository.ts'
@@ -30,7 +34,7 @@ import type { PartnershipFilters, PartnershipRecord } from './repository.ts'
  * Partnerships: ongoing two-way relationships. Status is a stage of the
  * `partnership` pipeline; there is no favour ledger (`brief.md` non-goal).
  *
- * Key people attach through `partnership_people` and appear as `person_ids` on
+ * Key people attach through `person_links` and appear as `person_ids` on
  * the wire, the Deals mechanics; kind is free text, the Opportunities mechanics.
  * A stage move is an ordinary PATCH of `stage_id`, and it is the one change that
  * files a `stage_changed` activity and a `stage.changed` event instead of the
@@ -43,6 +47,7 @@ export interface PartnershipsDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
 }
 
 /** What a changed column is called on a timeline. `successLooksLike` is why these are written out. */
@@ -81,6 +86,8 @@ export interface CreatePartnershipInput {
   readonly personIds: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** Wire shape for a create body: `null` values are ignored, non-null are validated. */
+  readonly customFields: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 /** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
@@ -97,6 +104,11 @@ export interface UpdatePartnershipInput {
   readonly personIds?: readonly string[] | undefined
   readonly summary?: string | undefined
   readonly tags?: readonly string[] | undefined
+  /**
+   * Partial merge patch (wire shape): sent keys change, `null` clears a key,
+   * absent keys are left alone. Unknown keys are `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 export interface PartnershipsService {
@@ -208,7 +220,7 @@ export function createPartnershipsService(
     workspaceId: string,
     personIds: readonly string[],
   ): Promise<ReadonlyMap<string, string>> {
-    const named = await repository.findPeopleNamed(dependencies.db, workspaceId, personIds)
+    const named = await personLinks.findPeopleNamed(dependencies.db, workspaceId, personIds)
     const missing = personIds.filter((id) => !named.has(id))
 
     if (missing.length > 0) {
@@ -223,9 +235,14 @@ export function createPartnershipsService(
   }
 
   /** @returns The page's views, with every partnership's people fetched in one query. */
-  async function toViews(records: readonly PartnershipRecord[]): Promise<PartnershipView[]> {
-    const peopleByPartnership = await repository.listPersonIdsFor(
+  async function toViews(
+    workspaceId: string,
+    records: readonly PartnershipRecord[],
+  ): Promise<PartnershipView[]> {
+    const peopleByPartnership = await personLinks.listPersonIdsFor(
       dependencies.db,
+      workspaceId,
+      'partnership',
       records.map((record) => record.id),
     )
 
@@ -239,14 +256,20 @@ export function createPartnershipsService(
       const rows = await repository.listPartnerships(dependencies.db, workspaceId, filters, window)
       const page = toPage(rows, window, (partnership) => partnership.id)
 
-      return { items: await toViews(page.items), nextCursor: page.nextCursor }
+      return { items: await toViews(workspaceId, page.items), nextCursor: page.nextCursor }
     },
 
     async get(actor, id) {
       const workspaceId = requireWorkspaceId(actor)
       const partnership = await require(workspaceId, id)
 
-      return toView(partnership, await repository.listPersonIds(dependencies.db, id))
+      return toView(
+        partnership,
+        await personLinks.listPersonIds(dependencies.db, workspaceId, {
+          targetType: 'partnership',
+          targetId: id,
+        }),
+      )
     },
 
     async create(actor, input) {
@@ -269,6 +292,12 @@ export function createPartnershipsService(
       const id = dependencies.createId('partnership')
 
       return dependencies.transaction(async ({ tx, events }) => {
+        const customFields = await dependencies.customFields.forCreate(
+          tx,
+          workspaceId,
+          'partnership',
+          input.customFields,
+        )
         const created = await repository.insertPartnership(tx, {
           id,
           workspaceId,
@@ -282,9 +311,16 @@ export function createPartnershipsService(
           successLooksLike: input.successLooksLike,
           summary: input.summary,
           tags: [...input.tags],
+          customFields,
         })
 
-        await repository.insertPartnershipPeople(tx, id, personIds)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'partnership', targetId: id },
+          personIds,
+        )
 
         await dependencies.recordActivity(tx, workspaceId, actor, {
           targetType: 'partnership',
@@ -329,7 +365,10 @@ export function createPartnershipsService(
         await requireOwner(workspaceId, changes.ownerId)
       }
 
-      const currentPeople = await repository.listPersonIds(dependencies.db, id)
+      const currentPeople = await personLinks.listPersonIds(dependencies.db, workspaceId, {
+        targetType: 'partnership',
+        targetId: id,
+      })
       const nextPeople =
         changes.personIds === undefined ? undefined : [...new Set(changes.personIds)]
       const added =
@@ -343,16 +382,26 @@ export function createPartnershipsService(
       const named = await requirePeople(workspaceId, [...added, ...removed])
 
       const columns = toStoredColumns(changes)
-      const changed = changedKeys(existing, columns)
+      const scalarChanged = changedKeys(existing, columns)
       const linksChanged = added.length > 0 || removed.length > 0
 
-      if (changed.length === 0 && !linksChanged) {
-        return toView(existing, currentPeople)
-      }
-
       return dependencies.transaction(async ({ tx, events }) => {
+        const cf = await dependencies.customFields.forUpdate(
+          tx,
+          workspaceId,
+          'partnership',
+          existing.customFields,
+          changes.customFields,
+        )
+        const customFieldsChanged = cf !== undefined && cf.changedPaths.length > 0
+
+        if (scalarChanged.length === 0 && !linksChanged && !customFieldsChanged) {
+          return toView(existing, currentPeople)
+        }
+
         const updated = await repository.updatePartnership(tx, workspaceId, id, {
           ...columns,
+          ...(customFieldsChanged ? { customFields: cf.merged } : {}),
           updatedAt: dependencies.now(),
         })
 
@@ -360,8 +409,19 @@ export function createPartnershipsService(
           throw AppError.notFound('Partnership not found')
         }
 
-        await repository.insertPartnershipPeople(tx, id, added)
-        await repository.deletePartnershipPeople(tx, id, removed)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'partnership', targetId: id },
+          added,
+        )
+        await personLinks.unlinkPeople(
+          tx,
+          workspaceId,
+          { targetType: 'partnership', targetId: id },
+          removed,
+        )
 
         if (stageMove !== undefined) {
           await dependencies.recordActivity(tx, workspaceId, actor, {
@@ -372,14 +432,19 @@ export function createPartnershipsService(
           })
         }
 
-        const otherChanged = changed.filter((field) => field !== 'stageId')
+        const otherChanged = scalarChanged.filter((field) => field !== 'stageId')
+        const customFieldPaths = cf?.changedPaths ?? []
+        const activityChanged = [...otherChanged, ...customFieldPaths]
 
-        if (otherChanged.length > 0) {
+        if (activityChanged.length > 0) {
+          const labels: Record<string, string> = { ...PARTNERSHIP_FIELD_LABELS, ...cf?.labels }
+          const before: Record<string, unknown> = { ...existing, ...cf?.flatBefore }
+          const after: Record<string, unknown> = { ...columns, ...cf?.flatAfter }
           await dependencies.recordActivity(tx, workspaceId, actor, {
             targetType: 'partnership',
             targetId: id,
             kind: 'updated',
-            ...describeUpdate(otherChanged, PARTNERSHIP_FIELD_LABELS, existing, columns),
+            ...describeUpdate(activityChanged, labels, before, after),
           })
         }
 
@@ -407,7 +472,13 @@ export function createPartnershipsService(
         events.emit(
           'partnerships.partnership.updated',
           { type: 'partnership', id },
-          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+          {
+            changed: [
+              ...scalarChanged,
+              ...(linksChanged ? ['personIds'] : []),
+              ...customFieldPaths,
+            ],
+          },
         )
 
         if (stageMove !== undefined) {
@@ -428,9 +499,9 @@ export function createPartnershipsService(
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
-        // `partnership_people` dies with the partnership through its foreign key;
-        // notes, activities, decisions and plan items have no key, so they are
-        // removed here, in the same transaction.
+        // Notes, activities, decisions, plan items, and person_links have no
+        // key back to the partnership, so they are removed here, in the same
+        // transaction.
         await deleteRecordsAttachedTo(tx, workspaceId, 'partnership', id)
         await repository.deletePartnership(tx, workspaceId, id)
 

package/src/modules/people/consentHydration.ts

@@ -0,0 +1,167 @@
+import type { ConsentPurposeStatus } from '@kelpie/schemas'
+import { and, asc, eq, inArray } from 'drizzle-orm'
+
+import type { Queryable } from '../../runtime/transaction.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
+import { personConsents } from './schema.ts'
+
+/**
+ * Merges a workspace's consent purposes with any explicit `person_consents`
+ * rows into the effective status agents and humans read on a Person.
+ *
+ * The rule is simple: an explicit row wins; absence means "inherits the
+ * purpose's `default_status`". This helper does the join and the merge in one
+ * place so every read of a Person resolves it the same way.
+ */
+
+export interface EffectiveConsent {
+  readonly purposeSlug: string
+  readonly purposeLabel: string
+  readonly status: ConsentPurposeStatus
+  readonly source: string | null
+  readonly notedAt: Date | null
+  readonly inherited: boolean
+}
+
+/** The workspace purposes and any person-level rows, in one shape. */
+interface PurposeRow {
+  readonly id: string
+  readonly slug: string
+  readonly label: string
+  readonly defaultStatus: ConsentPurposeStatus
+  readonly sortOrder: number
+}
+
+interface PersonConsentRow {
+  readonly personId: string
+  readonly purposeId: string
+  readonly status: 'granted' | 'withdrawn'
+  readonly source: string
+  readonly notedAt: Date
+}
+
+async function loadPurposes(
+  db: Queryable,
+  workspaceId: string,
+): Promise<readonly PurposeRow[]> {
+  const rows = await db
+    .select({
+      id: consentPurposes.id,
+      slug: consentPurposes.slug,
+      label: consentPurposes.label,
+      defaultStatus: consentPurposes.defaultStatus,
+      sortOrder: consentPurposes.sortOrder,
+    })
+    .from(consentPurposes)
+    .where(eq(consentPurposes.workspaceId, workspaceId))
+    .orderBy(asc(consentPurposes.sortOrder), asc(consentPurposes.id))
+
+  return rows.map((row) => ({
+    id: row.id,
+    slug: row.slug,
+    label: row.label,
+    defaultStatus: row.defaultStatus as ConsentPurposeStatus,
+    sortOrder: row.sortOrder,
+  }))
+}
+
+async function loadConsentsFor(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<readonly PersonConsentRow[]> {
+  if (personIds.length === 0) return []
+  const rows = await db
+    .select({
+      personId: personConsents.personId,
+      purposeId: personConsents.purposeId,
+      status: personConsents.status,
+      source: personConsents.source,
+      notedAt: personConsents.notedAt,
+    })
+    .from(personConsents)
+    .where(
+      and(
+        eq(personConsents.workspaceId, workspaceId),
+        inArray(personConsents.personId, [...personIds]),
+      ),
+    )
+
+  return rows.map((row) => ({
+    personId: row.personId,
+    purposeId: row.purposeId,
+    status: row.status as 'granted' | 'withdrawn',
+    source: row.source,
+    notedAt: row.notedAt,
+  }))
+}
+
+function mergeFor(
+  purposes: readonly PurposeRow[],
+  explicitByPurpose: ReadonlyMap<string, PersonConsentRow>,
+): readonly EffectiveConsent[] {
+  return purposes.map((purpose) => {
+    const explicit = explicitByPurpose.get(purpose.id)
+    if (explicit === undefined) {
+      return {
+        purposeSlug: purpose.slug,
+        purposeLabel: purpose.label,
+        status: purpose.defaultStatus,
+        source: null,
+        notedAt: null,
+        inherited: true,
+      }
+    }
+    return {
+      purposeSlug: purpose.slug,
+      purposeLabel: purpose.label,
+      status: explicit.status,
+      source: explicit.source,
+      notedAt: explicit.notedAt,
+      inherited: false,
+    }
+  })
+}
+
+/** Consents for one person. */
+export async function readConsentsFor(
+  db: Queryable,
+  workspaceId: string,
+  personId: string,
+): Promise<readonly EffectiveConsent[]> {
+  const [purposes, explicit] = await Promise.all([
+    loadPurposes(db, workspaceId),
+    loadConsentsFor(db, workspaceId, [personId]),
+  ])
+  const byPurpose = new Map(explicit.map((row) => [row.purposeId, row]))
+  return mergeFor(purposes, byPurpose)
+}
+
+/**
+ * Consents for many people. Loads purposes once and person rows once, then
+ * merges in memory — cheaper than a per-row read for a paged list.
+ */
+export async function readConsentsForMany(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<ReadonlyMap<string, readonly EffectiveConsent[]>> {
+  if (personIds.length === 0) return new Map()
+  const [purposes, explicit] = await Promise.all([
+    loadPurposes(db, workspaceId),
+    loadConsentsFor(db, workspaceId, personIds),
+  ])
+
+  const byPerson = new Map<string, Map<string, PersonConsentRow>>()
+  for (const row of explicit) {
+    const map = byPerson.get(row.personId) ?? new Map<string, PersonConsentRow>()
+    map.set(row.purposeId, row)
+    byPerson.set(row.personId, map)
+  }
+
+  const out = new Map<string, readonly EffectiveConsent[]>()
+  for (const personId of personIds) {
+    out.set(personId, mergeFor(purposes, byPerson.get(personId) ?? new Map()))
+  }
+  return out
+}

package/src/modules/people/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { createCustomFieldValues } from '../custom-fields/index.ts'
 import { peopleEvents } from './events.ts'
 import { mountPeopleRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -15,7 +16,7 @@ import { registerPeopleTools } from './tools.ts'
 export function createPeopleModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'people',
-    requires: ['workspace', 'activities'],
+    requires: ['workspace', 'activities', 'custom-fields'],
     structural: true,
     events: peopleEvents,
 
@@ -29,6 +30,7 @@ export function createPeopleModule(migrationsDirectory: string): KelpieModule {
           createId: context.createId,
           now: context.now,
         }),
+        customFields: createCustomFieldValues({ db: context.db }),
       })
 
       context.schema(schema, migrationsDirectory)

package/src/modules/people/personConsentWrites.ts

@@ -0,0 +1,177 @@
+import type { ConsentStatus } from '@kelpie/schemas'
+import { and, eq, inArray } from 'drizzle-orm'
+
+import { AppError } from '../../lib/errors.ts'
+import type { Transaction } from '../../runtime/transaction.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
+import { personConsents } from './schema.ts'
+
+/**
+ * Writes to `person_consents`, shared by the manual PATCH override and every
+ * capture site (forms, lists, imports). Every write is idempotent — a second
+ * grant for the same (person, purpose) with the same source is a no-op.
+ *
+ * `source` follows the shape in `docs/privacy.md`:
+ * `form:<form_id>` | `list:<list_id>` | `import` | `manual`.
+ */
+
+export interface ConsentWriteChange {
+  readonly purposeSlug: string
+  readonly purposeLabel: string
+  readonly status: ConsentStatus | null
+  readonly previousStatus: ConsentStatus | null
+}
+
+export interface ConsentWriteInput {
+  readonly purposeSlug: string
+  readonly status: ConsentStatus | null
+}
+
+interface PurposeRow {
+  readonly id: string
+  readonly slug: string
+  readonly label: string
+}
+
+async function resolvePurposesBySlug(
+  tx: Transaction,
+  workspaceId: string,
+  slugs: readonly string[],
+): Promise<ReadonlyMap<string, PurposeRow>> {
+  if (slugs.length === 0) return new Map()
+  const rows = await tx
+    .select({
+      id: consentPurposes.id,
+      slug: consentPurposes.slug,
+      label: consentPurposes.label,
+    })
+    .from(consentPurposes)
+    .where(
+      and(
+        eq(consentPurposes.workspaceId, workspaceId),
+        inArray(consentPurposes.slug, [...slugs]),
+      ),
+    )
+  return new Map(rows.map((row) => [row.slug, row]))
+}
+
+/**
+ * Applies one `PersonConsent` write. `status: null` deletes the row (falls
+ * back to the purpose default); any other status upserts it.
+ *
+ * @returns The change that landed — with the previous status so a caller can
+ *   file a "no change" as a no-op activity.
+ */
+export async function upsertPersonConsent(
+  tx: Transaction,
+  workspaceId: string,
+  personId: string,
+  purposeId: string,
+  purposeSlug: string,
+  purposeLabel: string,
+  status: ConsentStatus | null,
+  source: string,
+  now: Date,
+): Promise<ConsentWriteChange> {
+  const [existing] = await tx
+    .select({ status: personConsents.status })
+    .from(personConsents)
+    .where(
+      and(eq(personConsents.personId, personId), eq(personConsents.purposeId, purposeId)),
+    )
+    .limit(1)
+
+  const previousStatus = (existing?.status ?? null) as ConsentStatus | null
+
+  if (status === null) {
+    if (existing !== undefined) {
+      await tx
+        .delete(personConsents)
+        .where(
+          and(eq(personConsents.personId, personId), eq(personConsents.purposeId, purposeId)),
+        )
+    }
+    return { purposeSlug, purposeLabel, status: null, previousStatus }
+  }
+
+  await tx
+    .insert(personConsents)
+    .values({
+      workspaceId,
+      personId,
+      purposeId,
+      status,
+      notedAt: now,
+      source,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [personConsents.personId, personConsents.purposeId],
+      set: {
+        status,
+        notedAt: now,
+        source,
+        updatedAt: now,
+      },
+    })
+
+  return { purposeSlug, purposeLabel, status, previousStatus }
+}
+
+/**
+ * Reads by slug for a manual PATCH: resolves each named purpose to its id,
+ * refuses an unknown slug with a `422`, and applies the writes. Every write
+ * ridden through here uses `source: 'manual'`.
+ */
+export async function applyManualConsentWrites(
+  tx: Transaction,
+  workspaceId: string,
+  personId: string,
+  writes: readonly ConsentWriteInput[],
+  now: Date,
+): Promise<readonly ConsentWriteChange[]> {
+  if (writes.length === 0) return []
+  const slugs = writes.map((write) => write.purposeSlug)
+  const purposesBySlug = await resolvePurposesBySlug(tx, workspaceId, slugs)
+
+  const missing = slugs.filter((slug) => !purposesBySlug.has(slug))
+  if (missing.length > 0) {
+    throw AppError.validationFailed(
+      'One or more consent purposes were not found in this workspace',
+      missing.map((slug) => ({
+        field: `consents.${slug}`,
+        message: `Unknown consent purpose "${slug}"`,
+      })),
+    )
+  }
+
+  const changes: ConsentWriteChange[] = []
+  for (const write of writes) {
+    const purpose = purposesBySlug.get(write.purposeSlug)
+    if (purpose === undefined) continue // impossible after the check above
+    const change = await upsertPersonConsent(
+      tx,
+      workspaceId,
+      personId,
+      purpose.id,
+      purpose.slug,
+      purpose.label,
+      write.status,
+      'manual',
+      now,
+    )
+    changes.push(change)
+  }
+  return changes
+}
+
+/**
+ * The `changed` paths a person update event emits for consent writes. Names
+ * every purpose that actually moved, shaped as `consents.<slug>`.
+ */
+export function consentChangedPaths(changes: readonly ConsentWriteChange[]): readonly string[] {
+  return changes
+    .filter((change) => change.status !== change.previousStatus)
+    .map((change) => `consents.${change.purposeSlug}`)
+}
+

package/src/modules/people/repository.ts

@@ -66,6 +66,11 @@ function matchesTerm(term: string): SQL | undefined {
 
   return or(
     ilike(people.name, pattern),
+    // The same two parts `search_vector` carries, so filtering this list and
+    // searching the workspace find a person by their surname alike. Salutation
+    // and suffix are in neither: "Dr" matches half a workspace.
+    ilike(people.firstName, pattern),
+    ilike(people.lastName, pattern),
     ilike(people.email, pattern),
     ilike(people.summary, pattern),
     arrayContainsPattern(people.tags, pattern),