@kelpie/server 0.10.0 → 0.11.0

package/src/modules/forms/fields.ts

@@ -1,7 +1,14 @@
+import {
+  isCompatibleFormFieldType,
+  isKnownMapTarget,
+  isRepeatableMapTarget,
+} from '@kelpie/schemas'
+import type { CustomFieldDefinitionRef, FormFieldType } from '@kelpie/schemas'
+
 import type { ErrorDetail } from '../../lib/errors.ts'
 import type { StoredFormFieldOption } from './schema.ts'
 import { PERSON_EMAIL_TARGET } from './schema.ts'
-import type { FormFieldMapTarget, FormFieldType, FormOptionValueType } from './schema.ts'
+import type { FormFieldMapTarget, FormOptionValueType } from './schema.ts'
 
 /** The map target for a consent field. Repeatable, unique per purpose_id. */
 const PERSON_CONSENT_TARGET = 'person.consent'
@@ -40,15 +47,18 @@ export interface OptionDraft {
 /**
  * Targets a form may map more than one field to.
  *
- * Only `submission`, which writes no CRM field and so has nothing to collide
- * over. Two fields both mapped to `person.name` would leave the submit picking
- * one of them by field order, which is not a decision a form author made.
+ * `submission` writes no CRM field; `person.consent` is read separately per
+ * purpose. Everything else is unique per form.
  */
-const REPEATABLE_TARGETS: ReadonlySet<string> = new Set(['submission'])
 
 /** The two targets that establish a company for a submit to attach a Deal to. */
 const COMPANY_TARGETS: readonly string[] = ['company.name', 'company.domain']
 
+export interface FindFieldProblemsOptions {
+  readonly createsPartnership?: boolean
+  readonly customFieldDefinitions?: readonly CustomFieldDefinitionRef[]
+}
+
 /**
  * Everything wrong with a field list, as `api.md` field details.
  *
@@ -69,11 +79,13 @@ const COMPANY_TARGETS: readonly string[] = ['company.name', 'company.domain']
 export function findFieldProblems(
   fields: readonly FieldShape[],
   createsDeal: boolean,
-  createsPartnership = false,
+  options: FindFieldProblemsOptions = {},
 ): readonly ErrorDetail[] {
   const problems: ErrorDetail[] = []
   const seenTargets = new Set<string>()
   const usedConsentPurposes = new Set<string>()
+  const customFieldDefinitions = options.customFieldDefinitions ?? []
+  const createsPartnership = options.createsPartnership ?? false
 
   if (!fields.some((field) => field.mapTo === PERSON_EMAIL_TARGET)) {
     problems.push({
@@ -101,6 +113,18 @@ export function findFieldProblems(
   for (const [index, field] of fields.entries()) {
     const at = `fields.${String(index)}`
 
+    if (!isKnownMapTarget(field.mapTo, customFieldDefinitions)) {
+      problems.push({ field: `${at}.map_to`, message: `Unknown map target ${field.mapTo}` })
+    } else if (
+      field.mapTo !== PERSON_CONSENT_TARGET &&
+      !isCompatibleFormFieldType(field.type as FormFieldType, field.mapTo, customFieldDefinitions)
+    ) {
+      problems.push({
+        field: `${at}.type`,
+        message: `A ${field.type} field cannot map to ${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
@@ -153,7 +177,7 @@ export function findFieldProblems(
         field: `${at}.map_to`,
         message: 'A consent or notice field must map to person.consent',
       })
-    } else if (!REPEATABLE_TARGETS.has(field.mapTo)) {
+    } else if (!isRepeatableMapTarget(field.mapTo)) {
       if (seenTargets.has(field.mapTo)) {
         problems.push({ field: `${at}.map_to`, message: `Another field already maps to ${field.mapTo}` })
       }

package/src/modules/forms/mapping.ts

@@ -4,7 +4,6 @@ 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
@@ -19,7 +18,7 @@ import type { FormFieldMapTarget } from './schema.ts'
 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>>
+export type MappedAnswers = Record<string, string>
 
 /**
  * What a submit will write, once the blanks are known.
@@ -40,6 +39,8 @@ export interface SubmitIntent {
   /** The `person.first_name` answer only. Never split out of `personName`. */
   readonly personFirstName: string | undefined
   readonly personLastName: string | undefined
+  /** The `person.phones` answer only. Written when the person's phone list is empty. */
+  readonly personPhone: string | undefined
   readonly companyName: string | undefined
   /** The `company.domain` answer only. Never derived from the address; see `resolveDomain`. */
   readonly companyDomain: string | undefined
@@ -99,7 +100,7 @@ export function mapAnswers(fields: readonly FormFieldRecord[], answers: Answers)
       continue
     }
 
