@kelpie/server 0.1.0

package/src/modules/people/routes.ts

@@ -0,0 +1,175 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { pageBody, readIdFilter, readJsonBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import {
+  INFLUENCE_LEVELS,
+  PREFERRED_CHANNELS,
+  RELATIONSHIP_LEVELS,
+  SOCIAL_NETWORK_IDS,
+} from './schema.ts'
+import type { CreatePersonInput, PeopleService, PersonView, UpdatePersonInput } from './service.ts'
+
+/**
+ * Wire shapes for `/v1/people`.
+ *
+ * Bodies are strict: `api.md` makes an unknown field a 422 rather than something
+ * dropped in silence, because a client misspelling `summry` should hear about it
+ * on the first request, not on the day someone notices the field is empty.
+ */
+
+const socialProfileBody = z.strictObject({
+  network: z.enum(SOCIAL_NETWORK_IDS),
+  url: z.string().min(1),
+})
+
+/** The full field set, without defaults. `createBody` adds those; `updateBody` makes it partial. */
+const personShape = {
+  name: z.string().min(1),
+  email: z.string().nullable(),
+  phones: z.array(z.string().min(1)),
+  social_profiles: z.array(socialProfileBody),
+  timezone: z.string().nullable(),
+  location: z.string().nullable(),
+  preferred_channel: z.enum(PREFERRED_CHANNELS),
+  influence: z.enum(INFLUENCE_LEVELS),
+  relationship: z.enum(RELATIONSHIP_LEVELS),
+  summary: z.string(),
+  tags: z.array(z.string().min(1)),
+  last_contacted_at: z.iso.datetime().nullable(),
+}
+
+/**
+ * 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.
+ */
+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 updateBody = z.strictObject(personShape).partial()
+
+export interface PeopleRoutesDependencies extends CredentialDependencies {
+  readonly service: PeopleService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreatePersonInput {
+  return {
+    name: body.name,
+    email: body.email,
+    phones: body.phones,
+    socialProfiles: body.social_profiles,
+    timezone: body.timezone,
+    location: body.location,
+    preferredChannel: body.preferred_channel,
+    influence: body.influence,
+    relationship: body.relationship,
+    summary: body.summary,
+    tags: body.tags,
+    lastContactedAt: body.last_contacted_at === null ? null : new Date(body.last_contacted_at),
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdatePersonInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.email === undefined ? {} : { email: body.email }),
+    ...(body.phones === undefined ? {} : { phones: body.phones }),
+    ...(body.social_profiles === undefined ? {} : { socialProfiles: body.social_profiles }),
+    ...(body.timezone === undefined ? {} : { timezone: body.timezone }),
+    ...(body.location === undefined ? {} : { location: body.location }),
+    ...(body.preferred_channel === undefined ? {} : { preferredChannel: body.preferred_channel }),
+    ...(body.influence === undefined ? {} : { influence: body.influence }),
+    ...(body.relationship === undefined ? {} : { relationship: body.relationship }),
+    ...(body.summary === undefined ? {} : { summary: body.summary }),
+    ...(body.tags === undefined ? {} : { tags: body.tags }),
+    ...(body.last_contacted_at === undefined
+      ? {}
+      : {
+          lastContactedAt:
+            body.last_contacted_at === null ? null : new Date(body.last_contacted_at),
+        }),
+  }
+}
+
+export function personResponse(person: PersonView): Record<string, unknown> {
+  return {
+    id: person.id,
+    name: person.name,
+    email: person.email,
+    phones: person.phones,
+    social_profiles: person.socialProfiles,
+    timezone: person.timezone,
+    location: person.location,
+    preferred_channel: person.preferredChannel,
+    influence: person.influence,
+    relationship: person.relationship,
+    summary: person.summary,
+    tags: person.tags,
+    last_contacted_at: person.lastContactedAt === null ? null : person.lastContactedAt.toISOString(),
+    created_at: person.createdAt.toISOString(),
+    updated_at: person.updatedAt.toISOString(),
+  }
+}
+
+export function mountPeopleRoutes(router: Hono, dependencies: PeopleRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/people', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        companyIds: readIdFilter(context, 'company_id'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, personResponse))
+  })
+
+  router.post('/people', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const person = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(personResponse(person), 201)
+  })
+
+  router.get('/people/:id', async (context) => {
+    const person = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(personResponse(person))
+  })
+
+  router.patch('/people/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const person = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(personResponse(person))
+  })
+
+  router.delete('/people/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/people/schema.ts

@@ -0,0 +1,89 @@
+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 {
+  checkOneOf,
+  citext,
+  createdAt,
+  moment,
+  primaryId,
+  searchVector,
+  updatedAt,
+} from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * The fixed value sets come from `@kelpie/schemas`, so this table's check
+ * constraints, this module's Zod enums, and the browser's decoder are one list
+ * rather than three copies. A value the boundary accepts and the check
+ * constraint refuses would be a 500 where a 422 belongs.
+ *
+ * Re-exported because `routes.ts` and `service.ts` read them from here, and the
+ * table they constrain is the reason they matter.
+ */
+export {
+  INFLUENCE_LEVELS,
+  PREFERRED_CHANNELS,
+  RELATIONSHIP_LEVELS,
+  SOCIAL_NETWORK_IDS,
+} from '@kelpie/schemas'
+export type {
+  Influence,
+  PreferredChannel,
+  Relationship,
+  SocialNetworkId,
+} from '@kelpie/schemas'
+export type { SocialProfile }
+
+/**
+ * Who you know. Job title is not here: it lives on Position, because a person can
+ * hold titles at more than one company.
+ *
+ * `phones` and `social_profiles` are jsonb because nothing queries into them.
+ * They are typed rather than left as `unknown`, and the route layer parses what
+ * goes in, so a row read back is the shape it claims to be.
+ */
+export const people = pgTable(
+  'people',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    email: citext('email'),
+    phones: jsonb('phones').$type<readonly string[]>().notNull().default([]),
+    socialProfiles: jsonb('social_profiles')
+      .$type<readonly SocialProfile[]>()
+      .notNull()
+      .default([]),
+    timezone: text('timezone'),
+    location: text('location'),
+    preferredChannel: text('preferred_channel').notNull(),
+    influence: text('influence').notNull(),
+    relationship: text('relationship').notNull(),
+    summary: text('summary').notNull().default(''),
+    tags: text('tags').array().notNull().default([]),
+    lastContactedAt: moment('last_contacted_at'),
+    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' },
+      { column: people.email, weight: 'B' },
+      { column: people.summary, weight: 'B' },
+      { column: people.tags, weight: 'C', array: true },
+    ]),
+  },
+  (table) => [
+    unique('people_workspace_email_key').on(table.workspaceId, table.email),
+    index('people_workspace_idx').on(table.workspaceId),
+    index('people_search_idx').using('gin', table.searchVector),
+    checkOneOf('people_preferred_channel_check', table.preferredChannel, PREFERRED_CHANNELS),
+    checkOneOf('people_influence_check', table.influence, INFLUENCE_LEVELS),
+    checkOneOf('people_relationship_check', table.relationship, RELATIONSHIP_LEVELS),
+  ],
+)

