@kelpie/server 0.8.0 → 0.10.0

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),

package/src/modules/people/routes.ts

@@ -1,3 +1,5 @@
+import { CONSENT_STATUSES, composeName, customFieldsPatchShape } from '@kelpie/schemas'
+import type { NameParts } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -5,6 +7,8 @@ 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 { EffectiveConsent } from './consentHydration.ts'
 import {
   INFLUENCE_LEVELS,
   PREFERRED_CHANNELS,
@@ -26,9 +30,32 @@ const socialProfileBody = z.strictObject({
   url: z.string().min(1),
 })
 
+/**
+ * One manual consent write on a Person body. `purpose_slug` names the
+ * workspace purpose; `status: null` clears the row and falls back to the
+ * purpose default, any other value upserts `source: manual`.
+ */
+const consentWriteBody = z.strictObject({
+  purpose_slug: z.string().min(1),
+  status: z.enum(CONSENT_STATUSES).nullable(),
+})
+
+/** The name parts of a body, under the names `composeName` reads them by. */
+function toNameParts(body: {
+  readonly first_name?: string | null
+  readonly last_name?: string | null
+  readonly suffix?: string | null
+}): NameParts {
+  return { firstName: body.first_name, lastName: body.last_name, suffix: body.suffix }
+}
+
 /** The full field set, without defaults. `createBody` adds those; `updateBody` makes it partial. */
 const personShape = {
   name: z.string().min(1),
+  salutation: z.string().nullable(),
+  first_name: z.string().nullable(),
+  last_name: z.string().nullable(),
+  suffix: z.string().nullable(),
   email: z.string().nullable(),
   phones: z.array(z.string().min(1)),
   social_profiles: z.array(socialProfileBody),
@@ -40,27 +67,56 @@ const personShape = {
   summary: z.string(),
   tags: z.array(z.string().min(1)),
   last_contacted_at: z.iso.datetime().nullable(),
+  do_not_contact: z.boolean(),
+  consents: z.array(consentWriteBody),
+  custom_fields: customFieldsPatchShape,
 }
 
 /**
- * Only `name` is required. The defaults are the ones the mockup's own Add person
- * button writes, so creating through the API and creating through the UI produce
- * the same record.
+ * A create names its person and defaults everything else. The defaults are the
+ * ones the mockup's own Add person button writes, so creating through the API and
+ * creating through the UI produce the same record.
+ *
+ * Naming the person means `name`, or the `first_name` / `last_name` pair for one
+ * to be composed from — the shape a caller holding a row out of another CRM
+ * already has. Sending neither is the one refusal, because `name` is what every
+ * list, picker and timeline in Kelpie renders and a blank one is a record nobody
+ * can pick out again.
  */
-export const createBody = z.strictObject({
-  ...personShape,
-  email: personShape.email.default(null),
-  phones: personShape.phones.default([]),
-  social_profiles: personShape.social_profiles.default([]),
-  timezone: personShape.timezone.default(null),
-  location: personShape.location.default(null),
-  preferred_channel: personShape.preferred_channel.default('email'),
-  influence: personShape.influence.default('influencer'),
-  relationship: personShape.relationship.default('cold'),
-  summary: personShape.summary.default(''),
-  tags: personShape.tags.default([]),
-  last_contacted_at: personShape.last_contacted_at.default(null),
-})
+export const createBody = z
+  .strictObject({
+    ...personShape,
+    name: personShape.name.optional(),
+    salutation: personShape.salutation.default(null),
+    first_name: personShape.first_name.default(null),
+    last_name: personShape.last_name.default(null),
+    suffix: personShape.suffix.default(null),
+    email: personShape.email.default(null),
+    phones: personShape.phones.default([]),
+    social_profiles: personShape.social_profiles.default([]),
+    timezone: personShape.timezone.default(null),
+    location: personShape.location.default(null),
+    preferred_channel: personShape.preferred_channel.default('email'),
+    influence: personShape.influence.default('influencer'),
+    relationship: personShape.relationship.default('cold'),
+    summary: personShape.summary.default(''),
+    tags: personShape.tags.default([]),
+    last_contacted_at: personShape.last_contacted_at.default(null),
+    do_not_contact: personShape.do_not_contact.default(false),
+    consents: personShape.consents.default([]),
+    custom_fields: personShape.custom_fields.default({}),
+  })
+  .superRefine((body, context) => {
+    if (body.name !== undefined || composeName(toNameParts(body)).length > 0) {
+      return
+    }
+
+    context.addIssue({
+      code: 'custom',
+      path: ['name'],
+      message: 'Send a name, or a first_name or last_name to compose one from',
+    })
+  })
 
 export const updateBody = z.strictObject(personShape).partial()
 
@@ -70,7 +126,13 @@ export interface PeopleRoutesDependencies extends CredentialDependencies {
 
 export function toCreateInput(body: z.infer<typeof createBody>): CreatePersonInput {
   return {
-    name: body.name,
+    // Composed only here, on the way in, and only when the caller sent no name.
+    // `createBody` has already refused a body that would leave this blank.
+    name: body.name ?? composeName(toNameParts(body)),
+    salutation: body.salutation,
+    firstName: body.first_name,
+    lastName: body.last_name,
+    suffix: body.suffix,
     email: body.email,
     phones: body.phones,
     socialProfiles: body.social_profiles,
@@ -82,12 +144,31 @@ export function toCreateInput(body: z.infer<typeof createBody>): CreatePersonInp
     summary: body.summary,
     tags: body.tags,
     lastContactedAt: body.last_contacted_at === null ? null : new Date(body.last_contacted_at),
+    doNotContact: body.do_not_contact,
+    consents: body.consents.map((consent) => ({
+      purposeSlug: consent.purpose_slug,
+      status: consent.status,
+    })),
+    customFields: body.custom_fields,
   }
 }
 
+/**
+ * A patch changes exactly the fields it names.
+ *
+ * Sending `first_name` alone does **not** recompute `name`. A display name is
+ * something somebody chose — "Chris" for a Christopher, a married name, a
+ * transliteration — and silently rewriting it from a part would undo that
+ * choice from across the room. Renaming is `name`, which is one more field in
+ * the same request for a caller that wants both.
+ */
 export function toUpdateInput(body: z.infer<typeof updateBody>): UpdatePersonInput {
   return {
     ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.salutation === undefined ? {} : { salutation: body.salutation }),
+    ...(body.first_name === undefined ? {} : { firstName: body.first_name }),
+    ...(body.last_name === undefined ? {} : { lastName: body.last_name }),
+    ...(body.suffix === undefined ? {} : { suffix: body.suffix }),
     ...(body.email === undefined ? {} : { email: body.email }),
     ...(body.phones === undefined ? {} : { phones: body.phones }),
     ...(body.social_profiles === undefined ? {} : { socialProfiles: body.social_profiles }),
@@ -104,6 +185,27 @@ export function toUpdateInput(body: z.infer<typeof updateBody>): UpdatePersonInp
           lastContactedAt:
             body.last_contacted_at === null ? null : new Date(body.last_contacted_at),
         }),
+    ...(body.do_not_contact === undefined ? {} : { doNotContact: body.do_not_contact }),
+    ...(body.consents === undefined
+      ? {}
+      : {
+          consents: body.consents.map((consent) => ({
+            purposeSlug: consent.purpose_slug,
+            status: consent.status,
+          })),
+        }),
+    ...(body.custom_fields === undefined ? {} : { customFields: body.custom_fields }),
+  }
+}
+
+function consentEntry(entry: EffectiveConsent): Record<string, unknown> {
+  return {
+    purpose_slug: entry.purposeSlug,
+    purpose_label: entry.purposeLabel,
+    status: entry.status,
+    source: entry.source,
+    noted_at: entry.notedAt === null ? null : entry.notedAt.toISOString(),
+    inherited: entry.inherited,
   }
 }
 
