@kelpie/server 0.7.0 → 0.9.0

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

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

@@ -0,0 +1,225 @@
+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 { 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'
+import { raises } from '../raises/schema.ts'
+import type { CustomFieldObjectType } from './schema.ts'
+import { customFieldDefinitions } from './schema.ts'
+
+export type CustomFieldDefinitionRecord = typeof customFieldDefinitions.$inferSelect
+export type CustomFieldDefinitionColumns = typeof customFieldDefinitions.$inferInsert
+
+export const CUSTOM_FIELD_DEFINITION_SORTS: SortableFields<CustomFieldDefinitionRecord> = {
+  sort_order: {
+    column: customFieldDefinitions.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(customFieldDefinitions.label, (row) => row.label),
+  key: textSort(customFieldDefinitions.key, (row) => row.key),
+  created_at: timestampSort(customFieldDefinitions.createdAt, (row) => row.createdAt),
+  updated_at: timestampSort(customFieldDefinitions.updatedAt, (row) => row.updatedAt),
+}
+
+export const DEFAULT_CUSTOM_FIELD_DEFINITION_SORT = 'sort_order'
+
+export interface CustomFieldDefinitionFilters {
+  readonly term?: string | undefined
+  readonly objectType?: CustomFieldObjectType | undefined
+}
+
+function conditionsFor(
+  workspaceId: string,
+  filters: CustomFieldDefinitionFilters,
+): (SQL | undefined)[] {
+  return [
+    eq(customFieldDefinitions.workspaceId, workspaceId),
+    filters.term === undefined
+      ? undefined
+      : ilike(customFieldDefinitions.label, containsPattern(filters.term)),
+    filters.objectType === undefined
+      ? undefined
+      : eq(customFieldDefinitions.objectType, filters.objectType),
+  ]
+}
+
+export function listDefinitions(
+  db: Queryable,
+  workspaceId: string,
+  filters: CustomFieldDefinitionFilters,
+  window: ListWindow<CustomFieldDefinitionRecord>,
+): Promise<CustomFieldDefinitionRecord[]> {
+  return db
+    .select()
+    .from(customFieldDefinitions)
+    .where(
+      and(...conditionsFor(workspaceId, filters), keysetCondition(window, customFieldDefinitions.id)),
+    )
+    .orderBy(...orderByWindow(window, customFieldDefinitions.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findDefinition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<CustomFieldDefinitionRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(customFieldDefinitions)
+    .where(and(eq(customFieldDefinitions.workspaceId, workspaceId), eq(customFieldDefinitions.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * Every definition for one workspace, ordered as the editor renders them.
+ *
+ * Not paged: a workspace's whole set is small (hard cap 100 per object type),
+ * and every write path — validation, delete-strip — needs the definitions for
+ * one object type at once.
+ */
+export function definitionsForObject(
+  db: Queryable,
+  workspaceId: string,
+  objectType: CustomFieldObjectType,
+): Promise<CustomFieldDefinitionRecord[]> {
+  return db
+    .select()
+    .from(customFieldDefinitions)
+    .where(
+      and(
+        eq(customFieldDefinitions.workspaceId, workspaceId),
+        eq(customFieldDefinitions.objectType, objectType),
+      ),
+    )
+    .orderBy(asc(customFieldDefinitions.sortOrder), asc(customFieldDefinitions.id))
+}
+
+export async function countDefinitions(
+  db: Queryable,
+  workspaceId: string,
+): Promise<number> {
+  const [row] = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(customFieldDefinitions)
+    .where(eq(customFieldDefinitions.workspaceId, workspaceId))
+
+  return Number(row?.count ?? 0)
+}
+
+export async function insertDefinition(
+  db: Queryable,
+  values: CustomFieldDefinitionColumns,
+): Promise<CustomFieldDefinitionRecord> {
+  const [created] = await db.insert(customFieldDefinitions).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting custom_field_definition ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateDefinition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<CustomFieldDefinitionColumns>,
+): Promise<CustomFieldDefinitionRecord | undefined> {
+  const [updated] = await db
+    .update(customFieldDefinitions)
+    .set(changes)
+    .where(and(eq(customFieldDefinitions.workspaceId, workspaceId), eq(customFieldDefinitions.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteDefinition(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(customFieldDefinitions)
+    .where(and(eq(customFieldDefinitions.workspaceId, workspaceId), eq(customFieldDefinitions.id, id)))
+    .returning({ id: customFieldDefinitions.id })
+
+  return deleted.length
+}
+
+/**
+ * The tables `custom_fields` lives on, keyed by object type. A one-directional
+ * import: this module knows every carrier so that a definition delete can strip
+ * its key from the right table without every object module having to opt in.
+ */
+const TABLES = {
+  person: people,
+  company: companies,
+  deal: deals,
+  opportunity: opportunities,
+  partnership: partnerships,
+  raise: raises,
+  enquiry: enquiries,
+} as const
+
+/**
+ * Removes one key from every record of one object type in one workspace.
+ *
+ * Uses `?` to skip rows that never carried the key, so the write set is only
+ * the rows that actually held a value. The `-` operator on jsonb returns the
+ * object without that key; a key that was not present is a no-op.
+ */
+export async function stripKeyFromRecords(
+  db: Queryable,
+  workspaceId: string,
+  objectType: CustomFieldObjectType,
+  key: string,
+): Promise<number> {
+  const table = TABLES[objectType]
+  const stripped = await db
+    .update(table)
+    .set({
+      customFields: sql`${table.customFields} - ${key}`,
+    })
+    .where(and(eq(table.workspaceId, workspaceId), sql`${table.customFields} ? ${key}`))
+    .returning({ id: table.id })
+
+  return stripped.length
+}
+
+/** Bulk row read for a caller that already has a set of ids to update. */
+export async function readCustomFieldsById(
+  db: Queryable,
+  workspaceId: string,
+  objectType: CustomFieldObjectType,
+  ids: readonly string[],
+): Promise<Map<string, Readonly<Record<string, unknown>>>> {
+  if (ids.length === 0) {
+    return new Map()
+  }
+  const table = TABLES[objectType]
+  const rows = await db
+    .select({ id: table.id, customFields: table.customFields })
+    .from(table)
+    .where(and(eq(table.workspaceId, workspaceId), inArray(table.id, [...ids])))
+
+  return new Map(rows.map((row) => [row.id, row.customFields]))
+}

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

@@ -0,0 +1,155 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+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 { CUSTOM_FIELD_OBJECT_TYPES, CUSTOM_FIELD_TYPES } from './schema.ts'
+import type { CustomFieldObjectType } from './schema.ts'
+import type {
+  CreateCustomFieldDefinitionInput,
+  CustomFieldDefinitionView,
+  CustomFieldDefinitionsService,
+  UpdateCustomFieldDefinitionInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/custom_fields`.
+ *
+ * `key`, `type`, and `object_type` are only on the create body: the update
+ * body omits them, and a strict PATCH answers `422` for any of the three.
+ * `options` accepts any string list here; per-type membership (and the
+ * "options only on select-like types" rule) live in the service.
+ */
+
+const optionsSchema = z.array(z.string().min(1).max(120)).max(100)
+
+export const createBody = z.strictObject({
+  object_type: z.enum(CUSTOM_FIELD_OBJECT_TYPES),
+  key: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+  type: z.enum(CUSTOM_FIELD_TYPES),
+  options: optionsSchema.default([]),
+  description: z.string().max(2000).default(''),
+})
+
+export const updateBody = z
+  .strictObject({
+    label: z.string().min(1).max(120),
+    description: z.string().max(2000),
+    options: optionsSchema,
+    sort_order: z.number().int().min(0),
+  })
+  .partial()
+
+export interface CustomFieldsRoutesDependencies extends CredentialDependencies {
+  readonly service: CustomFieldDefinitionsService
+}
+
+export function toCreateInput(
+  body: z.infer<typeof createBody>,
+): CreateCustomFieldDefinitionInput {
+  return {
+    objectType: body.object_type,
+    key: body.key,
+    label: body.label,
+    type: body.type,
+    options: body.options,
+    description: body.description,
+  }
+}
+
+export function toUpdateInput(
+  body: z.infer<typeof updateBody>,
+): UpdateCustomFieldDefinitionInput {
+  return {
+    ...(body.label === undefined ? {} : { label: body.label }),
+    ...(body.description === undefined ? {} : { description: body.description }),
+    ...(body.options === undefined ? {} : { options: body.options }),
+    ...(body.sort_order === undefined ? {} : { sortOrder: body.sort_order }),
+  }
+}
+
+export function customFieldDefinitionResponse(
+  definition: CustomFieldDefinitionView,
+): Record<string, unknown> {
+  return {
+    id: definition.id,
+    object_type: definition.objectType,
+    key: definition.key,
+    label: definition.label,
+    type: definition.type,
+    options: definition.options,
+    description: definition.description,
+    sort_order: definition.sortOrder,
+    created_at: definition.createdAt.toISOString(),
+    updated_at: definition.updatedAt.toISOString(),
+  }
+}
+
+function readObjectTypeFilter(context: Context): CustomFieldObjectType | undefined {
+  const raw = context.req.query('object_type')
+  if (raw === undefined) {
+    return undefined
+  }
+  if (!CUSTOM_FIELD_OBJECT_TYPES.includes(raw as CustomFieldObjectType)) {
+    throw AppError.validationFailed('That is not a record type custom fields attach to', [
+      { field: 'object_type', message: `Unknown object type "${raw}"` },
+    ])
+  }
+  return raw as CustomFieldObjectType
+}
+
+export function mountCustomFieldsRoutes(
+  router: Hono,
+  dependencies: CustomFieldsRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> =>
+    resolveActorFrom(dependencies, context)
+
+  router.get('/custom_fields', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        objectType: readObjectTypeFilter(context),
+      },
+      readListParameters(context),
+    )
+    return context.json(pageBody(page, customFieldDefinitionResponse))
+  })
+
+  router.post('/custom_fields', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const definition = await dependencies.service.create(
+      await requireActor(context),
+      toCreateInput(body),
+    )
+    return context.json(customFieldDefinitionResponse(definition), 201)
+  })
+
+  router.get('/custom_fields/:id', async (context) => {
+    const definition = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+    return context.json(customFieldDefinitionResponse(definition))
+  })
+
+  router.patch('/custom_fields/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const definition = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+    return context.json(customFieldDefinitionResponse(definition))
+  })
+
+  router.delete('/custom_fields/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+    return context.body(null, 204)
+  })
+}

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

@@ -0,0 +1,61 @@
+import { CUSTOM_FIELD_OBJECT_TYPES, CUSTOM_FIELD_TYPES } from '@kelpie/schemas'
+import { index, integer, jsonb, 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 field definitions for the six taggable record types.
+ *
+ * `key` and `type` are set at create and are immutable after: a rename would
+ * strand every record's value under an old key, and a type swap would leave the
+ * jsonb value in the wrong shape. The strict PATCH body naturally refuses
+ * either as a `422`.
+ *
+ * `options` is stored as jsonb rather than `text[]` so future option metadata
+ * (colours, an archived flag) can be added without a migration. Empty for every
+ * type but `select` and `multi_select`; the service enforces that half of the
+ * rule.
+ *
+ * Re-exports the two arrays so the routes layer reads them from here alongside
+ * the tables they constrain.
+ */
+export { CUSTOM_FIELD_OBJECT_TYPES, CUSTOM_FIELD_TYPES } from '@kelpie/schemas'
+export type { CustomFieldObjectType, CustomFieldType } from '@kelpie/schemas'
+
+export const customFieldDefinitions = pgTable(
+  'custom_field_definitions',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    objectType: text('object_type').notNull(),
+    key: text('key').notNull(),
+    label: text('label').notNull(),
+    type: text('type').notNull(),
+    options: jsonb('options').$type<readonly string[]>().notNull().default([]),
+    description: text('description').notNull().default(''),
+    sortOrder: integer('sort_order').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('custom_field_definitions_workspace_idx').on(table.workspaceId),
+    index('custom_field_definitions_workspace_object_idx').on(
+      table.workspaceId,
+      table.objectType,
+    ),
+    unique('custom_field_definitions_workspace_object_key_key').on(
+      table.workspaceId,
+      table.objectType,
+      table.key,
+    ),
+    checkOneOf(
+      'custom_field_definitions_object_type_check',
+      table.objectType,
+      CUSTOM_FIELD_OBJECT_TYPES,
+    ),
+    checkOneOf('custom_field_definitions_type_check', table.type, CUSTOM_FIELD_TYPES),
+  ],
+)