@kelpie/server 0.5.2 → 0.6.0

package/src/modules/people/events.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the people module.
+ *
+ * The runtime catalog (below) is the authority; the `KelpieEventMap`
+ * augmentation gives autocomplete at every emit and subscribe site.
+ */
+
+export const PEOPLE_EVENT_NAMES = [
+  'people.person.created',
+  'people.person.updated',
+  'people.person.deleted',
+] as const
+
+export const peopleEvents = {
+  'people.person.created': z.object({}).strict(),
+  'people.person.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'people.person.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type PersonCreatedData = Record<string, never>
+export interface PersonUpdatedData {
+  readonly changed: readonly string[]
+}
+export type PersonDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'people.person.created': PersonCreatedData
+    'people.person.updated': PersonUpdatedData
+    'people.person.deleted': PersonDeletedData
+  }
+}

package/src/modules/people/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { peopleEvents } from './events.ts'
 import { mountPeopleRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createPeopleService } from './service.ts'
@@ -16,6 +17,7 @@ export function createPeopleModule(migrationsDirectory: string): KelpieModule {
     id: 'people',
     requires: ['workspace', 'activities'],
     structural: true,
+    events: peopleEvents,
 
     register(context) {
       const service = createPeopleService({

package/src/modules/people/service.ts

@@ -10,8 +10,10 @@ import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
 import { describeCreation, describeUpdate } from '../activities/wording.ts'
 import type { FieldLabels } from '../activities/wording.ts'
+import { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import {
   deleteRecordsAttachedTo,
   deleteRecordsAttachedToCandidaciesOf,
@@ -160,45 +162,48 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
       const workspaceId = requireWorkspaceId(actor)
       const id = dependencies.createId('person')
 
-      return dependencies.transaction(async ({ tx, events }) => {
-        let created: PersonRecord
-
-        try {
-          created = await repository.insertPerson(tx, {
-            id,
-            workspaceId,
-            name: input.name,
-            email: input.email === null ? null : normaliseEmail(input.email),
-            phones: input.phones,
-            socialProfiles: input.socialProfiles,
-            timezone: input.timezone,
-            location: input.location,
-            preferredChannel: input.preferredChannel,
-            influence: input.influence,
-            relationship: input.relationship,
-            summary: input.summary,
-            tags: [...input.tags],
-            lastContactedAt: input.lastContactedAt,
-          })
-        } catch (error: unknown) {
-          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
-            throw duplicateEmail()
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let created: PersonRecord
+
+          try {
+            created = await repository.insertPerson(tx, {
+              id,
+              workspaceId,
+              name: input.name,
+              email: input.email === null ? null : normaliseEmail(input.email),
+              phones: input.phones,
+              socialProfiles: input.socialProfiles,
+              timezone: input.timezone,
+              location: input.location,
+              preferredChannel: input.preferredChannel,
+              influence: input.influence,
+              relationship: input.relationship,
+              summary: input.summary,
+              tags: [...input.tags],
+              lastContactedAt: input.lastContactedAt,
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateEmail()
+            }
+
+            throw error
           }
 
-          throw error
-        }
-
-        await dependencies.recordActivity(tx, workspaceId, actor, {
-          targetType: 'person',
-          targetId: created.id,
-          kind: 'created',
-          ...describeCreation('Person'),
-        })
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'person',
+            targetId: created.id,
+            kind: 'created',
+            ...describeCreation('Person'),
+          })
 
-        events.emit('record.created', { workspaceId, objectType: 'person', recordId: created.id })
+          events.emit('people.person.created', { type: 'person', id: created.id }, {})
 
-        return toView(created)
-      })
+          return toView(created)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
     },
 
     async update(actor, id, changes) {
@@ -214,71 +219,76 @@ export function createPeopleService(dependencies: PeopleDependencies): PeopleSer
         return toView(existing)
       }
 
-      return dependencies.transaction(async ({ tx, events }) => {
-        let updated: PersonRecord | undefined
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          let updated: PersonRecord | undefined
+
+          try {
+            updated = await repository.updatePerson(tx, workspaceId, id, {
+              ...columns,
+              updatedAt: dependencies.now(),
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateEmail()
+            }
+
+            throw error
+          }
 
-        try {
-          updated = await repository.updatePerson(tx, workspaceId, id, {
-            ...columns,
-            updatedAt: dependencies.now(),
-          })
-        } catch (error: unknown) {
-          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
-            throw duplicateEmail()
+          if (updated === undefined) {
+            throw AppError.notFound('Person not found')
           }
 
-          throw error
-        }
-
-        if (updated === undefined) {
-          throw AppError.notFound('Person not found')
-        }
-
-        await dependencies.recordActivity(tx, workspaceId, actor, {
-          targetType: 'person',
-          targetId: id,
-          kind: 'updated',
-          ...describeUpdate(changed, PERSON_FIELD_LABELS, existing, columns),
-        })
-
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'person',
-          recordId: id,
-          changedFields: changed,
-        })
-
-        return toView(updated)
-      })
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'person',
+            targetId: id,
+            kind: 'updated',
+            ...describeUpdate(changed, PERSON_FIELD_LABELS, existing, columns),
+          })
+
+          events.emit(
+            'people.person.updated',
+            { type: 'person', id },
+            { changed },
+          )
+
+          return toView(updated)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
     },
 
     async remove(actor, id) {
       const workspaceId = requireWorkspaceId(actor)
 
-      await dependencies.transaction(async ({ tx, events }) => {
-        await require(workspaceId, id)
+      await dependencies.transaction(
+        async ({ tx, events }) => {
+          await require(workspaceId, id)
 
-        // Notes, activities and decisions carry no foreign key to their target,
-        // so nothing in the database removes them. Same transaction: if the
-        // delete below is refused, these come back with it.
-        await deleteRecordsAttachedTo(tx, workspaceId, 'person', id)
+          // Notes, activities and decisions carry no foreign key to their target,
+          // so nothing in the database removes them. Same transaction: if the
+          // delete below is refused, these come back with it.
+          await deleteRecordsAttachedTo(tx, workspaceId, 'person', id)
 
-        // The candidacy rows themselves cascade, which is why their interview
-        // notes have to be taken here: no hiring service sees that delete.
-        await deleteRecordsAttachedToCandidaciesOf(tx, workspaceId, id)
+          // The candidacy rows themselves cascade, which is why their interview
+          // notes have to be taken here: no hiring service sees that delete.
+          await deleteRecordsAttachedToCandidaciesOf(tx, workspaceId, id)
 
-        try {
-          await repository.deletePerson(tx, workspaceId, id)
-        } catch (error: unknown) {
-          if (isReferenceViolation(error)) {
-            throw referencedElsewhere(error, 'person')
-          }
+          try {
+            await repository.deletePerson(tx, workspaceId, id)
+          } catch (error: unknown) {
+            if (isReferenceViolation(error)) {
+              throw referencedElsewhere(error, 'person')
+            }
 
-          throw error
-        }
+            throw error
+          }
 
-        events.emit('record.deleted', { workspaceId, objectType: 'person', recordId: id })
-      })
+          events.emit('people.person.deleted', { type: 'person', id }, {})
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
     },
   }
 }

