@kelpie/server 0.10.0 → 0.11.0

package/src/modules/conversions/mcp.ts

@@ -0,0 +1,71 @@
+import { convertEnquiryBody, convertPipelineRecordBody, PIPELINE_KINDS } from '@kelpie/schemas'
+import type { PipelineKind } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg } from '../crudTools.ts'
+import type { ConversionsService } from './service.ts'
+import { objectLabelFor } from './fieldMap.ts'
+import { toConvertInput } from './routes.ts'
+import { renderConvertedPipelineRecord } from './wire.ts'
+
+const CONVERT_TOOL_RESOURCES: Readonly<Record<PipelineKind, string>> = {
+  enquiry: 'enquiries',
+  deal: 'deals',
+  opportunity: 'opportunities',
+  raise: 'raises',
+  partnership: 'partnerships',
+}
+
+export function registerPipelineConvertTool(
+  mcp: McpToolRegistry,
+  conversions: ConversionsService,
+  sourceKind: PipelineKind,
+): void {
+  const bodySchema =
+    sourceKind === 'enquiry'
+      ? convertEnquiryBody
+      : convertPipelineRecordBody
+
+  mcp.tool({
+    name: `${CONVERT_TOOL_RESOURCES[sourceKind]}_convert`,
+    description:
+      `Convert a ${objectLabelFor(sourceKind)} to another pipeline record type. ` +
+      'Creates a new record, moves notes/activities/decisions/plans to it, copies ' +
+      'linked people, and leaves the source in place with a conversion link. ' +
+      `Target types: ${PIPELINE_KINDS.join(', ')}. 409 if already converted.`,
+    inputSchema: bodySchema.and(z.strictObject({ id: idArg })),
+    invoke: async (args, actor) => {
+      const { id, ...body } = args
+      const { targetKind, target, personIds } = await conversions.convert(
+        actor,
+        sourceKind,
+        id,
+        toConvertInput(body),
+      )
+
+      return renderConvertedPipelineRecord(targetKind, target, personIds)
+    },
+  })
+}
+
+/** Backward-compatible alias for agents that still call enquiries_convert_to_deal. */
+export function registerEnquiryConvertToDealTool(
+  mcp: McpToolRegistry,
+  conversions: ConversionsService,
+): void {
+  mcp.tool({
+    name: 'enquiries_convert_to_deal',
+    description:
+      'Convert an enquiry to a Deal. Same as enquiries_convert with target_type deal. ' +
+      'Mirrors POST /v1/enquiries/{id}/convert.',
+    inputSchema: z.strictObject({ id: idArg }),
+    invoke: async ({ id }, actor) => {
+      const { targetKind, target, personIds } = await conversions.convert(actor, 'enquiry', id, {
+        targetType: 'deal',
+      })
+
+      return renderConvertedPipelineRecord(targetKind, target, personIds)
+    },
+  })
+}

package/src/modules/conversions/repoint.ts

