@kelpie/server 0.8.0 → 0.10.0

package/src/modules/consent-purposes/service.ts

@@ -0,0 +1,423 @@
+import { CONSENT_PURPOSE_STATUSES } from '@kelpie/schemas'
+import type { ConsentPurposeStatus } from '@kelpie/schemas'
+import { and, eq, sql } from 'drizzle-orm'
+
+import { toEventActor } from '../../lib/actor.ts'
+import { changedKeys } from '../../lib/changes.ts'
+import {
+  FOREIGN_KEY_VIOLATION,
+  UNIQUE_VIOLATION,
+  postgresErrorCode,
+} from '../../lib/database.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
+import { limitFor } from '../../runtime/entitlements.ts'
+import type { Transaction, TransactionScope } from '../../runtime/transaction.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { formFields } from '../forms/schema.ts'
+import { lists } from '../lists/schema.ts'
+import { roleAllows } from '../workspace/roles.ts'
+import { CONSENT_PURPOSES_LIMIT } from './capabilities.ts'
+import './events.ts'
+import * as repository from './repository.ts'
+import {
+  CONSENT_PURPOSE_SORTS,
+  DEFAULT_CONSENT_PURPOSE_SORT,
+} from './repository.ts'
+import type {
+  ConsentPurposeFilters,
+  ConsentPurposeRecord,
+} from './repository.ts'
+
+/**
+ * CRUD for the workspace's consent purposes.
+ *
+ * Reads are open to any workspace member — every capture site needs to list
+ * them to render its purpose picker. Writes need the admin role: a purpose
+ * change touches every form, list, and import job that names it, and it is
+ * team-wide config rather than a per-user preference.
+ */
+
+/** Hard cap per workspace. Bites when the entitlement leaves the count unlimited. */
+export const CONSENT_PURPOSES_HARD_CAP = 50
+
+const KEY_PATTERN = /^[a-z][a-z0-9_]*$/u
+const MAX_SLUG_LENGTH = 64
+const MAX_LABEL_LENGTH = 120
+const MIN_LABEL_LENGTH = 1
+const MAX_DESCRIPTION_LENGTH = 2000
+
+export interface ConsentPurposesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly entitlements: EntitlementRegistry
+}
+
+/** What the API returns: the stored row minus the tenancy column. */
+export type ConsentPurposeView = Omit<ConsentPurposeRecord, 'workspaceId'>
+
+export interface CreateConsentPurposeInput {
+  readonly slug: string
+  readonly label: string
+  readonly description: string
+  readonly defaultStatus: ConsentPurposeStatus
+}
+
+/** PATCH semantics: `slug` is immutable and refused by the route body. */
+export interface UpdateConsentPurposeInput {
+  readonly label?: string | undefined
+  readonly description?: string | undefined
+  readonly defaultStatus?: ConsentPurposeStatus | undefined
+  readonly sortOrder?: number | undefined
+}
+
+export interface ConsentPurposesService {
+  list(
+    actor: Actor,
+    filters: ConsentPurposeFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<ConsentPurposeView>>
+  get(actor: Actor, id: string): Promise<ConsentPurposeView>
+  create(actor: Actor, input: CreateConsentPurposeInput): Promise<ConsentPurposeView>
+  update(
+    actor: Actor,
+    id: string,
+    changes: UpdateConsentPurposeInput,
+  ): Promise<ConsentPurposeView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: ConsentPurposeRecord): ConsentPurposeView {
+  const { workspaceId: _workspaceId, ...view } = record
+  return view
+}
+
+function fieldError(field: string, message: string): AppError {
+  return AppError.validationFailed('That consent purpose is not valid', [{ field, message }])
+}
+
+function duplicateSlug(): AppError {
+  return AppError.conflict('Another consent purpose already uses that slug', [
+    { field: 'slug', message: 'Already in use' },
+  ])
+}
+
+function validateSlug(slug: string): void {
+  if (slug.length === 0 || slug.length > MAX_SLUG_LENGTH) {
+    throw fieldError('slug', `1 to ${String(MAX_SLUG_LENGTH)} characters`)
+  }
+  if (!KEY_PATTERN.test(slug)) {
+    throw fieldError(
+      'slug',
+      'Lowercase letters, digits and underscores; must start with a letter',
+    )
+  }
+}
+
+function validateLabel(label: string): void {
+  if (label.length < MIN_LABEL_LENGTH || label.length > MAX_LABEL_LENGTH) {
+    throw fieldError(
+      'label',
+      `${String(MIN_LABEL_LENGTH)} to ${String(MAX_LABEL_LENGTH)} characters`,
+    )
+  }
+}
+
+function validateDescription(description: string): void {
+  if (description.length > MAX_DESCRIPTION_LENGTH) {
+    throw fieldError('description', `At most ${String(MAX_DESCRIPTION_LENGTH)} characters`)
+  }
+}
+
+function validateDefaultStatus(status: string): void {
+  if (!CONSENT_PURPOSE_STATUSES.includes(status as ConsentPurposeStatus)) {
+    throw fieldError('default_status', `Unknown status "${status}"`)
+  }
+}
+
+/**
+ * A purpose still named by a form's consent field or a list's
+ * `consent_purpose_id` cannot be deleted. Counted here so the 409 lists both
+ * types; the FK on either side would refuse the delete on its own but only
+ * name one.
+ */
+async function referencingTypes(
+  db: Database | Transaction,
+  workspaceId: string,
+  id: string,
+): Promise<readonly string[]> {
+  const [fieldRow, listRow] = await Promise.all([
+    db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(formFields)
+      .where(
+        and(
+          eq(formFields.workspaceId, workspaceId),
+          // The array contains this purpose id. A form field carries a set of
+          // purposes; the delete is refused if any field still lists this one.
+          sql`${id} = ANY(${formFields.consentPurposeIds})`,
+        ),
+      ),
+    db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(lists)
+      .where(and(eq(lists.workspaceId, workspaceId), eq(lists.consentPurposeId, id))),
+  ])
+
+  const referencing: string[] = []
+  if (Number(fieldRow[0]?.count ?? 0) > 0) {
+    referencing.push('form_field')
+  }
+  if (Number(listRow[0]?.count ?? 0) > 0) {
+    referencing.push('list')
+  }
+  return referencing
+}
+
+export function createConsentPurposesService(
+  dependencies: ConsentPurposesDependencies,
+): ConsentPurposesService {
+  function requireAdminWorkspace(actor: Actor): string {
+    const workspaceId = requireWorkspaceId(actor)
+    if (actor.role === null || !roleAllows(actor.role, 'admin')) {
+      throw new AppError('forbidden', 'This action needs the admin role')
+    }
+    return workspaceId
+  }
+
+  async function require(
+    workspaceId: string,
+    id: string,
+  ): Promise<ConsentPurposeRecord> {
+    const purpose = await repository.findPurpose(dependencies.db, workspaceId, id)
+    if (purpose === undefined) {
+      throw AppError.notFound('Consent purpose not found')
+    }
+    return purpose
+  }
+
+  async function renumber(
+    tx: Transaction,
+    workspaceId: string,
+    order: readonly ConsentPurposeRecord[],
+  ): Promise<void> {
+    for (const [index, purpose] of order.entries()) {
+      if (purpose.sortOrder !== index) {
+        await repository.updatePurpose(tx, workspaceId, purpose.id, {
+          sortOrder: index,
+          updatedAt: dependencies.now(),
+        })
+      }
+    }
+  }
+
+  async function moveToPosition(
+    tx: Transaction,
+    workspaceId: string,
+    purpose: ConsentPurposeRecord,
+    position: number,
+  ): Promise<void> {
+    const rows = await repository.purposesForWorkspace(tx, workspaceId)
+    const target = rows.find((row) => row.id === purpose.id)
+    if (target === undefined) {
+      throw AppError.notFound('Consent purpose not found')
+    }
+    if (position < 0 || position >= rows.length) {
+      throw fieldError('sort_order', `Use 0 to ${String(rows.length - 1)}`)
+    }
+    const reordered = rows.filter((row) => row.id !== purpose.id)
+    reordered.splice(position, 0, target)
+    await renumber(tx, workspaceId, reordered)
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, CONSENT_PURPOSE_SORTS, DEFAULT_CONSENT_PURPOSE_SORT)
+      const rows = await repository.listPurposes(dependencies.db, workspaceId, filters, window)
+      return mapPage(toPage(rows, window, (row) => row.id), toView)
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireAdminWorkspace(actor)
+      validateSlug(input.slug)
+      validateLabel(input.label)
+      validateDescription(input.description)
+      validateDefaultStatus(input.defaultStatus)
+
+      const limit = await limitFor(
+        dependencies.entitlements,
+        workspaceId,
+        CONSENT_PURPOSES_LIMIT.name,
+      )
+      if (limit !== null) {
+        const total = await repository.countPurposes(dependencies.db, workspaceId)
+        if (total >= limit) {
+          throw new AppError(
+            'entitlement_required',
+            `Your plan allows ${String(limit)} consent purpose${limit === 1 ? '' : 's'}`,
+          )
+        }
+      }
+
+      const id = dependencies.createId('consentPurpose')
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          const existing = await repository.purposesForWorkspace(tx, workspaceId)
+          if (existing.length >= CONSENT_PURPOSES_HARD_CAP) {
+            throw AppError.conflict(
+              `A workspace may define at most ${String(CONSENT_PURPOSES_HARD_CAP)} consent purposes`,
+              [{ field: 'slug', message: 'Limit reached' }],
+            )
+          }
+
+          let created: ConsentPurposeRecord
+          try {
+            created = await repository.insertPurpose(tx, {
+              id,
+              workspaceId,
+              slug: input.slug,
+              label: input.label,
+              description: input.description,
+              defaultStatus: input.defaultStatus,
+              sortOrder: (existing.at(-1)?.sortOrder ?? -1) + 1,
+            })
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+              throw duplicateSlug()
+            }
+            throw error
+          }
+
+          events.emit(
+            'consent_purposes.purpose.created',
+            { type: 'consent_purpose', id: created.id },
+            { slug: created.slug },
+          )
+
+          return toView(created)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const existing = await require(workspaceId, id)
+
+      if (changes.label !== undefined) {
+        validateLabel(changes.label)
+      }
+      if (changes.description !== undefined) {
+        validateDescription(changes.description)
+      }
+      if (changes.defaultStatus !== undefined) {
+        validateDefaultStatus(changes.defaultStatus)
+      }
+
+      const columns: Partial<repository.ConsentPurposeColumns> = {
+        ...(changes.label === undefined ? {} : { label: changes.label }),
+        ...(changes.description === undefined ? {} : { description: changes.description }),
+        ...(changes.defaultStatus === undefined
+          ? {}
+          : { defaultStatus: changes.defaultStatus }),
+      }
+      const changed = changedKeys(existing, columns)
+      const position = changes.sortOrder
+
+      if (changed.length === 0 && position === undefined) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(
+        async ({ tx, events }) => {
+          if (position !== undefined) {
+            await moveToPosition(tx, workspaceId, existing, position)
+          }
+
+          let updated: ConsentPurposeRecord | undefined
+          if (changed.length > 0) {
+            updated = await repository.updatePurpose(tx, workspaceId, id, {
+              ...columns,
+              updatedAt: dependencies.now(),
+            })
+            if (updated === undefined) {
+              throw AppError.notFound('Consent purpose not found')
+            }
+          } else {
+            updated = await repository.findPurpose(tx, workspaceId, id)
+            if (updated === undefined) {
+              throw AppError.notFound('Consent purpose not found')
+            }
+          }
+
+          if (changed.length > 0 || position !== undefined) {
+            const changedPaths = [
+              ...changed,
+              ...(position !== undefined && position !== existing.sortOrder ? ['sortOrder'] : []),
+            ]
+            events.emit(
+              'consent_purposes.purpose.updated',
+              { type: 'consent_purpose', id },
+              { slug: updated.slug, changed: changedPaths },
+            )
+          }
+
+          return toView(updated)
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const existing = await require(workspaceId, id)
+
+      await dependencies.transaction(
+        async ({ tx, events }) => {
+          const referencing = await referencingTypes(tx, workspaceId, id)
+          if (referencing.length > 0) {
+            throw AppError.conflict(
+              'Remove this purpose from every form and list that names it before deleting it',
+              referencing.map((type) => ({ field: type, message: 'still references this purpose' })),
+            )
+          }
+
+          try {
+            await repository.deletePurpose(tx, workspaceId, id)
+          } catch (error: unknown) {
+            if (postgresErrorCode(error) === FOREIGN_KEY_VIOLATION) {
+              throw AppError.conflict(
+                'Remove this purpose from every form and list that names it before deleting it',
+                [{ field: 'id', message: 'still referenced' }],
+              )
+            }
+            throw error
+          }
+
+          const survivors = await repository.purposesForWorkspace(tx, workspaceId)
+          await renumber(tx, workspaceId, survivors)
+
+          events.emit(
+            'consent_purposes.purpose.deleted',
+            { type: 'consent_purpose', id },
+            { slug: existing.slug },
+          )
+        },
+        { workspaceId, actor: toEventActor(actor) },
+      )
+    },
+  }
+}