package/src/modules/pipelines/service.ts

@@ -8,8 +8,15 @@ import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
 import type { Transaction, TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
 import { describeStageChange } from '../activities/wording.ts'
+import { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+// The four owning modules register their `<kind>.<obj>.stage_changed` events;
+// pipelines fires them from cascade reassignments.
+import '../deals/events.ts'
+import '../opportunities/events.ts'
+import '../partnerships/events.ts'
+import '../raises/events.ts'
 import { referencedElsewhere } from '../references.ts'
 import { reassignStagedRecords } from '../stagedRecords.ts'
 import * as repository from './repository.ts'
@@ -310,13 +317,7 @@ export function createPipelineStagesService(
               kind: 'stage_changed',
               ...describeStageChange(stage.label, moveTo.label),
             })
-            events.emit('stage.changed', {
-              workspaceId,
-              objectType: kind,
-              recordId,
-              fromStageId: stage.id,
-              toStageId: moveTo.id,
-            })
+            emitStageChangedFor(events, kind, recordId, stage.id, moveTo.id)
           }
         }
 
@@ -333,7 +334,45 @@ export function createPipelineStagesService(
         }
 
         await renumber(tx, workspaceId, rows.filter((row) => row.id !== id))
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }
+
+/**
+ * Dispatches the stage-changed envelope for a moved record. Each of the four
+ * staged object types has its own event name in its owning module's catalog;
+ * pipelines is the emitter, not the owner.
+ */
+function emitStageChangedFor(
+  events: import('../../runtime/transaction.ts').BufferedEvents,
+  kind: PipelineKind,
+  recordId: string,
+  fromStageId: string,
+  toStageId: string,
+): void {
+  const data = { fromStageId, toStageId } as const
+
+  switch (kind) {
+    case 'deal':
+      events.emit('deals.deal.stage_changed', { type: 'deal', id: recordId }, data)
+      break
+    case 'opportunity':
+      events.emit(
+        'opportunities.opportunity.stage_changed',
+        { type: 'opportunity', id: recordId },
+        data,
+      )
+      break
+    case 'partnership':
+      events.emit(
+        'partnerships.partnership.stage_changed',
+        { type: 'partnership', id: recordId },
+        data,
+      )
+      break
+    case 'raise':
+      events.emit('raises.raise.stage_changed', { type: 'raise', id: recordId }, data)
+      break
+  }
+}

