@kelpie/server 0.7.0 → 0.9.0

package/src/modules/import-export/drafts.ts

@@ -6,6 +6,7 @@ import {
   PREFERRED_CHANNELS,
   RELATIONSHIP_LEVELS,
   SIZE_BANDS,
+  composeName,
 } from '@kelpie/schemas'
 
 import { normaliseDomain, normaliseEmail } from '../../lib/normalisation.ts'
@@ -43,6 +44,10 @@ export interface CompanyDraft {
 
 export interface PersonDraft {
   readonly name?: string
+  readonly salutation?: string
+  readonly firstName?: string
+  readonly lastName?: string
+  readonly suffix?: string
   readonly email?: string
   readonly phones?: readonly string[]
   readonly timezone?: string
@@ -157,11 +162,25 @@ export function companyDraft(mapped: Readonly<Record<string, string>>): CompanyD
   })
 }
 
+/**
+ * `name` falls back to the first and last name cells, because most CRMs export
+ * those two and no full name at all. Composed only when the row's own `name` is
+ * blank, and never the other way round: a `name` cell is never split to fill
+ * `first_name`, since a guessed part is stored exactly like one somebody typed.
+ */
 export function personDraft(mapped: Readonly<Record<string, string>>): PersonDraft {
   const email = text(mapped, 'email')
+  const firstName = text(mapped, 'first_name')
+  const lastName = text(mapped, 'last_name')
+  const suffix = text(mapped, 'suffix')
+  const composed = composeName({ firstName, lastName, suffix })
 
   return present<PersonDraft>({
-    name: text(mapped, 'name'),
+    name: text(mapped, 'name') ?? (composed.length > 0 ? composed : undefined),
+    salutation: text(mapped, 'salutation'),
+    firstName,
+    lastName,
+    suffix,
     email: email === undefined ? undefined : (normaliseEmail(email) ?? undefined),
     phones: list(mapped, 'phones'),
     timezone: text(mapped, 'timezone'),

package/src/modules/import-export/exportRows.ts

@@ -30,13 +30,23 @@ function joinList(values: readonly string[]): string {
  * The header row of an export and of a template.
  *
  * `importOnly` columns are left out: a People import may map `company_domain`,
- * `company_name` and `title` to drive a Position, but a person holds many
- * positions and none of them is a field on the person. Writing one on the export
- * would be lossy, so the export and the template carry the round-trippable
- * columns only, and each cell function matches this order one for one.
+ * `company_name`, `title`, `consent_status`, and `consent_at` to drive extra
+ * writes, but none is a field on the person row. A template also leaves out
+ * `exportOnly` columns (`do_not_contact`, `consents`), which the export writes
+ * for readability but a caller round-trips through the per-purpose columns and
+ * `consent_purpose_id` on the job.
  */
 export function headersFor(object: ImportObject): readonly string[] {
-  return OBJECT_COLUMNS[object].filter((column) => column.importOnly !== true).map((column) => column.key)
+  return OBJECT_COLUMNS[object]
+    .filter((column) => column.importOnly !== true)
+    .map((column) => column.key)
+}
+
+/** The template's headers — the round-trippable ones for a caller to fill in. */
+export function templateHeadersFor(object: ImportObject): readonly string[] {
+  return OBJECT_COLUMNS[object]
+    .filter((column) => column.importOnly !== true && column.exportOnly !== true)
+    .map((column) => column.key)
 }
 
 export function companyCells(row: ExportCompanyRow): readonly string[] {
@@ -59,6 +69,10 @@ export function companyCells(row: ExportCompanyRow): readonly string[] {
 export function personCells(row: ExportPersonRow): readonly string[] {
   return [
     row.name,
+    row.salutation ?? '',
+    row.firstName ?? '',
+    row.lastName ?? '',
+    row.suffix ?? '',
     row.email ?? '',
     row.timezone ?? '',
     row.location ?? '',
@@ -68,6 +82,8 @@ export function personCells(row: ExportPersonRow): readonly string[] {
     row.summary,
     joinList(row.tags),
     joinList(row.phones),
+    row.doNotContact ? 'true' : 'false',
+    row.consents,
   ]
 }
 

package/src/modules/import-export/plan.ts

@@ -1,4 +1,5 @@
 import type {
+  ConsentStatus,
   ImportConflictMode,
   ImportCounts,
   ImportObject,
@@ -44,6 +45,8 @@ export interface PlanContext {
   readonly conflictMode: ImportConflictMode
   /** What a People row does with an absent company. Ignored by the other objects. */
   readonly onMissingCompany: OnMissingCompany
+  /** The consent purpose the job grants for each row's consent_status. Null when not set. */
+  readonly consentPurposeId: string | null
   readonly lookups: ImportLookups
 }
 
@@ -55,6 +58,14 @@ export type PlannedAffiliation =
   | { readonly kind: 'link'; readonly companyId: string; readonly title: string }
   | { readonly kind: 'create'; readonly company: CompanyDraft; readonly title: string }
 
+/** A consent write that rides with a People row when the job has a purpose. */
+export interface ImportConsentGrant {
+  readonly purposeId: string
+  readonly status: ConsentStatus
+  /** ISO date from the `consent_at` column; null when the column is unmapped or blank. */
+  readonly notedAt: string | null
+}
+
 /** The values a write applies, once every reference in the row has been resolved. */
 export type ImportWrite =
   | { readonly object: 'companies'; readonly draft: CompanyDraft }
@@ -63,6 +74,8 @@ export type ImportWrite =
       readonly draft: PersonDraft
       /** A position to upsert alongside the person, when the row named a company and a title. */
       readonly affiliation?: PlannedAffiliation
+      /** Consent to grant against the job's purpose. Absent when consent_status is blank. */
+      readonly consent?: ImportConsentGrant
     }
   | {
       readonly object: 'positions'
@@ -249,8 +262,18 @@ function resolveWrite(context: PlanContext, mapped: Readonly<Record<string, stri
   switch (context.object) {
     case 'companies':
       return { object: 'companies', draft: companyDraft(mapped) }
-    case 'people':
-      return { object: 'people', draft: personDraft(mapped) }
+    case 'people': {
+      const write: {
+        object: 'people'
+        draft: PersonDraft
+        consent?: ImportConsentGrant
+      } = { object: 'people', draft: personDraft(mapped) }
+      const consent = readConsentGrant(context, mapped)
+      if (consent !== undefined) {
+        write.consent = consent
+      }
+      return write
+    }
     case 'positions':
       return planPosition(context, mapped)
     case 'deals':
@@ -258,6 +281,28 @@ function resolveWrite(context: PlanContext, mapped: Readonly<Record<string, stri
   }
 }
 
+/**
+ * The consent grant a People row carries. Absent unless the job has a purpose
+ * set on it AND the row has a non-blank `consent_status`. `validateRow` has
+ * already refused an unknown status by the time this runs, so the coercion
+ * below is safe.
+ */
+function readConsentGrant(
+  context: PlanContext,
+  mapped: Readonly<Record<string, string>>,
+): ImportConsentGrant | undefined {
+  if (context.consentPurposeId === null) return undefined
+  const rawStatus = (mapped.consent_status ?? '').trim().toLowerCase()
+  if (rawStatus.length === 0) return undefined
+  if (rawStatus !== 'granted' && rawStatus !== 'withdrawn') return undefined
+  const rawAt = (mapped.consent_at ?? '').trim()
+  return {
+    purposeId: context.consentPurposeId,
+    status: rawStatus as ConsentStatus,
+    notedAt: rawAt.length === 0 ? null : rawAt,
+  }
+}
+
 /**
  * The company affiliation a People row asks for, if any, and any note about it.
  *

package/src/modules/import-export/presets.ts

@@ -27,7 +27,12 @@ export const SOURCE_PRESETS: Readonly<Record<ImportSource, SourcePreset>> = {
       description: 'Description',
     },
     people: {
+      // Both, because a HubSpot contact export carries the parts and often no
+      // full name at all. A preset header the file does not have falls through
+      // to the exact-key match below, so mapping all three costs a file nothing.
       name: 'Full Name',
+      first_name: 'First Name',
+      last_name: 'Last Name',
       email: 'Email',
       phones: 'Phone Number',
       location: 'City',
@@ -59,10 +64,15 @@ export const SOURCE_PRESETS: Readonly<Record<ImportSource, SourcePreset>> = {
     },
     people: {
       name: 'Full Name',
+      salutation: 'Salutation',
+      first_name: 'First Name',
+      last_name: 'Last Name',
       email: 'Email',
       phones: 'Phone',
       location: 'Mailing City',
       company_name: 'Account Name',
+      // Salesforce's Contact.Title is the job title, and a job title is a
+      // Position. It is not this object's `suffix`, which stays unmapped.
       title: 'Title',
     },
     positions: {

package/src/modules/import-export/repository.ts

@@ -3,8 +3,9 @@ import { and, asc, eq, gt, inArray, sql } from 'drizzle-orm'
 import type { Queryable } from '../../runtime/transaction.ts'
 import { users } from '../auth/schema.ts'
 import { companies } from '../companies/schema.ts'
-import { dealPeople, deals } from '../deals/schema.ts'
-import { people } from '../people/schema.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
+import { deals } from '../deals/schema.ts'
+import { people, personConsents, personLinks } from '../people/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
 import { positions } from '../positions/schema.ts'
 import { workspaceMembers } from '../workspace/schema.ts'
@@ -487,6 +488,10 @@ export function readCompanies(
 export interface ExportPersonRow {
   readonly id: string
   readonly name: string
+  readonly salutation: string | null
+  readonly firstName: string | null
+  readonly lastName: string | null
+  readonly suffix: string | null
   readonly email: string | null
   readonly timezone: string | null
   readonly location: string | null
@@ -496,17 +501,27 @@ export interface ExportPersonRow {
   readonly summary: string
   readonly tags: readonly string[]
   readonly phones: readonly string[]
+  readonly doNotContact: boolean
+  /**
+   * `<purpose_slug>:<status>` pairs joined with '; ', in purpose sort order.
+   * Purposes at their default (no explicit `person_consents` row) are omitted.
+   */
+  readonly consents: string
 }
 
-export function readPeople(
+export async function readPeople(
   db: Queryable,
   workspaceId: string,
   after: string,
 ): Promise<ExportPersonRow[]> {
-  return db
+  const rows = await db
     .select({
       id: people.id,
       name: people.name,
+      salutation: people.salutation,
+      firstName: people.firstName,
+      lastName: people.lastName,
+      suffix: people.suffix,
       email: people.email,
       timezone: people.timezone,
       location: people.location,
@@ -516,11 +531,54 @@ export function readPeople(
       summary: people.summary,
       tags: people.tags,
       phones: people.phones,
+      doNotContact: people.doNotContact,
     })
     .from(people)
     .where(and(eq(people.workspaceId, workspaceId), gt(people.id, after)))
     .orderBy(asc(people.id))
     .limit(EXPORT_PAGE)
+
+  if (rows.length === 0) return []
+  const consentsByPerson = await readConsentsForExport(
+    db,
+    workspaceId,
+    rows.map((row) => row.id),
+  )
+  return rows.map((row) => ({
+    ...row,
+    consents: consentsByPerson.get(row.id) ?? '',
+  }))
+}
+
+async function readConsentsForExport(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  const rows = await db
+    .select({
+      personId: personConsents.personId,
+      slug: consentPurposes.slug,
+      status: personConsents.status,
+      sortOrder: consentPurposes.sortOrder,
+    })
+    .from(personConsents)
+    .innerJoin(consentPurposes, eq(consentPurposes.id, personConsents.purposeId))
+    .where(
+      and(
+        eq(personConsents.workspaceId, workspaceId),
+        inArray(personConsents.personId, [...personIds]),
+      ),
+    )
+    .orderBy(asc(consentPurposes.sortOrder), asc(consentPurposes.slug))
+
+  const out = new Map<string, string[]>()
+  for (const row of rows) {
+    const list = out.get(row.personId) ?? []
+    list.push(`${row.slug}:${row.status}`)
+    out.set(row.personId, list)
+  }
+  return new Map(Array.from(out, ([personId, list]) => [personId, list.join('; ')]))
 }
 
 export interface ExportPositionRow {
@@ -604,6 +662,7 @@ export function readDeals(
 /** The addresses of the people on each of a page of deals, in one query. */
 export async function readDealPersonEmails(
   db: Queryable,
+  workspaceId: string,
   dealIds: readonly string[],
 ): Promise<ReadonlyMap<string, readonly string[]>> {
   if (dealIds.length === 0) {
@@ -611,10 +670,16 @@ export async function readDealPersonEmails(
   }
 
   const rows = await db
-    .select({ dealId: dealPeople.dealId, email: people.email })
-    .from(dealPeople)
-    .innerJoin(people, eq(people.id, dealPeople.personId))
-    .where(inArray(dealPeople.dealId, [...dealIds]))
+    .select({ dealId: personLinks.targetId, email: people.email })
+    .from(personLinks)
+    .innerJoin(people, eq(people.id, personLinks.personId))
+    .where(
+      and(
+        eq(personLinks.workspaceId, workspaceId),
+        eq(personLinks.targetType, 'deal'),
+        inArray(personLinks.targetId, [...dealIds]),
+      ),
+    )
     .orderBy(asc(people.email))
 
   const byDeal = new Map<string, string[]>()

package/src/modules/import-export/routes.ts

@@ -46,6 +46,8 @@ const createJobForm = z.object({
   on_missing_company: z.enum(ON_MISSING_COMPANY).default('skip'),
   match_key: z.string().min(1).optional(),
   column_map: z.string().optional(),
+  /** People imports only — mirrors on_missing_company's per-object gate. */
+  consent_purpose_id: z.string().min(1).optional(),
   dry_run: z.enum(['true', 'false']).default('true'),
 })
 
@@ -63,6 +65,7 @@ export function importJobResponse(job: ImportJobView): Record<string, unknown> {
     on_missing_company: job.onMissingCompany,
     match_key: job.matchKey,
     column_map: job.columnMap,
+    consent_purpose_id: job.consentPurposeId,
     source_headers: job.sourceHeaders,
     file_name: job.fileName,
     counts: job.counts,
@@ -237,6 +240,7 @@ export function mountImportExportRoutes(
       onMissingCompany: parsed.data.on_missing_company,
       matchKeyId: parsed.data.match_key ?? defaultMatchKeyId(parsed.data.object),
       columnMap: readColumnMap(parsed.data.column_map),
+      consentPurposeId: parsed.data.consent_purpose_id ?? null,
       fileName: file.name.length === 0 ? null : file.name,
       csv: await file.text(),
     })

package/src/modules/import-export/schema.ts

@@ -15,6 +15,7 @@ import type {
 import { index, integer, jsonb, pgTable, primaryKey, text } from 'drizzle-orm/pg-core'
 
 import { checkOneOf, createdAt, primaryId, updatedAt } from '../../lib/columns.ts'
+import { consentPurposes } from '../consent-purposes/schema.ts'
 import { workspaces } from '../workspace/schema.ts'
 
 /**
@@ -78,6 +79,16 @@ export const importJobs = pgTable(
     onMissingCompany: text('on_missing_company').notNull().default('skip'),
     matchKey: text('match_key').notNull(),
     columnMap: jsonb('column_map').$type<ImportColumnMap>().notNull().default({}),
+    /**
+     * The consent purpose a People import grants for each row that carries a
+     * `consent_status`. Required whenever the map names `consent_status` or
+     * `consent_at`; null on every other object and on People jobs that skip
+     * consent columns. `set null` on delete so a purpose can be removed
+     * without invalidating an old job.
+     */
+    consentPurposeId: text('consent_purpose_id').references(() => consentPurposes.id, {
+      onDelete: 'set null',
+    }),
     sourceHeaders: jsonb('source_headers').$type<readonly string[]>().notNull().default([]),
     counts: jsonb('counts').$type<ImportCounts>().notNull(),
     /** The first `IMPORT_REPORTED_ERRORS` failing rows. `counts.error` is the true number. */

package/src/modules/import-export/service.ts

@@ -99,7 +99,7 @@ function emitImportedRecordUpdated(
 }
 import { CsvFormatError, csvLine, fileDigest, parseCsv } from './csv.ts'
 import type { CsvRow, ParsedCsv } from './csv.ts'
-import { headersFor } from './exportRows.ts'
+import { templateHeadersFor } from './exportRows.ts'
 import { buildMatchKey, mapRow, splitList } from './mapping.ts'
 import { applyWrite } from './writes.ts'
 import { countPlans, planRow, planRows } from './plan.ts'
@@ -146,6 +146,7 @@ export interface ImportJobView {
   readonly onMissingCompany: OnMissingCompany
   readonly matchKey: string
   readonly columnMap: ImportColumnMap
+  readonly consentPurposeId: string | null
   readonly sourceHeaders: readonly string[]
   readonly fileName: string | null
   readonly counts: ImportCounts
@@ -164,6 +165,11 @@ export interface CreateImportJobInput {
   readonly matchKeyId: string
   /** Absent means "derive one from the source preset and the file's own headers". */
   readonly columnMap: ImportColumnMap | undefined
+  /**
+   * People imports only. Required whenever the mapping names `consent_status`
+   * or `consent_at`, refused with `422` for any other object.
+   */
+  readonly consentPurposeId: string | null
   readonly fileName: string | null
   readonly csv: string
 }
@@ -460,6 +466,7 @@ export function createImportExportService(
       matchKey: requireMatchKey(job.object as ImportObject, job.matchKey),
       conflictMode: job.conflictMode as ImportConflictMode,
       onMissingCompany: job.onMissingCompany as OnMissingCompany,
+      consentPurposeId: job.consentPurposeId,
       lookups,
     }
   }
@@ -837,6 +844,24 @@ export function createImportExportService(
 
       requireUsableColumnMap(input.object, matchKey, columnMap, parsed.headers)
 
+      // Consent is a People-only feature. A purpose on any other object is
+      // refused up front; mapping the consent columns without one is refused
+      // too — the writer would have no purpose to grant against.
+      const mapsConsentColumn =
+        columnMap.consent_status !== null || columnMap.consent_at !== null
+      if (input.consentPurposeId !== null && input.object !== 'people') {
+        throw AppError.validationFailed(
+          'consent_purpose_id is only accepted on people imports',
+          [{ field: 'consent_purpose_id', message: 'People imports only' }],
+        )
+      }
+      if (input.object === 'people' && mapsConsentColumn && input.consentPurposeId === null) {
+        throw AppError.validationFailed(
+          'Mapping consent_status or consent_at needs a consent_purpose_id on the job',
+          [{ field: 'consent_purpose_id', message: 'Required when consent columns are mapped' }],
+        )
+      }
+
       const id = dependencies.createId('importJob')
       const now = dependencies.now()
 
@@ -853,6 +878,7 @@ export function createImportExportService(
         onMissingCompany: input.onMissingCompany,
         matchKey: matchKey.id,
         columnMap,
+        consentPurposeId: input.consentPurposeId,
         sourceHeaders: parsed.headers,
         counts: { ...EMPTY_COUNTS, total: parsed.rows.length },
         errors: [],
@@ -970,7 +996,7 @@ export function createImportExportService(
     },
 
     templateCsv(object) {
-      return csvLine(headersFor(object))
+      return csvLine(templateHeadersFor(object))
     },
   }
 }

package/src/modules/import-export/streams.ts

@@ -52,10 +52,12 @@ async function* pageThrough<TRow extends { readonly id: string }>(
 /** The rows of one page, all their people in one query rather than one per deal. */
 async function dealPage(
   db: Database,
+  workspaceId: string,
   rows: readonly repository.ExportDealRow[],
 ): Promise<readonly (readonly string[])[]> {
   const emails = await repository.readDealPersonEmails(
     db,
+    workspaceId,
     rows.map((row) => row.id),
   )
 
@@ -91,7 +93,7 @@ export async function* streamExport(
     case 'deals':
       yield* pageThrough({
         read: (after) => repository.readDeals(db, workspaceId, after),
-        cells: (rows) => dealPage(db, rows),
+        cells: (rows) => dealPage(db, workspaceId, rows),
       })
       return
   }

package/src/modules/import-export/tools.ts

@@ -69,6 +69,15 @@ const previewArgs = z.strictObject({
     ),
   match_key: z.string().min(1).optional().describe('Which field decides that match.'),
   column_map: columnMapArg.optional(),
+  consent_purpose_id: z
+    .string()
+    .min(1)
+    .nullable()
+    .default(null)
+    .describe(
+      'People imports only: the consent purpose a row grants for each `consent_status`. ' +
+        'Required whenever consent_status or consent_at is mapped.',
+    ),
   file_name: z.string().min(1).nullable().default(null).describe('Recorded on the job, for the log.'),
 })
 
@@ -135,6 +144,7 @@ export function registerImportExportTools(mcp: McpToolRegistry, service: ImportE
           onMissingCompany: args.on_missing_company,
           matchKeyId: args.match_key ?? defaultMatchKeyId(args.object),
           columnMap: args.column_map,
+          consentPurposeId: args.consent_purpose_id,
           fileName: args.file_name,
           csv: args.csv,
         }),

package/src/modules/import-export/validation.ts

@@ -1,6 +1,7 @@
 import {
   ACCOUNT_TYPES,
   COMPANY_STAGES,
+  CONSENT_STATUSES,
   ICP_FITS,
   INFLUENCE_LEVELS,
   PREFERRED_CHANNELS,
@@ -90,7 +91,28 @@ function checkCompany(errors: StoredRowError[], mapped: Readonly<Record<string,
   checkEnum(errors, 'icp_fit', ICP_FITS, mapped.icp_fit)
 }
 
+/**
+ * A People row names its person one way or the other.
+ *
+ * `name` is not a `required` column, because the requirement is really about a
+ * pair of them: the row carries a full `name`, or the `first_name` /
+ * `last_name` cells for one to be composed from. Most CRMs export the parts and
+ * no full name, and refusing every row of such a file over a column it was
+ * never going to have is the migration nobody finishes.
+ */
+function checkPersonName(errors: StoredRowError[], mapped: Readonly<Record<string, string>>): void {
+  const named = ['name', 'first_name', 'last_name'].some(
+    (column) => (mapped[column] ?? '').trim().length > 0,
+  )
+
+  if (!named) {
+    errors.push({ field: 'name', message: 'Missing a name, first_name or last_name' })
+  }
+}
+
 function checkPerson(errors: StoredRowError[], mapped: Readonly<Record<string, string>>): void {
+  checkPersonName(errors, mapped)
+
   const email = (mapped.email ?? '').trim()
 
   if (email.length > 0 && !EMAIL_SHAPE.test(email)) {
@@ -100,6 +122,12 @@ function checkPerson(errors: StoredRowError[], mapped: Readonly<Record<string, s
   checkEnum(errors, 'preferred_channel', PREFERRED_CHANNELS, mapped.preferred_channel)
   checkEnum(errors, 'influence', INFLUENCE_LEVELS, mapped.influence)
   checkEnum(errors, 'relationship', RELATIONSHIP_LEVELS, mapped.relationship)
+  checkEnum(errors, 'consent_status', CONSENT_STATUSES, mapped.consent_status)
+
+  const consentAt = (mapped.consent_at ?? '').trim()
+  if (consentAt.length > 0 && !isoDateSchema.safeParse(consentAt).success) {
+    errors.push({ field: 'consent_at', message: `"${consentAt}" is not a date. Use YYYY-MM-DD` })
+  }
 }
 
 function checkPosition(errors: StoredRowError[], mapped: Readonly<Record<string, string>>): void {