-    mapped[field.mapTo as FormFieldMapTarget] = value
+    mapped[field.mapTo] = value
   }
 
   return mapped
@@ -286,6 +287,7 @@ export function readIntent(mapped: MappedAnswers): SubmitIntent | undefined {
       email,
     personFirstName: firstName,
     personLastName: lastName,
+    personPhone: mapped['person.phones'],
     companyName: mapped['company.name'],
     companyDomain: resolveDomain(mapped),
     positionTitle: mapped['position.title'],
@@ -314,6 +316,21 @@ export function fillBlank(stored: string | null, inbound: string | undefined): s
   return stored === null || stored.trim().length === 0 ? inbound : undefined
 }
 
+/**
+ * The merge rule for `person.phones`: fill when the stored list is empty, never
+ * append to a list the team has already set.
+ */
+export function fillPhonesBlank(
+  stored: readonly string[],
+  inbound: string | undefined,
+): readonly string[] | undefined {
+  if (inbound === undefined || inbound.length === 0) {
+    return undefined
+  }
+
+  return stored.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

package/src/modules/forms/repository.ts

@@ -296,11 +296,6 @@ export async function insertSubmission(
 export interface FormListRow {
   readonly listId: string
   readonly targetType: RecordTargetType
-  /**
-   * When the list has a consent purpose, form-driven adds capture consent
-   * against it. Carried through so submission.ts needs no second query.
-   */
-  readonly consentPurposeId: string | null
 }
 
 export async function listFormLists(db: Queryable, formId: string): Promise<FormListRow[]> {
@@ -308,7 +303,6 @@ export async function listFormLists(db: Queryable, formId: string): Promise<Form
     .select({
       listId: formLists.listId,
       targetType: lists.targetType,
-      consentPurposeId: lists.consentPurposeId,
     })
     .from(formLists)
     .innerJoin(lists, eq(lists.id, formLists.listId))
@@ -318,7 +312,6 @@ export async function listFormLists(db: Queryable, formId: string): Promise<Form
   return rows.map((row) => ({
     listId: row.listId,
     targetType: row.targetType as RecordTargetType,
-    consentPurposeId: row.consentPurposeId,
   }))
 }
 

package/src/modules/forms/routes.ts

@@ -17,7 +17,6 @@ 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,
@@ -51,7 +50,7 @@ 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),
+  map_to: z.string().min(1),
   options: z.array(optionBody).default([]),
   placeholder: z.string().nullable().default(null),
   statement: z.string().nullable().default(null),

package/src/modules/forms/schema.ts

@@ -1,5 +1,4 @@
 import {
-  FORM_FIELD_MAP_TARGETS,
   FORM_FIELD_TYPES,
   FORM_STATUSES,
   PIPELINE_KINDS,
@@ -250,7 +249,6 @@ export const formFields = pgTable(
   (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),
   ],
 )
 

package/src/modules/forms/service.ts

@@ -1,3 +1,4 @@
+import type { CustomFieldDefinitionRef, CustomFieldObjectType, CustomFieldType } from '@kelpie/schemas'
 import type {
   FormAttachTarget,
   FormSubmissionLinkTarget,
@@ -18,6 +19,8 @@ import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import * as consentPurposesRepository from '../consent-purposes/repository.ts'
+import * as customFieldsRepository from '../custom-fields/repository.ts'
+import { CUSTOM_FIELD_OBJECT_TYPES } from '../custom-fields/schema.ts'
 import * as listsRepository from '../lists/repository.ts'
 import * as pipelineRepository from '../pipelines/repository.ts'
 import { missingTargets } from '../recordTargets.ts'
@@ -328,18 +331,42 @@ export function createFormsService(dependencies: FormsDependencies): FormsServic
   /**
    * @throws AppError 422 listing every problem with the field list at once.
    */
-  function requireUsableFields(
+  async function requireUsableFields(
+    workspaceId: string,
     fields: readonly FieldShape[],
     createsDeal: boolean,
     createsPartnership: boolean,
-  ): void {
-    const problems = findFieldProblems(fields, createsDeal, createsPartnership)
+  ): Promise<void> {
+    const customFieldDefinitions = await loadCustomFieldDefinitions(workspaceId)
+    const problems = findFieldProblems(fields, createsDeal, {
+      createsPartnership,
+      customFieldDefinitions,
+    })
 
     if (problems.length > 0) {
       throw AppError.validationFailed('That field list cannot process a submission', problems)
     }
   }
 
+  async function loadCustomFieldDefinitions(
+    workspaceId: string,
+  ): Promise<readonly CustomFieldDefinitionRef[]> {
+    const rows = await Promise.all(
+      CUSTOM_FIELD_OBJECT_TYPES.map((objectType) =>
+        customFieldsRepository.definitionsForObject(dependencies.db, workspaceId, objectType),
+      ),
+    )
+
+    return rows.flat().map(
+      (row): CustomFieldDefinitionRef => ({
+        objectType: row.objectType as CustomFieldObjectType,
+        key: row.key,
+        label: row.label,
+        type: row.type as CustomFieldType,
+      }),
+    )
+  }
+
   /**
    * The lists an action-configured form names must exist in this workspace and
    * target `person` or `company`. A list of another target type would never
@@ -479,7 +506,7 @@ export function createFormsService(dependencies: FormsDependencies): FormsServic
     workspaceId: string,
     state: ResultingState,
   ): Promise<void> {
-    requireUsableFields(state.fields, state.createDeal, state.createPartnership)
+    await requireUsableFields(workspaceId, state.fields, state.createDeal, state.createPartnership)
     await requireConsentPurposes(workspaceId, state.fields)
     await requireActionLists(workspaceId, state.listIds)
     await requireAttachTargets(workspaceId, state.attachTargets)

package/src/modules/forms/starters.ts

@@ -0,0 +1,129 @@
+import type { FormFieldMapTarget, FormFieldType } from '@kelpie/schemas'
+
+/**
+ * The forms a new workspace starts with. Data, not migrations: a workspace
+ * owner may rename, pause, or delete them, and add any others they need.
+ *
+ * Consent fields name a purpose by slug; `seedStarterForms` resolves those to
+ * the ids assigned when `STARTER_CONSENT_PURPOSES` is inserted.
+ */
+
+export type StarterFormSlug = 'contact' | 'newsletter'
+
+export type StarterConsentPurposeSlug = 'contact' | 'marketing'
+
+export type StarterListSlug = 'newsletter'
+
+export interface StarterFormField {
+  readonly label: string
+  readonly type: FormFieldType
+  readonly required: boolean
+  readonly mapTo: FormFieldMapTarget
+  readonly placeholder?: string | null
+  readonly statement?: string
+  readonly consentPurposeSlug?: StarterConsentPurposeSlug
+}
+
+export interface StarterForm {
+  readonly slug: StarterFormSlug
+  readonly name: string
+  readonly title: string
+  readonly description: string
+  readonly thankYouMessage: string
+  readonly linkedListSlug?: StarterListSlug
+  readonly fields: readonly StarterFormField[]
+}
+
+export const STARTER_FORMS: readonly StarterForm[] = [
+  {
+    slug: 'contact',
+    name: 'Contact',
+    title: 'Contact us',
+    description: 'General enquiries from your website.',
+    thankYouMessage: 'Thanks. We will be in touch.',
+    fields: [
+      {
+        label: 'Name',
+        type: 'text',
+        required: true,
+        mapTo: 'person.name',
+        placeholder: 'Your name',
+      },
+      {
+        label: 'Email',
+        type: 'email',
+        required: true,
+        mapTo: 'person.email',
+        placeholder: 'you@company.com',
+      },
+      {
+        label: 'Job title',
+        type: 'text',
+        required: false,
+        mapTo: 'position.title',
+        placeholder: 'Your role',
+      },
+      {
+        label: 'Company',
+        type: 'text',
+        required: false,
+        mapTo: 'company.name',
+        placeholder: 'Company name',
+      },
+      {
+        label: 'Phone',
+        type: 'text',
+        required: false,
+        mapTo: 'person.phones',
+        placeholder: 'Phone number',
+      },
+      {
+        label: 'Message',
+        type: 'textarea',
+        required: false,
+        mapTo: 'submission',
+        placeholder: 'How can we help?',
+      },
+      {
+        label: 'Consent',
+        type: 'consent',
+        required: true,
+        mapTo: 'person.consent',
+        statement: 'Please tell us how we can contact you about your enquiry.',
+        consentPurposeSlug: 'contact',
+      },
+    ],
+  },
+  {
+    slug: 'newsletter',
+    name: 'Newsletter',
+    title: 'Newsletter signup',
+    description: 'Subscribe to product updates and campaigns.',
+    thankYouMessage: 'Thanks for subscribing.',
+    linkedListSlug: 'newsletter',
+    fields: [
+      {
+        label: 'Name',
+        type: 'text',
+        required: false,
+        mapTo: 'person.name',
+        placeholder: 'Your name',
+      },
+      {
+        label: 'Email',
+        type: 'email',
+        required: true,
+        mapTo: 'person.email',
+        placeholder: 'you@company.com',
+      },
+      {
+        label: 'Consent',
+        type: 'consent',
+        required: true,
+        mapTo: 'person.consent',
+        statement: 'Please confirm you want to hear from us.',
+        consentPurposeSlug: 'marketing',
+      },
+    ],
+  },
+]