package/src/modules/consent-purposes/starters.ts

@@ -0,0 +1,32 @@
+import type { ConsentPurposeStatus } from '@kelpie/schemas'
+
+/**
+ * The purposes a new workspace starts with. Data, not migrations: a workspace
+ * owner may rename, reorder, or delete them, and add any others they need.
+ *
+ * Both starters default to `unknown` — silence about a person's wishes is not
+ * a grant, and every capture site (forms, lists, imports, manual override)
+ * writes an explicit `person_consents` row when consent is actually given.
+ */
+
+export interface StarterConsentPurpose {
+  readonly slug: string
+  readonly label: string
+  readonly description: string
+  readonly defaultStatus: ConsentPurposeStatus
+}
+
+export const STARTER_CONSENT_PURPOSES: readonly StarterConsentPurpose[] = [
+  {
+    slug: 'contact',
+    label: 'Contact',
+    description: 'Being contacted by the workspace about our work together.',
+    defaultStatus: 'unknown',
+  },
+  {
+    slug: 'marketing',
+    label: 'Marketing',
+    description: 'Marketing communications — newsletters, product updates, and campaigns.',
+    defaultStatus: 'unknown',
+  },
+]

package/src/modules/consent-purposes/tools.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, listWindowShape, registerCrudTools, termArg } from '../crudTools.ts'
+import {
+  createBody,
+  consentPurposeResponse,
+  toCreateInput,
+  toUpdateInput,
+  updateBody,
+} from './routes.ts'
+import type { ConsentPurposesService } from './service.ts'
+
+/**
+ * `consent_purposes_*`. Same schemas and mappers as `/v1/consent_purposes`, so
+ * the REST surface and the MCP one cannot drift. Agents list purposes before
+ * a person consent write so they know which slugs the workspace defines.
+ */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+})
+
+export function registerConsentPurposesTools(
+  mcp: McpToolRegistry,
+  service: ConsentPurposesService,
+): void {
+  registerCrudTools(mcp, {
+    resource: 'consent_purposes',
+    subject: 'consent purpose',
+    about:
+      'A workspace-defined consent purpose. Read these before writing a person ' +
+      'consent or setting a form/list/import purpose_id.',
+    service,
+    render: consentPurposeResponse,
+    listArgs,
+    toFilters: (args) => ({ term: args.q }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/core.ts

@@ -6,10 +6,13 @@ import { createAgentTasksModule } from './agent-tasks/index.ts'
 import { createApiKeysModule } from './api-keys/index.ts'
 import { createAuthModule } from './auth/index.ts'
 import { createCompaniesModule } from './companies/index.ts'
+import { createConsentPurposesModule } from './consent-purposes/index.ts'
+import { createCustomFieldsModule } from './custom-fields/index.ts'
 import { createDashboardModule } from './dashboard/index.ts'
 import { createDealsModule } from './deals/index.ts'
 import { createDecisionsModule } from './decisions/index.ts'
 import { createEmailDomainLinkerModule } from './email-domain-linker/index.ts'
+import { createEnquiriesModule } from './enquiries/index.ts'
 import { createFormsModule } from './forms/index.ts'
 import { createHandbookModule } from './handbook/index.ts'
 import { createHiringModule } from './hiring/index.ts'
@@ -47,6 +50,12 @@ export const coreModules: readonly KelpieModule[] = [
   createAuthModule(coreMigrationsDirectory),
   createWorkspaceModule(coreMigrationsDirectory),
   createApiKeysModule(coreMigrationsDirectory),
+  // Structural. Registers before People, Forms, Lists, and Import-Export so
+  // its table is defined when their fks and per-person consent join reach it.
+  createConsentPurposesModule(coreMigrationsDirectory),
+  // Structural. Registers before the six object modules so the validator
+  // factory it exports is present when they inject it into their services.
+  createCustomFieldsModule(coreMigrationsDirectory),
   createPeopleModule(coreMigrationsDirectory),
   createCompaniesModule(coreMigrationsDirectory),
   createPositionsModule(coreMigrationsDirectory),
@@ -54,6 +63,7 @@ export const coreModules: readonly KelpieModule[] = [
   createNotesModule(coreMigrationsDirectory),
   createPipelinesModule(coreMigrationsDirectory),
   createDealsModule(coreMigrationsDirectory),
+  createEnquiriesModule(coreMigrationsDirectory),
   createOpportunitiesModule(coreMigrationsDirectory),
   createPartnershipsModule(coreMigrationsDirectory),
   createRaisesModule(coreMigrationsDirectory),

package/src/modules/custom-fields/capabilities.ts

@@ -0,0 +1,17 @@
+import type { LimitCapability } from '../../runtime/entitlements.ts'
+
+/**
+ * How many custom-field definitions one workspace may have across every object
+ * type. Open source answers unlimited; the cloud can gate it later without a
+ * core change.
+ *
+ * The workspace-wide count is what an entitlement caps. A per-(workspace,
+ * object_type) ceiling is enforced separately in the service as a hard cap that
+ * protects the database from a runaway create loop.
+ */
+export const CUSTOM_FIELDS_LIMIT: LimitCapability = {
+  name: 'custom_fields.limit',
+  kind: 'limit',
+  description:
+    'How many custom-field definitions one workspace may have across every object type. Unlimited in open source.',
+}

package/src/modules/custom-fields/events.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events published by the custom-fields module.
+ *
+ * `target` is the definition. The value-side changes ride each object module's
+ * own `.updated` event, with per-key entries in `changed` shaped as
+ * `customFields.<key>`. The webhooks bridge does not translate any of these —
+ * `custom_fields.field` is not in `RECORD_OBJECT_TYPES`, and there is no
+ * `record.*` wire event for a definition CRUD, so the four-event wire catalog
+ * stays unchanged.
+ */
+
+export const customFieldsEvents = {
+  'custom_fields.field.created': z.object({ objectType: z.string(), key: z.string() }),
+  'custom_fields.field.updated': z.object({
+    objectType: z.string(),
+    key: z.string(),
+    changed: z.array(z.string()).readonly(),
+  }),
+  'custom_fields.field.deleted': z.object({
+    objectType: z.string(),
+    key: z.string(),
+    strippedRecordCount: z.number().int(),
+  }),
+} satisfies ModuleEventCatalog
+
+export interface CustomFieldCreatedData {
+  readonly objectType: string
+  readonly key: string
+}
+export interface CustomFieldUpdatedData {
+  readonly objectType: string
+  readonly key: string
+  readonly changed: readonly string[]
+}
+export interface CustomFieldDeletedData {
+  readonly objectType: string
+  readonly key: string
+  readonly strippedRecordCount: number
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'custom_fields.field.created': CustomFieldCreatedData
+    'custom_fields.field.updated': CustomFieldUpdatedData
+    'custom_fields.field.deleted': CustomFieldDeletedData
+  }
+}

package/src/modules/custom-fields/index.ts

@@ -0,0 +1,61 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { CUSTOM_FIELDS_LIMIT } from './capabilities.ts'
+import { customFieldsEvents } from './events.ts'
+import { mountCustomFieldsRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createCustomFieldDefinitionsService } from './service.ts'
+import { registerCustomFieldsTools } from './tools.ts'
+
+/**
+ * Custom fields: workspace-defined attributes for the six taggable record
+ * types. Structural because records carry values keyed by definition key, so a
+ * disabled module would leave the values on records with no way to read them.
+ *
+ * Requires the six object modules only for schema visibility: the strip-on-
+ * delete pass reads their tables through `stripKeyFromRecords`, and drizzle-kit
+ * needs the barrel to see them registered before this module's schema loads.
+ * Runtime dependency runs the other way — the six modules `requires` this one
+ * so the validator is present when they register.
+ *
+ * Exports the values factory so the six object modules can inject it into
+ * their services (`createCustomFieldValues` is the cross-module seam here).
+ */
+export {
+  createCustomFieldValues,
+} from './values.ts'
+export type {
+  CustomFieldValuesValidator,
+  CustomFieldsMerge,
+  StoredCustomFieldValue,
+} from './values.ts'
+
+export function createCustomFieldsModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'custom-fields',
+    requires: ['workspace'],
+    structural: true,
+    events: customFieldsEvents,
+
+    register(context) {
+      context.entitlements.declare(CUSTOM_FIELDS_LIMIT)
+
+      const service = createCustomFieldDefinitionsService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        entitlements: context.entitlements,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountCustomFieldsRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerCustomFieldsTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}