@kelpie/server 0.8.0 → 0.9.0

package/src/modules/companies/service.ts

@@ -1,3 +1,5 @@
+import type { CustomFieldWireValue } from '@kelpie/schemas'
+
 import { changedKeys } from '../../lib/changes.ts'
 import { UNIQUE_VIOLATION, isReferenceViolation, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
@@ -16,6 +18,7 @@ import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
 import { referencedElsewhere } from '../references.ts'
 import * as repository from './repository.ts'
 import { COMPANY_SORTS, DEFAULT_COMPANY_SORT } from './repository.ts'
@@ -35,6 +38,7 @@ export interface CompaniesDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly recordActivity: ActivityRecorder
+  readonly customFields: CustomFieldValuesValidator
 }
 
 /** What a changed column is called on a timeline. `icpFit` is why these are written out. */
@@ -73,6 +77,8 @@ export interface CreateCompanyInput {
   readonly summary: string
   readonly tags: readonly string[]
   readonly isOwn: boolean
+  /** Wire shape merge patch (undefined for a create without any). */
+  readonly customFields: Readonly<Record<string, CustomFieldWireValue | null>> | undefined
 }
 
 /** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
@@ -156,6 +162,12 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
       const id = dependencies.createId('company')
 
       return dependencies.transaction(async ({ tx, events }) => {
+        const customFields = await dependencies.customFields.forCreate(
+          tx,
+          workspaceId,
+          'company',
+          input.customFields,
+        )
         let created: CompanyRecord
 
         try {
@@ -176,6 +188,7 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
             summary: input.summary,
             tags: [...input.tags],
             isOwn: input.isOwn,
+            customFields,
           })
         } catch (error: unknown) {
           if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
@@ -211,18 +224,28 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
       const workspaceId = requireWorkspaceId(actor)
       const existing = await require(workspaceId, id)
       const columns = toStoredColumns(changes)
-      const changed = changedKeys(existing, columns)
-
-      if (changed.length === 0) {
-        return toView(existing)
-      }
+      const scalarChanged = changedKeys(existing, columns)
 
       return dependencies.transaction(async ({ tx, events }) => {
+        const cf = await dependencies.customFields.forUpdate(
+          tx,
+          workspaceId,
+          'company',
+          existing.customFields,
+          changes.customFields,
+        )
+        const customFieldsChanged = cf !== undefined && cf.changedPaths.length > 0
+
+        if (scalarChanged.length === 0 && !customFieldsChanged) {
+          return toView(existing)
+        }
+
         let updated: CompanyRecord | undefined
 
         try {
           updated = await repository.updateCompany(tx, workspaceId, id, {
             ...columns,
+            ...(customFieldsChanged ? { customFields: cf.merged } : {}),
             updatedAt: dependencies.now(),
           })
         } catch (error: unknown) {
@@ -237,19 +260,31 @@ export function createCompaniesService(dependencies: CompaniesDependencies): Com
           throw AppError.notFound('Company not found')
         }
 
-        await dependencies.recordActivity(tx, workspaceId, actor, {
-          targetType: 'company',
-          targetId: id,
-          kind: 'updated',
-          ...describeUpdate(changed, COMPANY_FIELD_LABELS, existing, columns),
-        })
+        const customFieldPaths = cf?.changedPaths ?? []
+        const activityChanged = [...scalarChanged, ...customFieldPaths]
+
+        if (activityChanged.length > 0) {
+          const labels: Record<string, string> = { ...COMPANY_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: 'company',
+            targetId: id,
+            kind: 'updated',
+            ...describeUpdate(activityChanged, labels, before, after),
+          })
+        }
 
-        events.emit('companies.company.updated', { type: 'company', id }, { changed })
+        events.emit(
+          'companies.company.updated',
+          { type: 'company', id },
+          { changed: [...scalarChanged, ...customFieldPaths] },
+        )
 
         // Sync sweep when the domain moved. A newly-set domain gains matches;
         // a changed domain gains new matches without touching the old links
         // (never-remove — a person may still work at the previous domain).
-        if (changed.includes('domain')) {
+        if (scalarChanged.includes('domain')) {
           await autoLinkCompanyByDomain(tx, events, workspaceId, updated, {
             createId: dependencies.createId,
             now: dependencies.now,

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

@@ -0,0 +1,12 @@
+import type { LimitCapability } from '../../runtime/entitlements.ts'
+
+/**
+ * How many consent purposes one workspace may define. Open source answers
+ * unlimited; the cloud can gate it later without a core change.
+ */
+export const CONSENT_PURPOSES_LIMIT: LimitCapability = {
+  name: 'consent_purposes.limit',
+  kind: 'limit',
+  description:
+    'How many consent purposes one workspace may define. Unlimited in open source.',
+}

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

