@kelpie/server 0.12.0 → 0.14.0

package/src/modules/events/attendances.ts

@@ -0,0 +1,245 @@
+import { ATTENDANCE_STATUS_LABELS } from '@kelpie/schemas'
+import type { AttendanceSource, AttendanceStatus } from '@kelpie/schemas'
+
+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 { toEventActor } from '../../lib/actor.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import { describeLink, describeUnlink, describeUpdate } from '../activities/wording.ts'
+import type { FieldLabels } from '../activities/wording.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import * as personLinks from '../personLinks.ts'
+import './catalog.ts'
+import * as repository from './repository.ts'
+import { ATTENDANCE_SORTS, DEFAULT_ATTENDANCE_SORT } from './repository.ts'
+import type { AttendanceFilters, AttendanceRecord } from './repository.ts'
+
+export interface AttendancesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+const ATTENDANCE_FIELD_LABELS: FieldLabels = {
+  status: 'Attendance status',
+}
+
+export type AttendanceView = Omit<AttendanceRecord, 'workspaceId'>
+
+export interface CreateAttendanceInput {
+  readonly eventId: string
+  readonly personId: string
+  readonly status: AttendanceStatus
+  readonly source: AttendanceSource
+}
+
+export interface UpdateAttendanceInput {
+  readonly status?: AttendanceStatus | undefined
+}
+
+export interface AttendancesService {
+  list(
+    actor: Actor,
+    filters: AttendanceFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<AttendanceView>>
+  get(actor: Actor, id: string): Promise<AttendanceView>
+  create(actor: Actor, input: CreateAttendanceInput): Promise<AttendanceView>
+  update(actor: Actor, id: string, changes: UpdateAttendanceInput): Promise<AttendanceView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: AttendanceRecord): AttendanceView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function duplicateAttendance(): AppError {
+  return AppError.conflict('That person is already registered for that event', [
+    { field: 'person_id', message: 'Already registered for this event' },
+  ])
+}
+
+export function createAttendancesService(
+  dependencies: AttendancesDependencies,
+): AttendancesService {
+  async function require(workspaceId: string, id: string): Promise<AttendanceRecord> {
+    const row = await repository.findAttendance(dependencies.db, workspaceId, id)
+
+    if (row === undefined) {
+      throw AppError.notFound('Attendance not found')
+    }
+
+    return row
+  }
+
+  async function requireEvent(workspaceId: string, eventId: string): Promise<string> {
+    const event = await repository.findEvent(dependencies.db, workspaceId, eventId)
+
+    if (event === undefined) {
+      throw AppError.notFound('Event not found')
+    }
+
+    return event.name
+  }
+
+  async function requirePerson(workspaceId: string, personId: string): Promise<string> {
+    const named = await personLinks.findPeopleNamed(dependencies.db, workspaceId, [personId])
+    const name = named.get(personId)
+
+    if (name === undefined) {
+      throw AppError.notFound('Person not found')
+    }
+
+    return name
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, ATTENDANCE_SORTS, DEFAULT_ATTENDANCE_SORT)
+      const rows = await repository.listAttendances(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 eventName = await requireEvent(workspaceId, input.eventId)
+      const personName = await requirePerson(workspaceId, input.personId)
+      const id = dependencies.createId('attendance')
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let created: AttendanceRecord
+
+          try {
+            created = await repository.insertAttendance(tx, {
+              id,
+              workspaceId,
+              eventId: input.eventId,
+              personId: input.personId,
+              status: input.status,
+              source: input.source,
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateAttendance()
+            }
+
+            throw error
+          }
+
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'event',
+            targetId: input.eventId,
+            kind: 'linked',
+            ...describeLink('person', personName),
+          })
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'person',
+            targetId: input.personId,
+            kind: 'linked',
+            ...describeLink('event', eventName),
+          })
+
+          events.emit('events.attendance.created', { type: 'attendance', id }, {})
+
+          return toView(created)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns: Partial<repository.AttendanceColumns> = {
+        ...(changes.status === undefined ? {} : { status: changes.status }),
+      }
+      const changed = changedKeys(existing, columns)
+
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          const updated = await repository.updateAttendance(tx, workspaceId, id, {
+            ...columns,
+            updatedAt: dependencies.now(),
+          })
+
+          if (updated === undefined) {
+            throw AppError.notFound('Attendance not found')
+          }
+
+          const before = {
+            status: ATTENDANCE_STATUS_LABELS[existing.status as AttendanceStatus],
+          }
+          const after = {
+            status:
+              ATTENDANCE_STATUS_LABELS[(columns.status as AttendanceStatus | undefined) ?? existing.status as AttendanceStatus],
+          }
+
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'attendance',
+            targetId: id,
+            kind: 'updated',
+            ...describeUpdate(changed, ATTENDANCE_FIELD_LABELS, before, after),
+          })
+
+          events.emit('events.attendance.updated', { type: 'attendance', id }, { changed })
+
+          return toView(updated)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const eventName = await requireEvent(workspaceId, existing.eventId)
+      const personName = await requirePerson(workspaceId, existing.personId)
+
+      await dependencies.transaction(
+        async ({ tx, events }) => {
+          await deleteRecordsAttachedTo(tx, workspaceId, 'attendance', id)
+          await repository.deleteAttendance(tx, workspaceId, id)
+
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'event',
+            targetId: existing.eventId,
+            kind: 'unlinked',
+            ...describeUnlink('person', personName),
+          })
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'person',
+            targetId: existing.personId,
+            kind: 'unlinked',
+            ...describeUnlink('event', eventName),
+          })
+
+          events.emit('events.attendance.deleted', { type: 'attendance', id }, {})
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+  }
+}

