@kelpie/server 0.5.1 → 0.6.0

package/src/modules/hiring/candidates.ts

@@ -12,8 +12,10 @@ 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 { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as repository from './repository.ts'
 import { DEFAULT_CANDIDATE_SORT, CANDIDATE_SORTS } from './repository.ts'
@@ -287,10 +289,10 @@ export function createCandidatesService(dependencies: CandidatesDependencies): C
           ...describeLink('role', roleTitle),
         })
 
-        events.emit('record.created', { workspaceId, objectType: 'candidate', recordId: id })
+        events.emit('hiring.candidate.created', { type: 'candidate', id }, {})
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -354,15 +356,10 @@ export function createCandidatesService(dependencies: CandidatesDependencies): C
           ),
         })
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'candidate',
-          recordId: id,
-          changedFields: changed,
-        })
+        events.emit('hiring.candidate.updated', { type: 'candidate', id }, { changed })
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -384,8 +381,8 @@ export function createCandidatesService(dependencies: CandidatesDependencies): C
           ...describeUnlink('role', roleTitle),
         })
 
-        events.emit('record.deleted', { workspaceId, objectType: 'candidate', recordId: id })
-      })
+        events.emit('hiring.candidate.deleted', { type: 'candidate', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/hiring/events.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the hiring module (roles + candidates). */
+
+export const hiringEvents = {
+  'hiring.role.created': z.object({}).strict(),
+  'hiring.role.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'hiring.role.deleted': z.object({}).strict(),
+  'hiring.candidate.created': z.object({}).strict(),
+  'hiring.candidate.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'hiring.candidate.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type RoleCreatedData = Record<string, never>
+export interface RoleUpdatedData {
+  readonly changed: readonly string[]
+}
+export type RoleDeletedData = Record<string, never>
+export type CandidateCreatedData = Record<string, never>
+export interface CandidateUpdatedData {
+  readonly changed: readonly string[]
+}
+export type CandidateDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'hiring.role.created': RoleCreatedData
+    'hiring.role.updated': RoleUpdatedData
+    'hiring.role.deleted': RoleDeletedData
+    'hiring.candidate.created': CandidateCreatedData
+    'hiring.candidate.updated': CandidateUpdatedData
+    'hiring.candidate.deleted': CandidateDeletedData
+  }
+}

package/src/modules/hiring/index.ts

@@ -1,6 +1,7 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
 import { createCandidatesService } from './candidates.ts'
+import { hiringEvents } from './events.ts'
 import { createRolesService } from './roles.ts'
 import { mountHiringRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -22,6 +23,7 @@ export function createHiringModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'hiring',
     requires: ['people', 'activities'],
+    events: hiringEvents,
 
     register(context) {
       const recordActivity = createActivityRecorder({

package/src/modules/hiring/roles.ts

@@ -9,8 +9,10 @@ import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
 import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
 import { 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 { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as repository from './repository.ts'
 import { DEFAULT_ROLE_SORT, ROLE_SORTS } from './repository.ts'
@@ -103,10 +105,10 @@ export function createRolesService(dependencies: RolesDependencies): RolesServic
           status: input.status,
         })
 
-        events.emit('record.created', { workspaceId, objectType: 'role', recordId: id })
+        events.emit('hiring.role.created', { type: 'role', id }, {})
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -129,15 +131,10 @@ export function createRolesService(dependencies: RolesDependencies): RolesServic
           throw AppError.notFound('Role not found')
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'role',
-          recordId: id,
-          changedFields: changed,
-        })
+        events.emit('hiring.role.updated', { type: 'role', id }, { changed })
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     /**
@@ -167,8 +164,8 @@ export function createRolesService(dependencies: RolesDependencies): RolesServic
 
         await repository.deleteRole(tx, workspaceId, id)
 
-        events.emit('record.deleted', { workspaceId, objectType: 'role', recordId: id })
-      })
+        events.emit('hiring.role.deleted', { type: 'role', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/import-export/events.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the import-export module.
+ *
+ * Record events (`people.person.created`, etc.) fire from this module during
+ * an import, but they are owned by the record's module and declared in its
+ * catalog. `imports.job.completed` is what this module owns.
+ */
+
+export const importExportEvents = {
+  'imports.job.completed': z.object({ object: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface ImportCompletedData {
+  readonly object: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'imports.job.completed': ImportCompletedData
+  }
+}

package/src/modules/import-export/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { importExportEvents } from './events.ts'
 import { mountImportExportRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createImportExportService } from './service.ts'
@@ -21,6 +22,7 @@ export function createImportExportModule(migrationsDirectory: string): KelpieMod
   return {
     id: 'import-export',
     requires: ['people', 'companies', 'positions', 'pipelines', 'deals', 'activities'],
+    events: importExportEvents,
 
     register(context) {
       const service = createImportExportService({

package/src/modules/import-export/service.ts

@@ -24,10 +24,78 @@ import { AppError, describeThrown } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import type { Logger } from '../../lib/logger.ts'
 import { normaliseDomain, normaliseEmail } from '../../lib/normalisation.ts'
-import type { Queryable, TransactionScope } from '../../runtime/transaction.ts'
+import type { BufferedEvents, Queryable, TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
+import { toEventActor } from '../../lib/actor.ts'
+import type { RecordObjectType } from '../../runtime/events.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
+import '../companies/events.ts'
+import '../deals/events.ts'
+import '../people/events.ts'
+import '../positions/events.ts'
+import './events.ts'
+
+/**
+ * Fires the created event owned by the record's module for one imported row.
+ * Split from the loop so TypeScript can correlate the object type with its
+ * typed event name at each call site.
+ */
+function emitImportedRecordCreated(
+  events: BufferedEvents,
+  objectType: RecordObjectType,
+  recordId: string,
+): void {
+  switch (objectType) {
+    case 'person':
+      events.emit('people.person.created', { type: 'person', id: recordId }, {})
+      return
+    case 'company':
+      events.emit('companies.company.created', { type: 'company', id: recordId }, {})
+      return
+    case 'position':
+      events.emit('positions.position.created', { type: 'position', id: recordId }, {})
+      return
+    case 'deal':
+      events.emit('deals.deal.created', { type: 'deal', id: recordId }, {})
+      return
+    // The remaining `RecordObjectType` values are not produced by an import.
+    default:
+      throw new Error(`import produced an unexpected object type: ${objectType}`)
+  }
+}
+
+function emitImportedRecordUpdated(
+  events: BufferedEvents,
+  objectType: RecordObjectType,
+  recordId: string,
+  changed: readonly string[],
+): void {
+  switch (objectType) {
+    case 'person':
+      events.emit('people.person.updated', { type: 'person', id: recordId }, { changed })
+      return
+    case 'company':
+      events.emit(
+        'companies.company.updated',
+        { type: 'company', id: recordId },
+        { changed },
+      )
+      return
+    case 'position':
+      events.emit(
+        'positions.position.updated',
+        { type: 'position', id: recordId },
+        { changed },
+      )
+      return
+    case 'deal':
+      events.emit('deals.deal.updated', { type: 'deal', id: recordId }, { changed })
+      return
+    default:
+      throw new Error(`import produced an unexpected object type: ${objectType}`)
+  }
+}
 import { CsvFormatError, csvLine, fileDigest, parseCsv } from './csv.ts'
 import type { CsvRow, ParsedCsv } from './csv.ts'
 import { headersFor } from './exportRows.ts'
@@ -550,20 +618,16 @@ export function createImportExportService(
         )
 
         if (plan.action === 'create') {
-          events.emit('record.created', {
-            workspaceId,
-            objectType: written.objectType,
-            recordId: written.recordId,
-          })
+          emitImportedRecordCreated(events, written.objectType, written.recordId)
         } else if (written.changedFields.length > 0) {
           // An update that moved nothing publishes nothing. Re-running the same
           // file must not wake every consumer watching for a change.
-          events.emit('record.updated', {
-            workspaceId,
-            objectType: written.objectType,
-            recordId: written.recordId,
-            changedFields: written.changedFields,
-          })
+          emitImportedRecordUpdated(
+            events,
+            written.objectType,
+            written.recordId,
+            written.changedFields,
+          )
         }
       }
 
@@ -579,7 +643,7 @@ export function createImportExportService(
       )
 
       return outcome
-    })
+    }, { workspaceId, actor: toEventActor(actor) })
   }
 
   /**
@@ -658,10 +722,14 @@ export function createImportExportService(
     })
 
     await dependencies.transaction(({ events }) => {
-      events.emit('import.completed', { workspaceId, importJobId: jobId, object: job.object })
+      events.emit(
+        'imports.job.completed',
+        { type: 'import_job', id: jobId },
+        { object: job.object },
+      )
 
       return Promise.resolve()
-    })
+    }, { workspaceId, actor: toEventActor(actor) })
   }
 
   /**

package/src/modules/notes/events.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the notes module.
+ *
+ * `target` is the record the note attaches to (a person, company, deal, ...).
+ * The note's own id lives in `data` so a consumer that watches records does
+ * not need a second lookup to know which record the note landed on.
+ */
+
+export const notesEvents = {
+  'notes.note.added': z.object({ noteId: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface NoteAddedData {
+  readonly noteId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'notes.note.added': NoteAddedData
+  }
+}

package/src/modules/notes/index.ts

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

package/src/modules/notes/service.ts

@@ -7,8 +7,10 @@ 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 { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { missingTargets } from '../recordTargets.ts'
 import type { RecordTargetType } from '../recordTargets.ts'
 import * as repository from './repository.ts'
@@ -145,15 +147,14 @@ export function createNotesService(dependencies: NotesDependencies): NotesServic
         // 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,
-        })
+        events.emit(
+          'notes.note.added',
+          { type: created.targetType, id: created.targetId },
+          { noteId: created.id },
+        )
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {

package/src/modules/opportunities/events.ts

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

package/src/modules/opportunities/index.ts

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

package/src/modules/opportunities/service.ts

@@ -8,8 +8,10 @@ import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
 import { describeCreation, describeStageChange, 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 { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as companyRepository from '../companies/repository.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
@@ -236,10 +238,10 @@ export function createOpportunitiesService(
           ...describeCreation('Opportunity'),
         })
 
-        events.emit('record.created', { workspaceId, objectType: 'opportunity', recordId: id })
+        events.emit('opportunities.opportunity.created', { type: 'opportunity', id }, {})
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -302,25 +304,22 @@ export function createOpportunitiesService(
           })
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'opportunity',
-          recordId: id,
-          changedFields: changed,
-        })
+        events.emit(
+          'opportunities.opportunity.updated',
+          { type: 'opportunity', id },
+          { changed },
+        )
 
         if (stageMove !== undefined) {
-          events.emit('stage.changed', {
-            workspaceId,
-            objectType: 'opportunity',
-            recordId: id,
-            fromStageId: stageMove.from.id,
-            toStageId: stageMove.to.id,
-          })
+          events.emit(
+            'opportunities.opportunity.stage_changed',
+            { type: 'opportunity', id },
+            { fromStageId: stageMove.from.id, toStageId: stageMove.to.id },
+          )
         }
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -335,8 +334,8 @@ export function createOpportunitiesService(
         await deleteRecordsAttachedTo(tx, workspaceId, 'opportunity', id)
         await repository.deleteOpportunity(tx, workspaceId, id)
 
-        events.emit('record.deleted', { workspaceId, objectType: 'opportunity', recordId: id })
-      })
+        events.emit('opportunities.opportunity.deleted', { type: 'opportunity', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/partnerships/events.ts

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

package/src/modules/partnerships/index.ts

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

package/src/modules/partnerships/service.ts

@@ -14,8 +14,10 @@ import {
   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 { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as companyRepository from '../companies/repository.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
@@ -301,10 +303,10 @@ export function createPartnershipsService(
           })
         }
 
-        events.emit('record.created', { workspaceId, objectType: 'partnership', recordId: id })
+        events.emit('partnerships.partnership.created', { type: 'partnership', id }, {})
 
         return toView(created, personIds)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -402,25 +404,22 @@ export function createPartnershipsService(
           })
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'partnership',
-          recordId: id,
-          changedFields: linksChanged ? [...changed, 'personIds'] : changed,
-        })
+        events.emit(
+          'partnerships.partnership.updated',
+          { type: 'partnership', id },
+          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+        )
 
         if (stageMove !== undefined) {
-          events.emit('stage.changed', {
-            workspaceId,
-            objectType: 'partnership',
-            recordId: id,
-            fromStageId: stageMove.from.id,
-            toStageId: stageMove.to.id,
-          })
+          events.emit(
+            'partnerships.partnership.stage_changed',
+            { type: 'partnership', id },
+            { fromStageId: stageMove.from.id, toStageId: stageMove.to.id },
+          )
         }
 
         return toView(updated, nextPeople ?? currentPeople)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -435,8 +434,8 @@ export function createPartnershipsService(
         await deleteRecordsAttachedTo(tx, workspaceId, 'partnership', id)
         await repository.deletePartnership(tx, workspaceId, id)
 
-        events.emit('record.deleted', { workspaceId, objectType: 'partnership', recordId: id })
-      })
+        events.emit('partnerships.partnership.deleted', { type: 'partnership', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }