@kelpie/server 0.12.0 → 0.13.0

package/src/modules/dashboard/repository.ts

@@ -9,6 +9,7 @@ import { activities } from '../activities/schema.ts'
 import { decisions } from '../decisions/schema.ts'
 import { deals } from '../deals/schema.ts'
 import { enquiries } from '../enquiries/schema.ts'
+import { attendances, events } from '../events/schema.ts'
 import { notes } from '../notes/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
 import { partnerships } from '../partnerships/schema.ts'
@@ -242,6 +243,69 @@ export async function listPartnershipTouchpoints(
   )
 }
 
+/** A scheduled Event whose start is inside `[from, to)`. */
+export interface UpcomingEventRecord {
+  readonly id: string
+  readonly name: string
+  readonly startsAt: Date
+  readonly endsAt: Date
+  readonly format: string
+  readonly location: string
+  readonly attendeeCount: number
+  readonly ownerId: string | null
+}
+
+function upcomingEventConditions(workspaceId: string, from: Date, to: Date): (SQL | undefined)[] {
+  return [
+    eq(events.workspaceId, workspaceId),
+    eq(events.status, 'scheduled'),
+    gte(events.startsAt, from),
+    lt(events.startsAt, to),
+  ]
+}
+
+export async function countUpcomingEvents(
+  db: Queryable,
+  workspaceId: string,
+  from: Date,
+  to: Date,
+): Promise<number> {
+  const [row] = await db
+    .select({ total: count() })
+    .from(events)
+    .where(and(...upcomingEventConditions(workspaceId, from, to)))
+
+  return row?.total ?? 0
+}
+
+export async function listUpcomingEvents(
+  db: Queryable,
+  workspaceId: string,
+  from: Date,
+  to: Date,
+  limit: number,
+): Promise<readonly UpcomingEventRecord[]> {
+  const rows = await db
+    .select({
+      id: events.id,
+      name: events.name,
+      startsAt: events.startsAt,
+      endsAt: events.endsAt,
+      format: events.format,
+      location: events.location,
+      ownerId: events.ownerId,
+      attendeeCount: sql<number>`coalesce(count(${attendances.id}) filter (where ${attendances.status} <> 'cancelled'), 0)::int`,
+    })
+    .from(events)
+    .leftJoin(attendances, eq(attendances.eventId, events.id))
+    .where(and(...upcomingEventConditions(workspaceId, from, to)))
+    .groupBy(events.id)
+    .orderBy(asc(events.startsAt), asc(events.id))
+    .limit(limit)
+
+  return rows
+}
+
 /**
  * The calendar day a contact happened on, in the workspace's zone.
  *

package/src/modules/dashboard/routes.ts

@@ -15,6 +15,7 @@ import type {
   SignalList,
   StaleContactSignal,
   TouchpointSignal,
+  UpcomingEventSignal,
 } from './service.ts'
 
 /**
@@ -83,6 +84,19 @@ function touchpointBody(touchpoint: TouchpointSignal): Record<string, unknown> {
   }
 }
 
+function upcomingEventBody(event: UpcomingEventSignal): Record<string, unknown> {
+  return {
+    id: event.id,
+    name: event.name,
+    starts_at: event.startsAt.toISOString(),
+    ends_at: event.endsAt.toISOString(),
+    format: event.format,
+    location: event.location,
+    attendee_count: event.attendeeCount,
+    owner_id: event.ownerId,
+  }
+}
+
 function staleContactBody(contact: StaleContactSignal): Record<string, unknown> {
   return {
     id: contact.id,
@@ -147,6 +161,7 @@ export function dashboardResponse(snapshot: DashboardSnapshot): Record<string, u
     overdue_plan_items: signalListBody(snapshot.overduePlanItems, planItemBody),
     due_soon_plan_items: signalListBody(snapshot.dueSoonPlanItems, planItemBody),
     partnership_touchpoints: signalListBody(snapshot.partnershipTouchpoints, touchpointBody),
+    upcoming_events: signalListBody(snapshot.upcomingEvents, upcomingEventBody),
     stale_contacts: signalListBody(snapshot.staleContacts, staleContactBody),
     recent_activity: snapshot.recentActivity.map(activityBody),
     recent_notes: snapshot.recentNotes.map(noteBody),

package/src/modules/dashboard/service.ts

@@ -117,6 +117,17 @@ export interface DecisionSignal extends TargetRef {
   readonly dueAt: Date | null
 }
 
+export interface UpcomingEventSignal {
+  readonly id: string
+  readonly name: string
+  readonly startsAt: Date
+  readonly endsAt: Date
+  readonly format: string
+  readonly location: string
+  readonly attendeeCount: number
+  readonly ownerId: string | null
+}
+
 export interface DashboardSnapshot {
   readonly generatedAt: Date
   /** The day everything below was computed against, `YYYY-MM-DD`. */
