@kelpie/server 0.1.0

package/src/modules/decisions/repository.ts

@@ -0,0 +1,204 @@
+import { and, eq, ilike, inArray, or, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { companies } from '../companies/schema.ts'
+import { deals } from '../deals/schema.ts'
+import { opportunities } from '../opportunities/schema.ts'
+import { partnerships } from '../partnerships/schema.ts'
+import { people } from '../people/schema.ts'
+import { raises } from '../raises/schema.ts'
+import { workspaceMembers } from '../workspace/schema.ts'
+import { decisions } from './schema.ts'
+import type { RecordTargetType } from './schema.ts'
+
+export type DecisionRecord = typeof decisions.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type DecisionColumns = typeof decisions.$inferInsert
+
+export const DECISION_SORTS: SortableFields<DecisionRecord> = {
+  decided_at: timestampSort(decisions.decidedAt, (decision) => decision.decidedAt),
+  created_at: timestampSort(decisions.createdAt, (decision) => decision.createdAt),
+  updated_at: timestampSort(decisions.updatedAt, (decision) => decision.updatedAt),
+}
+
+/**
+ * The workspace list answers "what have we committed to lately", so the most
+ * recent decision leads. `due_at` is nullable, and a keyset cannot seek past a
+ * null, so it is not a sort.
+ */
+export const DEFAULT_DECISION_SORT = '-decided_at'
+
+export interface DecisionFilters {
+  /** `?target_type=`. On its own it lists every decision on that kind of record. */
+  readonly targetType?: RecordTargetType | undefined
+  /** `?target_id=`, repeatable: a panel asks with one, a roll-up with a set. */
+  readonly targetIds?: readonly string[] | undefined
+  readonly term?: string | undefined
+}
+
+/**
+ * The target tables `?q=` can name a record in. Ids join without a type gate
+ * because every id carries its prefix and matches at most one table.
+ *
+ * Candidate is missing: its label is the person behind the candidacy, two joins
+ * away, so a candidate-targeted decision matches on body and rationale only.
+ */
+const NAMED_TARGET_TABLES = [
+  { table: people, id: people.id, name: people.name },
+  { table: companies, id: companies.id, name: companies.name },
+  { table: deals, id: deals.id, name: deals.name },
+  { table: opportunities, id: opportunities.id, name: opportunities.name },
+  { table: partnerships, id: partnerships.id, name: partnerships.name },
+  { table: raises, id: raises.id, name: raises.name },
+]
+
+/**
+ * The target-name half of `?q=`. Reads the other modules' *tables*, never their
+ * repositories, the rule set for a filter spanning a relation
+ * (`architecture.md`).
+ */
+function targetNameMatches(pattern: string): SQL[] {
+  return NAMED_TARGET_TABLES.map(
+    ({ table, id, name }) => sql`exists (
+      select 1
+      from ${table}
+      where ${id} = ${decisions.targetId}
+        and ${name} ilike ${pattern}
+    )`,
+  )
+}
+
+/** The fields the mockup's decisions `FilterBar` matches: body, rationale, target type, target name. */
+function matchesTerm(term: string): SQL | undefined {
+  const pattern = containsPattern(term)
+
+  return or(
+    ilike(decisions.body, pattern),
+    ilike(decisions.rationale, pattern),
+    ilike(decisions.targetType, pattern),
+    ...targetNameMatches(pattern),
+  )
+}
+
+function conditionsFor(workspaceId: string, filters: DecisionFilters): (SQL | undefined)[] {
+  return [
+    eq(decisions.workspaceId, workspaceId),
+    filters.targetType === undefined ? undefined : eq(decisions.targetType, filters.targetType),
+    filters.targetIds === undefined ? undefined : inArray(decisions.targetId, filters.targetIds),
+    filters.term === undefined ? undefined : matchesTerm(filters.term),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listDecisions(
+  db: Queryable,
+  workspaceId: string,
+  filters: DecisionFilters,
+  window: ListWindow<DecisionRecord>,
+): Promise<DecisionRecord[]> {
+  return db
+    .select()
+    .from(decisions)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, decisions.id)))
+    .orderBy(...orderByWindow(window, decisions.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findDecision(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<DecisionRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(decisions)
+    .where(and(eq(decisions.workspaceId, workspaceId), eq(decisions.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertDecision(db: Queryable, values: DecisionColumns): Promise<DecisionRecord> {
+  const [created] = await db.insert(decisions).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting decision ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateDecision(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<DecisionColumns>,
+): Promise<DecisionRecord | undefined> {
+  const [updated] = await db
+    .update(decisions)
+    .set(changes)
+    .where(and(eq(decisions.workspaceId, workspaceId), eq(decisions.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteDecision(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(decisions)
+    .where(and(eq(decisions.workspaceId, workspaceId), eq(decisions.id, id)))
+    .returning({ id: decisions.id })
+
+  return deleted.length
+}
+
+/**
+ * Removes every decision attached to a target.
+ *
+ * The target is polymorphic and carries no foreign key, so nothing in the
+ * database deletes these. The service that deletes the target calls this inside
+ * the same transaction (`schema.md`).
+ */
+export async function deleteForTarget(
+  db: Queryable,
+  workspaceId: string,
+  targetType: string,
+  targetId: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(decisions)
+    .where(
+      and(
+        eq(decisions.workspaceId, workspaceId),
+        eq(decisions.targetType, targetType),
+        eq(decisions.targetId, targetId),
+      ),
+    )
+    .returning({ id: decisions.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
+}

package/src/modules/decisions/routes.ts

@@ -0,0 +1,184 @@
+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 type { DecisionFilters } from './repository.ts'
+import { RECORD_TARGET_TYPES } from './schema.ts'
+import type { RecordTargetType } from './schema.ts'
+import type {
+  CreateDecisionInput,
+  DecisionView,
+  DecisionsService,
+  UpdateDecisionInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/decisions`.
+ *
+ * Bodies are strict: `api.md` makes an unknown field a 422 rather than something
+ * dropped in silence.
+ */
+
+/**
+ * The full field set, without defaults. `createBody` adds those; `updateBody`
+ * makes it partial. `rationale` is `min(1)` because the column is nullable: an
+ * empty string and a null would be two spellings of "none", and a reader would
+ * have to check for both.
+ */
+const decisionShape = {
+  body: z.string().min(1),
+  rationale: z.string().min(1).nullable(),
+  decided_at: z.iso.datetime(),
+  owner_id: z.string().min(1).nullable(),
+  due_at: z.iso.datetime().nullable(),
+}
+
+/**
+ * Only the target and the body are required. An absent `decided_at` means now,
+ * and an absent `owner_id` means the caller — the mockup's panel stamps both
+ * onto every decision it records. `owner_id: null` says nobody carries it.
+ */
+export const createBody = z.strictObject({
+  ...decisionShape,
+  target_type: z.enum(RECORD_TARGET_TYPES),
+  target_id: z.string().min(1),
+  rationale: decisionShape.rationale.default(null),
+  decided_at: decisionShape.decided_at.optional(),
+  owner_id: decisionShape.owner_id.optional(),
+  due_at: decisionShape.due_at.default(null),
+})
+
+/** The target never moves. Re-filing a decision under another record is a delete and a create. */
+export const updateBody = z.strictObject(decisionShape).partial()
+
+export interface DecisionsRoutesDependencies extends CredentialDependencies {
+  readonly service: DecisionsService
+}
+
+export function decisionResponse(decision: DecisionView): Record<string, unknown> {
+  return {
+    id: decision.id,
+    target_type: decision.targetType,
+    target_id: decision.targetId,
+    body: decision.body,
+    rationale: decision.rationale,
+    decided_at: decision.decidedAt.toISOString(),
+    owner_id: decision.ownerId,
+    due_at: decision.dueAt === null ? null : decision.dueAt.toISOString(),
+    created_at: decision.createdAt.toISOString(),
+    updated_at: decision.updatedAt.toISOString(),
+  }
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateDecisionInput {
+  return {
+    targetType: body.target_type,
+    targetId: body.target_id,
+    body: body.body,
+    rationale: body.rationale,
+    decidedAt: body.decided_at === undefined ? undefined : new Date(body.decided_at),
+    ownerId: body.owner_id,
+    dueAt: body.due_at === null ? null : new Date(body.due_at),
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateDecisionInput {
+  return {
+    ...(body.body === undefined ? {} : { body: body.body }),
+    ...(body.rationale === undefined ? {} : { rationale: body.rationale }),
+    ...(body.decided_at === undefined ? {} : { decidedAt: new Date(body.decided_at) }),
+    ...(body.owner_id === undefined ? {} : { ownerId: body.owner_id }),
+    ...(body.due_at === undefined ? {} : { dueAt: body.due_at === null ? null : new Date(body.due_at) }),
+  }
+}
+
+/**
+ * `?target_type=`, one record type.
+ *
+ * @throws AppError 422 for a type nothing attaches a decision to. Answering it
+ *   with an empty list would read as "none yet" instead of "that is not a
+ *   thing".
+ */
+function readTargetType(context: Context): RecordTargetType | undefined {
+  const raw = context.req.query('target_type')
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  const parsed = z.enum(RECORD_TARGET_TYPES).safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed('That is not a record type a decision attaches to', [
+      { field: 'target_type', message: `Use one of: ${RECORD_TARGET_TYPES.join(', ')}` },
+    ])
+  }
+
+  return parsed.data
+}
+
+/**
+ * Unlike a note list, a decision list stands on its own: `/decisions` is a
+ * workspace page, so every filter here is optional.
+ */
+function readFilters(context: Context): DecisionFilters {
+  return {
+    targetType: readTargetType(context),
+    targetIds: readIdFilter(context, 'target_id'),
+    term: context.req.query('q'),
+  }
+}
+
+export function mountDecisionsRoutes(
+  router: Hono,
+  dependencies: DecisionsRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/decisions', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      readFilters(context),
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, decisionResponse))
+  })
+
+  router.post('/decisions', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const decision = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(decisionResponse(decision), 201)
+  })
+
+  router.get('/decisions/:id', async (context) => {
+    const decision = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(decisionResponse(decision))
+  })
+
+  router.patch('/decisions/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const decision = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(decisionResponse(decision))
+  })
+
+  router.delete('/decisions/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/decisions/schema.ts

@@ -0,0 +1,56 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { index, pgTable, text } from 'drizzle-orm/pg-core'
+
+import {
+  checkOneOf,
+  createdAt,
+  moment,
+  primaryId,
+  searchVector,
+  updatedAt,
+} from '../../lib/columns.ts'
+import type { SearchVectorPart } 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'
+
+/**
+ * What we decided or promised. These are the commitments agents must not
+ * contradict, which is why they are a queryable record rather than note text.
+ */
+export const decisions = pgTable(
+  'decisions',
+  {
+    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(),
+    rationale: text('rationale'),
+    decidedAt: moment('decided_at').notNull().defaultNow(),
+    ownerId: text('owner_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
+    dueAt: moment('due_at'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    // The body carries weight A because a decision has no name: the body is what
+    // the result list shows and what a reader recognises it by.
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: decisions.body, weight: 'A' },
+      { column: decisions.rationale, weight: 'B' },
+    ]),
+  },
+  (table) => [
+    index('decisions_target_idx').on(table.workspaceId, table.targetType, table.targetId),
+    index('decisions_search_idx').using('gin', table.searchVector),
+    checkOneOf('decisions_target_type_check', table.targetType, RECORD_TARGET_TYPES),
+  ],
+)

package/src/modules/decisions/service.ts

@@ -0,0 +1,223 @@
+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 type { Actor } from '../auth/actor.ts'
+import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import { targetExists } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import * as repository from './repository.ts'
+import { DECISION_SORTS, DEFAULT_DECISION_SORT } from './repository.ts'
+import type { DecisionFilters, DecisionRecord } from './repository.ts'
+
+/**
+ * Decisions: what the workspace decided or promised, kept queryable so agents
+ * can read the commitments they must not contradict.
+ *
+ * The target is polymorphic and has no foreign key, so this service is what
+ * refuses a decision attached to an id that does not exist or belongs to
+ * another workspace. Nothing in the database would.
+ *
+ * No activity rows. `ACTIVITY_KINDS` carries nothing that describes a decision,
+ * and filing one under `updated` would put a sentence on a timeline about a
+ * record the timeline is not for. Adding a kind is a check-constraint migration
+ * and belongs to whichever feature decides decision history is worth keeping.
+ */
+
+export interface DecisionsDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+}
+
+/** A decision as the API returns one: the stored row minus the tenancy column. */
+export type DecisionView = Omit<DecisionRecord, 'workspaceId'>
+
+export interface CreateDecisionInput {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly body: string
+  readonly rationale: string | null
+  /** Absent means now: most decisions are recorded as they are made. */
+  readonly decidedAt: Date | undefined
+  /**
+   * Absent means the caller, like a Deal: the mockup's panel files the decision
+   * under whoever recorded it. Null means nobody carries the commitment. A
+   * workspace API key has no member, so its absent owner is null too.
+   */
+  readonly ownerId: string | null | undefined
+  readonly dueAt: Date | null
+}
+
+/** PATCH semantics: an absent field is left alone. The target never moves. */
+export interface UpdateDecisionInput {
+  readonly body?: string | undefined
+  readonly rationale?: string | null | undefined
+  readonly decidedAt?: Date | undefined
+  readonly ownerId?: string | null | undefined
+  readonly dueAt?: Date | null | undefined
+}
+
+export interface DecisionsService {
+  list(
+    actor: Actor,
+    filters: DecisionFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<DecisionView>>
+  get(actor: Actor, id: string): Promise<DecisionView>
+  create(actor: Actor, input: CreateDecisionInput): Promise<DecisionView>
+  update(actor: Actor, id: string, changes: UpdateDecisionInput): Promise<DecisionView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: DecisionRecord): DecisionView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+export function createDecisionsService(dependencies: DecisionsDependencies): DecisionsService {
+  async function require(workspaceId: string, id: string): Promise<DecisionRecord> {
+    const decision = await repository.findDecision(dependencies.db, workspaceId, id)
+
+    // A decision in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (decision === undefined) {
+      throw AppError.notFound('Decision not found')
+    }
+
+    return decision
+  }
+
+  async function requireTarget(
+    workspaceId: string,
+    targetType: RecordTargetType,
+    targetId: string,
+  ): Promise<void> {
+    if (!(await targetExists(dependencies.db, workspaceId, targetType, targetId))) {
+      throw AppError.notFound('Record not found')
+    }
+  }
+
+  async function requireOwner(workspaceId: string, ownerId: string): Promise<void> {
+    if (!(await repository.memberExists(dependencies.db, workspaceId, ownerId))) {
+      throw AppError.notFound('Team member not found')
+    }
+  }
+
+  return {
+    // No target check here, unlike notes: this list is a workspace list first,
+    // and a filter naming an id that matches nothing answers with an empty
+    // page, the same as any other filter.
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, DECISION_SORTS, DEFAULT_DECISION_SORT)
+      const rows = await repository.listDecisions(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(
+        toPage(rows, window, (decision) => decision.id),
+        toView,
+      )
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await requireTarget(workspaceId, input.targetType, input.targetId)
+
+      const ownerId = input.ownerId === undefined ? actorMemberId(actor) : input.ownerId
+
+      if (ownerId !== null) {
+        await requireOwner(workspaceId, ownerId)
+      }
+
+      const id = dependencies.createId('decision')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const created = await repository.insertDecision(tx, {
+          id,
+          workspaceId,
+          targetType: input.targetType,
+          targetId: input.targetId,
+          body: input.body,
+          rationale: input.rationale,
+          decidedAt: input.decidedAt ?? dependencies.now(),
+          ownerId,
+          dueAt: input.dueAt,
+        })
+
+        // `decision.added` rather than `record.created`: the catalog gives
+        // decisions their own event, carrying the target, because a consumer
+        // watching a record wants the commitment without a second lookup to
+        // find out what it is attached to.
+        events.emit('decision.added', {
+          workspaceId,
+          decisionId: 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)
+
+      if (typeof changes.ownerId === 'string' && changes.ownerId !== existing.ownerId) {
+        await requireOwner(workspaceId, changes.ownerId)
+      }
+
+      const columns: Partial<repository.DecisionColumns> = {
+        ...(changes.body === undefined ? {} : { body: changes.body }),
+        ...(changes.rationale === undefined ? {} : { rationale: changes.rationale }),
+        ...(changes.decidedAt === undefined ? {} : { decidedAt: changes.decidedAt }),
+        ...(changes.ownerId === undefined ? {} : { ownerId: changes.ownerId }),
+        ...(changes.dueAt === undefined ? {} : { dueAt: changes.dueAt }),
+      }
+      const changed = changedKeys(existing, columns)
+
+      // A PATCH that changes nothing is not a write. Bumping `updated_at` for it
+      // would make the decision look freshly touched to anything sorting by it.
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      // No event. The catalog carries `decision.added` and nothing for a
+      // decision changing, and inventing a name here would add one the webhooks
+      // engine has never been told about.
+      return dependencies.transaction(async ({ tx }) => {
+        const updated = await repository.updateDecision(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (updated === undefined) {
+          throw AppError.notFound('Decision not found')
+        }
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      // No event, for the same reason an update has none. A withdrawn
+      // commitment simply stops being listable.
+      await dependencies.transaction(async ({ tx }) => {
+        await require(workspaceId, id)
+        await repository.deleteDecision(tx, workspaceId, id)
+      })
+    },
+  }
+}