@kelpie/server 0.8.0 → 0.9.0

package/src/modules/deals/service.ts

@@ -1,3 +1,5 @@
+import type { CustomFieldWireValue } from '@kelpie/schemas'
+
 import { changedKeys } from '../../lib/changes.ts'
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
@@ -20,6 +22,8 @@ import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
 import * as companyRepository from '../companies/repository.ts'
+import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
+import * as personLinks from '../personLinks.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
 import type { PipelineStageRecord } from '../pipelines/repository.ts'
 import * as repository from './repository.ts'
@@ -29,8 +33,8 @@ import type { DealFilters, DealRecord } from './repository.ts'
 /**
  * Deals: the sales pipeline, and the first of the four staged objects.
  *
- * People attach through `deal_people` and appear as `person_ids` on the wire;
- * the join table is a storage detail. A stage move is an ordinary PATCH of
+ * People attach through `person_links` and appear as `person_ids` on the wire;
+ * the polymorphic link table is a storage detail. A stage move is an ordinary PATCH of
  * `stage_id`, and it is the one change that files a `stage_changed` activity and
  * a `stage.changed` event instead of the generic update pair.
  */
@@ -41,6 +45,7 @@ export interface DealsDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
 }
 
 /** What a changed column is called on a timeline. `whyWin` is why these are written out. */
