@kelpie/server 0.5.1 → 0.6.0

package/src/modules/companies/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 } from '../attachedRecords.ts'
 import { referencedElsewhere } from '../references.ts'
 import * as repository from './repository.ts'
@@ -185,10 +187,10 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
           ...describeCreation('Company'),
         })
 
-        events.emit('record.created', { workspaceId, objectType: 'company', recordId: created.id })
+        events.emit('companies.company.created', { type: 'company', id: created.id }, {})
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -228,15 +230,10 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
           ...describeUpdate(changed, COMPANY_FIELD_LABELS, existing, columns),
         })
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'company',
-          recordId: id,
-          changedFields: changed,
-        })
+        events.emit('companies.company.updated', { type: 'company', id }, { changed })
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -260,8 +257,8 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
           throw error
         }
 
-        events.emit('record.deleted', { workspaceId, objectType: 'company', recordId: id })
-      })
+        events.emit('companies.company.deleted', { type: 'company', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/core.ts

@@ -22,6 +22,7 @@ import { createPlansModule } from './plans/index.ts'
 import { createPositionsModule } from './positions/index.ts'
 import { createRaisesModule } from './raises/index.ts'
 import { createSearchModule } from './search/index.ts'
+import { createSmtpEmailModule } from './smtp-email/index.ts'
 import { createWebhooksModule } from './webhooks/index.ts'
 import { createWorkspaceModule } from './workspace/index.ts'
 
@@ -65,4 +66,7 @@ export const coreModules: readonly KelpieModule[] = [
   createImportExportModule(coreMigrationsDirectory),
   createAgentTasksModule(coreMigrationsDirectory),
   createWebhooksModule(coreMigrationsDirectory),
+  // Owns no tables. Registers a `'smtp'` provider with core's email runtime;
+  // the factory only runs if the assembly's `email.provider` picks it.
+  createSmtpEmailModule(),
 ]

package/src/modules/deals/events.ts

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

package/src/modules/deals/index.ts

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

package/src/modules/deals/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'
@@ -297,10 +299,10 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
           })
         }
 
