@kelpie/server 0.8.0 → 0.10.0

package/src/modules/raises/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 { raisesEvents } from './events.ts'
 import { mountRaisesRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -17,7 +18,7 @@ import { registerRaisesTools } from './tools.ts'
 export function createRaisesModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'raises',
-    requires: ['companies', 'people', 'pipelines', 'activities'],
+    requires: ['companies', 'people', 'pipelines', 'activities', 'custom-fields'],
     events: raisesEvents,
 
     register(context) {
@@ -30,6 +31,7 @@ export function createRaisesModule(migrationsDirectory: string): KelpieModule {
           createId: context.createId,
           now: context.now,
         }),
+        customFields: createCustomFieldValues({ db: context.db }),
       })
 
       context.schema(schema, migrationsDirectory)

package/src/modules/raises/repository.ts

@@ -1,4 +1,4 @@
-import { and, asc, eq, ilike, inArray, or, sql } from 'drizzle-orm'
+import { and, eq, ilike, inArray, or, sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
 
 import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
@@ -6,9 +6,9 @@ import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
 import { arrayContainsPattern, containsPattern } from '../../lib/search.ts'
 import type { Queryable } from '../../runtime/transaction.ts'
 import { companies } from '../companies/schema.ts'
-import { people } from '../people/schema.ts'
+import { anyPersonLinked } from '../personLinks.ts'
 import { workspaceMembers } from '../workspace/schema.ts'
-import { raisePeople, raises } from './schema.ts'
+import { raises } from './schema.ts'
 
 export type RaiseRecord = typeof raises.$inferSelect
 
@@ -52,15 +52,6 @@ function companyNameMatches(pattern: string): SQL {
   )`
 }
 
-function hasAnyOfPeople(personIds: readonly string[]): SQL {
-  return sql`exists (
-    select 1
-    from ${raisePeople}
-    where ${raisePeople.raiseId} = ${raises.id}
-      and ${inArray(raisePeople.personId, personIds)}
-  )`
-}
-
 function matchesTerm(term: string): SQL | undefined {
   const pattern = containsPattern(term)
 
@@ -78,7 +69,9 @@ function conditionsFor(workspaceId: string, filters: RaiseFilters): (SQL | undef
     filters.term === undefined ? undefined : matchesTerm(filters.term),
     filters.companyIds === undefined ? undefined : inArray(raises.companyId, filters.companyIds),
     filters.stageIds === undefined ? undefined : inArray(raises.stageId, filters.stageIds),
-    filters.personIds === undefined ? undefined : hasAnyOfPeople(filters.personIds),
+    filters.personIds === undefined
+      ? undefined
+      : anyPersonLinked('raise', raises.id, raises.workspaceId, filters.personIds),
   ]
 }
 
@@ -145,100 +138,6 @@ export async function deleteRaise(db: Queryable, workspaceId: string, id: string
   return deleted.length
 }
 
-/** The key people on one raise. Ordered by id so a response is stable across reads. */
-export async function listPersonIds(db: Queryable, raiseId: string): Promise<string[]> {
-  const rows = await db
-    .select({ personId: raisePeople.personId })
-    .from(raisePeople)
-    .where(eq(raisePeople.raiseId, raiseId))
-    .orderBy(asc(raisePeople.personId))
-
-  return rows.map((row) => row.personId)
-}
-
-/**
- * The key people on each of a page of raises, in one query rather than one per
- * row.
- *
- * @returns Ids missing from the map have no people.
- */
-export async function listPersonIdsFor(
-  db: Queryable,
-  raiseIds: readonly string[],
-): Promise<ReadonlyMap<string, readonly string[]>> {
-  if (raiseIds.length === 0) {
-    return new Map()
-  }
-
-  const rows = await db
-    .select({ raiseId: raisePeople.raiseId, personId: raisePeople.personId })
-    .from(raisePeople)
-    .where(inArray(raisePeople.raiseId, raiseIds))
-    .orderBy(asc(raisePeople.personId))
-
-  const byRaise = new Map<string, string[]>()
-
-  for (const row of rows) {
-    const existing = byRaise.get(row.raiseId)
-
-    if (existing === undefined) {
-      byRaise.set(row.raiseId, [row.personId])
-    } else {
-      existing.push(row.personId)
-    }
-  }
-
-  return byRaise
-}
-
-export async function insertRaisePeople(
-  db: Queryable,
-  raiseId: string,
-  personIds: readonly string[],
-): Promise<void> {
-  if (personIds.length === 0) {
-    return
-  }
-
-  await db.insert(raisePeople).values(personIds.map((personId) => ({ raiseId, personId })))
-}
-
-export async function deleteRaisePeople(
-  db: Queryable,
-  raiseId: string,
-  personIds: readonly string[],
-): Promise<void> {
-  if (personIds.length === 0) {
-    return
-  }
-
-  await db
-    .delete(raisePeople)
-    .where(and(eq(raisePeople.raiseId, raiseId), inArray(raisePeople.personId, personIds)))
-}
-
-/**
- * The names of these people in this workspace, keyed by id. An id missing from
- * the map does not exist here, which is how `person_ids` is validated. Reads the
- * `people` *table*, per the cross-relation rule in `architecture.md`.
- */
-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]))
-}
-
 /** Whether a member belongs to this workspace, for validating `owner_id`. */
 export async function memberExists(
   db: Queryable,

package/src/modules/raises/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 { CreateRaiseInput, RaiseView, RaisesService, UpdateRaiseInput } from './service.ts'
 
 /** Wire shapes for `/v1/raises`. Bodies are strict; an unknown field is a 422, per `api.md`. */
@@ -26,6 +28,7 @@ const raiseShape = {
   person_ids: z.array(z.string().min(1)),
   summary: z.string(),
   tags: z.array(z.string().min(1)),
+  custom_fields: customFieldsPatchShape,
 }
 
 /**
@@ -48,6 +51,7 @@ export const createBody = z.strictObject({
   person_ids: raiseShape.person_ids.default([]),
   summary: raiseShape.summary.default(''),
   tags: raiseShape.tags.default([]),
+  custom_fields: raiseShape.custom_fields.default({}),
 })
 
 export const updateBody = z.strictObject(raiseShape).partial()
@@ -70,6 +74,7 @@ export function toCreateInput(body: z.infer<typeof createBody>): CreateRaiseInpu
     personIds: body.person_ids,
     summary: body.summary,
     tags: body.tags,
+    customFields: body.custom_fields,
   }
 }
 
@@ -87,6 +92,7 @@ export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateRaiseInpu
     ...(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 raiseResponse(raise: RaiseView): Record<string, unknown> {
     person_ids: raise.personIds,
     summary: raise.summary,
     tags: raise.tags,
+    custom_fields: renderCustomFieldsForWire(raise.customFields),
     created_at: raise.createdAt.toISOString(),
     updated_at: raise.updatedAt.toISOString(),
   }

package/src/modules/raises/schema.ts

@@ -1,9 +1,9 @@
-import { bigint, date, index, pgTable, primaryKey, text } from 'drizzle-orm/pg-core'
+import type { CustomFieldValue } from '@kelpie/schemas'
+import { bigint, 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'
 
@@ -34,6 +34,11 @@ export const raises = pgTable(
     expectedClose: date('expected_close'),
     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[] => [
@@ -52,15 +57,3 @@ export const raises = pgTable(
   ],
 )
 
-export const raisePeople = pgTable(
-  'raise_people',
-  {
-    raiseId: text('raise_id')
-      .notNull()
-      .references(() => raises.id, { onDelete: 'cascade' }),
-    personId: text('person_id')
-      .notNull()
-      .references(() => people.id, { onDelete: 'restrict' }),
-  },
-  (table) => [primaryKey({ columns: [table.raiseId, table.personId] })],
-)

package/src/modules/raises/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'
@@ -31,7 +35,7 @@ import type { RaiseFilters, RaiseRecord } from './repository.ts'
  * passed. The firm is `company_id`; the ongoing relationship with that firm
  * stays a Partnership (`brief.md`).
  *
- * Key people attach through `raise_people` and appear as `person_ids` on the
+ * Key people attach through `person_links` and appear as `person_ids` on the
  * wire, and the check size is integer cents plus an ISO 4217 code, both the
  * Deals 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`
@@ -44,6 +48,7 @@ export interface RaisesDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
 }
 
 /** What a changed column is called on a timeline. The mockup says Firm and Target close, not Company and Expected close. */
