@kelpie/server 0.1.0

package/src/modules/forms/mapping.ts

@@ -0,0 +1,222 @@
+import type { ErrorDetail } from '../../lib/errors.ts'
+import { normaliseDomain, normaliseEmail } from '../../lib/normalisation.ts'
+import type { FormFieldRecord } from './repository.ts'
+import { PERSON_EMAIL_TARGET } from './schema.ts'
+import type { FormFieldMapTarget } from './schema.ts'
+
+/**
+ * The submit rules from `forms.md` that need no database: what an answer map
+ * means, and whether it is one this form accepts.
+ *
+ * Pure on purpose. These are the rules a reader of `forms.md` would check by
+ * hand, they have no clock and no workspace, and they are the half of a submit
+ * worth a unit test. `submission.ts` holds the half that writes rows.
+ */
+
+/** An answer map as it arrives: field id to the text or option key given. */
+export type Answers = Readonly<Record<string, string>>
+
+/** Answers keyed by what they write rather than by which field carried them. */
+export type MappedAnswers = Partial<Record<FormFieldMapTarget, string>>
+
+/**
+ * What a submit will write, once the blanks are known.
+ *
+ * Every value here is already trimmed and normalised. A field the submitter left
+ * blank is absent rather than empty, because "not given" and "given as nothing"
+ * lead to different merges and only the first one happened.
+ */
+export interface SubmitIntent {
+  /** Normalised. The one value a submit cannot proceed without. */
+  readonly email: string
+  /** The name given, or the part of the address before the `@` when none was. */
+  readonly personName: string
+  readonly companyName: string | undefined
+  /** The `company.domain` answer only. Never derived from the address; see `resolveDomain`. */
+  readonly companyDomain: string | undefined
+  readonly positionTitle: string | undefined
+  /** Only meaningful when the form creates deals. */
+  readonly dealName: string | undefined
+}
+
+/**
+ * Reduces answers to one value per target.
+ *
+ * Blank answers are dropped, so a submitter who cleared a prefilled field does
+ * not overwrite a stored value with nothing. Two fields sharing a target is
+ * refused when the form is written, except for `submission`, which writes
+ * nothing and so cannot collide.
+ */
+export function mapAnswers(fields: readonly FormFieldRecord[], answers: Answers): MappedAnswers {
+  const mapped: MappedAnswers = {}
+
+  for (const field of fields) {
+    const value = answers[field.id]?.trim()
+
+    if (value === undefined || value.length === 0) {
+      continue
+    }
+
+    mapped[field.mapTo as FormFieldMapTarget] = value
+  }
+
+  return mapped
+}
+
+/**
+ * Everything wrong with an answer map, as `api.md` field details.
+ *
+ * All of it at once rather than the first problem: a form is filled in by a
+ * person, and telling them about one missing field at a time is how a contact
+ * form gets abandoned.
+ *
+ * A missing `person.email` is deliberately not reported here. It is the one
+ * failure that is about the form rather than the answers, `forms.md` gives it
+ * its own status, and the caller raises it before reaching this.
+ */
+export function findAnswerProblems(
+  fields: readonly FormFieldRecord[],
+  answers: Answers,
+): readonly ErrorDetail[] {
+  const known = new Set(fields.map((field) => field.id))
+  const problems: ErrorDetail[] = []
+
+  for (const id of Object.keys(answers)) {
+    if (!known.has(id)) {
+      problems.push({ field: `answers.${id}`, message: 'Unknown field' })
+    }
+  }
+
+  for (const field of fields) {
+    const value = answers[field.id]?.trim() ?? ''
+
+    if (value.length === 0) {
+      if (field.required) {
+        problems.push({ field: `answers.${field.id}`, message: `${field.label} is required` })
+      }
+
+      continue
+    }
+
+    // An option's `key` is what is stored, so it is what is accepted. The
+    // display `value` may change without invalidating a stored answer.
+    if (field.type === 'select' && !field.options.some((option) => option.key === value)) {
+      problems.push({
+        field: `answers.${field.id}`,
+        message: `${field.label} does not offer that choice`,
+      })
+    }
+  }
+
+  return problems
+}
+
+/**
+ * The domain a Company is matched or created on: the `company.domain` answer,
+ * and nothing else.
+ *
+ * The address's host is deliberately not used. An email domain is not a company
+ * identifier — one company sends from several, a consumer address belongs to no
+ * company at all, and two people at unrelated businesses can share one. Deriving
+ * a company from it merges records that were never the same company, and the
+ * merge is invisible until somebody notices two leads on one account.
+ *
+ * A form that wants companies matched on domain asks for the domain.
+ */
+function resolveDomain(mapped: MappedAnswers): string | undefined {
+  const given = mapped['company.domain']
+
+  return given === undefined ? undefined : normaliseDomain(given) ?? undefined
+}
+
+/**
+ * Reads an answer map into what the submit will write.
+ *
+ * @returns undefined when no usable `person.email` answer was given, which is
+ *   the `422` from `forms.md`. A value that is not an address at all fails the
+ *   same way: it would otherwise create a person nobody can reply to.
+ */
+export function readIntent(mapped: MappedAnswers): SubmitIntent | undefined {
+  const raw = mapped[PERSON_EMAIL_TARGET]
+  const email = raw === undefined ? null : normaliseEmail(raw)
+
+  if (email === null || !email.includes('@')) {
+    return undefined
+  }
+
+  return {
+    email,
+    personName: mapped['person.name'] ?? email.split('@')[0] ?? email,
+    companyName: mapped['company.name'],
+    companyDomain: resolveDomain(mapped),
+    positionTitle: mapped['position.title'],
+    dealName: mapped['deal.name'],
+  }
+}
+
+/**
+ * The merge rule for every field a submit touches: fill a blank, never overwrite.
+ *
+ * A form is filled in by whoever happens to be at the keyboard, and a CRM record
+ * carries what the team has since learned. An inbound "Alex" must not replace
+ * "Alex Rivera", so the stored value wins whenever there is one.
+ *
+ * @returns undefined when nothing should be written, which keeps the field out
+ *   of the update and off the `changedFields` of the event.
+ */
+export function fillBlank(stored: string | null, inbound: string | undefined): string | undefined {
+  if (inbound === undefined || inbound.length === 0) {
+    return undefined
+  }
+
+  return stored === null || stored.trim().length === 0 ? inbound : undefined
+}
+
+/** What a new Company is called when the answers named a domain and no name. */
+export function companyNameFrom(intent: SubmitIntent): string | undefined {
+  return intent.companyName ?? intent.companyDomain
+}
+
+/**
+ * Expands `{{company.name}}` and `{{person.name}}` in a deal name template.
+ *
+ * The fallbacks are the mockup's: a template is written once by an admin and
+ * then run against whatever arrives, so a submission with no company name must
+ * still produce a deal with a name somebody can read on a board.
+ */
+export function expandDealNameTemplate(
+  template: string,
+  values: { readonly companyName: string; readonly personName: string },
+): string {
+  return template
+    .replaceAll('{{company.name}}', values.companyName.length > 0 ? values.companyName : 'Website lead')
+    .replaceAll('{{person.name}}', values.personName.length > 0 ? values.personName : 'Lead')
+}
+
+/** How far ahead a deal created by a form is expected to close (`forms.md` rule 6). */
+export const DEAL_CLOSE_HORIZON_DAYS = 30
+
+/** `YYYY-MM-DD`, `days` after `from`. Date-only, per `api.md`. */
+export function expectedCloseFrom(from: Date, days: number): string {
+  const due = new Date(from.getTime())
+
+  due.setUTCDate(due.getUTCDate() + days)
+
+  return due.toISOString().slice(0, 10)
+}
+
+/**
+ * The first three answers, as `Label: value`, for the activity detail line.
+ *
+ * Three because the timeline renders one line and a contact form's first
+ * answers are the ones that say who arrived. The rest is on the submission.
+ */
+export function describeAnswers(fields: readonly FormFieldRecord[], answers: Answers): string | null {
+  const parts = fields
+    .map((field) => ({ label: field.label, value: answers[field.id]?.trim() ?? '' }))
+    .filter((entry) => entry.value.length > 0)
+    .slice(0, 3)
+    .map((entry) => `${entry.label}: ${entry.value}`)
+
+  return parts.length === 0 ? null : parts.join(' · ')
+}