@@ -0,0 +1,146 @@
+import { PIPELINE_KINDS } from '@kelpie/schemas'
+import type { PipelineKind } from '@kelpie/schemas'
+import { and, eq } from 'drizzle-orm'
+
+import type { Queryable } from '../../runtime/transaction.ts'
+import * as activityRepository from '../activities/repository.ts'
+import * as agentRunRepository from '../agent-tasks/repository.ts'
+import * as decisionRepository from '../decisions/repository.ts'
+import { formAttachTargets } from '../forms/schema.ts'
+import * as listRepository from '../lists/repository.ts'
+import * as noteRepository from '../notes/repository.ts'
+import * as planRepository from '../plans/repository.ts'
+
+/**
+ * The polymorphic repoint rule: mirror of `deleteRecordsAttachedTo`, used when
+ * a pipeline record converts to another type and its history should follow the
+ * new record while the source stays in place.
+ */
+
+export interface PipelineTargetRef {
+  readonly targetType: PipelineKind
+  readonly targetId: string
+}
+
+/**
+ * @param db Must be the caller's transaction.
+ * @returns How many rows were repointed or removed, for the caller's activity trail.
+ */
+export async function repointRecordsAttachedTo(
+  db: Queryable,
+  workspaceId: string,
+  from: PipelineTargetRef,
+  to: PipelineTargetRef,
+): Promise<number> {
+  const fromType = from.targetType
+  const fromId = from.targetId
+  const toType = to.targetType
+  const toId = to.targetId
+
+  const notes = await noteRepository.repointForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const activities = await activityRepository.repointForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const decisions = await decisionRepository.repointForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const plans = await planRepository.repointForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const agentRuns = await agentRunRepository.repointForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const attachTargets = await repointFormAttachTargets(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+    toType,
+    toId,
+  )
+  const memberships = await listRepository.deleteMembershipsForTarget(
+    db,
+    workspaceId,
+    fromType,
+    fromId,
+  )
+
+  return notes + activities + decisions + plans + agentRuns + attachTargets + memberships
+}
+
+async function repointFormAttachTargets(
+  db: Queryable,
+  workspaceId: string,
+  fromType: PipelineKind,
+  fromId: string,
+  toType: PipelineKind,
+  toId: string,
+): Promise<number> {
+  const held = await db
+    .select({ formId: formAttachTargets.formId })
+    .from(formAttachTargets)
+    .where(
+      and(
+        eq(formAttachTargets.workspaceId, workspaceId),
+        eq(formAttachTargets.targetType, fromType),
+        eq(formAttachTargets.targetId, fromId),
+      ),
+    )
+
+  if (held.length === 0) {
+    return 0
+  }
+
+  await db
+    .delete(formAttachTargets)
+    .where(
+      and(
+        eq(formAttachTargets.workspaceId, workspaceId),
+        eq(formAttachTargets.targetType, fromType),
+        eq(formAttachTargets.targetId, fromId),
+      ),
+    )
+
+  await db.insert(formAttachTargets).values(
+    held.map((row: { formId: string }) => ({
+      workspaceId,
+      formId: row.formId,
+      targetType: toType,
+      targetId: toId,
+    })),
+  )
+
+  return held.length
+}
+
+/** Whether a pipeline kind is one of the five convertible types. */
+export function isPipelineKind(value: string): value is PipelineKind {
+  return (PIPELINE_KINDS as readonly string[]).includes(value)
+}

package/src/modules/conversions/routes.ts

@@ -0,0 +1,68 @@
+import type { ConvertPipelineRecordInput, PipelineKind } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import type { z } from 'zod'
+
+import { readJsonBody } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type { ConversionsService } from './service.ts'
+import { renderConvertedPipelineRecord } from './wire.ts'
+
+export interface ConvertRouteDependencies extends CredentialDependencies {
+  readonly conversions: ConversionsService
+  readonly sourceKind: PipelineKind
+  readonly bodySchema: z.ZodType<{
+    target_type: PipelineKind
+    stage_id?: string | undefined
+    company_id?: string | undefined
+    kind?: string | undefined
+    name?: string | undefined
+  }>
+  readonly renderTarget?: (
+    targetKind: PipelineKind,
+    target: unknown,
+    personIds: readonly string[],
+  ) => Record<string, unknown>
+}
+
+export function toConvertInput(body: {
+  target_type: PipelineKind
+  stage_id?: string | undefined
+  company_id?: string | undefined
+  kind?: string | undefined
+  name?: string | undefined
+}): ConvertPipelineRecordInput {
+  return {
+    targetType: body.target_type,
+    stageId: body.stage_id,
+    companyId: body.company_id,
+    kind: body.kind,
+    name: body.name,
+  }
+}
+
+export function mountPipelineConvertRoute(
+  router: Hono,
+  path: string,
+  dependencies: ConvertRouteDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.post(path, async (context) => {
+    const id = context.req.param('id')!
+
+    const body = await readJsonBody(context, dependencies.bodySchema)
+    const { targetKind, target, personIds } = await dependencies.conversions.convert(
+      await requireActor(context),
+      dependencies.sourceKind,
+      id,
+      toConvertInput(body),
+    )
+
+    const render =
+      dependencies.renderTarget ?? ((kind, record, ids) => renderConvertedPipelineRecord(kind, record, ids))
+
+    return context.json(render(targetKind, target, personIds), 201)
+  })
+}

package/src/modules/conversions/service.ts

