@kelpie/server 0.7.0 → 0.9.0

package/migrations/meta/_journal.json

@@ -148,6 +148,118 @@
       "when": 1787447911296,
       "tag": "0020_early_nemesis",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1787527717966,
+      "tag": "0021_certain_maggott",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1787626585359,
+      "tag": "0022_stormy_manta",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1787651539093,
+      "tag": "0023_funny_maddog",
+      "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "7",
+      "when": 1787978002874,
+      "tag": "0024_third_king_cobra",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1787979321712,
+      "tag": "0025_worthless_chimera",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1787981859874,
+      "tag": "0026_late_aqueduct",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1788007470077,
+      "tag": "0027_brainy_silver_sable",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1788045423814,
+      "tag": "0028_freezing_scrambler",
+      "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1788067713235,
+      "tag": "0029_custom_fields",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1788089808149,
+      "tag": "0030_enquiries",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1788128702292,
+      "tag": "0031_consent",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1788133056653,
+      "tag": "0032_form_field_statement",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "7",
+      "when": 1788134204561,
+      "tag": "0033_form_field_consent_purpose_ids",
+      "breakpoints": true
+    },
+    {
+      "idx": 34,
+      "version": "7",
+      "when": 1788134239537,
+      "tag": "0034_drop_form_field_consent_purpose_id",
+      "breakpoints": true
+    },
+    {
+      "idx": 35,
+      "version": "7",
+      "when": 1788146179776,
+      "tag": "0035_form_field_consent_purpose_labels",
+      "breakpoints": true
+    },
+    {
+      "idx": 36,
+      "version": "7",
+      "when": 1788146891073,
+      "tag": "0036_form_field_notice_type",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
   "keywords": [
     "kelpie",
@@ -52,11 +52,12 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
-    "@kelpie/schemas": "^0.7.0",
+    "@kelpie/schemas": "^0.9.0",
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "emittery": "^2.0.0",
     "hono": "^4.12.32",
+    "mailgen": "^2.0.36",
     "nodemailer": "^9.0.5",
     "postgres": "^3.4.9",
     "ulid": "^3.0.2",

package/src/lib/consumerEmailDomains.ts

@@ -0,0 +1,62 @@
+/**
+ * Consumer email hosts, checked case-insensitively.
+ *
+ * The email-domain listener refuses to auto-link a Person to a Company on any
+ * domain in this list. A consumer address belongs to no one company, and a
+ * Company row entered by mistake against, say, `gmail.com` would otherwise
+ * auto-attach every consumer address after.
+ *
+ * A starter list of the common providers. Add locale variants and less common
+ * hosts as the need arrives.
+ */
+const CONSUMER_EMAIL_DOMAINS: ReadonlySet<string> = new Set([
+  'gmail.com',
+  'googlemail.com',
+  'yahoo.com',
+  'yahoo.co.uk',
+  'yahoo.co.jp',
+  'yahoo.fr',
+  'yahoo.de',
+  'yahoo.ca',
+  'yahoo.com.au',
+  'ymail.com',
+  'rocketmail.com',
+  'hotmail.com',
+  'hotmail.co.uk',
+  'hotmail.fr',
+  'hotmail.de',
+  'hotmail.it',
+  'hotmail.es',
+  'outlook.com',
+  'outlook.co.uk',
+  'live.com',
+  'live.co.uk',
+  'msn.com',
+  'aol.com',
+  'aim.com',
+  'icloud.com',
+  'me.com',
+  'mac.com',
+  'protonmail.com',
+  'proton.me',
+  'pm.me',
+  'gmx.com',
+  'gmx.net',
+  'gmx.de',
+  'mail.com',
+  'fastmail.com',
+  'fastmail.fm',
+  'zoho.com',
+  'yandex.com',
+  'yandex.ru',
+  'tutanota.com',
+  'tuta.io',
+  'qq.com',
+  '163.com',
+  '126.com',
+  'naver.com',
+])
+
+export function isConsumerEmailDomain(domain: string): boolean {
+  return CONSUMER_EMAIL_DOMAINS.has(domain.trim().toLowerCase())
+}

package/src/lib/email.ts

@@ -21,7 +21,14 @@ import type { Logger } from './logger.ts'
 export interface EmailMessage {
   readonly to: string
   readonly subject: string
+  /** The plaintext part. Always present: text-only clients and logs read it. */
   readonly body: string
+  /**
+   * The HTML alternative, rendered by `lib/emailContent.ts`. Optional so
+   * provider modules written against the older port keep compiling and a
+   * plain-text message stays expressible.
+   */
+  readonly html?: string
 }
 
 export interface EmailSender {

package/src/lib/emailContent.ts

@@ -0,0 +1,91 @@
+import Mailgen from 'mailgen'
+
+/**
+ * Renders transactional mail bodies: a plaintext part and an HTML part from
+ * one description of the message.
+ *
+ * Email clients need table-based, inline-styled HTML; mailgen owns that
+ * problem so Kelpie does not. The plaintext part is built here by hand rather
+ * than by mailgen's plaintext generator, because that generator pads lines
+ * with trailing whitespace and the plaintext body is the part tests and
+ * text-only clients read token links out of. The wording of the two parts
+ * comes from the same fields, so they cannot drift.
+ */
+
+/** A link the message asks the reader to follow, rendered as a button in HTML. */
+export interface EmailAction {
+  readonly instructions: string
+  readonly buttonText: string
+  readonly link: string
+}
+
+export interface EmailContent {
+  readonly intro?: string
+  readonly action?: EmailAction
+  readonly outro?: string
+}
+
+export interface RenderedEmail {
+  readonly text: string
+  readonly html: string
+}
+
+/**
+ * Fixed so rendering is deterministic. Mailgen's default footer stamps the
+ * current year, which the sender has no claim to: the workspace, not Kelpie,
+ * owns the relationship with the recipient.
+ */
+const FOOTER_LINE = 'Sent by Kelpie.'
+
+/**
+ * Renders one transactional message. `appBaseUrl` becomes the link on the
+ * product name in the header and footer, so every part of the mail points at
+ * the deployment that sent it.
+ */
+export function renderEmail(content: EmailContent, appBaseUrl: string): RenderedEmail {
+  const generator = new Mailgen({
+    theme: 'default',
+    product: {
+      name: 'Kelpie',
+      link: appBaseUrl,
+      copyright: FOOTER_LINE,
+    },
+  })
+
+  const html: string = generator.generate({
+    body: {
+      greeting: false,
+      signature: false,
+      ...(content.intro === undefined ? {} : { intro: content.intro }),
+      ...(content.action === undefined
+        ? {}
+        : {
+            action: {
+              instructions: content.action.instructions,
+              button: {
+                text: content.action.buttonText,
+                link: content.action.link,
+                fallback: true,
+              },
+            },
+          }),
+      ...(content.outro === undefined ? {} : { outro: content.outro }),
+    },
+  })
+
+  const paragraphs: string[] = []
+
+  if (content.intro !== undefined) {
+    paragraphs.push(content.intro)
+  }
+
+  if (content.action !== undefined) {
+    paragraphs.push(`${content.action.instructions}\n\n${content.action.link}`)
+  }
+
+  if (content.outro !== undefined) {
+    paragraphs.push(content.outro)
+  }
+
+  return { text: paragraphs.join('\n\n'), html }
+}

package/src/lib/emailDomainAutoLink.ts

@@ -0,0 +1,165 @@
+import { UNIQUE_VIOLATION, postgresErrorCode } from './database.ts'
+import type { IdFactory } from './ids.ts'
+import { isConsumerEmailDomain } from './consumerEmailDomains.ts'
+import type { BufferedEvents, Transaction } from '../runtime/transaction.ts'
+import type { ActivityRecorder, SystemActor } from '../modules/activities/recorder.ts'
+import { describeLink } from '../modules/activities/wording.ts'
+import * as companyRepository from '../modules/companies/repository.ts'
+import type { CompanyRecord } from '../modules/companies/repository.ts'
+import * as peopleRepository from '../modules/people/repository.ts'
+import type { PersonRecord } from '../modules/people/repository.ts'
+import '../modules/positions/events.ts'
+import * as positionRepository from '../modules/positions/repository.ts'
+
+/**
+ * Auto-link a Person to a workspace Company whose domain matches the person's
+ * email. Runs inside the caller's transaction, so the new Position is present
+ * in the response the API returns for the same request.
+ *
+ * Skips: no email, consumer email host (`isConsumerEmailDomain`), no Company
+ * on that domain in the workspace, or a Position already linking the two. A
+ * unique-key race with a concurrent linker is absorbed.
+ *
+ * The created Position carries an empty title. `positions.title` is `NOT NULL`,
+ * and empty reads honestly as "the domain matched; no title yet".
+ *
+ * Split from the people service so the layering (people below positions) is
+ * carried by imports only: this helper depends on both repositories, and the
+ * people service depends on this helper. The `positions` module still owns the
+ * event catalogue for the emitted event.
+ */
+
+/** What the timeline calls this side effect. */
+const LINKER_ACTOR: SystemActor = { kind: 'system', label: 'Email domain match' }
+
+export interface AutoLinkDependencies {
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/**
+ * Considers `person` for a matching Company in `workspaceId` and inserts a
+ * titleless Position if none links them yet.
+ *
+ * @returns The new Position's id, or `undefined` if nothing was written.
+ */
+export async function autoLinkPersonByEmailDomain(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  person: PersonRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<string | undefined> {
+  if (person.email === null) {
+    return undefined
+  }
+
+  const at = person.email.indexOf('@')
+  if (at < 0) {
+    return undefined
+  }
+
+  const domain = person.email.slice(at + 1)
+  if (domain.length === 0 || isConsumerEmailDomain(domain)) {
+    return undefined
+  }
+
+  const company = await companyRepository.findCompanyByDomain(tx, workspaceId, domain)
+  if (company === undefined) {
+    return undefined
+  }
+
+  const held = await positionRepository.listPositionsAt(tx, workspaceId, person.id, company.id)
+  if (held.length > 0) {
+    return undefined
+  }
+
+  return insertStubPosition(tx, events, workspaceId, person, company, dependencies)
+}
+
+/**
+ * Sweeps every Person in `workspaceId` whose email domain matches `company`'s
+ * domain and stubs a Position where none exists yet. Called when a Company is
+ * created or its domain is set.
+ *
+ * @returns The ids of every Position this call inserted.
+ */
+export async function autoLinkCompanyByDomain(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  company: CompanyRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<readonly string[]> {
+  if (company.domain === null || company.domain.length === 0) {
+    return []
+  }
+
+  if (isConsumerEmailDomain(company.domain)) {
+    return []
+  }
+
+  const matches = await peopleRepository.findPeopleByEmailDomain(tx, workspaceId, company.domain)
+  const created: string[] = []
+
+  for (const person of matches) {
+    const held = await positionRepository.listPositionsAt(tx, workspaceId, person.id, company.id)
+    if (held.length > 0) {
+      continue
+    }
+
+    const id = await insertStubPosition(tx, events, workspaceId, person, company, dependencies)
+    if (id !== undefined) {
+      created.push(id)
+    }
+  }
+
+  return created
+}
+
+/**
+ * The write half. Wraps the unique-constraint race the two entry points share:
+ * a concurrent linker that beat us to `(personId, companyId, '')` is treated
+ * as success (the link is there, either way).
+ */
+async function insertStubPosition(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  person: PersonRecord,
+  company: CompanyRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<string | undefined> {
+  try {
+    const created = await positionRepository.insertPosition(tx, {
+      id: dependencies.createId('position'),
+      workspaceId,
+      personId: person.id,
+      companyId: company.id,
+      title: '',
+    })
+
+    await dependencies.recordActivity(tx, workspaceId, LINKER_ACTOR, {
+      targetType: 'person',
+      targetId: person.id,
+      kind: 'linked',
+      ...describeLink('company', company.name),
+    })
+    await dependencies.recordActivity(tx, workspaceId, LINKER_ACTOR, {
+      targetType: 'company',
+      targetId: company.id,
+      kind: 'linked',
+      ...describeLink('person', person.name),
+    })
+
+    events.emit('positions.position.created', { type: 'position', id: created.id }, {})
+
+    return created.id
+  } catch (error: unknown) {
+    if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+      return undefined
+    }
+    throw error
+  }
+}

package/src/lib/ids.ts

@@ -19,6 +19,7 @@ export const idPrefixes = {
   position: 'pos',
   pipelineStage: 'stage',
   deal: 'deal',
+  enquiry: 'enq',
   opportunity: 'opp',
   partnership: 'prt',
   raise: 'rse',
@@ -28,7 +29,19 @@ export const idPrefixes = {
   decision: 'dec',
   note: 'note',
   activity: 'act',
+  list: 'list',
+  listMember: 'lmem',
+  /**
+   * Never returns over the wire either: `person_links` has no routes of its
+   * own — the link surfaces as a `person_ids` array on each pipeline record —
+   * so the prefix is not in `api.md`'s public prefix table, matching `idem`
+   * and `rl`. It still comes from this factory rather than a bare ULID call,
+   * so every id in the database is generated the same, injectable way.
+   */
+  personLink: 'plink',
   handbookPage: 'hb',
+  customFieldDefinition: 'fld',
+  consentPurpose: 'cnp',
   form: 'form',
   formField: 'ff',
   formSubmission: 'sub',

package/src/modules/activities/repository.ts

@@ -1,12 +1,16 @@
 import { and, eq, inArray, or, sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
 
+import type { PipelineKind } from '@kelpie/schemas'
+
 import { keysetCondition, orderByWindow, timestampSort } from '../../lib/pagination.ts'
 import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
 import type { Queryable } from '../../runtime/transaction.ts'
-import { dealPeople, deals } from '../deals/schema.ts'
+import { deals } from '../deals/schema.ts'
+import { enquiries } from '../enquiries/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
-import { partnershipPeople, partnerships } from '../partnerships/schema.ts'
+import { partnerships } from '../partnerships/schema.ts'
+import * as personLinks from '../personLinks.ts'
 import type { RecordTargetType } from '../recordTargets.ts'
 import { activities } from './schema.ts'
 
@@ -66,7 +70,7 @@ export async function listRolledUpTargets(
   targetId: string,
 ): Promise<ActivityTarget[]> {
   if (targetType === 'company') {
-    const [dealRows, opportunityRows, partnershipRows] = await Promise.all([
+    const [dealRows, opportunityRows, partnershipRows, enquiryRows] = await Promise.all([
       db
         .select({ id: deals.id })
         .from(deals)
@@ -81,36 +85,31 @@ export async function listRolledUpTargets(
         .select({ id: partnerships.id })
         .from(partnerships)
         .where(and(eq(partnerships.workspaceId, workspaceId), eq(partnerships.companyId, targetId))),
+      db
+        .select({ id: enquiries.id })
+        .from(enquiries)
+        .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.companyId, targetId))),
     ])
 
     return [
       ...dealRows.map((row) => ({ targetType: 'deal' as const, targetId: row.id })),
       ...opportunityRows.map((row) => ({ targetType: 'opportunity' as const, targetId: row.id })),
       ...partnershipRows.map((row) => ({ targetType: 'partnership' as const, targetId: row.id })),
+      ...enquiryRows.map((row) => ({ targetType: 'enquiry' as const, targetId: row.id })),
     ]
   }
 
   if (targetType === 'person') {
-    // An opportunity has no people, so a person rolls up two relations, not three.
-    const [dealRows, partnershipRows] = await Promise.all([
-      db
-        .select({ id: deals.id })
-        .from(deals)
-        .innerJoin(dealPeople, eq(dealPeople.dealId, deals.id))
-        .where(and(eq(deals.workspaceId, workspaceId), eq(dealPeople.personId, targetId))),
-      db
-        .select({ id: partnerships.id })
-        .from(partnerships)
-        .innerJoin(partnershipPeople, eq(partnershipPeople.partnershipId, partnerships.id))
-        .where(
-          and(eq(partnerships.workspaceId, workspaceId), eq(partnershipPeople.personId, targetId)),
-        ),
-    ])
-
-    return [
-      ...dealRows.map((row) => ({ targetType: 'deal' as const, targetId: row.id })),
-      ...partnershipRows.map((row) => ({ targetType: 'partnership' as const, targetId: row.id })),
-    ]
+    // person_links carries all four pipeline kinds in one table, so a person's
+    // roll-up is one read regardless of how many pipelines they touch. The
+    // shared helper's `PipelineKind` narrows to the check-constraint set, which
+    // is exactly what an ActivityTarget expects to receive.
+    const links = await personLinks.listTargetsOfPerson(db, workspaceId, targetId)
+
+    return links.map((link) => ({
+      targetType: link.targetType satisfies PipelineKind as RecordTargetType,
+      targetId: link.targetId,
+    }))
   }
 
   return []

package/src/modules/activities/wording.ts

@@ -147,6 +147,24 @@ export function describeStageChange(fromStage: string, toStage: string): Activit
   return { action: `moved to ${toStage}`, detail: `${fromStage} → ${toStage}` }
 }
 
+/**
+ * `converted to Deal`, with the deal's name beneath it. Files on the enquiry;
+ * the deal's own timeline gets `created Deal from Enquiry` via
+ * `describeCreationFrom`.
+ */
+export function describeConversion(objectLabel: string, name: string): ActivityWording {
+  return { action: `converted to ${objectLabel}`, detail: name }
+}
+
+/**
+ * `created Deal from Enquiry`, with the source record's name beneath it. Mirror
+ * of `describeCreationVia` but the source is another CRM record rather than a
+ * form or import file.
+ */
+export function describeCreationFrom(objectLabel: string, sourceLabel: string, sourceName: string): ActivityWording {
+  return { action: `created ${objectLabel} from ${sourceLabel}`, detail: sourceName }
+}
+
 /** How much of a note's body the timeline repeats before trailing off. */
 const NOTE_EXCERPT_LENGTH = 120
 

package/src/modules/agent-tasks/catalog.ts

@@ -305,6 +305,69 @@ Optionally save as a Note.`,
 Append a Note, propose Plan items, update summary/whyWin/risks only with clear evidence, extract Decisions.`,
   }),
 
+  // Enquiry
+  task({
+    id: 'enquiry.triage',
+    label: 'Triage enquiry',
+    description: 'Recommend pursue, nurture, or close.',
+    targetTypes: ['enquiry'],
+    placement: 'primary',
+    handbookSlugs: ['ideal-customer-profile', 'product', 'agent-faq'],
+    instructions: `Assess this Enquiry against Ideal customer profile and Product. Recommend one of:
+- pursue (convert to Deal)
+- nurture (keep in In progress, add a follow-up Plan item)
+- close (move to Closed, note the reason).
+Save the recommendation and rationale as a Note. Do not change the stage or convert without human confirmation.`,
+  }),
+  task({
+    id: 'enquiry.propose_plan',
+    label: 'Propose Plan',
+    description: 'Dated follow-up items.',
+    targetTypes: ['enquiry'],
+    placement: 'primary',
+    handbookSlugs: ['agent-faq'],
+    instructions: `Propose dated Plan items for this Enquiry (a first response, a follow-up, a review).
+Prefer concrete actions over vague reminders.`,
+  }),
+  task({
+    id: 'enquiry.refresh_summary',
+    label: 'Refresh enquiry summary',
+    description: 'Rewrite summary from evidence.',
+    targetTypes: ['enquiry'],
+    placement: 'primary',
+    handbookSlugs: ['agent-faq'],
+    instructions: `Rewrite the Enquiry summary from source, stage, notes, and linked Company.`,
+  }),
+  task({
+    id: 'enquiry.draft_reply',
+    label: 'Draft reply',
+    description: 'First-response email in Voice.',
+    targetTypes: ['enquiry'],
+    placement: 'primary',
+    handbookSlugs: ['voice-and-tone', 'product', 'agent-faq'],
+    instructions: `Draft a first response to this Enquiry in Voice. Reference the Product handbook only where the
+Enquiry's summary or notes signal a match. Save the draft as a Note. Do not send.`,
+  }),
+  task({
+    id: 'enquiry.capture_decision',
+    label: 'Capture decision',
+    description: 'Log what was decided about this enquiry.',
+    targetTypes: ['enquiry'],
+    placement: 'overflow',
+    handbookSlugs: ['agent-faq'],
+    instructions: `Create a Decision linked to this Enquiry from recent commitments or the human's instruction.`,
+  }),
+  task({
+    id: 'enquiry.log_transcript',
+    label: 'Log transcript',
+    description: 'Parse call notes into CRM updates.',
+    targetTypes: ['enquiry'],
+    placement: 'overflow',
+    handbookSlugs: ['agent-faq'],
+    instructions: `The human will paste a call or chat transcript after this prompt.
+Append a Note, propose Plan items, update the summary only with clear evidence, extract Decisions.`,
+  }),
+
   // Opportunity
   task({
     id: 'opportunity.propose_plan',