-        events.emit('record.created', { workspaceId, objectType: 'deal', recordId: id })
+        events.emit('deals.deal.created', { type: 'deal', id }, {})
 
         return toView(created, personIds)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -393,25 +395,22 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
           })
         }
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'deal',
-          recordId: id,
-          changedFields: linksChanged ? [...changed, 'personIds'] : changed,
-        })
+        events.emit(
+          'deals.deal.updated',
+          { type: 'deal', id },
+          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+        )
 
         if (stageMove !== undefined) {
-          events.emit('stage.changed', {
-            workspaceId,
-            objectType: 'deal',
-            recordId: id,
-            fromStageId: stageMove.from.id,
-            toStageId: stageMove.to.id,
-          })
+          events.emit(
+            'deals.deal.stage_changed',
+            { type: 'deal', id },
+            { fromStageId: stageMove.from.id, toStageId: stageMove.to.id },
+          )
         }
 
         return toView(updated, nextPeople ?? currentPeople)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async remove(actor, id) {
@@ -426,8 +425,8 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
         await deleteRecordsAttachedTo(tx, workspaceId, 'deal', id)
         await repository.deleteDeal(tx, workspaceId, id)
 
-        events.emit('record.deleted', { workspaceId, objectType: 'deal', recordId: id })
-      })
+        events.emit('deals.deal.deleted', { type: 'deal', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }

package/src/modules/decisions/events.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the decisions module.
+ *
+ * `target` is the record the decision attaches to; the decision's own id lives
+ * in `data`.
+ */
+
+export const decisionsEvents = {
+  'decisions.decision.added': z.object({ decisionId: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface DecisionAddedData {
+  readonly decisionId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'decisions.decision.added': DecisionAddedData
+  }
+}

package/src/modules/decisions/index.ts

@@ -1,4 +1,5 @@
 import type { KelpieModule } from '../../runtime/module.ts'
+import { decisionsEvents } from './events.ts'
 import { mountDecisionsRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createDecisionsService } from './service.ts'
@@ -17,6 +18,7 @@ export function createDecisionsModule(migrationsDirectory: string): KelpieModule
     id: 'decisions',
     requires: ['workspace'],
     structural: true,
+    events: decisionsEvents,
 
     register(context) {
       const service = createDecisionsService({

package/src/modules/decisions/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 { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import './events.ts'
 import { targetExists } from '../recordTargets.ts'
 import type { RecordTargetType } from '../recordTargets.ts'
 import * as repository from './repository.ts'
@@ -158,15 +160,14 @@ export function createDecisionsService(dependencies: DecisionsDependencies): Dec
         // 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,
-        })
+        events.emit(
+          'decisions.decision.added',
+          { type: created.targetType, id: created.targetId },
+          { decisionId: created.id },
+        )
 
         return toView(created)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {

package/src/modules/forms/events.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the forms module.
+ *
+ * `forms.form.*` cover the form definition CRUD. `forms.submission.submitted`
+ * fires once per submission; the webhooks bridge translates it to the wire
+ * `form.submitted` event (the ids live in `data`).
+ */
+
+export const formsEvents = {
+  'forms.form.created': z.object({}).strict(),
+  'forms.form.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'forms.form.deleted': z.object({}).strict(),
+  'forms.submission.submitted': z.object({ formId: z.string(), submissionId: z.string() }),
+} satisfies ModuleEventCatalog
+
+export type FormCreatedData = Record<string, never>
+export interface FormUpdatedData {
+  readonly changed: readonly string[]
+}
+export type FormDeletedData = Record<string, never>
+export interface FormSubmissionData {
+  readonly formId: string
+  readonly submissionId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'forms.form.created': FormCreatedData
+    'forms.form.updated': FormUpdatedData
+    'forms.form.deleted': FormDeletedData
+    'forms.submission.submitted': FormSubmissionData
+  }
+}

package/src/modules/forms/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { formsEvents } from './events.ts'
 import { mountPublicFormRoutes } from './publicRoutes.ts'
 import { mountFormsRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -23,6 +24,7 @@ export function createFormsModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'forms',
     requires: ['people', 'companies', 'positions', 'pipelines', 'deals', 'activities'],
+    events: formsEvents,
 
     register(context) {
       const service = createFormsService({

package/src/modules/forms/service.ts

@@ -6,8 +6,10 @@ import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
 import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
 import { generateToken } from '../../lib/tokens.ts'
 import type { Transaction, 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 * as pipelineRepository from '../pipelines/repository.ts'
 import { fieldsDiffer, findFieldProblems, storedOptions } from './fields.ts'
 import type { FieldDraft, FieldShape } from './fields.ts'
@@ -253,10 +255,10 @@ export function createFormsService(dependencies: FormsDependencies): FormsServic
         })
         const fields = await writeFields(tx, workspaceId, id, input.fields)
 
-        events.emit('record.created', { workspaceId, objectType: 'form', recordId: id })
+        events.emit('forms.form.created', { type: 'form', id }, {})
 
         return toView(created, fields)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -310,15 +312,14 @@ export function createFormsService(dependencies: FormsDependencies): FormsServic
           return writeFields(tx, workspaceId, id, changes.fields)
         })()
 
-        events.emit('record.updated', {
-          workspaceId,
-          objectType: 'form',
-          recordId: id,
-          changedFields: rewritesFields ? [...written, 'fields'] : written,
-        })
+        events.emit(
+          'forms.form.updated',
+          { type: 'form', id },
+          { changed: rewritesFields ? [...written, 'fields'] : written },
+        )
 
         return toView(updated, fields)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     /**
@@ -339,8 +340,8 @@ export function createFormsService(dependencies: FormsDependencies): FormsServic
           throw AppError.notFound('Form not found')
         }
 
-        events.emit('record.deleted', { workspaceId, objectType: 'form', recordId: id })
-      })
+        events.emit('forms.form.deleted', { type: 'form', id }, {})
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async listSubmissions(actor, formId, query) {

package/src/modules/forms/submission.ts

@@ -7,14 +7,19 @@ import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
 import type { BufferedEvents, Transaction, TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder, SystemActor } from '../activities/recorder.ts'
 import { describeCreationVia, describeFormSubmission } from '../activities/wording.ts'
+import '../companies/events.ts'
 import * as companyRepository from '../companies/repository.ts'
 import type { CompanyRecord } from '../companies/repository.ts'
 import * as dealRepository from '../deals/repository.ts'
+import '../deals/events.ts'
+import '../people/events.ts'
 import * as peopleRepository from '../people/repository.ts'
 import type { PersonRecord } from '../people/repository.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
+import '../positions/events.ts'
 import * as positionRepository from '../positions/repository.ts'
 import * as workspaceRepository from '../workspace/repository.ts'
+import './events.ts'
 import {
   DEAL_CLOSE_HORIZON_DAYS,
   companyNameFrom,
@@ -148,34 +153,80 @@ function emitRecordEvents(
   workspaceId: string,
   touched: TouchedRecords,
 ): void {
-  const upserts = [
-    { objectType: 'person', outcome: touched.person } as const,
-    { objectType: 'company', outcome: touched.company } as const,
-    { objectType: 'position', outcome: touched.position } as const,
-  ]
-
-  for (const { objectType, outcome } of upserts) {
-    if (outcome === undefined) {
-      continue
-    }
+  if (touched.person !== undefined) {
+    emitUpsertEvent(events, 'person', touched.person)
+  }
+  if (touched.company !== undefined) {
+    emitUpsertEvent(events, 'company', touched.company)
+  }
+  if (touched.position !== undefined) {
+    emitUpsertEvent(events, 'position', touched.position)
+  }
 
-    if (outcome.created) {
-      events.emit('record.created', { workspaceId, objectType, recordId: outcome.record.id })
-      continue
-    }
+  if (touched.dealId !== null) {
+    events.emit('deals.deal.created', { type: 'deal', id: touched.dealId }, {})
+  }
+  // workspaceId is used by the transaction scope's envelope stamping; the
+  // parameter stays on the signature so future call sites keep the same shape.
+  void workspaceId
+}
 
-    if (outcome.filled.length > 0) {
-      events.emit('record.updated', {
-        workspaceId,
-        objectType,
-        recordId: outcome.record.id,
-        changedFields: outcome.filled,
-      })
+/**
+ * Dispatches the created/updated event owned by the record's module for one
+ * upsert. Split from the loop above so TypeScript can correlate the object
+ * type with its typed event name at each call site.
+ */
+function emitUpsertEvent(
+  events: BufferedEvents,
+  objectType: 'person' | 'company' | 'position',
+  outcome: { readonly created: boolean; readonly record: { readonly id: string }; readonly filled: readonly string[] },
+): void {
+  if (outcome.created) {
+    switch (objectType) {
+      case 'person':
+        events.emit('people.person.created', { type: 'person', id: outcome.record.id }, {})
+        return
+      case 'company':
+        events.emit('companies.company.created', { type: 'company', id: outcome.record.id }, {})
+        return
+      case 'position':
+        events.emit(
+          'positions.position.created',
+          { type: 'position', id: outcome.record.id },
+          {},
+        )
+        return
     }
   }
 
-  if (touched.dealId !== null) {
-    events.emit('record.created', { workspaceId, objectType: 'deal', recordId: touched.dealId })
+  if (outcome.filled.length === 0) {
+    return
+  }
+
+  const changed = outcome.filled
+
+  switch (objectType) {
+    case 'person':
+      events.emit(
+        'people.person.updated',
+        { type: 'person', id: outcome.record.id },
+        { changed },
+      )
+      return
+    case 'company':
+      events.emit(
+        'companies.company.updated',
+        { type: 'company', id: outcome.record.id },
+        { changed },
+      )
+      return
+    case 'position':
+      events.emit(
+        'positions.position.updated',
+        { type: 'position', id: outcome.record.id },
+        { changed },
+      )
+      return
   }
 }
 
@@ -484,11 +535,11 @@ export function createFormSubmitService(dependencies: SubmissionDependencies): F
         }
 
         emitRecordEvents(events, workspaceId, { person, company, position, dealId })
-        events.emit('form.submitted', {
-          workspaceId,
-          formId: form.id,
-          submissionId: submission.id,
-        })
+        events.emit(
+          'forms.submission.submitted',
+          { type: 'submission', id: submission.id },
+          { formId: form.id, submissionId: submission.id },
+        )
 
         return {
           submissionId: submission.id,
@@ -500,7 +551,7 @@ export function createFormSubmitService(dependencies: SubmissionDependencies): F
           submittedAt: submission.submittedAt,
           thankYouMessage: form.thankYouMessage,
         }
-      })
+      }, { workspaceId })
     },
   }
 }