@@ -111,6 +213,10 @@ export function personResponse(person: PersonView): Record<string, unknown> {
   return {
     id: person.id,
     name: person.name,
+    salutation: person.salutation,
+    first_name: person.firstName,
+    last_name: person.lastName,
+    suffix: person.suffix,
     email: person.email,
     phones: person.phones,
     social_profiles: person.socialProfiles,
@@ -122,6 +228,9 @@ export function personResponse(person: PersonView): Record<string, unknown> {
     summary: person.summary,
     tags: person.tags,
     last_contacted_at: person.lastContactedAt === null ? null : person.lastContactedAt.toISOString(),
+    do_not_contact: person.doNotContact,
+    consents: person.consents.map(consentEntry),
+    custom_fields: renderCustomFieldsForWire(person.customFields),
     created_at: person.createdAt.toISOString(),
     updated_at: person.updatedAt.toISOString(),
   }

package/src/modules/people/schema.ts

@@ -1,6 +1,12 @@
-import { INFLUENCE_LEVELS, PREFERRED_CHANNELS, RELATIONSHIP_LEVELS } from '@kelpie/schemas'
-import type { SocialProfile } from '@kelpie/schemas'
-import { index, jsonb, pgTable, text, unique } from 'drizzle-orm/pg-core'
+import {
+  CONSENT_STATUSES,
+  INFLUENCE_LEVELS,
+  PIPELINE_KINDS,
+  PREFERRED_CHANNELS,
+  RELATIONSHIP_LEVELS,
+} from '@kelpie/schemas'
+import type { CustomFieldValue, SocialProfile } from '@kelpie/schemas'
+import { boolean, index, jsonb, pgTable, primaryKey, text, unique } from 'drizzle-orm/pg-core'
 
 import {
   checkOneOf,
@@ -12,6 +18,7 @@ import {
   updatedAt,
 } from '../../lib/columns.ts'
 import type { SearchVectorPart } from '../../lib/columns.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
 import { workspaces } from '../workspace/schema.ts'
 
 /**
@@ -53,6 +60,14 @@ export const people = pgTable(
       .notNull()
       .references(() => workspaces.id, { onDelete: 'cascade' }),
     name: text('name').notNull(),
+    // The canonical display name is `name`, and it is the only one of these that
+    // is required. The parts are recorded when they are known and left null when
+    // they are not; nothing composes them back into `name` after the row exists,
+    // so an edit to one never renames the record behind the editor's back.
+    salutation: text('salutation'),
+    firstName: text('first_name'),
+    lastName: text('last_name'),
+    suffix: text('suffix'),
     email: citext('email'),
     phones: jsonb('phones').$type<readonly string[]>().notNull().default([]),
     socialProfiles: jsonb('social_profiles')
@@ -67,12 +82,31 @@ export const people = pgTable(
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
     lastContactedAt: moment('last_contacted_at'),
+    // The Article 21 objection. A global do-not-contact signal, independent
+    // of consent purposes: agents check this before outreach regardless of
+    // per-purpose consent state. Never touched by forms, lists, or imports —
+    // the workspace member owns this flag.
+    doNotContact: boolean('do_not_contact').notNull().default(false),
+    // Workspace-defined fields, keyed by definition key. The custom-fields
+    // service validates every key on write; the store here just carries the
+    // shape. Default `{}` mirrors `tags`'s default — the object is always
+    // present, never null.
+    customFields: jsonb('custom_fields')
+      .$type<Readonly<Record<string, CustomFieldValue>>>()
+      .notNull()
+      .default({}),
     createdAt: createdAt(),
     updatedAt: updatedAt(),
     // Their title is not here because it is not on this table. `GET /v1/search`
     // reaches it through `positions.search_vector`.
     searchVector: searchVector((): readonly SearchVectorPart[] => [
       { column: people.name, weight: 'A' },
+      // The parts carry the same weight as the display name: they exist so a
+      // person can be found by a name they are not displayed under, and finding
+      // them is the whole point of storing them. `salutation` and `suffix` are
+      // left out — "Dr" and "Jr" match half a workspace and narrow nothing.
+      { column: people.firstName, weight: 'A' },
+      { column: people.lastName, weight: 'A' },
       { column: people.email, weight: 'B' },
       { column: people.summary, weight: 'B' },
       { column: people.tags, weight: 'C', array: true },
@@ -87,3 +121,75 @@ export const people = pgTable(
     checkOneOf('people_relationship_check', table.relationship, RELATIONSHIP_LEVELS),
   ],
 )
+
+/**
+ * The explicit consent decision for one (person, purpose) pair.
+ *
+ * Absence of a row means "inherits the purpose's `default_status`", so no
+ * `unknown` status here — a stored row always carries a decision. The pk is
+ * composite on `(person_id, purpose_id)` with no public id; the row is
+ * addressed by the pair, like `form_lists` and `form_attach_targets`.
+ *
+ * `source` records where the decision came from: `form:<form_id>`,
+ * `list:<list_id>`, `import`, or `manual`. Cascade with both the person and
+ * the purpose — erasing a person drops these with the rest of their record,
+ * and removing a purpose drops every row that still names it.
+ */
+export const personConsents = pgTable(
+  'person_consents',
+  {
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'cascade' }),
+    purposeId: text('purpose_id')
+      .notNull()
+      .references(() => consentPurposes.id, { onDelete: 'cascade' }),
+    status: text('status').notNull(),
+    notedAt: moment('noted_at').notNull().defaultNow(),
+    source: text('source').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.personId, table.purposeId] }),
+    index('person_consents_workspace_idx').on(table.workspaceId),
+    index('person_consents_purpose_idx').on(table.purposeId),
+    checkOneOf('person_consents_status_check', table.status, CONSENT_STATUSES),
+  ],
+)
+
+/**
+ * A person's involvement in a pipeline record — a deal, opportunity, raise, or
+ * partnership. One polymorphic table instead of a join per pipeline type; the
+ * person side keeps a real foreign key with **restrict**, so the database still
+ * blocks deleting a person who is on a deal. The target side is polymorphic per
+ * the convention: no FK, existence checked by the service, rows removed in the
+ * target's own delete transaction (`attachedRecords.ts`).
+ *
+ * `company` and `role` are deliberately absent from the check constraint: a
+ * link with a payload and its own lifecycle stays a typed object —
+ * Person↔Company is **Position** (title), Person↔Role is **Candidate** (status,
+ * stage, referrer).
+ */
+export const personLinks = pgTable(
+  'person_links',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'restrict' }),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+  },
+  (table) => [
+    index('person_links_target_idx').on(table.workspaceId, table.targetType, table.targetId),
+    unique('person_links_person_target_key').on(table.personId, table.targetType, table.targetId),
+    checkOneOf('person_links_target_type_check', table.targetType, PIPELINE_KINDS),
+  ],
+)