@@ -0,0 +1,38 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/**
+ * Domain events for the consent-purposes catalog.
+ *
+ * `target` is the purpose definition. Per-person consent writes ride each
+ * person's own `.updated` event, with per-purpose entries in `changed` shaped
+ * as `consents.<slug>`.
+ */
+export const consentPurposesEvents = {
+  'consent_purposes.purpose.created': z.object({ slug: z.string() }),
+  'consent_purposes.purpose.updated': z.object({
+    slug: z.string(),
+    changed: z.array(z.string()).readonly(),
+  }),
+  'consent_purposes.purpose.deleted': z.object({ slug: z.string() }),
+} satisfies ModuleEventCatalog
+
+export interface ConsentPurposeCreatedData {
+  readonly slug: string
+}
+export interface ConsentPurposeUpdatedData {
+  readonly slug: string
+  readonly changed: readonly string[]
+}
+export interface ConsentPurposeDeletedData {
+  readonly slug: string
+}
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'consent_purposes.purpose.created': ConsentPurposeCreatedData
+    'consent_purposes.purpose.updated': ConsentPurposeUpdatedData
+    'consent_purposes.purpose.deleted': ConsentPurposeDeletedData
+  }
+}

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

@@ -0,0 +1,48 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { CONSENT_PURPOSES_LIMIT } from './capabilities.ts'
+import { consentPurposesEvents } from './events.ts'
+import { mountConsentPurposesRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createConsentPurposesService } from './service.ts'
+import { registerConsentPurposesTools } from './tools.ts'
+
+/**
+ * Consent purposes: the workspace catalog every capture site names.
+ *
+ * Structural because Person consent rows carry `purpose_id`, and forms /
+ * lists / imports each reference one; a disabled module would leave those
+ * references without a definition to resolve.
+ *
+ * Registers before people, forms, lists, and import-export so their `_fk`
+ * targets are in the schema barrel when their own migrations reference them.
+ */
+export function createConsentPurposesModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'consent-purposes',
+    requires: ['workspace'],
+    structural: true,
+    events: consentPurposesEvents,
+
+    register(context) {
+      context.entitlements.declare(CONSENT_PURPOSES_LIMIT)
+
+      const service = createConsentPurposesService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        entitlements: context.entitlements,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountConsentPurposesRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerConsentPurposesTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}

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

