@kelpie/server 0.5.2 → 0.7.0

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

@@ -3,6 +3,7 @@ import {
   IMPORT_OBJECTS,
   IMPORT_SOURCES,
   MAX_IMPORT_FILE_BYTES,
+  ON_MISSING_COMPANY,
   defaultMatchKeyId,
 } from '@kelpie/schemas'
 import { z } from 'zod'
@@ -59,6 +60,13 @@ const previewArgs = z.strictObject({
     .enum(IMPORT_CONFLICT_MODES)
     .default('skip')
     .describe('What to do with a row that matches an existing record.'),
+  on_missing_company: z
+    .enum(ON_MISSING_COMPANY)
+    .default('skip')
+    .describe(
+      'People import only: what to do when a row names a company that is not here yet. ' +
+        "'skip' imports the person and leaves the position unlinked; 'create' invents the company.",
+    ),
   match_key: z.string().min(1).optional().describe('Which field decides that match.'),
   column_map: columnMapArg.optional(),
   file_name: z.string().min(1).nullable().default(null).describe('Recorded on the job, for the log.'),
@@ -124,6 +132,7 @@ export function registerImportExportTools(mcp: McpToolRegistry, service: ImportE
           source: args.source,
           object: args.object,
           conflictMode: args.conflict_mode,
+          onMissingCompany: args.on_missing_company,
           matchKeyId: args.match_key ?? defaultMatchKeyId(args.object),
           columnMap: args.column_map,
           fileName: args.file_name,

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

@@ -11,7 +11,7 @@ import * as dealRepository from '../deals/repository.ts'
 import * as peopleRepository from '../people/repository.ts'
 import * as positionRepository from '../positions/repository.ts'
 import { IMPORT_DEAL_CURRENCY, NEW_COMPANY_DEFAULTS, NEW_PERSON_DEFAULTS } from './drafts.ts'
-import type { ImportWrite, RowPlan } from './plan.ts'
+import type { ImportWrite, PlannedAffiliation, RowPlan } from './plan.ts'
 
 /**
  * Applying one planned row: the insert or update, and the timeline entry that
@@ -34,6 +34,21 @@ export interface WriteDependencies {
   readonly sourceName: string
 }
 
+/**
+ * A record a row wrote besides its primary one.
+ *
+ * A People row with an affiliation makes a Position, and under
+ * `on_missing_company: create` a Company as well. Each needs its own module
+ * event, which the service emits from these.
+ */
+export interface SideRecord {
+  readonly objectType: RecordObjectType
+  readonly recordId: string
+  readonly created: boolean
+  /** The columns an update moved. Empty on a create. */
+  readonly changedFields: readonly string[]
+}
+
 export interface WriteOutcome {
   readonly recordId: string
   readonly objectType: RecordObjectType
@@ -43,6 +58,8 @@ export interface WriteOutcome {
    * nothing at all.
    */
   readonly changedFields: readonly string[]
+  /** Records the row wrote besides its primary one: a People affiliation's company and position. */
+  readonly sideRecords?: readonly SideRecord[]
 }
 
 /** A create or update plan. `skip` and `error` never reach here. */
@@ -102,6 +119,92 @@ async function writeCompany(
   return { recordId: id, objectType: 'company', changedFields }
 }
 
+/**
+ * Writes the position a People row named, and the company it belongs to when the
+ * job was told to create one.
+ *
+ * The company is created before the position so the link has something to point
+ * at. The position is renamed in place when the person already holds one at that
+ * company, and created otherwise, which is the two-column-key behaviour the
+ * People affiliation chose. Files the `created Company` and `linked to company`
+ * activities as it goes, the same sentences the Companies and Positions imports
+ * write.
+ */
+async function applyAffiliation(
+  dependencies: WriteDependencies,
+  personId: string,
+  affiliation: PlannedAffiliation,
+): Promise<readonly SideRecord[]> {
+  const { tx, workspaceId, actor, sourceName } = dependencies
+  const sideRecords: SideRecord[] = []
+
+  const companyId = await (async (): Promise<string> => {
+    if (affiliation.kind === 'link') {
+      return affiliation.companyId
+    }
+
+    const created = await companyRepository.insertCompany(tx, {
+      ...NEW_COMPANY_DEFAULTS,
+      ...affiliation.company,
+      tags: affiliation.company.tags === undefined ? undefined : [...affiliation.company.tags],
+      id: dependencies.createId('company'),
+      workspaceId,
+      name: affiliation.company.name ?? '',
+    })
+
+    sideRecords.push({ objectType: 'company', recordId: created.id, created: true, changedFields: [] })
+    await dependencies.recordActivity(tx, workspaceId, actor, {
+      targetType: 'company',
+      targetId: created.id,
+      kind: 'created',
+      ...describeCreationVia('Company', sourceName),
+    })
+
+    return created.id
+  })()
+
+  const held = await positionRepository.listPositionsAt(tx, workspaceId, personId, companyId)
+  const current = held[0]
+
+  if (current === undefined) {
+    const created = await positionRepository.insertPosition(tx, {
+      id: dependencies.createId('position'),
+      workspaceId,
+      personId,
+      companyId,
+      title: affiliation.title,
+    })
+
+    sideRecords.push({ objectType: 'position', recordId: created.id, created: true, changedFields: [] })
+
+    for (const end of [
+      { targetType: 'person', targetId: personId, related: 'company' },
+      { targetType: 'company', targetId: companyId, related: 'person' },
+    ] as const) {
+      await dependencies.recordActivity(tx, workspaceId, actor, {
+        targetType: end.targetType,
+        targetId: end.targetId,
+        kind: 'linked',
+        ...describeLink(end.related, sourceName),
+      })
+    }
+
+    return sideRecords
+  }
+
+  const changedFields = changedKeys(current, { title: affiliation.title })
+
+  if (changedFields.length > 0) {
+    await positionRepository.updatePosition(tx, workspaceId, current.id, {
+      title: affiliation.title,
+      updatedAt: dependencies.now,
+    })
+    sideRecords.push({ objectType: 'position', recordId: current.id, created: false, changedFields })
+  }
+
+  return sideRecords
+}
+
 async function writePerson(
   dependencies: WriteDependencies,
   plan: WritablePlan,
@@ -120,7 +223,12 @@ async function writePerson(
       name: write.draft.name ?? '',
     })
 
-    return { recordId: created.id, objectType: 'person', changedFields: [] }
+    const sideRecords =
+      write.affiliation === undefined
+        ? []
+        : await applyAffiliation(dependencies, created.id, write.affiliation)
+
+    return { recordId: created.id, objectType: 'person', changedFields: [], sideRecords }
   }
 
   const id = requireTarget(plan)
@@ -144,7 +252,12 @@ async function writePerson(
     })
   }
 
-  return { recordId: id, objectType: 'person', changedFields }
+  const sideRecords =
+    write.affiliation === undefined
+      ? []
+      : await applyAffiliation(dependencies, id, write.affiliation)
+
+  return { recordId: id, objectType: 'person', changedFields, sideRecords }
 }
 
 /**

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

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