@@ -89,6 +94,8 @@ export interface CreateRaiseInput {
   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. */
@@ -106,6 +113,11 @@ export interface UpdateRaiseInput {
   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 RaisesService {
@@ -207,7 +219,7 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
     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) {
@@ -222,9 +234,14 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
   }
 
   /** @returns The page's views, with every raise's people fetched in one query. */
-  async function toViews(records: readonly RaiseRecord[]): Promise<RaiseView[]> {
-    const peopleByRaise = await repository.listPersonIdsFor(
+  async function toViews(
+    workspaceId: string,
+    records: readonly RaiseRecord[],
+  ): Promise<RaiseView[]> {
+    const peopleByRaise = await personLinks.listPersonIdsFor(
       dependencies.db,
+      workspaceId,
+      'raise',
       records.map((record) => record.id),
     )
 
@@ -238,14 +255,20 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
       const rows = await repository.listRaises(dependencies.db, workspaceId, filters, window)
       const page = toPage(rows, window, (raise) => raise.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 raise = await require(workspaceId, id)
 
-      return toView(raise, await repository.listPersonIds(dependencies.db, id))
+      return toView(
+        raise,
+        await personLinks.listPersonIds(dependencies.db, workspaceId, {
+          targetType: 'raise',
+          targetId: id,
+        }),
+      )
     },
 
     async create(actor, input) {
@@ -268,6 +291,12 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
       const id = dependencies.createId('raise')
 
       return dependencies.transaction(async ({ tx, events }) => {
+        const customFields = await dependencies.customFields.forCreate(
+          tx,
+          workspaceId,
+          'raise',
+          input.customFields,
+        )
         const created = await repository.insertRaise(tx, {
           id,
           workspaceId,
@@ -282,9 +311,16 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
           expectedClose: input.expectedClose,
           summary: input.summary,
           tags: [...input.tags],
+          customFields,
         })
 
-        await repository.insertRaisePeople(tx, id, personIds)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'raise', targetId: id },
+          personIds,
+        )
 
         await dependencies.recordActivity(tx, workspaceId, actor, {
           targetType: 'raise',
@@ -329,7 +365,10 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
         await requireOwner(workspaceId, changes.ownerId)
       }
 
-      const currentPeople = await repository.listPersonIds(dependencies.db, id)
+      const currentPeople = await personLinks.listPersonIds(dependencies.db, workspaceId, {
+        targetType: 'raise',
+        targetId: id,
+      })
       const nextPeople =
         changes.personIds === undefined ? undefined : [...new Set(changes.personIds)]
       const added =
@@ -343,16 +382,26 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
       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,
+          'raise',
+          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.updateRaise(tx, workspaceId, id, {
           ...columns,
+          ...(customFieldsChanged ? { customFields: cf.merged } : {}),
           updatedAt: dependencies.now(),
         })
 
@@ -360,8 +409,19 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
           throw AppError.notFound('Raise not found')
         }
 
-        await repository.insertRaisePeople(tx, id, added)
-        await repository.deleteRaisePeople(tx, id, removed)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'raise', targetId: id },
+          added,
+        )
+        await personLinks.unlinkPeople(
+          tx,
+          workspaceId,
+          { targetType: 'raise', targetId: id },
+          removed,
+        )
 
         if (stageMove !== undefined) {
           await dependencies.recordActivity(tx, workspaceId, actor, {
@@ -372,14 +432,19 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
           })
         }
 
-        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> = { ...RAISE_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: 'raise',
             targetId: id,
             kind: 'updated',
-            ...describeUpdate(otherChanged, RAISE_FIELD_LABELS, existing, columns),
+            ...describeUpdate(activityChanged, labels, before, after),
           })
         }
 
@@ -407,7 +472,13 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
         events.emit(
           'raises.raise.updated',
           { type: 'raise', id },
-          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+          {
+            changed: [
+              ...scalarChanged,
+              ...(linksChanged ? ['personIds'] : []),
+              ...customFieldPaths,
+            ],
+          },
         )
 
         if (stageMove !== undefined) {
@@ -428,7 +499,7 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
-        // `raise_people` dies with the raise through its foreign key; notes,
+        // Notes, activities, decisions, plan items, and person_links have no key back to the raise;
         // activities, decisions and plan items have no key, so they are removed
         // here, in the same transaction.
         await deleteRecordsAttachedTo(tx, workspaceId, 'raise', id)

package/src/modules/recordTargets.ts

@@ -4,6 +4,7 @@ import type { PgColumn, PgTable } from 'drizzle-orm/pg-core'
 import type { Queryable } from '../runtime/transaction.ts'
 import { companies } from './companies/schema.ts'
 import { deals } from './deals/schema.ts'
+import { enquiries } from './enquiries/schema.ts'
 import { candidates } from './hiring/schema.ts'
 import { RECORD_TARGET_TYPES } from './notes/schema.ts'
 import { opportunities } from './opportunities/schema.ts'
@@ -64,6 +65,7 @@ const TABLES: Readonly<Record<RecordTargetType, TargetTable>> = {
     partnerships.name,
   ),
   raise: targetTable(raises, raises.id, raises.workspaceId, raises.name),
+  enquiry: targetTable(enquiries, enquiries.id, enquiries.workspaceId, enquiries.name),
   candidate: targetTable(candidates, candidates.id, candidates.workspaceId),
 }
 

package/src/modules/references.ts

@@ -1,3 +1,6 @@
+import type { PipelineKind } from '@kelpie/schemas'
+import { PIPELINE_KINDS } from '@kelpie/schemas'
+
 import { referenceViolationTable } from '../lib/database.ts'
 import { AppError } from '../lib/errors.ts'
 
@@ -10,21 +13,30 @@ import { AppError } from '../lib/errors.ts'
  * insert, and would need updating every time a table gains a foreign key.
  */
 
-/** Referencing tables, as the domain names a user of the API would recognise. */
+/**
+ * Referencing tables, as the domain names a user of the API would recognise.
+ *
+ * `person_links` is deliberately absent: its `target_type` is one of four
+ * pipeline kinds and the row itself names which, so a caller reads
+ * `referencedByPipelineRecords` for that path instead of losing detail to a
+ * generic "person link" label.
+ */
 const REFERENCING_TYPE_BY_TABLE: Readonly<Record<string, string>> = {
   candidates: 'candidate',
-  deal_people: 'deal',
   deals: 'deal',
+  enquiries: 'enquiry',
   form_submissions: 'form submission',
   forms: 'form',
   opportunities: 'opportunity',
-  partnership_people: 'partnership',
   partnerships: 'partnership',
-  raise_people: 'raise',
   raises: 'raise',
   workspace_members: 'team member',
 }
 
+const PIPELINE_KIND_ORDER: ReadonlyMap<PipelineKind, number> = new Map(
+  PIPELINE_KINDS.map((kind, index) => [kind, index] as const),
+)
+
 /**
  * @param subject The record being deleted, e.g. `person`. Appears in the message.
  * @returns A 409. The referencing type is omitted when the driver did not report
@@ -42,3 +54,30 @@ export function referencedElsewhere(error: unknown, subject: string): AppError {
     { field: 'id', message: `Referenced by ${type}` },
   ])
 }
+
+/**
+ * The 409 for a person delete that `person_links` refused. The service queries
+ * the distinct target types still pointing at the person and passes them here,
+ * so the reply names one detail per pipeline the person is on (in
+ * `PIPELINE_KINDS` order, matching how the pipelines appear across the UI).
+ * Falls back to the generic wording only when the query came back empty, which
+ * is the delete-races-another-delete race — still a 409, just less specific.
+ */
+export function referencedByPipelineRecords(
+  subject: string,
+  types: readonly PipelineKind[],
+): AppError {
+  if (types.length === 0) {
+    return AppError.conflict(`This ${subject} is still referenced by another record`)
+  }
+
+  const ordered = [...types].sort(
+    (left, right) => (PIPELINE_KIND_ORDER.get(left) ?? 0) - (PIPELINE_KIND_ORDER.get(right) ?? 0),
+  )
+  const [first] = ordered
+
+  return AppError.conflict(
+    `This ${subject} is still referenced by a ${first}`,
+    ordered.map((type) => ({ field: 'id', message: `Referenced by ${type}` })),
+  )
+}