@kelpie/server 0.5.2 → 0.7.0

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

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/drafts.ts

@@ -174,6 +174,33 @@ export function personDraft(mapped: Readonly<Record<string, string>>): PersonDra
   })
 }
 
+/**
+ * The company a People row's affiliation would create.
+ *
+ * Built from the row's `company_domain` and `company_name` cells, not the
+ * `name`/`domain` a Companies file uses. The name falls back to the raw domain
+ * so a create from a domain-only row is not a nameless company. The write lays
+ * `NEW_COMPANY_DEFAULTS` over this, the same as a Companies import.
+ */
+export function affiliationCompanyDraft(mapped: Readonly<Record<string, string>>): CompanyDraft {
+  const domainRaw = text(mapped, 'company_domain')
+
+  return present<CompanyDraft>({
+    name: text(mapped, 'company_name') ?? domainRaw,
+    domain: domainRaw === undefined ? undefined : (normaliseDomain(domainRaw) ?? undefined),
+    industry: undefined,
+    description: undefined,
+    stage: undefined,
+    sizeBand: undefined,
+    hq: undefined,
+    website: undefined,
+    accountType: undefined,
+    icpFit: undefined,
+    summary: undefined,
+    tags: undefined,
+  })
+}
+
 /**
  * `value` is required, so `moneyToCents` has already been checked by
  * `validateRow` and cannot be undefined here.

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/exportRows.ts

@@ -26,8 +26,17 @@ function joinList(values: readonly string[]): string {
   return values.join('|')
 }
 
+/**
+ * The header row of an export and of a template.
+ *
+ * `importOnly` columns are left out: a People import may map `company_domain`,
+ * `company_name` and `title` to drive a Position, but a person holds many
+ * positions and none of them is a field on the person. Writing one on the export
+ * would be lossy, so the export and the template carry the round-trippable
+ * columns only, and each cell function matches this order one for one.
+ */
 export function headersFor(object: ImportObject): readonly string[] {
-  return OBJECT_COLUMNS[object].map((column) => column.key)
+  return OBJECT_COLUMNS[object].filter((column) => column.importOnly !== true).map((column) => column.key)
 }
 
 export function companyCells(row: ExportCompanyRow): readonly string[] {

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({