@kelpie/server 0.1.0

package/src/modules/notes/routes.ts

@@ -0,0 +1,170 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+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 { isRecordTargetType } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import { RECORD_TARGET_TYPES } from './schema.ts'
+import type { CreateNoteInput, NoteView, NotesService, UpdateNoteInput } from './service.ts'
+
+/**
+ * Wire shapes for `/v1/notes`.
+ *
+ * Bodies are strict: `api.md` makes an unknown field a 422 rather than something
+ * dropped in silence.
+ */
+
+export const createBody = z.strictObject({
+  target_type: z.enum(RECORD_TARGET_TYPES),
+  target_id: z.string().min(1),
+  body: z.string().min(1),
+  pinned: z.boolean().default(false),
+})
+
+/** The target never moves. Re-filing a note under another record is a delete and a create. */
+export const updateBody = z
+  .strictObject({
+    body: z.string().min(1),
+    pinned: z.boolean(),
+  })
+  .partial()
+
+export interface NotesRoutesDependencies extends CredentialDependencies {
+  readonly service: NotesService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateNoteInput {
+  return {
+    targetType: body.target_type,
+    targetId: body.target_id,
+    body: body.body,
+    pinned: body.pinned,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateNoteInput {
+  return {
+    ...(body.body === undefined ? {} : { body: body.body }),
+    ...(body.pinned === undefined ? {} : { pinned: body.pinned }),
+  }
+}
+
+export function noteResponse(note: NoteView): Record<string, unknown> {
+  return {
+    id: note.id,
+    target_type: note.targetType,
+    target_id: note.targetId,
+    body: note.body,
+    author_id: note.authorId,
+    pinned: note.pinned,
+    created_at: note.createdAt.toISOString(),
+    updated_at: note.updatedAt.toISOString(),
+  }
+}
+
+/**
+ * A note list always names the records it belongs to. There is no workspace-wide
+ * note list in the mockup, and answering one by accident through an omitted
+ * filter would page a workspace's entire note history to render one panel.
+ *
+ * `?target_id=` repeats to name a set, per `api.md`, so a page rendering a note
+ * per row resolves them in one request instead of one per row. `?target_type=`
+ * stays single: the ids in one set are all the same kind of record, and a
+ * request mixing them would need the type paired with each id rather than
+ * alongside them.
+ *
+ * @throws AppError 422 when either half is missing, the type is unknown, an id
+ *   is blank or there are more than `MAX_FILTER_IDS`, or `?pinned=` is a word
+ *   that is not true or false.
+ */
+function readFilters(context: Context): {
+  targetType: RecordTargetType
+  targetIds: readonly string[]
+  pinned: boolean | undefined
+} {
+  const targetType = context.req.query('target_type')
+  const targetIds = readIdFilter(context, 'target_id')
+
+  if (targetType === undefined || targetIds === undefined) {
+    throw AppError.validationFailed('A note list always names the records it is for', [
+      { field: 'target_type', message: 'Required' },
+      { field: 'target_id', message: 'Required' },
+    ])
+  }
+
+  if (!isRecordTargetType(targetType)) {
+    throw AppError.validationFailed('That is not a record type a note attaches to', [
+      { field: 'target_type', message: `Unknown target type "${targetType}"` },
+    ])
+  }
+
+  return { targetType, targetIds, pinned: readPinned(context.req.query('pinned')) }
+}
+
+function readPinned(raw: string | undefined): boolean | undefined {
+  if (raw === undefined) {
+    return undefined
+  }
+
+  if (raw === 'true') {
+    return true
+  }
+
+  if (raw === 'false') {
+    return false
+  }
+
+  // Not defaulted to false: `?pinned=yes` asked a question, and answering the
+  // unpinned one instead is worse than saying the question was malformed.
+  throw AppError.validationFailed('"pinned" filters on true or false', [
+    { field: 'pinned', message: `Expected true or false, got "${raw}"` },
+  ])
+}
+
+export function mountNotesRoutes(router: Hono, dependencies: NotesRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/notes', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      readFilters(context),
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, noteResponse))
+  })
+
+  router.post('/notes', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const note = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(noteResponse(note), 201)
+  })
+
+  router.get('/notes/:id', async (context) => {
+    const note = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(noteResponse(note))
+  })
+
+  router.patch('/notes/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const note = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(noteResponse(note))
+  })
+
+  router.delete('/notes/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/notes/schema.ts

@@ -0,0 +1,42 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { boolean, index, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, primaryId, updatedAt } from '../../lib/columns.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/**
+ * The target types come from `@kelpie/schemas`, so this check constraint, the
+ * route's Zod enum, and the browser's decoder are one list rather than three
+ * copies. Re-exported because `routes.ts` and `service.ts` read them from here,
+ * and the table they constrain is the reason they matter.
+ */
+export { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+export type { RecordTargetType } from '@kelpie/schemas'
+
+/**
+ * Notes attach to any CRM object. The target is polymorphic with no database
+ * foreign key, so the owning service deletes dependents in the same transaction
+ * as the parent.
+ *
+ * Pinned notes are what agents read first.
+ */
+export const notes = pgTable(
+  'notes',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    body: text('body').notNull(),
+    authorId: text('author_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
+    pinned: boolean('pinned').notNull().default(false),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('notes_target_idx').on(table.workspaceId, table.targetType, table.targetId),
+    checkOneOf('notes_target_type_check', table.targetType, RECORD_TARGET_TYPES),
+  ],
+)

package/src/modules/notes/service.ts

@@ -0,0 +1,204 @@
+import { changedKeys } from '../../lib/changes.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 { describeNote } from '../activities/wording.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import type { Actor } from '../auth/actor.ts'
+import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import { missingTargets } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_NOTE_SORT, NOTE_SORTS } from './repository.ts'
+import type { NoteFilters, NoteRecord } from './repository.ts'
+
+/**
+ * Notes: what a person wrote down about a record.
+ *
+ * The target is polymorphic and has no foreign key, so this service is what
+ * refuses a note attached to an id that does not exist or belongs to another
+ * workspace. Nothing in the database would.
+ *
+ * Writing a note is history: it records a `note_added` activity in the same
+ * transaction, so a note that commits always has the timeline entry announcing
+ * it. Editing one does not. A note's body changing is not an event anyone needs
+ * on a timeline, and a row per typo fix would bury the entries that matter.
+ */
+
+export interface NotesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/** A note as the API returns one: the stored row minus the tenancy column. */
+export type NoteView = Omit<NoteRecord, 'workspaceId'>
+
+export interface CreateNoteInput {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly body: string
+  readonly pinned: boolean
+}
+
+/** PATCH semantics: an absent field is left alone. The target never moves. */
+export interface UpdateNoteInput {
+  readonly body?: string | undefined
+  readonly pinned?: boolean | undefined
+}
+
+export interface NotesService {
+  list(actor: Actor, filters: NoteFilters, query: ListQueryParameters): Promise<Page<NoteView>>
+  get(actor: Actor, id: string): Promise<NoteView>
+  create(actor: Actor, input: CreateNoteInput): Promise<NoteView>
+  update(actor: Actor, id: string, changes: UpdateNoteInput): Promise<NoteView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: NoteRecord): NoteView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+export function createNotesService(dependencies: NotesDependencies): NotesService {
+  async function require(workspaceId: string, id: string): Promise<NoteRecord> {
+    const note = await repository.findNote(dependencies.db, workspaceId, id)
+
+    // A note in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (note === undefined) {
+      throw AppError.notFound('Note not found')
+    }
+
+    return note
+  }
+
+  /**
+   * Every id has to resolve. One that does not fails the whole list rather than
+   * being dropped from the set: a caller asking about five records and getting
+   * four records' notes back has no way to tell which of the five it asked about
+   * was the empty one.
+   */
+  async function requireTargets(
+    workspaceId: string,
+    targetType: RecordTargetType,
+    targetIds: readonly string[],
+  ): Promise<void> {
+    const missing = await missingTargets(dependencies.db, workspaceId, targetType, targetIds)
+
+    if (missing.length > 0) {
+      throw AppError.notFound('Record not found')
+    }
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await requireTargets(workspaceId, filters.targetType, filters.targetIds)
+
+      const window = readListWindow(query, NOTE_SORTS, DEFAULT_NOTE_SORT)
+      const rows = await repository.listNotes(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(
+        toPage(rows, window, (note) => note.id),
+        toView,
+      )
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await requireTargets(workspaceId, input.targetType, [input.targetId])
+
+      const id = dependencies.createId('note')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const created = await repository.insertNote(tx, {
+          id,
+          workspaceId,
+          targetType: input.targetType,
+          targetId: input.targetId,
+          body: input.body,
+          authorId: actorMemberId(actor),
+          pinned: input.pinned,
+        })
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: input.targetType,
+          targetId: input.targetId,
+          kind: 'note_added',
+          ...describeNote(input.body),
+        })
+
+        // `note.added` rather than `record.created`: the catalog gives notes
+        // their own event, carrying the target, because a consumer watching a
+        // record wants the note without a second lookup to find out what it is
+        // attached to.
+        events.emit('note.added', {
+          workspaceId,
+          noteId: created.id,
+          targetType: created.targetType,
+          targetId: created.targetId,
+        })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns: Partial<repository.NoteColumns> = {
+        ...(changes.body === undefined ? {} : { body: changes.body }),
+        ...(changes.pinned === undefined ? {} : { pinned: changes.pinned }),
+      }
+      const changed = changedKeys(existing, columns)
+
+      // A PATCH that changes nothing is not a write. Bumping `updated_at` for it
+      // would make the note look freshly touched to anything sorting by it.
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      // No event. The catalog carries `note.added` and nothing for a note
+      // changing or going away, and inventing one here would add a name the
+      // webhooks engine has never been told about. Recorded as a follow-up.
+      return dependencies.transaction(async ({ tx }) => {
+        const updated = await repository.updateNote(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (updated === undefined) {
+          throw AppError.notFound('Note not found')
+        }
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx }) => {
+        await require(workspaceId, id)
+        await repository.deleteNote(tx, workspaceId, id)
+
+        // The `note_added` activity stays. It records something that did
+        // happen, and rewriting history to match the present is what an
+        // append-only table exists to prevent.
+      })
+    },
+  }
+}

