@kelpie/server 0.7.0 → 0.9.0

package/src/modules/partnerships/routes.ts

@@ -1,3 +1,4 @@
+import { customFieldsPatchShape } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -6,6 +7,7 @@ import { pageBody, readIdFilter, readJsonBody, readListParameters } from '../../
 import type { Actor } from '../auth/actor.ts'
 import { resolveActorFrom } from '../auth/credentials.ts'
 import type { CredentialDependencies } from '../auth/credentials.ts'
+import { renderCustomFieldsForWire } from '../custom-fields/wire.ts'
 import type {
   CreatePartnershipInput,
   PartnershipView,
@@ -28,6 +30,7 @@ const partnershipShape = {
   person_ids: z.array(z.string().min(1)),
   summary: z.string(),
   tags: z.array(z.string().min(1)),
+  custom_fields: customFieldsPatchShape,
 }
 
 /**
@@ -49,6 +52,7 @@ export const createBody = z.strictObject({
   person_ids: partnershipShape.person_ids.default([]),
   summary: partnershipShape.summary.default(''),
   tags: partnershipShape.tags.default([]),
+  custom_fields: partnershipShape.custom_fields.default({}),
 })
 
 export const updateBody = z.strictObject(partnershipShape).partial()
@@ -70,6 +74,7 @@ export function toCreateInput(body: z.infer<typeof createBody>): CreatePartnersh
     personIds: body.person_ids,
     summary: body.summary,
     tags: body.tags,
+    customFields: body.custom_fields,
   }
 }
 
@@ -88,6 +93,7 @@ export function toUpdateInput(body: z.infer<typeof updateBody>): UpdatePartnersh
     ...(body.person_ids === undefined ? {} : { personIds: body.person_ids }),
     ...(body.summary === undefined ? {} : { summary: body.summary }),
     ...(body.tags === undefined ? {} : { tags: body.tags }),
+    ...(body.custom_fields === undefined ? {} : { customFields: body.custom_fields }),
   }
 }
 
@@ -105,6 +111,7 @@ export function partnershipResponse(partnership: PartnershipView): Record<string
     person_ids: partnership.personIds,
     summary: partnership.summary,
     tags: partnership.tags,
+    custom_fields: renderCustomFieldsForWire(partnership.customFields),
     created_at: partnership.createdAt.toISOString(),
     updated_at: partnership.updatedAt.toISOString(),
   }

package/src/modules/partnerships/schema.ts

@@ -1,9 +1,9 @@
-import { date, index, pgTable, primaryKey, text } from 'drizzle-orm/pg-core'
+import type { CustomFieldValue } from '@kelpie/schemas'
+import { date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
 
 import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
 import type { SearchVectorPart } from '../../lib/columns.ts'
 import { companies } from '../companies/schema.ts'
-import { people } from '../people/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
 import { workspaceMembers, workspaces } from '../workspace/schema.ts'
 
@@ -32,6 +32,11 @@ export const partnerships = pgTable(
     successLooksLike: text('success_looks_like').notNull().default(''),
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
+    // Workspace-defined fields, keyed by definition key. See people/schema.ts.
+    customFields: jsonb('custom_fields')
+      .$type<Readonly<Record<string, CustomFieldValue>>>()
+      .notNull()
+      .default({}),
     createdAt: createdAt(),
     updatedAt: updatedAt(),
     searchVector: searchVector((): readonly SearchVectorPart[] => [
@@ -51,15 +56,3 @@ export const partnerships = pgTable(
   ],
 )
 
-export const partnershipPeople = pgTable(
-  'partnership_people',
-  {
-    partnershipId: text('partnership_id')
-      .notNull()
-      .references(() => partnerships.id, { onDelete: 'cascade' }),
-    personId: text('person_id')
-      .notNull()
-      .references(() => people.id, { onDelete: 'restrict' }),
-  },
-  (table) => [primaryKey({ columns: [table.partnershipId, table.personId] })],
-)

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)