@@ -129,6 +140,7 @@ export interface DashboardSnapshot {
   readonly overduePlanItems: SignalList<PlanItemSignal>
   readonly dueSoonPlanItems: SignalList<PlanItemSignal>
   readonly partnershipTouchpoints: SignalList<TouchpointSignal>
+  readonly upcomingEvents: SignalList<UpcomingEventSignal>
   readonly staleContacts: SignalList<StaleContactSignal>
   readonly recentActivity: readonly ActivitySignal[]
   readonly recentNotes: readonly NoteSignal[]
@@ -155,6 +167,10 @@ interface DayBounds {
   readonly through: string
   /** The first day a contact still counts as fresh. */
   readonly staleCutoff: string
+  /** Instant the upcoming Events window starts (now). */
+  readonly fromInstant: Date
+  /** Instant the upcoming Events window ends (now plus `UPCOMING_DAYS`). */
+  readonly throughInstant: Date
 }
 
 /** Everything read from the database, before any of it is named or shaped. */
@@ -163,6 +179,7 @@ interface SignalRows {
   readonly overduePlanItems: SignalList<repository.PlanItemRecord>
   readonly dueSoonPlanItems: SignalList<repository.PlanItemRecord>
   readonly partnershipTouchpoints: SignalList<repository.TouchpointRecord>
+  readonly upcomingEvents: SignalList<repository.UpcomingEventRecord>
   readonly staleContacts: SignalList<repository.StaleContactRecord>
   readonly recentActivity: readonly repository.ActivityRecord[]
   readonly recentNotes: readonly repository.NoteRecord[]
@@ -201,6 +218,19 @@ async function readTouchpoints(
   }
 }
 
+async function readUpcomingEvents(
+  db: Database,
+  workspaceId: string,
+  from: Date,
+  to: Date,
+  limit: number,
+): Promise<SignalList<repository.UpcomingEventRecord>> {
+  return {
+    total: await repository.countUpcomingEvents(db, workspaceId, from, to),
+    items: await repository.listUpcomingEvents(db, workspaceId, from, to, limit),
+  }
+}
+
 async function readStaleContacts(
   db: Database,
   workspaceId: string,
@@ -236,6 +266,7 @@ async function readSignals(
     overduePlanItems,
     dueSoonPlanItems,
     partnershipTouchpoints,
+    upcomingEvents,
     staleContacts,
     recentActivity,
     recentNotes,
@@ -245,6 +276,7 @@ async function readSignals(
     readPlanItems(db, workspaceId, { before: days.today }, limit),
     readPlanItems(db, workspaceId, { from: days.today, to: days.through }, limit),
     readTouchpoints(db, workspaceId, days.through, limit),
+    readUpcomingEvents(db, workspaceId, days.fromInstant, days.throughInstant, limit),
     readStaleContacts(db, workspaceId, timezone, days.staleCutoff, limit),
     repository.listRecentActivity(db, workspaceId, limit),
     repository.listRecentNotes(db, workspaceId, limit),
@@ -256,6 +288,7 @@ async function readSignals(
     overduePlanItems,
     dueSoonPlanItems,
     partnershipTouchpoints,
+    upcomingEvents,
     staleContacts,
     recentActivity,
     recentNotes,
@@ -376,6 +409,19 @@ function toSnapshot(
     overduePlanItems: toPlanItemSignal(rows.overduePlanItems, nameOf),
     dueSoonPlanItems: toPlanItemSignal(rows.dueSoonPlanItems, nameOf),
     partnershipTouchpoints: toTouchpointSignal(rows.partnershipTouchpoints, days.today),
+    upcomingEvents: {
+      total: rows.upcomingEvents.total,
+      items: rows.upcomingEvents.items.map((row) => ({
+        id: row.id,
+        name: row.name,
+        startsAt: row.startsAt,
+        endsAt: row.endsAt,
+        format: row.format,
+        location: row.location,
+        attendeeCount: row.attendeeCount,
+        ownerId: row.ownerId,
+      })),
+    },
     staleContacts: toStaleContactSignal(rows.staleContacts, days.today),
     recentActivity: rows.recentActivity.map((row) => ({
       id: row.id,
@@ -436,6 +482,8 @@ export function createDashboardService(dependencies: DashboardDependencies): Das
         today,
         through: upcomingEnd(today),
         staleCutoff: staleContactCutoff(today),
+        fromInstant: generatedAt,
+        throughInstant: new Date(generatedAt.getTime() + UPCOMING_DAYS * 24 * 60 * 60 * 1000),
       }
 
       const rows = await readSignals(dependencies.db, workspaceId, timezone, days, limit)

package/src/modules/decisions/repository.ts

@@ -8,6 +8,7 @@ import type { Queryable } from '../../runtime/transaction.ts'
 import { companies } from '../companies/schema.ts'
 import { deals } from '../deals/schema.ts'
 import { enquiries } from '../enquiries/schema.ts'
+import { events } from '../events/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
 import { partnerships } from '../partnerships/schema.ts'
 import { people } from '../people/schema.ts'
@@ -57,6 +58,7 @@ const NAMED_TARGET_TABLES = [
   { table: partnerships, id: partnerships.id, workspaceId: partnerships.workspaceId, name: partnerships.name },
   { table: raises, id: raises.id, workspaceId: raises.workspaceId, name: raises.name },
   { table: enquiries, id: enquiries.id, workspaceId: enquiries.workspaceId, name: enquiries.name },
+  { table: events, id: events.id, workspaceId: events.workspaceId, name: events.name },
 ]
 
 /**

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()
+    },
+  }
+}