package/src/modules/people/service.ts

@@ -0,0 +1,284 @@
+import { changedKeys } from '../../lib/changes.ts'
+import { UNIQUE_VIOLATION, isReferenceViolation, postgresErrorCode } from '../../lib/database.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import { normaliseEmail } from '../../lib/normalisation.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import { describeCreation, describeUpdate } from '../activities/wording.ts'
+import type { FieldLabels } from '../activities/wording.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import {
+  deleteRecordsAttachedTo,
+  deleteRecordsAttachedToCandidaciesOf,
+} from '../attachedRecords.ts'
+import { referencedElsewhere } from '../references.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_PERSON_SORT, PERSON_SORTS } from './repository.ts'
+import type { PersonFilters, PersonRecord } from './repository.ts'
+import type { Influence, PreferredChannel, Relationship, SocialProfile } from './schema.ts'
+
+/**
+ * People: who the workspace knows.
+ *
+ * No job title here. A title belongs to the Position linking a person to a
+ * company, because one person can hold titles at several.
+ *
+ * Every member of a workspace may read and write its people. The role ladder
+ * guards workspace administration, not CRM data.
+ */
+
+export interface PeopleDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/**
+ * What a changed column is called on a timeline.
+ *
+ * Written out rather than derived from the column name, because the mechanical
+ * answer is wrong often enough to matter: `preferredChannel` happens to give
+ * "Preferred channel", and `icpFit` gives "Icp fit".
+ */
+const PERSON_FIELD_LABELS: FieldLabels = {
+  name: 'Name',
+  email: 'Email',
+  phones: 'Phone numbers',
+  socialProfiles: 'Social profiles',
+  timezone: 'Timezone',
+  location: 'Location',
+  preferredChannel: 'Preferred channel',
+  influence: 'Influence',
+  relationship: 'Relationship',
+  summary: 'Summary',
+  tags: 'Tags',
+  lastContactedAt: 'Last contacted',
+}
+
+/**
+ * A person as the API returns one: the stored row minus the tenancy column.
+ *
+ * Deliberately an alias rather than a parallel interface. A hand-written copy of
+ * fifteen fields drifts from the table the first time one is added.
+ */
+export type PersonView = Omit<PersonRecord, 'workspaceId'>
+
+export interface CreatePersonInput {
+  readonly name: string
+  readonly email: string | null
+  readonly phones: readonly string[]
+  readonly socialProfiles: readonly SocialProfile[]
+  readonly timezone: string | null
+  readonly location: string | null
+  readonly preferredChannel: PreferredChannel
+  readonly influence: Influence
+  readonly relationship: Relationship
+  readonly summary: string
+  readonly tags: readonly string[]
+  readonly lastContactedAt: Date | null
+}
+
+/** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
+export type UpdatePersonInput = Partial<CreatePersonInput>
+
+export interface PeopleService {
+  list(actor: Actor, filters: PersonFilters, query: ListQueryParameters): Promise<Page<PersonView>>
+  get(actor: Actor, id: string): Promise<PersonView>
+  create(actor: Actor, input: CreatePersonInput): Promise<PersonView>
+  update(actor: Actor, id: string, changes: UpdatePersonInput): Promise<PersonView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: PersonRecord): PersonView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+/**
+ * The stored form of what the caller sent. Blank normalises to null: the email is
+ * unique per workspace, so a stored `''` would make the second person without an
+ * address a 409.
+ */
+function toStoredColumns(input: UpdatePersonInput): Partial<repository.PersonColumns> {
+  return {
+    ...(input.name === undefined ? {} : { name: input.name }),
+    ...(input.email === undefined ? {} : { email: input.email === null ? null : normaliseEmail(input.email) }),
+    ...(input.phones === undefined ? {} : { phones: input.phones }),
+    ...(input.socialProfiles === undefined ? {} : { socialProfiles: input.socialProfiles }),
+    ...(input.timezone === undefined ? {} : { timezone: input.timezone }),
+    ...(input.location === undefined ? {} : { location: input.location }),
+    ...(input.preferredChannel === undefined ? {} : { preferredChannel: input.preferredChannel }),
+    ...(input.influence === undefined ? {} : { influence: input.influence }),
+    ...(input.relationship === undefined ? {} : { relationship: input.relationship }),
+    ...(input.summary === undefined ? {} : { summary: input.summary }),
+    ...(input.tags === undefined ? {} : { tags: [...input.tags] }),
+    ...(input.lastContactedAt === undefined ? {} : { lastContactedAt: input.lastContactedAt }),
+  }
+}
+
+function duplicateEmail(): AppError {
+  return AppError.conflict('Another person in this workspace already has that email address', [
+    { field: 'email', message: 'Already in use' },
+  ])
+}
+
+export function createPeopleService(dependencies: PeopleDependencies): PeopleService {
+  async function require(workspaceId: string, id: string): Promise<PersonRecord> {
+    const person = await repository.findPerson(dependencies.db, workspaceId, id)
+
+    // A person in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (person === undefined) {
+      throw AppError.notFound('Person not found')
+    }
+
+    return person
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, PERSON_SORTS, DEFAULT_PERSON_SORT)
+      const rows = await repository.listPeople(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(toPage(rows, window, (person) => person.id), toView)
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+      const id = dependencies.createId('person')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        let created: PersonRecord
+
+        try {
+          created = await repository.insertPerson(tx, {
+            id,
+            workspaceId,
+            name: input.name,
+            email: input.email === null ? null : normaliseEmail(input.email),
+            phones: input.phones,
+            socialProfiles: input.socialProfiles,
+            timezone: input.timezone,
+            location: input.location,
+            preferredChannel: input.preferredChannel,
+            influence: input.influence,
+            relationship: input.relationship,
+            summary: input.summary,
+            tags: [...input.tags],
+            lastContactedAt: input.lastContactedAt,
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicateEmail()
+          }
+
+          throw error
+        }
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: created.id,
+          kind: 'created',
+          ...describeCreation('Person'),
+        })
+
+        events.emit('record.created', { workspaceId, objectType: 'person', recordId: created.id })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns = toStoredColumns(changes)
+      const changed = changedKeys(existing, columns)
+
+      // A PATCH that changes nothing is not a write. Bumping `updated_at` for it
+      // would make the record look freshly touched to everything that sorts or
+      // filters by it.
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        let updated: PersonRecord | undefined
+
+        try {
+          updated = await repository.updatePerson(tx, workspaceId, id, {
+            ...columns,
+            updatedAt: dependencies.now(),
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicateEmail()
+          }
+
+          throw error
+        }
+
+        if (updated === undefined) {
+          throw AppError.notFound('Person not found')
+        }
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: id,
+          kind: 'updated',
+          ...describeUpdate(changed, PERSON_FIELD_LABELS, existing, columns),
+        })
+
+        events.emit('record.updated', {
+          workspaceId,
+          objectType: 'person',
+          recordId: id,
+          changedFields: changed,
+        })
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        await require(workspaceId, id)
+
+        // Notes, activities and decisions carry no foreign key to their target,
+        // so nothing in the database removes them. Same transaction: if the
+        // delete below is refused, these come back with it.
+        await deleteRecordsAttachedTo(tx, workspaceId, 'person', id)
+
+        // The candidacy rows themselves cascade, which is why their interview
+        // notes have to be taken here: no hiring service sees that delete.
+        await deleteRecordsAttachedToCandidaciesOf(tx, workspaceId, id)
+
+        try {
+          await repository.deletePerson(tx, workspaceId, id)
+        } catch (error: unknown) {
+          if (isReferenceViolation(error)) {
+            throw referencedElsewhere(error, 'person')
+          }
+
+          throw error
+        }
+
+        events.emit('record.deleted', { workspaceId, objectType: 'person', recordId: id })
+      })
+    },
+  }
+}

