@kelpie/server 0.7.0 → 0.8.0

package/migrations/meta/_journal.json

@@ -148,6 +148,27 @@
       "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
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.7.0",
+  "version": "0.8.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.8.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

@@ -28,6 +28,8 @@ export const idPrefixes = {
   decision: 'dec',
   note: 'note',
   activity: 'act',
+  list: 'list',
+  listMember: 'lmem',
   handbookPage: 'hb',
   form: 'form',
   formField: 'ff',

package/src/modules/attachedRecords.ts

@@ -6,6 +6,7 @@ import type { Queryable } from '../runtime/transaction.ts'
 import * as activityRepository from './activities/repository.ts'
 import * as decisionRepository from './decisions/repository.ts'
 import { candidates } from './hiring/schema.ts'
+import * as listRepository from './lists/repository.ts'
 import * as noteRepository from './notes/repository.ts'
 import * as planRepository from './plans/repository.ts'
 
@@ -37,7 +38,7 @@ export async function deleteRecordsAttachedTo(
   targetType: AttachableTargetType,
   targetId: string,
 ): Promise<number> {
-  // Sequential, not concurrent: a transaction is one connection, and four
+  // Sequential, not concurrent: a transaction is one connection, and five
   // statements racing down it is not something to rely on for a cheap delete.
   const notes = await noteRepository.deleteForTarget(db, workspaceId, targetType, targetId)
   const activities = await activityRepository.deleteForTarget(db, workspaceId, targetType, targetId)
@@ -45,8 +46,14 @@ export async function deleteRecordsAttachedTo(
   const plans = PLAN_TARGET_TYPES.has(targetType)
     ? await planRepository.deleteForTarget(db, workspaceId, targetType, targetId)
     : 0
+  const memberships = await listRepository.deleteMembershipsForTarget(
+    db,
+    workspaceId,
+    targetType,
+    targetId,
+  )
 
-  return notes + activities + decisions + plans
+  return notes + activities + decisions + plans + memberships
 }
 
 /**

package/src/modules/auth/preferences.ts

@@ -1,4 +1,4 @@
-import type { ThemePreference } from '@kelpie/schemas'
+import type { ListViewPreference, ThemePreference } from '@kelpie/schemas'
 
 /**
  * What an account's preferences are before anyone has saved any, and how a
@@ -17,12 +17,17 @@ export interface PreferenceValues {
   readonly emailDigest: boolean
   readonly mentionEmails: boolean
   readonly productUpdates: boolean
+  readonly listViews: Readonly<Record<string, ListViewPreference>>
 }
 
 /**
  * UTC, not the workspace's zone. An account is global and may belong to several
  * workspaces in different zones, so deriving from one of them would be picking
  * arbitrarily and calling it the person's answer.
+ *
+ * `listViews` starts empty. Each list page falls back to its own default when
+ * the map holds no entry for it, so the person sees the page's built-in shape
+ * until they change it.
  */
 export const DEFAULT_PREFERENCES: PreferenceValues = {
   timezone: 'UTC',
@@ -30,6 +35,7 @@ export const DEFAULT_PREFERENCES: PreferenceValues = {
   emailDigest: true,
   mentionEmails: true,
   productUpdates: false,
+  listViews: {},
 }
 
 export type PreferenceChanges = Partial<PreferenceValues>
@@ -40,6 +46,11 @@ export type PreferenceChanges = Partial<PreferenceValues>
  * The result is always a complete row, which is what makes the write an upsert
  * with no read-modify-write hazard in the caller: the same request applied twice
  * produces the same row.
+ *
+ * `listViews` is treated as one field, so the caller replaces the whole map
+ * rather than merging by key. The UI already holds the current map in the
+ * account-preferences query, so a per-view change becomes a PATCH of the merged
+ * map — the merge lives where the choice was made.
  */
 export function applyPreferenceChanges(
   stored: PreferenceValues | undefined,
@@ -53,5 +64,6 @@ export function applyPreferenceChanges(
     emailDigest: changes.emailDigest ?? current.emailDigest,
     mentionEmails: changes.mentionEmails ?? current.mentionEmails,
     productUpdates: changes.productUpdates ?? current.productUpdates,
+    listViews: changes.listViews ?? current.listViews,
   }
 }

package/src/modules/auth/routes.ts

@@ -1,4 +1,5 @@
 import { THEME_PREFERENCES } from '@kelpie/schemas'
+import type { ListViewPreference } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -59,6 +60,24 @@ const updateAccountBody = z
     path: ['current_password'],
   })
 
+const listViewBody: z.ZodType<ListViewPreference, unknown> = z
+  .strictObject({
+    columns: z.array(z.string()).optional(),
+    mode: z.enum(['list', 'columns']).optional(),
+    grouping: z.string().optional(),
+    scope: z.string().optional(),
+    sort: z.string().optional(),
+  })
+  .transform(
+    (wire): ListViewPreference => ({
+      ...(wire.columns === undefined ? {} : { columns: wire.columns }),
+      ...(wire.mode === undefined ? {} : { mode: wire.mode }),
+      ...(wire.grouping === undefined ? {} : { grouping: wire.grouping }),
+      ...(wire.scope === undefined ? {} : { scope: wire.scope }),
+      ...(wire.sort === undefined ? {} : { sort: wire.sort }),
+    }),
+  )
+
 const updatePreferencesBody = z
   .strictObject({
     timezone: timezoneSchema,
@@ -66,6 +85,7 @@ const updatePreferencesBody = z
     email_digest: z.boolean(),
     mention_emails: z.boolean(),
     product_updates: z.boolean(),
+    list_views: z.record(z.string(), listViewBody),
   })
   .partial()
 
@@ -118,6 +138,7 @@ function preferencesResponse(preferences: PreferenceValues): Record<string, unkn
     email_digest: preferences.emailDigest,
     mention_emails: preferences.mentionEmails,
     product_updates: preferences.productUpdates,
+    list_views: preferences.listViews,
   }
 }
 
