@kelpie/server 0.8.0 → 0.10.0

package/src/modules/import-export/writes.ts

@@ -7,11 +7,14 @@ import type { ActivityRecorder } from '../activities/recorder.ts'
 import { describeCreationVia, describeLink, describeUpdateVia } from '../activities/wording.ts'
 import type { Actor } from '../auth/actor.ts'
 import * as companyRepository from '../companies/repository.ts'
+import * as consentPurposesRepository from '../consent-purposes/repository.ts'
 import * as dealRepository from '../deals/repository.ts'
 import * as peopleRepository from '../people/repository.ts'
+import { upsertPersonConsent } from '../people/personConsentWrites.ts'
+import * as personLinks from '../personLinks.ts'
 import * as positionRepository from '../positions/repository.ts'
 import { IMPORT_DEAL_CURRENCY, NEW_COMPANY_DEFAULTS, NEW_PERSON_DEFAULTS } from './drafts.ts'
-import type { ImportWrite, PlannedAffiliation, RowPlan } from './plan.ts'
+import type { ImportConsentGrant, ImportWrite, PlannedAffiliation, RowPlan } from './plan.ts'
 
 /**
  * Applying one planned row: the insert or update, and the timeline entry that
@@ -220,6 +223,9 @@ async function writePerson(
       tags: write.draft.tags === undefined ? undefined : [...write.draft.tags],
       id: dependencies.createId('person'),
       workspaceId,
+      // `name` is not a required column any more; the People row check is what
+      // guarantees one, from the row's own `name` or composed from its first and
+      // last name cells. A row reaching here without one never passed validation.
       name: write.draft.name ?? '',
     })
 
@@ -228,6 +234,10 @@ async function writePerson(
         ? []
         : await applyAffiliation(dependencies, created.id, write.affiliation)
 
+    if (write.consent !== undefined) {
+      await applyImportConsent(dependencies, created.id, write.consent)
+    }
+
     return { recordId: created.id, objectType: 'person', changedFields: [], sideRecords }
   }
 
@@ -257,9 +267,51 @@ async function writePerson(
       ? []
       : await applyAffiliation(dependencies, id, write.affiliation)
 
+  if (write.consent !== undefined) {
+    await applyImportConsent(dependencies, id, write.consent)
+  }
+
   return { recordId: id, objectType: 'person', changedFields, sideRecords }
 }
 
+/**
+ * Applies the row's consent grant against the job's purpose. The purpose is
+ * looked up once per call rather than cached across rows — a commit runs one
+ * transaction and one row at a time — so the round trip is small and stays
+ * consistent with the current transaction's view.
+ */
+async function applyImportConsent(
+  dependencies: WriteDependencies,
+  personId: string,
+  consent: ImportConsentGrant,
+): Promise<void> {
+  const [purpose] = await consentPurposesRepository.listPurposesByIds(
+    dependencies.tx,
+    dependencies.workspaceId,
+    [consent.purposeId],
+  )
+  if (purpose === undefined) return
+  const notedAt = consent.notedAt === null ? dependencies.now : new Date(`${consent.notedAt}T00:00:00Z`)
+  await upsertPersonConsent(
+    dependencies.tx,
+    dependencies.workspaceId,
+    personId,
+    consent.purposeId,
+    purpose.slug,
+    purpose.label,
+    consent.status,
+    'import',
+    notedAt,
+  )
+  await dependencies.recordActivity(dependencies.tx, dependencies.workspaceId, dependencies.actor, {
+    targetType: 'person',
+    targetId: personId,
+    kind: 'updated',
+    action: `${consent.status === 'granted' ? 'granted' : 'withdrew'} ${purpose.label} consent via ${dependencies.sourceName}`,
+    detail: null,
+  })
+}
+
 /**
  * A Position's only writable field is its title, so an update is a rename.
  *
@@ -318,12 +370,19 @@ async function reconcileDealPeople(
   dealId: string,
   personIds: readonly string[],
 ): Promise<boolean> {
-  const current = await dealRepository.listPersonIds(dependencies.tx, dealId)
+  const target = { targetType: 'deal' as const, targetId: dealId }
+  const current = await personLinks.listPersonIds(dependencies.tx, dependencies.workspaceId, target)
   const added = personIds.filter((personId) => !current.includes(personId))
   const removed = current.filter((personId) => !personIds.includes(personId))
 
-  await dealRepository.insertDealPeople(dependencies.tx, dealId, added)
-  await dealRepository.deleteDealPeople(dependencies.tx, dealId, removed)
+  await personLinks.linkPeople(
+    dependencies.tx,
+    dependencies.createId,
+    dependencies.workspaceId,
+    target,
+    added,
+  )
+  await personLinks.unlinkPeople(dependencies.tx, dependencies.workspaceId, target, removed)
 
   return added.length > 0 || removed.length > 0
 }
@@ -352,7 +411,13 @@ async function writeDeal(
       // the same way, and no CSV column carries one.
       currency: IMPORT_DEAL_CURRENCY,
     })
-    await dealRepository.insertDealPeople(tx, id, write.personIds)
+    await personLinks.linkPeople(
+      tx,
+      dependencies.createId,
+      workspaceId,
+      { targetType: 'deal', targetId: id },
+      write.personIds,
+    )
 
     return { recordId: id, objectType: 'deal', changedFields: [] }
   }

package/src/modules/lists/index.ts

@@ -1,5 +1,11 @@
+import type { EventActor } from '@kelpie/schemas'
+
+import type { Database } from '../../lib/database.ts'
 import type { KelpieModule } from '../../runtime/module.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
 import { listsEvents } from './events.ts'
+import * as repository from './repository.ts'
 import { mountListsRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createListsService } from './service.ts'
@@ -39,3 +45,68 @@ export function createListsModule(migrationsDirectory: string): KelpieModule {
     },
   }
 }
+
+/** Dependencies a caller outside the lists module already holds. */
+export interface RemoveListMemberByTargetDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+}
+
+export interface RemoveListMemberByTargetInput {
+  readonly workspaceId: string
+  readonly listId: string
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  /**
+   * The event actor to stamp on `lists.member.removed`. An integration webhook
+   * that has no signed-in user passes `{ kind: 'system' }`; a module acting on
+   * behalf of a user passes `{ kind: 'user', id: userId }`.
+   */
+  readonly actor: EventActor
+}
+
+/**
+ * Removes a person (or any record) from a list by target, from outside the lists module.
+ *
+ * The path an integration takes when a signal from an external system removes
+ * membership — a Resend unsubscribe removing the person from every mapped list,
+ * a compliance sweep evicting a record — and there is no signed-in user to
+ * hang a normal `removeMember(actor, listId, id)` call on. Every safeguard the
+ * REST route enforces (workspace membership, ownership of the list, presence
+ * of the member row) is skipped here on purpose: the caller has already
+ * decided, and the input is trusted because it comes from another module in
+ * the same assembly rather than a request body.
+ *
+ * @returns `true` if the row was on the list and is now gone (emits
+ *   `lists.member.removed`), `false` if the target was not a member — a no-op
+ *   so a delivery redelivered by an at-least-once webhook is safe.
+ */
+export async function removeListMemberByTarget(
+  dependencies: RemoveListMemberByTargetDependencies,
+  input: RemoveListMemberByTargetInput,
+): Promise<boolean> {
+  return dependencies.transaction(
+    async ({ tx, events }) => {
+      const deleted = await repository.deleteListMemberByTarget(
+        tx,
+        input.workspaceId,
+        input.listId,
+        input.targetType,
+        input.targetId,
+      )
+
+      if (deleted === undefined) {
+        return false
+      }
+
+      events.emit(
+        'lists.member.removed',
+        { type: input.targetType, id: input.targetId },
+        { listId: input.listId },
+      )
+
+      return true
+    },
+    { workspaceId: input.workspaceId, actor: input.actor },
+  )
+}