@@ -0,0 +1,310 @@
+import type { ConvertPipelineRecordInput, PipelineKind } from '@kelpie/schemas'
+
+import { toEventActor } from '../../lib/actor.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { Database } from '../../lib/database.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { EventName } from '../../runtime/events.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import {
+  describeConversion,
+  describeCreationFrom,
+  describeStageChange,
+} from '../activities/wording.ts'
+import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
+import * as personLinks from '../personLinks.ts'
+import * as pipelineRepository from '../pipelines/repository.ts'
+import {
+  assertNotAlreadyConverted,
+  buildTargetInsertPayload,
+  insertConvertedTarget,
+  intersectCustomFields,
+  loadPipelineSnapshot,
+  markSourceConverted,
+  objectLabelFor,
+  type ConvertedTargetRecord,
+} from './fieldMap.ts'
+import { repointRecordsAttachedTo } from './repoint.ts'
+
+export interface ConversionsDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
+}
+
+export interface ConvertPipelineRecordResult {
+  readonly targetKind: PipelineKind
+  readonly target: ConvertedTargetRecord
+  readonly personIds: readonly string[]
+}
+
+export interface ConversionsService {
+  convert(
+    actor: Actor,
+    sourceKind: PipelineKind,
+    sourceId: string,
+    body: ConvertPipelineRecordInput,
+  ): Promise<ConvertPipelineRecordResult>
+}
+
+function conversionEventName(sourceKind: PipelineKind): EventName {
+  switch (sourceKind) {
+    case 'enquiry':
+      return 'enquiries.enquiry.converted'
+    case 'deal':
+      return 'deals.deal.converted'
+    case 'opportunity':
+      return 'opportunities.opportunity.converted'
+    case 'raise':
+      return 'raises.raise.converted'
+    case 'partnership':
+      return 'partnerships.partnership.converted'
+  }
+}
+
+function createdEventName(targetKind: PipelineKind): EventName {
+  switch (targetKind) {
+    case 'enquiry':
+      return 'enquiries.enquiry.created'
+    case 'deal':
+      return 'deals.deal.created'
+    case 'opportunity':
+      return 'opportunities.opportunity.created'
+    case 'raise':
+      return 'raises.raise.created'
+    case 'partnership':
+      return 'partnerships.partnership.created'
+  }
+}
+
+function updatedEventName(sourceKind: PipelineKind): EventName {
+  switch (sourceKind) {
+    case 'enquiry':
+      return 'enquiries.enquiry.updated'
+    case 'deal':
+      return 'deals.deal.updated'
+    case 'opportunity':
+      return 'opportunities.opportunity.updated'
+    case 'raise':
+      return 'raises.raise.updated'
+    case 'partnership':
+      return 'partnerships.partnership.updated'
+  }
+}
+
+function stageChangedEventName(sourceKind: PipelineKind): EventName {
+  switch (sourceKind) {
+    case 'enquiry':
+      return 'enquiries.enquiry.stage_changed'
+    case 'deal':
+      return 'deals.deal.stage_changed'
+    case 'opportunity':
+      return 'opportunities.opportunity.stage_changed'
+    case 'raise':
+      return 'raises.raise.stage_changed'
+    case 'partnership':
+      return 'partnerships.partnership.stage_changed'
+  }
+}
+
+function targetEventType(kind: PipelineKind): string {
+  switch (kind) {
+    case 'enquiry':
+      return 'enquiry'
+    case 'deal':
+      return 'deal'
+    case 'opportunity':
+      return 'opportunity'
+    case 'raise':
+      return 'raise'
+    case 'partnership':
+      return 'partnership'
+  }
+}
+
+export function createConversionsService(dependencies: ConversionsDependencies): ConversionsService {
+  return {
+    async convert(actor, sourceKind, sourceId, body) {
+      const workspaceId = requireWorkspaceId(actor)
+      const targetKind = body.targetType
+
+      if (sourceKind === targetKind) {
+        throw AppError.validationFailed('Choose a different target type to convert into', [
+          { field: 'target_type', message: `Already a ${objectLabelFor(sourceKind)}` },
+        ])
+      }
+
+      const source = await loadPipelineSnapshot(dependencies.db, workspaceId, sourceKind, sourceId)
+
+      if (source === undefined) {
+        throw AppError.notFound(`${objectLabelFor(sourceKind)} not found`)
+      }
+
+      assertNotAlreadyConverted(source)
+
+      const targetStages = await pipelineRepository.listStagesOfKind(
+        dependencies.db,
+        workspaceId,
+        targetKind,
+      )
+      const openTargetStage = targetStages.find((row) => row.open) ?? targetStages[0]
+
+      if (openTargetStage === undefined) {
+        throw AppError.conflict(`This workspace has no ${objectLabelFor(targetKind).toLowerCase()} stages`)
+      }
+
+      if (body.stageId !== undefined) {
+        const chosen = targetStages.find((row) => row.id === body.stageId)
+
+        if (chosen === undefined) {
+          throw AppError.validationFailed('Stage not found for this target type', [
+            { field: 'stage_id', message: body.stageId },
+          ])
+        }
+      }
+
+      const sourceStages = await pipelineRepository.listStagesOfKind(
+        dependencies.db,
+        workspaceId,
+        sourceKind,
+      )
+      const closedSourceStage = sourceStages.find((row) => !row.open)
+      const currentSourceStage = sourceStages.find((row) => row.id === source.stageId)
+
+      const personIds = await personLinks.listPersonIds(dependencies.db, workspaceId, {
+        targetType: sourceKind,
+        targetId: sourceId,
+      })
+      const targetId = dependencies.createId(targetKind)
+      const now = dependencies.now()
+      const sourceLabel = objectLabelFor(sourceKind)
+      const targetLabel = objectLabelFor(targetKind)
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const payload = buildTargetInsertPayload(
+          source,
+          targetKind,
+          body,
+          openTargetStage.id,
+        )
+        const customFields = await intersectCustomFields(
+          tx,
+          workspaceId,
+          targetKind,
+          source.customFields,
+          dependencies.customFields,
+        )
+        const target = await insertConvertedTarget(
+          tx,
+          workspaceId,
+          targetKind,
+          targetId,
+          payload,
+          customFields,
+          now,
+        )
+
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: targetKind, targetId },
+          personIds,
+        )
+
+        await repointRecordsAttachedTo(
+          tx,
+          workspaceId,
+          { targetType: sourceKind, targetId: sourceId },
+          { targetType: targetKind, targetId },
+        )
+
+        const stageChanged =
+          closedSourceStage !== undefined && closedSourceStage.id !== source.stageId
+
+        await markSourceConverted(
+          tx,
+          workspaceId,
+          source,
+          targetKind,
+          targetId,
+          stageChanged ? closedSourceStage.id : undefined,
+          now,
+        )
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: targetKind,
+          targetId,
+          kind: 'created',
+          ...describeCreationFrom(targetLabel, sourceLabel, source.name),
+        })
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: sourceKind,
+          targetId: sourceId,
+          kind: 'updated',
+          ...describeConversion(targetLabel, payload.name),
+        })
+
+        if (stageChanged && currentSourceStage !== undefined) {
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: sourceKind,
+            targetId: sourceId,
+            kind: 'stage_changed',
+            ...describeStageChange(currentSourceStage.label, closedSourceStage.label),
+          })
+        }
+
+        events.emit(createdEventName(targetKind), { type: targetEventType(targetKind), id: targetId }, {})
+
+        const sourceChanged: string[] = stageChanged
+          ? ['convertedTargetType', 'convertedTargetId', 'stageId']
+          : ['convertedTargetType', 'convertedTargetId']
+
+        if (source.kind === 'enquiry' && targetKind === 'deal') {
+          sourceChanged.push('convertedDealId')
+        }
+
+        events.emit(
+          updatedEventName(sourceKind),
+          { type: targetEventType(sourceKind), id: sourceId },
+          { changed: sourceChanged },
+        )
+
+        if (stageChanged && currentSourceStage !== undefined) {
+          events.emit(
+            stageChangedEventName(sourceKind),
+            { type: targetEventType(sourceKind), id: sourceId },
+            { fromStageId: currentSourceStage.id, toStageId: closedSourceStage.id },
+          )
+        }
+
+        const conversionPayload =
+          sourceKind === 'enquiry' && targetKind === 'deal'
+            ? { dealId: targetId, targetType: targetKind, targetId }
+            : { targetType: targetKind, targetId }
+
+        events.emit(
+          conversionEventName(sourceKind),
+          { type: targetEventType(sourceKind), id: sourceId },
+          conversionPayload,
+        )
+
+        return { targetKind, target, personIds }
+      }, { workspaceId, actor: toEventActor(actor) })
+    },
+  }
+}
+
+/** Factory helper shared by pipeline modules. */
+export function createSharedConversionsService(
+  dependencies: ConversionsDependencies,
+): ConversionsService {
+  return createConversionsService(dependencies)
+}