@@ -213,6 +234,7 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
       ...(body.email_digest === undefined ? {} : { emailDigest: body.email_digest }),
       ...(body.mention_emails === undefined ? {} : { mentionEmails: body.mention_emails }),
       ...(body.product_updates === undefined ? {} : { productUpdates: body.product_updates }),
+      ...(body.list_views === undefined ? {} : { listViews: body.list_views }),
     })
 
     return context.json(preferencesResponse(preferences))

package/src/modules/auth/schema.ts

@@ -1,6 +1,6 @@
 import { THEME_PREFERENCES } from '@kelpie/schemas'
-import type { ThemePreference } from '@kelpie/schemas'
-import { boolean, pgTable, text } from 'drizzle-orm/pg-core'
+import type { ListViewPreference, ThemePreference } from '@kelpie/schemas'
+import { boolean, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
 
 import { checkOneOf, citext, createdAt, moment, primaryId, updatedAt } from '../../lib/columns.ts'
 
@@ -57,6 +57,16 @@ export const userPreferences = pgTable(
     emailDigest: boolean('email_digest').notNull(),
     mentionEmails: boolean('mention_emails').notNull(),
     productUpdates: boolean('product_updates').notNull(),
+    /**
+     * Per-list column choices, keyed on a stable view id (`people`, `deals`, …).
+     * A view id the client no longer recognises stays untouched here rather than
+     * being cleaned up: the map is small, and the write path is the client
+     * merging its current choice into what it read.
+     */
+    listViews: jsonb('list_views')
+      .$type<Readonly<Record<string, ListViewPreference>>>()
+      .notNull()
+      .default({}),
     updatedAt: updatedAt(),
   },
   (table) => [checkOneOf('user_preferences_theme_check', table.theme, THEME_PREFERENCES)],

package/src/modules/auth/service.ts

@@ -1,5 +1,6 @@
 import { APP_LINK_PATHS, buildAppLink } from '../../lib/appUrl.ts'
 import type { EmailSender } from '../../lib/email.ts'
+import { renderEmail } from '../../lib/emailContent.ts'
 import { AppError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import { UNIQUE_VIOLATION, postgresErrorCode } from '../../lib/database.ts'
@@ -95,6 +96,7 @@ function toPreferenceValues(record: repository.UserPreferencesRecord): Preferenc
     emailDigest: record.emailDigest,
     mentionEmails: record.mentionEmails,
     productUpdates: record.productUpdates,
+    listViews: record.listViews,
   }
 }
 