package/src/modules/notes/tools.ts

@@ -0,0 +1,46 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools } from '../crudTools.ts'
+import { createBody, noteResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { NotesService } from './service.ts'
+
+/** `notes_*`. Same schemas and mappers as `/v1/notes`. */
+
+/**
+ * `target_type` and `target_id` are required, exactly as they are on the REST
+ * list. A note list always names the records it is for; there is no "every note
+ * in the workspace" question to ask.
+ */
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  target_type: z.enum(RECORD_TARGET_TYPES).describe('The kind of record these notes are on.'),
+  target_id: idSetArg.describe('The records to read notes from. One id, or a page of them.'),
+  pinned: z
+    .boolean()
+    .optional()
+    .describe('True for pinned notes only. Pinned notes carry the signal; prefer them.'),
+})
+
+export function registerNotesTools(mcp: McpToolRegistry, service: NotesService): void {
+  registerCrudTools(mcp, {
+    resource: 'notes',
+    subject: 'note',
+    about: 'Freeform text attached to any record. A pinned one is what somebody wanted read first.',
+    service,
+    render: noteResponse,
+    listArgs,
+    toFilters: (args) => ({
+      targetType: args.target_type,
+      // Not `toSet`, whose undefined case cannot happen here and would have to be
+      // defaulted to an empty array that means the opposite of what it looks like.
+      targetIds: typeof args.target_id === 'string' ? [args.target_id] : args.target_id,
+      pinned: args.pinned,
+    }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/opportunities/index.ts

@@ -0,0 +1,44 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountOpportunitiesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createOpportunitiesService } from './service.ts'
+import { registerOpportunitiesTools } from './tools.ts'
+
+/**
+ * Opportunities: the non-sales pipeline.
+ *
+ * Requires its relations because creating one checks that the company, stage,
+ * and owner 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 createOpportunitiesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'opportunities',
+    requires: ['companies', 'pipelines', 'activities'],
+
+    register(context) {
+      const service = createOpportunitiesService({
+        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) => {
+        mountOpportunitiesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerOpportunitiesTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/opportunities/repository.ts

@@ -0,0 +1,157 @@
+import { and, eq, ilike, inArray, or, sql } 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 { arrayContainsPattern, containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { companies } from '../companies/schema.ts'
+import { workspaceMembers } from '../workspace/schema.ts'
+import { opportunities } from './schema.ts'
+
+export type OpportunityRecord = typeof opportunities.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type OpportunityColumns = typeof opportunities.$inferInsert
+
+/** The sort fields `?sort=` documents. The nullable close date stays out: a keyset cannot seek past a null. */
+export const OPPORTUNITY_SORTS: SortableFields<OpportunityRecord> = {
+  name: textSort(opportunities.name, (opportunity) => opportunity.name),
+  created_at: timestampSort(opportunities.createdAt, (opportunity) => opportunity.createdAt),
+  updated_at: timestampSort(opportunities.updatedAt, (opportunity) => opportunity.updatedAt),
+}
+
+export const DEFAULT_OPPORTUNITY_SORT = '-created_at'
+
+export interface OpportunityFilters {
+  /** `?q=`: name, kind, summary, tags, or the company's name. */
+  readonly term?: string | undefined
+  /** `?kind=`, repeatable: kinds are free text, so a match is exact, not fuzzy. */
+  readonly kinds?: readonly string[] | undefined
+  /** `?company_id=`, repeatable. */
+  readonly companyIds?: readonly string[] | undefined
+  /** `?stage_id=`, repeatable: the board fetches one column with one of these. */
+  readonly stageIds?: readonly string[] | undefined
+}
+
+/**
+ * The company half of `?q=`. Reads the `companies` *table*, never its
+ * repository, the rule set for a filter spanning a relation (`architecture.md`).
+ */
+function companyNameMatches(pattern: string): SQL {
+  return sql`exists (
+    select 1
+    from ${companies}
+    where ${companies.id} = ${opportunities.companyId}
+      and ${companies.name} ilike ${pattern}
+  )`
+}
+
+function matchesTerm(term: string): SQL | undefined {
+  const pattern = containsPattern(term)
+
+  return or(
+    ilike(opportunities.name, pattern),
+    ilike(opportunities.kind, pattern),
+    ilike(opportunities.summary, pattern),
+    arrayContainsPattern(opportunities.tags, pattern),
+    companyNameMatches(pattern),
+  )
+}
+
+function conditionsFor(workspaceId: string, filters: OpportunityFilters): (SQL | undefined)[] {
+  return [
+    eq(opportunities.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : matchesTerm(filters.term),
+    filters.kinds === undefined ? undefined : inArray(opportunities.kind, filters.kinds),
+    filters.companyIds === undefined
+      ? undefined
+      : inArray(opportunities.companyId, filters.companyIds),
+    filters.stageIds === undefined ? undefined : inArray(opportunities.stageId, filters.stageIds),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listOpportunities(
+  db: Queryable,
+  workspaceId: string,
+  filters: OpportunityFilters,
+  window: ListWindow<OpportunityRecord>,
+): Promise<OpportunityRecord[]> {
+  return db
+    .select()
+    .from(opportunities)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, opportunities.id)))
+    .orderBy(...orderByWindow(window, opportunities.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findOpportunity(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<OpportunityRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(opportunities)
+    .where(and(eq(opportunities.workspaceId, workspaceId), eq(opportunities.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertOpportunity(
+  db: Queryable,
+  values: OpportunityColumns,
+): Promise<OpportunityRecord> {
+  const [created] = await db.insert(opportunities).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting opportunity ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateOpportunity(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<OpportunityColumns>,
+): Promise<OpportunityRecord | undefined> {
+  const [updated] = await db
+    .update(opportunities)
+    .set(changes)
+    .where(and(eq(opportunities.workspaceId, workspaceId), eq(opportunities.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteOpportunity(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(opportunities)
+    .where(and(eq(opportunities.workspaceId, workspaceId), eq(opportunities.id, id)))
+    .returning({ id: opportunities.id })
+
+  return deleted.length
+}
+
+/** Whether a member belongs to this workspace, for validating `owner_id`. */
+export async function memberExists(
+  db: Queryable,
+  workspaceId: string,
+  memberId: string,
+): Promise<boolean> {
+  const [found] = await db
+    .select({ id: workspaceMembers.id })
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.id, memberId)))
+    .limit(1)
+
+  return found !== undefined
+}