package/src/modules/handbook/events.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the handbook module.
+ *
+ * Handbook pages are content objects, not CRM records — the target type is
+ * `handbook_page`, and the webhooks bridge does not (yet) deliver these to
+ * subscribers. They still fire on the bus for in-process consumers.
+ */
+
+export const handbookEvents = {
+  'handbook.page.created': z.object({}).strict(),
+  'handbook.page.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'handbook.page.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type HandbookPageCreatedData = Record<string, never>
+export interface HandbookPageUpdatedData {
+  readonly changed: readonly string[]
+}
+export type HandbookPageDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'handbook.page.created': HandbookPageCreatedData
+    'handbook.page.updated': HandbookPageUpdatedData
+    'handbook.page.deleted': HandbookPageDeletedData
+  }
+}

package/src/modules/handbook/index.ts

@@ -1,4 +1,5 @@
 import type { KelpieModule } from '../../runtime/module.ts'
+import { handbookEvents } from './events.ts'
 import { mountHandbookRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createHandbookService } from './service.ts'
@@ -20,6 +21,7 @@ export function createHandbookModule(migrationsDirectory: string): KelpieModule
   return {
     id: 'handbook',
     requires: ['workspace'],
+    events: handbookEvents,
 
     register(context) {
       const service = createHandbookService({

package/src/modules/handbook/service.ts

@@ -6,8 +6,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 { Transaction, TransactionScope } from '../../runtime/transaction.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 * as repository from './repository.ts'
 import { DEFAULT_HANDBOOK_PAGE_SORT, HANDBOOK_PAGE_SORTS } from './repository.ts'
 import type { HandbookPageFilters, HandbookPageRecord } from './repository.ts'
@@ -292,11 +294,7 @@ export function createHandbookService(dependencies: HandbookDependencies): Handb
             updatedBy: actorMemberId(actor),
           })
 
-          events.emit('record.created', {
-            workspaceId,
-            objectType: 'handbook_page',
-            recordId: id,
-          })
+          events.emit('handbook.page.created', { type: 'handbook_page', id }, {})
 
           return toView(created)
         } catch (error: unknown) {
@@ -308,7 +306,7 @@ export function createHandbookService(dependencies: HandbookDependencies): Handb
 
           throw error
         }
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async update(actor, id, changes) {
@@ -346,16 +344,11 @@ export function createHandbookService(dependencies: HandbookDependencies): Handb
         const changed = [...written, ...movedFields]
 
         if (changed.length > 0) {
-          events.emit('record.updated', {
-            workspaceId,
-            objectType: 'handbook_page',
-            recordId: id,
-            changedFields: changed,
-          })
+          events.emit('handbook.page.updated', { type: 'handbook_page', id }, { changed })
         }
 
         return toView(updated)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     /**
@@ -391,9 +384,9 @@ export function createHandbookService(dependencies: HandbookDependencies): Handb
         )
 
         for (const recordId of removed) {
-          events.emit('record.deleted', { workspaceId, objectType: 'handbook_page', recordId })
+          events.emit('handbook.page.deleted', { type: 'handbook_page', id: recordId }, {})
         }
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
   }
 }