package/src/modules/conversions/wire.ts

@@ -0,0 +1,42 @@
+import type { PipelineKind } from '@kelpie/schemas'
+
+import { dealResponse } from '../deals/routes.ts'
+import type { DealRecord } from '../deals/repository.ts'
+import { enquiryResponse } from '../enquiries/routes.ts'
+import type { EnquiryRecord } from '../enquiries/repository.ts'
+import { opportunityResponse } from '../opportunities/routes.ts'
+import type { OpportunityRecord } from '../opportunities/repository.ts'
+import { partnershipResponse } from '../partnerships/routes.ts'
+import type { PartnershipRecord } from '../partnerships/repository.ts'
+import { raiseResponse } from '../raises/routes.ts'
+import type { RaiseRecord } from '../raises/repository.ts'
+
+/** Wire-shape a freshly converted pipeline record for any target type. */
+export function renderConvertedPipelineRecord(
+  targetKind: PipelineKind,
+  target: unknown,
+  personIds: readonly string[],
+): Record<string, unknown> {
+  const { workspaceId: _workspaceId, ...record } = target as {
+    workspaceId: string
+  }
+
+  switch (targetKind) {
+    case 'enquiry':
+      return enquiryResponse({ ...(record as Omit<EnquiryRecord, 'workspaceId'>), personIds })
+    case 'deal':
+      return dealResponse({ ...(record as Omit<DealRecord, 'workspaceId'>), personIds })
+    case 'opportunity':
+      return opportunityResponse({
+        ...(record as Omit<OpportunityRecord, 'workspaceId'>),
+        personIds,
+      })
+    case 'raise':
+      return raiseResponse({ ...(record as Omit<RaiseRecord, 'workspaceId'>), personIds })
+    case 'partnership':
+      return partnershipResponse({
+        ...(record as Omit<PartnershipRecord, 'workspaceId'>),
+        personIds,
+      })
+  }
+}