package/src/modules/events/catalog.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the events module (CRM gatherings + attendances). */
+
+export const crmEventsCatalog = {
+  'events.event.created': z.object({}).strict(),
+  'events.event.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'events.event.deleted': z.object({}).strict(),
+  'events.attendance.created': z.object({}).strict(),
+  'events.attendance.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'events.attendance.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type CrmEventCreatedData = Record<string, never>
+export interface CrmEventUpdatedData {
+  readonly changed: readonly string[]
+}
+export type CrmEventDeletedData = Record<string, never>
+export type AttendanceCreatedData = Record<string, never>
+export interface AttendanceUpdatedData {
+  readonly changed: readonly string[]
+}
+export type AttendanceDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'events.event.created': CrmEventCreatedData
+    'events.event.updated': CrmEventUpdatedData
+    'events.event.deleted': CrmEventDeletedData
+    'events.attendance.created': AttendanceCreatedData
+    'events.attendance.updated': AttendanceUpdatedData
+    'events.attendance.deleted': AttendanceDeletedData
+  }
+}

package/src/modules/events/index.ts

@@ -0,0 +1,54 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { createCustomFieldValues } from '../custom-fields/index.ts'
+import { createAttendancesService } from './attendances.ts'
+import { crmEventsCatalog } from './catalog.ts'
+import { mountEventsRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createEventsService } from './service.ts'
+import { registerEventsTools } from './tools.ts'
+
+/**
+ * Events: dated gatherings, attendances, and Event-only associations.
+ *
+ * Requires people (attendees), activities (timeline), and custom-fields
+ * (workspace-defined attributes on the Event). Associations resolve other
+ * modules' tables directly, the way notes resolve polymorphic targets.
+ */
+export function createEventsModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'events',
+    requires: ['people', 'activities', 'custom-fields'],
+    events: crmEventsCatalog,
+
+    register(context) {
+      const recordActivity = createActivityRecorder({
+        createId: context.createId,
+        now: context.now,
+      })
+      const shared = {
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity,
+      }
+
+      context.schema(schema, migrationsDirectory)
+
+      const events = createEventsService({
+        ...shared,
+        customFields: createCustomFieldValues({ db: context.db }),
+      })
+      const attendances = createAttendancesService(shared)
+
+      context.routes((router) => {
+        mountEventsRoutes(router, { db: context.db, now: context.now, events, attendances })
+      })
+
+      registerEventsTools(context.mcp, { events, attendances })
+
+      return Promise.resolve()
+    },
+  }
+}