package/src/modules/people/tools.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import { createBody, personResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { PeopleService } from './service.ts'
+
+/** `people_*`. Same schemas and mappers as `/v1/people`, so the two cannot drift. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+  company_id: idSetArg
+    .optional()
+    .describe('Only people holding a position at one of these companies.'),
+})
+
+export function registerPeopleTools(mcp: McpToolRegistry, service: PeopleService): void {
+  registerCrudTools(mcp, {
+    resource: 'people',
+    subject: 'person',
+    about: 'Someone the workspace knows. A job title belongs to a position, never to the person.',
+    service,
+    render: personResponse,
+    listArgs,
+    toFilters: (args) => ({ term: args.q, companyIds: toSet(args.company_id) }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/pipelines/index.ts

@@ -0,0 +1,43 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountPipelinesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createPipelineStagesService } from './service.ts'
+import { registerPipelineTools } from './tools.ts'
+
+/**
+ * Pipeline stage configuration: the board columns of the four pipelines.
+ *
+ * Requires `activities`, because remove-with-reassign writes each displaced
+ * record's `stage_changed` timeline entry in the same transaction.
+ */
+export function createPipelinesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'pipelines',
+    requires: ['workspace', 'activities'],
+    structural: true,
+
+    register(context) {
+      const service = createPipelineStagesService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity: createActivityRecorder({
+          createId: context.createId,
+          now: context.now,
+        }),
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountPipelinesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerPipelineTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}