@kelpie/server 0.10.0 → 0.12.0

package/src/modules/deals/service.ts

@@ -21,6 +21,7 @@ import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import { clearConversionPointersToTarget } from '../conversions/clearPointers.ts'
 import * as companyRepository from '../companies/repository.ts'
 import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
 import * as personLinks from '../personLinks.ts'
@@ -488,6 +489,8 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
+        await clearConversionPointersToTarget(tx, workspaceId, 'deal', id)
+
         // Form submissions unlink themselves through `set null`; notes,
         // activities, decisions, plan items, and person_links have no key back
         // to the deal, so they are removed here, in the same transaction.

package/src/modules/deals/tools.ts

@@ -2,6 +2,8 @@ import { z } from 'zod'
 
 import type { McpToolRegistry } from '../../runtime/module.ts'
 import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import type { ConversionsService } from '../conversions/index.ts'
+import { registerPipelineConvertTool } from '../conversions/mcp.ts'
 import { createBody, dealResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
 import type { DealsService } from './service.ts'
 
@@ -15,7 +17,11 @@ const listArgs = z.strictObject({
   person_id: idSetArg.optional().describe('Only deals one of these people is a contact on.'),
 })
 
-export function registerDealsTools(mcp: McpToolRegistry, service: DealsService): void {
+export function registerDealsTools(
+  mcp: McpToolRegistry,
+  service: DealsService,
+  conversions: ConversionsService,
+): void {
   registerCrudTools(mcp, {
     resource: 'deals',
     subject: 'deal',
@@ -36,4 +42,6 @@ export function registerDealsTools(mcp: McpToolRegistry, service: DealsService):
     updateArgs: updateBody.extend({ id: idArg }),
     toUpdateInput,
   })
+
+  registerPipelineConvertTool(mcp, conversions, 'deal')
 }

package/src/modules/decisions/repository.ts

@@ -191,7 +191,29 @@ export async function deleteForTarget(
   return deleted.length
 }
 
-/** Whether a member belongs to this workspace, for validating `owner_id`. */
+/** Moves every decision from one target to another inside a conversion transaction. */
+export async function repointForTarget(
+  db: Queryable,
+  workspaceId: string,
+  fromType: string,
+  fromId: string,
+  toType: string,
+  toId: string,
+): Promise<number> {
+  const updated = await db
+    .update(decisions)
+    .set({ targetType: toType, targetId: toId })
+    .where(
+      and(
+        eq(decisions.workspaceId, workspaceId),
+        eq(decisions.targetType, fromType),
+        eq(decisions.targetId, fromId),
+      ),
+    )
+    .returning({ id: decisions.id })
+
+  return updated.length
+}
 export async function memberExists(
   db: Queryable,
   workspaceId: string,

package/src/modules/enquiries/events.ts

@@ -18,7 +18,11 @@ export const enquiriesEvents = {
    * outside Kelpie subscribe to `record.created` on the deal instead. Kept for
    * internal listeners that want the semantic signal.
    */
-  'enquiries.enquiry.converted': z.object({ dealId: z.string() }),
+  'enquiries.enquiry.converted': z.object({
+    dealId: z.string().optional(),
+    targetType: z.string(),
+    targetId: z.string(),
+  }),
 } satisfies ModuleEventCatalog
 
 export type EnquiryCreatedData = Record<string, never>
@@ -31,7 +35,9 @@ export interface EnquiryStageChangedData {
   readonly toStageId: string
 }
 export interface EnquiryConvertedData {
-  readonly dealId: string
+  readonly dealId?: string | undefined
+  readonly targetType: string
+  readonly targetId: string
 }
 
 declare module '../../runtime/events.ts' {

package/src/modules/enquiries/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 { enquiriesEvents } from './events.ts'
 import { mountEnquiriesRoutes } from './routes.ts'
@@ -24,6 +25,7 @@ export function createEnquiriesModule(migrationsDirectory: string): KelpieModule
     events: enquiriesEvents,
 
     register(context) {
+      const conversions = createConversionsFromContext(context)
       const service = createEnquiriesService({
         db: context.db,
         transaction: context.transaction,
@@ -39,10 +41,10 @@ export function createEnquiriesModule(migrationsDirectory: string): KelpieModule
       context.schema(schema, migrationsDirectory)
 
       context.routes((router) => {
-        mountEnquiriesRoutes(router, { db: context.db, now: context.now, service })
+        mountEnquiriesRoutes(router, { db: context.db, now: context.now, service, conversions })
       })
 
-      registerEnquiriesTools(context.mcp, service)
+      registerEnquiriesTools(context.mcp, service, conversions)
 
       return Promise.resolve()
     },

package/src/modules/enquiries/routes.ts

@@ -1,4 +1,4 @@
-import { customFieldsPatchShape } from '@kelpie/schemas'
+import { convertEnquiryBody, convertedToResponse, customFieldsPatchShape } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -7,7 +7,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 { dealResponse } from '../deals/routes.ts'
+import { mountPipelineConvertRoute } from '../conversions/routes.ts'
+import type { ConversionsService } from '../conversions/index.ts'
 import type { CreateEnquiryInput, EnquiriesService, EnquiryView, UpdateEnquiryInput } from './service.ts'
 
 /** Wire shapes for `/v1/enquiries`. Bodies are strict; an unknown field is a 422, per `api.md`. */
@@ -52,6 +53,7 @@ export const updateBody = z.strictObject(enquiryShape).partial()
 
 export interface EnquiriesRoutesDependencies extends CredentialDependencies {
   readonly service: EnquiriesService
+  readonly conversions: ConversionsService
 }
 
 export function toCreateInput(body: z.infer<typeof createBody>): CreateEnquiryInput {
@@ -91,6 +93,7 @@ export function enquiryResponse(enquiry: EnquiryView): Record<string, unknown> {
     company_id: enquiry.companyId,
     owner_id: enquiry.ownerId,
     converted_deal_id: enquiry.convertedDealId,
+    converted_to: convertedToResponse(enquiry.convertedTargetType, enquiry.convertedTargetId),
     person_ids: enquiry.personIds,
     summary: enquiry.summary,
     tags: enquiry.tags,
@@ -156,17 +159,12 @@ export function mountEnquiriesRoutes(
   })
 
   /**
-   * Convert an enquiry to a deal. Idempotent-ish: a second call 409s and
-   * carries the existing deal id in `details`. Returns the freshly created
-   * deal, wire-shaped, so the caller can navigate straight to it.
+   * Convert an enquiry to another pipeline record type. An empty body defaults
+   * the target to a deal for backward compatibility.
    */
-  router.post('/enquiries/:id/convert', async (context) => {
-    const { deal, personIds } = await dependencies.service.convertToDeal(
-      await requireActor(context),
-      context.req.param('id'),
-    )
-    const { workspaceId: _workspaceId, ...dealView } = deal
-
-    return context.json(dealResponse({ ...dealView, personIds }), 201)
+  mountPipelineConvertRoute(router, '/enquiries/:id/convert', {
+    ...dependencies,
+    sourceKind: 'enquiry',
+    bodySchema: convertEnquiryBody,
   })
 }

package/src/modules/enquiries/schema.ts

@@ -1,7 +1,9 @@
+import { sql } from 'drizzle-orm'
+import { check, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+import { PIPELINE_KINDS } from '@kelpie/schemas'
 import type { CustomFieldValue } from '@kelpie/schemas'
-import { 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 { deals } from '../deals/schema.ts'
@@ -17,7 +19,8 @@ import { workspaceMembers, workspaces } from '../workspace/schema.ts'
  * enquiry may arrive before a company is on file. `converted_deal_id` becomes
  * non-null when the enquiry is converted via
  * `POST /v1/enquiries/:id/convert`; deleting the deal nulls it back so a
- * fresh conversion is possible.
+ * fresh conversion is possible. `converted_target_*` generalises that pointer
+ * to any pipeline type.
  */
 export const enquiries = pgTable(
   'enquiries',
@@ -34,6 +37,8 @@ export const enquiries = pgTable(
     companyId: text('company_id').references(() => companies.id, { onDelete: 'restrict' }),
     ownerId: text('owner_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
     convertedDealId: text('converted_deal_id').references(() => deals.id, { onDelete: 'set null' }),
+    convertedTargetType: text('converted_target_type'),
+    convertedTargetId: text('converted_target_id'),
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
     // Workspace-defined fields, keyed by definition key. See people/schema.ts.
@@ -55,5 +60,9 @@ export const enquiries = pgTable(
     index('enquiries_stage_idx').on(table.stageId),
     index('enquiries_converted_deal_idx').on(table.convertedDealId),
     index('enquiries_search_idx').using('gin', table.searchVector),
+    check(
+      'enquiries_converted_target_type_check',
+      sql`${table.convertedTargetType} is null or ${oneOf('enquiries_converted_target_type_check', table.convertedTargetType, PIPELINE_KINDS)}`,
+    ),
   ],
 )

package/src/modules/enquiries/service.ts

@@ -9,9 +9,7 @@ import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
 import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { ActivityRecorder } from '../activities/recorder.ts'
 import {
-  describeConversion,
   describeCreation,
-  describeCreationFrom,
   describeLink,
   describeStageChange,
   describeUnlink,
@@ -22,12 +20,10 @@ import { toEventActor } from '../../lib/actor.ts'
 import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
-import '../deals/events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import { clearConversionPointersToTarget } from '../conversions/clearPointers.ts'
 import * as companyRepository from '../companies/repository.ts'
 import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
-import * as dealRepository from '../deals/repository.ts'
-import type { DealRecord } from '../deals/repository.ts'
 import * as personLinks from '../personLinks.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
 import type { PipelineStageRecord } from '../pipelines/repository.ts'
@@ -108,12 +104,6 @@ export interface UpdateEnquiryInput {
   readonly customFields?: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
-/** What `convertToDeal` returns: the freshly created deal, plus its people. */
-export interface ConvertedDealView {
-  readonly deal: DealRecord
-  readonly personIds: readonly string[]
-}
-
 export interface EnquiriesService {
   list(
     actor: Actor,
@@ -124,7 +114,6 @@ export interface EnquiriesService {
   create(actor: Actor, input: CreateEnquiryInput): Promise<EnquiryView>
   update(actor: Actor, id: string, changes: UpdateEnquiryInput): Promise<EnquiryView>
   remove(actor: Actor, id: string): Promise<void>
-  convertToDeal(actor: Actor, id: string): Promise<ConvertedDealView>
 }
 
 function toView(record: EnquiryRecord, personIds: readonly string[]): EnquiryView {
@@ -492,6 +481,8 @@ export function createEnquiriesService(dependencies: EnquiriesDependencies): Enq
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
+        await clearConversionPointersToTarget(tx, workspaceId, 'enquiry', id)
+
         // Notes, activities, decisions, plan items, person_links, list
         // memberships and form_attach_targets rows are removed here in the
         // same transaction. `form_submissions.enquiry_id` is a set-null FK, so
@@ -502,143 +493,5 @@ export function createEnquiriesService(dependencies: EnquiriesDependencies): Enq
         events.emit('enquiries.enquiry.deleted', { type: 'enquiry', id }, {})
       }, { workspaceId, actor: toEventActor(actor) })
     },
-
-    async convertToDeal(actor, id) {
-      const workspaceId = requireWorkspaceId(actor)
-      const existing = await require(workspaceId, id)
-
-      if (existing.convertedDealId !== null) {
-        throw new AppError(
-          'conflict',
-          'This enquiry has already been converted to a deal',
-          [{ field: 'converted_deal_id', message: `Deal ${existing.convertedDealId}` }],
-        )
-      }
-
-      if (existing.companyId === null) {
-        throw AppError.validationFailed('An enquiry needs a company before it can become a deal', [
-          { field: 'company_id', message: 'Link a company to the enquiry first' },
-        ])
-      }
-
-      const dealStages = await pipelineRepository.listStagesOfKind(
-        dependencies.db,
-        workspaceId,
-        'deal',
-      )
-      const openDealStage = dealStages.find((row) => row.open) ?? dealStages[0]
-
-      if (openDealStage === undefined) {
-        // Unreachable through the API: workspaces seed stages and the last
-        // deal stage cannot be removed.
-        throw AppError.conflict('This workspace has no deal stages')
-      }
-
-      const enquiryStages = await pipelineRepository.listStagesOfKind(
-        dependencies.db,
-        workspaceId,
-        'enquiry',
-      )
-      // A closed enquiry stage is where a converted enquiry lands. If the
-      // workspace has deleted every closed stage we leave the enquiry where it
-      // is rather than refuse the conversion over board cosmetics.
-      const closedEnquiryStage = enquiryStages.find((row) => !row.open)
-
-      const personIds = await personLinks.listPersonIds(dependencies.db, workspaceId, {
-        targetType: 'enquiry',
-        targetId: id,
-      })
-      const dealId = dependencies.createId('deal')
-      const now = dependencies.now()
-
-      return dependencies.transaction(async ({ tx, events }) => {
-        const deal = await dealRepository.insertDeal(tx, {
-          id: dealId,
-          workspaceId,
-          name: existing.name,
-          companyId: existing.companyId as string,
-          stageId: openDealStage.id,
-          valueCents: null,
-          currency: null,
-          ownerId: existing.ownerId,
-          expectedClose: null,
-          competitors: [],
-          risks: '',
-          whyWin: '',
-          summary: existing.summary,
-          tags: [...existing.tags],
-          externalId: null,
-          customFields: {},
-        })
-
-        await personLinks.linkPeople(
-          tx,
-          dependencies.createId,
-          workspaceId,
-          { targetType: 'deal', targetId: dealId },
-          personIds,
-        )
-
-        const stageChanged =
-          closedEnquiryStage !== undefined && closedEnquiryStage.id !== existing.stageId
-        const currentEnquiryStage = enquiryStages.find((row) => row.id === existing.stageId)
-
-        const updatedEnquiry = await repository.updateEnquiry(tx, workspaceId, id, {
-          convertedDealId: dealId,
-          ...(stageChanged ? { stageId: closedEnquiryStage.id } : {}),
-          updatedAt: now,
-        })
-
-        if (updatedEnquiry === undefined) {
-          throw AppError.notFound('Enquiry not found')
-        }
-
-        await dependencies.recordActivity(tx, workspaceId, actor, {
-          targetType: 'deal',
-          targetId: dealId,
-          kind: 'created',
-          ...describeCreationFrom('Deal', 'Enquiry', existing.name),
-        })
-
-        await dependencies.recordActivity(tx, workspaceId, actor, {
-          targetType: 'enquiry',
-          targetId: id,
-          kind: 'updated',
-          ...describeConversion('Deal', deal.name),
-        })
-
-        if (stageChanged && currentEnquiryStage !== undefined) {
-          await dependencies.recordActivity(tx, workspaceId, actor, {
-            targetType: 'enquiry',
-            targetId: id,
-            kind: 'stage_changed',
-            ...describeStageChange(currentEnquiryStage.label, closedEnquiryStage.label),
-          })
-        }
-
-        events.emit('deals.deal.created', { type: 'deal', id: dealId }, {})
-        events.emit(
-          'enquiries.enquiry.updated',
-          { type: 'enquiry', id },
-          {
-            changed: stageChanged
-              ? ['convertedDealId', 'stageId']
-              : ['convertedDealId'],
-          },
-        )
-
-        if (stageChanged && currentEnquiryStage !== undefined) {
-          events.emit(
-            'enquiries.enquiry.stage_changed',
-            { type: 'enquiry', id },
-            { fromStageId: currentEnquiryStage.id, toStageId: closedEnquiryStage.id },
-          )
-        }
-
-        events.emit('enquiries.enquiry.converted', { type: 'enquiry', id }, { dealId })
-
-        return { deal, personIds }
-      }, { workspaceId, actor: toEventActor(actor) })
-    },
   }
 }

package/src/modules/enquiries/tools.ts

@@ -9,7 +9,8 @@ import {
   termArg,
   toSet,
 } from '../crudTools.ts'
-import { dealResponse } from '../deals/routes.ts'
+import type { ConversionsService } from '../conversions/index.ts'
+import { registerEnquiryConvertToDealTool, registerPipelineConvertTool } from '../conversions/mcp.ts'
 import { createBody, enquiryResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
 import type { EnquiriesService } from './service.ts'
 
@@ -24,7 +25,11 @@ const listArgs = z.strictObject({
   person_id: idSetArg.optional().describe('Only enquiries any of these people are on.'),
 })
 
-export function registerEnquiriesTools(mcp: McpToolRegistry, service: EnquiriesService): void {
+export function registerEnquiriesTools(
+  mcp: McpToolRegistry,
+  service: EnquiriesService,
+  conversions: ConversionsService,
+): void {
   registerCrudTools(mcp, {
     resource: 'enquiries',
     subject: 'enquiry',
@@ -47,20 +52,6 @@ export function registerEnquiriesTools(mcp: McpToolRegistry, service: EnquiriesS
     toUpdateInput,
   })
 
-  mcp.tool({
-    name: 'enquiries_convert_to_deal',
-    description:
-      'Convert an enquiry to a Deal. Copies name, company, owner and linked ' +
-      'people to a new deal in the first open deal stage, moves the enquiry ' +
-      'to its first closed stage, and records the link on the enquiry. 409 if ' +
-      'the enquiry has already been converted; 422 if it has no company. ' +
-      'Mirrors POST /v1/enquiries/{id}/convert.',
-    inputSchema: z.strictObject({ id: idArg }),
-    invoke: async ({ id }, actor) => {
-      const { deal, personIds } = await service.convertToDeal(actor, id)
-      const { workspaceId: _workspaceId, ...dealView } = deal
-
-      return dealResponse({ ...dealView, personIds })
-    },
-  })
+  registerPipelineConvertTool(mcp, conversions, 'enquiry')
+  registerEnquiryConvertToDealTool(mcp, conversions)
 }