@kelpie/server 0.10.0 → 0.12.0

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

package/src/modules/deals/routes.ts

@@ -1,4 +1,4 @@
-import { customFieldsPatchShape } from '@kelpie/schemas'
+import { convertPipelineRecordBody, convertedToResponse, customFieldsPatchShape } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -8,6 +8,8 @@ import type { Actor } from '../auth/actor.ts'
 import { resolveActorFrom } from '../auth/credentials.ts'
 import type { CredentialDependencies } from '../auth/credentials.ts'
 import { renderCustomFieldsForWire } from '../custom-fields/wire.ts'
+import { mountPipelineConvertRoute } from '../conversions/routes.ts'
+import type { ConversionsService } from '../conversions/index.ts'
 import type { CreateDealInput, DealView, DealsService, UpdateDealInput } from './service.ts'
 
 /** Wire shapes for `/v1/deals`. Bodies are strict; an unknown field is a 422, per `api.md`. */
@@ -58,6 +60,7 @@ export const updateBody = z.strictObject(dealShape).partial()
 
 export interface DealsRoutesDependencies extends CredentialDependencies {
   readonly service: DealsService
+  readonly conversions: ConversionsService
 }
 
 export function toCreateInput(body: z.infer<typeof createBody>): CreateDealInput {
@@ -117,6 +120,7 @@ export function dealResponse(deal: DealView): Record<string, unknown> {
     summary: deal.summary,
     tags: deal.tags,
     external_id: deal.externalId,
+    converted_to: convertedToResponse(deal.convertedTargetType, deal.convertedTargetId),
     custom_fields: renderCustomFieldsForWire(deal.customFields),
     created_at: deal.createdAt.toISOString(),
     updated_at: deal.updatedAt.toISOString(),
@@ -170,4 +174,10 @@ export function mountDealsRoutes(router: Hono, dependencies: DealsRoutesDependen
 
     return context.body(null, 204)
   })
+
+  mountPipelineConvertRoute(router, '/deals/:id/convert', {
+    ...dependencies,
+    sourceKind: 'deal',
+    bodySchema: convertPipelineRecordBody,
+  })
 }

package/src/modules/deals/schema.ts

@@ -1,7 +1,9 @@
+import { sql } from 'drizzle-orm'
+import { check, bigint, date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+import { PIPELINE_KINDS } from '@kelpie/schemas'
 import type { CustomFieldValue } from '@kelpie/schemas'
-import { bigint, date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
 
-import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import { createdAt, oneOf, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
 import type { SearchVectorPart } from '../../lib/columns.ts'
 import { companies } from '../companies/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
@@ -38,6 +40,8 @@ export const deals = pgTable(
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
     externalId: text('external_id'),
+    convertedTargetType: text('converted_target_type'),
+    convertedTargetId: text('converted_target_id'),
     // Workspace-defined fields, keyed by definition key. See people/schema.ts.
     customFields: jsonb('custom_fields')
       .$type<Readonly<Record<string, CustomFieldValue>>>()
@@ -59,6 +63,10 @@ export const deals = pgTable(
     index('deals_company_idx').on(table.companyId),
     index('deals_stage_idx').on(table.stageId),
     index('deals_search_idx').using('gin', table.searchVector),
+    check(
+      'deals_converted_target_type_check',
+      sql`${table.convertedTargetType} is null or ${oneOf('deals_converted_target_type_check', table.convertedTargetType, PIPELINE_KINDS)}`,
+    ),
   ],
 )