package/src/modules/plans/events.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the plans module.
+ *
+ * `target` is the record the plan item attaches to; the plan item's own id
+ * lives in `data`.
+ */
+
+export const plansEvents = {
+  'plans.plan_item.completed': z.object({ planItemId: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface PlanItemCompletedData {
+  readonly planItemId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'plans.plan_item.completed': PlanItemCompletedData
+  }
+}

package/src/modules/plans/index.ts

@@ -1,4 +1,5 @@
 import type { KelpieModule } from '../../runtime/module.ts'
+import { plansEvents } from './events.ts'
 import { mountPlansRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createPlansService } from './service.ts'
@@ -16,6 +17,7 @@ export function createPlansModule(migrationsDirectory: string): KelpieModule {
     id: 'plans',
     requires: ['workspace'],
     structural: true,
+    events: plansEvents,
 
     register(context) {
       const service = createPlansService({

package/src/modules/plans/service.ts

@@ -5,8 +5,10 @@ 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 { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { targetExists } from '../recordTargets.ts'
 import * as repository from './repository.ts'
 import { DEFAULT_PLAN_ITEM_SORT, PLAN_ITEM_SORTS } from './repository.ts'
@@ -149,16 +151,15 @@ export function createPlansService(dependencies: PlansDependencies): PlansServic
         // as already finished. A consumer watching for completed work cares that
         // the work is done, not whether it passed through `todo` on the way.
         if (created.status === 'done') {
-          events.emit('plan.completed', {
-            workspaceId,
-            planItemId: created.id,
-            targetType: created.targetType,
-            targetId: created.targetId,
-          })
+          events.emit(
+            'plans.plan_item.completed',
+            { type: created.targetType, id: created.targetId },
+            { planItemId: created.id },
+          )
         }
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -196,16 +197,15 @@ export function createPlansService(dependencies: PlansDependencies): PlansServic
         // On the transition only. Re-sending `done` on a finished item changes
         // nothing, and it is caught above before it reaches here.
         if (changed.includes('status') && updated.status === 'done') {
-          events.emit('plan.completed', {
-            workspaceId,
-            planItemId: updated.id,
-            targetType: updated.targetType,
-            targetId: updated.targetId,
-          })
+          events.emit(
+            'plans.plan_item.completed',
+            { type: updated.targetType, id: updated.targetId },
+            { planItemId: updated.id },
+          )
         }
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {

package/src/modules/positions/events.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the positions module. */
+
+export const positionsEvents = {
+  'positions.position.created': z.object({}).strict(),
+  'positions.position.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'positions.position.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type PositionCreatedData = Record<string, never>
+export interface PositionUpdatedData {
+  readonly changed: readonly string[]
+}
+export type PositionDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'positions.position.created': PositionCreatedData
+    'positions.position.updated': PositionUpdatedData
+    'positions.position.deleted': PositionDeletedData
+  }
+}

package/src/modules/positions/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { positionsEvents } from './events.ts'
 import { mountPositionsRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createPositionsService } from './service.ts'
@@ -15,6 +16,7 @@ export function createPositionsModule(migrationsDirectory: string): KelpieModule
   return {
     id: 'positions',
     requires: ['people', 'companies', 'activities'],
+    events: positionsEvents,
 
     register(context) {
       const service = createPositionsService({

package/src/modules/positions/service.ts

@@ -7,8 +7,10 @@ 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 { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import * as companyRepository from '../companies/repository.ts'
 import * as personRepository from '../people/repository.ts'
 import * as repository from './repository.ts'
@@ -174,10 +176,10 @@ export function createPositionsService(dependencies: PositionsDependencies): Pos
           ...describeLink('person', ends.personName),
         })
 
-        events.emit('record.created', { workspaceId, objectType: 'position', recordId: created.id })
+        events.emit('positions.position.created', { type: 'position', id: created.id }, {})
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -210,15 +212,10 @@ export function createPositionsService(dependencies: PositionsDependencies): Pos
           throw AppError.notFound('Position not found')
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'position',
-          recordId: id,
-          changedFields: ['title'],
-        })
+        events.emit('positions.position.updated', { type: 'position', id }, { changed: ['title'] })
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -246,8 +243,8 @@ export function createPositionsService(dependencies: PositionsDependencies): Pos
           ...describeUnlink('person', ends.personName),
         })
 
-        events.emit('record.deleted', { workspaceId, objectType: 'position', recordId: id })
-      })
+        events.emit('positions.position.deleted', { type: 'position', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/raises/events.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the raises module. */
+
+export const raisesEvents = {
+  'raises.raise.created': z.object({}).strict(),
+  'raises.raise.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'raises.raise.deleted': z.object({}).strict(),
+  'raises.raise.stage_changed': z.object({
+    fromStageId: z.string().nullable(),
+    toStageId: z.string(),
+  }),
+} satisfies ModuleEventCatalog
+
+export type RaiseCreatedData = Record<string, never>
+export interface RaiseUpdatedData {
+  readonly changed: readonly string[]
+}
+export type RaiseDeletedData = Record<string, never>
+export interface RaiseStageChangedData {
+  readonly fromStageId: string | null
+  readonly toStageId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'raises.raise.created': RaiseCreatedData
+    'raises.raise.updated': RaiseUpdatedData
+    'raises.raise.deleted': RaiseDeletedData
+    'raises.raise.stage_changed': RaiseStageChangedData
+  }
+}

package/src/modules/raises/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { raisesEvents } from './events.ts'
 import { mountRaisesRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createRaisesService } from './service.ts'
@@ -17,6 +18,7 @@ export function createRaisesModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'raises',
     requires: ['companies', 'people', 'pipelines', 'activities'],
+    events: raisesEvents,
 
     register(context) {
       const service = createRaisesService({