package/src/modules/deals/events.ts

@@ -12,6 +12,10 @@ export const dealsEvents = {
     fromStageId: z.string().nullable(),
     toStageId: z.string(),
   }),
+  'deals.deal.converted': z.object({
+    targetType: z.string(),
+    targetId: z.string(),
+  }),
 } satisfies ModuleEventCatalog
 
 export type DealCreatedData = Record<string, never>
@@ -23,6 +27,10 @@ export interface DealStageChangedData {
   readonly fromStageId: string | null
   readonly toStageId: string
 }
+export interface DealConvertedData {
+  readonly targetType: string
+  readonly targetId: string
+}
 
 declare module '../../runtime/events.ts' {
   interface KelpieEventMap {
@@ -30,5 +38,6 @@ declare module '../../runtime/events.ts' {
     'deals.deal.updated': DealUpdatedData
     'deals.deal.deleted': DealDeletedData
     'deals.deal.stage_changed': DealStageChangedData
+    'deals.deal.converted': DealConvertedData
   }
 }

package/src/modules/deals/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { createConversionsFromContext } from '../conversions/index.ts'
 import { createCustomFieldValues } from '../custom-fields/index.ts'
 import { dealsEvents } from './events.ts'
 import { mountDealsRoutes } from './routes.ts'
@@ -23,6 +24,7 @@ export function createDealsModule(migrationsDirectory: string): KelpieModule {
     events: dealsEvents,
 
     register(context) {
+      const conversions = createConversionsFromContext(context)
       const service = createDealsService({
         db: context.db,
         transaction: context.transaction,
@@ -38,10 +40,10 @@ export function createDealsModule(migrationsDirectory: string): KelpieModule {
       context.schema(schema, migrationsDirectory)
 
       context.routes((router) => {
-        mountDealsRoutes(router, { db: context.db, now: context.now, service })
+        mountDealsRoutes(router, { db: context.db, now: context.now, service, conversions })
       })
 
-      registerDealsTools(context.mcp, service)
+      registerDealsTools(context.mcp, service, conversions)
 
       return Promise.resolve()
     },