@kelpie/server 0.7.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/email-domain-linker/index.ts

@@ -0,0 +1,40 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountEmailDomainLinkerRoutes } from './routes.ts'
+import { createEmailDomainLinkerService } from './service.ts'
+
+/**
+ * Rebuild every email-domain link across the workspace.
+ *
+ * Owns no tables. Requires the modules whose data the sweep reads and writes.
+ * The sweep is the same one the companies service runs on a domain change,
+ * applied to every workspace Company at once — used to backfill links for
+ * data that predates the auto-linker, or after a bulk import.
+ */
+export function createEmailDomainLinkerModule(): KelpieModule {
+  return {
+    id: 'email-domain-linker',
+    requires: ['workspace', 'companies', 'people', 'positions', 'activities'],
+
+    register(context) {
+      const service = createEmailDomainLinkerService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity: createActivityRecorder({
+          createId: context.createId,
+          now: context.now,
+        }),
+      })
+
+      context.routes((router) => {
+        mountEmailDomainLinkerRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      return Promise.resolve()
+    },
+  }
+}
+
+export type { EmailDomainLinkerService, RelinkCounts } from './service.ts'

package/src/modules/email-domain-linker/routes.ts

@@ -0,0 +1,40 @@
+import type { Context, Hono } from 'hono'
+
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type { EmailDomainLinkerService, RelinkCounts } from './service.ts'
+
+/**
+ * Wire shape for `POST /v1/workspaces/:id/relink-email-domains`.
+ *
+ * No request body. The response counts what the sweep did.
+ */
+
+export interface EmailDomainLinkerRoutesDependencies extends CredentialDependencies {
+  readonly service: EmailDomainLinkerService
+}
+
+export function relinkResponse(counts: RelinkCounts): Record<string, unknown> {
+  return {
+    companies_scanned: counts.companiesScanned,
+    positions_created: counts.positionsCreated,
+  }
+}
+
+export function mountEmailDomainLinkerRoutes(
+  router: Hono,
+  dependencies: EmailDomainLinkerRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> =>
+    resolveActorFrom(dependencies, context)
+
+  router.post('/workspaces/:id/relink-email-domains', async (context) => {
+    const counts = await dependencies.service.relink(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(relinkResponse(counts))
+  })
+}

package/src/modules/email-domain-linker/service.ts

@@ -0,0 +1,122 @@
+import { and, eq, isNotNull } from 'drizzle-orm'
+
+import { toEventActor } from '../../lib/actor.ts'
+import type { Database } from '../../lib/database.ts'
+import { autoLinkCompanyByDomain } from '../../lib/emailDomainAutoLink.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import * as authRepository from '../auth/repository.ts'
+import { companies } from '../companies/schema.ts'
+import { parseMemberRole, roleAllows } from '../workspace/roles.ts'
+
+/**
+ * Rebuild every email-domain link across the workspace.
+ *
+ * Iterates each Company that carries a domain and runs the same sweep the
+ * companies service runs on a domain change — every workspace Person whose
+ * email is at that domain gets a titleless Position where none exists yet.
+ *
+ * Idempotent: a follow-up run adds nothing. Add-only, consumer-host-skipping,
+ * and workspace-scoped, same as the inline auto-linker.
+ *
+ * One transaction per Company, not one for the whole sweep. A workspace can
+ * carry thousands of Companies, and a single transaction that long would
+ * hold row-share locks against every write elsewhere for the whole run.
+ */
+
+export interface EmailDomainLinkerDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+export interface RelinkCounts {
+  /** Companies with a non-null domain that were considered. Consumer hosts are counted but skipped. */
+  readonly companiesScanned: number
+  /** New Positions the sweep inserted this run. */
+  readonly positionsCreated: number
+}
+
+export interface EmailDomainLinkerService {
+  relink(actor: Actor, workspaceId: string): Promise<RelinkCounts>
+}
+
+export function createEmailDomainLinkerService(
+  dependencies: EmailDomainLinkerDependencies,
+): EmailDomainLinkerService {
+  async function requireAdmin(actor: Actor, workspaceId: string): Promise<void> {
+    if (actor.workspaceId !== workspaceId) {
+      throw AppError.notFound('Workspace not found')
+    }
+
+    if (actor.kind === 'api_key' && actor.userId === null) {
+      if (!roleAllows(actor.role, 'admin')) {
+        throw new AppError('forbidden', 'This action needs the admin role')
+      }
+      return
+    }
+
+    const userId = actor.userId
+
+    if (userId === null) {
+      throw AppError.notFound('Workspace not found')
+    }
+
+    const membership = await authRepository.findMembership(dependencies.db, workspaceId, userId)
+
+    if (membership === undefined) {
+      throw AppError.notFound('Workspace not found')
+    }
+
+    const role = parseMemberRole(membership.role)
+
+    if (role === undefined) {
+      throw new Error(`workspace_members.role holds "${membership.role}", which its check forbids`)
+    }
+
+    if (!roleAllows(role, 'admin')) {
+      throw new AppError('forbidden', 'This action needs the admin role')
+    }
+  }
+
+  return {
+    async relink(actor, workspaceId) {
+      requireWorkspaceId(actor)
+      await requireAdmin(actor, workspaceId)
+
+      // Every workspace Company that carries a domain — the ones the sweep
+      // can match against. Pooled read outside the per-company transactions:
+      // the work-list is one query, each write opens its own scope.
+      const rows = await dependencies.db
+        .select()
+        .from(companies)
+        .where(and(eq(companies.workspaceId, workspaceId), isNotNull(companies.domain)))
+
+      let created = 0
+
+      // One transaction per Company, not one for the whole sweep. A workspace
+      // can carry thousands of Companies; a single transaction that long would
+      // hold row-share locks against every write elsewhere for the whole run.
+      for (const company of rows) {
+        const inserted = await dependencies.transaction(
+          async ({ tx, events }) =>
+            autoLinkCompanyByDomain(tx, events, workspaceId, company, {
+              createId: dependencies.createId,
+              now: dependencies.now,
+              recordActivity: dependencies.recordActivity,
+            }),
+          { workspaceId, actor: toEventActor(actor) },
+        )
+        created += inserted.length
+      }
+
+      return { companiesScanned: rows.length, positionsCreated: created }
+    },
+  }
+}

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