@@ -0,0 +1,163 @@
+import { and, asc, eq, ilike, inArray, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { consentPurposes } from './schema.ts'
+
+export type ConsentPurposeRecord = typeof consentPurposes.$inferSelect
+export type ConsentPurposeColumns = typeof consentPurposes.$inferInsert
+
+export const CONSENT_PURPOSE_SORTS: SortableFields<ConsentPurposeRecord> = {
+  sort_order: {
+    column: consentPurposes.sortOrder,
+    valueOf: (row) => String(row.sortOrder),
+    parse: (value) => {
+      const parsed = Number(value)
+      if (!Number.isInteger(parsed)) {
+        throw new Error('sort_order cursor is not a whole number')
+      }
+      return parsed
+    },
+  },
+  label: textSort(consentPurposes.label, (row) => row.label),
+  slug: textSort(consentPurposes.slug, (row) => row.slug),
+  created_at: timestampSort(consentPurposes.createdAt, (row) => row.createdAt),
+  updated_at: timestampSort(consentPurposes.updatedAt, (row) => row.updatedAt),
+}
+
+export const DEFAULT_CONSENT_PURPOSE_SORT = 'sort_order'
+
+export interface ConsentPurposeFilters {
+  readonly term?: string | undefined
+}
+
+function conditionsFor(workspaceId: string, filters: ConsentPurposeFilters): (SQL | undefined)[] {
+  return [
+    eq(consentPurposes.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : ilike(consentPurposes.label, containsPattern(filters.term)),
+  ]
+}
+
+export function listPurposes(
+  db: Queryable,
+  workspaceId: string,
+  filters: ConsentPurposeFilters,
+  window: ListWindow<ConsentPurposeRecord>,
+): Promise<ConsentPurposeRecord[]> {
+  return db
+    .select()
+    .from(consentPurposes)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, consentPurposes.id)))
+    .orderBy(...orderByWindow(window, consentPurposes.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findPurpose(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<ConsentPurposeRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(consentPurposes)
+    .where(and(eq(consentPurposes.workspaceId, workspaceId), eq(consentPurposes.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function findPurposeBySlug(
+  db: Queryable,
+  workspaceId: string,
+  slug: string,
+): Promise<ConsentPurposeRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(consentPurposes)
+    .where(and(eq(consentPurposes.workspaceId, workspaceId), eq(consentPurposes.slug, slug)))
+    .limit(1)
+
+  return found
+}
+
+export function purposesForWorkspace(
+  db: Queryable,
+  workspaceId: string,
+): Promise<ConsentPurposeRecord[]> {
+  return db
+    .select()
+    .from(consentPurposes)
+    .where(eq(consentPurposes.workspaceId, workspaceId))
+    .orderBy(asc(consentPurposes.sortOrder), asc(consentPurposes.id))
+}
+
+/** The purposes with any of these ids, in this workspace. Used by cross-module checks. */
+export function listPurposesByIds(
+  db: Queryable,
+  workspaceId: string,
+  ids: readonly string[],
+): Promise<ConsentPurposeRecord[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db
+    .select()
+    .from(consentPurposes)
+    .where(
+      and(
+        eq(consentPurposes.workspaceId, workspaceId),
+        inArray(consentPurposes.id, [...ids]),
+      ),
+    )
+}
+
+export async function countPurposes(db: Queryable, workspaceId: string): Promise<number> {
+  const [row] = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(consentPurposes)
+    .where(eq(consentPurposes.workspaceId, workspaceId))
+
+  return Number(row?.count ?? 0)
+}
+
+export async function insertPurpose(
+  db: Queryable,
+  values: ConsentPurposeColumns,
+): Promise<ConsentPurposeRecord> {
+  const [created] = await db.insert(consentPurposes).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting consent_purpose ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updatePurpose(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<ConsentPurposeColumns>,
+): Promise<ConsentPurposeRecord | undefined> {
+  const [updated] = await db
+    .update(consentPurposes)
+    .set(changes)
+    .where(and(eq(consentPurposes.workspaceId, workspaceId), eq(consentPurposes.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deletePurpose(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(consentPurposes)
+    .where(and(eq(consentPurposes.workspaceId, workspaceId), eq(consentPurposes.id, id)))
+    .returning({ id: consentPurposes.id })
+
+  return deleted.length
+}

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

@@ -0,0 +1,122 @@
+import { CONSENT_PURPOSE_STATUSES } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { pageBody, readJsonBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type {
+  ConsentPurposeView,
+  ConsentPurposesService,
+  CreateConsentPurposeInput,
+  UpdateConsentPurposeInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/consent_purposes`.
+ *
+ * `slug` is only on the create body: the update body omits it and the strict
+ * PATCH answers `422` if it is sent. The description defaults to empty so a
+ * write that only sets label + slug is accepted.
+ */
+
+export const createBody = z.strictObject({
+  slug: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+  description: z.string().max(2000).default(''),
+  default_status: z.enum(CONSENT_PURPOSE_STATUSES).default('unknown'),
+})
+
+export const updateBody = z
+  .strictObject({
+    label: z.string().min(1).max(120),
+    description: z.string().max(2000),
+    default_status: z.enum(CONSENT_PURPOSE_STATUSES),
+    sort_order: z.number().int().min(0),
+  })
+  .partial()
+
+export interface ConsentPurposesRoutesDependencies extends CredentialDependencies {
+  readonly service: ConsentPurposesService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateConsentPurposeInput {
+  return {
+    slug: body.slug,
+    label: body.label,
+    description: body.description,
+    defaultStatus: body.default_status,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateConsentPurposeInput {
+  return {
+    ...(body.label === undefined ? {} : { label: body.label }),
+    ...(body.description === undefined ? {} : { description: body.description }),
+    ...(body.default_status === undefined ? {} : { defaultStatus: body.default_status }),
+    ...(body.sort_order === undefined ? {} : { sortOrder: body.sort_order }),
+  }
+}
+
+export function consentPurposeResponse(purpose: ConsentPurposeView): Record<string, unknown> {
+  return {
+    id: purpose.id,
+    slug: purpose.slug,
+    label: purpose.label,
+    description: purpose.description,
+    default_status: purpose.defaultStatus,
+    sort_order: purpose.sortOrder,
+    created_at: purpose.createdAt.toISOString(),
+    updated_at: purpose.updatedAt.toISOString(),
+  }
+}
+
+export function mountConsentPurposesRoutes(
+  router: Hono,
+  dependencies: ConsentPurposesRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> =>
+    resolveActorFrom(dependencies, context)
+
+  router.get('/consent_purposes', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      { term: context.req.query('q') },
+      readListParameters(context),
+    )
+    return context.json(pageBody(page, consentPurposeResponse))
+  })
+
+  router.post('/consent_purposes', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const purpose = await dependencies.service.create(
+      await requireActor(context),
+      toCreateInput(body),
+    )
+    return context.json(consentPurposeResponse(purpose), 201)
+  })
+
+  router.get('/consent_purposes/:id', async (context) => {
+    const purpose = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+    return context.json(consentPurposeResponse(purpose))
+  })
+
+  router.patch('/consent_purposes/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const purpose = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+    return context.json(consentPurposeResponse(purpose))
+  })
+
+  router.delete('/consent_purposes/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+    return context.body(null, 204)
+  })
+}

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

@@ -0,0 +1,46 @@
+import { CONSENT_PURPOSE_STATUSES } from '@kelpie/schemas'
+import { index, integer, pgTable, text, unique } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, primaryId, updatedAt } from '../../lib/columns.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * Workspace-defined consent purposes.
+ *
+ * Every capture site — a form's consent field, a list, an import job, the
+ * manual override on a Person — names one of these. `slug` is set at create
+ * and immutable after: a rename would strand every form/list/import that
+ * names it and every `person_consents` row that carries it (identified by
+ * the purpose id). The strict PATCH body naturally refuses either as a `422`.
+ *
+ * `default_status` is the workspace default: a person without an explicit
+ * `person_consents` row for this purpose inherits it.
+ */
+export { CONSENT_PURPOSE_STATUSES } from '@kelpie/schemas'
+export type { ConsentPurposeStatus } from '@kelpie/schemas'
+
+export const consentPurposes = pgTable(
+  'consent_purposes',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    slug: text('slug').notNull(),
+    label: text('label').notNull(),
+    description: text('description').notNull().default(''),
+    defaultStatus: text('default_status').notNull().default('unknown'),
+    sortOrder: integer('sort_order').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('consent_purposes_workspace_idx').on(table.workspaceId),
+    unique('consent_purposes_workspace_slug_key').on(table.workspaceId, table.slug),
+    checkOneOf(
+      'consent_purposes_default_status_check',
+      table.defaultStatus,
+      CONSENT_PURPOSE_STATUSES,
+    ),
+  ],
+)