@kelpie/server 0.8.0 → 0.9.0

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