package/src/modules/forms/publicRoutes.ts

@@ -0,0 +1,92 @@
+import type { Hono } from 'hono'
+import { z } from 'zod'
+
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import { PUBLIC_ROUTE_PREFIX, readJsonBody, requestOrigin } from '../../lib/http.ts'
+import { embedContentSecurityPolicy, renderEmbedPage } from './embed.ts'
+import * as repository from './repository.ts'
+import type { FormSubmitService, SubmitOutcome } from './submission.ts'
+
+/**
+ * `/v1/public/forms/:publicKey/…`: the two endpoints anybody on the internet may
+ * call, with no credentials and from any origin.
+ *
+ * No handler here resolves an `Actor`, and none can: there is nothing to resolve
+ * one from. The workspace comes from the form the `publicKey` names, and every
+ * query underneath is scoped to it. That is the whole auth story, and it is why
+ * these routes are registered through `context.publicRoutes` rather than
+ * `context.routes` — the mount says which they are.
+ */
+
+const submitBody = z.strictObject({
+  answers: z.record(z.string().min(1), z.string()),
+})
+
+export interface PublicFormRoutesDependencies {
+  readonly db: Database
+  /** Injected so a test can pin the value the CSP and the tags share. */
+  readonly generateNonce?: () => string
+  readonly submissions: FormSubmitService
+}
+
+function submitResponse(outcome: SubmitOutcome): Record<string, unknown> {
+  return {
+    id: outcome.submissionId,
+    form_id: outcome.formId,
+    submitted_at: outcome.submittedAt.toISOString(),
+    person_id: outcome.personId,
+    company_id: outcome.companyId,
+    position_id: outcome.positionId,
+    deal_id: outcome.dealId,
+    // Echoed so an embed can render the confirmation without a second request
+    // for a form definition it has no other reason to fetch.
+    thank_you_message: outcome.thankYouMessage,
+  }
+}
+
+export function mountPublicFormRoutes(
+  router: Hono,
+  dependencies: PublicFormRoutesDependencies,
+): void {
+  const generateNonce = dependencies.generateNonce ?? (() => crypto.randomUUID())
+
+  router.post('/forms/:publicKey/submit', async (context) => {
+    const body = await readJsonBody(context, submitBody)
+    const outcome = await dependencies.submissions.submit(context.req.param('publicKey'), body.answers)
+
+    return context.json(submitResponse(outcome), 201)
+  })
+
+  /**
+   * The hosted page a customer's site frames.
+   *
+   * Served here rather than by the React application: this loads inside somebody
+   * else's marketing site, and it has no business bringing the CRM bundle with
+   * it. A paused form still renders, and says so; only its submit is closed.
+   */
+  router.get('/forms/:publicKey/embed', async (context) => {
+    const publicKey = context.req.param('publicKey')
+    const form = await repository.findFormByPublicKey(dependencies.db, publicKey)
+
+    if (form === undefined) {
+      throw AppError.notFound('Form not found')
+    }
+
+    const nonce = generateNonce()
+    const page = renderEmbedPage({
+      form,
+      fields: await repository.listFields(dependencies.db, form.id),
+      submitUrl: `${requestOrigin(context)}${PUBLIC_ROUTE_PREFIX}/forms/${publicKey}/submit`,
+      nonce,
+    })
+
+    context.header('Content-Security-Policy', embedContentSecurityPolicy(nonce))
+    // The page is per-form and changes whenever the form is edited. A short
+    // shared cache keeps a popular landing page off the database on every view
+    // without leaving an edited form stale for long.
+    context.header('Cache-Control', 'public, max-age=60')
+
+    return context.html(page)
+  })
+}