@@ -192,11 +194,23 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
 
   function sendVerificationEmail(to: string, token: string): Promise<void> {
     const link = buildAppLink(dependencies.appBaseUrl, APP_LINK_PATHS.verifyEmail, token)
+    const { text, html } = renderEmail(
+      {
+        action: {
+          instructions: 'Confirm this address to finish setting up your account:',
+          buttonText: 'Verify email address',
+          link,
+        },
+        outro: 'The link expires in 24 hours.',
+      },
+      dependencies.appBaseUrl,
+    )
 
     return dependencies.email.send({
       to,
       subject: 'Verify your Kelpie email address',
-      body: `Confirm this address to finish setting up your account:\n\n${link}\n\nThe link expires in 24 hours.`,
+      body: text,
+      html,
     })
   }
 
@@ -320,10 +334,18 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
         })
 
         if (changes.email !== undefined) {
+          const { text, html } = renderEmail(
+            {
+              intro: `Your Kelpie sign-in email changed from ${previousEmail} to ${updated.email}. If you did not make this change, reset your password right away.`,
+            },
+            dependencies.appBaseUrl,
+          )
+
           await dependencies.email.send({
             to: previousEmail,
             subject: 'Your Kelpie sign-in email changed',
-            body: `Your Kelpie sign-in email changed from ${previousEmail} to ${updated.email}. If you did not make this change, reset your password right away.`,
+            body: text,
+            html,
           })
         }
 
@@ -418,11 +440,23 @@ export function createAuthService(dependencies: AuthDependencies): AuthService {
       })
 
       const link = buildAppLink(dependencies.appBaseUrl, APP_LINK_PATHS.passwordReset, token)
+      const { text, html } = renderEmail(
+        {
+          action: {
+            instructions: 'Use this link within the hour to choose a new password:',
+            buttonText: 'Reset password',
+            link,
+          },
+          outro: 'If you did not ask for this, ignore it.',
+        },
+        dependencies.appBaseUrl,
+      )
 
       await dependencies.email.send({
         to: user.email,
         subject: 'Reset your Kelpie password',
-        body: `Use this link within the hour to choose a new password:\n\n${link}\n\nIf you did not ask for this, ignore it.`,
+        body: text,
+        html,
       })
     },
 

package/src/modules/companies/repository.ts

@@ -27,6 +27,8 @@ export interface CompanyFilters {
   readonly term?: string | undefined
   /** `?person_id=`, repeatable: companies where any of these people holds a position. */
   readonly personIds?: readonly string[] | undefined
+  /** `?is_own=true` returns only the workspace's own companies; `false` returns everything else. */
+  readonly isOwn?: boolean | undefined
 }
 
 /**
@@ -64,6 +66,7 @@ function conditionsFor(workspaceId: string, filters: CompanyFilters): (SQL | und
     eq(companies.workspaceId, workspaceId),
     filters.term === undefined ? undefined : matchesTerm(filters.term),
     filters.personIds === undefined ? undefined : employsAnyOf(filters.personIds),
+    filters.isOwn === undefined ? undefined : eq(companies.isOwn, filters.isOwn),
   ]
 }