package/src/modules/lists/repository.ts

@@ -103,6 +103,36 @@ export async function findList(
   return { ...found, memberCount: await countMembers(db, id) }
 }
 
+/**
+ * Bare list rows for a bulk existence + target-type check, without the
+ * member-count round trip `findList` pays for. Used by the forms service to
+ * validate `list_ids` at write time in one query rather than N.
+ */
+export interface ListIdRow {
+  readonly id: string
+  readonly targetType: string
+  readonly consentPurposeId: string | null
+}
+
+export async function listListsById(
+  db: Queryable,
+  workspaceId: string,
+  ids: readonly string[],
+): Promise<ListIdRow[]> {
+  if (ids.length === 0) {
+    return []
+  }
+
+  return db
+    .select({
+      id: lists.id,
+      targetType: lists.targetType,
+      consentPurposeId: lists.consentPurposeId,
+    })
+    .from(lists)
+    .where(and(eq(lists.workspaceId, workspaceId), inArray(lists.id, ids)))
+}
+
 async function countMembers(db: Queryable, listId: string): Promise<number> {
   const [row] = await db
     .select({ count: sql<number>`count(*)::int` })
@@ -240,6 +270,40 @@ export async function deleteListMember(
   return deleted.length
 }
 
+/**
+ * Removes the membership that points at a given target, if one is on the list.
+ *
+ * The addressed-by-target counterpart to `deleteListMember`, which addresses a
+ * row by its own id. An inbound integration webhook (Resend unsubscribe, for
+ * example) knows the person, not the list_member row that ties them to a list,
+ * and reading the row just to delete it is a round trip that adds nothing.
+ *
+ * @returns The removed row's id, or undefined if no member of that list points
+ *   at that target — the same shape a caller wanting to decide whether to emit
+ *   `lists.member.removed` needs.
+ */
+export async function deleteListMemberByTarget(
+  db: Queryable,
+  workspaceId: string,
+  listId: string,
+  targetType: string,
+  targetId: string,
+): Promise<{ id: string } | undefined> {
+  const [deleted] = await db
+    .delete(listMembers)
+    .where(
+      and(
+        eq(listMembers.workspaceId, workspaceId),
+        eq(listMembers.listId, listId),
+        eq(listMembers.targetType, targetType),
+        eq(listMembers.targetId, targetId),
+      ),
+    )
+    .returning({ id: listMembers.id })
+
+  return deleted
+}
+
 /** A membership row enriched with the list it points at. */
 export interface MembershipWithList {
   readonly id: string

package/src/modules/lists/routes.ts

@@ -31,12 +31,14 @@ export const createBody = z.strictObject({
   name: z.string().min(1),
   target_type: z.enum(RECORD_TARGET_TYPES),
   description: z.string().nullable().default(null),
+  consent_purpose_id: z.string().min(1).nullable().default(null),
 })
 
 export const updateBody = z
   .strictObject({
     name: z.string().min(1),
     description: z.string().nullable(),
+    consent_purpose_id: z.string().min(1).nullable(),
   })
   .partial()
 
@@ -54,6 +56,7 @@ export function toCreateInput(body: z.infer<typeof createBody>): CreateListInput
     name: body.name,
     targetType: body.target_type,
     description: body.description,
+    consentPurposeId: body.consent_purpose_id,
   }
 }
 
