@kelpie/schemas 0.7.0 → 0.9.0

package/src/form.ts

@@ -5,8 +5,15 @@ import {
   FORM_FIELD_TYPES,
   FORM_OPTION_VALUE_TYPES,
   FORM_STATUSES,
+  PIPELINE_KINDS,
+} from './values.ts'
+import type {
+  FormFieldMapTarget,
+  FormFieldType,
+  FormOptionValueType,
+  FormStatus,
+  PipelineKind,
 } from './values.ts'
-import type { FormFieldMapTarget, FormFieldType, FormOptionValueType, FormStatus } from './values.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
 import type { RecordTimestamps } from './wire.ts'
 
@@ -40,13 +47,46 @@ export interface FormField {
   /** Empty for every type but `select`. */
   readonly options: readonly FormFieldOption[]
   readonly placeholder: string | null
+  /**
+   * The intro sentence for a `consent` field — sits above the list of purpose
+   * checkboxes. `label` is the field heading; `statement` is what the visitor
+   * reads before ticking. Null for every other type.
+   */
+  readonly statement: string | null
+  /**
+   * Workspace consent purposes this `consent` field offers, in display order.
+   * Non-empty when `type === 'consent'`; empty otherwise. Each ticked box
+   * grants the purpose it belongs to; an unticked one is absence.
+   */
+  readonly consentPurposeIds: readonly string[]
+  /**
+   * Per-purpose override for the checkbox text, keyed by purpose id. Absent
+   * keys fall back to the workspace purpose's own label. Only the wording
+   * changes — the checkbox stays bound to its purpose.
+   */
+  readonly consentPurposeLabels: Readonly<Record<string, string>>
   /** Position in the form, contiguous from 0. The server renumbers on every write. */
   readonly sortOrder: number
 }
 
