@kelpie/server 0.12.0 → 0.13.0

package/src/modules/events/routes.ts

@@ -0,0 +1,405 @@
+import {
+  ATTENDANCE_SOURCES,
+  ATTENDANCE_STATUSES,
+  EVENT_ASSOCIATION_TARGET_TYPES,
+  EVENT_FORMATS,
+  EVENT_STATUSES,
+  customFieldsPatchShape,
+} from '@kelpie/schemas'
+import type { EventAssociationTargetType } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+import { pageBody, readIdFilter, readJsonBody, readListParameters } from '../../lib/http.ts'
+import { renderCustomFieldsForWire } from '../custom-fields/wire.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type {
+  AttendanceView,
+  AttendancesService,
+  CreateAttendanceInput,
+  UpdateAttendanceInput,
+} from './attendances.ts'
+import type { CreateEventInput, EventView, EventsService, UpdateEventInput } from './service.ts'
+import type { AssociationRef } from './repository.ts'
+
+const isoTimestamp = z.iso.datetime()
+
+const associationBody = z.strictObject({
+  target_type: z.enum(EVENT_ASSOCIATION_TARGET_TYPES),
+  target_id: z.string().min(1),
+})
+
+const eventShape = {
+  name: z.string().min(1),
+  kind: z.string(),
+  starts_at: isoTimestamp,
+  ends_at: isoTimestamp,
+  timezone: z.string().min(1),
+  location: z.string(),
+  meeting_url: z.string().url().nullable(),
+  format: z.enum(EVENT_FORMATS),
+  details: z.string(),
+  status: z.enum(EVENT_STATUSES),
+  owner_id: z.string().min(1).nullable(),
+  summary: z.string(),
+  tags: z.array(z.string().min(1)),
+  associations: z.array(associationBody),
+  custom_fields: customFieldsPatchShape,
+}
+
+export const createEventBody = z.strictObject({
+  ...eventShape,
+  kind: eventShape.kind.default(''),
+  timezone: eventShape.timezone.optional(),
+  location: eventShape.location.default(''),
+  meeting_url: eventShape.meeting_url.default(null),
+  details: eventShape.details.default(''),
+  status: eventShape.status.default('scheduled'),
+  owner_id: eventShape.owner_id.optional(),
+  summary: eventShape.summary.default(''),
+  tags: eventShape.tags.default([]),
+  associations: eventShape.associations.default([]),
+  custom_fields: eventShape.custom_fields.default({}),
+})
+
+export const updateEventBody = z.strictObject(eventShape).partial()
+
+const attendanceShape = {
+  event_id: z.string().min(1),
+  person_id: z.string().min(1),
+  status: z.enum(ATTENDANCE_STATUSES),
+  source: z.enum(ATTENDANCE_SOURCES),
+}
+
+export const createAttendanceBody = z.strictObject({
+  ...attendanceShape,
+  status: attendanceShape.status.default('registered'),
+  source: attendanceShape.source.default('manual'),
+})
+
+export const nestedCreateAttendanceBody = z.strictObject({
+  person_id: z.string().min(1),
+  status: z.enum(ATTENDANCE_STATUSES).default('registered'),
+})
+
+export const updateAttendanceBody = z.strictObject({ status: z.enum(ATTENDANCE_STATUSES) }).partial()
+
+export interface EventsRoutesDependencies extends CredentialDependencies {
+  readonly events: EventsService
+  readonly attendances: AttendancesService
+}
+
+function toAssociation(body: z.infer<typeof associationBody>): AssociationRef {
+  return { targetType: body.target_type, targetId: body.target_id }
+}
+
+export function toCreateEventInput(body: z.infer<typeof createEventBody>): CreateEventInput {
+  return {
+    name: body.name,
+    kind: body.kind,
+    startsAt: new Date(body.starts_at),
+    endsAt: new Date(body.ends_at),
+    timezone: body.timezone,
+    location: body.location,
+    meetingUrl: body.meeting_url,
+    format: body.format,
+    details: body.details,
+    status: body.status,
+    ownerId: body.owner_id,
+    summary: body.summary,
+    tags: body.tags,
+    associations: body.associations.map(toAssociation),
+    customFields: body.custom_fields,
+  }
+}
+
+export function toUpdateEventInput(body: z.infer<typeof updateEventBody>): UpdateEventInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.kind === undefined ? {} : { kind: body.kind }),
+    ...(body.starts_at === undefined ? {} : { startsAt: new Date(body.starts_at) }),
+    ...(body.ends_at === undefined ? {} : { endsAt: new Date(body.ends_at) }),
+    ...(body.timezone === undefined ? {} : { timezone: body.timezone }),
+    ...(body.location === undefined ? {} : { location: body.location }),
+    ...(body.meeting_url === undefined ? {} : { meetingUrl: body.meeting_url }),
+    ...(body.format === undefined ? {} : { format: body.format }),
+    ...(body.details === undefined ? {} : { details: body.details }),
+    ...(body.status === undefined ? {} : { status: body.status }),
+    ...(body.owner_id === undefined ? {} : { ownerId: body.owner_id }),
+    ...(body.summary === undefined ? {} : { summary: body.summary }),
+    ...(body.tags === undefined ? {} : { tags: body.tags }),
+    ...(body.associations === undefined
+      ? {}
+      : { associations: body.associations.map(toAssociation) }),
+    ...(body.custom_fields === undefined ? {} : { customFields: body.custom_fields }),
+  }
+}
+
+export function eventResponse(event: EventView): Record<string, unknown> {
+  return {
+    id: event.id,
+    name: event.name,
+    kind: event.kind,
+    starts_at: event.startsAt.toISOString(),
+    ends_at: event.endsAt.toISOString(),
+    timezone: event.timezone,
+    location: event.location,
+    meeting_url: event.meetingUrl,
+    format: event.format,
+    details: event.details,
+    status: event.status,
+    owner_id: event.ownerId,
+    summary: event.summary,
+    tags: event.tags,
+    associations: event.associations.map((row) => ({
+      target_type: row.targetType,
+      target_id: row.targetId,
+    })),
+    custom_fields: renderCustomFieldsForWire(event.customFields),
+    created_at: event.createdAt.toISOString(),
+    updated_at: event.updatedAt.toISOString(),
+  }
+}
+
+export function toCreateAttendanceInput(
+  body: z.infer<typeof createAttendanceBody>,
+): CreateAttendanceInput {
+  return {
+    eventId: body.event_id,
+    personId: body.person_id,
+    status: body.status,
+    source: body.source,
+  }
+}
+
+export function toUpdateAttendanceInput(
+  body: z.infer<typeof updateAttendanceBody>,
+): UpdateAttendanceInput {
+  return body.status === undefined ? {} : { status: body.status }
+}
+
+export function attendanceResponse(row: AttendanceView): Record<string, unknown> {
+  return {
+    id: row.id,
+    event_id: row.eventId,
+    person_id: row.personId,
+    status: row.status,
+    source: row.source,
+    created_at: row.createdAt.toISOString(),
+    updated_at: row.updatedAt.toISOString(),
+  }
+}
+
+function readEnumFilter<Value extends string>(
+  context: Context,
+  name: string,
+  allowed: readonly Value[],
+): readonly Value[] | undefined {
+  const values = readIdFilter(context, name)
+
+  if (values === undefined) {
+    return undefined
+  }
+
+  const unknown = values.filter((value) => !allowed.includes(value as Value))
+
+  if (unknown.length > 0) {
+    throw AppError.validationFailed(`"${name}" does not take ${unknown.join(', ')}`, [
+      { field: name, message: `Expected one of ${allowed.join(', ')}` },
+    ])
+  }
+
+  return values as readonly Value[]
+}
+
+function readTimestampQuery(context: Context, name: string): Date | undefined {
+  const raw = context.req.query(name)
+
+  if (raw === undefined || raw === '') {
+    return undefined
+  }
+
+  const parsed = isoTimestamp.safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed(`"${name}" must be an ISO 8601 timestamp`, [
+      { field: name, message: 'Use 2026-08-02T01:00:00.000Z' },
+    ])
+  }
+
+  return new Date(parsed.data)
+}
+
+export function mountEventsRoutes(router: Hono, dependencies: EventsRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/events', async (context) => {
+    const page = await dependencies.events.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        statuses: readEnumFilter(context, 'status', EVENT_STATUSES),
+        formats: readEnumFilter(context, 'format', EVENT_FORMATS),
+        ownerIds: readIdFilter(context, 'owner_id'),
+        from: readTimestampQuery(context, 'from'),
+        to: readTimestampQuery(context, 'to'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, eventResponse))
+  })
+
+  router.post('/events', async (context) => {
+    const body = await readJsonBody(context, createEventBody)
+    const event = await dependencies.events.create(
+      await requireActor(context),
+      toCreateEventInput(body),
+    )
+
+    return context.json(eventResponse(event), 201)
+  })
+
+  router.get('/events/:id', async (context) => {
+    const event = await dependencies.events.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(eventResponse(event))
+  })
+
+  router.patch('/events/:id', async (context) => {
+    const body = await readJsonBody(context, updateEventBody)
+    const event = await dependencies.events.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateEventInput(body),
+    )
+
+    return context.json(eventResponse(event))
+  })
+
+  router.delete('/events/:id', async (context) => {
+    await dependencies.events.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  router.get('/events/:id/attendances', async (context) => {
+    const page = await dependencies.attendances.list(
+      await requireActor(context),
+      {
+        eventIds: [context.req.param('id')],
+        statuses: readEnumFilter(context, 'status', ATTENDANCE_STATUSES),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, attendanceResponse))
+  })
+
+  router.post('/events/:id/attendances', async (context) => {
+    const body = await readJsonBody(context, nestedCreateAttendanceBody)
+    const row = await dependencies.attendances.create(await requireActor(context), {
+      eventId: context.req.param('id'),
+      personId: body.person_id,
+      status: body.status,
+      source: 'manual',
+    })
+
+    return context.json(attendanceResponse(row), 201)
+  })
+
+  router.get('/attendances', async (context) => {
+    const page = await dependencies.attendances.list(
+      await requireActor(context),
+      {
+        eventIds: readIdFilter(context, 'event_id'),
+        personIds: readIdFilter(context, 'person_id'),
+        statuses: readEnumFilter(context, 'status', ATTENDANCE_STATUSES),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, attendanceResponse))
+  })
+
+  router.post('/attendances', async (context) => {
+    const body = await readJsonBody(context, createAttendanceBody)
+    const row = await dependencies.attendances.create(
+      await requireActor(context),
+      toCreateAttendanceInput(body),
+    )
+
+    return context.json(attendanceResponse(row), 201)
+  })
+
+  router.get('/attendances/:id', async (context) => {
+    const row = await dependencies.attendances.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(attendanceResponse(row))
+  })
+
+  router.patch('/attendances/:id', async (context) => {
+    const body = await readJsonBody(context, updateAttendanceBody)
+    const row = await dependencies.attendances.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateAttendanceInput(body),
+    )
+
+    return context.json(attendanceResponse(row))
+  })
+
+  router.delete('/attendances/:id', async (context) => {
+    await dependencies.attendances.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  router.get('/event-associations', async (context) => {
+    const actor = await requireActor(context)
+    const targetType = context.req.query('target_type')
+    const targetId = context.req.query('target_id')
+
+    if (targetType === undefined || targetId === undefined || targetId === '') {
+      throw AppError.validationFailed('target_type and target_id are required', [
+        { field: 'target_type', message: 'Required with target_id' },
+      ])
+    }
+
+    const parsed = z.enum(EVENT_ASSOCIATION_TARGET_TYPES).safeParse(targetType)
+
+    if (!parsed.success) {
+      throw AppError.validationFailed('Unknown association target type', [
+        {
+          field: 'target_type',
+          message: `Use one of: ${EVENT_ASSOCIATION_TARGET_TYPES.join(', ')}`,
+        },
+      ])
+    }
+
+    const rows = await dependencies.events.listAssociationsFor(
+      actor,
+      parsed.data as EventAssociationTargetType,
+      targetId,
+    )
+
+    return context.json({
+      data: rows.map((row) => ({
+        event_id: row.eventId,
+        event_name: row.eventName,
+        target_type: parsed.data,
+        target_id: targetId,
+      })),
+      next_cursor: null,
+    })
+  })
+}

package/src/modules/events/schema.ts

@@ -0,0 +1,148 @@
+import {
+  ATTENDANCE_SOURCES,
+  ATTENDANCE_STATUSES,
+  EVENT_ASSOCIATION_TARGET_TYPES,
+  EVENT_FORMATS,
+  EVENT_STATUSES,
+} from '@kelpie/schemas'
+import type { CustomFieldValue } from '@kelpie/schemas'
+import { index, jsonb, pgTable, text, timestamp, unique } from 'drizzle-orm/pg-core'
+
+import {
+  checkOneOf,
+  createdAt,
+  primaryId,
+  searchVector,
+  updatedAt,
+} from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { people } from '../people/schema.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+export {
+  ATTENDANCE_SOURCES,
+  ATTENDANCE_STATUSES,
+  EVENT_ASSOCIATION_TARGET_TYPES,
+  EVENT_FORMATS,
+  EVENT_STATUSES,
+} from '@kelpie/schemas'
+export type {
+  AttendanceSource,
+  AttendanceStatus,
+  EventAssociationTargetType,
+  EventFormat,
+  EventStatus,
+} from '@kelpie/schemas'
+
+/**
+ * A dated gathering. Not a pipeline: no stages, no kanban, no person_links.
+ * People attach as Attendances; other records attach through event_associations.
+ */
+export const events = pgTable(
+  'events',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    kind: text('kind').notNull().default(''),
+    startsAt: timestamp('starts_at', { withTimezone: true, mode: 'date' }).notNull(),
+    endsAt: timestamp('ends_at', { withTimezone: true, mode: 'date' }).notNull(),
+    timezone: text('timezone').notNull(),
+    location: text('location').notNull().default(''),
+    meetingUrl: text('meeting_url'),
+    format: text('format').notNull(),
+    details: text('details').notNull().default(''),
+    status: text('status').notNull(),
+    ownerId: text('owner_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
+    summary: text('summary').notNull().default(''),
+    tags: text('tags').array().notNull().default([]),
+    customFields: jsonb('custom_fields')
+      .$type<Readonly<Record<string, CustomFieldValue>>>()
+      .notNull()
+      .default({}),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: events.name, weight: 'A' },
+      { column: events.details, weight: 'B' },
+      { column: events.summary, weight: 'B' },
+      { column: events.kind, weight: 'C' },
+      { column: events.location, weight: 'C' },
+      { column: events.tags, weight: 'C', array: true },
+    ]),
+  },
+  (table) => [
+    index('events_workspace_idx').on(table.workspaceId),
+    index('events_starts_idx').on(table.workspaceId, table.startsAt),
+    index('events_search_idx').using('gin', table.searchVector),
+    checkOneOf('events_format_check', table.format, EVENT_FORMATS),
+    checkOneOf('events_status_check', table.status, EVENT_STATUSES),
+  ],
+)
+
+/** The Person↔Event link. RSVP state lives here, never on Person. */
+export const attendances = pgTable(
+  'attendances',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    eventId: text('event_id')
+      .notNull()
+      .references(() => events.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'cascade' }),
+    status: text('status').notNull(),
+    source: text('source').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    unique('attendances_event_person_key').on(table.eventId, table.personId),
+    index('attendances_workspace_idx').on(table.workspaceId),
+    index('attendances_event_idx').on(table.eventId),
+    index('attendances_person_idx').on(table.personId),
+    checkOneOf('attendances_status_check', table.status, ATTENDANCE_STATUSES),
+    checkOneOf('attendances_source_check', table.source, ATTENDANCE_SOURCES),
+  ],
+)
+
+/**
+ * Event↔other record. Polymorphic target, no FK. The id never crosses the wire.
+ */
+export const eventAssociations = pgTable(
+  'event_associations',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    eventId: text('event_id')
+      .notNull()
+      .references(() => events.id, { onDelete: 'cascade' }),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    createdAt: createdAt(),
+  },
+  (table) => [
+    unique('event_associations_event_target_key').on(
+      table.eventId,
+      table.targetType,
+      table.targetId,
+    ),
+    index('event_associations_target_idx').on(
+      table.workspaceId,
+      table.targetType,
+      table.targetId,
+    ),
+    checkOneOf(
+      'event_associations_target_type_check',
+      table.targetType,
+      EVENT_ASSOCIATION_TARGET_TYPES,
+    ),
+  ],
+)