@kelpie/server 0.8.0 → 0.9.0

package/src/modules/forms/fields.ts

@@ -3,6 +3,9 @@ import type { StoredFormFieldOption } from './schema.ts'
 import { PERSON_EMAIL_TARGET } from './schema.ts'
 import type { FormFieldMapTarget, FormFieldType, FormOptionValueType } from './schema.ts'
 
+/** The map target for a consent field. Repeatable, unique per purpose_id. */
+const PERSON_CONSENT_TARGET = 'person.consent'
+
 /**
  * What a form's field list has to satisfy before it is stored.
  *
@@ -20,6 +23,12 @@ export interface FieldDraft {
   readonly mapTo: FormFieldMapTarget
   readonly options: readonly OptionDraft[]
   readonly placeholder: string | null
+  /** The intro sentence for a `consent` field. Ignored for every other type. */
+  readonly statement: string | null
+  /** Non-empty for `consent` fields; one checkbox per id in display order. */
+  readonly consentPurposeIds: readonly string[]
+  /** Per-purpose override for the checkbox text. Falls back to the workspace label. */
+  readonly consentPurposeLabels: Readonly<Record<string, string>>
 }
 
 export interface OptionDraft {
@@ -52,13 +61,19 @@ const COMPANY_TARGETS: readonly string[] = ['company.name', 'company.domain']
  *   or `company.domain` answer, so a deal-creating form without either would
  *   quietly never create a deal. Refused here rather than discovered later by
  *   somebody wondering where their inbound pipeline went.
+ * @param createsPartnership Same rule for partnerships: a Partnership belongs
+ *   to a Company. Opportunities are exempt because `opportunities.company_id`
+ *   is nullable — a form that creates an opportunity without resolving a
+ *   company creates an opportunity without one, which is a valid state.
  */
 export function findFieldProblems(
   fields: readonly FieldShape[],
   createsDeal: boolean,
+  createsPartnership = false,
 ): readonly ErrorDetail[] {
   const problems: ErrorDetail[] = []
   const seenTargets = new Set<string>()
+  const usedConsentPurposes = new Set<string>()
 
   if (!fields.some((field) => field.mapTo === PERSON_EMAIL_TARGET)) {
     problems.push({
@@ -67,17 +82,78 @@ export function findFieldProblems(
     })
   }
 
-  if (createsDeal && !fields.some((field) => COMPANY_TARGETS.includes(field.mapTo))) {
+  const hasCompanyField = fields.some((field) => COMPANY_TARGETS.includes(field.mapTo))
+
+  if (createsDeal && !hasCompanyField) {
     problems.push({
       field: 'fields',
       message: `A form that creates deals needs a field mapped to ${COMPANY_TARGETS.join(' or ')}`,
     })
   }
 
+  if (createsPartnership && !hasCompanyField) {
+    problems.push({
+      field: 'fields',
+      message: `A form that creates partnerships needs a field mapped to ${COMPANY_TARGETS.join(' or ')}`,
+    })
+  }
+
   for (const [index, field] of fields.entries()) {
     const at = `fields.${String(index)}`
 
-    if (!REPEATABLE_TARGETS.has(field.mapTo)) {
+    // `person.consent` is repeatable — a form may carry more than one consent
+    // (checkbox) or notice (implicit) field, each offering its own list of
+    // purposes — but no purpose may appear on two fields, whether as the
+    // same field's duplicate or on two fields at once. Everything else
+    // non-`submission` is unique per form.
+    if (field.mapTo === PERSON_CONSENT_TARGET) {
+      if (field.type !== 'consent' && field.type !== 'notice') {
+        problems.push({
+          field: `${at}.type`,
+          message: 'A person.consent field must be of type "consent" or "notice"',
+        })
+      }
+      if (field.type === 'notice' && (field.statement ?? '').trim().length === 0) {
+        problems.push({
+          field: `${at}.statement`,
+          message: 'A notice field needs a statement',
+        })
+      }
+      if (field.consentPurposeIds.length === 0) {
+        problems.push({
+          field: `${at}.consent_purpose_ids`,
+          message:
+            field.type === 'notice'
+              ? 'A notice field needs at least one purpose it grants implicitly'
+              : 'A consent field needs at least one purpose',
+        })
+      } else {
+        const seenLocal = new Set<string>()
+        for (const purposeId of field.consentPurposeIds) {
+          if (seenLocal.has(purposeId)) {
+            problems.push({
+              field: `${at}.consent_purpose_ids`,
+              message: 'A consent field lists each purpose only once',
+            })
+            break
+          }
+          seenLocal.add(purposeId)
+          if (usedConsentPurposes.has(purposeId)) {
+            problems.push({
+              field: `${at}.consent_purpose_ids`,
+              message: 'Another consent field on this form already names this purpose',
+            })
+          } else {
+            usedConsentPurposes.add(purposeId)
+          }
+        }
+      }
+    } else if (field.type === 'consent' || field.type === 'notice') {
+      problems.push({
+        field: `${at}.map_to`,
+        message: 'A consent or notice field must map to person.consent',
+      })
+    } else if (!REPEATABLE_TARGETS.has(field.mapTo)) {
       if (seenTargets.has(field.mapTo)) {
         problems.push({ field: `${at}.map_to`, message: `Another field already maps to ${field.mapTo}` })
       }
@@ -150,6 +226,9 @@ export interface FieldShape {
   readonly mapTo: string
   readonly options: readonly StoredFormFieldOption[]
   readonly placeholder: string | null
+  readonly statement: string | null
+  readonly consentPurposeIds: readonly string[]
+  readonly consentPurposeLabels: Readonly<Record<string, string>>
 }
 
 /**
@@ -180,11 +259,32 @@ export function fieldsDiffer(
       field.required !== draft.required ||
       field.mapTo !== draft.mapTo ||
       field.placeholder !== draft.placeholder ||
+      field.statement !== draft.statement ||
+      stringListDiffer(field.consentPurposeIds, draft.consentPurposeIds) ||
+      labelMapDiffer(field.consentPurposeLabels, draft.consentPurposeLabels) ||
       optionsDiffer(field.options, draft.options)
     )
   })
 }
 
+function labelMapDiffer(
+  stored: Readonly<Record<string, string>>,
+  drafts: Readonly<Record<string, string>>,
+): boolean {
+  const storedKeys = Object.keys(stored)
+  const draftKeys = Object.keys(drafts)
+  if (storedKeys.length !== draftKeys.length) return true
+  return storedKeys.some((key) => stored[key] !== drafts[key])
+}
+
+function stringListDiffer(
+  stored: readonly string[],
+  drafts: readonly string[],
+): boolean {
+  if (stored.length !== drafts.length) return true
+  return stored.some((value, index) => value !== drafts[index])
+}
+
 function optionsDiffer(
   stored: readonly StoredFormFieldOption[],
   drafts: readonly OptionDraft[],

package/src/modules/forms/index.ts

@@ -23,7 +23,18 @@ import { registerFormsTools } from './tools.ts'
 export function createFormsModule(migrationsDirectory: string): KelpieModule {
   return {
     id: 'forms',
-    requires: ['people', 'companies', 'positions', 'pipelines', 'deals', 'activities'],
+    requires: [
+      'people',
+      'companies',
+      'positions',
+      'pipelines',
+      'deals',
+      'opportunities',
+      'partnerships',
+      'raises',
+      'lists',
+      'activities',
+    ],
     events: formsEvents,
 
     register(context) {

package/src/modules/forms/mapping.ts

@@ -1,3 +1,5 @@
+import { composeName } from '@kelpie/schemas'
+
 import type { ErrorDetail } from '../../lib/errors.ts'
 import { normaliseDomain, normaliseEmail } from '../../lib/normalisation.ts'
 import type { FormFieldRecord } from './repository.ts'
@@ -29,14 +31,48 @@ export type MappedAnswers = Partial<Record<FormFieldMapTarget, string>>
 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. */
+  /**
+   * The name given, the one composed from the first and last name answers, or —
+   * when the form asked for no name at all — the part of the address before the
+   * `@`.
+   */
   readonly personName: string
+  /** The `person.first_name` answer only. Never split out of `personName`. */
+  readonly personFirstName: string | undefined
+  readonly personLastName: string | undefined
   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
+  /** Only meaningful when the form creates opportunities. */
+  readonly opportunityName: string | undefined
+  /** Only meaningful when the form creates partnerships. */
+  readonly partnershipName: string | undefined
+  /** Only meaningful when the form creates enquiries. */
+  readonly enquiryName: string | undefined
+}
+
+/** True for a consent-field answer that means "ticked". */
+export function isConsentTicked(value: string | undefined): boolean {
+  if (value === undefined) return false
+  const trimmed = value.trim().toLowerCase()
+  return trimmed === 'true' || trimmed === 'on' || trimmed === '1' || trimmed === 'yes'
+}
+
+/** One consent grant read off the answers, for the submit transaction to apply. */
+export interface ConsentGrant {
+  readonly fieldId: string
+  readonly purposeId: string
+  /** The field-level intro sentence, shown above every checkbox in the field. */
+  readonly statement: string
+  /**
+   * The field's per-purpose text override for this purpose. Empty when the
+   * field defers to the workspace purpose's own label; the submit resolves
+   * that fallback with the purpose row it loads to record the activity.
+   */
+  readonly customLabel: string
 }
 
 /**
@@ -45,12 +81,18 @@ export interface SubmitIntent {
  * 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.
+ * nothing and so cannot collide, and `person.consent`, which is read by
+ * {@link readConsentGrants} instead — a form may carry several consent boxes,
+ * each granting a different purpose.
  */
 export function mapAnswers(fields: readonly FormFieldRecord[], answers: Answers): MappedAnswers {
   const mapped: MappedAnswers = {}
 
   for (const field of fields) {
+    // `person.consent` (both `consent` and `notice` types) is read separately
+    // — a checkbox field by ticked ids, a notice implicitly by submission.
+    if (field.mapTo === 'person.consent') continue
+
     const value = answers[field.id]?.trim()
 
     if (value === undefined || value.length === 0) {
@@ -63,6 +105,67 @@ export function mapAnswers(fields: readonly FormFieldRecord[], answers: Answers)
   return mapped
 }
 
+/**
+ * Every ticked purpose across every consent field on this form, in field
+ * order then purpose order. A consent field's answer is a comma-separated
+ * list of the purpose ids the visitor ticked; anything not on the field's
+ * configured list is dropped silently — the embed offers only what the field
+ * declares, so an unlisted id has to be an unusual client.
+ *
+ * The statement is the field's `statement` when set, else the field's label —
+ * the sentence shown above the checkboxes.
+ */
+export function readConsentGrants(
+  fields: readonly FormFieldRecord[],
+  answers: Answers,
+): readonly ConsentGrant[] {
+  const grants: ConsentGrant[] = []
+  for (const field of fields) {
+    if (field.consentPurposeIds.length === 0) continue
+    const statement = field.statement ?? field.label
+
+    // A `notice` field grants every configured purpose implicitly: the
+    // visitor's act of submitting the form is the consent, per the notice
+    // text they read. No answer to parse.
+    if (field.type === 'notice') {
+      for (const purposeId of field.consentPurposeIds) {
+        grants.push({
+          fieldId: field.id,
+          purposeId,
+          statement,
+          customLabel: '',
+        })
+      }
+      continue
+    }
+
+    if (field.type !== 'consent') continue
+    const ticked = parseConsentAnswer(answers[field.id])
+    if (ticked.length === 0) continue
+    const allowed = new Set(field.consentPurposeIds)
+    for (const purposeId of ticked) {
+      if (!allowed.has(purposeId)) continue
+      grants.push({
+        fieldId: field.id,
+        purposeId,
+        statement,
+        customLabel: field.consentPurposeLabels[purposeId] ?? '',
+      })
+    }
+  }
+  return grants
+}
+
+/** Splits a consent field's answer into the ticked purpose ids. */
+export function parseConsentAnswer(raw: string | undefined): readonly string[] {
+  if (raw === undefined) return []
+  const parts = raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+  return Array.from(new Set(parts))
+}
+
 /**
  * Everything wrong with an answer map, as `api.md` field details.
  *
@@ -88,6 +191,28 @@ export function findAnswerProblems(
   }
 
   for (const field of fields) {
+    // A consent field's answer is a comma-separated list of ticked purpose
+    // ids. Required means at least one must be ticked; unrequired means the
+    // list may be empty. Ids not on the field's own list are silently
+    // ignored on submit — the embed offers only what the field configures.
+    if (field.type === 'consent') {
+      const ticked = parseConsentAnswer(answers[field.id])
+      if (field.required && ticked.length === 0) {
+        problems.push({
+          field: `answers.${field.id}`,
+          message: `${field.label} needs at least one choice`,
+        })
+      }
+      continue
+    }
+
+    // A notice field carries no answer — its consent is implicit in the
+    // submission. `required` is meaningless on it. An answer sent for it is
+    // silently ignored; the mapper never reads it either.
+    if (field.type === 'notice') {
+      continue
+    }
+
     const value = answers[field.id]?.trim() ?? ''
 
     if (value.length === 0) {
@@ -144,13 +269,30 @@ export function readIntent(mapped: MappedAnswers): SubmitIntent | undefined {
     return undefined
   }
 
+  const firstName = mapped['person.first_name']
+  const lastName = mapped['person.last_name']
+  // A form that asks for a first and last name rather than one name box is the
+  // common arrangement, so the pair composes the display name. The address's
+  // local part stays the last resort it always was, for a form that asks for
+  // neither.
+  const composed = composeName({ firstName, lastName })
+
   return {
     email,
-    personName: mapped['person.name'] ?? email.split('@')[0] ?? email,
+    personName:
+      mapped['person.name'] ??
+      (composed.length > 0 ? composed : undefined) ??
+      email.split('@')[0] ??
+      email,
+    personFirstName: firstName,
+    personLastName: lastName,
     companyName: mapped['company.name'],
     companyDomain: resolveDomain(mapped),
     positionTitle: mapped['position.title'],
     dealName: mapped['deal.name'],
+    opportunityName: mapped['opportunity.name'],
+    partnershipName: mapped['partnership.name'],
+    enquiryName: mapped['enquiry.name'],
   }
 }
 
@@ -178,13 +320,14 @@ export function companyNameFrom(intent: SubmitIntent): string | undefined {
 }
 
 /**
- * Expands `{{company.name}}` and `{{person.name}}` in a deal name template.
+ * Expands `{{company.name}}` and `{{person.name}}` in a create-trigger name
+ * template. Shared by the deal, opportunity, and partnership triggers.
  *
  * 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.
+ * still produce a record with a name somebody can read on a board.
  */
-export function expandDealNameTemplate(
+export function expandNameTemplate(
   template: string,
   values: { readonly companyName: string; readonly personName: string },
 ): string {
@@ -193,6 +336,40 @@ export function expandDealNameTemplate(
     .replaceAll('{{person.name}}', values.personName.length > 0 ? values.personName : 'Lead')
 }
 
+/**
+ * The union merge for a form's tag actions. The stored order is preserved and
+ * new tags land at the end, so the timeline reads oldest-first. Never removes
+ * a tag a human set: `forms.md` §Tags is explicit on that.
+ *
+ * @returns The merged list, and `changed` = true when at least one new tag
+ *   landed. The caller uses `changed` to decide whether to emit an update
+ *   event, since a no-op merge should not publish `*.updated`.
+ */
+export function mergeTags(
+  stored: readonly string[],
+  inbound: readonly string[],
+): { readonly next: readonly string[]; readonly changed: boolean } {
+  const known = new Set(stored)
+  const additions: string[] = []
+
+  for (const tag of inbound) {
+    const trimmed = tag.trim()
+
+    if (trimmed.length === 0 || known.has(trimmed)) {
+      continue
+    }
+
+    known.add(trimmed)
+    additions.push(trimmed)
+  }
+
+  if (additions.length === 0) {
+    return { next: stored, changed: false }
+  }
+
+  return { next: [...stored, ...additions], changed: true }
+}
+
 /** How far ahead a deal created by a form is expected to close (`forms.md` rule 6). */
 export const DEAL_CLOSE_HORIZON_DAYS = 30
 

package/src/modules/forms/publicRoutes.ts

@@ -7,7 +7,10 @@ import { PUBLIC_ROUTE_PREFIX, readJsonBody, requestOrigin } from '../../lib/http
 import { requireCapability } from '../../runtime/entitlements.ts'
 import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
 import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
+import * as consentPurposesRepository from '../consent-purposes/repository.ts'
+import { findWorkspace } from '../workspace/repository.ts'
 import { embedContentSecurityPolicy, renderEmbedPage } from './embed.ts'
+import type { FormFieldRecord } from './repository.ts'
 import * as repository from './repository.ts'
 import type { FormSubmitService, SubmitOutcome } from './submission.ts'
 
@@ -35,6 +38,26 @@ export interface PublicFormRoutesDependencies {
   readonly entitlements: EntitlementRegistry
 }
 
+/**
+ * The purpose labels every consent field on this form points at, keyed by id.
+ * Renders the embed with the display label beside each checkbox rather than
+ * an opaque id. A purpose that has since been removed drops out of the map;
+ * `renderField` falls back to the id when it does, so a stale field stays
+ * visible but obviously off.
+ */
+async function loadConsentPurposeLabels(
+  db: Database,
+  workspaceId: string,
+  fields: readonly FormFieldRecord[],
+): Promise<ReadonlyMap<string, string>> {
+  const ids = Array.from(
+    new Set(fields.flatMap((field) => (field.type === 'consent' ? field.consentPurposeIds : []))),
+  )
+  if (ids.length === 0) return new Map()
+  const rows = await consentPurposesRepository.listPurposesByIds(db, workspaceId, ids)
+  return new Map(rows.map((row) => [row.id, row.label]))
+}
+
 function submitResponse(outcome: SubmitOutcome): Record<string, unknown> {
   // The upserted record ids stay off this response on purpose. The caller is an
   // unauthenticated website, and a Kelpie id is a ULID whose timestamp would tell
@@ -83,12 +106,31 @@ export function mountPublicFormRoutes(
     // module off does not serve its embed either.
     await requireCapability(dependencies.entitlements, form.workspaceId, moduleCapabilityName('forms'))
 
+    const workspace = await findWorkspace(dependencies.db, form.workspaceId)
+
+    if (workspace === undefined) {
+      throw AppError.notFound('Form not found')
+    }
+
+    // `view=page` is the standalone hosted URL (brand chrome). The default —
+    // and what iframe snippets load — is the bare embed: fields only.
+    const layout = context.req.query('view') === 'page' ? 'page' : 'embed'
+
     const nonce = generateNonce()
+    const fields = await repository.listFields(dependencies.db, form.id)
+    const consentPurposeLabels = await loadConsentPurposeLabels(
+      dependencies.db,
+      form.workspaceId,
+      fields,
+    )
     const page = renderEmbedPage({
       form,
-      fields: await repository.listFields(dependencies.db, form.id),
+      fields,
+      consentPurposeLabels,
       submitUrl: `${requestOrigin(context)}${PUBLIC_ROUTE_PREFIX}/forms/${publicKey}/submit`,
       nonce,
+      workspaceName: workspace.name,
+      layout,
     })
 
     context.header('Content-Security-Policy', embedContentSecurityPolicy(nonce))