@@ -61,6 +64,9 @@ export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateListInput
   return {
     ...(body.name === undefined ? {} : { name: body.name }),
     ...(body.description === undefined ? {} : { description: body.description }),
+    ...(body.consent_purpose_id === undefined
+      ? {}
+      : { consentPurposeId: body.consent_purpose_id }),
   }
 }
 
@@ -78,6 +84,8 @@ export function listResponse(list: ListView): Record<string, unknown> {
     description: list.description,
     target_type: list.targetType,
     member_count: list.memberCount,
+    consent_purpose_id: list.consentPurposeId,
+    consent_purpose_slug: list.consentPurposeSlug,
     created_at: list.createdAt.toISOString(),
     updated_at: list.updatedAt.toISOString(),
   }

package/src/modules/lists/schema.ts

@@ -2,6 +2,7 @@ import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
 import { foreignKey, index, pgTable, text, timestamp, unique } from 'drizzle-orm/pg-core'
 
 import { checkOneOf, createdAt, primaryId, updatedAt } from '../../lib/columns.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
 import { workspaces } from '../workspace/schema.ts'
 
 /**
@@ -34,6 +35,15 @@ export const lists = pgTable(
     name: text('name').notNull(),
     description: text('description'),
     targetType: text('target_type').notNull(),
+    /**
+     * The consent purpose captured when a form submit adds a person to this
+     * list. Person lists only — the service refuses a non-null value on any
+     * other target type. `restrict` on delete so a purpose in use is not
+     * silently unset behind the list's back.
+     */
+    consentPurposeId: text('consent_purpose_id').references(() => consentPurposes.id, {
+      onDelete: 'restrict',
+    }),
     createdAt: createdAt(),
     updatedAt: updatedAt(),
   },

package/src/modules/lists/service.ts