+/**
+ * One pre-existing pipeline record every submitter is linked into through
+ * `person_links`. `target_type` is fixed at form-write time; the row itself
+ * lives in `form_attach_targets` on the server.
+ */
+export interface FormAttachTarget {
+  readonly targetType: PipelineKind
+  readonly targetId: string
+}
+
 export interface Form extends RecordTimestamps {
   readonly id: string
   readonly name: string
+  /**
+   * Heading on the hosted/embed page. Defaults to `name` when the form is
+   * created; edit it from Settings without renaming the form in the CRM.
+   */
+  readonly title: string
   readonly description: string | null
   readonly status: FormStatus
   readonly fields: readonly FormField[]
@@ -56,6 +96,39 @@ export interface Form extends RecordTimestamps {
   readonly dealStageId: string | null
   /** Expands `{{company.name}}` and `{{person.name}}`. Null when `createDeal` is off. */
   readonly dealNameTemplate: string | null
+  readonly createOpportunity: boolean
+  /** Required when `createOpportunity` is on: opportunities carry a `kind`. */
+  readonly opportunityKind: string | null
+  readonly opportunityStageId: string | null
+  readonly opportunityNameTemplate: string | null
+  /** Null falls back to the workspace default member at submit time. */
+  readonly opportunityOwnerId: string | null
+  readonly createPartnership: boolean
+  /** Required when `createPartnership` is on. */
+  readonly partnershipKind: string | null
+  readonly partnershipStageId: string | null
+  readonly partnershipNameTemplate: string | null
+  /** Null falls back to the workspace default member at submit time. */
+  readonly partnershipOwnerId: string | null
+  readonly createEnquiry: boolean
+  /**
+   * Free-text label for the enquiry's `source` column. Optional: an unset value
+   * stores an empty string. Enquiry needs no `kind` because it has no `kind`
+   * column — a form's source is the source.
+   */
+  readonly enquirySource: string | null
+  readonly enquiryStageId: string | null
+  readonly enquiryNameTemplate: string | null
+  /** Null falls back to the workspace default member at submit time. */
+  readonly enquiryOwnerId: string | null
+  /** Tags to merge (union) into the resolved Person's `tags` on every submit. */
+  readonly personTags: readonly string[]
+  /** Tags to merge (union) into the resolved Company's `tags`; skipped when no company resolved. */
+  readonly companyTags: readonly string[]
+  /** Lists (person or company) every matching record is added to on submit. */
+  readonly listIds: readonly string[]
+  /** Pre-existing pipeline records the submitter is linked to via `person_links`. */
+  readonly attachTargets: readonly FormAttachTarget[]
   /**
    * The handle the public submit and embed endpoints resolve a workspace from.
    * Globally unique, and the only credential those endpoints take.
@@ -86,6 +159,9 @@ const formFieldSchema = z
     map_to: z.enum(FORM_FIELD_MAP_TARGETS),
     options: z.array(formFieldOptionSchema),
     placeholder: z.string().nullable(),
+    statement: z.string().nullable(),
+    consent_purpose_ids: z.array(idSchema),
+    consent_purpose_labels: z.record(z.string(), z.string()),
     sort_order: z.number().int(),
   })
   .transform(
@@ -97,14 +173,30 @@ const formFieldSchema = z
       mapTo: wire.map_to,
       options: wire.options,
       placeholder: wire.placeholder,
+      statement: wire.statement,
+      consentPurposeIds: wire.consent_purpose_ids,
+      consentPurposeLabels: wire.consent_purpose_labels,
       sortOrder: wire.sort_order,
     }),
   )
 
+const attachTargetSchema = z
+  .object({
+    target_type: z.enum(PIPELINE_KINDS),
+    target_id: idSchema,
+  })
+  .transform(
+    (wire): FormAttachTarget => ({
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+    }),
+  )
+
 export const formSchema: z.ZodType<Form, unknown> = z
   .object({
     id: idSchema,
     name: z.string(),
+    title: z.string(),
     description: z.string().nullable(),
     status: z.enum(FORM_STATUSES),
     fields: z.array(formFieldSchema),
@@ -112,6 +204,25 @@ export const formSchema: z.ZodType<Form, unknown> = z
     create_deal: z.boolean(),
     deal_stage_id: idSchema.nullable(),
     deal_name_template: z.string().nullable(),
+    create_opportunity: z.boolean(),
+    opportunity_kind: z.string().nullable(),
+    opportunity_stage_id: idSchema.nullable(),
+    opportunity_name_template: z.string().nullable(),
+    opportunity_owner_id: idSchema.nullable(),
+    create_partnership: z.boolean(),
+    partnership_kind: z.string().nullable(),
+    partnership_stage_id: idSchema.nullable(),
+    partnership_name_template: z.string().nullable(),
+    partnership_owner_id: idSchema.nullable(),
+    create_enquiry: z.boolean(),
+    enquiry_source: z.string().nullable(),
+    enquiry_stage_id: idSchema.nullable(),
+    enquiry_name_template: z.string().nullable(),
+    enquiry_owner_id: idSchema.nullable(),
+    person_tags: z.array(z.string()),
+    company_tags: z.array(z.string()),
+    list_ids: z.array(idSchema),
+    attach_targets: z.array(attachTargetSchema),
     public_key: z.string(),
     ...recordTimestamps,
   })
@@ -119,6 +230,7 @@ export const formSchema: z.ZodType<Form, unknown> = z
     (wire): Form => ({
       id: wire.id,
       name: wire.name,
+      title: wire.title,
       description: wire.description,
       status: wire.status,
       fields: wire.fields,
@@ -126,6 +238,25 @@ export const formSchema: z.ZodType<Form, unknown> = z
       createDeal: wire.create_deal,
       dealStageId: wire.deal_stage_id,
       dealNameTemplate: wire.deal_name_template,
+      createOpportunity: wire.create_opportunity,
+      opportunityKind: wire.opportunity_kind,
+      opportunityStageId: wire.opportunity_stage_id,
+      opportunityNameTemplate: wire.opportunity_name_template,
+      opportunityOwnerId: wire.opportunity_owner_id,
+      createPartnership: wire.create_partnership,
+      partnershipKind: wire.partnership_kind,
+      partnershipStageId: wire.partnership_stage_id,
+      partnershipNameTemplate: wire.partnership_name_template,
+      partnershipOwnerId: wire.partnership_owner_id,
+      createEnquiry: wire.create_enquiry,
+      enquirySource: wire.enquiry_source,
+      enquiryStageId: wire.enquiry_stage_id,
+      enquiryNameTemplate: wire.enquiry_name_template,
+      enquiryOwnerId: wire.enquiry_owner_id,
+      personTags: wire.person_tags,
+      companyTags: wire.company_tags,
+      listIds: wire.list_ids,
+      attachTargets: wire.attach_targets,
       publicKey: wire.public_key,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,
@@ -152,10 +283,18 @@ export interface FormFieldInput {
   readonly mapTo: FormFieldMapTarget
   readonly options?: readonly FormFieldOptionInput[]
   readonly placeholder?: string | null
+  /** The intro sentence above the list of consent checkboxes. */
+  readonly statement?: string | null
+  /** Non-empty for `consent` fields; each id becomes a checkbox 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 CreateFormInput {
   readonly name: string
+  /** Defaults to `name` when omitted. */
+  readonly title?: string
   readonly description?: string | null
   readonly status?: FormStatus
   readonly fields: readonly FormFieldInput[]
@@ -163,11 +302,34 @@ export interface CreateFormInput {
   readonly createDeal?: boolean
   readonly dealStageId?: string | null
   readonly dealNameTemplate?: string | null
+  readonly createOpportunity?: boolean
+  readonly opportunityKind?: string | null
+  readonly opportunityStageId?: string | null
+  readonly opportunityNameTemplate?: string | null
+  readonly opportunityOwnerId?: string | null
+  readonly createPartnership?: boolean
+  readonly partnershipKind?: string | null
+  readonly partnershipStageId?: string | null
+  readonly partnershipNameTemplate?: string | null
+  readonly partnershipOwnerId?: string | null
+  readonly createEnquiry?: boolean
+  readonly enquirySource?: string | null
+  readonly enquiryStageId?: string | null
+  readonly enquiryNameTemplate?: string | null
+  readonly enquiryOwnerId?: string | null
+  readonly personTags?: readonly string[]
+  readonly companyTags?: readonly string[]
+  readonly listIds?: readonly string[]
+  readonly attachTargets?: readonly FormAttachTarget[]
 }
 
-/** `fields` is absent or the whole list; there is no per-field patch. */
+/**
+ * `fields`, `list_ids`, and `attach_targets` are each absent or the whole list;
+ * there is no per-entry patch.
+ */
 export interface FormInput {
   readonly name?: string
+  readonly title?: string
   readonly description?: string | null
   readonly status?: FormStatus
   readonly fields?: readonly FormFieldInput[]
@@ -175,6 +337,25 @@ export interface FormInput {
   readonly createDeal?: boolean
   readonly dealStageId?: string | null
   readonly dealNameTemplate?: string | null
+  readonly createOpportunity?: boolean
+  readonly opportunityKind?: string | null
+  readonly opportunityStageId?: string | null
+  readonly opportunityNameTemplate?: string | null
+  readonly opportunityOwnerId?: string | null
+  readonly createPartnership?: boolean
+  readonly partnershipKind?: string | null
+  readonly partnershipStageId?: string | null
+  readonly partnershipNameTemplate?: string | null
+  readonly partnershipOwnerId?: string | null
+  readonly createEnquiry?: boolean
+  readonly enquirySource?: string | null
+  readonly enquiryStageId?: string | null
+  readonly enquiryNameTemplate?: string | null
+  readonly enquiryOwnerId?: string | null
+  readonly personTags?: readonly string[]
+  readonly companyTags?: readonly string[]
+  readonly listIds?: readonly string[]
+  readonly attachTargets?: readonly FormAttachTarget[]
 }
 
 function fieldBody(field: FormFieldInput): Record<string, unknown> {
@@ -187,12 +368,20 @@ function fieldBody(field: FormFieldInput): Record<string, unknown> {
       definedFields({ key: option.key, value: option.value, value_type: option.valueType }),
     ),
     placeholder: field.placeholder,
+    statement: field.statement,
+    consent_purpose_ids: field.consentPurposeIds,
+    consent_purpose_labels: field.consentPurposeLabels,
   })
 }
 
+function attachTargetBody(target: FormAttachTarget): Record<string, unknown> {
+  return { target_type: target.targetType, target_id: target.targetId }
+}
+
 export function createFormBody(input: CreateFormInput): Record<string, unknown> {
   return definedFields({
     name: input.name,
+    title: input.title,
     description: input.description,
     status: input.status,
     fields: input.fields.map(fieldBody),
@@ -200,12 +389,32 @@ export function createFormBody(input: CreateFormInput): Record<string, unknown>
     create_deal: input.createDeal,
     deal_stage_id: input.dealStageId,
     deal_name_template: input.dealNameTemplate,
+    create_opportunity: input.createOpportunity,
+    opportunity_kind: input.opportunityKind,
+    opportunity_stage_id: input.opportunityStageId,
+    opportunity_name_template: input.opportunityNameTemplate,
+    opportunity_owner_id: input.opportunityOwnerId,
+    create_partnership: input.createPartnership,
+    partnership_kind: input.partnershipKind,
+    partnership_stage_id: input.partnershipStageId,
+    partnership_name_template: input.partnershipNameTemplate,
+    partnership_owner_id: input.partnershipOwnerId,
+    create_enquiry: input.createEnquiry,
+    enquiry_source: input.enquirySource,
+    enquiry_stage_id: input.enquiryStageId,
+    enquiry_name_template: input.enquiryNameTemplate,
+    enquiry_owner_id: input.enquiryOwnerId,
+    person_tags: input.personTags,
+    company_tags: input.companyTags,
+    list_ids: input.listIds,
+    attach_targets: input.attachTargets?.map(attachTargetBody),
   })
 }
 
 export function formBody(input: FormInput): Record<string, unknown> {
   return definedFields({
     name: input.name,
+    title: input.title,
     description: input.description,
     status: input.status,
     fields: input.fields?.map(fieldBody),
@@ -213,5 +422,24 @@ export function formBody(input: FormInput): Record<string, unknown> {
     create_deal: input.createDeal,
     deal_stage_id: input.dealStageId,
     deal_name_template: input.dealNameTemplate,
+    create_opportunity: input.createOpportunity,
+    opportunity_kind: input.opportunityKind,
+    opportunity_stage_id: input.opportunityStageId,
+    opportunity_name_template: input.opportunityNameTemplate,
+    opportunity_owner_id: input.opportunityOwnerId,
+    create_partnership: input.createPartnership,
+    partnership_kind: input.partnershipKind,
+    partnership_stage_id: input.partnershipStageId,
+    partnership_name_template: input.partnershipNameTemplate,
+    partnership_owner_id: input.partnershipOwnerId,
+    create_enquiry: input.createEnquiry,
+    enquiry_source: input.enquirySource,
+    enquiry_stage_id: input.enquiryStageId,
+    enquiry_name_template: input.enquiryNameTemplate,
+    enquiry_owner_id: input.enquiryOwnerId,
+    person_tags: input.personTags,
+    company_tags: input.companyTags,
+    list_ids: input.listIds,
+    attach_targets: input.attachTargets?.map(attachTargetBody),
   })
 }

package/src/formSubmission.ts

@@ -1,7 +1,26 @@
 import { z } from 'zod'
 
+import { FORM_ACTION_STATUSES } from './values.ts'
+import type { FormActionStatus } from './values.ts'
 import { idSchema, timestampSchema } from './wire.ts'
 
+/**
+ * The record types a submission can name through its FK columns. Used by
+ * `GET /v1/form-submissions?target_type=…` so the query, the server, and the
+ * UI hook agree on the seven values.
+ */
+export const FORM_SUBMISSION_LINK_TARGETS = [
+  'person',
+  'company',
+  'position',
+  'deal',
+  'opportunity',
+  'partnership',
+  'enquiry',
+] as const
+
+export type FormSubmissionLinkTarget = (typeof FORM_SUBMISSION_LINK_TARGETS)[number]
+
 /**
  * Wire shape for `/v1/forms/:id/submissions`, and for what the public submit
  * endpoint answers with.
@@ -11,6 +30,19 @@ import { idSchema, timestampSchema } from './wire.ts'
  * submission) and no update at all.
  */
 
+/**
+ * One post-submit action's outcome. The submission's `actionLog` carries these
+ * in the order the runner attempted them, so a reader can see what ran, what
+ * was skipped, and what rolled back.
+ */
+export interface FormSubmissionActionEntry {
+  /** A machine name for the action ('create_deal', 'tag_person', 'add_list'…). */
+  readonly action: string
+  readonly status: FormActionStatus
+  /** Human-readable message. Never a stack trace; safe for the Submissions UI. */
+  readonly detail: string
+}
+
 export interface FormSubmission {
   readonly id: string
   readonly formId: string
@@ -26,9 +58,32 @@ export interface FormSubmission {
   readonly companyId: string | null
   readonly positionId: string | null
   readonly dealId: string | null
+  readonly opportunityId: string | null
+  readonly partnershipId: string | null
+  readonly enquiryId: string | null
+  /**
+   * Per-action outcome from the post-submit runner, in the order attempted.
+   * Only actions the form was configured to run appear; a form with no
+   * post-actions has an empty log.
+   */
+  readonly actionLog: readonly FormSubmissionActionEntry[]
   readonly createdAt: Date
 }
 
+const actionEntrySchema = z
+  .object({
+    action: z.string(),
+    status: z.enum(FORM_ACTION_STATUSES),
+    detail: z.string(),
+  })
+  .transform(
+    (wire): FormSubmissionActionEntry => ({
+      action: wire.action,
+      status: wire.status,
+      detail: wire.detail,
+    }),
+  )
+
 export const formSubmissionSchema: z.ZodType<FormSubmission, unknown> = z
   .object({
     id: idSchema,
@@ -39,6 +94,10 @@ export const formSubmissionSchema: z.ZodType<FormSubmission, unknown> = z
     company_id: idSchema.nullable(),
     position_id: idSchema.nullable(),
     deal_id: idSchema.nullable(),
+    opportunity_id: idSchema.nullable(),
+    partnership_id: idSchema.nullable(),
+    enquiry_id: idSchema.nullable(),
+    action_log: z.array(actionEntrySchema),
     created_at: timestampSchema,
   })
   .transform(
@@ -51,6 +110,10 @@ export const formSubmissionSchema: z.ZodType<FormSubmission, unknown> = z
       companyId: wire.company_id,
       positionId: wire.position_id,
       dealId: wire.deal_id,
+      opportunityId: wire.opportunity_id,
+      partnershipId: wire.partnership_id,
+      enquiryId: wire.enquiry_id,
+      actionLog: wire.action_log,
       createdAt: wire.created_at,
     }),
   )

package/src/importExport.ts

@@ -115,12 +115,22 @@ export interface CsvColumn {
   /**
    * A column an import may map but an export never writes.
    *
-   * The People affiliation columns are the only ones: a person can hold many
-   * positions, so a single company and title on the person row would be lossy on
-   * the way out. They map on the way in to drive a Position, and the export and
-   * template leave them out. See `headersFor`.
+   * The People affiliation columns are the original example: a person can hold
+   * many positions, so a single company and title on the person row would be
+   * lossy on the way out. They map on the way in to drive a Position, and the
+   * export and template leave them out. The consent grant columns follow the
+   * same rule — a person's consent state is exported serialised in `consents`,
+   * not row-by-row per purpose. See `headersFor`.
    */
   readonly importOnly?: boolean
+  /**
+   * A column an export writes but an import never maps. `do_not_contact` and
+   * the serialised `consents` list are exported for readability; consent
+   * round-trips through `consent_status` / `consent_at` plus the job's
+   * `consent_purpose_id`, and `do_not_contact` is a Person patch, not part of
+   * an import job.
+   */
+  readonly exportOnly?: boolean
 }
 
 /**
@@ -133,11 +143,19 @@ export interface CsvColumn {
  * still carry `company_domain`, `company_name` and `title`, which drive a
  * Position for the person rather than a field on them. Those three are
  * `importOnly`, so an export and a template leave them out.
+ *
+ * A People row still has to name its person, but `name` is not marked `required`
+ * here: the row satisfies it with `name`, or with `first_name` / `last_name` for
+ * the name to be composed from. `required` is a per-column flag and that is a
+ * statement about a pair of them, so the rule lives in the People row check
+ * instead. Every CRM worth migrating from exports first and last name in their
+ * own columns and most export no full name at all, which is the case this
+ * exists for.
  */
 export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>> = {
   companies: [
     { key: 'name', label: 'Name', required: true },
-    { key: 'domain', label: 'Domain', required: true },
+    { key: 'domain', label: 'Domain', required: false },
     { key: 'industry', label: 'Industry', required: false },
     { key: 'stage', label: 'Stage', required: false },
     { key: 'size_band', label: 'Size band', required: false },
@@ -150,7 +168,11 @@ export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>
     { key: 'hq', label: 'HQ', required: false },
   ],
   people: [
-    { key: 'name', label: 'Name', required: true },
+    { key: 'name', label: 'Name', required: false },
+    { key: 'salutation', label: 'Salutation', required: false },
+    { key: 'first_name', label: 'First name', required: false },
+    { key: 'last_name', label: 'Last name', required: false },
+    { key: 'suffix', label: 'Suffix', required: false },
     { key: 'email', label: 'Email', required: true },
     { key: 'timezone', label: 'Timezone', required: false },
     { key: 'location', label: 'Location', required: false },
@@ -160,9 +182,18 @@ export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>
     { key: 'summary', label: 'Summary', required: false },
     { key: 'tags', label: 'Tags', required: false },
     { key: 'phones', label: 'Phones', required: false },
+    { key: 'do_not_contact', label: 'Do not contact', required: false, exportOnly: true },
+    { key: 'consents', label: 'Consents', required: false, exportOnly: true },
     { key: 'company_domain', label: 'Company domain', required: false, importOnly: true },
     { key: 'company_name', label: 'Company name', required: false, importOnly: true },
     { key: 'title', label: 'Title', required: false, importOnly: true },
+    /**
+     * Consent grant to write for the job's purpose. `granted` or `withdrawn`.
+     * Mapping either column with no `consent_purpose_id` set on the job is a
+     * `422` — the writer would not know which purpose the row is for.
+     */
+    { key: 'consent_status', label: 'Consent status', required: false, importOnly: true },
+    { key: 'consent_at', label: 'Consent at', required: false, importOnly: true },
   ],
   positions: [
     { key: 'person_email', label: 'Person email', required: true },
@@ -298,6 +329,12 @@ export interface ImportJob extends RecordTimestamps {
   readonly onMissingCompany: OnMissingCompany
   readonly matchKey: string
   readonly columnMap: ImportColumnMap
+  /**
+   * The consent purpose a People import grants (or withdraws) for each row
+   * that carries a `consent_status`. Required whenever the map names
+   * `consent_status` or `consent_at`. Null for every other object.
+   */
+  readonly consentPurposeId: string | null
   /** The headers as they appeared in the uploaded file, in file order. */
   readonly sourceHeaders: readonly string[]
   readonly fileName: string | null
@@ -348,6 +385,7 @@ export const importJobSchema: z.ZodType<ImportJob, unknown> = z
     on_missing_company: z.enum(ON_MISSING_COMPANY),
     match_key: z.string(),
     column_map: z.record(z.string(), z.string().nullable()),
+    consent_purpose_id: idSchema.nullable(),
     source_headers: z.array(z.string()),
     file_name: z.string().nullable(),
     counts: countsSchema,
@@ -366,6 +404,7 @@ export const importJobSchema: z.ZodType<ImportJob, unknown> = z
       onMissingCompany: wire.on_missing_company,
       matchKey: wire.match_key,
       columnMap: wire.column_map,
+      consentPurposeId: wire.consent_purpose_id,
       sourceHeaders: wire.source_headers,
       fileName: wire.file_name,
       counts: wire.counts,