@kelpie/server 0.1.0

package/src/modules/forms/routes.ts

@@ -0,0 +1,276 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+import {
+  PUBLIC_ROUTE_PREFIX,
+  pageBody,
+  readJsonBody,
+  readListParameters,
+  requestOrigin,
+} 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 { embedSnippets } from './embed.ts'
+import type { FieldDraft } from './fields.ts'
+import {
+  FORM_FIELD_MAP_TARGETS,
+  FORM_FIELD_TYPES,
+  FORM_OPTION_VALUE_TYPES,
+  FORM_STATUSES,
+} from './schema.ts'
+import type { FormStatus } from './schema.ts'
+import type {
+  CreateFormInput,
+  FormSubmissionView,
+  FormView,
+  FormsService,
+  UpdateFormInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/forms`. Bodies are strict; an unknown field is a 422, per
+ * `api.md`.
+ *
+ * Fields are nested rather than their own resource, and a write carries the
+ * whole list. Field ids therefore never appear in a request: they are assigned
+ * on write, and a client that wants to change one field sends the list back with
+ * that field changed. That is also exactly what a drag-reorder sends.
+ */
+
+const optionBody = z.strictObject({
+  key: z.string().min(1),
+  value: z.string().min(1),
+  value_type: z.enum(FORM_OPTION_VALUE_TYPES).default('string'),
+})
+
+const fieldBody = z.strictObject({
+  label: z.string().min(1),
+  type: z.enum(FORM_FIELD_TYPES),
+  required: z.boolean().default(false),
+  map_to: z.enum(FORM_FIELD_MAP_TARGETS),
+  options: z.array(optionBody).default([]),
+  placeholder: z.string().nullable().default(null),
+})
+
+const formShape = {
+  name: z.string().min(1),
+  description: z.string().nullable(),
+  status: z.enum(FORM_STATUSES),
+  fields: z.array(fieldBody),
+  thank_you_message: z.string(),
+  create_deal: z.boolean(),
+  deal_stage_id: z.string().min(1).nullable(),
+  deal_name_template: z.string().nullable(),
+}
+
+/**
+ * A name and a field list are the whole requirement.
+ *
+ * A form is created active, because a form nobody can submit to is not a state
+ * anybody asks for on purpose; pausing it is one PATCH away. An absent
+ * `deal_stage_id` with `create_deal` on means the pipeline's first open stage,
+ * resolved at submit time rather than frozen at create time, so a workspace that
+ * reorders its board does not leave old forms pointing at a stage it moved.
+ */
+export const createBody = z.strictObject({
+  ...formShape,
+  description: formShape.description.default(null),
+  status: formShape.status.default('active'),
+  thank_you_message: formShape.thank_you_message.default('Thanks. We will be in touch.'),
+  create_deal: formShape.create_deal.default(false),
+  deal_stage_id: formShape.deal_stage_id.default(null),
+  deal_name_template: formShape.deal_name_template.default(null),
+})
+
+export const updateBody = z.strictObject(formShape).partial()
+
+const statusFilter = z.enum(FORM_STATUSES)
+
+export interface FormsRoutesDependencies extends CredentialDependencies {
+  readonly service: FormsService
+}
+
+function readStatusFilter(context: Context): FormStatus | undefined {
+  const raw = context.req.query('status')
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  const parsed = statusFilter.safeParse(raw)
+
+  // Silently answering "no forms" would report a typo as an empty workspace.
+  if (!parsed.success) {
+    throw AppError.validationFailed('That form status does not exist', [
+      { field: 'status', message: `Use one of: ${FORM_STATUSES.join(', ')}` },
+    ])
+  }
+
+  return parsed.data
+}
+
+function toFieldDraft(field: z.infer<typeof fieldBody>): FieldDraft {
+  return {
+    label: field.label,
+    type: field.type,
+    required: field.required,
+    mapTo: field.map_to,
+    options: field.options.map((option) => ({
+      key: option.key,
+      value: option.value,
+      valueType: option.value_type,
+    })),
+    placeholder: field.placeholder,
+  }
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateFormInput {
+  return {
+    name: body.name,
+    description: body.description,
+    status: body.status,
+    fields: body.fields.map(toFieldDraft),
+    thankYouMessage: body.thank_you_message,
+    createDeal: body.create_deal,
+    dealStageId: body.deal_stage_id,
+    dealNameTemplate: body.deal_name_template,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateFormInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.description === undefined ? {} : { description: body.description }),
+    ...(body.status === undefined ? {} : { status: body.status }),
+    ...(body.fields === undefined ? {} : { fields: body.fields.map(toFieldDraft) }),
+    ...(body.thank_you_message === undefined ? {} : { thankYouMessage: body.thank_you_message }),
+    ...(body.create_deal === undefined ? {} : { createDeal: body.create_deal }),
+    ...(body.deal_stage_id === undefined ? {} : { dealStageId: body.deal_stage_id }),
+    ...(body.deal_name_template === undefined
+      ? {}
+      : { dealNameTemplate: body.deal_name_template }),
+  }
+}
+
+export function formResponse(form: FormView): Record<string, unknown> {
+  return {
+    id: form.id,
+    name: form.name,
+    description: form.description,
+    status: form.status,
+    fields: form.fields.map((field) => ({
+      id: field.id,
+      label: field.label,
+      type: field.type,
+      required: field.required,
+      map_to: field.mapTo,
+      options: field.options.map((option) => ({
+        key: option.key,
+        value: option.value,
+        value_type: option.valueType,
+      })),
+      placeholder: field.placeholder,
+      sort_order: field.sortOrder,
+    })),
+    thank_you_message: form.thankYouMessage,
+    create_deal: form.createDeal,
+    deal_stage_id: form.dealStageId,
+    deal_name_template: form.dealNameTemplate,
+    public_key: form.publicKey,
+    created_at: form.createdAt.toISOString(),
+    updated_at: form.updatedAt.toISOString(),
+  }
+}
+
+export function formSubmissionResponse(submission: FormSubmissionView): Record<string, unknown> {
+  return {
+    id: submission.id,
+    form_id: submission.formId,
+    submitted_at: submission.submittedAt.toISOString(),
+    answers: submission.answers,
+    person_id: submission.personId,
+    company_id: submission.companyId,
+    position_id: submission.positionId,
+    deal_id: submission.dealId,
+    created_at: submission.createdAt.toISOString(),
+  }
+}
+
+/** The absolute URL of a form's hosted embed page, on the origin this request arrived at. */
+export function embedUrlFor(context: Context, publicKey: string): string {
+  return `${requestOrigin(context)}${PUBLIC_ROUTE_PREFIX}/forms/${publicKey}/embed`
+}
+
+export function mountFormsRoutes(router: Hono, dependencies: FormsRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/forms', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      { term: context.req.query('q'), status: readStatusFilter(context) },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, formResponse))
+  })
+
+  router.post('/forms', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const form = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(formResponse(form), 201)
+  })
+
+  router.get('/forms/:id', async (context) => {
+    const form = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(formResponse(form))
+  })
+
+  router.patch('/forms/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const form = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(formResponse(form))
+  })
+
+  router.delete('/forms/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  router.get('/forms/:id/submissions', async (context) => {
+    const page = await dependencies.service.listSubmissions(
+      await requireActor(context),
+      context.req.param('id'),
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, formSubmissionResponse))
+  })
+
+  /**
+   * What to paste into a website.
+   *
+   * Its own endpoint rather than a field on the form, so the form's shape is the
+   * same on a list and on a read. The snippets are derived from the request's
+   * origin and the form's `public_key`, neither of which is stored.
+   */
+  router.get('/forms/:id/embed', async (context) => {
+    const form = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+    const snippets = embedSnippets(embedUrlFor(context, form.publicKey), form.id)
+
+    return context.json({
+      url: snippets.url,
+      iframe_snippet: snippets.iframe,
+      script_snippet: snippets.script,
+    })
+  })
+}

package/src/modules/forms/schema.ts

@@ -0,0 +1,135 @@
+import { FORM_FIELD_MAP_TARGETS, FORM_FIELD_TYPES, FORM_STATUSES } from '@kelpie/schemas'
+import type { FormOptionValueType } from '@kelpie/schemas'
+import { boolean, index, integer, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, moment, primaryId, updatedAt } from '../../lib/columns.ts'
+import { companies } from '../companies/schema.ts'
+import { deals } from '../deals/schema.ts'
+import { people } from '../people/schema.ts'
+import { pipelineStages } from '../pipelines/schema.ts'
+import { positions } from '../positions/schema.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * The fixed value sets come from `@kelpie/schemas`, so these tables' check
+ * constraints, this module's Zod enums, and the browser's decoder are one list
+ * rather than three copies. A value the boundary accepts and the check
+ * constraint refuses would be a 500 where a 422 belongs.
+ */
+export {
+  FORM_FIELD_MAP_TARGET_LABELS,
+  FORM_FIELD_MAP_TARGETS,
+  FORM_FIELD_TYPES,
+  FORM_OPTION_VALUE_TYPES,
+  FORM_STATUSES,
+  PERSON_EMAIL_TARGET,
+} from '@kelpie/schemas'
+export type {
+  FormFieldMapTarget,
+  FormFieldType,
+  FormOptionValueType,
+  FormStatus,
+} from '@kelpie/schemas'
+
+/**
+ * A select choice as it is stored.
+ *
+ * jsonb rather than a fourth table: nothing queries into an option, and the set
+ * is only ever read, written, and replaced along with the field that owns it.
+ * Typed rather than left as `unknown`, and the route layer parses what goes in,
+ * so a row read back is the shape it claims to be.
+ *
+ * No id. `key` is what a stored answer holds and what a submit is validated
+ * against, so it is already the handle; a second identifier would be one nothing
+ * addresses and one more thing to keep unique.
+ */
+export interface StoredFormFieldOption {
+  readonly key: string
+  readonly value: string
+  readonly valueType: FormOptionValueType
+}
+
+/**
+ * Embeddable inbound forms. `public_key` is globally unique because the public
+ * submit endpoint resolves the workspace from it, with no credentials.
+ */
+export const forms = pgTable(
+  'forms',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    description: text('description'),
+    status: text('status').notNull().default('active'),
+    thankYouMessage: text('thank_you_message').notNull().default(''),
+    createDeal: boolean('create_deal').notNull().default(false),
+    dealStageId: text('deal_stage_id').references(() => pipelineStages.id, { onDelete: 'restrict' }),
+    dealNameTemplate: text('deal_name_template'),
+    publicKey: text('public_key').notNull().unique(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('forms_workspace_idx').on(table.workspaceId),
+    checkOneOf('forms_status_check', table.status, FORM_STATUSES),
+  ],
+)
+
+/**
+ * `map_to` decides what a field writes on submit. At most one `person.email`
+ * mapping per form, enforced in the service layer because that is a per-form
+ * rule, not a per-row one.
+ */
+export const formFields = pgTable(
+  'form_fields',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    formId: text('form_id')
+      .notNull()
+      .references(() => forms.id, { onDelete: 'cascade' }),
+    label: text('label').notNull(),
+    type: text('type').notNull(),
+    required: boolean('required').notNull().default(false),
+    mapTo: text('map_to').notNull(),
+    options: jsonb('options').$type<readonly StoredFormFieldOption[]>().notNull().default([]),
+    placeholder: text('placeholder'),
+    sortOrder: integer('sort_order').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('form_fields_form_idx').on(table.formId),
+    checkOneOf('form_fields_type_check', table.type, FORM_FIELD_TYPES),
+    checkOneOf('form_fields_map_to_check', table.mapTo, FORM_FIELD_MAP_TARGETS),
+  ],
+)
+
+/**
+ * Record links are set null rather than cascade: a submission stays as evidence
+ * of what arrived even after the record it created is deleted.
+ */
+export const formSubmissions = pgTable(
+  'form_submissions',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    formId: text('form_id')
+      .notNull()
+      .references(() => forms.id, { onDelete: 'cascade' }),
+    submittedAt: moment('submitted_at').notNull().defaultNow(),
+    answers: jsonb('answers').$type<Readonly<Record<string, string>>>().notNull(),
+    personId: text('person_id').references(() => people.id, { onDelete: 'set null' }),
+    companyId: text('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    positionId: text('position_id').references(() => positions.id, { onDelete: 'set null' }),
+    dealId: text('deal_id').references(() => deals.id, { onDelete: 'set null' }),
+    createdAt: createdAt(),
+  },
+  (table) => [index('form_submissions_form_idx').on(table.formId)],
+)