@@ -9,6 +9,7 @@ import type { TransactionScope } from '../../runtime/transaction.ts'
 import { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import * as consentPurposesRepository from '../consent-purposes/repository.ts'
 import { missingTargets, resolveTargetNames, targetKey } from '../recordTargets.ts'
 import type { RecordTargetType } from '../recordTargets.ts'
 import './events.ts'
@@ -43,8 +44,14 @@ export interface ListsDependencies {
   readonly now: () => Date
 }
 
-/** A list as the API returns one: the stored row minus the tenancy column. */
-export type ListView = Omit<ListWithCount, 'workspaceId'>
+/**
+ * A list as the API returns one: the stored row minus the tenancy column,
+ * plus the denormalised slug of the consent purpose (when set) so a reader
+ * needs no second call.
+ */
+export type ListView = Omit<ListWithCount, 'workspaceId'> & {
+  readonly consentPurposeSlug: string | null
+}
 
 /** A membership plus the list it points at, as `/v1/list-memberships` returns one. */
 export interface ListMembershipView {
@@ -71,12 +78,18 @@ export interface CreateListInput {
   readonly name: string
   readonly targetType: RecordTargetType
   readonly description: string | null
+  /**
+   * Optional consent purpose captured on form-driven adds. Person lists only.
+   * A non-null value on any other target type is refused at 422.
+   */
+  readonly consentPurposeId: string | null
 }
 
 /** PATCH semantics: an absent field is left alone. The type never moves. */
 export interface UpdateListInput {
   readonly name?: string | undefined
   readonly description?: string | null | undefined
+  readonly consentPurposeId?: string | null | undefined
 }
 
 export interface AddListMemberInput {
@@ -104,10 +117,10 @@ export interface ListsService {
   ): Promise<readonly ListMembershipView[]>
 }
 
-function toView(record: ListWithCount): ListView {
+function toView(record: ListWithCount, consentPurposeSlug: string | null): ListView {
   const { workspaceId: _workspaceId, ...view } = record
 
-  return view
+  return { ...view, consentPurposeSlug }
 }
 
 function toMembershipView(row: MembershipWithList): ListMembershipView {
@@ -157,6 +170,13 @@ function alreadyMember(): AppError {
   ])
 }
 
+function purposeNotPersonList(): AppError {
+  return AppError.validationFailed(
+    'Only person lists capture consent — remove consent_purpose_id or change the list type',
+    [{ field: 'consent_purpose_id', message: 'Person lists only' }],
+  )
+}
+
 export function createListsService(dependencies: ListsDependencies): ListsService {
   async function require(workspaceId: string, id: string): Promise<ListWithCount> {
     const list = await repository.findList(dependencies.db, workspaceId, id)
@@ -180,23 +200,77 @@ export function createListsService(dependencies: ListsDependencies): ListsServic
     }
   }
 
+  async function resolveConsentPurposeSlug(
+    workspaceId: string,
+    purposeId: string | null,
+  ): Promise<string | null> {
+    if (purposeId === null) return null
+    const [row] = await consentPurposesRepository.listPurposesByIds(
+      dependencies.db,
+      workspaceId,
+      [purposeId],
+    )
+    return row?.slug ?? null
+  }
+
+  async function requireConsentPurposeExists(
+    workspaceId: string,
+    purposeId: string,
+  ): Promise<void> {
+    const rows = await consentPurposesRepository.listPurposesByIds(
+      dependencies.db,
+      workspaceId,
+      [purposeId],
+    )
+    if (rows.length === 0) {
+      throw AppError.validationFailed('That consent purpose was not found', [
+        { field: 'consent_purpose_id', message: `No purpose ${purposeId} here` },
+      ])
+    }
+  }
+
   return {
     async list(actor, filters, query) {
       const workspaceId = requireWorkspaceId(actor)
       const window = readListWindow(query, LIST_SORTS, DEFAULT_LIST_SORT)
       const rows = await repository.listLists(dependencies.db, workspaceId, filters, window)
+      const purposeIds = Array.from(
+        new Set(
+          rows
+            .map((row) => row.consentPurposeId)
+            .filter((id): id is string => id !== null),
+        ),
+      )
+      const purposes = await consentPurposesRepository.listPurposesByIds(
+        dependencies.db,
+        workspaceId,
+        purposeIds,
+      )
+      const slugByPurpose = new Map(purposes.map((purpose) => [purpose.id, purpose.slug]))
 
-      return mapPage(toPage(rows, window, (row) => row.id), toView)
+      return mapPage(toPage(rows, window, (row) => row.id), (row) =>
+        toView(row, row.consentPurposeId === null ? null : (slugByPurpose.get(row.consentPurposeId) ?? null)),
+      )
     },
 
     async get(actor, id) {
-      return toView(await require(requireWorkspaceId(actor), id))
+      const workspaceId = requireWorkspaceId(actor)
+      const record = await require(workspaceId, id)
+      const slug = await resolveConsentPurposeSlug(workspaceId, record.consentPurposeId)
+      return toView(record, slug)
     },
 
     async create(actor, input) {
       const workspaceId = requireWorkspaceId(actor)
       const id = dependencies.createId('list')
 
+      if (input.consentPurposeId !== null) {
+        if (input.targetType !== 'person') {
+          throw purposeNotPersonList()
+        }
+        await requireConsentPurposeExists(workspaceId, input.consentPurposeId)
+      }
+
       return dependencies.transaction(
         async ({ tx, events }) => {
           let created
@@ -207,6 +281,7 @@ export function createListsService(dependencies: ListsDependencies): ListsServic
               name: input.name,
               description: input.description,
               targetType: input.targetType,
+              consentPurposeId: input.consentPurposeId,
             })
           } catch (error: unknown) {
             if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
@@ -218,7 +293,12 @@ export function createListsService(dependencies: ListsDependencies): ListsServic
 
           events.emit('lists.list.created', { type: 'list', id: created.id }, {})
 
-          return toView({ ...created, memberCount: 0 })
+          const slug = await resolveConsentPurposeSlug(
+            workspaceId,
+            created.consentPurposeId,
+          )
+
+          return toView({ ...created, memberCount: 0 }, slug)
         },
         { workspaceId, actor: toEventActor(actor) },
       )
@@ -227,14 +307,33 @@ export function createListsService(dependencies: ListsDependencies): ListsServic
     async update(actor, id, changes) {
       const workspaceId = requireWorkspaceId(actor)
       const existing = await require(workspaceId, id)
+
+      if (
+        changes.consentPurposeId !== undefined &&
+        changes.consentPurposeId !== null &&
+        existing.targetType !== 'person'
+      ) {
+        throw purposeNotPersonList()
+      }
+      if (
+        changes.consentPurposeId !== undefined &&
+        changes.consentPurposeId !== null
+      ) {
+        await requireConsentPurposeExists(workspaceId, changes.consentPurposeId)
+      }
+
       const columns: Partial<repository.ListColumns> = {
         ...(changes.name === undefined ? {} : { name: changes.name }),
         ...(changes.description === undefined ? {} : { description: changes.description }),
+        ...(changes.consentPurposeId === undefined
+          ? {}
+          : { consentPurposeId: changes.consentPurposeId }),
       }
       const changed = changedKeys(existing, columns)
 
       if (changed.length === 0) {
-        return toView(existing)
+        const slug = await resolveConsentPurposeSlug(workspaceId, existing.consentPurposeId)
+        return toView(existing, slug)
       }
 
       return dependencies.transaction(
@@ -259,7 +358,9 @@ export function createListsService(dependencies: ListsDependencies): ListsServic
 
           events.emit('lists.list.updated', { type: 'list', id }, { changed })
 
-          return toView({ ...updated, memberCount: existing.memberCount })
+          const slug = await resolveConsentPurposeSlug(workspaceId, updated.consentPurposeId)
+
+          return toView({ ...updated, memberCount: existing.memberCount }, slug)
         },
         { workspaceId, actor: toEventActor(actor) },
       )

package/src/modules/mcp/index.ts

@@ -44,6 +44,11 @@ export const MCP_INSTRUCTIONS = [
   '- The handbook holds voice, ICP, and how this company sells. Read handbook_pages_list',
   '  before writing anything a customer will see.',
   '- A job title belongs to a position, not a person. A person may hold several.',
+  '- A person has one name, which is what to call them and what every list shows.',
+  '  first_name, last_name, salutation and suffix are optional detail beside it. Send',
+  '  the parts when you know them; people_create composes a name from first_name and',
+  '  last_name when you send no name. Never split a name into parts yourself, and note',
+  '  that changing a part does not rename the person — send name to do that.',
   '- Next steps are plan_items with a date and an owner, not prose in a summary field.',
 ].join('\n')
 

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

package/src/modules/opportunities/repository.ts

@@ -6,6 +6,7 @@ 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 { anyPersonLinked } from '../personLinks.ts'
 import { workspaceMembers } from '../workspace/schema.ts'
 import { opportunities } from './schema.ts'
 
@@ -32,6 +33,8 @@ export interface OpportunityFilters {
   readonly companyIds?: readonly string[] | undefined
   /** `?stage_id=`, repeatable: the board fetches one column with one of these. */
   readonly stageIds?: readonly string[] | undefined
+  /** `?person_id=`, repeatable: opportunities any of these people are on. */
+  readonly personIds?: readonly string[] | undefined
 }
 
 /**
@@ -69,6 +72,14 @@ function conditionsFor(workspaceId: string, filters: OpportunityFilters): (SQL |
       ? undefined
       : inArray(opportunities.companyId, filters.companyIds),
     filters.stageIds === undefined ? undefined : inArray(opportunities.stageId, filters.stageIds),
+    filters.personIds === undefined
+      ? undefined
+      : anyPersonLinked(
+          'opportunity',
+          opportunities.id,
+          opportunities.workspaceId,
+          filters.personIds,
+        ),
   ]
 }