@kelpie/server 0.6.0 → 0.8.0

package/src/modules/lists/service.ts

@@ -0,0 +1,404 @@
+import { changedKeys } from '../../lib/changes.ts'
+import { UNIQUE_VIOLATION, 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 { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+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 { missingTargets, resolveTargetNames, targetKey } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import './events.ts'
+import * as repository from './repository.ts'
+import {
+  DEFAULT_LIST_MEMBER_SORT,
+  DEFAULT_LIST_SORT,
+  LIST_MEMBER_SORTS,
+  LIST_SORTS,
+} from './repository.ts'
+import type {
+  ListFilters,
+  ListMemberFilters,
+  ListMemberRecord,
+  ListWithCount,
+  MembershipWithList,
+} from './repository.ts'
+
+/**
+ * Lists: named collections of records of one type.
+ *
+ * The type is fixed at creation. A member's type must match the parent list's,
+ * a rule the database enforces through a composite foreign key. The service
+ * checks the same before the insert so a mismatch produces a friendly 422
+ * rather than a driver error the caller has to decode.
+ */
+
+export interface ListsDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+}
+
+/** A list as the API returns one: the stored row minus the tenancy column. */
+export type ListView = Omit<ListWithCount, 'workspaceId'>
+
+/** A membership plus the list it points at, as `/v1/list-memberships` returns one. */
+export interface ListMembershipView {
+  readonly id: string
+  readonly listId: string
+  readonly listName: string
+  readonly listTargetType: RecordTargetType
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly addedAt: Date
+}
+
+/** A member enriched with the resolved name of the record it points at. */
+export interface ListMemberView {
+  readonly id: string
+  readonly listId: string
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly targetName: string | null
+  readonly addedAt: Date
+}
+
+export interface CreateListInput {
+  readonly name: string
+  readonly targetType: RecordTargetType
+  readonly description: 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
+}
+
+export interface AddListMemberInput {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+}
+
+export interface ListsService {
+  list(actor: Actor, filters: ListFilters, query: ListQueryParameters): Promise<Page<ListView>>
+  get(actor: Actor, id: string): Promise<ListView>
+  create(actor: Actor, input: CreateListInput): Promise<ListView>
+  update(actor: Actor, id: string, changes: UpdateListInput): Promise<ListView>
+  remove(actor: Actor, id: string): Promise<void>
+  listMembers(
+    actor: Actor,
+    filters: ListMemberFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<ListMemberView>>
+  addMember(actor: Actor, listId: string, input: AddListMemberInput): Promise<ListMemberView>
+  removeMember(actor: Actor, listId: string, id: string): Promise<void>
+  membershipsFor(
+    actor: Actor,
+    targetType: RecordTargetType,
+    targetId: string,
+  ): Promise<readonly ListMembershipView[]>
+}
+
+function toView(record: ListWithCount): ListView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function toMembershipView(row: MembershipWithList): ListMembershipView {
+  return {
+    id: row.id,
+    listId: row.listId,
+    listName: row.listName,
+    listTargetType: row.listTargetType as RecordTargetType,
+    targetType: row.targetType as RecordTargetType,
+    targetId: row.targetId,
+    addedAt: row.addedAt,
+  }
+}
+
+function toMemberView(record: ListMemberRecord, name: string | undefined): ListMemberView {
+  return {
+    id: record.id,
+    listId: record.listId,
+    targetType: record.targetType as RecordTargetType,
+    targetId: record.targetId,
+    targetName: name ?? null,
+    addedAt: record.addedAt,
+  }
+}
+
+function duplicateName(): AppError {
+  return AppError.conflict('Another list in this workspace already has that name', [
+    { field: 'name', message: 'Already in use' },
+  ])
+}
+
+function typeMismatch(expected: RecordTargetType, got: RecordTargetType): AppError {
+  return AppError.validationFailed(
+    `That record cannot join a ${expected} list`,
+    [
+      {
+        field: 'target_type',
+        message: `Expected ${expected} to match the list's type, got ${got}`,
+      },
+    ],
+  )
+}
+
+function alreadyMember(): AppError {
+  return AppError.conflict('That record is already on the list', [
+    { field: 'target_id', message: 'Already a member' },
+  ])
+}
+
+export function createListsService(dependencies: ListsDependencies): ListsService {
+  async function require(workspaceId: string, id: string): Promise<ListWithCount> {
+    const list = await repository.findList(dependencies.db, workspaceId, id)
+
+    if (list === undefined) {
+      throw AppError.notFound('List not found')
+    }
+
+    return list
+  }
+
+  async function requireTarget(
+    workspaceId: string,
+    targetType: RecordTargetType,
+    targetId: string,
+  ): Promise<void> {
+    const missing = await missingTargets(dependencies.db, workspaceId, targetType, [targetId])
+
+    if (missing.length > 0) {
+      throw AppError.notFound('Record not found')
+    }
+  }
+
+  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)
+
+      return mapPage(toPage(rows, window, (row) => row.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('list')
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let created
+          try {
+            created = await repository.insertList(tx, {
+              id,
+              workspaceId,
+              name: input.name,
+              description: input.description,
+              targetType: input.targetType,
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateName()
+            }
+
+            throw error
+          }
+
+          events.emit('lists.list.created', { type: 'list', id: created.id }, {})
+
+          return toView({ ...created, memberCount: 0 })
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns: Partial<repository.ListColumns> = {
+        ...(changes.name === undefined ? {} : { name: changes.name }),
+        ...(changes.description === undefined ? {} : { description: changes.description }),
+      }
+      const changed = changedKeys(existing, columns)
+
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let updated
+          try {
+            updated = await repository.updateList(tx, workspaceId, id, {
+              ...columns,
+              updatedAt: dependencies.now(),
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateName()
+            }
+
+            throw error
+          }
+
+          if (updated === undefined) {
+            throw AppError.notFound('List not found')
+          }
+
+          events.emit('lists.list.updated', { type: 'list', id }, { changed })
+
+          return toView({ ...updated, memberCount: existing.memberCount })
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(
+        async ({ tx, events }) => {
+          await require(workspaceId, id)
+          // Members cascade with the list; nothing else references it.
+          await repository.deleteList(tx, workspaceId, id)
+
+          events.emit('lists.list.deleted', { type: 'list', id }, {})
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async listMembers(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      // The list must exist. A caller reading members of a missing list gets a
+      // 404, not a silent empty page.
+      await require(workspaceId, filters.listId)
+
+      const window = readListWindow(query, LIST_MEMBER_SORTS, DEFAULT_LIST_MEMBER_SORT)
+      const rows = await repository.listListMembers(dependencies.db, workspaceId, filters, window)
+      const names = await resolveTargetNames(
+        dependencies.db,
+        workspaceId,
+        rows.map((row) => ({
+          targetType: row.targetType as RecordTargetType,
+          targetId: row.targetId,
+        })),
+      )
+      const page = toPage(rows, window, (row) => row.id)
+
+      return mapPage(page, (row) =>
+        toMemberView(
+          row,
+          names.get(
+            targetKey({
+              targetType: row.targetType as RecordTargetType,
+              targetId: row.targetId,
+            }),
+          ),
+        ),
+      )
+    },
+
+    async addMember(actor, listId, input) {
+      const workspaceId = requireWorkspaceId(actor)
+      const list = await require(workspaceId, listId)
+
+      if (list.targetType !== input.targetType) {
+        throw typeMismatch(list.targetType as RecordTargetType, input.targetType)
+      }
+
+      await requireTarget(workspaceId, input.targetType, input.targetId)
+
+      const id = dependencies.createId('listMember')
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let created
+          try {
+            created = await repository.insertListMember(tx, {
+              id,
+              workspaceId,
+              listId,
+              targetType: input.targetType,
+              targetId: input.targetId,
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw alreadyMember()
+            }
+
+            throw error
+          }
+
+          events.emit(
+            'lists.member.added',
+            { type: input.targetType, id: input.targetId },
+            { listId },
+          )
+
+          const names = await resolveTargetNames(tx, workspaceId, [
+            { targetType: input.targetType, targetId: input.targetId },
+          ])
+
+          return toMemberView(
+            created,
+            names.get(targetKey({ targetType: input.targetType, targetId: input.targetId })),
+          )
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async membershipsFor(actor, targetType, targetId) {
+      const workspaceId = requireWorkspaceId(actor)
+      // The target must exist. A caller listing memberships of a missing record
+      // gets 404, not a silent empty list — same rule as notes/decisions.
+      await requireTarget(workspaceId, targetType, targetId)
+
+      const rows = await repository.listMembershipsForTarget(
+        dependencies.db,
+        workspaceId,
+        targetType,
+        targetId,
+      )
+
+      return rows.map(toMembershipView)
+    },
+
+    async removeMember(actor, listId, id) {
+      const workspaceId = requireWorkspaceId(actor)
+      await require(workspaceId, listId)
+
+      const existing = await repository.findListMember(dependencies.db, workspaceId, listId, id)
+
+      if (existing === undefined) {
+        throw AppError.notFound('List member not found')
+      }
+
+      await dependencies.transaction(
+        async ({ tx, events }) => {
+          await repository.deleteListMember(tx, workspaceId, listId, id)
+
+          events.emit(
+            'lists.member.removed',
+            { type: existing.targetType as RecordTargetType, id: existing.targetId },
+            { listId },
+          )
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+  }
+}

package/src/modules/lists/tools.ts

@@ -0,0 +1,128 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import {
+  deleteResult,
+  idArg,
+  listWindowShape,
+  pageResult,
+  registerCrudTools,
+  toListQuery,
+} from '../crudTools.ts'
+import {
+  addMemberBody,
+  createBody,
+  listMemberResponse,
+  listMembershipResponse,
+  listResponse,
+  toAddMemberInput,
+  toCreateInput,
+  toUpdateInput,
+  updateBody,
+} from './routes.ts'
+import type { ListsService } from './service.ts'
+
+/**
+ * `lists_*`. Same schemas and mappers as `/v1/lists`, so the two cannot drift.
+ *
+ * The list-level five come from `registerCrudTools`; the three membership tools
+ * are declared by hand because they hang off `/v1/lists/:id/members`, which does
+ * not fit the by-id CRUD shape.
+ */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Free text. Matches list names.'),
+  target_type: z
+    .enum(RECORD_TARGET_TYPES)
+    .optional()
+    .describe('Only lists that hold this kind of record.'),
+})
+
+const membersListArgs = z.strictObject({
+  ...listWindowShape,
+  list_id: idArg.describe('The list whose members you want.'),
+})
+
+const addMemberArgs = addMemberBody.extend({
+  list_id: idArg.describe('The list to add to. Its type must match target_type.'),
+})
+
+const removeMemberArgs = z.strictObject({
+  list_id: idArg.describe('The list to remove from.'),
+  id: idArg.describe('The membership id, from list_members_list.'),
+})
+
+const membershipsForArgs = z.strictObject({
+  target_type: z.enum(RECORD_TARGET_TYPES).describe('The kind of record.'),
+  target_id: idArg.describe('The record whose list memberships you want.'),
+})
+
+export function registerListsTools(mcp: McpToolRegistry, service: ListsService): void {
+  registerCrudTools(mcp, {
+    resource: 'lists',
+    subject: 'list',
+    about:
+      'A named collection of records of one type, chosen when the list is created and fixed for its lifetime.',
+    service,
+    render: listResponse,
+    listArgs,
+    toFilters: (args) => ({ term: args.q, targetType: args.target_type }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+
+  mcp.tool({
+    name: 'list_members_list',
+    description:
+      'List the records on one list. Cursor paged. Mirrors GET /v1/lists/{id}/members.',
+    inputSchema: membersListArgs,
+    invoke: async (args, actor) =>
+      pageResult(
+        await service.listMembers(actor, { listId: args.list_id }, toListQuery(args)),
+        listMemberResponse,
+      ),
+  })
+
+  mcp.tool({
+    name: 'list_members_add',
+    description:
+      'Add a record to a list. The record\'s type must match the list\'s. ' +
+      'Mirrors POST /v1/lists/{id}/members.',
+    inputSchema: addMemberArgs,
+    invoke: async (args, actor) =>
+      listMemberResponse(await service.addMember(actor, args.list_id, toAddMemberInput(args))),
+  })
+
+  mcp.tool({
+    name: 'list_members_remove',
+    description:
+      'Remove a record from a list. Mirrors DELETE /v1/lists/{id}/members/{memberId}.',
+    inputSchema: removeMemberArgs,
+    invoke: async (args, actor) => {
+      await service.removeMember(actor, args.list_id, args.id)
+
+      return deleteResult(args.id)
+    },
+  })
+
+  mcp.tool({
+    name: 'list_memberships_for',
+    description:
+      'Which lists is this record on? Returns one row per membership, with the ' +
+      'list joined in. Mirrors GET /v1/list-memberships.',
+    inputSchema: membershipsForArgs,
+    invoke: async (args, actor) => {
+      const memberships = await service.membershipsFor(actor, args.target_type, args.target_id)
+
+      return { data: memberships.map(listMembershipResponse), next_cursor: null }
+    },
+  })
+}

package/src/modules/people/repository.ts

@@ -132,6 +132,32 @@ export async function findPersonByEmail(
   return found
 }
 
+/**
+ * Every person in this workspace whose email is exactly at `domain`, case-
+ * insensitive. Used by the email-domain auto-linker when a Company is created
+ * or its domain is set.
+ *
+ * Not `ilike '%@domain'`: that also matches `alex@sub.domain`, which the
+ * person-side matcher (exact `email.slice(at + 1) = companies.domain`) would
+ * never link. `split_part` peels off the address at the last `@`, keeping the
+ * two directions consistent.
+ */
+export async function findPeopleByEmailDomain(
+  db: Queryable,
+  workspaceId: string,
+  domain: string,
+): Promise<PersonRecord[]> {
+  return db
+    .select()
+    .from(people)
+    .where(
+      and(
+        eq(people.workspaceId, workspaceId),
+        sql`split_part(${people.email}::text, '@', 2) = lower(${domain})`,
+      ),
+    )
+}
+
 export async function insertPerson(db: Queryable, values: PersonColumns): Promise<PersonRecord> {
   const [created] = await db.insert(people).values(values).returning()
 

package/src/modules/people/service.ts

@@ -1,6 +1,7 @@
 import { changedKeys } from '../../lib/changes.ts'
 import { UNIQUE_VIOLATION, isReferenceViolation, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
+import { autoLinkPersonByEmailDomain } from '../../lib/emailDomainAutoLink.ts'
 import { AppError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import { normaliseEmail } from '../../lib/normalisation.ts'
@@ -200,6 +201,15 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
 
           events.emit('people.person.created', { type: 'person', id: created.id }, {})
 
+          // Sync auto-link. Inside the same transaction so the response returns
+          // with the Position already visible to a follow-up read; without this
+          // the UI would not see the new Position until a manual refresh.
+          await autoLinkPersonByEmailDomain(tx, events, workspaceId, created, {
+            createId: dependencies.createId,
+            now: dependencies.now,
+            recordActivity: dependencies.recordActivity,
+          })
+
           return toView(created)
         },
         { workspaceId, actor: toEventActor(actor) },
@@ -253,6 +263,16 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
             { changed },
           )
 
+          // Sync auto-link when the email moved. Same-transaction rationale as
+          // the create path above.
+          if (changed.includes('email')) {
+            await autoLinkPersonByEmailDomain(tx, events, workspaceId, updated, {
+              createId: dependencies.createId,
+              now: dependencies.now,
+              recordActivity: dependencies.recordActivity,
+            })
+          }
+
           return toView(updated)
         },
         { workspaceId, actor: toEventActor(actor) },

package/src/modules/positions/routes.ts

@@ -17,11 +17,13 @@ import type {
 export const createBody = z.strictObject({
   person_id: z.string().min(1),
   company_id: z.string().min(1),
-  title: z.string().min(1),
+  // An empty title records the link without a job title — a person known to be
+  // at the company, with the role not yet captured.
+  title: z.string(),
 })
 
 /** Only the title. Moving a link to a different person or company is a delete and a create. */
-export const updateBody = z.strictObject({ title: z.string().min(1) }).partial()
+export const updateBody = z.strictObject({ title: z.string() }).partial()
 
 export interface PositionsRoutesDependencies extends CredentialDependencies {
   readonly service: PositionsService