@kelpie/server 0.1.0

package/src/modules/plans/tools.ts

@@ -0,0 +1,45 @@
+import { PIPELINE_KINDS, PLAN_ITEM_STATUSES } from '@kelpie/schemas'
+import { isoDateSchema } from '../../lib/dates.ts'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { enumSetArg, idArg, idSetArg, listWindowShape, registerCrudTools, toSet } from '../crudTools.ts'
+import { createBody, planItemResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { PlansService } from './service.ts'
+
+/** `plan_items_*`. Same schemas and mappers as `/v1/plan_items`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  target_type: z.enum(PIPELINE_KINDS).optional().describe('One pipeline\'s plan items.'),
+  target_id: idSetArg.optional().describe('The plan items on these records.'),
+  status: enumSetArg(PLAN_ITEM_STATUSES)
+    .optional()
+    .describe('Naming todo and in_progress together is how you ask for outstanding work.'),
+  from: isoDateSchema.optional().describe('Inclusive lower bound, YYYY-MM-DD.'),
+  to: isoDateSchema.optional().describe('Inclusive upper bound, YYYY-MM-DD.'),
+})
+
+export function registerPlansTools(mcp: McpToolRegistry, service: PlansService): void {
+  registerCrudTools(mcp, {
+    resource: 'plan_items',
+    subject: 'plan item',
+    about:
+      'A dated, owned next step on a deal, opportunity, partnership or raise. ' +
+      'Next steps live here, not in a summary field.',
+    service,
+    render: planItemResponse,
+    listArgs,
+    toFilters: (args) => ({
+      targetType: args.target_type,
+      targetIds: toSet(args.target_id),
+      statuses: toSet(args.status),
+      from: args.from,
+      to: args.to,
+    }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/positions/index.ts

@@ -0,0 +1,42 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountPositionsRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createPositionsService } from './service.ts'
+import { registerPositionsTools } from './tools.ts'
+
+/**
+ * Position: the person-to-company link, and the only place a job title lives.
+ *
+ * Requires both ends, because creating one checks that the person and the company
+ * are in the caller's workspace before linking them.
+ */
+export function createPositionsModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'positions',
+    requires: ['people', 'companies', 'activities'],
+
+    register(context) {
+      const service = createPositionsService({
+        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) => {
+        mountPositionsRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerPositionsTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/positions/repository.ts

@@ -0,0 +1,136 @@
+import { and, asc, eq, inArray } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { positions } from './schema.ts'
+
+export type PositionRecord = typeof positions.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type PositionColumns = typeof positions.$inferInsert
+
+export const POSITION_SORTS: SortableFields<PositionRecord> = {
+  title: textSort(positions.title, (position) => position.title),
+  created_at: timestampSort(positions.createdAt, (position) => position.createdAt),
+  updated_at: timestampSort(positions.updatedAt, (position) => position.updatedAt),
+}
+
+export const DEFAULT_POSITION_SORT = '-created_at'
+
+/**
+ * No `?q=`. A position holds one field a user could search, and it is already
+ * reachable from both sides through the person and company filters.
+ */
+export interface PositionFilters {
+  /** `?person_id=`, repeatable: the positions held by any of these people. */
+  readonly personIds?: readonly string[] | undefined
+  /** `?company_id=`, repeatable: the positions held at any of these companies. */
+  readonly companyIds?: readonly string[] | undefined
+}
+
+function conditionsFor(workspaceId: string, filters: PositionFilters): (SQL | undefined)[] {
+  return [
+    eq(positions.workspaceId, workspaceId),
+    filters.personIds === undefined ? undefined : inArray(positions.personId, filters.personIds),
+    filters.companyIds === undefined ? undefined : inArray(positions.companyId, filters.companyIds),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listPositions(
+  db: Queryable,
+  workspaceId: string,
+  filters: PositionFilters,
+  window: ListWindow<PositionRecord>,
+): Promise<PositionRecord[]> {
+  return db
+    .select()
+    .from(positions)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, positions.id)))
+    .orderBy(...orderByWindow(window, positions.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findPosition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<PositionRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(positions)
+    .where(and(eq(positions.workspaceId, workspaceId), eq(positions.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * Every title a person holds at one company, oldest first.
+ *
+ * A form submit needs the whole set rather than one row: a person may hold two
+ * titles at the same company, and the submit prefers the one whose title
+ * matches before it falls back to filling in a blank on any of them
+ * (`forms.md` submit rule 5).
+ */
+export function listPositionsAt(
+  db: Queryable,
+  workspaceId: string,
+  personId: string,
+  companyId: string,
+): Promise<PositionRecord[]> {
+  return db
+    .select()
+    .from(positions)
+    .where(
+      and(
+        eq(positions.workspaceId, workspaceId),
+        eq(positions.personId, personId),
+        eq(positions.companyId, companyId),
+      ),
+    )
+    .orderBy(asc(positions.createdAt), asc(positions.id))
+}
+
+export async function insertPosition(
+  db: Queryable,
+  values: PositionColumns,
+): Promise<PositionRecord> {
+  const [created] = await db.insert(positions).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting position ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updatePosition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<PositionColumns>,
+): Promise<PositionRecord | undefined> {
+  const [updated] = await db
+    .update(positions)
+    .set(changes)
+    .where(and(eq(positions.workspaceId, workspaceId), eq(positions.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deletePosition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(positions)
+    .where(and(eq(positions.workspaceId, workspaceId), eq(positions.id, id)))
+    .returning({ id: positions.id })
+
+  return deleted.length
+}

package/src/modules/positions/routes.ts

@@ -0,0 +1,97 @@
+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 type {
+  CreatePositionInput,
+  PositionView,
+  PositionsService,
+  UpdatePositionInput,
+} from './service.ts'
+
+/** Wire shapes for `/v1/positions`. Bodies are strict; an unknown field is a 422, per `api.md`. */
+
+export const createBody = z.strictObject({
+  person_id: z.string().min(1),
+  company_id: z.string().min(1),
+  title: z.string().min(1),
+})
+
+/** 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 interface PositionsRoutesDependencies extends CredentialDependencies {
+  readonly service: PositionsService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreatePositionInput {
+  return { personId: body.person_id, companyId: body.company_id, title: body.title }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdatePositionInput {
+  return { ...(body.title === undefined ? {} : { title: body.title }) }
+}
+
+export function positionResponse(position: PositionView): Record<string, unknown> {
+  return {
+    id: position.id,
+    person_id: position.personId,
+    company_id: position.companyId,
+    title: position.title,
+    created_at: position.createdAt.toISOString(),
+    updated_at: position.updatedAt.toISOString(),
+  }
+}
+
+export function mountPositionsRoutes(router: Hono, dependencies: PositionsRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/positions', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        personIds: readIdFilter(context, 'person_id'),
+        companyIds: readIdFilter(context, 'company_id'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, positionResponse))
+  })
+
+  router.post('/positions', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const position = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(positionResponse(position), 201)
+  })
+
+  router.get('/positions/:id', async (context) => {
+    const position = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(positionResponse(position))
+  })
+
+  router.patch('/positions/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const position = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(positionResponse(position))
+  })
+
+  router.delete('/positions/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/positions/schema.ts

@@ -0,0 +1,42 @@
+import { index, pgTable, text, unique } from 'drizzle-orm/pg-core'
+
+import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { companies } from '../companies/schema.ts'
+import { people } from '../people/schema.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * A person holds a title at a company. Always use this link; there is no bare
+ * person-to-company foreign key anywhere.
+ *
+ * A pure dependent: it dies with either side and nothing restricts on it.
+ */
+export const positions = pgTable(
+  'positions',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'cascade' }),
+    companyId: text('company_id')
+      .notNull()
+      .references(() => companies.id, { onDelete: 'cascade' }),
+    title: text('title').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    // A position is never a search result itself. This vector exists so a search
+    // for a job title finds the person holding it, which is what the mockup's
+    // `/search` and `?q=` on people both do.
+    searchVector: searchVector((): readonly SearchVectorPart[] => [{ column: positions.title, weight: 'A' }]),
+  },
+  (table) => [
+    unique('positions_person_company_title_key').on(table.personId, table.companyId, table.title),
+    index('positions_workspace_idx').on(table.workspaceId),
+    index('positions_company_idx').on(table.companyId),
+    index('positions_search_idx').using('gin', table.searchVector),
+  ],
+)

package/src/modules/positions/service.ts

@@ -0,0 +1,253 @@
+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 type { ActivityRecorder } from '../activities/recorder.ts'
+import { describeLink, describeUnlink } from '../activities/wording.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import * as companyRepository from '../companies/repository.ts'
+import * as personRepository from '../people/repository.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_POSITION_SORT, POSITION_SORTS } from './repository.ts'
+import type { PositionFilters, PositionRecord } from './repository.ts'
+
+/**
+ * Position: the person-to-company link, and the only place a job title lives.
+ *
+ * A bare company id on Person would force one title per person, which is wrong
+ * for advisors, founders, and anyone mid-move.
+ *
+ * A pure dependent. It dies with either side through its foreign keys, and
+ * nothing restricts on it, so deleting one is always allowed.
+ */
+
+export interface PositionsDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/** A position as the API returns one: the stored row minus the tenancy column. */
+export type PositionView = Omit<PositionRecord, 'workspaceId'>
+
+/** The two records a position joins. Both the create input and a stored row satisfy it. */
+export interface PositionEnds {
+  readonly personId: string
+  readonly companyId: string
+}
+
+export interface CreatePositionInput extends PositionEnds {
+  readonly title: string
+}
+
+/** Only the title can move. Repointing a link at a different person is a delete and a create. */
+export interface UpdatePositionInput {
+  readonly title?: string | undefined
+}
+
+export interface PositionsService {
+  list(
+    actor: Actor,
+    filters: PositionFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<PositionView>>
+  get(actor: Actor, id: string): Promise<PositionView>
+  create(actor: Actor, input: CreatePositionInput): Promise<PositionView>
+  update(actor: Actor, id: string, changes: UpdatePositionInput): Promise<PositionView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: PositionRecord): PositionView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function duplicatePosition(): AppError {
+  return AppError.conflict('That person already holds that title at that company', [
+    { field: 'title', message: 'Already held at this company' },
+  ])
+}
+
+export function createPositionsService(dependencies: PositionsDependencies): PositionsService {
+  async function require(workspaceId: string, id: string): Promise<PositionRecord> {
+    const position = await repository.findPosition(dependencies.db, workspaceId, id)
+
+    if (position === undefined) {
+      throw AppError.notFound('Position not found')
+    }
+
+    return position
+  }
+
+  /**
+   * Both ends must be in the caller's workspace.
+   *
+   * The foreign keys alone would let a request link to a record in another
+   * workspace, because they are global. Checking here is what makes the tenancy
+   * boundary hold, and a record on the far side of it reports as missing rather
+   * than as forbidden, per `api.md`.
+   *
+   * @returns Both names. The link activity names the far side on each end's
+   *   timeline, and re-reading two rows that were just read to say so would be
+   *   two queries spent on something already in hand.
+   */
+  async function requireEnds(
+    workspaceId: string,
+    input: PositionEnds,
+  ): Promise<{ personName: string; companyName: string }> {
+    const person = await personRepository.findPerson(dependencies.db, workspaceId, input.personId)
+
+    if (person === undefined) {
+      throw AppError.notFound('Person not found')
+    }
+
+    const company = await companyRepository.findCompany(
+      dependencies.db,
+      workspaceId,
+      input.companyId,
+    )
+
+    if (company === undefined) {
+      throw AppError.notFound('Company not found')
+    }
+
+    return { personName: person.name, companyName: company.name }
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, POSITION_SORTS, DEFAULT_POSITION_SORT)
+      const rows = await repository.listPositions(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(toPage(rows, window, (position) => position.id), toView)
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+      const ends = await requireEnds(workspaceId, input)
+      const id = dependencies.createId('position')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        let created: PositionRecord
+
+        try {
+          created = await repository.insertPosition(tx, {
+            id,
+            workspaceId,
+            personId: input.personId,
+            companyId: input.companyId,
+            title: input.title,
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicatePosition()
+          }
+
+          throw error
+        }
+
+        // Both ends. A position is the link itself and has no timeline of its
+        // own, so the event that matters is "this person is now at that
+        // company", which is news on each of their pages.
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: input.personId,
+          kind: 'linked',
+          ...describeLink('company', ends.companyName),
+        })
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'company',
+          targetId: input.companyId,
+          kind: 'linked',
+          ...describeLink('person', ends.personName),
+        })
+
+        events.emit('record.created', { workspaceId, objectType: 'position', recordId: created.id })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+
+      if (changes.title === undefined || changes.title === existing.title) {
+        return toView(existing)
+      }
+
+      const title = changes.title
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        let updated: PositionRecord | undefined
+
+        try {
+          updated = await repository.updatePosition(tx, workspaceId, id, {
+            title,
+            updatedAt: dependencies.now(),
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicatePosition()
+          }
+
+          throw error
+        }
+
+        if (updated === undefined) {
+          throw AppError.notFound('Position not found')
+        }
+
+        events.emit('record.updated', {
+          workspaceId,
+          objectType: 'position',
+          recordId: id,
+          changedFields: ['title'],
+        })
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        const position = await require(workspaceId, id)
+        const ends = await requireEnds(workspaceId, position)
+
+        await repository.deletePosition(tx, workspaceId, id)
+
+        // Both ends, mirroring the link. Only this route files the unlink: the
+        // foreign keys take positions with either end, and that path never
+        // reaches a service.
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: position.personId,
+          kind: 'unlinked',
+          ...describeUnlink('company', ends.companyName),
+        })
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'company',
+          targetId: position.companyId,
+          kind: 'unlinked',
+          ...describeUnlink('person', ends.personName),
+        })
+
+        events.emit('record.deleted', { workspaceId, objectType: 'position', recordId: id })
+      })
+    },
+  }
+}

package/src/modules/positions/tools.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools, toSet } from '../crudTools.ts'
+import { createBody, positionResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { PositionsService } from './service.ts'
+
+/** `positions_*`. Same schemas and mappers as `/v1/positions`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  person_id: idSetArg.optional().describe('Only the positions held by these people.'),
+  company_id: idSetArg.optional().describe('Only the positions held at these companies.'),
+})
+
+export function registerPositionsTools(mcp: McpToolRegistry, service: PositionsService): void {
+  registerCrudTools(mcp, {
+    resource: 'positions',
+    subject: 'position',
+    about:
+      'The link between a person and a company, and the only place a job title lives. ' +
+      'One person may hold several.',
+    service,
+    render: positionResponse,
+    listArgs,
+    toFilters: (args) => ({ personIds: toSet(args.person_id), companyIds: toSet(args.company_id) }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/raises/index.ts

@@ -0,0 +1,44 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountRaisesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createRaisesService } from './service.ts'
+import { registerRaisesTools } from './tools.ts'
+
+/**
+ * Raises: fundraising processes, one per firm per round.
+ *
+ * Requires its relations because creating one checks that the firm, stage,
+ * owner, and key people are all in the caller's workspace before linking them,
+ * and `activities` because every write leaves its timeline entry in the same
+ * transaction.
+ */
+export function createRaisesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'raises',
+    requires: ['companies', 'people', 'pipelines', 'activities'],
+
+    register(context) {
+      const service = createRaisesService({
+        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) => {
+        mountRaisesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerRaisesTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}