@@ -79,6 +84,8 @@ export interface CreateDealInput {
   readonly summary: string
   readonly tags: readonly string[]
   readonly externalId: string | null
+  /** Wire shape for a create body: `null` values are ignored, non-null are validated. */
+  readonly customFields: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 /** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
@@ -98,6 +105,12 @@ export interface UpdateDealInput {
   readonly summary?: string | undefined
   readonly tags?: readonly string[] | undefined
   readonly externalId?: string | null | undefined
+  /**
+   * Partial merge patch (wire shape): sent keys change, `null` clears a key,
+   * absent keys are left alone. The whole object is undefined when the caller
+   * sent nothing at all. Unknown keys are `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 export interface DealsService {
@@ -201,7 +214,7 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
     workspaceId: string,
     personIds: readonly string[],
   ): Promise<ReadonlyMap<string, string>> {
-    const named = await repository.findPeopleNamed(dependencies.db, workspaceId, personIds)
+    const named = await personLinks.findPeopleNamed(dependencies.db, workspaceId, personIds)
     const missing = personIds.filter((id) => !named.has(id))
 
     if (missing.length > 0) {
@@ -216,9 +229,11 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
   }
 
   /** @returns The page's views, with every deal's people fetched in one query. */
-  async function toViews(records: readonly DealRecord[]): Promise<DealView[]> {
-    const peopleByDeal = await repository.listPersonIdsFor(
+  async function toViews(workspaceId: string, records: readonly DealRecord[]): Promise<DealView[]> {
+    const peopleByDeal = await personLinks.listPersonIdsFor(
       dependencies.db,
+      workspaceId,
+      'deal',
       records.map((record) => record.id),
     )
 
@@ -232,14 +247,20 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
       const rows = await repository.listDeals(dependencies.db, workspaceId, filters, window)
       const page = toPage(rows, window, (deal) => deal.id)
 
-      return { items: await toViews(page.items), nextCursor: page.nextCursor }
+      return { items: await toViews(workspaceId, page.items), nextCursor: page.nextCursor }
     },
 
     async get(actor, id) {
       const workspaceId = requireWorkspaceId(actor)
       const deal = await require(workspaceId, id)
 
-      return toView(deal, await repository.listPersonIds(dependencies.db, id))
+      return toView(
+        deal,
+        await personLinks.listPersonIds(dependencies.db, workspaceId, {
+          targetType: 'deal',
+          targetId: id,
+        }),
+      )
     },
 
     async create(actor, input) {
@@ -262,6 +283,12 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
       const id = dependencies.createId('deal')
 
       return dependencies.transaction(async ({ tx, events }) => {
+        const customFields = await dependencies.customFields.forCreate(
+          tx,
+          workspaceId,
+          'deal',
+          input.customFields,
+        )
         const created = await repository.insertDeal(tx, {
           id,
           workspaceId,
@@ -278,9 +305,16 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
           summary: input.summary,
           tags: [...input.tags],
           externalId: input.externalId,
+          customFields,
         })
 
-        await repository.insertDealPeople(tx, id, personIds)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'deal', targetId: id },
+          personIds,
+        )
 
         await dependencies.recordActivity(tx, workspaceId, actor, {
           targetType: 'deal',
@@ -325,7 +359,10 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
         await requireOwner(workspaceId, changes.ownerId)
       }
 
-      const currentPeople = await repository.listPersonIds(dependencies.db, id)
+      const currentPeople = await personLinks.listPersonIds(dependencies.db, workspaceId, {
+        targetType: 'deal',
+        targetId: id,
+      })
       const nextPeople = changes.personIds === undefined ? undefined : [...new Set(changes.personIds)]
       const added =
         nextPeople === undefined ? [] : nextPeople.filter((personId) => !currentPeople.includes(personId))
@@ -334,16 +371,26 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
       const named = await requirePeople(workspaceId, [...added, ...removed])
 
       const columns = toStoredColumns(changes)
-      const changed = changedKeys(existing, columns)
+      const scalarChanged = changedKeys(existing, columns)
       const linksChanged = added.length > 0 || removed.length > 0
 
-      if (changed.length === 0 && !linksChanged) {
-        return toView(existing, currentPeople)
-      }
-
       return dependencies.transaction(async ({ tx, events }) => {
+        const cf = await dependencies.customFields.forUpdate(
+          tx,
+          workspaceId,
+          'deal',
+          existing.customFields,
+          changes.customFields,
+        )
+        const customFieldsChanged = cf !== undefined && cf.changedPaths.length > 0
+
+        if (scalarChanged.length === 0 && !linksChanged && !customFieldsChanged) {
+          return toView(existing, currentPeople)
+        }
+
         const updated = await repository.updateDeal(tx, workspaceId, id, {
           ...columns,
+          ...(customFieldsChanged ? { customFields: cf.merged } : {}),
           updatedAt: dependencies.now(),
         })
 
@@ -351,8 +398,19 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
           throw AppError.notFound('Deal not found')
         }
 
-        await repository.insertDealPeople(tx, id, added)
-        await repository.deleteDealPeople(tx, id, removed)
+        await personLinks.linkPeople(
+          tx,
+          dependencies.createId,
+          workspaceId,
+          { targetType: 'deal', targetId: id },
+          added,
+        )
+        await personLinks.unlinkPeople(
+          tx,
+          workspaceId,
+          { targetType: 'deal', targetId: id },
+          removed,
+        )
 
         if (stageMove !== undefined) {
           await dependencies.recordActivity(tx, workspaceId, actor, {
@@ -363,14 +421,19 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
           })
         }
 
-        const otherChanged = changed.filter((field) => field !== 'stageId')
+        const otherChanged = scalarChanged.filter((field) => field !== 'stageId')
+        const customFieldPaths = cf?.changedPaths ?? []
+        const activityChanged = [...otherChanged, ...customFieldPaths]
 
-        if (otherChanged.length > 0) {
+        if (activityChanged.length > 0) {
+          const labels: Record<string, string> = { ...DEAL_FIELD_LABELS, ...cf?.labels }
+          const before: Record<string, unknown> = { ...existing, ...cf?.flatBefore }
+          const after: Record<string, unknown> = { ...columns, ...cf?.flatAfter }
           await dependencies.recordActivity(tx, workspaceId, actor, {
             targetType: 'deal',
             targetId: id,
             kind: 'updated',
-            ...describeUpdate(otherChanged, DEAL_FIELD_LABELS, existing, columns),
+            ...describeUpdate(activityChanged, labels, before, after),
           })
         }
 
@@ -398,7 +461,13 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
         events.emit(
           'deals.deal.updated',
           { type: 'deal', id },
-          { changed: linksChanged ? [...changed, 'personIds'] : changed },
+          {
+            changed: [
+              ...scalarChanged,
+              ...(linksChanged ? ['personIds'] : []),
+              ...customFieldPaths,
+            ],
+          },
         )
 
         if (stageMove !== undefined) {
@@ -419,9 +488,9 @@ export function createDealsService(dependencies: DealsDependencies): DealsServic
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
-        // `deal_people` dies with the deal through its foreign key and form
-        // submissions unlink themselves; notes, activities, decisions and plan
-        // items have no key, so they are removed here, in the same transaction.
+        // 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.
         await deleteRecordsAttachedTo(tx, workspaceId, 'deal', id)
         await repository.deleteDeal(tx, workspaceId, id)
 

package/src/modules/decisions/repository.ts

@@ -7,6 +7,7 @@ import { containsPattern } from '../../lib/search.ts'
 import type { Queryable } from '../../runtime/transaction.ts'
 import { companies } from '../companies/schema.ts'
 import { deals } from '../deals/schema.ts'
+import { enquiries } from '../enquiries/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
 import { partnerships } from '../partnerships/schema.ts'
 import { people } from '../people/schema.ts'
@@ -55,6 +56,7 @@ const NAMED_TARGET_TABLES = [
   { table: opportunities, id: opportunities.id, workspaceId: opportunities.workspaceId, name: opportunities.name },
   { table: partnerships, id: partnerships.id, workspaceId: partnerships.workspaceId, name: partnerships.name },
   { table: raises, id: raises.id, workspaceId: raises.workspaceId, name: raises.name },
+  { table: enquiries, id: enquiries.id, workspaceId: enquiries.workspaceId, name: enquiries.name },
 ]
 
 /**

package/src/modules/enquiries/events.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the enquiries module. */
+
+export const enquiriesEvents = {
+  'enquiries.enquiry.created': z.object({}).strict(),
+  'enquiries.enquiry.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'enquiries.enquiry.deleted': z.object({}).strict(),
+  'enquiries.enquiry.stage_changed': z.object({
+    fromStageId: z.string().nullable(),
+    toStageId: z.string(),
+  }),
+  /**
+   * The enquiry has been converted to a Deal. Fires from
+   * `POST /v1/enquiries/:id/convert`. Not deliverable as a webhook: consumers
+   * 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() }),
+} satisfies ModuleEventCatalog
+
+export type EnquiryCreatedData = Record<string, never>
+export interface EnquiryUpdatedData {
+  readonly changed: readonly string[]
+}
+export type EnquiryDeletedData = Record<string, never>
+export interface EnquiryStageChangedData {
+  readonly fromStageId: string | null
+  readonly toStageId: string
+}
+export interface EnquiryConvertedData {
+  readonly dealId: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'enquiries.enquiry.created': EnquiryCreatedData
+    'enquiries.enquiry.updated': EnquiryUpdatedData
+    'enquiries.enquiry.deleted': EnquiryDeletedData
+    'enquiries.enquiry.stage_changed': EnquiryStageChangedData
+    'enquiries.enquiry.converted': EnquiryConvertedData
+  }
+}

package/src/modules/enquiries/index.ts

@@ -0,0 +1,50 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { createCustomFieldValues } from '../custom-fields/index.ts'
+import { enquiriesEvents } from './events.ts'
+import { mountEnquiriesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createEnquiriesService } from './service.ts'
+import { registerEnquiriesTools } from './tools.ts'
+
+/**
+ * Enquiries: the top-of-funnel pipeline.
+ *
+ * Requires its relations because creating one checks that the company, stage,
+ * and owner are all in the caller's workspace before linking them, and
+ * `activities` because every write leaves its timeline entry in the same
+ * transaction. `deals` is required for `convertToDeal`, which inserts into
+ * the deals table directly (the standard cross-module write pattern, per
+ * `architecture.md`).
+ */
+export function createEnquiriesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'enquiries',
+    requires: ['companies', 'pipelines', 'activities', 'custom-fields', 'deals'],
+    events: enquiriesEvents,
+
+    register(context) {
+      const service = createEnquiriesService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity: createActivityRecorder({
+          createId: context.createId,
+          now: context.now,
+        }),
+        customFields: createCustomFieldValues({ db: context.db }),
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountEnquiriesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerEnquiriesTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/enquiries/repository.ts

@@ -0,0 +1,164 @@
+import { and, eq, ilike, inArray, or, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { arrayContainsPattern, containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { companies } from '../companies/schema.ts'
+import { anyPersonLinked } from '../personLinks.ts'
+import { workspaceMembers } from '../workspace/schema.ts'
+import { enquiries } from './schema.ts'
+
+export type EnquiryRecord = typeof enquiries.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type EnquiryColumns = typeof enquiries.$inferInsert
+
+/** The sort fields `?sort=` documents. */
+export const ENQUIRY_SORTS: SortableFields<EnquiryRecord> = {
+  name: textSort(enquiries.name, (enquiry) => enquiry.name),
+  created_at: timestampSort(enquiries.createdAt, (enquiry) => enquiry.createdAt),
+  updated_at: timestampSort(enquiries.updatedAt, (enquiry) => enquiry.updatedAt),
+}
+
+export const DEFAULT_ENQUIRY_SORT = '-created_at'
+
+export interface EnquiryFilters {
+  /** `?q=`: name, source, summary, tags, or the company's name. */
+  readonly term?: string | undefined
+  /** `?source=`, repeatable: sources are free text, so a match is exact, not fuzzy. */
+  readonly sources?: readonly string[] | undefined
+  /** `?company_id=`, repeatable. */
+  readonly companyIds?: readonly string[] | undefined
+  /** `?stage_id=`, repeatable: the board fetches one column with one of these. */
+  readonly stageIds?: readonly string[] | undefined
+  /** `?person_id=`, repeatable: enquiries any of these people are on. */
+  readonly personIds?: readonly string[] | undefined
+}
+
+/**
+ * The company half of `?q=`. Reads the `companies` *table*, never its
+ * repository, the rule set for a filter spanning a relation (`architecture.md`).
+ */
+function companyNameMatches(pattern: string): SQL {
+  return sql`exists (
+    select 1
+    from ${companies}
+    where ${companies.id} = ${enquiries.companyId}
+      and ${companies.workspaceId} = ${enquiries.workspaceId}
+      and ${companies.name} ilike ${pattern}
+  )`
+}
+
+function matchesTerm(term: string): SQL | undefined {
+  const pattern = containsPattern(term)
+
+  return or(
+    ilike(enquiries.name, pattern),
+    ilike(enquiries.source, pattern),
+    ilike(enquiries.summary, pattern),
+    arrayContainsPattern(enquiries.tags, pattern),
+    companyNameMatches(pattern),
+  )
+}
+
+function conditionsFor(workspaceId: string, filters: EnquiryFilters): (SQL | undefined)[] {
+  return [
+    eq(enquiries.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : matchesTerm(filters.term),
+    filters.sources === undefined ? undefined : inArray(enquiries.source, filters.sources),
+    filters.companyIds === undefined
+      ? undefined
+      : inArray(enquiries.companyId, filters.companyIds),
+    filters.stageIds === undefined ? undefined : inArray(enquiries.stageId, filters.stageIds),
+    filters.personIds === undefined
+      ? undefined
+      : anyPersonLinked('enquiry', enquiries.id, enquiries.workspaceId, filters.personIds),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listEnquiries(
+  db: Queryable,
+  workspaceId: string,
+  filters: EnquiryFilters,
+  window: ListWindow<EnquiryRecord>,
+): Promise<EnquiryRecord[]> {
+  return db
+    .select()
+    .from(enquiries)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, enquiries.id)))
+    .orderBy(...orderByWindow(window, enquiries.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<EnquiryRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(enquiries)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertEnquiry(
+  db: Queryable,
+  values: EnquiryColumns,
+): Promise<EnquiryRecord> {
+  const [created] = await db.insert(enquiries).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting enquiry ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<EnquiryColumns>,
+): Promise<EnquiryRecord | undefined> {
+  const [updated] = await db
+    .update(enquiries)
+    .set(changes)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(enquiries)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .returning({ id: enquiries.id })
+
+  return deleted.length
+}
+
+/** Whether a member belongs to this workspace, for validating `owner_id`. */
+export async function memberExists(
+  db: Queryable,
+  workspaceId: string,
+  memberId: string,
+): Promise<boolean> {
+  const [found] = await db
+    .select({ id: workspaceMembers.id })
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.id, memberId)))
+    .limit(1)
+
+  return found !== undefined
+}