package/src/modules/forms/repository.ts

@@ -0,0 +1,223 @@
+import { and, asc, eq, ilike, inArray, or } 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 { formFields, formSubmissions, forms } from './schema.ts'
+
+export type FormRecord = typeof forms.$inferSelect
+export type FormFieldRecord = typeof formFields.$inferSelect
+export type FormSubmissionRecord = typeof formSubmissions.$inferSelect
+
+/** The writable column shapes. Services build these; nothing else knows the column names. */
+export type FormColumns = typeof forms.$inferInsert
+export type FormFieldColumns = typeof formFields.$inferInsert
+export type FormSubmissionColumns = typeof formSubmissions.$inferInsert
+
+export const FORM_SORTS: SortableFields<FormRecord> = {
+  name: textSort(forms.name, (form) => form.name),
+  created_at: timestampSort(forms.createdAt, (form) => form.createdAt),
+  updated_at: timestampSort(forms.updatedAt, (form) => form.updatedAt),
+}
+
+export const DEFAULT_FORM_SORT = '-created_at'
+
+/**
+ * Submissions sort newest-first and by nothing else.
+ *
+ * `submitted_at` rather than `created_at`, even though a submit writes both at
+ * once: the two come apart the moment an import backfills historical
+ * submissions, and the question a reader asks is when the form was filled in.
+ */
+export const FORM_SUBMISSION_SORTS: SortableFields<FormSubmissionRecord> = {
+  submitted_at: timestampSort(formSubmissions.submittedAt, (row) => row.submittedAt),
+  created_at: timestampSort(formSubmissions.createdAt, (row) => row.createdAt),
+}
+
+export const DEFAULT_FORM_SUBMISSION_SORT = '-submitted_at'
+
+export interface FormFilters {
+  /** `?q=`: name and description. */
+  readonly term?: string | undefined
+  /** `?status=`: `active` or `paused`. */
+  readonly status?: string | undefined
+}
+
+function conditionsFor(workspaceId: string, filters: FormFilters): (SQL | undefined)[] {
+  const pattern = filters.term === undefined ? undefined : containsPattern(filters.term)
+
+  return [
+    eq(forms.workspaceId, workspaceId),
+    pattern === undefined ? undefined : or(ilike(forms.name, pattern), ilike(forms.description, pattern)),
+    filters.status === undefined ? undefined : eq(forms.status, filters.status),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listForms(
+  db: Queryable,
+  workspaceId: string,
+  filters: FormFilters,
+  window: ListWindow<FormRecord>,
+): Promise<FormRecord[]> {
+  return db
+    .select()
+    .from(forms)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, forms.id)))
+    .orderBy(...orderByWindow(window, forms.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findForm(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<FormRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(forms)
+    .where(and(eq(forms.workspaceId, workspaceId), eq(forms.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * The one lookup in this service that is not workspace-scoped, because it is
+ * what resolves the workspace.
+ *
+ * `public_key` is unique across every workspace (`schema.ts`), so this answers
+ * with at most one row and the caller reads `workspaceId` off it. Nothing else
+ * on a public request may name a workspace.
+ */
+export async function findFormByPublicKey(
+  db: Queryable,
+  publicKey: string,
+): Promise<FormRecord | undefined> {
+  const [found] = await db.select().from(forms).where(eq(forms.publicKey, publicKey)).limit(1)
+
+  return found
+}
+
+export async function insertForm(db: Queryable, values: FormColumns): Promise<FormRecord> {
+  const [created] = await db.insert(forms).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting form ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateForm(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<FormColumns>,
+): Promise<FormRecord | undefined> {
+  const [updated] = await db
+    .update(forms)
+    .set(changes)
+    .where(and(eq(forms.workspaceId, workspaceId), eq(forms.id, id)))
+    .returning()
+
+  return updated
+}
+
+/** Fields and submissions die with the form through their foreign keys. */
+export async function deleteForm(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(forms)
+    .where(and(eq(forms.workspaceId, workspaceId), eq(forms.id, id)))
+    .returning({ id: forms.id })
+
+  return deleted.length
+}
+
+/** One form's fields, in the order the embed renders them. */
+export function listFields(db: Queryable, formId: string): Promise<FormFieldRecord[]> {
+  return db
+    .select()
+    .from(formFields)
+    .where(eq(formFields.formId, formId))
+    .orderBy(asc(formFields.sortOrder), asc(formFields.id))
+}
+
+/**
+ * The fields of a page of forms, in one query.
+ *
+ * A list of forms renders each one's field count and mapping summary, and
+ * `api.md` has no `include` expansion, so the alternative is one query per row.
+ */
+export function listFieldsFor(
+  db: Queryable,
+  formIds: readonly string[],
+): Promise<FormFieldRecord[]> {
+  if (formIds.length === 0) {
+    return Promise.resolve([])
+  }
+
+  return db
+    .select()
+    .from(formFields)
+    .where(inArray(formFields.formId, formIds))
+    .orderBy(asc(formFields.sortOrder), asc(formFields.id))
+}
+
+export async function insertFields(
+  db: Queryable,
+  values: readonly FormFieldColumns[],
+): Promise<FormFieldRecord[]> {
+  if (values.length === 0) {
+    return []
+  }
+
+  return db.insert(formFields).values([...values]).returning()
+}
+
+/**
+ * Drops every field of a form, so the caller can write the list it was given.
+ *
+ * A write replaces the whole list rather than diffing it. Field ids are not
+ * addressable on the wire, positions are derived from the array's order, and a
+ * drag-reorder changes every position after the one that moved: a diff would be
+ * more code for the same rows.
+ */
+export async function deleteFields(db: Queryable, formId: string): Promise<void> {
+  await db.delete(formFields).where(eq(formFields.formId, formId))
+}
+
+export function listSubmissions(
+  db: Queryable,
+  workspaceId: string,
+  formId: string,
+  window: ListWindow<FormSubmissionRecord>,
+): Promise<FormSubmissionRecord[]> {
+  return db
+    .select()
+    .from(formSubmissions)
+    .where(
+      and(
+        eq(formSubmissions.workspaceId, workspaceId),
+        eq(formSubmissions.formId, formId),
+        keysetCondition(window, formSubmissions.id),
+      ),
+    )
+    .orderBy(...orderByWindow(window, formSubmissions.id))
+    .limit(window.fetchLimit)
+}
+
+export async function insertSubmission(
+  db: Queryable,
+  values: FormSubmissionColumns,
+): Promise<FormSubmissionRecord> {
+  const [created] = await db.insert(formSubmissions).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting form submission ${values.id} returned no row`)
+  }
+
+  return created
+}